soup3-0.9.0/.cargo_vcs_info.json0000644000000001361046102023000121350ustar { "git": { "sha1": "43121bc229b241b6338b62d56be1bdd164d60eea" }, "path_in_vcs": "" }soup3-0.9.0/.gitignore000064400000000000000000000000221046102023000126650ustar 00000000000000target Cargo.lock soup3-0.9.0/.gitlab-ci.yml000064400000000000000000000035171046102023000133450ustar 00000000000000variables: # format is = # the name is used in the URL # latest release must be at the top # (only relevant on main branch) RELEASES: | v0.8=0.8 # we need the gir submodules GIT_SUBMODULE_STRATEGY: recursive # overwrite 'update = none' in .gitmodules GIT_SUBMODULE_UPDATE_FLAGS: --checkout image: "ghcr.io/gtk-rs/gtk4-rs/gtk4:latest" before_script: - sudo dnf install --quiet -y libnghttp2-devel libpsl-devel sqlite-devel glib-networking # install rust nightly toolchain - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --default-toolchain none -y - source $HOME/.cargo/env - rustup toolchain install nightly --profile minimal --allow-downgrade -c rustfmt # compile libsoup3 - meson setup _build --prefix=/usr -Dlibsoup:brotli=enabled -Dlibsoup:docs=disabled -Dlibsoup:installed_tests=false -Dlibsoup:vapi=disabled - meson compile -C _build - meson install -C _build - curl --proto '=https' --tlsv1.2 -sSf -o gir-rustdoc.py https://gitlab.gnome.org/World/Rust/gir-rustdoc/-/raw/main/gir-rustdoc.py - chmod +x gir-rustdoc.py build: script: - cargo build --all-features --examples - cargo test docs: stage: test variables: GIT_SUBMODULE_STRATEGY: recursive RUSTDOCFLAGS: "--cfg docsrs" script: # generate the docs - cargo install rustdoc-stripper - ./generator.py --embed-docs - rustup default nightly - eval $(./gir-rustdoc.py pre-docs) - cargo doc --all-features --no-deps - mv target/doc/ docs artifacts: paths: - docs pages: stage: deploy script: - ./gir-rustdoc.py html-index # main docs - mkdir public/git - mv docs public/git/docs # stable docs - ./gir-rustdoc.py docs-from-artifacts artifacts: paths: - public rules: - if: $CI_DEFAULT_BRANCH == $CI_COMMIT_BRANCH soup3-0.9.0/.gitmodules000064400000000000000000000002661046102023000130640ustar 00000000000000[submodule "gir-files"] path = gir-files url = https://github.com/gtk-rs/gir-files update = none [submodule "gir"] path = gir url = https://github.com/gtk-rs/gir update = none soup3-0.9.0/Cargo.lock0000644000000240311046102023000101100ustar # This file is automatically @generated by Cargo. # It is not intended for manual editing. version = 4 [[package]] name = "bitflags" version = "2.11.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af" [[package]] name = "cfg-expr" version = "0.20.7" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3c6b04e07d8080154ed4ac03546d9a2b303cc2fe1901ba0b35b301516e289368" dependencies = [ "smallvec", "target-lexicon", ] [[package]] name = "equivalent" version = "1.0.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f" [[package]] name = "futures-channel" version = "0.3.32" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d" dependencies = [ "futures-core", ] [[package]] name = "futures-core" version = "0.3.32" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d" [[package]] name = "futures-executor" version = "0.3.32" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "baf29c38818342a3b26b5b923639e7b1f4a61fc5e76102d4b1981c6dc7a7579d" dependencies = [ "futures-core", "futures-task", "futures-util", ] [[package]] name = "futures-io" version = "0.3.32" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cecba35d7ad927e23624b22ad55235f2239cfa44fd10428eecbeba6d6a717718" [[package]] name = "futures-macro" version = "0.3.32" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e835b70203e41293343137df5c0664546da5745f82ec9b84d40be8336958447b" dependencies = [ "proc-macro2", "quote", "syn", ] [[package]] name = "futures-task" version = "0.3.32" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393" [[package]] name = "futures-util" version = "0.3.32" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6" dependencies = [ "futures-core", "futures-macro", "futures-task", "pin-project-lite", "slab", ] [[package]] name = "gio" version = "0.22.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "816b6743c46b217aa8fba679095ac6f2162fd53259dc8f186fcdbff9c555db03" dependencies = [ "futures-channel", "futures-core", "futures-io", "futures-util", "gio-sys", "glib", "libc", "pin-project-lite", "smallvec", ] [[package]] name = "gio-sys" version = "0.22.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "64729ba2772c080448f9f966dba8f4456beeb100d8c28a865ef8a0f2ef4987e1" dependencies = [ "glib-sys", "gobject-sys", "libc", "system-deps", "windows-sys", ] [[package]] name = "glib" version = "0.22.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "16877c6e619447e0bcb6de326a42a8bd02b36328cfeeda210135425e576efa3d" dependencies = [ "bitflags", "futures-channel", "futures-core", "futures-executor", "futures-task", "futures-util", "gio-sys", "glib-macros", "glib-sys", "gobject-sys", "libc", "memchr", "smallvec", ] [[package]] name = "glib-macros" version = "0.22.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "bda575994e3689b1bc12f89c3df621ead46ff292623b76b4710a3a5b79be54bb" dependencies = [ "heck", "proc-macro2", "quote", "syn", ] [[package]] name = "glib-sys" version = "0.22.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "48073e3b228419faa80b9b7f7122759d4ab2f44cd52a065fde7ca08f34c03147" dependencies = [ "libc", "system-deps", ] [[package]] name = "gobject-sys" version = "0.22.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "18eda93f09d3778f38255b231b17ef67195013a592c91624a4daf8bead875565" dependencies = [ "glib-sys", "libc", "system-deps", ] [[package]] name = "hashbrown" version = "0.16.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100" [[package]] name = "heck" version = "0.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" [[package]] name = "indexmap" version = "2.13.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7714e70437a7dc3ac8eb7e6f8df75fd8eb422675fc7678aff7364301092b1017" dependencies = [ "equivalent", "hashbrown", ] [[package]] name = "libc" version = "0.2.183" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b5b646652bf6661599e1da8901b3b9522896f01e736bad5f723fe7a3a27f899d" [[package]] name = "memchr" version = "2.8.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79" [[package]] name = "pin-project-lite" version = "0.2.17" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" [[package]] name = "pkg-config" version = "0.3.32" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7edddbd0b52d732b21ad9a5fab5c704c14cd949e5e9a1ec5929a24fded1b904c" [[package]] name = "proc-macro2" version = "1.0.106" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934" dependencies = [ "unicode-ident", ] [[package]] name = "quote" version = "1.0.45" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924" dependencies = [ "proc-macro2", ] [[package]] name = "serde_core" version = "1.0.228" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad" dependencies = [ "serde_derive", ] [[package]] name = "serde_derive" version = "1.0.228" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79" dependencies = [ "proc-macro2", "quote", "syn", ] [[package]] name = "serde_spanned" version = "1.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f8bbf91e5a4d6315eee45e704372590b30e260ee83af6639d64557f51b067776" dependencies = [ "serde_core", ] [[package]] name = "slab" version = "0.4.12" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" [[package]] name = "smallvec" version = "1.15.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03" [[package]] name = "soup3" version = "0.9.0" dependencies = [ "futures-channel", "gio", "glib", "libc", "soup3-sys", ] [[package]] name = "soup3-sys" version = "0.9.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "79d5d25225bb06f83b78ff8cc35973b56d45fcdd21af6ed6d2bbd67f5a6f9bea" dependencies = [ "gio-sys", "glib-sys", "gobject-sys", "libc", "system-deps", ] [[package]] name = "syn" version = "2.0.117" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99" dependencies = [ "proc-macro2", "quote", "unicode-ident", ] [[package]] name = "system-deps" version = "7.0.7" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "48c8f33736f986f16d69b6cb8b03f55ddcad5c41acc4ccc39dd88e84aa805e7f" dependencies = [ "cfg-expr", "heck", "pkg-config", "toml", "version-compare", ] [[package]] name = "target-lexicon" version = "0.13.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "df7f62577c25e07834649fc3b39fafdc597c0a3527dc1c60129201ccfcbaa50c" [[package]] name = "toml" version = "0.9.12+spec-1.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cf92845e79fc2e2def6a5d828f0801e29a2f8acc037becc5ab08595c7d5e9863" dependencies = [ "indexmap", "serde_core", "serde_spanned", "toml_datetime", "toml_parser", "toml_writer", "winnow", ] [[package]] name = "toml_datetime" version = "0.7.5+spec-1.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "92e1cfed4a3038bc5a127e35a2d360f145e1f4b971b551a2ba5fd7aedf7e1347" dependencies = [ "serde_core", ] [[package]] name = "toml_parser" version = "1.0.9+spec-1.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "702d4415e08923e7e1ef96cd5727c0dfed80b4d2fa25db9647fe5eb6f7c5a4c4" dependencies = [ "winnow", ] [[package]] name = "toml_writer" version = "1.0.6+spec-1.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ab16f14aed21ee8bfd8ec22513f7287cd4a91aa92e44edfe2c17ddd004e92607" [[package]] name = "unicode-ident" version = "1.0.24" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75" [[package]] name = "version-compare" version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "03c2856837ef78f57382f06b2b8563a2f512f7185d732608fd9176cb3b8edf0e" [[package]] name = "windows-link" version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" [[package]] name = "windows-sys" version = "0.61.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" dependencies = [ "windows-link", ] [[package]] name = "winnow" version = "0.7.15" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945" soup3-0.9.0/Cargo.toml0000644000000031001046102023000101250ustar # THIS FILE IS AUTOMATICALLY GENERATED BY CARGO # # When uploading crates to the registry Cargo will automatically # "normalize" Cargo.toml files for maximal compatibility # with all versions of Cargo and also rewrite `path` dependencies # to registry (e.g., crates.io) dependencies. # # If you are reading this file be aware that the original Cargo.toml # will likely look very different (and much more reasonable). # See Cargo.toml.orig for the original contents. [package] edition = "2024" rust-version = "1.92" name = "soup3" version = "0.9.0" authors = ["The Gtk-rs Project Developers"] build = false autolib = false autobins = false autoexamples = false autotests = false autobenches = false description = "Soup crate for Rust" homepage = "https://world.pages.gitlab.gnome.org/Rust/soup3-rs/" documentation = "https://world.pages.gitlab.gnome.org/Rust/soup3-rs/git/docs/" readme = "README.md" keywords = [ "soup", "gtk-rs", "gnome", ] license = "MIT" repository = "https://gitlab.gnome.org/World/Rust/soup3-rs" [package.metadata.docs.rs] rustdoc-args = ["--generate-link-to-definition"] all-features = true [features] default = ["ffi/v3_0"] v3_2 = ["ffi/v3_2"] v3_4 = [ "v3_2", "ffi/v3_4", ] v3_6 = [ "v3_4", "ffi/v3_6", ] v3_8 = [ "v3_6", "ffi/v3_8", ] [lib] name = "soup" path = "src/lib.rs" [dependencies.ffi] version = "0.9" package = "soup3-sys" [dependencies.futures-channel] version = "0.3" [dependencies.gio] version = "0.22" features = ["v2_70"] [dependencies.glib] version = "0.22" features = ["v2_66"] [dependencies.libc] version = "0.2" soup3-0.9.0/Cargo.toml.orig000064400000000000000000000024661046102023000136020ustar 00000000000000[workspace] members = [ "sys", ] exclude = ["gir"] [workspace.package] authors = ["The Gtk-rs Project Developers"] edition = "2024" homepage = "https://world.pages.gitlab.gnome.org/Rust/soup3-rs/" keywords = ["soup", "gtk-rs", "gnome"] license = "MIT" repository = "https://gitlab.gnome.org/World/Rust/soup3-rs" rust-version = "1.92" version = "0.9.0" [package] name = "soup3" version.workspace = true edition.workspace = true rust-version.workspace = true description = "Soup crate for Rust" repository.workspace = true license.workspace = true keywords.workspace = true authors.workspace = true homepage.workspace = true documentation = "https://world.pages.gitlab.gnome.org/Rust/soup3-rs/git/docs/" [package.metadata.docs.rs] rustdoc-args = ["--generate-link-to-definition"] all-features = true [lib] name = "soup" [dependencies] libc = "0.2" futures-channel = "0.3" [dependencies.ffi] package = "soup3-sys" path = "sys" version = "0.9" [dependencies.glib] git = "https://github.com/gtk-rs/gtk-rs-core" branch = "0.22" version = "0.22" features = [ "v2_66" ] [dependencies.gio] git = "https://github.com/gtk-rs/gtk-rs-core" branch = "0.22" version = "0.22" features = [ "v2_70" ] [features] default = ["ffi/v3_0"] v3_2 = ["ffi/v3_2"] v3_4 = ["v3_2", "ffi/v3_4"] v3_6 = ["v3_4", "ffi/v3_6"] v3_8 = ["v3_6", "ffi/v3_8"] soup3-0.9.0/Gir.toml000064400000000000000000000151031046102023000123210ustar 00000000000000[external_libraries] Gio = {min_version = "2.66"} [options] girs_directories = [".", "./gir-files"] library = "Soup" version = "3.0" min_cfg_version = "3.0" target_path = "." work_mode = "normal" generate_safety_asserts = true deprecate_by_min_version = true single_version_file = true use_gi_docgen = true generate_builder = true external_libraries = [ "GLib", "GObject", ] generate = [ # "Soup.*", "Soup.Auth", "Soup.AuthBasic", "Soup.AuthDigest", "Soup.AuthDomainBasicAuthCallback", "Soup.AuthDomainFilter", "Soup.AuthDomainGenericAuthCallback", "Soup.AuthManager", "Soup.AuthNegotiate", "Soup.AuthNTLM", "Soup.Cache", "Soup.Cacheability", "Soup.CacheType", "Soup.ContentDecoder", "Soup.ContentSniffer", "Soup.CookieJarAcceptPolicy", "Soup.CookieJarDB", "Soup.CookieJarText", "Soup.DateFormat", "Soup.Encoding", "Soup.Expectation", "Soup.HSTSEnforcer", "Soup.HSTSEnforcerDB", # "Soup.HSTSPolicy", "Soup.HTTPVersion", # "Soup.Logger", "Soup.LoggerFilter", "Soup.LoggerLogLevel", "Soup.LoggerPrinter", "Soup.MemoryUse", # "Soup.Message", # "Soup.MessageBody", "Soup.MessageFlags", # "Soup.MessageHeadersIter", "Soup.MessageHeadersType", "Soup.MessageMetrics", "Soup.MessagePriority", "Soup.Multipart", # "Soup.MultipartInputStream", # "Soup.Range", "Soup.SameSitePolicy", "Soup.ServerMessage", "Soup.ServerListenOptions", "Soup.SessionError", "Soup.SessionFeature", "Soup.Status", "Soup.TLDError", "Soup.URIComponent", "Soup.WebsocketCloseCode", # "Soup.WebsocketConnection", "Soup.WebsocketConnectionType", "Soup.WebsocketDataType", "Soup.WebsocketError", "Soup.WebsocketExtension", # "Soup.WebsocketExtensionDeflate", "Soup.WebsocketExtensionManager", "Soup.WebsocketState", ] manual = [ "Gio.AsyncResult", "Gio.Cancellable", "Gio.File", "Gio.FilterInputStream", "Gio.InputStream", "Gio.IOStream", "Gio.InetSocketAddress", "Gio.OutputStream", "Gio.OutputStreamSpliceFlags", "Gio.PollableInputStream", "Gio.ProxyResolver", "Gio.Socket", "Gio.SocketAddress", "Gio.SocketClientEvent", "Gio.SocketConnectable", "Gio.TlsCertificate", "Gio.TlsCertificateFlags", "Gio.TlsClientConnection", "Gio.TlsDatabase", "Gio.TlsInteraction", "Gio.TlsAuthenticationMode", "Gio.TlsPassword", "Gio.TlsProtocolVersion", "GLib.Bytes", "GLib.DateTime", "GLib.DestroyNotify", "GLib.Error", "GLib.HashTable", "GLib.IOChannel", "GLib.IOCondition", "GLib.IOFunc", "GLib.List", "GLib.MainContext", "GLib.Priority", "GLib.PtrArray", "GLib.Quark", "GLib.SList", "GLib.Source", "GLib.SourceFunc", "GLib.Uri", # "GLib.Value", # "GLib.ValueArray", "GLib.Variant", "GObject.Object" # "GLib.Data", # "GLib.TimeVal", ] [[object]] name="Soup.Cookie" status = "generate" [[object.function]] name = "equal" [[object.function.parameter]] name = "cookie1" const = true [[object.function.parameter]] name = "cookie2" const = true [[object]] name="Soup.CookieJar" status = "generate" manual_traits = ["CookieJarExtManual"] [[object.function]] name = "add_cookie" manual = true [[object.function]] name = "add_cookie_full" manual = true [[object.function]] name = "add_cookie_with_first_party" manual = true [[object.function]] name = "delete_cookie" manual = true [[object]] name="Soup.AuthDomain" status="generate" [[object.property]] name="filter" ignore=true [[object.property]] name="generic-auth-callback" ignore=true [[object]] name="Soup.AuthDomainBasic" status="generate" [[object.property]] name="auth-callback" ignore=true [[object]] name="Soup.AuthDomainDigest" status="generate" [[object.property]] name="auth-callback" ignore=true [[object]] name="Soup.Server" manual_traits = ["ServerExtManual"] status="generate" [[object.function]] name="add_early_handler" manual = true [[object.function]] name="add_handler" manual = true [[object.function]] name="add_websocket_handler" manual = true [[object]] name = "Soup.Session" status = "generate" manual_traits = ["SessionExtManual"] [[object.function]] name = "websocket_connect_async" ignore = true [[object]] name="Soup.Logger" status = "generate" [[object.function]] name = "set_printer" manual = true [[object]] name="Soup.MessageBody" status = "generate" [[object.function]] name = "append" ignore = true # [[object]] # name="Soup.CookieJar" # status = "generate" # [[object.function]] # name = "add_cookie" # ignore= true # [[object.function]] # name = "add_cookie_with_first_party" # ignore= true # [[object.function]] # name = "add_cookie_full" # ignore= true # [[object.function]] # name = "get_cookie_list_with_same_site_info" # ignore= true [[object]] name="Soup.WebsocketConnection" manual_traits = ["WebsocketConnectionExtManual"] status="generate" [[object.function]] name = "new" manual = true [[object.function]] name = "send_binary" ignore = true [[object.function]] name = "send_message" ignore = true [[object]] name="Soup.WebsocketExtensionDeflate" version="2.68" status="generate" [[object]] name="Soup.MultipartInputStream" status="generate" [[object.function]] name="next_part_async" ignore=true [[object]] name="Soup.Message" status="generate" [[object.function]] name="new" [object.function.return] nullable_return_is_error = "Invalid URL" [[object.function]] name="new_from_encoded_form" [object.function.return] nullable_return_is_error = "Invalid URL" [[object.function]] name="new_from_multipart" [object.function.return] nullable_return_is_error = "Invalid URL" [[object.function]] name = "get_site_for_cookies" ignore = true [[object.function]] name = "set_site_for_cookies" ignore = true [[object.function]] name="set_chunk_allocator" ignore=true [[object]] name="Soup.MessageHeaders" status="generate" [[object.derive]] name = "PartialEq, Eq, PartialOrd, Ord, Hash" [[object.function]] name = "get_content_disposition" manual = true [[object.function]] name = "set_content_disposition" manual = true [[object.function]] name = "get_content_type" manual = true [[object.function]] name = "set_content_type" manual = true [[object]] name="Soup.HSTSPolicy" status="generate" [[object.function]] name="equal" ignore=true [[object]] name="Soup.*" status="generate" [[object.function]] name = "(header_g_string_append_param|soup_header_g_string_append_param_quoted)" manual = true [[object.function]] name = "cookies_free" ignore = true [[object.function]] name = "cookies_to_cookie_header" ignore = true [[object.function]] name = "cookies_to_request" ignore = true [[object.function]] name = "cookies_to_response" ignore = true soup3-0.9.0/LICENSE000064400000000000000000000021201046102023000117030ustar 00000000000000The MIT License (MIT) Copyright (c) 2013-2017, The Gtk-rs Project Developers. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. soup3-0.9.0/README.md000064400000000000000000000016741046102023000121720ustar 00000000000000# Soup3-rs [Project site](https://gitlab.gnome.org/World/Rust/soup3-rs) | [Online documentation](https://world.pages.gitlab.gnome.org/Rust/soup3-rs/git/docs/soup/) __Rust__ bindings and wrappers for __libsoup__ v3. ## Using We recommend using [crates from crates.io](https://crates.io/crates/soup3). If you want to track the bleeding edge, use the git dependency instead: ```toml [dependencies] soup3 = { git = "https://gitlab.gnome.org/World/Rust/soup3-rs" } ``` Avoid mixing versioned and git crates like this: ```toml # This will not compile [dependencies] gtk3 = "0.15" soup3 = { git = "https://gitlab.gnome.org/World/Rust/soup3-rs" } ``` ## Minimum supported Rust version Currently, the minimum supported Rust version is `1.56.0`. ## Documentation https://world.pages.gitlab.gnome.org/Rust/soup3-rs/git/docs/soup ## Contribute Contributor you're welcome! ## License __soup3-rs__ is available under the MIT License, please refer to it. soup3-0.9.0/Soup-3.0.gir000064400000000000000000033571261046102023000126530ustar 00000000000000 The abstract base class for handling authentication. Specific HTTP Authentication mechanisms are implemented by its subclasses, but applications never need to be aware of the specific subclasses being used. [class@Auth] objects store the authentication data associated with a given bit of web space. They are created automatically by [class@Session]. Creates a new [class@Auth] of type @type with the information from @msg and @auth_header. This is called by [class@Session]; you will normally not create auths yourself. the new [class@Auth], or %NULL if it could not be created the type of auth to create (a subtype of [class@Auth]) the #SoupMessage the auth is being created for the WWW-Authenticate/Proxy-Authenticate header Call this on an auth to authenticate it. Normally this will cause the auth's message to be requeued with the new authentication info. a #SoupAuth the username provided by the user or client the password provided by the user or client Tests if @auth is able to authenticate by providing credentials to the [method@Auth.authenticate]. %TRUE if @auth is able to accept credentials. a #SoupAuth Generates an appropriate "Authorization" header for @msg. (The session will only call this if [method@Auth.is_authenticated] returned %TRUE.) the "Authorization" header, which must be freed. a #SoupAuth the #SoupMessage to be authorized Returns a list of paths on the server which @auth extends over. (All subdirectories of these paths are also assumed to be part of @auth's protection space, unless otherwise discovered not to be.) the list of paths, which can be freed with [method@Auth.free_protection_space]. a #SoupAuth the URI of the request that @auth was generated in response to. Tests if @auth has been given a username and password. %TRUE if @auth has been given a username and password a #SoupAuth Tests if @auth is ready to make a request for @msg with. For most auths, this is equivalent to [method@Auth.is_authenticated], but for some auth types (eg, NTLM), the auth may be sendable (eg, as an authentication request) even before it is authenticated. %TRUE if @auth is ready to make a request with. a #SoupAuth a #SoupMessage Updates @auth with the information from @msg and @auth_header, possibly un-authenticating it. As with [ctor@Auth.new], this is normally only used by [class@Session]. %TRUE if @auth is still a valid (but potentially unauthenticated) [class@Auth]. %FALSE if something about @auth_params could not be parsed or incorporated into @auth at all. a #SoupAuth the #SoupMessage @auth is being updated for the WWW-Authenticate/Proxy-Authenticate header Call this on an auth to authenticate it. Normally this will cause the auth's message to be requeued with the new authentication info. a #SoupAuth the username provided by the user or client the password provided by the user or client Tests if @auth is able to authenticate by providing credentials to the [method@Auth.authenticate]. %TRUE if @auth is able to accept credentials. a #SoupAuth Call this on an auth to cancel it. You need to cancel an auth to complete an asynchronous authenticate operation when no credentials are provided ([method@Auth.authenticate] is not called). The [class@Auth] will be cancelled on dispose if it hasn't been authenticated. a #SoupAuth Frees @space. a #SoupAuth the return value from [method@Auth.get_protection_space] Returns the authority (host:port) that @auth is associated with. the authority a #SoupAuth Generates an appropriate "Authorization" header for @msg. (The session will only call this if [method@Auth.is_authenticated] returned %TRUE.) the "Authorization" header, which must be freed. a #SoupAuth the #SoupMessage to be authorized Gets an opaque identifier for @auth. The identifier can be used as a hash key or the like. [class@Auth] objects from the same server with the same identifier refer to the same authentication domain (eg, the URLs associated with them take the same usernames and passwords). the identifier a #SoupAuth Returns a list of paths on the server which @auth extends over. (All subdirectories of these paths are also assumed to be part of @auth's protection space, unless otherwise discovered not to be.) the list of paths, which can be freed with [method@Auth.free_protection_space]. a #SoupAuth the URI of the request that @auth was generated in response to. Returns @auth's realm. This is an identifier that distinguishes separate authentication spaces on a given server, and may be some string that is meaningful to the user. (Although it is probably not localized.) the realm name a #SoupAuth soup_auth_get_scheme_name: (attributes org.gtk.Method.get_property=scheme-name) Returns @auth's scheme name. (Eg, "Basic", "Digest", or "NTLM") the scheme name a #SoupAuth Tests if @auth has been given a username and password. %TRUE if @auth has been given a username and password a #SoupAuth Tests if @auth has been cancelled %TRUE if @auth has been cancelled a #SoupAuth Tests whether or not @auth is associated with a proxy server rather than an "origin" server. %TRUE or %FALSE a #SoupAuth Tests if @auth is ready to make a request for @msg with. For most auths, this is equivalent to [method@Auth.is_authenticated], but for some auth types (eg, NTLM), the auth may be sendable (eg, as an authentication request) even before it is authenticated. %TRUE if @auth is ready to make a request with. a #SoupAuth a #SoupMessage Updates @auth with the information from @msg and @auth_header, possibly un-authenticating it. As with [ctor@Auth.new], this is normally only used by [class@Session]. %TRUE if @auth is still a valid (but potentially unauthenticated) [class@Auth]. %FALSE if something about @auth_params could not be parsed or incorporated into @auth at all. a #SoupAuth the #SoupMessage @auth is being updated for the WWW-Authenticate/Proxy-Authenticate header The authority (host:port) being authenticated to. Whether or not the auth has been authenticated. Whether or not the auth has been cancelled. Whether or not the auth is for a proxy server. The authentication realm. The authentication scheme name. HTTP "Basic" authentication. [class@Session]s support this by default; if you want to disable support for it, call [method@Session.remove_feature_by_type], passing %SOUP_TYPE_AUTH_BASIC. %TRUE if @auth is still a valid (but potentially unauthenticated) [class@Auth]. %FALSE if something about @auth_params could not be parsed or incorporated into @auth at all. a #SoupAuth the #SoupMessage @auth is being updated for the WWW-Authenticate/Proxy-Authenticate header the list of paths, which can be freed with [method@Auth.free_protection_space]. a #SoupAuth the URI of the request that @auth was generated in response to. a #SoupAuth the username provided by the user or client the password provided by the user or client %TRUE if @auth has been given a username and password a #SoupAuth the "Authorization" header, which must be freed. a #SoupAuth the #SoupMessage to be authorized %TRUE if @auth is ready to make a request with. a #SoupAuth a #SoupMessage %TRUE if @auth is able to accept credentials. a #SoupAuth HTTP "Digest" authentication. [class@Session]s support this by default; if you want to disable support for it, call [method@Session.remove_feature_by_type] passing %SOUP_TYPE_AUTH_DIGEST. Server-side authentication. A [class@AuthDomain] manages authentication for all or part of a [class@Server]. To make a server require authentication, first create an appropriate subclass of [class@AuthDomain], and then add it to the server with [method@Server.add_auth_domain]. In order for an auth domain to have any effect, you must add one or more paths to it (via [method@AuthDomain.add_path]). To require authentication for all ordinary requests, add the path `"/"`. (Note that this does not include the special `"*"` URI (eg, "OPTIONS *"), which must be added as a separate path if you want to cover it.) If you need greater control over which requests should and shouldn't be authenticated, add paths covering everything you *might* want authenticated, and then use a filter ([method@AuthDomain.set_filter] to bypass authentication for those requests that don't need it. Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to @msg. It requests that the client authenticate, and sets @msg's status accordingly. This is used by [class@Server] internally and is probably of no use to anyone else. a #SoupAuthDomain a #SoupServerMessage Checks if @msg authenticates to @domain via @username and @password. This would normally be called from a [callback@AuthDomainGenericAuthCallback]. whether or not the message is authenticated a #SoupAuthDomain a #SoupServerMessage a username a password Checks if @msg contains appropriate authorization for @domain to accept it. Mirroring [method@AuthDomain.covers], this does not check whether or not @domain *cares* if @msg is authorized. This is used by [class@Server] internally and is probably of no use to anyone else. the username that @msg has authenticated as, if in fact it has authenticated. %NULL otherwise. a #SoupAuthDomain a #SoupServerMessage Adds @path to @domain. Requests under @path on @domain's server will require authentication (unless overridden by [method@AuthDomain.remove_path] or [method@AuthDomain.set_filter]). a #SoupAuthDomain the path to add to @domain Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to @msg. It requests that the client authenticate, and sets @msg's status accordingly. This is used by [class@Server] internally and is probably of no use to anyone else. a #SoupAuthDomain a #SoupServerMessage Checks if @msg authenticates to @domain via @username and @password. This would normally be called from a [callback@AuthDomainGenericAuthCallback]. whether or not the message is authenticated a #SoupAuthDomain a #SoupServerMessage a username a password Checks if @domain requires @msg to be authenticated (according to its paths and filter function). This does not actually look at whether @msg *is* authenticated, merely whether or not it needs to be. This is used by [class@Server] internally and is probably of no use to anyone else. %TRUE if @domain requires @msg to be authenticated a #SoupAuthDomain a #SoupServerMessage Gets the realm name associated with @domain. @domain's realm a #SoupAuthDomain Removes @path from @domain. Requests under @path on @domain's server will NOT require authentication. This is not simply an undo-er for [method@AuthDomain.add_path]; it can be used to "carve out" a subtree that does not require authentication inside a hierarchy that does. Note also that unlike with [method@AuthDomain.add_path], this cannot be overridden by adding a filter, as filters can only bypass authentication that would otherwise be required, not require it where it would otherwise be unnecessary. a #SoupAuthDomain the path to remove from @domain Adds @filter as an authentication filter to @domain. The filter gets a chance to bypass authentication for certain requests that would otherwise require it. Eg, it might check the message's path in some way that is too complicated to do via the other methods, or it might check the message's method, and allow GETs but not PUTs. The filter function returns %TRUE if the request should still require authentication, or %FALSE if authentication is unnecessary for this request. To help prevent security holes, your filter should return %TRUE by default, and only return %FALSE under specifically-tested circumstances, rather than the other way around. Eg, in the example above, where you want to authenticate PUTs but not GETs, you should check if the method is GET and return %FALSE in that case, and then return %TRUE for all other methods (rather than returning %TRUE for PUT and %FALSE for all other methods). This way if it turned out (now or later) that some paths supported additional methods besides GET and PUT, those methods would default to being NOT allowed for unauthenticated users. You can also set the filter by setting the SoupAuthDomain:filter and [property@AuthDomain:filter-data properties], which can also be used to set the filter at construct time. a #SoupAuthDomain the auth filter for @domain data to pass to @filter destroy notifier to free @filter_data when @domain is destroyed Sets @auth_callback as an authentication-handling callback for @domain. Whenever a request comes in to @domain which cannot be authenticated via a domain-specific auth callback (eg, [callback@AuthDomainDigestAuthCallback]), the generic auth callback will be invoked. See [callback@AuthDomainGenericAuthCallback] for information on what the callback should do. a #SoupAuthDomain the auth callback data to pass to @auth_callback destroy notifier to free @auth_data when @domain is destroyed The [callback@AuthDomainFilter] for the domain. Data to pass to the [callback@AuthDomainFilter]. The [callback@AuthDomainGenericAuthCallback]. The data to pass to the [callback@AuthDomainGenericAuthCallback]. Whether or not this is a proxy auth domain. The realm of this auth domain. Server-side "Basic" authentication. [class@AuthDomainBasic] handles the server side of HTTP "Basic" (ie, cleartext password) authentication. Creates a [class@AuthDomainBasic]. You must set the [property@AuthDomain:realm] property, to indicate the realm name to be returned with the authentication challenge to the client. Other parameters are optional. the new #SoupAuthDomain name of first option, or %NULL option name/value pairs Sets the callback that @domain will use to authenticate incoming requests. For each request containing authorization, @domain will invoke the callback, and then either accept or reject the request based on @callback's return value. You can also set the auth callback by setting the [property@AuthDomainBasic:auth-callback] and [property@AuthDomainBasic:auth-data] properties, which can also be used to set the callback at construct time. the domain the callback data to pass to @auth_callback destroy notifier to free @user_data when @domain is destroyed The [callback@AuthDomainBasicAuthCallback]. The data to pass to the [callback@AuthDomainBasicAuthCallback]. Callback used by [class@AuthDomainBasic] for authentication purposes. The application should verify that @username and @password and valid and return %TRUE or %FALSE. If you are maintaining your own password database (rather than using the password to authenticate against some other system like PAM or a remote server), you should make sure you know what you are doing. In particular, don't store cleartext passwords, or easily-computed hashes of cleartext passwords, even if you don't care that much about the security of your server, because users will frequently use the same password for multiple sites, and so compromising any site with a cleartext (or easily-cracked) password database may give attackers access to other more-interesting sites as well. %TRUE if @username and @password are valid the domain the message being authenticated the username provided by the client the password provided by the client the data passed to [method@AuthDomainBasic.set_auth_callback] a #SoupAuthDomain a #SoupServerMessage whether or not the message is authenticated a #SoupAuthDomain a #SoupServerMessage a username a password Server-side "Digest" authentication. [class@AuthDomainDigest] handles the server side of HTTP "Digest" authentication. Creates a [class@AuthDomainDigest]. You must set the [property@AuthDomain:realm] property, to indicate the realm name to be returned with the authentication challenge to the client. Other parameters are optional. the new #SoupAuthDomain name of first option, or %NULL option name/value pairs Encodes the username/realm/password triplet for Digest authentication. That is, it returns a stringified MD5 hash of @username, @realm, and @password concatenated together. This is the form that is needed as the return value of [class@AuthDomainDigest]'s auth handler. For security reasons, you should store the encoded hash, rather than storing the cleartext password itself and calling this method only when you need to verify it. This way, if your server is compromised, the attackers will not gain access to cleartext passwords which might also be usable at other sites. (Note also that the encoded password returned by this method is identical to the encoded password stored in an Apache .htdigest file.) the encoded password a username an auth realm name the password for @username in @realm Sets the callback that @domain will use to authenticate incoming requests. For each request containing authorization, @domain will invoke the callback, and then either accept or reject the request based on @callback's return value. You can also set the auth callback by setting the [property@AuthDomainDigest:auth-callback] and [property@AuthDomainDigest:auth-data] properties, which can also be used to set the callback at construct time. the domain the callback data to pass to @auth_callback destroy notifier to free @user_data when @domain is destroyed The [callback@AuthDomainDigestAuthCallback]. The data to pass to the [callback@AuthDomainDigestAuthCallback]. Callback used by [class@AuthDomainDigest] for authentication purposes. The application should look up @username in its password database, and return the corresponding encoded password (see [func@AuthDomainDigest.encode_password]. the encoded password, or %NULL if @username is not a valid user. @domain will free the password when it is done with it. the domain the message being authenticated the username provided by the client the data passed to [method@AuthDomainDigest.set_auth_callback] The prototype for a [class@AuthDomain] filter. See [method@AuthDomain.set_filter] for details. %TRUE if @msg requires authentication, %FALSE if not. a #SoupAuthDomain a #SoupServerMessage the data passed to [method@AuthDomain.set_filter] The prototype for a [class@AuthDomain] generic authentication callback. The callback should look up the user's password, call [method@AuthDomain.check_password], and use the return value from that method as its own return value. In general, for security reasons, it is preferable to use the auth-domain-specific auth callbacks (eg, [callback@AuthDomainBasicAuthCallback] and [callback@AuthDomainDigestAuthCallback]), because they don't require keeping a cleartext password database. Most users will use the same password for many different sites, meaning if any site with a cleartext password database is compromised, accounts on other servers might be compromised as well. For many of the cases where [class@Server] is used, this is not really relevant, but it may still be worth considering. %TRUE if @msg is authenticated, %FALSE if not. a #SoupAuthDomain the [class@ServerMessage] being authenticated the username from @msg the data passed to [method@AuthDomain.set_generic_auth_callback] HTTP client-side authentication handler. [class@AuthManager] is the [iface@SessionFeature] that handles HTTP authentication for a [class@Session]. A [class@AuthManager] is added to the session by default, and normally you don't need to worry about it at all. However, if you want to disable HTTP authentication, you can remove the feature from the session with [method@Session.remove_feature_by_type] or disable it on individual requests with [method@Message.disable_feature]. You can use this with [method@Session.remove_feature_by_type] or [method@Message.disable_feature]. (Although this type has only been publicly visible since libsoup 2.42, it has always existed in the background, and you can use `g_type_from_name ("SoupAuthManager")` to get its [alias@GObject.Type] in earlier releases.) Clear all credentials cached by @manager. a #SoupAuthManager Records that @auth is to be used under @uri, as though a WWW-Authenticate header had been received at that URI. This can be used to "preload" @manager's auth cache, to avoid an extra HTTP round trip in the case where you know ahead of time that a 401 response will be returned. This is only useful for authentication types where the initial Authorization header does not depend on any additional information from the server. (Eg, Basic or NTLM, but not Digest.) a #SoupAuthManager the #GUri under which @auth is to be used the #SoupAuth to use HTTP-based NTLM authentication. [class@Session]s do not support this type by default; if you want to enable support for it, call [method@Session.add_feature_by_type], passing %SOUP_TYPE_AUTH_NTLM. HTTP-based GSS-Negotiate authentication, as defined by [RFC 4559](https://datatracker.ietf.org/doc/html/rfc4559). [class@Session]s do not support this type by default; if you want to enable support for it, call [method@Session.add_feature_by_type], passing %SOUP_TYPE_AUTH_NEGOTIATE. This auth type will only work if libsoup was compiled with GSSAPI support; you can check [func@AuthNegotiate.supported] to see if it was. Indicates whether libsoup was built with GSSAPI support. If this is %FALSE, %SOUP_TYPE_AUTH_NEGOTIATE will still be defined and can still be added to a [class@Session], but libsoup will never attempt to actually use this auth type. %TRUE if supported otherwise %FALSE Macro to test the version of libsoup being compiled against. Returns %TRUE if the version of the libsoup header files is the same as or newer than the passed-in version. major version (e.g. 2 for version 2.42.0) minor version (e.g. 42 for version 2.42.0) micro version (e.g. 0 for version 2.42.0) A constant corresponding to 1 day. For use with [ctor@Cookie.new] and [method@Cookie.set_max_age]. A constant corresponding to 1 hour. For use with [ctor@Cookie.new] and [method@Cookie.set_max_age]. A constant corresponding to 1 week. For use with [ctor@Cookie.new] and [method@Cookie.set_max_age]. A constant corresponding to 1 year. For use with [ctor@Cookie.new] and [method@Cookie.set_max_age]. File-based cache for HTTP resources. Creates a new #SoupCache. a new #SoupCache the directory to store the cached data, or %NULL to use the default one. Note that since the cache isn't safe to access for multiple processes at once, and the default directory isn't namespaced by process, clients are strongly discouraged from passing %NULL. the #SoupCacheType of the cache Will remove all entries in the @cache plus all the cache files. This is not thread safe and must be called only from the thread that created the [class@Cache] a #SoupCache Synchronously writes the cache index out to disk. Contrast with [method@Cache.flush], which writes pending cache *entries* to disk. You must call this before exiting if you want your cache data to persist between sessions. This is not thread safe and must be called only from the thread that created the [class@Cache] a #SoupCache Forces all pending writes in the @cache to be committed to disk. For doing so it will iterate the [struct@GLib.MainContext] associated with @cache's session as long as needed. Contrast with [method@Cache.dump], which writes out the cache index file. a #SoupCache Gets the maximum size of the cache. the maximum size of the cache, in bytes. a #SoupCache Loads the contents of @cache's index into memory. This is not thread safe and must be called only from the thread that created the [class@Cache] a #SoupCache Sets the maximum size of the cache. a #SoupCache the maximum size of the cache, in bytes The directory to store the cache files. Whether the cache is private or shared. The type of cache; this affects what kinds of responses will be saved. a single-user cache a shared cache Indicates if a message should or shouldn't be cached. The message should be cached The message shouldn't be cached The messages cache should be invalidated The messages cache should be updated Handles decoding of HTTP messages. [class@ContentDecoder] handles adding the "Accept-Encoding" header on outgoing messages, and processing the "Content-Encoding" header on incoming ones. Currently it supports the "gzip", "deflate", and "br" content codings. A [class@ContentDecoder] will automatically be added to the session by default. (You can use [method@Session.remove_feature_by_type] if you don't want this.) If [class@ContentDecoder] successfully decodes the Content-Encoding, the message body will contain the decoded data; however, the message headers will be unchanged (and so "Content-Encoding" will still be present, "Content-Length" will describe the original encoded length, etc). If "Content-Encoding" contains any encoding types that [class@ContentDecoder] doesn't recognize, then none of the encodings will be decoded. (Note that currently there is no way to (automatically) use Content-Encoding when sending a request body, or to pick specific encoding types to support.) Sniffs the mime type of messages. A [class@ContentSniffer] tries to detect the actual content type of the files that are being downloaded by looking at some of the data before the [class@Message] emits its [signal@Message::got-headers] signal. [class@ContentSniffer] implements [iface@SessionFeature], so you can add content sniffing to a session with [method@Session.add_feature] or [method@Session.add_feature_by_type]. Creates a new [class@ContentSniffer]. a new #SoupContentSniffer Sniffs @buffer to determine its Content-Type. The result may also be influenced by the Content-Type declared in @msg's response headers. the sniffed Content-Type of @buffer; this will never be %NULL, but may be `application/octet-stream`. a #SoupContentSniffer the message to sniff a buffer containing the start of @msg's response body return location for Content-Type parameters (eg, "charset"), or %NULL Implements HTTP cookies, as described by [RFC 6265](http://tools.ietf.org/html/rfc6265.txt). To have a [class@Session] handle cookies for your appliction automatically, use a [class@CookieJar]. @name and @value will be set for all cookies. If the cookie is generated from a string that appears to have no name, then @name will be the empty string. @domain and @path give the host or domain, and path within that host/domain, to restrict this cookie to. If @domain starts with ".", that indicates a domain (which matches the string after the ".", or any hostname that has @domain as a suffix). Otherwise, it is a hostname and must match exactly. @expires will be non-%NULL if the cookie uses either the original "expires" attribute, or the newer "max-age" attribute. If @expires is %NULL, it indicates that neither "expires" nor "max-age" was specified, and the cookie expires at the end of the session. If @http_only is set, the cookie should not be exposed to untrusted code (eg, javascript), so as to minimize the danger posed by cross-site scripting attacks. Creates a new [struct@Cookie] with the given attributes. Use [method@Cookie.set_secure] and [method@Cookie.set_http_only] if you need to set those attributes on the returned cookie. If @domain starts with ".", that indicates a domain (which matches the string after the ".", or any hostname that has @domain as a suffix). Otherwise, it is a hostname and must match exactly. @max_age is used to set the "expires" attribute on the cookie; pass -1 to not include the attribute (indicating that the cookie expires with the current session), 0 for an already-expired cookie, or a lifetime in seconds. You can use the constants %SOUP_COOKIE_MAX_AGE_ONE_HOUR, %SOUP_COOKIE_MAX_AGE_ONE_DAY, %SOUP_COOKIE_MAX_AGE_ONE_WEEK and %SOUP_COOKIE_MAX_AGE_ONE_YEAR (or multiples thereof) to calculate this value. (If you really care about setting the exact time that the cookie will expire, use [method@Cookie.set_expires].) As of version 3.4.0 the default value of a cookie's same-site-policy is %SOUP_SAME_SITE_POLICY_LAX. a new #SoupCookie. cookie name cookie value cookie domain or hostname cookie path, or %NULL max age of the cookie, or -1 for a session cookie Tests if @cookie should be sent to @uri. (At the moment, this does not check that @cookie's domain matches @uri, because it assumes that the caller has already done that. But don't rely on that; it may change in the future.) %TRUE if @cookie should be sent to @uri, %FALSE if not a #SoupCookie a #GUri Copies @cookie. a copy of @cookie a #SoupCookie Checks if the @cookie's domain and @host match. The domains match if @cookie should be sent when making a request to @host, or that @cookie should be accepted when receiving a response from @host. %TRUE if the domains match, %FALSE otherwise a #SoupCookie a URI Tests if @cookie1 and @cookie2 are equal. Note that currently, this does not check that the cookie domains match. This may change in the future. whether the cookies are equal. a #SoupCookie a #SoupCookie Frees @cookie. a #SoupCookie Gets @cookie's domain. @cookie's domain a #SoupCookie Gets @cookie's expiration time. @cookie's expiration time, which is owned by @cookie and should not be modified or freed. a #GDateTime Gets @cookie's HttpOnly attribute. @cookie's HttpOnly attribute a #SoupCookie Gets @cookie's name. @cookie's name a #SoupCookie Gets @cookie's path. @cookie's path a #SoupCookie Returns the same-site policy for this cookie. a #SoupSameSitePolicy a #SoupCookie Gets @cookie's secure attribute. @cookie's secure attribute a #SoupCookie Gets @cookie's value. @cookie's value a #SoupCookie Sets @cookie's domain to @domain. a #SoupCookie the new domain Sets @cookie's expiration time to @expires. If @expires is %NULL, @cookie will be a session cookie and will expire at the end of the client's session. (This sets the same property as [method@Cookie.set_max_age].) a #SoupCookie the new expiration time, or %NULL Sets @cookie's HttpOnly attribute to @http_only. If %TRUE, @cookie will be marked as "http only", meaning it should not be exposed to web page scripts or other untrusted code. a #SoupCookie the new value for the HttpOnly attribute Sets @cookie's max age to @max_age. If @max_age is -1, the cookie is a session cookie, and will expire at the end of the client's session. Otherwise, it is the number of seconds until the cookie expires. You can use the constants %SOUP_COOKIE_MAX_AGE_ONE_HOUR, %SOUP_COOKIE_MAX_AGE_ONE_DAY, %SOUP_COOKIE_MAX_AGE_ONE_WEEK and %SOUP_COOKIE_MAX_AGE_ONE_YEAR (or multiples thereof) to calculate this value. (A value of 0 indicates that the cookie should be considered already-expired.) This sets the same property as [method@Cookie.set_expires]. a #SoupCookie the new max age Sets @cookie's name to @name. a #SoupCookie the new name Sets @cookie's path to @path. a #SoupCookie the new path When used in conjunction with [method@CookieJar.get_cookie_list_with_same_site_info] this sets the policy of when this cookie should be exposed. a #SoupCookie a #SoupSameSitePolicy Sets @cookie's secure attribute to @secure. If %TRUE, @cookie will only be transmitted from the client to the server over secure (https) connections. a #SoupCookie the new value for the secure attribute Sets @cookie's value to @value. a #SoupCookie the new value Serializes @cookie in the format used by the Cookie header (ie, for returning a cookie from a [class@Session] to a server). the header a #SoupCookie Serializes @cookie in the format used by the Set-Cookie header. i.e. for sending a cookie from a [class@Server] to a client. the header a #SoupCookie Parses @header and returns a [struct@Cookie]. If @header contains multiple cookies, only the first one will be parsed. If @header does not have "path" or "domain" attributes, they will be defaulted from @origin. If @origin is %NULL, path will default to "/", but domain will be left as %NULL. Note that this is not a valid state for a [struct@Cookie], and you will need to fill in some appropriate string for the domain if you want to actually make use of the cookie. As of version 3.4.0 the default value of a cookie's same-site-policy is %SOUP_SAME_SITE_POLICY_LAX. a new #SoupCookie, or %NULL if it could not be parsed, or contained an illegal "domain" attribute for a cookie originating from @origin. a cookie string (eg, the value of a Set-Cookie header) origin of the cookie Automatic cookie handling for SoupSession. A [class@CookieJar] stores [struct@Cookie]s and arrange for them to be sent with the appropriate [class@Message]s. [class@CookieJar] implements [iface@SessionFeature], so you can add a cookie jar to a session with [method@Session.add_feature] or [method@Session.add_feature_by_type]. Note that the base [class@CookieJar] class does not support any form of long-term cookie persistence. Creates a new [class@CookieJar]. The base [class@CookieJar] class does not support persistent storage of cookies; use a subclass for that. a new #SoupCookieJar Gets whether @jar stores cookies persistenly. %TRUE if @jar storage is persistent or %FALSE otherwise. a #SoupCookieJar Adds @cookie to @jar. Emits the [signal@CookieJar::changed] signal if we are modifying an existing cookie or adding a valid new cookie ('valid' means that the cookie's expire date is not in the past). @cookie will be 'stolen' by the jar, so don't free it afterwards. a #SoupCookieJar a #SoupCookie Adds @cookie to @jar. Emits the [signal@CookieJar::changed] signal if we are modifying an existing cookie or adding a valid new cookie ('valid' means that the cookie's expire date is not in the past). @first_party will be used to reject cookies coming from third party resources in case such a security policy is set in the @jar. @uri will be used to reject setting or overwriting secure cookies from insecure origins. %NULL is treated as secure. @cookie will be 'stolen' by the jar, so don't free it afterwards. a #SoupCookieJar a #SoupCookie the URI setting the cookie the URI for the main document Adds @cookie to @jar. Emits the [signal@CookieJar::changed] signal if we are modifying an existing cookie or adding a valid new cookie ('valid' means that the cookie's expire date is not in the past). @first_party will be used to reject cookies coming from third party resources in case such a security policy is set in the @jar. @cookie will be 'stolen' by the jar, so don't free it afterwards. For secure cookies to work properly you may want to use [method@CookieJar.add_cookie_full]. a #SoupCookieJar the URI for the main document a #SoupCookie Constructs a [struct@GLib.List] with every cookie inside the @jar. The cookies in the list are a copy of the original, so you have to free them when you are done with them. For historical reasons this list is in reverse order. a #GSList with all the cookies in the @jar. a #SoupCookieJar Deletes @cookie from @jar. Emits the [signal@CookieJar::changed] signal. a #SoupCookieJar a #SoupCookie Gets @jar's [enum@CookieJarAcceptPolicy]. the #SoupCookieJarAcceptPolicy set in the @jar a #SoupCookieJar Retrieves the list of cookies that would be sent with a request to @uri as a [struct@GLib.List] of [struct@Cookie] objects. If @for_http is %TRUE, the return value will include cookies marked "HttpOnly" (that is, cookies that the server wishes to keep hidden from client-side scripting operations such as the JavaScript document.cookies property). Since [class@CookieJar] sets the Cookie header itself when making the actual HTTP request, you should almost certainly be setting @for_http to %FALSE if you are calling this. a #GSList with the cookies in the @jar that would be sent with a request to @uri. a #SoupCookieJar a #GUri whether or not the return value is being passed directly to an HTTP operation This is an extended version of [method@CookieJar.get_cookie_list] that provides more information required to use SameSite cookies. See the [SameSite cookies spec](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00) for more detailed information. a #GSList with the cookies in the @jar that would be sent with a request to @uri. a #SoupCookieJar a #GUri a #GUri for the top level document a #GUri indicating the origin to get cookies for whether or not the return value is being passed directly to an HTTP operation if the HTTP method is safe, as defined by RFC 7231, ignored when @for_http is %FALSE whether or not the HTTP request is part of top level navigation Retrieves (in Cookie-header form) the list of cookies that would be sent with a request to @uri. If @for_http is %TRUE, the return value will include cookies marked "HttpOnly" (that is, cookies that the server wishes to keep hidden from client-side scripting operations such as the JavaScript document.cookies property). Since [class@CookieJar] sets the Cookie header itself when making the actual HTTP request, you should almost certainly be setting @for_http to %FALSE if you are calling this. the cookies, in string form, or %NULL if there are no cookies for @uri. a #SoupCookieJar a #GUri whether or not the return value is being passed directly to an HTTP operation Gets whether @jar stores cookies persistenly. %TRUE if @jar storage is persistent or %FALSE otherwise. a #SoupCookieJar Sets @policy as the cookie acceptance policy for @jar. a #SoupCookieJar a #SoupCookieJarAcceptPolicy Adds @cookie to @jar, exactly as though it had appeared in a Set-Cookie header returned from a request to @uri. Keep in mind that if the [enum@CookieJarAcceptPolicy] set is either %SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY or %SOUP_COOKIE_JAR_ACCEPT_GRANDFATHERED_THIRD_PARTY you'll need to use [method@CookieJar.set_cookie_with_first_party], otherwise the jar will have no way of knowing if the cookie is being set by a third party or not. a #SoupCookieJar the URI setting the cookie the stringified cookie to set Adds @cookie to @jar, exactly as though it had appeared in a Set-Cookie header returned from a request to @uri. @first_party will be used to reject cookies coming from third party resources in case such a security policy is set in the @jar. a #SoupCookieJar the URI setting the cookie the URI for the main document the stringified cookie to set The policy the jar should follow to accept or reject cookies. Whether or not the cookie jar is read-only. Emitted when @jar changes. If a cookie has been added, @new_cookie will contain the newly-added cookie and @old_cookie will be %NULL. If a cookie has been deleted, @old_cookie will contain the to-be-deleted cookie and @new_cookie will be %NULL. If a cookie has been changed, @old_cookie will contain its old value, and @new_cookie its new value. the old #SoupCookie value the new #SoupCookie value The policy for accepting or rejecting cookies returned in responses. accept all cookies unconditionally. reject all cookies unconditionally. accept all cookies set by the main document loaded in the application using libsoup. An example of the most common case, web browsers, would be: If http://www.example.com is the page loaded, accept all cookies set by example.com, but if a resource from http://www.third-party.com is loaded from that page reject any cookie that it could try to set. For libsoup to be able to tell apart first party cookies from the rest, the application must call [method@Message.set_first_party] on each outgoing [class@Message], setting the [struct@GLib.Uri] of the main document. If no first party is set in a message when this policy is in effect, cookies will be assumed to be third party by default. accept all cookies set by the main document loaded in the application using libsoup, and from domains that have previously set at least one cookie when loaded as the main document. An example of the most common case, web browsers, would be: if http://www.example.com is the page loaded, accept all cookies set by example.com, but if a resource from http://www.third-party.com is loaded from that page, reject any cookie that it could try to set unless it already has a cookie in the cookie jar. For libsoup to be able to tell apart first party cookies from the rest, the application must call [method@Message.set_first_party] on each outgoing [class@Message], setting the [struct@GLib.Uri] of the main document. If no first party is set in a message when this policy is in effect, cookies will be assumed to be third party by default. %TRUE if @jar storage is persistent or %FALSE otherwise. a #SoupCookieJar Database-based Cookie Jar. [class@CookieJarDB] is a [class@CookieJar] that reads cookies from and writes them to a sqlite database in the new Mozilla format. (This is identical to `SoupCookieJarSqlite` in libsoup-gnome; it has just been moved into libsoup proper, and renamed to avoid conflicting.) Creates a [class@CookieJarDB]. @filename will be read in at startup to create an initial set of cookies. If @read_only is %FALSE, then the non-session cookies will be written to @filename when the [signal@CookieJar::changed] signal is emitted from the jar. (If @read_only is %TRUE, then the cookie jar will only be used for this session, and changes made to it will be lost when the jar is destroyed.) the new #SoupCookieJar the filename to read to/write from, or %NULL %TRUE if @filename is read-only Cookie-storage filename. Text-file-based ("cookies.txt") Cookie Jar [class@CookieJarText] is a [class@CookieJar] that reads cookies from and writes them to a text file in format similar to Mozilla's "cookies.txt". Creates a [class@CookieJarText]. @filename will be read in at startup to create an initial set of cookies. If @read_only is %FALSE, then the non-session cookies will be written to @filename when the [signal@CookieJar::changed] signal is emitted from the jar. (If @read_only is %TRUE, then the cookie jar will only be used for this session, and changes made to it will be lost when the jar is destroyed.) the new #SoupCookieJar the filename to read to/write from %TRUE if @filename is read-only Cookie-storage filename. Marks a symbol as deprecated in favor of another symbol. You should use `SOUP_DEPRECATED_FOR_IN_*` in order to handle versioning. the symbol that replaces the deprecated one A macro used to indicate a symbol was deprecated in this version with a replacement. The recommended replacement function. A macro used to indicate a symbol was deprecated in this version with a replacement. The recommended replacement function. A macro used to indicate a symbol was deprecated in this version with a replacement. The recommended replacement function. A macro used to indicate a symbol was deprecated in this version with a replacement. The recommended replacement function. A macro used to indicate a symbol was deprecated in this version with a replacement. The recommended replacement function. Date formats that [func@date_time_to_string] can use. @SOUP_DATE_HTTP and @SOUP_DATE_COOKIE always coerce the time to UTC. This enum may be extended with more values in future releases. RFC 1123 format, used by the HTTP "Date" header. Eg "Sun, 06 Nov 1994 08:49:37 GMT". The format for the "Expires" timestamp in the Netscape cookie specification. Eg, "Sun, 06-Nov-1994 08:49:37 GMT". How a message body is encoded for transport unknown / error no body is present (which is not the same as a 0-length body, and only occurs in certain places) Content-Length encoding Response body ends when the connection is closed chunked encoding (currently only supported for response) multipart/byteranges (Reserved for future use: NOT CURRENTLY IMPLEMENTED) Represents the parsed value of the "Expect" header. any unrecognized expectation "100-continue" A macro containing the value `multipart/form-data`; the MIME type used for posting form data that contains files to be uploaded. A macro containing the value `application/x-www-form-urlencoded`; the default MIME type for POSTing HTML form data. Automatic HTTP Strict Transport Security enforcing for [class@Session]. A [class@HSTSEnforcer] stores HSTS policies and enforces them when required. [class@HSTSEnforcer] implements [iface@SessionFeature], so you can add an HSTS enforcer to a session with [method@Session.add_feature] or [method@Session.add_feature_by_type]. [class@HSTSEnforcer] keeps track of all the HTTPS destinations that, when connected to, return the Strict-Transport-Security header with valid values. [class@HSTSEnforcer] will forget those destinations upon expiry or when the server requests it. When the [class@Session] the [class@HSTSEnforcer] is attached to queues or restarts a message, the [class@HSTSEnforcer] will rewrite the URI to HTTPS if the destination is a known HSTS host and is contacted over an insecure transport protocol (HTTP). Users of [class@HSTSEnforcer] are advised to listen to changes in the [property@Message:uri] property in order to be aware of changes in the message URI. Note that [class@HSTSEnforcer] does not support any form of long-term HSTS policy persistence. See [class@HSTSEnforcerDB] for a persistent enforcer. Creates a new [class@HSTSEnforcer]. The base [class@HSTSEnforcer] class does not support persistent storage of HSTS policies, see [class@HSTSEnforcerDB] for that. a new #SoupHSTSEnforcer The class closure for the [signal@HSTSEnforcer::changed] signal. Gets whether @hsts_enforcer has a currently valid policy for @domain. %TRUE if access to @domain should happen over HTTPS, false otherwise. a #SoupHSTSEnforcer a domain. Gets whether @hsts_enforcer stores policies persistenly. %TRUE if @hsts_enforcer storage is persistent or %FALSE otherwise. a #SoupHSTSEnforcer Gets a list of domains for which there are policies in @enforcer. a newly allocated list of domains. Use [func@GLib.List.free_full] and [func@GLib.free] to free the list. a #SoupHSTSEnforcer whether to include session policies Gets a list with the policies in @enforcer. a newly allocated list of policies. Use [func@GLib.List.free_full] and [method@HSTSPolicy.free] to free the list. a #SoupHSTSEnforcer whether to include session policies Gets whether @hsts_enforcer has a currently valid policy for @domain. %TRUE if access to @domain should happen over HTTPS, false otherwise. a #SoupHSTSEnforcer a domain. Gets whether @hsts_enforcer stores policies persistenly. %TRUE if @hsts_enforcer storage is persistent or %FALSE otherwise. a #SoupHSTSEnforcer Sets @policy to @hsts_enforcer. If @policy is expired, any existing HSTS policy for its host will be removed instead. If a policy existed for this host, it will be replaced. Otherwise, the new policy will be inserted. If the policy is a session policy, that is, one created with [ctor@HSTSPolicy.new_session_policy], the policy will not expire and will be enforced during the lifetime of @hsts_enforcer's [class@Session]. a #SoupHSTSEnforcer the policy of the HSTS host Sets a session policy for @domain. A session policy is a policy that is permanent to the lifetime of @hsts_enforcer's [class@Session] and doesn't expire. a #SoupHSTSEnforcer policy domain or hostname %TRUE if the policy applies on sub domains Emitted when @hsts_enforcer changes. If a policy has been added, @new_policy will contain the newly-added policy and @old_policy will be %NULL. If a policy has been deleted, @old_policy will contain the to-be-deleted policy and @new_policy will be %NULL. If a policy has been changed, @old_policy will contain its old value, and @new_policy its new value. Note that you shouldn't modify the policies from a callback to this signal. the old #SoupHSTSPolicy value the new #SoupHSTSPolicy value Class structure for [class@HSTSEnforcer]. The parent class. The @is_persistent function advertises whether the enforcer is persistent or whether changes made to it will be lost when the underlying [class@Session] is finished. %TRUE if @hsts_enforcer storage is persistent or %FALSE otherwise. a #SoupHSTSEnforcer The @has_valid_policy function is called to check whether there is a valid policy for the given domain. This method should return %TRUE for [class@HSTSEnforcer] to change the scheme of the #GUri in the [class@Message] to HTTPS. Implementations might want to chain up to the @has_valid_policy in the parent class to check, for instance, for runtime policies. %TRUE if access to @domain should happen over HTTPS, false otherwise. a #SoupHSTSEnforcer a domain. The class closure for the [signal@HSTSEnforcer::changed] signal. Persistent HTTP Strict Transport Security enforcer. [class@HSTSEnforcerDB] is a [class@HSTSEnforcer] that uses a SQLite database as a backend for persistency. Creates a [class@HSTSEnforcerDB]. @filename will be read in during the initialization of a [class@HSTSEnforcerDB], in order to create an initial set of HSTS policies. If the file doesn't exist, a new database will be created and initialized. Changes to the policies during the lifetime of a [class@HSTSEnforcerDB] will be written to @filename when [signal@HSTSEnforcer::changed] is emitted. the new #SoupHSTSEnforcer the filename of the database to read/write from. The filename of the SQLite database where HSTS policies are stored. [struct@HSTSPolicy] implements HTTP policies, as described by [RFC 6797](http://tools.ietf.org/html/rfc6797). @domain represents the host that this policy applies to. The domain must be IDNA-canonicalized. [ctor@HSTSPolicy.new] and related methods will do this for you. @max_age contains the 'max-age' value from the Strict Transport Security header and indicates the time to live of this policy, in seconds. @expires will be non-%NULL if the policy has been set by the host and hence has an expiry time. If @expires is %NULL, it indicates that the policy is a permanent session policy set by the user agent. If @include_subdomains is %TRUE, the Strict Transport Security policy must also be enforced on subdomains of @domain. Creates a new [struct@HSTSPolicy] with the given attributes. @domain is a domain on which the strict transport security policy represented by this object must be enforced. @max_age is used to set the "expires" attribute on the policy; pass %SOUP_HSTS_POLICY_MAX_AGE_PAST for an already-expired policy, or a lifetime in seconds. If @include_subdomains is %TRUE, the strict transport security policy must also be enforced on all subdomains of @domain. a new #SoupHSTSPolicy. policy domain or hostname max age of the policy %TRUE if the policy applies on subdomains Parses @msg's first "Strict-Transport-Security" response header and returns a [struct@HSTSPolicy]. a new #SoupHSTSPolicy, or %NULL if no valid "Strict-Transport-Security" response header was found. a #SoupMessage Full version of [ctor@HSTSPolicy.new], to use with an existing expiration date. See [ctor@HSTSPolicy.new] for details. a new #SoupHSTSPolicy. policy domain or hostname max age of the policy the date of expiration of the policy or %NULL for a permanent policy %TRUE if the policy applies on subdomains Creates a new session [struct@HSTSPolicy] with the given attributes. A session policy is a policy that is valid during the lifetime of the [class@HSTSEnforcer] it is added to. Contrary to regular policies, it has no expiration date and is not stored in persistent enforcers. These policies are useful for user-agent to load their own or user-defined rules. @domain is a domain on which the strict transport security policy represented by this object must be enforced. If @include_subdomains is %TRUE, the strict transport security policy must also be enforced on all subdomains of @domain. a new #SoupHSTSPolicy. policy domain or hostname %TRUE if the policy applies on sub domains Copies @policy. a copy of @policy a #SoupHSTSPolicy Tests if @policy1 and @policy2 are equal. whether the policies are equal. a #SoupHSTSPolicy a #SoupHSTSPolicy Frees @policy. a #SoupHSTSPolicy Gets @policy's domain. @policy's domain. a #SoupHSTSPolicy Returns the expiration date for @policy. A #GDateTime or %NULL if unset a #SoupHSTSPolicy Returns the max age for @policy. Max age in seconds a #SoupHSTSPolicy Gets whether @policy include its subdomains. %TRUE if @policy includes subdomains, %FALSE otherwise. a #SoupHSTSPolicy Gets whether @policy is expired. Permanent policies never expire. %TRUE if @policy is expired, %FALSE otherwise. a #SoupHSTSPolicy Gets whether @policy is a non-permanent, non-expirable session policy. See [ctor@HSTSPolicy.new_session_policy] for details. %TRUE if @policy is permanent, %FALSE otherwise a #SoupHSTSPolicy An expiration date that is always in the past. Indicates the HTTP protocol version being used. HTTP 1.0 (RFC 1945) HTTP 1.1 (RFC 2616) HTTP 2.0 (RFC 7540) The set of #GUriFlags libsoup expects all #GUri to use. Debug logging support [class@Logger] watches a [class@Session] and logs the HTTP traffic that it generates, for debugging purposes. Many applications use an environment variable to determine whether or not to use [class@Logger], and to determine the amount of debugging output. To use [class@Logger], first create a logger with [ctor@Logger.new], optionally configure it with [method@Logger.set_request_filter], [method@Logger.set_response_filter], and [method@Logger.set_printer], and then attach it to a session (or multiple sessions) with [method@Session.add_feature]. By default, the debugging output is sent to `stdout`, and looks something like: ``` > POST /unauth HTTP/1.1 > Soup-Debug-Timestamp: 1200171744 > Soup-Debug: SoupSession 1 (0x612190), SoupMessage 1 (0x617000), GSocket 1 (0x612220) > Host: localhost > Content-Type: text/plain > Connection: close < HTTP/1.1 201 Created < Soup-Debug-Timestamp: 1200171744 < Soup-Debug: SoupMessage 1 (0x617000) < Date: Sun, 12 Jan 2008 21:02:24 GMT < Content-Length: 0 ``` The `Soup-Debug-Timestamp` line gives the time (as a `time_t`) when the request was sent, or the response fully received. The `Soup-Debug` line gives further debugging information about the [class@Session], [class@Message], and [class@Gio.Socket] involved; the hex numbers are the addresses of the objects in question (which may be useful if you are running in a debugger). The decimal IDs are simply counters that uniquely identify objects across the lifetime of the [class@Logger]. In particular, this can be used to identify when multiple messages are sent across the same connection. Currently, the request half of the message is logged just before the first byte of the request gets written to the network (from the [signal@Message::starting] signal). The response is logged just after the last byte of the response body is read from the network (from the [signal@Message::got-body] or [signal@Message::got-informational] signal), which means that the [signal@Message::got-headers] signal, and anything triggered off it (such as [signal@Message::authenticate]) will be emitted *before* the response headers are actually logged. If the response doesn't happen to trigger the [signal@Message::got-body] nor [signal@Message::got-informational] signals due to, for example, a cancellation before receiving the last byte of the response body, the response will still be logged on the event of the [signal@Message::finished] signal. Creates a new [class@Logger] with the given debug level. If you need finer control over what message parts are and aren't logged, use [method@Logger.set_request_filter] and [method@Logger.set_response_filter]. a new #SoupLogger the debug level Get the maximum body size for @logger. the maximum body size, or -1 if unlimited a #SoupLogger Sets the maximum body size for @logger (-1 means no limit). a #SoupLogger the maximum body size to log Sets up an alternate log printing routine, if you don't want the log to go to `stdout`. a #SoupLogger the callback for printing logging output data to pass to the callback a #GDestroyNotify to free @printer_data Sets up a filter to determine the log level for a given request. For each HTTP request @logger will invoke @request_filter to determine how much (if any) of that request to log. (If you do not set a request filter, @logger will just always log requests at the level passed to [ctor@Logger.new].) a #SoupLogger the callback for request debugging data to pass to the callback a #GDestroyNotify to free @filter_data Sets up a filter to determine the log level for a given response. For each HTTP response @logger will invoke @response_filter to determine how much (if any) of that response to log. (If you do not set a response filter, @logger will just always log responses at the level passed to [ctor@Logger.new].) a #SoupLogger the callback for response debugging data to pass to the callback a #GDestroyNotify to free @filter_data The level of logging output. If [property@Logger:level] is %SOUP_LOGGER_LOG_BODY, this gives the maximum number of bytes of the body that will be logged. (-1 means "no limit".) The prototype for a logging filter. The filter callback will be invoked for each request or response, and should analyze it and return a [enum@LoggerLogLevel] value indicating how much of the message to log. a [enum@LoggerLogLevel] value indicating how much of the message to log the #SoupLogger the message being logged the data passed to [method@Logger.set_request_filter] or [method@Logger.set_response_filter] Describes the level of logging output to provide. No logging Log the Request-Line or Status-Line and the Soup-Debug pseudo-headers Log the full request/response headers Log the full headers and request/response bodies The prototype for a custom printing callback. @level indicates what kind of information is being printed. Eg, it will be %SOUP_LOGGER_LOG_HEADERS if @data is header data. @direction is either '<', '>', or ' ', and @data is the single line to print; the printer is expected to add a terminating newline. To get the effect of the default printer, you would do: ```c printf ("%c %s\n", direction, data); ``` the #SoupLogger the level of the information being printed. a single-character prefix to @data data to print the data passed to [method@Logger.set_printer] Like [func@get_major_version], but from the headers used at application compile time, rather than from the library linked against at application run time. Like [func@get_micro_version], but from the headers used at application compile time, rather than from the library linked against at application run time. Like [func@get_minor_version], but from the headers used at application compile time, rather than from the library linked against at application run time. The lifetime of the memory being passed. The memory is statically allocated and constant; libsoup can use the passed-in buffer directly and not need to worry about it being modified or freed. The caller has allocated the memory and libsoup will assume ownership of it and free it with [func@GLib.free]. The passed-in data belongs to the caller and libsoup will copy it into new memory leaving the caller free to reuse the original memory. Represents an HTTP message being sent or received. A [class@Message] represents an HTTP message that is being sent or received. You would create a [class@Message] with [ctor@Message.new] or [ctor@Message.new_from_uri], set up its fields appropriately, and send it. [property@Message:status-code] will normally be a [enum@Status] value, eg, %SOUP_STATUS_OK, though of course it might actually be an unknown status code. [property@Message:reason-phrase] is the actual text returned from the server, which may or may not correspond to the "standard" description of @status_code. At any rate, it is almost certainly not localized, and not very descriptive even if it is in the user's language; you should not use [property@Message:reason-phrase] in user-visible messages. Rather, you should look at [property@Message:status-code], and determine an end-user-appropriate message based on that and on what you were trying to do. Note that libsoup's terminology here does not quite match the HTTP specification: in RFC 2616, an "HTTP-message" is *either* a Request, *or* a Response. In libsoup, a [class@Message] combines both the request and the response. Creates a new empty [class@Message], which will connect to @uri. the new #SoupMessage (or %NULL if @uri could not be parsed). the HTTP method for the created request the destination endpoint (as a string) Creates a new [class@Message] and sets it up to send the given @encoded_form to @uri via @method. If @method is "GET", it will include the form data into @uri's query field, and if @method is "POST" or "PUT", it will be set as request body. This function takes the ownership of @encoded_form, that will be released with [func@GLib.free] when no longer in use. See also [func@form_encode], [func@form_encode_hash] and [func@form_encode_datalist]. the new #SoupMessage, or %NULL if @uri_string could not be parsed or @method is not "GET, "POST" or "PUT" the HTTP method for the created request (GET, POST or PUT) the destination endpoint (as a string) a encoded form Creates a new [class@Message] and sets it up to send @multipart to @uri_string via POST. the new #SoupMessage, or %NULL if @uri_string could not be parsed the destination endpoint a #SoupMultipart Creates a new empty [class@Message], which will connect to @uri. the new #SoupMessage the HTTP method for the created request the destination endpoint Creates a new [class@Message] to send `OPTIONS *` to a server. The path of @base_uri will be ignored. the new #SoupMessage the destination endpoint Adds @flags to the set of @msg's flags. a #SoupMessage a set of #SoupMessageFlags values Adds a signal handler to @msg for @signal. Similar to [func@GObject.signal_connect], but the @callback will only be run if @msg's incoming messages headers (that is, the `request_headers`) contain a header named @header. the handler ID from [func@GObject.signal_connect] a #SoupMessage signal to connect the handler to. HTTP response header to match against the header handler data to pass to @handler_cb Adds a signal handler to @msg for @signal. Similar to [func@GObject.signal_connect], but the @callback will only be run if @msg has the status @status_code. @signal must be a signal that will be emitted after @msg's status is set (this means it can't be a "wrote" signal). the handler ID from [func@GObject.signal_connect] a #SoupMessage signal to connect the handler to. status code to match against the header handler data to pass to @handler_cb Disables the actions of [iface@SessionFeature]s with the given @feature_type (or a subclass of that type) on @msg. @msg is processed as though the feature(s) hadn't been added to the session. Eg, passing #SOUP_TYPE_CONTENT_SNIFFER for @feature_type will disable Content-Type sniffing on the message. You must call this before queueing @msg on a session; calling it on a message that has already been queued is undefined. In particular, you cannot call this on a message that is being requeued after a redirect or authentication. a #SoupMessage the #GType of a [iface@SessionFeature] Returns the unique idenfier for the last connection used. This may be 0 if it was a cached resource or it has not gotten a connection yet. An id or 0 if no connection. The #SoupMessage Gets @msg's first-party [struct@GLib.Uri]. the @msg's first party #GUri a #SoupMessage Gets the flags on @msg. the flags a #SoupMessage Returns whether HTTP/1 version is currently demanded for the @msg send. %TRUE, when HTTP/1 is demanded, %FALSE otherwise. The #SoupMessage Gets the HTTP version of @msg. This is the minimum of the version from the request and the version from the response. the HTTP version a #SoupMessage Gets whether @msg is intended to be used to send `OPTIONS *` to a server. %TRUE if the message is options ping, or %FALSE otherwise a #SoupMessage Returns if this message is set as a top level navigation. Used for same-site policy checks. Whether the current request is a top-level navitation a #SoupMessage Returns the method of this message. A method such as %SOUP_METHOD_GET The #SoupMessage Get the [struct@MessageMetrics] of @msg. If the flag %SOUP_MESSAGE_COLLECT_METRICS is not enabled for @msg this will return %NULL. a #SoupMessageMetrics The #SoupMessage Retrieves the [enum@MessagePriority]. If not set this value defaults to #SOUP_MESSAGE_PRIORITY_NORMAL. the priority of the message. a #SoupMessage Returns the reason phrase for the status of this message. the phrase The #SoupMessage Get the remote [class@Gio.SocketAddress] of the connection associated with the message. The returned address can be %NULL if the connection hasn't been established yet, or the resource was loaded from the disk cache. In case of proxy connections, the remote address returned is a [class@Gio.ProxyAddress]. If [property@Session:remote-connectable] is set the returned address id for the connection to the session's remote connectable. a #GSocketAddress or %NULL if the connection hasn't been established The #SoupMessage Returns the headers sent with the request. The [struct@MessageHeaders] The #SoupMessage Returns the headers recieved with the response. The [struct@MessageHeaders] The #SoupMessage Gets @msg's site for cookies #GUri. the @msg's site for cookies #GUri a #SoupMessage Returns the set status of this message. The #SoupStatus The #SoupMessage Gets the name of the TLS ciphersuite negotiated for @msg's connection. the name of the TLS ciphersuite, or %NULL if @msg's connection is not SSL. a #SoupMessage Gets the peer's [class@Gio.TlsCertificate] associated with @msg's connection. Note that this is not set yet during the emission of [signal@Message::accept-certificate] signal. @msg's TLS peer certificate, or %NULL if @msg's connection is not SSL. a #SoupMessage Gets the errors associated with validating @msg's TLS peer certificate. Note that this is not set yet during the emission of [signal@Message::accept-certificate] signal. a #GTlsCertificateFlags with @msg's TLS peer certificate errors. a #SoupMessage Gets the TLS protocol version negotiated for @msg's connection. If the message connection is not SSL, %G_TLS_PROTOCOL_VERSION_UNKNOWN is returned. a #GTlsProtocolVersion a #SoupMessage Gets @msg's URI. the URI @msg is targeted for. a #SoupMessage Get whether [iface@SessionFeature]s of the given @feature_type (or a subclass of that type) are disabled on @msg. See [method@Message.disable_feature]. %TRUE if feature is disabled, or %FALSE otherwise. a #SoupMessage the #GType of a [iface@SessionFeature] Determines whether or not @msg's connection can be kept alive for further requests after processing @msg. The result is based on the HTTP version, Connection header, etc. %TRUE or %FALSE. a #SoupMessage Queries if @flags are present in the set of @msg's flags. %TRUE if @flags are enabled in @msg a #SoupMessage a set of #SoupMessageFlags values Removes @flags from the set of @msg's flags. a #SoupMessage a set of #SoupMessageFlags values Sets @first_party as the main document #GUri for @msg. For details of when and how this is used refer to the documentation for [enum@CookieJarAcceptPolicy]. a #SoupMessage the #GUri for the @msg's first party Sets the specified flags on @msg. a #SoupMessage a set of #SoupMessageFlags values Sets whether HTTP/1 version should be used when sending this message. Some connections can still override it, if needed. Note the value is unset after the message send is finished. The #SoupMessage value to set Set whether @msg is intended to be used to send `OPTIONS *` to a server. When set to %TRUE, the path of [property@Message:uri] will be ignored and [property@Message:method] set to %SOUP_METHOD_OPTIONS. a #SoupMessage the value to set Sets whether the current request is a top-level navitation. See the [same-site spec](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00) for more information. a #SoupMessage if %TRUE indicate the current request is a top-level navigation Set @msg's HTTP method to @method. a #SoupMessage the value to set Sets the priority of a message. Note that this won't have any effect unless used before the message is added to the session's message processing queue. The message will be placed just before any other previously added message with lower priority (messages with the same priority are processed on a FIFO basis). Setting priorities does not currently work with synchronous messages because in the synchronous/blocking case, priority ends up being determined semi-randomly by thread scheduling. a #SoupMessage the #SoupMessagePriority Set the request body of a [class@Message]. If @content_type is %NULL and @stream is not %NULL the Content-Type header will not be changed if present. The request body needs to be set again in case @msg is restarted (in case of redirection or authentication). the message MIME Content-Type of the body, or %NULL if unknown a #GInputStream to read the request body from the byte length of @stream or -1 if unknown Set the request body of a [class@Message] from [struct@GLib.Bytes]. If @content_type is %NULL and @bytes is not %NULL the Content-Type header will not be changed if present. The request body needs to be set again in case @msg is restarted (in case of redirection or authentication). the message MIME Content-Type of the body, or %NULL if unknown a #GBytes with the request body data Sets @site_for_cookies as the policy URL for same-site cookies for @msg. It is either the URL of the top-level document or %NULL depending on whether the registrable domain of this document's URL matches the registrable domain of its parent's/opener's URL. For the top-level document it is set to the document's URL. See the [same-site spec](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00) for more information. a #SoupMessage the #GUri for the @msg's site for cookies Sets the @certificate to be used by @msg's connection when a client certificate is requested during the TLS handshake. You can call this as a response to [signal@Message::request-certificate] signal, or before the connection is started. If @certificate is %NULL the handshake will continue without providing a GTlsCertificate. Note that the [class@Gio.TlsCertificate] set by this function will be ignored if [property@Session:tls-interaction] is not %NULL. a #SoupMessage the #GTlsCertificate to set, or %NULL Sets @msg's URI to @uri. If @msg has already been sent and you want to re-send it with the new URI, you need to send it again. a #SoupMessage the new #GUri Completes a certificate password request. You must call this as a response to [signal@Message::request-certificate-password] signal, to notify @msg that the [class@Gio.TlsPassword] has already been updated. a #SoupMessage The [struct@GLib.Uri] loaded in the application when the message was queued. Various message options. The HTTP protocol version to use. Whether the message is an OPTIONS ping. The [class@Message] is intended to be used to send `OPTIONS *` to a server. When set to %TRUE, the path of [property@Message:uri] will be ignored and [property@Message:method] set to %SOUP_METHOD_OPTIONS. Set when the message is navigating between top level domains. The message's HTTP method. Sets the priority of the [class@Message]. See [method@Message.set_priority] for further details. The HTTP response reason phrase. The remote [class@Gio.SocketAddress] of the connection associated with the message. The HTTP request headers. The HTTP response headers. Site used to compare cookies against. Used for SameSite cookie support. The HTTP response status code. The Name of TLS ciphersuite negotiated for this message connection. The peer's [class@Gio.TlsCertificate] associated with the message. The verification errors on [property@Message:tls-peer-certificate]. The TLS protocol version negotiated for the message connection. The message's Request-URI. Emitted during the @msg's connection TLS handshake after an unacceptable TLS certificate has been received. You can return %TRUE to accept @tls_certificate despite @tls_errors. %TRUE to accept the TLS certificate and stop other handlers from being invoked, or %FALSE to propagate the event further. the peer's #GTlsCertificate the tls errors of @tls_certificate Emitted when the message requires authentication. If credentials are available call [method@Auth.authenticate] on @auth. If these credentials fail, the signal will be emitted again, with @retrying set to %TRUE, which will continue until you return without calling [method@Auth.authenticate] on @auth. Note that this may be emitted before @msg's body has been fully read. You can authenticate @auth asynchronously by calling [method@GObject.Object.ref] on @auth and returning %TRUE. The operation will complete once either [method@Auth.authenticate] or [method@Auth.cancel] are called. %TRUE to stop other handlers from being invoked or %FALSE to propagate the event further. the #SoupAuth to authenticate %TRUE if this is the second (or later) attempt This signal is emitted after [signal@Message::got-headers]. If content sniffing is disabled, or no content sniffing will be performed, due to the sniffer deciding to trust the Content-Type sent by the server, this signal is emitted immediately after [signal@Message::got-headers], and @type is %NULL. the content type that we got from sniffing a #GHashTable with the parameters Emitted when all HTTP processing is finished for a message. (After [signal@Message::got_body]). Emitted after receiving the complete message response body. Emitted after reading a portion of the message body from the network. the number of bytes read Emitted after receiving the Status-Line and response headers. See also [method@Message.add_header_handler] and [method@Message.add_status_code_handler], which can be used to connect to a subset of emissions of this signal. If you cancel or requeue @msg while processing this signal, then the current HTTP I/O will be stopped after this signal emission finished, and @msg's connection will be closed. (If you need to requeue a message--eg, after handling authentication or redirection--it is usually better to requeue it from a [signal@Message::got-body] handler rather than a [signal@Message::got_headers] handler, so that the existing HTTP connection can be reused.) Emitted after receiving a 1xx (Informational) response for a (client-side) message. The response_headers will be filled in with the headers associated with the informational response; however, those header values will be erased after this signal is done. If you cancel or requeue @msg while processing this signal, then the current HTTP I/O will be stopped after this signal emission finished, and @msg's connection will be closed. Emitted when [class@HSTSEnforcer] has upgraded the protocol for @msg to HTTPS as a result of matching its domain with a HSTS policy. Emitted to indicate that some network-related event related to @msg has occurred. This essentially proxies the [signal@Gio.SocketClient::event] signal, but only for events that occur while @msg "owns" the connection; if @msg is sent on an existing persistent connection, then this signal will not be emitted. (If you want to force the message to be sent on a new connection, set the %SOUP_MESSAGE_NEW_CONNECTION flag on it.) See [signal@Gio.SocketClient::event] for more information on what the different values of @event correspond to, and what @connection will be in each case. the network event the current state of the network connection Emitted during the @msg's connection TLS handshake when @tls_connection requests a certificate from the client. You can set the client certificate by calling [method@Message.set_tls_client_certificate] and returning %TRUE. It's possible to handle the request asynchornously by returning %TRUE and call [method@Message.set_tls_client_certificate] later once the certificate is available. Note that this signal is not emitted if [property@Session:tls-interaction] was set, or if [method@Message.set_tls_client_certificate] was called before the connection TLS handshake started. %TRUE to handle the request, or %FALSE to make the connection fail with %G_TLS_ERROR_CERTIFICATE_REQUIRED. the #GTlsClientConnection Emitted during the @msg's connection TLS handshake when @tls_connection requests a certificate password from the client. You can set the certificate password on @password, then call [method@Message.tls_client_certificate_password_request_complete] and return %TRUE to handle the signal synchronously. It's possible to handle the request asynchornously by calling [method@GObject.Object.ref] on @password, then returning %TRUE and call [method@Message.tls_client_certificate_password_request_complete] later after setting the password on @password. Note that this signal is not emitted if [property@Session:tls-interaction] was set. %TRUE to handle the request, or %FALSE to make the connection fail with %G_TLS_ERROR_CERTIFICATE_REQUIRED. the #GTlsPassword Emitted when a request that was already sent once is now being sent again. e.g. because the first attempt received a redirection response, or because we needed to use authentication. Emitted just before a message is sent. Emitted immediately after writing the complete body for a message. Emitted immediately after writing a portion of the message body to the network. the number of bytes written Emitted immediately after writing the request headers for a message. [struct@MessageBody] represents the request or response body of a [class@Message]. Note that while @length always reflects the full length of the message body, @data is normally %NULL, and will only be filled in after [method@MessageBody.flatten] is called. For client-side messages, this automatically happens for the response body after it has been fully read. Likewise, for server-side messages, the request body is automatically filled in after being read. As an added bonus, when @data is filled in, it is always terminated with a `\0` byte (which is not reflected in @length). the data length of @data Creates a new [struct@MessageBody] [class@Message] uses this internally; you will not normally need to call it yourself. a new #SoupMessageBody. Appends @length bytes from @data to @body according to @use. a #SoupMessageBody how to use @data data to append length of @data Appends the data from @buffer to @body. a #SoupMessageBody a #GBytes Appends @length bytes from @data to @body. This function is exactly equivalent to [method@MessageBody.append] with %SOUP_MEMORY_TAKE as second argument; it exists mainly for convenience and simplifying language bindings. a #SoupMessageBody data to append length of @data Tags @body as being complete. Call this when using chunked encoding after you have appended the last chunk. a #SoupMessageBody Fills in @body's data field with a buffer containing all of the data in @body. Adds an additional `\0` byte not counted by @body's length field. a #GBytes containing the same data as @body. (You must [method@GLib.Bytes.unref] this if you do not want it.) a #SoupMessageBody Gets the accumulate flag on @body. See [method@MessageBody.set_accumulate. for details. the accumulate flag for @body. a #SoupMessageBody Gets a [struct@GLib.Bytes] containing data from @body starting at @offset. The size of the returned chunk is unspecified. You can iterate through the entire body by first calling [method@MessageBody.get_chunk] with an offset of 0, and then on each successive call, increment the offset by the length of the previously-returned chunk. If @offset is greater than or equal to the total length of @body, then the return value depends on whether or not [method@MessageBody.complete] has been called or not; if it has, then [method@MessageBody.get_chunk] will return a 0-length chunk (indicating the end of @body). If it has not, then [method@MessageBody.get_chunk] will return %NULL (indicating that @body may still potentially have more data, but that data is not currently available). a #GBytes a #SoupMessageBody an offset Handles the [struct@MessageBody] part of receiving a chunk of data from the network. Normally this means appending @chunk to @body, exactly as with [method@MessageBody.append_bytes], but if you have set @body's accumulate flag to %FALSE, then that will not happen. This is a low-level method which you should not normally need to use. a #SoupMessageBody a #GBytes received from the network Atomically increments the reference count of @body by one. the passed in #SoupMessageBody a #SoupMessageBody Sets or clears the accumulate flag on @body. (The default value is %TRUE.) If set to %FALSE, @body's data field will not be filled in after the body is fully sent/received, and the chunks that make up @body may be discarded when they are no longer needed. If you set the flag to %FALSE on the [class@Message] request_body of a client-side message, it will block the accumulation of chunks into @body's data field, but it will not normally cause the chunks to be discarded after being written like in the server-side [class@Message] response_body case, because the request body needs to be kept around in case the request needs to be sent a second time due to redirection or authentication. a #SoupMessageBody whether or not to accumulate body chunks in @body Deletes all of the data in @body. a #SoupMessageBody Atomically decrements the reference count of @body by one. When the reference count reaches zero, the resources allocated by @body are freed a #SoupMessageBody Handles the [struct@MessageBody] part of writing a chunk of data to the network. Normally this is a no-op, but if you have set @body's accumulate flag to %FALSE, then this will cause @chunk to be discarded to free up memory. This is a low-level method which you should not need to use, and there are further restrictions on its proper use which are not documented here. a #SoupMessageBody a #GBytes returned from [method@MessageBody.get_chunk] Various flags that can be set on a [class@Message] to alter its behavior. The session should not follow redirect (3xx) responses received by this message. Requests that the message should be sent on a newly-created connection, not reusing an existing persistent connection. Note that messages with non-idempotent [property@Message:method]s behave this way by default, unless #SOUP_MESSAGE_IDEMPOTENT is set. The message is considered idempotent, regardless its [property@Message:method], and allows reuse of existing idle connections, instead of always requiring a new one, unless #SOUP_MESSAGE_NEW_CONNECTION is set. The [class@AuthManager] should not use the credentials cache for this message, neither to use cached credentials to automatically authenticate this message nor to cache the credentials after the message is successfully authenticated. This applies to both server and proxy authentication. Note that [signal@Message::authenticate] signal will be emitted, if you want to disable authentication for a message use [method@Message.disable_feature] passing #SOUP_TYPE_AUTH_MANAGER instead. Metrics will be collected for this message. The HTTP message headers associated with a request or response. Creates a [struct@MessageHeaders]. ([class@Message] does this automatically for its own headers. You would only need to use this method if you are manually parsing or generating message headers.) a new #SoupMessageHeaders the type of headers Appends a new header with name @name and value @value to @hdrs. (If there is an existing header with name @name, then this creates a second one, which is only allowed for list-valued headers; see also [method@MessageHeaders.replace].) The caller is expected to make sure that @name and @value are syntactically correct. a #SoupMessageHeaders the header name to add the new value of @name Removes all the headers listed in the Connection header. a #SoupMessageHeaders Clears @hdrs. a #SoupMessageHeaders Calls @func once for each header value in @hdrs. Beware that unlike [method@MessageHeaders.get_list], this processes the headers in exactly the way they were added, rather than concatenating multiple same-named headers into a single value. (This is intentional; it ensures that if you call [method@MessageHeaders.append] multiple times with the same name, then the I/O code will output multiple copies of the header when sending the message to the remote implementation, which may be required for interoperability in some cases.) You may not modify the headers from @func. a #SoupMessageHeaders callback function to run for each header data to pass to @func Frees the array of ranges returned from [method@MessageHeaders.get_ranges]. a #SoupMessageHeaders an array of #SoupRange Looks up the "Content-Disposition" header in @hdrs, parses it, and returns its value in *@disposition and *@params. @params can be %NULL if you are only interested in the disposition-type. In HTTP, the most common use of this header is to set a disposition-type of "attachment", to suggest to the browser that a response should be saved to disk rather than displayed in the browser. If @params contains a "filename" parameter, this is a suggestion of a filename to use. (If the parameter value in the header contains an absolute or relative path, libsoup will truncate it down to just the final path component, so you do not need to test this yourself.) Content-Disposition is also used in "multipart/form-data", however this is handled automatically by [struct@Multipart] and the associated form methods. %TRUE if @hdrs contains a "Content-Disposition" header, %FALSE if not (in which case *@disposition and *@params will be unchanged). a #SoupMessageHeaders return location for the disposition-type, or %NULL return location for the Content-Disposition parameters, or %NULL Gets the message body length that @hdrs declare. This will only be non-0 if [method@MessageHeaders.get_encoding] returns %SOUP_ENCODING_CONTENT_LENGTH. the message body length declared by @hdrs. a #SoupMessageHeaders Parses @hdrs's Content-Range header and returns it in @start, @end, and @total_length. If the total length field in the header was specified as "*", then @total_length will be set to -1. %TRUE if @hdrs contained a "Content-Range" header containing a byte range which could be parsed, %FALSE otherwise. a #SoupMessageHeaders return value for the start of the range return value for the end of the range return value for the total length of the resource, or %NULL if you don't care. Looks up the "Content-Type" header in @hdrs, parses it, and returns its value in *@content_type and *@params. @params can be %NULL if you are only interested in the content type itself. a string with the value of the "Content-Type" header or %NULL if @hdrs does not contain that header or it cannot be parsed (in which case *@params will be unchanged). a #SoupMessageHeaders return location for the Content-Type parameters (eg, "charset"), or %NULL Gets the message body encoding that @hdrs declare. This may not always correspond to the encoding used on the wire; eg, a HEAD response may declare a Content-Length or Transfer-Encoding, but it will never actually include a body. the encoding declared by @hdrs. a #SoupMessageHeaders Gets the expectations declared by @hdrs's "Expect" header. Currently this will either be %SOUP_EXPECTATION_CONTINUE or %SOUP_EXPECTATION_UNRECOGNIZED. the contents of @hdrs's "Expect" header a #SoupMessageHeaders Gets the type of headers. the header's type. a #SoupMessageHeaders Gets the value of header @name in @hdrs. Use this for headers whose values are comma-delimited lists, and which are therefore allowed to appear multiple times in the headers. For non-list-valued headers, use [method@MessageHeaders.get_one]. If @name appears multiple times in @hdrs, [method@MessageHeaders.get_list] will concatenate all of the values together, separated by commas. This is sometimes awkward to parse (eg, WWW-Authenticate, Set-Cookie), but you have to be able to deal with it anyway, because the HTTP spec explicitly states that this transformation is allowed, and so an upstream proxy could do the same thing. the header's value or %NULL if not found. a #SoupMessageHeaders header name Gets the value of header @name in @hdrs. Use this for headers whose values are *not* comma-delimited lists, and which therefore can only appear at most once in the headers. For list-valued headers, use [method@MessageHeaders.get_list]. If @hdrs does erroneously contain multiple copies of the header, it is not defined which one will be returned. (Ideally, it will return whichever one makes libsoup most compatible with other HTTP implementations.) the header's value or %NULL if not found. a #SoupMessageHeaders header name Parses @hdrs's Range header and returns an array of the requested byte ranges. The returned array must be freed with [method@MessageHeaders.free_ranges]. If @total_length is non-0, its value will be used to adjust the returned ranges to have explicit start and end values, and the returned ranges will be sorted and non-overlapping. If @total_length is 0, then some ranges may have an end value of -1, as described under [struct@Range], and some of the ranges may be redundant. Beware that even if given a @total_length, this function does not check that the ranges are satisfiable. [class@Server] has built-in handling for range requests. If your server handler returns a %SOUP_STATUS_OK response containing the complete response body (rather than pausing the message and returning some of the response body later), and there is a Range header in the request, then libsoup will automatically convert the response to a %SOUP_STATUS_PARTIAL_CONTENT response containing only the range(s) requested by the client. The only time you need to process the Range header yourself is if either you need to stream the response body rather than returning it all at once, or you do not already have the complete response body available, and only want to generate the parts that were actually requested by the client. %TRUE if @hdrs contained a syntactically-valid "Range" header, %FALSE otherwise (in which case @range and @length will not be set). a #SoupMessageHeaders the total_length of the response body return location for an array of #SoupRange the length of the returned array Checks whether the list-valued header @name is present in @hdrs, and contains a case-insensitive match for @token. (If @name is present in @hdrs, then this is equivalent to calling [func@header_contains] on its value.) %TRUE if the header is present and contains @token, %FALSE otherwise. a #SoupMessageHeaders header name token to look for Checks whether the header @name is present in @hdrs and is (case-insensitively) equal to @value. %TRUE if the header is present and its value is @value, %FALSE otherwise. a #SoupMessageHeaders header name expected value Atomically increments the reference count of @hdrs by one. the passed in #SoupMessageHeaders a #SoupMessageHeaders Removes @name from @hdrs. If there are multiple values for @name, they are all removed. a #SoupMessageHeaders the header name to remove Replaces the value of the header @name in @hdrs with @value. See also [method@MessageHeaders.append]. The caller is expected to make sure that @name and @value are syntactically correct. a #SoupMessageHeaders the header name to replace the new value of @name Sets the "Content-Disposition" header in @hdrs to @disposition, optionally with additional parameters specified in @params. See [method@MessageHeaders.get_content_disposition] for a discussion of how Content-Disposition is used in HTTP. a #SoupMessageHeaders the disposition-type additional parameters Sets the message body length that @hdrs will declare, and sets @hdrs's encoding to %SOUP_ENCODING_CONTENT_LENGTH. You do not normally need to call this; if @hdrs is set to use Content-Length encoding, libsoup will automatically set its Content-Length header for you immediately before sending the headers. One situation in which this method is useful is when generating the response to a HEAD request; Calling [method@MessageHeaders.set_content_length] allows you to put the correct content length into the response without needing to waste memory by filling in a response body which won't actually be sent. a #SoupMessageHeaders the message body length Sets @hdrs's Content-Range header according to the given values. (Note that @total_length is the total length of the entire resource that this is a range of, not simply @end - @start + 1.) [class@Server] has built-in handling for range requests, and you do not normally need to call this function youself. See [method@MessageHeaders.get_ranges] for more details. a #SoupMessageHeaders the start of the range the end of the range the total length of the resource, or -1 if unknown Sets the "Content-Type" header in @hdrs to @content_type. Accepts additional parameters specified in @params. a #SoupMessageHeaders the MIME type additional parameters Sets the message body encoding that @hdrs will declare. In particular, you should use this if you are going to send a request or response in chunked encoding. a #SoupMessageHeaders a #SoupEncoding Sets @hdrs's "Expect" header according to @expectations. Currently %SOUP_EXPECTATION_CONTINUE is the only known expectation value. You should set this value on a request if you are sending a large message body (eg, via POST or PUT), and want to give the server a chance to reject the request after seeing just the headers (eg, because it will require authentication before allowing you to post, or because you're POSTing to a URL that doesn't exist). This saves you from having to transmit the large request body when the server is just going to ignore it anyway. a #SoupMessageHeaders the expectations to set Sets @hdrs's Range header to request the indicated range. @start and @end are interpreted as in a [struct@Range]. If you need to request multiple ranges, use [method@MessageHeaders.set_ranges]. a #SoupMessageHeaders the start of the range to request the end of the range to request Sets @hdrs's Range header to request the indicated ranges. If you only want to request a single range, you can use [method@MessageHeaders.set_range]. a #SoupMessageHeaders an array of #SoupRange the length of @range Atomically decrements the reference count of @hdrs by one. When the reference count reaches zero, the resources allocated by @hdrs are freed a #SoupMessageHeaders The callback passed to [method@MessageHeaders.foreach]. the header name the header value the data passed to [method@MessageHeaders.foreach] An opaque type used to iterate over a [struct@MessageHeaders] structure After intializing the iterator with [func@MessageHeadersIter.init], call [func@MessageHeadersIter.next] to fetch data from it. You may not modify the headers while iterating over them. Initializes @iter for iterating @hdrs. a pointer to a #SoupMessageHeadersIter structure a #SoupMessageHeaders Yields the next name/value pair in the [struct@MessageHeaders] being iterated by @iter. If @iter has already yielded the last header, then [func@MessageHeadersIter.next] will return %FALSE and @name and @value will be unchanged. %TRUE if another name and value were returned, %FALSE if the end of the headers has been reached. a #SoupMessageHeadersIter pointer to a variable to return the header name in pointer to a variable to return the header value in Value passed to [ctor@MessageHeaders.new] to set certain default behaviors. request headers response headers multipart body part headers Contains metrics collected while loading a [class@Message] either from the network or the disk cache. Metrics are not collected by default for a [class@Message], you need to add the flag %SOUP_MESSAGE_COLLECT_METRICS to enable the feature. Temporal metrics are expressed as a monotonic time and always start with a fetch start event and finish with response end. All other events are optional. An event can be 0 because it hasn't happened yet, because it's optional or because the load failed before the event reached. Size metrics are expressed in bytes and are updated while the [class@Message] is being loaded. You can connect to different [class@Message] signals to get the final result of every value. Copies @metrics. a copy of @metrics a #SoupMessageMetrics Frees @metrics. a #SoupMessageMetrics Get the time immediately after the [class@Message] completed the connection to the server. This includes the time for the proxy negotiation and TLS handshake. It will be 0 if no network connection was required to fetch the resource (a persistent connection was used or resource was loaded from the local disk cache). the connection end time a #SoupMessageMetrics Get the time immediately before the [class@Message] started to establish the connection to the server. It will be 0 if no network connection was required to fetch the resource (a persistent connection was used or resource was loaded from the local disk cache). the connection start time a #SoupMessageMetrics Get the time immediately after the [class@Message] completed the domain lookup name for the resource. It will be 0 if no domain lookup was required to fetch the resource (a persistent connection was used or resource was loaded from the local disk cache). the domain lookup end time a #SoupMessageMetrics Get the time immediately before the [class@Message] started the domain lookup name for the resource. It will be 0 if no domain lookup was required to fetch the resource (a persistent connection was used or resource was loaded from the local disk cache). the domain lookup start time a #SoupMessageMetrics Get the time immediately before the [class@Message] started to fetch a resource either from a remote server or local disk cache. the fetch start time a #SoupMessageMetrics Get the number of bytes sent to the network for the request body. This is the size of the body sent, after encodings are applied, so it might be greater than the value returned by [method@MessageMetrics.get_request_body_size]. This value is available right before [signal@Message::wrote-body] signal is emitted, but you might get an intermediate value if called before. the request body bytes sent a #SoupMessageMetrics Get the request body size in bytes. This is the size of the original body given to the request before any encoding is applied. This value is available right before [signal@Message::wrote-body] signal is emitted, but you might get an intermediate value if called before. the request body size a #SoupMessageMetrics Get the number of bytes sent to the network for the request headers. This value is available right before [signal@Message::wrote-headers] signal is emitted, but you might get an intermediate value if called before. the request headers bytes sent a #SoupMessageMetrics Get the time immediately before the [class@Message] started the request of the resource from the server or the local disk cache. the request start time a #SoupMessageMetrics Get the number of bytes received from the network for the response body. This value is available right before [signal@Message::got-body] signal is emitted, but you might get an intermediate value if called before. For resources loaded from the disk cache this value is always 0. the response body bytes received a #SoupMessageMetrics Get the response body size in bytes. This is the size of the body as given to the user after all encodings are applied, so it might be greater than the value returned by [method@MessageMetrics.get_response_body_bytes_received]. This value is available right before [signal@Message::got-body] signal is emitted, but you might get an intermediate value if called before. the response body size a #SoupMessageMetrics Get the time immediately after the [class@Message] received the last bytes of the response from the server or the local disk cache. In case of load failure, this returns the time immediately before the fetch is aborted. the response end time a #SoupMessageMetrics Get the number of bytes received from the network for the response headers. This value is available right before [signal@Message::got-headers] signal is emitted, but you might get an intermediate value if called before. For resources loaded from the disk cache this value is always 0. the response headers bytes received a #SoupMessageMetrics Get the time immediately after the [class@Message] received the first bytes of the response from the server or the local disk cache. the response start time a #SoupMessageMetrics Get the time immediately before the [class@Message] started the TLS handshake. It will be 0 if no TLS handshake was required to fetch the resource (connection was not secure, a persistent connection was used or resource was loaded from the local disk cache). the tls start time a #SoupMessageMetrics Priorities that can be set on a [class@Message] to instruct the message queue to process it before any other message with lower priority. The lowest priority, the messages with this priority will be the last ones to be attended. Use this for low priority messages, a [class@Message] with the default priority will be processed first. The default priotity, this is the priority assigned to the [class@Message] by default. High priority, a [class@Message] with this priority will be processed before the ones with the default priority. The highest priority, use this for very urgent [class@Message] as they will be the first ones to be attended. Represents a multipart HTTP message body, parsed according to the syntax of RFC 2046. Of particular interest to HTTP are `multipart/byte-ranges` and `multipart/form-data`, Although the headers of a [struct@Multipart] body part will contain the full headers from that body part, libsoup does not interpret them according to MIME rules. For example, each body part is assumed to have "binary" Content-Transfer-Encoding, even if its headers explicitly state otherwise. In other words, don't try to use [struct@Multipart] for handling real MIME multiparts. Creates a new empty [struct@Multipart] with a randomly-generated boundary string. Note that @mime_type must be the full MIME type, including "multipart/". See also: [ctor@Message.new_from_multipart]. a new empty #SoupMultipart of the given @mime_type the MIME type of the multipart to create. Parses @headers and @body to form a new [struct@Multipart] a new #SoupMultipart (or %NULL if the message couldn't be parsed or wasn't multipart). the headers of the HTTP message to parse the body of the HTTP message to parse Adds a new MIME part containing @body to @multipart Uses "Content-Disposition: form-data", as per the HTML forms specification. a multipart (presumably of type "multipart/form-data") the name of the control associated with this file the name of the file, or %NULL if not known the MIME type of the file, or %NULL if not known the file data Adds a new MIME part containing @data to @multipart. Uses "Content-Disposition: form-data", as per the HTML forms specification. a multipart (presumably of type "multipart/form-data") the name of the control associated with @data the body data Adds a new MIME part to @multipart with the given headers and body. (The multipart will make its own copies of @headers and @body, so you should free your copies if you are not using them for anything else.) a #SoupMultipart the MIME part headers the MIME part body Frees @multipart. a #SoupMultipart Gets the number of body parts in @multipart. the number of body parts in @multipart a #SoupMultipart Gets the indicated body part from @multipart. %TRUE on success, %FALSE if @part is out of range (in which case @headers and @body won't be set) a #SoupMultipart the part number to get (counting from 0) return location for the MIME part headers return location for the MIME part body Serializes @multipart to @dest_headers and @dest_body. a #SoupMultipart the headers of the HTTP message to serialize @multipart to the body of the HTTP message to serialize @multipart to Handles streams of multipart messages. This adds support for the multipart responses. For handling the multiple parts the user needs to wrap the [class@Gio.InputStream] obtained by sending the request with a [class@MultipartInputStream] and use [method@MultipartInputStream.next_part] before reading. Responses which are not wrapped will be treated like non-multipart responses. Note that although [class@MultipartInputStream] is a [class@Gio.InputStream], you should not read directly from it, and the results are undefined if you do. Creates a new [class@MultipartInputStream] that wraps the [class@Gio.InputStream] obtained by sending the [class@Message]. Reads should not be done directly through this object, use the input streams returned by [method@MultipartInputStream.next_part] or its async counterpart instead. a new #SoupMultipartInputStream the #SoupMessage the response is related to. the #GInputStream returned by sending the request. Obtains the headers for the part currently being processed. Note that the [struct@MessageHeaders] that are returned are owned by the [class@MultipartInputStream] and will be replaced when a call is made to [method@MultipartInputStream.next_part] or its async counterpart, so if keeping the headers is required, a copy must be made. Note that if a part had no headers at all an empty [struct@MessageHeaders] will be returned. a #SoupMessageHeaders containing the headers for the part currently being processed or %NULL if the headers failed to parse. a #SoupMultipartInputStream. Obtains an input stream for the next part. When dealing with a multipart response the input stream needs to be wrapped in a [class@MultipartInputStream] and this function or its async counterpart need to be called to obtain the first part for reading. After calling this function, [method@MultipartInputStream.get_headers] can be used to obtain the headers for the first part. A read of 0 bytes indicates the end of the part; a new call to this function should be done at that point, to obtain the next part. @error will only be set if an error happens during a read, %NULL is a valid return value otherwise. a new #GInputStream, or %NULL if there are no more parts the #SoupMultipartInputStream a #GCancellable Obtains a [class@Gio.InputStream] for the next request. See [method@MultipartInputStream.next_part] for details on the workflow. the #SoupMultipartInputStream. the I/O priority for the request. a #GCancellable. callback to call when request is satisfied. data for @callback Finishes an asynchronous request for the next part. a newly created [class@Gio.InputStream] for reading the next part or %NULL if there are no more parts. a #SoupMultipartInputStream. a #GAsyncResult. The [class@Message]. Represents a byte range as used in the Range header. If @end is non-negative, then @start and @end represent the bounds of of the range, counting from 0. (Eg, the first 500 bytes would be represented as @start = 0 and @end = 499.) If @end is -1 and @start is non-negative, then this represents a range starting at @start and ending with the last byte of the requested resource body. (Eg, all but the first 500 bytes would be @start = 500, and @end = -1.) If @end is -1 and @start is negative, then it represents a "suffix range", referring to the last -@start bytes of the resource body. (Eg, the last 500 bytes would be @start = -500 and @end = -1.) the start of the range the end of the range Tests if @status is a Client Error (4xx) response. an HTTP status code Tests if @status is an Informational (1xx) response. an HTTP status code Tests if @status is a Redirection (3xx) response. an HTTP status code Tests if @status is a Server Error (5xx) response. an HTTP status code Tests if @status is a Successful (2xx) response. an HTTP status code Represents the same-site policies of a cookie. The cookie is exposed with both cross-site and same-site requests The cookie is withheld on cross-site requests but exposed on cross-site navigations The cookie is only exposed for same-site requests [class@Server] provides a basic implementation of an HTTP server. The recommended usage of this server is for internal use, tasks like a mock server for tests, a private service for IPC, etc. It is not recommended to be exposed to untrusted clients as it may be vulnerable to denial of service attacks or other exploits. To begin, create a server using [ctor@Server.new]. Add at least one handler by calling [method@Server.add_handler] or [method@Server.add_early_handler]; the handler will be called to process any requests underneath the path you pass. (If you want all requests to go to the same handler, just pass "/" (or %NULL) for the path.) When a new connection is accepted (or a new request is started on an existing persistent connection), the [class@Server] will emit [signal@Server::request-started] and then begin processing the request as described below, but note that once the message is assigned a status-code, then callbacks after that point will be skipped. Note also that it is not defined when the callbacks happen relative to various [class@ServerMessage] signals. Once the headers have been read, [class@Server] will check if there is a [class@AuthDomain] `(qv)` covering the Request-URI; if so, and if the message does not contain suitable authorization, then the [class@AuthDomain] will set a status of %SOUP_STATUS_UNAUTHORIZED on the message. After checking for authorization, [class@Server] will look for "early" handlers (added with [method@Server.add_early_handler]) matching the Request-URI. If one is found, it will be run; in particular, this can be used to connect to signals to do a streaming read of the request body. (At this point, if the request headers contain `Expect: 100-continue`, and a status code has been set, then [class@Server] will skip the remaining steps and return the response. If the request headers contain `Expect: 100-continue` and no status code has been set, [class@Server] will return a %SOUP_STATUS_CONTINUE status before continuing.) The server will then read in the response body (if present). At this point, if there are no handlers at all defined for the Request-URI, then the server will return %SOUP_STATUS_NOT_FOUND to the client. Otherwise (assuming no previous step assigned a status to the message) any "normal" handlers (added with [method@Server.add_handler]) for the message's Request-URI will be run. Then, if the path has a WebSocket handler registered (and has not yet been assigned a status), [class@Server] will attempt to validate the WebSocket handshake, filling in the response and setting a status of %SOUP_STATUS_SWITCHING_PROTOCOLS or %SOUP_STATUS_BAD_REQUEST accordingly. If the message still has no status code at this point (and has not been paused with [method@ServerMessage.pause]), then it will be given a status of %SOUP_STATUS_INTERNAL_SERVER_ERROR (because at least one handler ran, but returned without assigning a status). Finally, the server will emit [signal@Server::request-finished] (or [signal@Server::request-aborted] if an I/O error occurred before handling was completed). If you want to handle the special "*" URI (eg, "OPTIONS *"), you must explicitly register a handler for "*"; the default handler will not be used for that case. If you want to process https connections in addition to (or instead of) http connections, you can set the [property@Server:tls-certificate] property. Once the server is set up, make one or more calls to [method@Server.listen], [method@Server.listen_local], or [method@Server.listen_all] to tell it where to listen for connections. (All ports on a [class@Server] use the same handlers; if you need to handle some ports differently, such as returning different data for http and https, you'll need to create multiple [class@Server]s, or else check the passed-in URI in the handler function.). [class@Server] will begin processing connections as soon as you return to (or start) the main loop for the current thread-default [struct@GLib.MainContext]. Creates a new [class@Server]. This is exactly equivalent to calling [ctor@GObject.Object.new] and specifying %SOUP_TYPE_SERVER as the type. a new #SoupServer. If you are using certain legacy properties, this may also return %NULL if an error occurs. name of first property to set value of @optname1, followed by additional property/value pairs Adds a new client stream to the @server. %TRUE on success, %FALSE if the stream could not be accepted or any other error occurred (in which case @error will be set). a #SoupServer a #GIOStream the local #GSocketAddress associated with the @stream the remote #GSocketAddress associated with the @stream Adds an authentication domain to @server. Each auth domain will have the chance to require authentication for each request that comes in; normally auth domains will require authentication for requests on certain paths that they have been set up to watch, or that meet other criteria set by the caller. If an auth domain determines that a request requires authentication (and the request doesn't contain authentication), @server will automatically reject the request with an appropriate status (401 Unauthorized or 407 Proxy Authentication Required). If the request used the SoupServer:100-continue Expectation, @server will reject it before the request body is sent. a #SoupServer a #SoupAuthDomain Adds an "early" handler to @server for requests prefixed by @path. Note that "normal" and "early" handlers are matched up together, so if you add a normal handler for "/foo" and an early handler for "/foo/bar", then a request to "/foo/bar" (or any path below it) will run only the early handler. (But if you add both handlers at the same path, then both will get run.) For requests under @path (that have not already been assigned a status code by a [class@AuthDomain] or a signal handler), @callback will be invoked after receiving the request headers, but before receiving the request body; the message's method and request-headers properties will be set. Early handlers are generally used for processing requests with request bodies in a streaming fashion. If you determine that the request will contain a message body, normally you would call [method@MessageBody.set_accumulate] on the message's request-body to turn off request-body accumulation, and connect to the message's [signal@ServerMessage::got-chunk] signal to process each chunk as it comes in. To complete the message processing after the full message body has been read, you can either also connect to [signal@ServerMessage::got-body], or else you can register a non-early handler for @path as well. As long as you have not set the status-code by the time [signal@ServerMessage::got-body] is emitted, the non-early handler will be run as well. a #SoupServer the toplevel path for the handler callback to invoke for requests under @path data for @callback destroy notifier to free @user_data Adds a handler to @server for requests prefixed by @path. If @path is %NULL or "/", then this will be the default handler for all requests that don't have a more specific handler. (Note though that if you want to handle requests to the special "*" URI, you must explicitly register a handler for "*"; the default handler will not be used for that case.) For requests under @path (that have not already been assigned a status code by a [class@AuthDomain], an early server handler, or a signal handler), @callback will be invoked after receiving the request body; the [class@ServerMessage]'s method, request-headers, and request-body properties will be set. After determining what to do with the request, the callback must at a minimum call [method@ServerMessage.set_status] on the message to set the response status code. Additionally, it may set response headers and/or fill in the response body. If the callback cannot fully fill in the response before returning (eg, if it needs to wait for information from a database, or another network server), it should call [method@ServerMessage.pause] to tell @server to not send the response right away. When the response is ready, call [method@ServerMessage.unpause] to cause it to be sent. To send the response body a bit at a time using "chunked" encoding, first call [method@MessageHeaders.set_encoding] to set %SOUP_ENCODING_CHUNKED on the response-headers. Then call [method@MessageBody.append] (or [method@MessageBody.append_bytes])) to append each chunk as it becomes ready, and [method@ServerMessage.unpause] to make sure it's running. (The server will automatically pause the message if it is using chunked encoding but no more chunks are available.) When you are done, call [method@MessageBody.complete] to indicate that no more chunks are coming. a #SoupServer the toplevel path for the handler callback to invoke for requests under @path data for @callback destroy notifier to free @user_data Add support for a WebSocket extension of the given @extension_type. When a WebSocket client requests an extension of @extension_type, a new [class@WebsocketExtension] of type @extension_type will be created to handle the request. Note that [class@WebsocketExtensionDeflate] is supported by default, use [method@Server.remove_websocket_extension] if you want to disable it. a #SoupServer a #GType Adds a WebSocket handler to @server for requests prefixed by @path. If @path is %NULL or "/", then this will be the default handler for all requests that don't have a more specific handler. When a path has a WebSocket handler registered, @server will check incoming requests for WebSocket handshakes after all other handlers have run (unless some earlier handler has already set a status code on the message), and update the request's status, response headers, and response body accordingly. If @origin is non-%NULL, then only requests containing a matching "Origin" header will be accepted. If @protocols is non-%NULL, then only requests containing a compatible "Sec-WebSocket-Protocols" header will be accepted. More complicated requirements can be handled by adding a normal handler to @path, and having it perform whatever checks are needed and setting a failure status code if the handshake should be rejected. a #SoupServer the toplevel path for the handler the origin of the connection the protocols supported by this handler callback to invoke for successful WebSocket requests under @path data for @callback destroy notifier to free @user_data Closes and frees @server's listening sockets. Note that if there are currently requests in progress on @server, that they will continue to be processed if @server's [struct@GLib.MainContext] is still running. You can call [method@Server.listen], etc, after calling this function if you want to start listening again. a #SoupServer Gets @server's list of listening sockets. You should treat these sockets as read-only; writing to or modifiying any of these sockets may cause @server to malfunction. a list of listening sockets. a #SoupServer Gets the @server SSL/TLS client authentication mode. a #GTlsAuthenticationMode a #SoupServer Gets the @server SSL/TLS certificate. a #GTlsCertificate or %NULL a #SoupServer Gets the @server SSL/TLS database. a #GTlsDatabase a #SoupServer Gets a list of URIs corresponding to the interfaces @server is listening on. These will contain IP addresses, not hostnames, and will also indicate whether the given listener is http or https. Note that if you used [method@Server.listen_all] the returned URIs will use the addresses `0.0.0.0` and `::`, rather than actually returning separate URIs for each interface on the system. a list of [struct@GLib.Uri], which you must free with each element with [method@GLib.Uri.unref] when you are done with it. a #SoupServer Checks whether @server is capable of https. In order for a server to run https, you must call [method@Server.set_tls_certificate], or set the [property@Server:tls-certificate] property, to provide it with a certificate to use. If you are using the deprecated single-listener APIs, then a return value of %TRUE indicates that the [class@Server] serves https exclusively. If you are using [method@Server.listen], etc, then a %TRUE return value merely indicates that the server is *able* to do https, regardless of whether it actually currently is or not. Use [method@Server.get_uris] to see if it currently has any https listeners. %TRUE if @server is configured to serve https. a #SoupServer Attempts to set up @server to listen for connections on @address. If @options includes %SOUP_SERVER_LISTEN_HTTPS, and @server has been configured for TLS, then @server will listen for https connections on this port. Otherwise it will listen for plain http. You may call this method (along with the other "listen" methods) any number of times on a server, if you want to listen on multiple ports, or set up both http and https service. After calling this method, @server will begin accepting and processing connections as soon as the appropriate [struct@GLib.MainContext] is run. Note that this API does not make use of dual IPv4/IPv6 sockets; if @address is an IPv6 address, it will only accept IPv6 connections. You must configure IPv4 listening separately. %TRUE on success, %FALSE if @address could not be bound or any other error occurred (in which case @error will be set). a #SoupServer the address of the interface to listen on listening options for this server Attempts to set up @server to listen for connections on all interfaces on the system. That is, it listens on the addresses `0.0.0.0` and/or `::`, depending on whether @options includes %SOUP_SERVER_LISTEN_IPV4_ONLY, %SOUP_SERVER_LISTEN_IPV6_ONLY, or neither.) If @port is specified, @server will listen on that port. If it is 0, @server will find an unused port to listen on. (In that case, you can use [method@Server.get_uris] to find out what port it ended up choosing. See [method@Server.listen] for more details. %TRUE on success, %FALSE if @port could not be bound or any other error occurred (in which case @error will be set). a #SoupServer the port to listen on, or 0 listening options for this server Attempts to set up @server to listen for connections on "localhost". That is, `127.0.0.1` and/or `::1`, depending on whether @options includes %SOUP_SERVER_LISTEN_IPV4_ONLY, %SOUP_SERVER_LISTEN_IPV6_ONLY, or neither). If @port is specified, @server will listen on that port. If it is 0, @server will find an unused port to listen on. (In that case, you can use [method@Server.get_uris] to find out what port it ended up choosing. See [method@Server.listen] for more details. %TRUE on success, %FALSE if @port could not be bound or any other error occurred (in which case @error will be set). a #SoupServer the port to listen on, or 0 listening options for this server Attempts to set up @server to listen for connections on @socket. See [method@Server.listen] for more details. %TRUE on success, %FALSE if an error occurred (in which case @error will be set). a #SoupServer a listening #GSocket listening options for this server Pauses I/O on @msg. This can be used when you need to return from the server handler without having the full response ready yet. Use [method@Server.unpause_message] to resume I/O. This must only be called on a [class@ServerMessage] which was created by the [class@Server] and are currently doing I/O, such as those passed into a [callback@ServerCallback] or emitted in a [signal@Server::request-read] signal. Use soup_server_message_pause() instead. a #SoupServer a #SoupServerMessage associated with @server. Removes @auth_domain from @server. a #SoupServer a #SoupAuthDomain Removes all handlers (early and normal) registered at @path. a #SoupServer the toplevel path for the handler Removes support for WebSocket extension of type @extension_type (or any subclass of @extension_type) from @server. a #SoupServer a #GType Sets @server's #GTlsAuthenticationMode to use for SSL/TLS client authentication. a #SoupServer a #GTlsAuthenticationMode Sets @server up to do https, using the given SSL/TLS @certificate. a #SoupServer a #GTlsCertificate Sets @server's #GTlsDatabase to use for validating SSL/TLS client certificates. a #SoupServer a #GTlsDatabase Resumes I/O on @msg. Use this to resume after calling [method@Server.pause_message], or after adding a new chunk to a chunked response. I/O won't actually resume until you return to the main loop. This must only be called on a [class@ServerMessage] which was created by the [class@Server] and are currently doing I/O, such as those passed into a [callback@ServerCallback] or emitted in a [signal@Server::request-read] signal. Use soup_server_message_unpause() instead. a #SoupServer a #SoupServerMessage associated with @server. If %TRUE, percent-encoding in the Request-URI path will not be automatically decoded. Server header. If non-%NULL, the value to use for the "Server" header on [class@ServerMessage]s processed by this server. The Server header is the server equivalent of the User-Agent header, and provides information about the server and its components. It contains a list of one or more product tokens, separated by whitespace, with the most significant product token coming first. The tokens must be brief, ASCII, and mostly alphanumeric (although "-", "_", and "." are also allowed), and may optionally include a "/" followed by a version string. You may also put comments, enclosed in parentheses, between or after the tokens. Some HTTP server implementations intentionally do not use version numbers in their Server header, so that installations running older versions of the server don't end up advertising their vulnerability to specific security holes. As with [property@Session:user_agent], if you set a [property@Server:server-header] property that has trailing whitespace, [class@Server] will append its own product token (eg, `libsoup/2.3.2`) to the end of the header for you. A [enum@Gio.TlsAuthenticationMode] for SSL/TLS client authentication. A [class@Gio.TlsCertificate[] that has a [property@Gio.TlsCertificate:private-key] set. If this is set, then the server will be able to speak https in addition to (or instead of) plain http. A [class@Gio.TlsDatabase] to use for validating SSL/TLS client certificates. Emitted when processing has failed for a message. This could mean either that it could not be read (if [signal@Server::request-read] has not been emitted for it yet), or that the response could not be written back (if [signal@Server::request-read] has been emitted but [signal@Server::request-finished] has not been). @message is in an undefined state when this signal is emitted; the signal exists primarily to allow the server to free any state that it may have allocated in [signal@Server::request-started]. the message Emitted when the server has finished writing a response to a request. the message Emitted when the server has successfully read a request. @message will have all of its request-side information filled in, and if the message was authenticated, @client will have information about that. This signal is emitted before any (non-early) handlers are called for the message, and if it sets the message's #status_code, then normal handler processing will be skipped. the message Emitted when the server has started reading a new request. @message will be completely blank; not even the Request-Line will have been read yet. About the only thing you can usefully do with it is connect to its signals. If the request is read successfully, this will eventually be followed by a [signal@Server::request_read signal]. If a response is then sent, the request processing will end with a [signal@Server::request-finished] signal. If a network error occurs, the processing will instead end with [signal@Server::request-aborted]. the new message A callback used to handle requests to a [class@Server]. @path and @query contain the likewise-named components of the Request-URI, subject to certain assumptions. By default, [class@Server] decodes all percent-encoding in the URI path, such that `"/foo%2Fbar"` is treated the same as `"/foo/bar"`. If your server is serving resources in some non-POSIX-filesystem namespace, you may want to distinguish those as two distinct paths. In that case, you can set the [property@Server:raw-paths] property when creating the [class@Server], and it will leave those characters undecoded. @query contains the query component of the Request-URI parsed according to the rules for HTML form handling. Although this is the only commonly-used query string format in HTTP, there is nothing that actually requires that HTTP URIs use that format; if your server needs to use some other format, you can just ignore @query, and call [method@Message.get_uri] and parse the URI's query field yourself. See [method@Server.add_handler] and [method@Server.add_early_handler] for details of what handlers can/should do. the #SoupServer the message being processed the path component of @msg's Request-URI the parsed query component of @msg's Request-URI the data passed to [method@Server.add_handler] or [method@Server.add_early_handler]. Options to pass to [method@Server.listen], etc. %SOUP_SERVER_LISTEN_IPV4_ONLY and %SOUP_SERVER_LISTEN_IPV6_ONLY only make sense with [method@Server.listen_all] and [method@Server.listen_local], not plain [method@Server.listen] (which simply listens on whatever kind of socket you give it). And you cannot specify both of them in a single call. Listen for https connections rather than plain http. Only listen on IPv4 interfaces. Only listen on IPv6 interfaces. An HTTP server request and response pair. A [class@ServerMessage] represents an HTTP message that is being sent or received on a [class@Server]. [class@Server] will create [class@ServerMessage]s automatically for incoming requests, which your application will receive via handlers. Note that libsoup's terminology here does not quite match the HTTP specification: in RFC 2616, an "HTTP-message" is *either* a Request, *or* a Response. In libsoup, a [class@ServerMessage] combines both the request and the response. Get the HTTP version of @msg. a #SoupHTTPVersion. a #SoupServerMessage Retrieves the [class@Gio.SocketAddress] associated with the local end of a connection. the #GSocketAddress associated with the local end of a connection, it may be %NULL if you used [method@Server.accept_iostream]. a #SoupServerMessage Get the HTTP method of @msg. the HTTP method. a #SoupServerMessage Get the HTTP reason phrase of @msg. the reason phrase. a #SoupServerMessage: Retrieves the [class@Gio.SocketAddress] associated with the remote end of a connection. the #GSocketAddress associated with the remote end of a connection, it may be %NULL if you used [method@Server.accept_iostream]. a #SoupServerMessage Retrieves the IP address associated with the remote end of a connection. the IP address associated with the remote end of a connection, it may be %NULL if you used [method@Server.accept_iostream]. a #SoupServerMessage Get the request body of @msg. a #SoupMessageBody. a #SoupServerMessage Get the request headers of @msg. a #SoupMessageHeaders with the request headers. a #SoupServerMessage Get the response body of @msg. a #SoupMessageBody. a #SoupServerMessage Get the response headers of @msg. a #SoupMessageHeaders with the response headers. a #SoupServerMessage Retrieves the [class@Gio.Socket] that @msg is associated with. If you are using this method to observe when multiple requests are made on the same persistent HTTP connection (eg, as the ntlm-test test program does), you will need to pay attention to socket destruction as well (eg, by using weak references), so that you do not get fooled when the allocator reuses the memory address of a previously-destroyed socket to represent a new socket. the #GSocket that @msg is associated with, %NULL if you used [method@Server.accept_iostream]. a #SoupServerMessage Get the HTTP status code of @msg. the HTTP status code. a #SoupServerMessage Gets the peer's #GTlsCertificate associated with @msg's connection. Note that this is not set yet during the emission of SoupServerMessage::accept-certificate signal. @msg's TLS peer certificate, or %NULL if @msg's connection is not SSL. a #SoupMessage Gets the errors associated with validating @msg's TLS peer certificate. Note that this is not set yet during the emission of SoupServerMessage::accept-certificate signal. a #GTlsCertificateFlags with @msg's TLS peer certificate errors. a #SoupMessage Get @msg's URI. a #GUri a #SoupServerMessage Gets if @msg represents an OPTIONS message with the path `*`. %TRUE if is an OPTIONS ping a #SoupServerMessage Pauses I/O on @msg. This can be used when you need to return from the server handler without having the full response ready yet. Use [method@ServerMessage.unpause] to resume I/O. a SoupServerMessage Set the HTTP version of @msg. a #SoupServerMessage a #SoupHTTPVersion Sets @msg's status_code to @status_code and adds a Location header pointing to @redirect_uri. Use this from a [class@Server] when you want to redirect the client to another URI. @redirect_uri can be a relative URI, in which case it is interpreted relative to @msg's current URI. In particular, if @redirect_uri is just a path, it will replace the path *and query* of @msg's URI. a #SoupServerMessage a 3xx status code the URI to redirect @msg to Convenience function to set the response body of a [class@ServerMessage]. If @content_type is %NULL, the response body must be empty as well. the message MIME Content-Type of the body a #SoupMemoryUse describing how to handle @resp_body a data buffer containing the body of the message response. the byte length of @resp_body. Sets @msg's status code to @status_code. If @status_code is a known value and @reason_phrase is %NULL, the reason_phrase will be set automatically. a #SoupServerMessage an HTTP status code a reason phrase "Steals" the HTTP connection associated with @msg from its [class@Server]. This happens immediately, regardless of the current state of the connection; if the response to @msg has not yet finished being sent, then it will be discarded; you can steal the connection from a [signal@ServerMessage::wrote-informational] or [signal@ServerMessage::wrote-body] signal handler if you need to wait for part or all of the response to be sent. Note that when calling this function from C, @msg will most likely be freed as a side effect. the #GIOStream formerly associated with @msg (or %NULL if @msg was no longer associated with a connection). No guarantees are made about what kind of #GIOStream is returned. a #SoupServerMessage Resumes I/O on @msg. Use this to resume after calling [method@ServerMessage.pause], or after adding a new chunk to a chunked response. I/O won't actually resume until you return to the main loop. a SoupServerMessage The peer's #GTlsCertificate associated with the message The verification errors on [property@ServerMessage:tls-peer-certificate] Emitted during the @msg's connection TLS handshake after client TLS certificate has been received. You can return %TRUE to accept @tls_certificate despite @tls_errors. %TRUE to accept the TLS certificate and stop other handlers from being invoked, or %FALSE to propagate the event further. the peer's #GTlsCertificate the tls errors of @tls_certificate Emitted when the @msg's socket is connected and the TLS handshake completed. Emitted when the @msg's socket is disconnected. Emitted when all HTTP processing is finished for a message. (After [signal@ServerMessage::wrote-body]). Emitted after receiving the complete request body. Emitted after receiving a chunk of a message body. Note that "chunk" in this context means any subpiece of the body, not necessarily the specific HTTP 1.1 chunks sent by the other side. the just-read chunk Emitted after receiving the Request-Line and request headers. Emitted immediately after writing the complete response body for a message. Emitted immediately after writing a portion of the message body to the network. the number of bytes written Emitted immediately after writing a body chunk for a message. Note that this signal is not parallel to [signal@ServerMessage::got-chunk]; it is emitted only when a complete chunk (added with [method@MessageBody.append] or [method@MessageBody.append_bytes] has been written. To get more useful continuous progress information, use [signal@ServerMessage::wrote-body-data]. Emitted immediately after writing the response headers for a message. Emitted immediately after writing a 1xx (Informational) response. A callback used to handle WebSocket requests to a [class@Server]. The callback will be invoked after sending the handshake response back to the client (and is only invoked if the handshake was successful). @path contains the path of the Request-URI, subject to the same rules as [callback@ServerCallback] `(qv)`. the #SoupServer the #SoupServerMessage the path component of @msg's Request-URI the newly created WebSocket connection the data passed to @soup_server_add_handler Soup session state object. [class@Session] is the object that controls client-side HTTP. A [class@Session] encapsulates all of the state that libsoup is keeping on behalf of your program; cached HTTP connections, authentication information, etc. It also keeps track of various global options and features that you are using. Most applications will only need a single [class@Session]; the primary reason you might need multiple sessions is if you need to have multiple independent authentication contexts. (Eg, you are connecting to a server and authenticating as two different users at different times; the easiest way to ensure that each [class@Message] is sent with the authentication information you intended is to use one session for the first user, and a second session for the other user.) Additional [class@Session] functionality is provided by [iface@SessionFeature] objects, which can be added to a session with [method@Session.add_feature] or [method@Session.add_feature_by_type] For example, [class@Logger] provides support for logging HTTP traffic, [class@ContentDecoder] provides support for compressed response handling, and [class@ContentSniffer] provides support for HTML5-style response body content sniffing. Additionally, subtypes of [class@Auth] can be added as features, to add support for additional authentication types. All `SoupSession`s are created with a [class@AuthManager], and support for %SOUP_TYPE_AUTH_BASIC and %SOUP_TYPE_AUTH_DIGEST. Additionally, sessions using the plain [class@Session] class (rather than one of its deprecated subtypes) have a [class@ContentDecoder] by default. Note that all async methods will invoke their callbacks on the thread-default context at the time of the function call. Creates a [class@Session] with the default options. the new session. Creates a [class@Session] with the specified options. the new session. name of first property to set value of @optname1, followed by additional property/value pairs Cancels all pending requests in @session and closes all idle persistent connections. the session Adds @feature's functionality to @session. You cannot add multiple features of the same [alias@GObject.Type] to a session. See the main [class@Session] documentation for information on what features are present in sessions by default. a #SoupSession an object that implements #SoupSessionFeature If @feature_type is the type of a class that implements [iface@SessionFeature], this creates a new feature of that type and adds it to @session as with [method@Session.add_feature]. You can use this when you don't need to customize the new feature in any way. Adding multiple features of the same @feature_type is not allowed. If @feature_type is not a [iface@SessionFeature] type, this gives each existing feature on @session the chance to accept @feature_type as a "subfeature". This can be used to add new [class@Auth] types, for instance. See the main [class@Session] documentation for information on what features are present in sessions by default. a #SoupSession a #GType Get the value used by @session for the "Accept-Language" header on new requests. the accept language string a #SoupSession Gets whether @session automatically sets the "Accept-Language" header on new requests. %TRUE if @session sets "Accept-Language" header automatically, or %FALSE otherwise. a #SoupSession Gets the [class@Message] of the @result asynchronous operation This is useful to get the [class@Message] of an asynchronous operation started by @session from its [callback@Gio.AsyncReadyCallback]. a #SoupMessage or %NULL if @result is not a valid @session async operation result. a #SoupSession the #GAsyncResult passed to your callback Gets the feature in @session of type @feature_type. a #SoupSessionFeature, or %NULL. The feature is owned by @session. a #SoupSession the #GType of the feature to get Gets the feature in @session of type @feature_type, provided that it is not disabled for @msg. a #SoupSessionFeature. The feature is owned by @session. a #SoupSession the #GType of the feature to get a #SoupMessage Get the timeout in seconds for idle connection lifetime currently used by @session. the timeout in seconds a #SoupSession Get the [class@Gio.InetSocketAddress] to use for the client side of connections in @session. a #GInetSocketAddress a #SoupSession Get the maximum number of connections that @session can open at once. the maximum number of connections a #SoupSession Get the maximum number of connections that @session can open at once to a given host. the maximum number of connections per host a #SoupSession Get the [iface@Gio.ProxyResolver] currently used by @session. a #GProxyResolver or %NULL if proxies are disabled in @session a #SoupSession Gets the remote connectable if one set. the #GSocketConnectable a #SoupSession Get the timeout in seconds for socket I/O operations currently used by @session. the timeout in seconds a #SoupSession Get the [class@Gio.TlsDatabase] currently used by @session. a #GTlsDatabase a #SoupSession Get the [class@Gio.TlsInteraction] currently used by @session. a #GTlsInteraction a #SoupSession Get the value used by @session for the "User-Agent" header on new requests. the user agent string a #SoupSession Tests if @session has at a feature of type @feature_type (which can be the type of either a [iface@SessionFeature], or else a subtype of some class managed by another feature, such as [class@Auth]). %TRUE or %FALSE a #SoupSession the #GType of the class of features to check for Start a preconnection to @msg. Once the connection is done, it will remain in idle state so that it can be reused by future requests. If there's already an idle connection for the given @msg host, the operation finishes successfully without creating a new connection. If a new request for the given @msg host is made while the preconnect is still ongoing, the request will take the ownership of the connection and the preconnect operation will finish successfully (if there's a connection error it will be handled by the request). The operation finishes when the connection is done or an error occurred. a #SoupSession a #SoupMessage the I/O priority of the request a #GCancellable the callback to invoke when the operation finishes data for @progress_callback and @callback Complete a preconnect async operation started with [method@Session.preconnect_async]. %TRUE if the preconnect succeeded, or %FALSE in case of error. a #SoupSession the #GAsyncResult passed to your callback Removes @feature's functionality from @session. a #SoupSession a feature that has previously been added to @session Removes all features of type @feature_type (or any subclass of @feature_type) from @session. a #SoupSession a #GType Synchronously sends @msg and waits for the beginning of a response. On success, a [class@Gio.InputStream] will be returned which you can use to read the response body. ("Success" here means only that an HTTP response was received and understood; it does not necessarily mean that a 2xx class status code was received.) If non-%NULL, @cancellable can be used to cancel the request; [method@Session.send] will return a %G_IO_ERROR_CANCELLED error. Note that with requests that have side effects (eg, `POST`, `PUT`, `DELETE`) it is possible that you might cancel the request after the server acts on it, but before it returns a response, leaving the remote resource in an unknown state. If @msg is requeued due to a redirect or authentication, the initial (`3xx/401/407`) response body will be suppressed, and [method@Session.send] will only return once a final response has been received. Possible error domains include [error@SessionError], [error@Gio.IOErrorEnum], and [error@Gio.TlsError] which you may want to specifically handle. a #GInputStream for reading the response body, or %NULL on error. a #SoupSession a #SoupMessage a #GCancellable Synchronously sends @msg and reads the response body. On success, a [struct@GLib.Bytes] will be returned with the response body. This function should only be used when the resource to be retrieved is not too long and can be stored in memory. See [method@Session.send] for more details on the general semantics. a #GBytes, or %NULL on error. a #SoupSession a #SoupMessage a #GCancellable Asynchronously sends @msg and reads the response body. When @callback is called, then either @msg has been sent, and its response body read, or else an error has occurred. This function should only be used when the resource to be retrieved is not too long and can be stored in memory. Call [method@Session.send_and_read_finish] to get a [struct@GLib.Bytes] with the response body. See [method@Session.send] for more details on the general semantics. a #SoupSession a #SoupMessage the I/O priority of the request a #GCancellable the callback to invoke data for @callback Gets the response to a [method@Session.send_and_read_async]. If successful, returns a [struct@GLib.Bytes] with the response body. a #GBytes, or %NULL on error. a #SoupSession the #GAsyncResult passed to your callback Synchronously sends @msg and splices the response body stream into @out_stream. See [method@Session.send] for more details on the general semantics. a #gssize containing the size of the data spliced, or -1 if an error occurred. a #SoupSession a #SoupMessage a #GOutputStream a set of #GOutputStreamSpliceFlags a #GCancellable Asynchronously sends @msg and splices the response body stream into @out_stream. When @callback is called, then either @msg has been sent and its response body spliced, or else an error has occurred. See [method@Session.send] for more details on the general semantics. a #SoupSession a #SoupMessage a #GOutputStream a set of #GOutputStreamSpliceFlags the I/O priority of the request a #GCancellable the callback to invoke data for @callback Gets the response to a [method@Session.send_and_splice_async]. a #gssize containing the size of the data spliced, or -1 if an error occurred. a #SoupSession the #GAsyncResult passed to your callback Asynchronously sends @msg and waits for the beginning of a response. When @callback is called, then either @msg has been sent, and its response headers received, or else an error has occurred. Call [method@Session.send_finish] to get a [class@Gio.InputStream] for reading the response body. See [method@Session.send] for more details on the general semantics. a #SoupSession a #SoupMessage the I/O priority of the request a #GCancellable the callback to invoke data for @callback Gets the response to a [method@Session.send_async] call. If successful returns a [class@Gio.InputStream] that can be used to read the response body. a #GInputStream for reading the response body, or %NULL on error. a #SoupSession the #GAsyncResult passed to your callback Set the value to use for the "Accept-Language" header on [class@Message]s sent from @session. If @accept_language is %NULL then no "Accept-Language" will be included in requests. See [property@Session:accept-language] for more information. a #SoupSession the languages string Set whether @session will automatically set the "Accept-Language" header on requests using a value generated from system languages based on [func@GLib.get_language_names]. See [property@Session:accept-language-auto] for more information. a #SoupSession the value to set Set a timeout in seconds for idle connection lifetime to be used by @session on new connections. See [property@Session:idle-timeout] for more information. a #SoupSession a timeout in seconds Set a [iface@Gio.ProxyResolver] to be used by @session on new connections. If @proxy_resolver is %NULL then no proxies will be used. See [property@Session:proxy-resolver] for more information. a #SoupSession a #GProxyResolver or %NULL Set a timeout in seconds for socket I/O operations to be used by @session on new connections. See [property@Session:timeout] for more information. a #SoupSession a timeout in seconds Set a [class@Gio.TlsDatabase] to be used by @session on new connections. If @tls_database is %NULL then certificate validation will always fail. See [property@Session:tls-database] for more information. a #SoupSession a #GTlsDatabase Set a [class@Gio.TlsInteraction] to be used by @session on new connections. If @tls_interaction is %NULL then client certificate validation will always fail. See [property@Session:tls-interaction] for more information. a #SoupSession a #GTlsInteraction Set the value to use for the "User-Agent" header on [class@Message]s sent from @session. If @user_agent has trailing whitespace, @session will append its own product token (eg, `libsoup/3.0.0`) to the end of the header for you. If @user_agent is %NULL then no "User-Agent" will be included in requests. See [property@Session:user-agent] for more information. a #SoupSession the user agent string Asynchronously creates a [class@WebsocketConnection] to communicate with a remote server. All necessary WebSocket-related headers will be added to @msg, and it will then be sent and asynchronously processed normally (including handling of redirection and HTTP authentication). If the server returns "101 Switching Protocols", then @msg's status code and response headers will be updated, and then the WebSocket handshake will be completed. On success, [method@Session.websocket_connect_finish] will return a new [class@WebsocketConnection]. On failure it will return a #GError. If the server returns a status other than "101 Switching Protocols", then @msg will contain the complete response headers and body from the server's response, and [method@Session.websocket_connect_finish] will return %SOUP_WEBSOCKET_ERROR_NOT_WEBSOCKET. a #SoupSession #SoupMessage indicating the WebSocket server to connect to origin of the connection a %NULL-terminated array of protocols supported the I/O priority of the request a #GCancellable the callback to invoke data for @callback Gets the [class@WebsocketConnection] response to a [method@Session.websocket_connect_async] call. If successful, returns a [class@WebsocketConnection] that can be used to communicate with the server. a new #SoupWebsocketConnection, or %NULL on error. a #SoupSession the #GAsyncResult passed to your callback If non-%NULL, the value to use for the "Accept-Language" header on [class@Message]s sent from this session. Setting this will disable [property@Session:accept-language-auto]. If %TRUE, [class@Session] will automatically set the string for the "Accept-Language" header on every [class@Message] sent, based on the return value of [func@GLib.get_language_names]. Setting this will override any previous value of [property@Session:accept-language]. Connection lifetime (in seconds) when idle. Any connection left idle longer than this will be closed. Although you can change this property at any time, it will only affect newly-created connections, not currently-open ones. You can call [method@Session.abort] after setting this if you want to ensure that all future connections will have this timeout value. Sets the [class@Gio.InetSocketAddress] to use for the client side of the connection. Use this property if you want for instance to bind the local socket to a specific IP address. The maximum number of connections that the session can open at once. The maximum number of connections that the session can open at once to a given host. A [iface@Gio.ProxyResolver] to use with this session. If no proxy resolver is set, then the default proxy resolver will be used. See [func@Gio.ProxyResolver.get_default]. You can set it to %NULL if you don't want to use proxies, or set it to your own [iface@Gio.ProxyResolver] if you want to control what proxies get used. Sets a socket to make outgoing connections on. This will override the default behaviour of opening TCP/IP sockets to the hosts specified in the URIs. This function is not required for common HTTP usage, but only when connecting to a HTTP service that is not using standard TCP/IP sockets. An example of this is a local service that uses HTTP over UNIX-domain sockets, in that case a [class@Gio.UnixSocketAddress] can be passed to this function. The timeout (in seconds) for socket I/O operations (including connecting to a server, and waiting for a reply to an HTTP request). Although you can change this property at any time, it will only affect newly-created connections, not currently-open ones. You can call [method@Session.abort] after setting this if you want to ensure that all future connections will have this timeout value. Not to be confused with [property@Session:idle-timeout] (which is the length of time that idle persistent connections will be kept open). Sets the [class@Gio.TlsDatabase] to use for validating SSL/TLS certificates. If no certificate database is set, then the default database will be used. See [method@Gio.TlsBackend.get_default_database]. A [class@Gio.TlsInteraction] object that will be passed on to any [class@Gio.TlsConnection]s created by the session. This can be used to provide client-side certificates, for example. User-Agent string. If non-%NULL, the value to use for the "User-Agent" header on [class@Message]s sent from this session. RFC 2616 says: "The User-Agent request-header field contains information about the user agent originating the request. This is for statistical purposes, the tracing of protocol violations, and automated recognition of user agents for the sake of tailoring responses to avoid particular user agent limitations. User agents SHOULD include this field with requests." The User-Agent header contains a list of one or more product tokens, separated by whitespace, with the most significant product token coming first. The tokens must be brief, ASCII, and mostly alphanumeric (although "-", "_", and "." are also allowed), and may optionally include a "/" followed by a version string. You may also put comments, enclosed in parentheses, between or after the tokens. If you set a [property@Session:user-agent] property that has trailing whitespace, [class@Session] will append its own product token (eg, `libsoup/2.3.2`) to the end of the header for you. Emitted when a request is queued on @session. When sending a request, first [signal@Session::request-queued] is emitted, indicating that the session has become aware of the request. After a connection is available to send the request various [class@Message] signals are emitted as the message is processed. If the message is requeued, it will emit [signal@Message::restarted], which will then be followed by other [class@Message] signals when the message is re-sent. Eventually, the message will emit [signal@Message::finished]. Normally, this signals the completion of message processing. However, it is possible that the application will requeue the message from the "finished" handler. In that case the process will loop back. Eventually, a message will reach "finished" and not be requeued. At that point, the session will emit [signal@Session::request-unqueued] to indicate that it is done with the message. To sum up: [signal@Session::request-queued] and [signal@Session::request-unqueued] are guaranteed to be emitted exactly once, but [signal@Message::finished] (and all of the other [class@Message] signals) may be invoked multiple times for a given message. the request that was queued Emitted when a request is removed from @session's queue, indicating that @session is done with it. See [signal@Session::request-queued] for a detailed description of the message lifecycle within a session. the request that was unqueued A [class@Session] error. the server's response could not be parsed the server's response was in an unsupported format the message has been redirected too many times the message has been restarted too many times failed to redirect message because Location header was missing or empty in response failed to redirect message because Location header contains an invalid URI the message is already in the session queue. Messages can only be reused after unqueued. Registers error quark for SoupSession if needed. Error quark for SoupSession. Interface for miscellaneous [class@Session] features. [iface@SessionFeature] is the interface used by classes that extend the functionality of a [class@Session]. Some features like HTTP authentication handling are implemented internally via [iface@SessionFeature]s. Other features can be added to the session by the application. (Eg, [class@Logger], [class@CookieJar].) See [method@Session.add_feature], etc, to add a feature to a session. The interface implemented by [iface@SessionFeature]s. These represent the known HTTP status code values, plus various network and internal errors. Note that no libsoup functions take or return this type directly; any function that works with status codes will accept unrecognized status codes as well. No status available. (Eg, the message has not been sent yet) 100 Continue (HTTP) 101 Switching Protocols (HTTP) 102 Processing (WebDAV) 200 Success (HTTP). Also used by many lower-level soup routines to indicate success. 201 Created (HTTP) 202 Accepted (HTTP) 203 Non-Authoritative Information (HTTP) 204 No Content (HTTP) 205 Reset Content (HTTP) 206 Partial Content (HTTP) 207 Multi-Status (WebDAV) 300 Multiple Choices (HTTP) 301 Moved Permanently (HTTP) 302 Found (HTTP) 302 Moved Temporarily (old name, RFC 2068) 303 See Other (HTTP) 304 Not Modified (HTTP) 305 Use Proxy (HTTP) 306 [Unused] (HTTP) 307 Temporary Redirect (HTTP) 308 Permanent Redirect (HTTP) 400 Bad Request (HTTP) 401 Unauthorized (HTTP) 402 Payment Required (HTTP) 403 Forbidden (HTTP) 404 Not Found (HTTP) 405 Method Not Allowed (HTTP) 406 Not Acceptable (HTTP) 407 Proxy Authentication Required (HTTP) shorter alias for %SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED 408 Request Timeout (HTTP) 409 Conflict (HTTP) 410 Gone (HTTP) 411 Length Required (HTTP) 412 Precondition Failed (HTTP) 413 Request Entity Too Large (HTTP) 414 Request-URI Too Long (HTTP) 415 Unsupported Media Type (HTTP) 416 Requested Range Not Satisfiable (HTTP) shorter alias for %SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE 417 Expectation Failed (HTTP) 421 Misdirected Request 422 Unprocessable Entity (WebDAV) 423 Locked (WebDAV) 424 Failed Dependency (WebDAV) 500 Internal Server Error (HTTP) 501 Not Implemented (HTTP) 502 Bad Gateway (HTTP) 503 Service Unavailable (HTTP) 504 Gateway Timeout (HTTP) 505 HTTP Version Not Supported (HTTP) 507 Insufficient Storage (WebDAV) 510 Not Extended (RFC 2774) Looks up the stock HTTP description of @status_code. *There is no reason for you to ever use this function.* If you wanted the textual description for the [property@Message:status-code] of a given [class@Message], you should just look at the message's [property@Message:reason-phrase]. However, you should only do that for use in debugging messages; HTTP reason phrases are not localized, and are not generally very descriptive anyway, and so they should never be presented to the user directly. Instead, you should create you own error messages based on the status code, and on what you were trying to do. the (terse, English) description of @status_code an HTTP status code Error codes for %SOUP_TLD_ERROR. A hostname was syntactically invalid. The passed-in "hostname" was actually an IP address (and thus has no base domain or public suffix). The passed-in hostname did not have enough components. Eg, calling [func@tld_get_base_domain] on <literal>"co.uk"</literal>. The passed-in hostname has no recognized public suffix. The Public Suffix List was not available. Registers error quark for soup_tld_get_base_domain() if needed. Error quark for Soup TLD functions. Marks a symbol unavailable before the given major and minor version. You should use `SOUP_AVAILABLE_IN_*` in order to handle versioning. the major version that introduced the symbol the minor version that introduced the symbol Enum values passed to [func@uri_copy] to indicate the components of the URI that should be updated with the given values. no component the URI scheme component the URI user component the URI password component the URI authentication parameters component the URI host component the URI port component the URI path component the URI query component the URI fragment component A macro that should be defined by the user prior to including `libsoup.h`. The definition should be one of the predefined libsoup version macros: %SOUP_VERSION_2_24, %SOUP_VERSION_2_26, ... This macro defines the earliest version of libsoup that the package is required to be able to compile against. If the compiler is configured to warn about the use of deprecated functions, then using functions that were deprecated in version %SOUP_VERSION_MIN_REQUIRED or earlier will cause warnings (but using functions deprecated in later releases will not). Pre-defined close codes that can be passed to [method@WebsocketConnection.close] or received from [method@WebsocketConnection.get_close_code]. However, other codes are also allowed. a normal, non-error close the client/server is going away a protocol error occurred the endpoint received data of a type that it does not support. reserved value indicating that no close code was present; must not be sent. reserved value indicating that the connection was closed abnormally; must not be sent. the endpoint received data that was invalid (eg, non-UTF-8 data in a text message). generic error code indicating some sort of policy violation. the endpoint received a message that is too big to process. the client is closing the connection because the server failed to negotiate a required extension. the server is closing the connection because it was unable to fulfill the request. reserved value indicating that the TLS handshake failed; must not be sent. The WebSocket Protocol Provides support for the [WebSocket](http://tools.ietf.org/html/rfc6455) protocol. To connect to a WebSocket server, create a [class@Session] and call [method@Session.websocket_connect_async]. To accept WebSocket connections, create a [class@Server] and add a handler to it with [method@Server.add_websocket_handler]. (Lower-level support is available via [func@websocket_client_prepare_handshake] and [func@websocket_client_verify_handshake], for handling the client side of the WebSocket handshake, and [func@websocket_server_process_handshake] for handling the server side.) [class@WebsocketConnection] handles the details of WebSocket communication. You can use [method@WebsocketConnection.send_text] and [method@WebsocketConnection.send_binary] to send data, and the [signal@WebsocketConnection::message] signal to receive data. ([class@WebsocketConnection] currently only supports asynchronous I/O.) Creates a [class@WebsocketConnection] on @stream with the given active @extensions. This should be called after completing the handshake to begin using the WebSocket protocol. a new #SoupWebsocketConnection a #GIOStream connected to the WebSocket server the URI of the connection the type of connection (client/side) the Origin of the client the subprotocol in use a #GList of #SoupWebsocketExtension objects Close the connection in an orderly fashion. Note that until the [signal@WebsocketConnection::closed] signal fires, the connection is not yet completely closed. The close message is not even sent until the main loop runs. The @code and @data are sent to the peer along with the close request. If @code is %SOUP_WEBSOCKET_CLOSE_NO_STATUS a close message with no body (without code and data) is sent. Note that the @data must be UTF-8 valid. the WebSocket close code close data Get the close code received from the WebSocket peer. This only becomes valid once the WebSocket is in the %SOUP_WEBSOCKET_STATE_CLOSED state. The value will often be in the [enum@WebsocketCloseCode] enumeration, but may also be an application defined close code. the close code or zero. the WebSocket Get the close data received from the WebSocket peer. This only becomes valid once the WebSocket is in the %SOUP_WEBSOCKET_STATE_CLOSED state. The data may be freed once the main loop is run, so copy it if you need to keep it around. the close data or %NULL the WebSocket Get the connection type (client/server) of the connection. the connection type the WebSocket Get the extensions chosen via negotiation with the peer. a #GList of #SoupWebsocketExtension objects the WebSocket Get the I/O stream the WebSocket is communicating over. the WebSocket's I/O stream. the WebSocket Gets the keepalive interval in seconds or 0 if disabled. the keepalive interval. the WebSocket Gets the keepalive pong timeout in seconds or 0 if disabled. the keepalive pong timeout. the WebSocket Gets the maximum payload size allowed for incoming packets. the maximum payload size. the WebSocket Gets the maximum total message size allowed for packets. the maximum total message size. the WebSocket Get the origin of the WebSocket. the origin the WebSocket Get the protocol chosen via negotiation with the peer. the chosen protocol the WebSocket Get the current state of the WebSocket. the state the WebSocket Get the URI of the WebSocket. For servers this represents the address of the WebSocket, and for clients it is the address connected to. the URI the WebSocket Send a binary message to the peer. If @length is 0, @data may be %NULL. The message is queued to be sent and will be sent when the main loop is run. the WebSocket the message contents the length of @data Send a message of the given @type to the peer. Note that this method, allows to send text messages containing %NULL characters. The message is queued to be sent and will be sent when the main loop is run. the WebSocket the type of message contents the message data as #GBytes Send a %NULL-terminated text (UTF-8) message to the peer. If you need to send text messages containing %NULL characters use [method@WebsocketConnection.send_message] instead. The message is queued to be sent and will be sent when the main loop is run. the WebSocket the message contents Sets the interval in seconds on when to send a ping message which will serve as a keepalive message. If set to 0 the keepalive message is disabled. the WebSocket the interval to send a ping message or 0 to disable it Set the timeout in seconds for when the absence of a pong from a keepalive ping is assumed to be caused by a faulty connection. If set to 0 then the absence of pongs from keepalive pings is ignored. the WebSocket the timeout in seconds Sets the maximum payload size allowed for incoming packets. It does not limit the outgoing packet size. the WebSocket the maximum payload size Sets the maximum total message size allowed for packets. It does not limit the outgoing packet size. the WebSocket the maximum total message size The type of connection (client/server). List of [class@WebsocketExtension] objects that are active in the connection. The underlying IO stream the WebSocket is communicating over. The input and output streams must be pollable streams. Interval in seconds on when to send a ping message which will serve as a keepalive message. If set to 0 the keepalive message is disabled. Timeout in seconds for when the absence of a pong from a keepalive ping is assumed to be caused by a faulty connection. The WebSocket will be transitioned to a closed state when this happens. If set to 0 then the absence of pongs from keepalive pings is ignored. The maximum payload size for incoming packets, or 0 to not limit it. Each message may consist of multiple packets, so also refer to [property@WebsocketConnection:max-total-message-size]. The maximum size for incoming messages. Set to a value to limit the total message size, or 0 to not limit it. [method@Server.add_websocket_handler] will set this to a nonzero default value to mitigate denial of service attacks. Clients must choose their own default if they need to mitigate denial of service attacks. You also need to set your own default if creating your own server SoupWebsocketConnection without using SoupServer. Each message may consist of multiple packets, so also refer to [property@WebsocketConnection:max-incoming-payload-size]. The client's Origin. The chosen protocol, or %NULL if a protocol was not agreed upon. The current state of the WebSocket. The URI of the WebSocket. For servers this represents the address of the WebSocket, and for clients it is the address connected to. Emitted when the connection has completely closed. This happens either due to an orderly close from the peer, one initiated via [method@WebsocketConnection.close] or a fatal error condition that caused a close. This signal will be emitted once. This signal will be emitted during an orderly close. Emitted when an error occurred on the WebSocket. This may be fired multiple times. Fatal errors will be followed by the [signal@WebsocketConnection::closed] signal being emitted. the error that occured Emitted when we receive a message from the peer. As a convenience, the @message data will always be %NULL-terminated, but the NUL byte will not be included in the length count. the type of message contents the message data Emitted when we receive a Pong frame (solicited or unsolicited) from the peer. As a convenience, the @message data will always be %NULL-terminated, but the NUL byte will not be included in the length count. the application data (if any) The abstract base class for [class@WebsocketConnection]. The type of a [class@WebsocketConnection]. unknown/invalid connection a client-side connection a server-side connection The type of data contained in a [signal@WebsocketConnection::message] signal. UTF-8 text binary data WebSocket-related errors. a generic error attempted to handshake with a server that does not appear to understand WebSockets. the WebSocket handshake failed because some detail was invalid (eg, incorrect accept key). the WebSocket handshake failed because the "Origin" header was not an allowed value. Registers error quark for SoupWebsocket if needed. Error quark for SoupWebsocket. A WebSocket extension [class@WebsocketExtension] is the base class for WebSocket extension objects. Configures @extension with the given @params. %TRUE if extension could be configured with the given parameters, or %FALSE otherwise a #SoupWebsocketExtension either %SOUP_WEBSOCKET_CONNECTION_CLIENT or %SOUP_WEBSOCKET_CONNECTION_SERVER the parameters Get the parameters strings to be included in the request header. If the extension doesn't include any parameter in the request, this function returns %NULL. a new allocated string with the parameters a #SoupWebsocketExtension Get the parameters strings to be included in the response header. If the extension doesn't include any parameter in the response, this function returns %NULL. a new allocated string with the parameters a #SoupWebsocketExtension Process a message after it's received. If the payload isn't changed the given @payload is just returned, otherwise [method@GLib.Bytes.unref] is called on the given @payload and a new [struct@GLib.Bytes] is returned with the new data. Extensions using reserved bits of the header will reset them in @header. the message payload data, or %NULL in case of error a #SoupWebsocketExtension the message header the payload data Process a message before it's sent. If the payload isn't changed the given @payload is just returned, otherwise [method@Glib.Bytes.unref] is called on the given @payload and a new [struct@GLib.Bytes] is returned with the new data. Extensions using reserved bits of the header will change them in @header. the message payload data, or %NULL in case of error a #SoupWebsocketExtension the message header the payload data Configures @extension with the given @params. %TRUE if extension could be configured with the given parameters, or %FALSE otherwise a #SoupWebsocketExtension either %SOUP_WEBSOCKET_CONNECTION_CLIENT or %SOUP_WEBSOCKET_CONNECTION_SERVER the parameters Get the parameters strings to be included in the request header. If the extension doesn't include any parameter in the request, this function returns %NULL. a new allocated string with the parameters a #SoupWebsocketExtension Get the parameters strings to be included in the response header. If the extension doesn't include any parameter in the response, this function returns %NULL. a new allocated string with the parameters a #SoupWebsocketExtension Process a message after it's received. If the payload isn't changed the given @payload is just returned, otherwise [method@GLib.Bytes.unref] is called on the given @payload and a new [struct@GLib.Bytes] is returned with the new data. Extensions using reserved bits of the header will reset them in @header. the message payload data, or %NULL in case of error a #SoupWebsocketExtension the message header the payload data Process a message before it's sent. If the payload isn't changed the given @payload is just returned, otherwise [method@Glib.Bytes.unref] is called on the given @payload and a new [struct@GLib.Bytes] is returned with the new data. Extensions using reserved bits of the header will change them in @header. the message payload data, or %NULL in case of error a #SoupWebsocketExtension the message header the payload data The class structure for the [class@WebsocketExtension]. the parent class the name of the extension called to configure the extension with the given parameters %TRUE if extension could be configured with the given parameters, or %FALSE otherwise a #SoupWebsocketExtension either %SOUP_WEBSOCKET_CONNECTION_CLIENT or %SOUP_WEBSOCKET_CONNECTION_SERVER the parameters called by the client to build the request header. It should include the parameters string starting with ';' a new allocated string with the parameters a #SoupWebsocketExtension called by the server to build the response header. It should include the parameters string starting with ';' a new allocated string with the parameters a #SoupWebsocketExtension called to process the payload data of a message before it's sent. Reserved bits of the header should be changed. the message payload data, or %NULL in case of error a #SoupWebsocketExtension the message header the payload data called to process the payload data of a message after it's received. Reserved bits of the header should be cleared. the message payload data, or %NULL in case of error a #SoupWebsocketExtension the message header the payload data A SoupWebsocketExtensionDeflate is a [class@WebsocketExtension] implementing permessage-deflate (RFC 7692). This extension is used by default in a [class@Session] when [class@WebsocketExtensionManager] feature is present, and always used by [class@Server]. SoupWebsocketExtensionManager is the [iface@SessionFeature] that handles WebSockets extensions for a [class@Session]. A [class@WebsocketExtensionManager] is added to the session by default, and normally you don't need to worry about it at all. However, if you want to disable WebSocket extensions, you can remove the feature from the session with [method@Session.remove_feature_by_type] or disable it on individual requests with [method@Message.disable_feature]. The state of the WebSocket connection. the connection is ready to send messages the connection is in the process of closing down; messages may be received, but not sent the connection is completely closed down Like [func@CHECK_VERSION], but the check for soup_check_version is at runtime instead of compile time. This is useful for compiling against older versions of libsoup, but using features from newer versions. %TRUE if the version of the libsoup currently loaded is the same as or newer than the passed-in version. the major version to check the minor version to check the micro version to check Parses @header and returns a [struct@Cookie]. If @header contains multiple cookies, only the first one will be parsed. If @header does not have "path" or "domain" attributes, they will be defaulted from @origin. If @origin is %NULL, path will default to "/", but domain will be left as %NULL. Note that this is not a valid state for a [struct@Cookie], and you will need to fill in some appropriate string for the domain if you want to actually make use of the cookie. As of version 3.4.0 the default value of a cookie's same-site-policy is %SOUP_SAME_SITE_POLICY_LAX. a new #SoupCookie, or %NULL if it could not be parsed, or contained an illegal "domain" attribute for a cookie originating from @origin. a cookie string (eg, the value of a Set-Cookie header) origin of the cookie Frees @cookies. a #GSList of [struct@Cookie] Parses @msg's Cookie request header and returns a [struct@GLib.SList] of `SoupCookie`s. As the "Cookie" header, unlike "Set-Cookie", only contains cookie names and values, none of the other [struct@Cookie] fields will be filled in. (Thus, you can't generally pass a cookie returned from this method directly to [func@cookies_to_response].) a #GSList of `SoupCookie`s, which can be freed with [method@Cookie.free]. a #SoupMessage containing a "Cookie" request header Parses @msg's Set-Cookie response headers and returns a [struct@GLib.SList] of `SoupCookie`s. Cookies that do not specify "path" or "domain" attributes will have their values defaulted from @msg. a #GSList of `SoupCookie`s, which can be freed with [method@Cookie.free]. a #SoupMessage containing a "Set-Cookie" response header Serializes a [struct@GLib.SList] of [struct@Cookie] into a string suitable for setting as the value of the "Cookie" header. the serialization of @cookies a #GSList of [struct@Cookie] Adds the name and value of each cookie in @cookies to @msg's "Cookie" request. If @msg already has a "Cookie" request header, these cookies will be appended to the cookies already present. Be careful that you do not append the same cookies twice, eg, when requeuing a message. a #GSList of [struct@Cookie] a #SoupMessage Appends a "Set-Cookie" response header to @msg for each cookie in @cookies. This is in addition to any other "Set-Cookie" headers @msg may already have. a #GSList of [struct@Cookie] a #SoupMessage Parses @date_string and tries to extract a date from it. This recognizes all of the "HTTP-date" formats from RFC 2616, RFC 2822 dates, and reasonable approximations thereof. (Eg, it is lenient about whitespace, leading "0"s, etc.) a new #GDateTime, or %NULL if @date_string could not be parsed. The date as a string Converts @date to a string in the format described by @format. @date as a string or %NULL a #GDateTime the format to generate the date in Decodes @form. which is an urlencoded dataset as defined in the HTML 4.01 spec. a hash table containing the name/value pairs from @encoded_form, which you can free with [func@GLib.HashTable.destroy]. data of type "application/x-www-form-urlencoded" Decodes the "multipart/form-data" request in @multipart. this is a convenience method for the case when you have a single file upload control in a form. (Or when you don't have any file upload controls, but are still using "multipart/form-data" anyway.) Pass the name of the file upload control in @file_control_name, and [func@form_decode_multipart] will extract the uploaded file data into @filename, @content_type, and @file. All of the other form control data will be returned (as strings, as with [func@form_decode] in the returned [struct@GLib.HashTable]. You may pass %NULL for @filename, @content_type and/or @file if you do not care about those fields. [func@form_decode_multipart] may also return %NULL in those fields if the client did not provide that information. You must free the returned filename and content-type with [func@GLib.free], and the returned file data with [method@Glib.Bytes.unref]. If you have a form with more than one file upload control, you will need to decode it manually, using [ctor@Multipart.new_from_message] and [method@Multipart.get_part]. a hash table containing the name/value pairs (other than @file_control_name) from @msg, which you can free with [func@GLib.HashTable.destroy]. On error, it will return %NULL. a #SoupMultipart the name of the HTML file upload control return location for the name of the uploaded file return location for the MIME type of the uploaded file return location for the uploaded file data Encodes the given field names and values into a value of type "application/x-www-form-urlencoded". Encodes as defined in the HTML 4.01 spec. This method requires you to know the names of the form fields (or at the very least, the total number of fields) at compile time; for working with dynamic forms, use [func@form_encode_hash] or [func@form_encode_datalist]. See also: [ctor@Message.new_from_encoded_form]. the encoded form name of the first form field value of @first_field, followed by additional field names and values, terminated by %NULL. Encodes @form_data_set into a value of type "application/x-www-form-urlencoded". Encodes as defined in the HTML 4.01 spec. Unlike [func@form_encode_hash], this preserves the ordering of the form elements, which may be required in some situations. See also: [ctor@Message.new_from_encoded_form]. the encoded form a datalist containing name/value pairs Encodes @form_data_set into a value of type "application/x-www-form-urlencoded". Encodes as defined in the HTML 4.01 spec. Note that the HTML spec states that "The control names/values are listed in the order they appear in the document." Since this method takes a hash table, it cannot enforce that; if you care about the ordering of the form fields, use [func@form_encode_datalist]. See also: [ctor@Message.new_from_encoded_form]. the encoded form a hash table containing name/value pairs (as strings) See [func@form_encode]. This is mostly an internal method, used by various other methods such as [func@form_encode]. See also: [ctor@Message.new_from_encoded_form]. the encoded form name of the first form field pointer to additional values, as in [func@form_encode] Returns the major version number of the libsoup library. e.g. in libsoup version 2.42.0 this is 2. This function is in the library, so it represents the libsoup library your code is running against. Contrast with the #SOUP_MAJOR_VERSION macro, which represents the major version of the libsoup headers you have included when compiling your code. the major version number of the libsoup library Returns the micro version number of the libsoup library. e.g. in libsoup version 2.42.0 this is 0. This function is in the library, so it represents the libsoup library your code is running against. Contrast with the #SOUP_MICRO_VERSION macro, which represents the micro version of the libsoup headers you have included when compiling your code. the micro version number of the libsoup library Returns the minor version number of the libsoup library. e.g. in libsoup version 2.42.0 this is 42. This function is in the library, so it represents the libsoup library your code is running against. Contrast with the #SOUP_MINOR_VERSION macro, which represents the minor version of the libsoup headers you have included when compiling your code. the minor version number of the libsoup library Parses @header to see if it contains the token @token (matched case-insensitively). Note that this can't be used with lists that have qvalues. whether or not @header contains @token An HTTP header suitable for parsing with [func@header_parse_list] a token Parses @header to see if it contains the token @token (matched case-sensitively). Note that this can't be used with lists that have qvalues. whether or not @header contains @token An HTTP header suitable for parsing with [func@header_parse_list] a token Frees @list. a #GSList returned from [func@header_parse_list] or [func@header_parse_quality_list] Frees @param_list. a #GHashTable returned from [func@header_parse_param_list] or [func@header_parse_semi_param_list] Appends something like `name=value` to @string, taking care to quote @value if needed, and if so, to escape any quotes or backslashes in @value. Alternatively, if @value is a non-ASCII UTF-8 string, it will be appended using RFC5987 syntax. Although in theory this is supposed to work anywhere in HTTP that uses this style of parameter, in reality, it can only be used portably with the Content-Disposition "filename" parameter. If @value is %NULL, this will just append @name to @string. a #GString being used to construct an HTTP header value a parameter name a parameter value, or %NULL Appends something like `name="value"` to @string, taking care to escape any quotes or backslashes in @value. If @value is (non-ASCII) UTF-8, this will instead use RFC 5987 encoding, just like [func@header_g_string_append_param]. a #GString being used to construct an HTTP header value a parameter name a parameter value Parses a header whose content is described by RFC2616 as `#something`. "something" does not itself contain commas, except as part of quoted-strings. a #GSList of list elements, as allocated strings a header value Parses a header which is a comma-delimited list of something like: `token [ "=" ( token | quoted-string ) ]`. Tokens that don't have an associated value will still be added to the resulting hash table, but with a %NULL value. This also handles RFC5987 encoding (which in HTTP is mostly used for giving UTF8-encoded filenames in the Content-Disposition header). a #GHashTable of list elements, which can be freed with [func@header_free_param_list]. a header value A strict version of [func@header_parse_param_list] that bails out if there are duplicate parameters. Note that this function will treat RFC5987-encoded parameters as duplicated if an ASCII version is also present. For header fields that might contain RFC5987-encoded parameters, use [func@header_parse_param_list] instead. a #GHashTable of list elements, which can be freed with [func@header_free_param_list] or %NULL if there are duplicate elements. a header value Parses a header whose content is a list of items with optional "qvalue"s (eg, Accept, Accept-Charset, Accept-Encoding, Accept-Language, TE). If @unacceptable is not %NULL, then on return, it will contain the items with qvalue 0. Either way, those items will be removed from the main list. a #GSList of acceptable values (as allocated strings), highest-qvalue first. a header value on return, will contain a list of unacceptable values Parses a header which is a semicolon-delimited list of something like: `token [ "=" ( token | quoted-string ) ]`. Tokens that don't have an associated value will still be added to the resulting hash table, but with a %NULL value. This also handles RFC5987 encoding (which in HTTP is mostly used for giving UTF8-encoded filenames in the Content-Disposition header). a #GHashTable of list elements, which can be freed with [func@header_free_param_list]. a header value A strict version of [func@header_parse_semi_param_list] that bails out if there are duplicate parameters. Note that this function will treat RFC5987-encoded parameters as duplicated if an ASCII version is also present. For header fields that might contain RFC5987-encoded parameters, use [func@header_parse_semi_param_list] instead. a #GHashTable of list elements, which can be freed with [func@header_free_param_list] or %NULL if there are duplicate elements. a header value Parses the headers of an HTTP request or response in @str and stores the results in @dest. Beware that @dest may be modified even on failure. This is a low-level method; normally you would use [func@headers_parse_request] or [func@headers_parse_response]. success or failure the header string (including the Request-Line or Status-Line, but not the trailing blank line) length of @str #SoupMessageHeaders to store the header values in Parses the headers of an HTTP request in @str and stores the results in @req_method, @req_path, @ver, and @req_headers. Beware that @req_headers may be modified even on failure. %SOUP_STATUS_OK if the headers could be parsed, or an HTTP error to be returned to the client if they could not be. the headers (up to, but not including, the trailing blank line) length of @str #SoupMessageHeaders to store the header values in if non-%NULL, will be filled in with the request method if non-%NULL, will be filled in with the request path if non-%NULL, will be filled in with the HTTP version Parses the headers of an HTTP response in @str and stores the results in @ver, @status_code, @reason_phrase, and @headers. Beware that @headers may be modified even on failure. success or failure. the headers (up to, but not including, the trailing blank line) length of @str #SoupMessageHeaders to store the header values in if non-%NULL, will be filled in with the HTTP version if non-%NULL, will be filled in with the status code if non-%NULL, will be filled in with the reason phrase Parses the HTTP Status-Line string in @status_line into @ver, @status_code, and @reason_phrase. @status_line must be terminated by either "\0" or "\r\n". %TRUE if @status_line was parsed successfully. an HTTP Status-Line if non-%NULL, will be filled in with the HTTP version if non-%NULL, will be filled in with the status code if non-%NULL, will be filled in with the reason phrase Initializes @iter for iterating @hdrs. a pointer to a #SoupMessageHeadersIter structure a #SoupMessageHeaders Yields the next name/value pair in the [struct@MessageHeaders] being iterated by @iter. If @iter has already yielded the last header, then [func@MessageHeadersIter.next] will return %FALSE and @name and @value will be unchanged. %TRUE if another name and value were returned, %FALSE if the end of the headers has been reached. a #SoupMessageHeadersIter pointer to a variable to return the header name in pointer to a variable to return the header value in Registers error quark for SoupSession if needed. Error quark for SoupSession. soup-method.h contains a number of defines for standard HTTP and WebDAV headers. You do not need to use these defines; you can pass arbitrary strings to soup_message_new() if you prefer. The thing that these defines <emphasis>are</emphasis> useful for is performing quick comparisons against soup_message_get_method(); because [class@Message] always contains an interned string, and these macros return interned strings, you can compare methods directly against these macros rather than needing to use strcmp(). This is most useful in [class@Server] handlers. Eg: <informalexample><programlisting> if (soup_message_get_method (msg) != SOUP_METHOD_GET &amp;&amp; soup_message_get_method (msg) != SOUP_METHOD_HEAD) { soup_message_set_status (msg, SOUP_METHOD_NOT_IMPLEMENTED); return; } </programlisting></informalexample> Looks up the stock HTTP description of @status_code. *There is no reason for you to ever use this function.* If you wanted the textual description for the [property@Message:status-code] of a given [class@Message], you should just look at the message's [property@Message:reason-phrase]. However, you should only do that for use in debugging messages; HTTP reason phrases are not localized, and are not generally very descriptive anyway, and so they should never be presented to the user directly. Instead, you should create you own error messages based on the status code, and on what you were trying to do. the (terse, English) description of @status_code an HTTP status code Looks whether the @domain passed as argument is a public domain suffix (.org, .com, .co.uk, etc) or not. Prior to libsoup 2.46, this function required that @domain be in UTF-8 if it was an IDN. From 2.46 on, the name can be in either UTF-8 or ASCII format. %TRUE if it is a public domain, %FALSE otherwise. a domain name Registers error quark for soup_tld_get_base_domain() if needed. Error quark for Soup TLD functions. Finds the base domain for a given @hostname The base domain is composed by the top level domain (such as .org, .com, .co.uk, etc) plus the second level domain, for example for myhost.mydomain.com it will return mydomain.com. Note that %NULL will be returned for private URLs (those not ending with any well known TLD) because choosing a base domain for them would be totally arbitrary. Prior to libsoup 2.46, this function required that @hostname be in UTF-8 if it was an IDN. From 2.46 on, the name can be in either UTF-8 or ASCII format (and the return value will be in the same format). a pointer to the start of the base domain in @hostname. If an error occurs, %NULL will be returned and @error set. a hostname As of 3.4.0 this will detect the default ports of HTTP(s) and WS(S) URIs when copying and set it to the default port of the new scheme. So for example copying `http://localhost:80` while changing the scheme to https will result in `https://localhost:443`. Return a copy of @uri with the given components updated. a new #GUri the #GUri to copy first #SoupURIComponent to update value of @first_component followed by additional components and values, terminated by %SOUP_URI_NONE Decodes the given data URI and returns its contents and @content_type. a #GBytes with the contents of @uri, or %NULL if @uri is not a valid data URI a data URI, in string form location to store content type Tests whether or not @uri1 and @uri2 are equal in all parts. %TRUE if equal otherwise %FALSE a #GUri another #GUri Adds the necessary headers to @msg to request a WebSocket handshake including supported WebSocket extensions. The message body and non-WebSocket-related headers are not modified. This is a low-level function; if you use [method@Session.websocket_connect_async] to create a WebSocket connection, it will call this for you. a #SoupMessage the "Origin" header to set list of protocols to offer list of supported extension types Looks at the response status code and headers in @msg and determines if they contain a valid WebSocket handshake response (given the handshake request in @msg's request headers). If @supported_extensions is non-%NULL, extensions included in the response "Sec-WebSocket-Extensions" are verified too. Accepted extensions are returned in @accepted_extensions parameter if non-%NULL. This is a low-level function; if you use [method@Session.websocket_connect_async] to create a WebSocket connection, it will call this for you. %TRUE if @msg contains a completed valid WebSocket handshake, %FALSE and an error if not. #SoupMessage containing both client and server sides of a WebSocket handshake list of supported extension types a #GList of [class@WebsocketExtension] objects Registers error quark for SoupWebsocket if needed. Error quark for SoupWebsocket. Examines the method and request headers in @msg and determines whether @msg contains a valid handshake request. If @origin is non-%NULL, then only requests containing a matching "Origin" header will be accepted. If @protocols is non-%NULL, then only requests containing a compatible "Sec-WebSocket-Protocols" header will be accepted. If @supported_extensions is non-%NULL, then only requests containing valid supported extensions in "Sec-WebSocket-Extensions" header will be accepted. Normally [func@websocket_server_process_handshake] will take care of this for you, and if you use [method@Server.add_websocket_handler] to handle accepting WebSocket connections, it will call that for you. However, this function may be useful if you need to perform more complicated validation; eg, accepting multiple different Origins, or handling different protocols depending on the path. %TRUE if @msg contained a valid WebSocket handshake, %FALSE and an error if not. #SoupServerMessage containing the client side of a WebSocket handshake expected Origin header allowed WebSocket protocols. list of supported extension types Examines the method and request headers in @msg and (assuming @msg contains a valid handshake request), fills in the handshake response. If @expected_origin is non-%NULL, then only requests containing a matching "Origin" header will be accepted. If @protocols is non-%NULL, then only requests containing a compatible "Sec-WebSocket-Protocols" header will be accepted. If @supported_extensions is non-%NULL, then only requests containing valid supported extensions in "Sec-WebSocket-Extensions" header will be accepted. The accepted extensions will be returned in @accepted_extensions parameter if non-%NULL. This is a low-level function; if you use [method@Server.add_websocket_handler] to handle accepting WebSocket connections, it will call this for you. %TRUE if @msg contained a valid WebSocket handshake request and was updated to contain a handshake response. %FALSE if not. #SoupServerMessage containing the client side of a WebSocket handshake expected Origin header allowed WebSocket protocols. list of supported extension types a #GList of [class@WebsocketExtension] objects soup3-0.9.0/generator.py000075500000000000000000000171431046102023000132540ustar 00000000000000#!/usr/bin/env python3 from pathlib import Path import argparse import subprocess import sys import asyncio DEFAULT_GIR_FILES_DIRECTORY = Path("./gir-files") DEFAULT_GIR_DIRECTORY = Path("./gir/") # TODO: This is typically the directory _of this Python script_ (which external projects symlink to) def run_command(command, folder=None): return subprocess.run(command, cwd=folder, check=True) async def spawn_process(exe, args): p = await asyncio.create_subprocess_exec( str(exe), *(str(arg) for arg in args), stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, ) stdout, stderr = await p.communicate() stdout = stdout.decode("utf-8") stderr = stderr.decode("utf-8") assert p.returncode == 0, stderr.strip() return stdout, stderr async def spawn_gir(conf, args): if conf.gir_path: stdout, stderr = await spawn_process(conf.gir_path, args) else: cargo_args = ["run", "--release", "--quiet", "--manifest-path", DEFAULT_GIR_DIRECTORY / "Cargo.toml", "--"] stdout, stderr = await spawn_process("cargo", cargo_args + args) # Gir doesn't print anything to stdout. If it does, this is likely out of # order with stderr, unless the printer/logging flushes in between. assert not stdout, "`gir` printed unexpected stdout: {}".format(stdout) if stderr: return "===> stderr:\n\n" + stderr + "\n" return "" def ask_yes_no_question(question, conf): question = "{} [y/N] ".format(question) if conf.yes: print(question + "y") return True line = input(question) return line.strip().lower() == "y" def update_submodule(submodule_path, conf): if any(submodule_path.iterdir()): return False print("=> Initializing {} submodule...".format(submodule_path)) run_command(["git", "submodule", "update", "--init", submodule_path]) print("<= Done!") if ask_yes_no_question( "Do you want to update {} submodule?".format(submodule_path), conf ): print("=> Updating submodule...") run_command(["git", "reset", "--hard", "HEAD"], submodule_path) run_command(["git", "pull", "-f", "origin", "main"], submodule_path) print("<= Done!") return True return False async def regenerate_crate_docs(conf, crate_dir, base_gir_args): doc_path = "docs.md" # Generate into docs.md instead of the default vendor.md doc_args = base_gir_args + ["-m", "doc", "--doc-target-path", doc_path] # The above `gir -m doc` generates docs.md relative to the directory containing Gir.toml doc_path = crate_dir / doc_path embed_args = ["-m", "-d", crate_dir / "src"] logs = "" if conf.strip_docs: logs += "==> Stripping documentation from `{}`...\n".format(crate_dir) # -n dumps stripped docs to stdout _, stderr = await spawn_process("rustdoc-stripper", embed_args + ["-s", "-n"]) if stderr: logs += "===> stderr:\n\n" + stderr + "\n" if conf.embed_docs: logs += "==> Regenerating documentation for `{}` into `{}`...\n".format( crate_dir, doc_path ) logs += await spawn_gir(conf, doc_args) logs += "==> Embedding documentation from `{}` into `{}`...\n".format( doc_path, crate_dir ) stdout, stderr = await spawn_process( "rustdoc-stripper", embed_args + ["-g", "-o", doc_path] ) if stdout: logs += "===> stdout:\n\n" + stdout + "\n" if stderr: logs += "===> stderr:\n\n" + stderr + "\n" return logs def regen_crates(path, conf): processes = [] if path.is_dir(): for entry in path.rglob("Gir*.toml"): processes += regen_crates(entry, conf) elif path.match("Gir*.toml"): args = ["-c", path, "-o", path.parent] + [ d for path in conf.gir_files_paths for d in ("-d", path) ] is_sys_crate = path.parent.name.endswith("sys") if conf.embed_docs or conf.strip_docs: # Embedding documentation only applies to non-sys crates if is_sys_crate: return processes processes.append(regenerate_crate_docs(conf, path.parent, args)) else: if is_sys_crate: args.extend(["-m", "sys"]) async def regenerate_crate(path, args): return "==> Regenerating `{}`...\n".format(path) + await spawn_gir( conf, args ) processes.append(regenerate_crate(path, args)) else: raise Exception("`{}` is not a valid Gir*.toml file".format(path)) return processes def valid_path(path): path = Path(path) if not path.exists(): raise argparse.ArgumentTypeError("`{}` no such file or directory".format(path)) return path def directory_path(path): path = Path(path) if not path.is_dir(): raise argparse.ArgumentTypeError("`{}` directory not found".format(path)) return path def file_path(path): path = Path(path) if not path.is_file(): raise argparse.ArgumentTypeError("`{}` file not found".format(path)) return path def parse_args(): parser = argparse.ArgumentParser( description="Helper to regenerate gtk-rs crates using gir.", formatter_class=argparse.ArgumentDefaultsHelpFormatter, ) parser.add_argument( "path", nargs="*", default=[Path(".")], type=valid_path, help="Paths in which to look for Gir.toml files", ) parser.add_argument( "--gir-files-directories", nargs="+", # If the option is used, we expect at least one folder! dest="gir_files_paths", default=[], type=directory_path, help="Path of the gir-files folder", ) parser.add_argument( "--gir-path", type=file_path, help="Path of the gir executable to run", ) parser.add_argument( "--yes", action="store_true", help=" Always answer `yes` to any question asked by the script", ) parser.add_argument( "--no-fmt", action="store_true", help="If set, this script will not run `cargo fmt`", ) parser.add_argument( "--embed-docs", action="store_true", help="Build documentation with `gir -m doc`, and embed it with `rustdoc-stripper -g`", ) parser.add_argument( "--strip-docs", action="store_true", help="Remove documentation with `rustdoc-stripper -s -n`. Can be used in conjunction with --embed-docs", ) return parser.parse_args() async def main(): conf = parse_args() if not conf.gir_files_paths: update_submodule(DEFAULT_GIR_FILES_DIRECTORY, conf) if conf.gir_path is None: update_submodule(DEFAULT_GIR_DIRECTORY, conf) print("=> Building gir...") run_command(["cargo", "build", "--release", "--manifest-path", DEFAULT_GIR_DIRECTORY / "Cargo.toml"]) print("<= Done!") print("=> Regenerating crates...") for path in conf.path: print("=> Looking in path `{}`".format(path)) # Collect and print the results as soon as they trickle in, one process at a time: for coro in asyncio.as_completed(regen_crates(path, conf)): print(await coro, end="") if not conf.no_fmt and not run_command(["cargo", "fmt"]): return 1 print("<= Done!") print("Don't forget to check if everything has been correctly generated!") return 0 if __name__ == "__main__": try: asyncio.run(main()) except Exception as e: print("Error: {}".format(e), file=sys.stderr) sys.exit(1) soup3-0.9.0/gir-files/.github/FUNDING.yml000064400000000000000000000000301046102023000157320ustar 00000000000000open_collective: gtk-rs soup3-0.9.0/gir-files/.github/dependabot.yml000064400000000000000000000003771046102023000167630ustar 00000000000000# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates version: 2 updates: - package-ecosystem: "github-actions" directory: "/" # Location of package manifests schedule: interval: "weekly" soup3-0.9.0/gir-files/.github/workflows/CI.yml000064400000000000000000000014031046102023000171750ustar 00000000000000on: push: branches: - main - create-pull-request/patch pull_request: branches: - main - create-pull-request/patch name: CI jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: actions-rs/toolchain@v1 with: toolchain: stable override: true - uses: actions/checkout@v6 with: repository: gtk-rs/gir ref: main path: gir - uses: actions/checkout@v6 with: repository: gtk-rs/gtk4-rs ref: main path: gtk4-rs - working-directory: gir run: cargo build --release - run: './gir/target/release/gir -c gtk4-rs/gtk4/sys/Gir.toml -m sys -o gtk4-rs/gtk4/sys/ -d .' soup3-0.9.0/gir-files/.github/workflows/auto-merge.yml000064400000000000000000000022661046102023000207570ustar 00000000000000name: Auto Merge PRs from github-actions[bot] on: pull_request: types: [opened, synchronize, labeled] jobs: auto-merge: runs-on: ubuntu-latest if: github.event.pull_request.user.login == 'github-actions[bot]' permissions: contents: read pull-requests: write statuses: read steps: - name: Wait for all required status checks run: | echo "Waiting for all required status checks to pass..." for i in {1..60}; do STATUS=$(gh api repos/${{ github.repository }}/commits/${{ github.event.pull_request.head.sha }}/status --jq '.state') echo "Current status: $STATUS" if [[ "$STATUS" == "success" ]]; then echo "All checks passed!" break elif [[ "$STATUS" == "failure" ]]; then echo "Some checks failed. Exiting." exit 1 fi sleep 10 done env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Merge PR using gh CLI run: gh pr merge ${{ github.event.pull_request.html_url }} --merge --admin --delete-branch env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} soup3-0.9.0/gir-files/.github/workflows/auto-update.yml000064400000000000000000000007251046102023000211400ustar 00000000000000name: Trigger Repository Dispatch on: workflow_dispatch: push: branches: - main jobs: dispatch: strategy: matrix: repo: ['gtk-rs/gtk4-rs', 'gtk-rs/gtk-rs-core'] runs-on: ubuntu-latest steps: - name: Send Repository Dispatch Event uses: peter-evans/repository-dispatch@v4 with: token: ${{ secrets.TOKEN_PAT }} repository: ${{ matrix.repo }} event-type: internal-merge-event soup3-0.9.0/gir-files/.github/workflows/regenerate_scheduled.yml000064400000000000000000000030651046102023000230510ustar 00000000000000name: Redownload & regenerate (weekly) on: schedule: - cron: '0 0 * * 0' workflow_dispatch: jobs: regenerate: name: Regenerate GIR files runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v6 with: token: ${{ secrets.GITHUB_TOKEN }} - name: Redownload, regenerate, reformat id: changes env: GITLAB_KEY: ${{ secrets.GITLAB_KEY }} run: | sudo apt-get -q update sudo apt-get -q upgrade sudo apt-get -q install binutils wget tar xmlstarlet podman python3-requests python3-gitlab podman pull ghcr.io/gtk-rs/gtk4-rs/gtk4:latest podman run --rm -v "$(pwd)":/app -w /app ghcr.io/gtk-rs/gtk4-rs/gtk4:latest python3 dl.py ./dl-win32.sh python3 ./dl-gtk-macos.py ./reformat.sh && ./fix.sh echo ::set-output name=pr_title::"Update GIR files ($(date +%Y-%m-%d))" echo ::set-output name=pr_body::"This PR was auto-generated on $(date +%Y-%m-%d). Please review and manually edit before merging." - name: Create PR id: cpr uses: peter-evans/create-pull-request@v8 with: commit-message: Update GIR files title: ${{ steps.changes.outputs.pr_title }} body: ${{ steps.changes.outputs.pr_body }} delete-branch: true - name: Review PR run: | echo "Opened PR #${{ steps.cpr.outputs.pull-request-number }} (${{ steps.cpr.outputs.pull-request-url }}) — ${{ steps.changes.outputs.pr_title }}" soup3-0.9.0/gir-files/.gitignore000064400000000000000000000000271046102023000145530ustar 00000000000000*.rnc .vscode .DS_Storesoup3-0.9.0/gir-files/Atk-1.0.gir000064400000000000000000031374751046102023000143260ustar 00000000000000 This is a singly-linked list (a #GSList) of #AtkAttribute. It is used by atk_text_get_run_attributes(), atk_text_get_default_attributes(), atk_editable_text_set_run_attributes(), atk_document_get_attributes() and atk_object_get_attributes() An AtkState describes a single state of an object. An AtkState describes a single state of an object. The full set of states that apply to an object at a given time are contained in its #AtkStateSet. See [id@atk_object_ref_state_set] and [id@atk_object_notify_state_change] The ATK interface provided by UI components which the user can activate/interact with. #AtkAction should be implemented by instances of #AtkObject classes with which the user can interact directly, i.e. buttons, checkboxes, scrollbars, e.g. components which are not "passive" providers of UI information. Exceptions: when the user interaction is already covered by another appropriate interface such as #AtkEditableText (insert/delete text, etc.) or #AtkValue (set value) then these actions should not be exposed by #AtkAction as well. Though most UI interactions on components should be invocable via keyboard as well as mouse, there will generally be a close mapping between "mouse actions" that are possible on a component and the AtkActions. Where mouse and keyboard actions are redundant in effect, #AtkAction should expose only one action rather than exposing redundant actions if possible. By convention we have been using "mouse centric" terminology for #AtkAction names. Perform the specified action on the object. %TRUE if success, %FALSE otherwise a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed Returns a description of the specified action of the object. a description string, or %NULL if @action does not implement this interface. a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed Gets the keybinding which can be used to activate this action, if one exists. The string returned should contain localized, human-readable, key sequences as they would appear when displayed on screen. It must be in the format "mnemonic;sequence;shortcut". - The mnemonic key activates the object if it is presently enabled onscreen. This typically corresponds to the underlined letter within the widget. Example: "n" in a traditional "New..." menu item or the "a" in "Apply" for a button. - The sequence is the full list of keys which invoke the action even if the relevant element is not currently shown on screen. For instance, for a menu item the sequence is the keybindings used to open the parent menus before invoking. The sequence string is colon-delimited. Example: "Alt+F:N" in a traditional "New..." menu item. - The shortcut, if it exists, will invoke the same action without showing the component or its enclosing menus or dialogs. Example: "Ctrl+N" in a traditional "New..." menu item. Example: For a traditional "New..." menu item, the expected return value would be: "N;Alt+F:N;Ctrl+N" for the English locale and "N;Alt+D:N;Strg+N" for the German locale. If, hypothetically, this menu item lacked a mnemonic, it would be represented by ";;Ctrl+N" and ";;Strg+N" respectively. the keybinding which can be used to activate this action, or %NULL if there is no keybinding for this action. a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed Returns the localized name of the specified action of the object. a name string, or %NULL if @action does not implement this interface. a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed Gets the number of accessible actions available on the object. If there are more than one, the first one is considered the "default" action of the object. a the number of actions, or 0 if @action does not implement this interface. a #GObject instance that implements AtkActionIface Returns a non-localized string naming the specified action of the object. This name is generally not descriptive of the end result of the action, but instead names the 'interaction type' which the object supports. By convention, the above strings should be used to represent the actions which correspond to the common point-and-click interaction techniques of the same name: i.e. "click", "press", "release", "drag", "drop", "popup", etc. The "popup" action should be used to pop up a context menu for the object, if one exists. For technical reasons, some toolkits cannot guarantee that the reported action is actually 'bound' to a nontrivial user event; i.e. the result of some actions via atk_action_do_action() may be NIL. a name string, or %NULL if @action does not implement this interface. a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed Sets a description of the specified action of the object. a gboolean representing if the description was successfully set; a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed the description to be assigned to this action Perform the specified action on the object. %TRUE if success, %FALSE otherwise a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed Returns a description of the specified action of the object. a description string, or %NULL if @action does not implement this interface. a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed Gets the keybinding which can be used to activate this action, if one exists. The string returned should contain localized, human-readable, key sequences as they would appear when displayed on screen. It must be in the format "mnemonic;sequence;shortcut". - The mnemonic key activates the object if it is presently enabled onscreen. This typically corresponds to the underlined letter within the widget. Example: "n" in a traditional "New..." menu item or the "a" in "Apply" for a button. - The sequence is the full list of keys which invoke the action even if the relevant element is not currently shown on screen. For instance, for a menu item the sequence is the keybindings used to open the parent menus before invoking. The sequence string is colon-delimited. Example: "Alt+F:N" in a traditional "New..." menu item. - The shortcut, if it exists, will invoke the same action without showing the component or its enclosing menus or dialogs. Example: "Ctrl+N" in a traditional "New..." menu item. Example: For a traditional "New..." menu item, the expected return value would be: "N;Alt+F:N;Ctrl+N" for the English locale and "N;Alt+D:N;Strg+N" for the German locale. If, hypothetically, this menu item lacked a mnemonic, it would be represented by ";;Ctrl+N" and ";;Strg+N" respectively. the keybinding which can be used to activate this action, or %NULL if there is no keybinding for this action. a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed Returns the localized name of the specified action of the object. a name string, or %NULL if @action does not implement this interface. a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed Gets the number of accessible actions available on the object. If there are more than one, the first one is considered the "default" action of the object. a the number of actions, or 0 if @action does not implement this interface. a #GObject instance that implements AtkActionIface Returns a non-localized string naming the specified action of the object. This name is generally not descriptive of the end result of the action, but instead names the 'interaction type' which the object supports. By convention, the above strings should be used to represent the actions which correspond to the common point-and-click interaction techniques of the same name: i.e. "click", "press", "release", "drag", "drop", "popup", etc. The "popup" action should be used to pop up a context menu for the object, if one exists. For technical reasons, some toolkits cannot guarantee that the reported action is actually 'bound' to a nontrivial user event; i.e. the result of some actions via atk_action_do_action() may be NIL. a name string, or %NULL if @action does not implement this interface. a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed Sets a description of the specified action of the object. a gboolean representing if the description was successfully set; a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed the description to be assigned to this action The #AtkAction interface should be supported by any object that can perform one or more actions. The interface provides the standard mechanism for an assistive technology to determine what those actions are as well as tell the object to perform them. Any object that can be manipulated should support this interface. %TRUE if success, %FALSE otherwise a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed a the number of actions, or 0 if @action does not implement this interface. a #GObject instance that implements AtkActionIface a description string, or %NULL if @action does not implement this interface. a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed a name string, or %NULL if @action does not implement this interface. a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed the keybinding which can be used to activate this action, or %NULL if there is no keybinding for this action. a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed a gboolean representing if the description was successfully set; a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed the description to be assigned to this action a name string, or %NULL if @action does not implement this interface. a #GObject instance that implements AtkActionIface the action index corresponding to the action to be performed AtkAttribute is a string name/value pair representing a generic attribute. This can be used to expose additional information from an accessible object as a whole (see atk_object_get_attributes()) or an document (see atk_document_get_attributes()). In the case of text attributes (see atk_text_get_default_attributes()), #AtkTextAttribute enum defines all the possible text attribute names. You can use atk_text_attribute_get_name() to get the string name from the enum value. See also atk_text_attribute_for_name() and atk_text_attribute_get_value() for more information. A string name/value pair representing a generic attribute. The attribute name. the value of the attribute, represented as a string. Frees the memory used by an #AtkAttributeSet, including all its #AtkAttributes. The #AtkAttributeSet to free Like atk_get_binary_age(), but from the headers used at application compile time, rather than from the library linked against at application run time. Returns %TRUE if the version of the ATK header files is the same as or newer than the passed-in version. major version (e.g. 1 for version 1.2.5) minor version (e.g. 2 for version 1.2.5) micro version (e.g. 5 for version 1.2.5) The ATK interface provided by UI components which occupy a physical area on the screen. which the user can activate/interact with. #AtkComponent should be implemented by most if not all UI elements with an actual on-screen presence, i.e. components which can be said to have a screen-coordinate bounding box. Virtually all widgets will need to have #AtkComponent implementations provided for their corresponding #AtkObject class. In short, only UI elements which are *not* GUI elements will omit this ATK interface. A possible exception might be textual information with a transparent background, in which case text glyph bounding box information is provided by #AtkText. Add the specified handler to the set of functions to be called when this object receives focus events (in or out). If the handler is already added it is not added again If you need to track when an object gains or lose the focus, use the #AtkObject::state-change "focused" notification instead. a handler id which can be used in atk_component_remove_focus_handler() or zero if the handler was already added. The #AtkComponent to attach the @handler to The #AtkFocusHandler to be attached to @component Checks whether the specified point is within the extent of the @component. Toolkit implementor note: ATK provides a default implementation for this virtual method. In general there are little reason to re-implement it. %TRUE or %FALSE indicating whether the specified point is within the extent of the @component or not the #AtkComponent x coordinate y coordinate specifies whether the coordinates are relative to the screen or to the components top level window Returns the alpha value (i.e. the opacity) for this @component, on a scale from 0 (fully transparent) to 1.0 (fully opaque). An alpha value from 0 to 1.0, inclusive. an #AtkComponent Gets the rectangle which gives the extent of the @component. If the extent can not be obtained (e.g. a non-embedded plug or missing support), all of x, y, width, height are set to -1. an #AtkComponent address of #gint to put x coordinate address of #gint to put y coordinate address of #gint to put width address of #gint to put height specifies whether the coordinates are relative to the screen or to the components top level window Gets the layer of the component. an #AtkLayer which is the layer of the component an #AtkComponent Gets the zorder of the component. The value G_MININT will be returned if the layer of the component is not ATK_LAYER_MDI or ATK_LAYER_WINDOW. a gint which is the zorder of the component, i.e. the depth at which the component is shown in relation to other components in the same container. an #AtkComponent Gets the position of @component in the form of a point specifying @component's top-left corner. If the position can not be obtained (e.g. a non-embedded plug or missing support), x and y are set to -1. Since 2.12. Use atk_component_get_extents() instead. an #AtkComponent address of #gint to put x coordinate position address of #gint to put y coordinate position specifies whether the coordinates are relative to the screen or to the components top level window Gets the size of the @component in terms of width and height. If the size can not be obtained (e.g. a non-embedded plug or missing support), width and height are set to -1. Since 2.12. Use atk_component_get_extents() instead. an #AtkComponent address of #gint to put width of @component address of #gint to put height of @component Grabs focus for this @component. %TRUE if successful, %FALSE otherwise. an #AtkComponent Gets a reference to the accessible child, if one exists, at the coordinate point specified by @x and @y. a reference to the accessible child, if one exists the #AtkComponent x coordinate y coordinate specifies whether the coordinates are relative to the screen or to the components top level window Remove the handler specified by @handler_id from the list of functions to be executed when this object receives focus events (in or out). If you need to track when an object gains or lose the focus, use the #AtkObject::state-change "focused" notification instead. the #AtkComponent to remove the focus handler from the handler id of the focus handler to be removed from @component Makes @component visible on the screen by scrolling all necessary parents. Contrary to atk_component_set_position, this does not actually move @component in its parent, this only makes the parents scroll so that the object shows up on the screen, given its current position within the parents. whether scrolling was successful. an #AtkComponent specify where the object should be made visible. Move the top-left of @component to a given position of the screen by scrolling all necessary parents. whether scrolling was successful. an #AtkComponent specify whether coordinates are relative to the screen or to the parent object. x-position where to scroll to y-position where to scroll to Sets the extents of @component. %TRUE or %FALSE whether the extents were set or not an #AtkComponent x coordinate y coordinate width to set for @component height to set for @component specifies whether the coordinates are relative to the screen or to the components top level window Sets the position of @component. Contrary to atk_component_scroll_to, this does not trigger any scrolling, this just moves @component in its parent. %TRUE or %FALSE whether or not the position was set or not an #AtkComponent x coordinate y coordinate specifies whether the coordinates are relative to the screen or to the component's top level window Set the size of the @component in terms of width and height. %TRUE or %FALSE whether the size was set or not an #AtkComponent width to set for @component height to set for @component Add the specified handler to the set of functions to be called when this object receives focus events (in or out). If the handler is already added it is not added again If you need to track when an object gains or lose the focus, use the #AtkObject::state-change "focused" notification instead. a handler id which can be used in atk_component_remove_focus_handler() or zero if the handler was already added. The #AtkComponent to attach the @handler to The #AtkFocusHandler to be attached to @component Checks whether the specified point is within the extent of the @component. Toolkit implementor note: ATK provides a default implementation for this virtual method. In general there are little reason to re-implement it. %TRUE or %FALSE indicating whether the specified point is within the extent of the @component or not the #AtkComponent x coordinate y coordinate specifies whether the coordinates are relative to the screen or to the components top level window Returns the alpha value (i.e. the opacity) for this @component, on a scale from 0 (fully transparent) to 1.0 (fully opaque). An alpha value from 0 to 1.0, inclusive. an #AtkComponent Gets the rectangle which gives the extent of the @component. If the extent can not be obtained (e.g. a non-embedded plug or missing support), all of x, y, width, height are set to -1. an #AtkComponent address of #gint to put x coordinate address of #gint to put y coordinate address of #gint to put width address of #gint to put height specifies whether the coordinates are relative to the screen or to the components top level window Gets the layer of the component. an #AtkLayer which is the layer of the component an #AtkComponent Gets the zorder of the component. The value G_MININT will be returned if the layer of the component is not ATK_LAYER_MDI or ATK_LAYER_WINDOW. a gint which is the zorder of the component, i.e. the depth at which the component is shown in relation to other components in the same container. an #AtkComponent Gets the position of @component in the form of a point specifying @component's top-left corner. If the position can not be obtained (e.g. a non-embedded plug or missing support), x and y are set to -1. Since 2.12. Use atk_component_get_extents() instead. an #AtkComponent address of #gint to put x coordinate position address of #gint to put y coordinate position specifies whether the coordinates are relative to the screen or to the components top level window Gets the size of the @component in terms of width and height. If the size can not be obtained (e.g. a non-embedded plug or missing support), width and height are set to -1. Since 2.12. Use atk_component_get_extents() instead. an #AtkComponent address of #gint to put width of @component address of #gint to put height of @component Grabs focus for this @component. %TRUE if successful, %FALSE otherwise. an #AtkComponent Gets a reference to the accessible child, if one exists, at the coordinate point specified by @x and @y. a reference to the accessible child, if one exists the #AtkComponent x coordinate y coordinate specifies whether the coordinates are relative to the screen or to the components top level window Remove the handler specified by @handler_id from the list of functions to be executed when this object receives focus events (in or out). If you need to track when an object gains or lose the focus, use the #AtkObject::state-change "focused" notification instead. the #AtkComponent to remove the focus handler from the handler id of the focus handler to be removed from @component Makes @component visible on the screen by scrolling all necessary parents. Contrary to atk_component_set_position, this does not actually move @component in its parent, this only makes the parents scroll so that the object shows up on the screen, given its current position within the parents. whether scrolling was successful. an #AtkComponent specify where the object should be made visible. Move the top-left of @component to a given position of the screen by scrolling all necessary parents. whether scrolling was successful. an #AtkComponent specify whether coordinates are relative to the screen or to the parent object. x-position where to scroll to y-position where to scroll to Sets the extents of @component. %TRUE or %FALSE whether the extents were set or not an #AtkComponent x coordinate y coordinate width to set for @component height to set for @component specifies whether the coordinates are relative to the screen or to the components top level window Sets the position of @component. Contrary to atk_component_scroll_to, this does not trigger any scrolling, this just moves @component in its parent. %TRUE or %FALSE whether or not the position was set or not an #AtkComponent x coordinate y coordinate specifies whether the coordinates are relative to the screen or to the component's top level window Set the size of the @component in terms of width and height. %TRUE or %FALSE whether the size was set or not an #AtkComponent width to set for @component height to set for @component The 'bounds-changed" signal is emitted when the position or size of the component changes. The AtkRectangle giving the new position and size. The AtkComponent interface should be supported by any object that is rendered on the screen. The interface provides the standard mechanism for an assistive technology to determine and set the graphical representation of an object. This virtual function is deprecated since 2.9.4 and it should not be overriden. See atk_component_add_focus_handler() for more information. a handler id which can be used in atk_component_remove_focus_handler() or zero if the handler was already added. The #AtkComponent to attach the @handler to The #AtkFocusHandler to be attached to @component %TRUE or %FALSE indicating whether the specified point is within the extent of the @component or not the #AtkComponent x coordinate y coordinate specifies whether the coordinates are relative to the screen or to the components top level window a reference to the accessible child, if one exists the #AtkComponent x coordinate y coordinate specifies whether the coordinates are relative to the screen or to the components top level window an #AtkComponent address of #gint to put x coordinate address of #gint to put y coordinate address of #gint to put width address of #gint to put height specifies whether the coordinates are relative to the screen or to the components top level window This virtual function is deprecated since 2.12 and it should not be overriden. Use @AtkComponentIface.get_extents instead. an #AtkComponent address of #gint to put x coordinate position address of #gint to put y coordinate position specifies whether the coordinates are relative to the screen or to the components top level window This virtual function is deprecated since 2.12 and it should not be overriden. Use @AtkComponentIface.get_extents instead. an #AtkComponent address of #gint to put width of @component address of #gint to put height of @component %TRUE if successful, %FALSE otherwise. an #AtkComponent This virtual function is deprecated since 2.9.4 and it should not be overriden. See atk_component_remove_focus_handler() for more information. the #AtkComponent to remove the focus handler from the handler id of the focus handler to be removed from @component %TRUE or %FALSE whether the extents were set or not an #AtkComponent x coordinate y coordinate width to set for @component height to set for @component specifies whether the coordinates are relative to the screen or to the components top level window %TRUE or %FALSE whether or not the position was set or not an #AtkComponent x coordinate y coordinate specifies whether the coordinates are relative to the screen or to the component's top level window %TRUE or %FALSE whether the size was set or not an #AtkComponent width to set for @component height to set for @component an #AtkLayer which is the layer of the component an #AtkComponent a gint which is the zorder of the component, i.e. the depth at which the component is shown in relation to other components in the same container. an #AtkComponent An alpha value from 0 to 1.0, inclusive. an #AtkComponent whether scrolling was successful. an #AtkComponent specify where the object should be made visible. whether scrolling was successful. an #AtkComponent specify whether coordinates are relative to the screen or to the parent object. x-position where to scroll to y-position where to scroll to Specifies how xy coordinates are to be interpreted. Used by functions such as atk_component_get_position() and atk_text_get_character_extents() specifies xy coordinates relative to the screen specifies xy coordinates relative to the widget's top-level window specifies xy coordinates relative to the widget's immediate parent. Since: 2.30 A convenience macro for ATK type implementations. Similar to ATK_DEFINE_TYPE(), but defines an abstract type. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. A convenience macro for ATK type implementations. Similar to ATK_DEFINE_TYPE_WITH_CODE(), but defines an abstract type. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. Custom code that gets inserted in the _get_type() function. A convenience macro for type ATK implementations, which declares a class initialization function, an instance initialization function (see #GTypeInfo for information about these) and a static variable named @t_n _parent_class pointing to the parent class. Furthermore, it defines a _get_type() function. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. The most general convenience macro for ATK type implementations, on which ATK_DEFINE_TYPE(), etc are based. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. #GTypeFlags to pass to g_type_register_static() Custom code that gets inserted in the _get_type() function. A convenience macro for ATK type implementations. Similar to ATK_DEFINE_TYPE(), but allows you to insert custom code into the _get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). The name of the new type, in Camel case. The name of the new type in lowercase, with words separated by '_'. The #GType of the parent type. Custom code that gets inserted in the _get_type() function. The ATK interface which represents the toplevel container for document content. The AtkDocument interface should be supported by any object whose content is a representation or view of a document. The AtkDocument interface should appear on the toplevel container for the document content; however AtkDocument instances may be nested (i.e. an AtkDocument may be a descendant of another AtkDocument) in those cases where one document contains "embedded content" which can reasonably be considered a document in its own right. Retrieves the current page number inside @document. the current page number inside @document, or -1 if not implemented, not know by the implementor, or irrelevant. the #AtkDocument Gets a %gpointer that points to an instance of the DOM. It is up to the caller to check atk_document_get_type to determine how to cast this pointer. Since 2.12. @document is already a representation of the document. Use it directly, or one of its children, as an instance of the DOM. a %gpointer that points to an instance of the DOM. a #GObject instance that implements AtkDocumentIface Retrieves the value of the given @attribute_name inside @document. a string value associated with the named attribute for this document, or %NULL if a value for @attribute_name has not been specified for this document. a #GObject instance that implements AtkDocumentIface a character string representing the name of the attribute whose value is being queried. Gets an AtkAttributeSet which describes document-wide attributes as name-value pairs. An AtkAttributeSet containing the explicitly set name-value-pair attributes associated with this document as a whole. a #GObject instance that implements AtkDocumentIface Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of the content of this document instance. Individual text substrings or images within this document may have a different locale, see atk_text_get_attributes and atk_image_get_image_locale. Please use atk_object_get_object_locale() instead. a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of the document content as a whole, or NULL if the document content does not specify a locale. a #GObject instance that implements AtkDocumentIface Gets a string indicating the document type. Since 2.12. Please use atk_document_get_attributes() to ask for the document type if it applies. a string indicating the document type a #GObject instance that implements AtkDocumentIface Retrieves the total number of pages inside @document. total page count of @document, or -1 if not implemented, not know by the implementor or irrelevant. the #AtkDocument Returns an array of AtkTextSelections within this document. a GArray of AtkTextSelection structures representing the selection. an #AtkDocument Sets the value for the given @attribute_name inside @document. %TRUE if @attribute_value is successfully associated with @attribute_name for this @document, and %FALSE if if the document does not allow the attribute to be modified a #GObject instance that implements #AtkDocumentIface a character string representing the name of the attribute whose value is being set. a string value to be associated with @attribute_name. Makes 1 or more selections within this document denoted by the given array of AtkTextSelections. Any existing physical selection (inside or outside this document) is replaced by the new selections. All objects within the given selection ranges must be descendants of this document. Otherwise FALSE will be returned. TRUE if the selection was made successfully; FALSE otherwise. an #AtkDocument. a GArray of AtkTextSelections to be selected. Retrieves the value of the given @attribute_name inside @document. a string value associated with the named attribute for this document, or %NULL if a value for @attribute_name has not been specified for this document. a #GObject instance that implements AtkDocumentIface a character string representing the name of the attribute whose value is being queried. Gets an AtkAttributeSet which describes document-wide attributes as name-value pairs. An AtkAttributeSet containing the explicitly set name-value-pair attributes associated with this document as a whole. a #GObject instance that implements AtkDocumentIface Retrieves the current page number inside @document. the current page number inside @document, or -1 if not implemented, not know by the implementor, or irrelevant. the #AtkDocument Gets a %gpointer that points to an instance of the DOM. It is up to the caller to check atk_document_get_type to determine how to cast this pointer. Since 2.12. @document is already a representation of the document. Use it directly, or one of its children, as an instance of the DOM. a %gpointer that points to an instance of the DOM. a #GObject instance that implements AtkDocumentIface Gets a string indicating the document type. Since 2.12. Please use atk_document_get_attributes() to ask for the document type if it applies. a string indicating the document type a #GObject instance that implements AtkDocumentIface Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of the content of this document instance. Individual text substrings or images within this document may have a different locale, see atk_text_get_attributes and atk_image_get_image_locale. Please use atk_object_get_object_locale() instead. a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of the document content as a whole, or NULL if the document content does not specify a locale. a #GObject instance that implements AtkDocumentIface Retrieves the total number of pages inside @document. total page count of @document, or -1 if not implemented, not know by the implementor or irrelevant. the #AtkDocument Returns an array of AtkTextSelections within this document. a GArray of AtkTextSelection structures representing the selection. an #AtkDocument Sets the value for the given @attribute_name inside @document. %TRUE if @attribute_value is successfully associated with @attribute_name for this @document, and %FALSE if if the document does not allow the attribute to be modified a #GObject instance that implements #AtkDocumentIface a character string representing the name of the attribute whose value is being set. a string value to be associated with @attribute_name. Makes 1 or more selections within this document denoted by the given array of AtkTextSelections. Any existing physical selection (inside or outside this document) is replaced by the new selections. All objects within the given selection ranges must be descendants of this document. Otherwise FALSE will be returned. TRUE if the selection was made successfully; FALSE otherwise. an #AtkDocument. a GArray of AtkTextSelections to be selected. The "document-attribute-changed" signal should be emitted when there is a change to one of the document attributes returned by atk_document_get_attributes. the name of the attribute being modified, or %NULL if not available. the attribute's new value, or %null if not available. The 'load-complete' signal is emitted when a pending load of a static document has completed. This signal is to be expected by ATK clients if and when AtkDocument implementors expose ATK_STATE_BUSY. If the state of an AtkObject which implements AtkDocument does not include ATK_STATE_BUSY, it should be safe for clients to assume that the AtkDocument's static contents are fully loaded into the container. (Dynamic document contents should be exposed via other signals.) The 'load-stopped' signal is emitted when a pending load of document contents is cancelled, paused, or otherwise interrupted by the user or application logic. It should not however be emitted while waiting for a resource (for instance while blocking on a file or network read) unless a user-significant timeout has occurred. The 'page-changed' signal is emitted when the current page of a document changes, e.g. pressing page up/down in a document viewer. the new page number. If this value is unknown or not applicable, -1 should be provided. The 'reload' signal is emitted when the contents of a document is refreshed from its source. Once 'reload' has been emitted, a matching 'load-complete' or 'load-stopped' signal should follow, which clients may await before interrogating ATK for the latest document content. gets a string indicating the document type. This virtual function is deprecated since 2.12 and it should not be overriden. a string indicating the document type a #GObject instance that implements AtkDocumentIface a #GObject instance that implements AtkDocumentIface. This virtual method is deprecated since 2.12 and it should not be overriden. a %gpointer that points to an instance of the DOM. a #GObject instance that implements AtkDocumentIface gets locale. This virtual function is deprecated since 2.7.90 and it should not be overriden. a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of the document content as a whole, or NULL if the document content does not specify a locale. a #GObject instance that implements AtkDocumentIface gets an AtkAttributeSet which describes document-wide attributes as name-value pairs. An AtkAttributeSet containing the explicitly set name-value-pair attributes associated with this document as a whole. a #GObject instance that implements AtkDocumentIface returns a string value assocciated with the named attribute for this document, or NULL a string value associated with the named attribute for this document, or %NULL if a value for @attribute_name has not been specified for this document. a #GObject instance that implements AtkDocumentIface a character string representing the name of the attribute whose value is being queried. sets the value of an attribute. Returns TRUE on success, FALSE otherwise %TRUE if @attribute_value is successfully associated with @attribute_name for this @document, and %FALSE if if the document does not allow the attribute to be modified a #GObject instance that implements #AtkDocumentIface a character string representing the name of the attribute whose value is being set. a string value to be associated with @attribute_name. gets the current page number. Since 2.12 the current page number inside @document, or -1 if not implemented, not know by the implementor, or irrelevant. the #AtkDocument gets the page count of the document. Since 2.12 total page count of @document, or -1 if not implemented, not know by the implementor or irrelevant. the #AtkDocument a GArray of AtkTextSelection structures representing the selection. an #AtkDocument TRUE if the selection was made successfully; FALSE otherwise. an #AtkDocument. a GArray of AtkTextSelections to be selected. The ATK interface implemented by components containing user-editable text content. #AtkEditableText should be implemented by UI components which contain text which the user can edit, via the #AtkObject corresponding to that component (see #AtkObject). #AtkEditableText is a subclass of #AtkText, and as such, an object which implements #AtkEditableText is by definition an #AtkText implementor as well. See [iface@AtkText] Copy text from @start_pos up to, but not including @end_pos to the clipboard. an #AtkEditableText start position end position Copy text from @start_pos up to, but not including @end_pos to the clipboard and then delete from the widget. an #AtkEditableText start position end position Delete text @start_pos up to, but not including @end_pos. an #AtkEditableText start position end position Insert text at a given position. an #AtkEditableText the text to insert the length of text to insert, in bytes The caller initializes this to the position at which to insert the text. After the call it points at the position after the newly inserted text. Paste text from clipboard to specified @position. an #AtkEditableText position to paste Sets the attributes for a specified range. See the ATK_ATTRIBUTE macros (such as #ATK_ATTRIBUTE_LEFT_MARGIN) for examples of attributes that can be set. Note that other attributes that do not have corresponding ATK_ATTRIBUTE macros may also be set for certain text widgets. %TRUE if attributes successfully set for the specified range, otherwise %FALSE an #AtkEditableText an #AtkAttributeSet start of range in which to set attributes end of range in which to set attributes Set text contents of @text. an #AtkEditableText string to set for text contents of @text Copy text from @start_pos up to, but not including @end_pos to the clipboard. an #AtkEditableText start position end position Copy text from @start_pos up to, but not including @end_pos to the clipboard and then delete from the widget. an #AtkEditableText start position end position Delete text @start_pos up to, but not including @end_pos. an #AtkEditableText start position end position Insert text at a given position. an #AtkEditableText the text to insert the length of text to insert, in bytes The caller initializes this to the position at which to insert the text. After the call it points at the position after the newly inserted text. Paste text from clipboard to specified @position. an #AtkEditableText position to paste Sets the attributes for a specified range. See the ATK_ATTRIBUTE macros (such as #ATK_ATTRIBUTE_LEFT_MARGIN) for examples of attributes that can be set. Note that other attributes that do not have corresponding ATK_ATTRIBUTE macros may also be set for certain text widgets. %TRUE if attributes successfully set for the specified range, otherwise %FALSE an #AtkEditableText an #AtkAttributeSet start of range in which to set attributes end of range in which to set attributes Set text contents of @text. an #AtkEditableText string to set for text contents of @text %TRUE if attributes successfully set for the specified range, otherwise %FALSE an #AtkEditableText an #AtkAttributeSet start of range in which to set attributes end of range in which to set attributes an #AtkEditableText string to set for text contents of @text an #AtkEditableText the text to insert the length of text to insert, in bytes The caller initializes this to the position at which to insert the text. After the call it points at the position after the newly inserted text. an #AtkEditableText start position end position an #AtkEditableText start position end position an #AtkEditableText start position end position an #AtkEditableText position to paste A function which is called when an object emits a matching event, as used in #atk_add_focus_tracker. Currently the only events for which object-specific handlers are supported are events of type "focus:". Most clients of ATK will prefer to attach signal handlers for the various ATK signals instead. see [id@atk_add_focus_tracker] An #AtkObject instance for whom the callback will be called when the specified event (e.g. 'focus:') takes place. An #AtkEventListenerInit function is a special function that is called in order to initialize the per-object event registration system used by #AtkEventListener, if any preparation is required. see [id@atk_focus_tracker_init] The type of callback function used for atk_component_add_focus_handler() and atk_component_remove_focus_handler() Deprecated with atk_component_add_focus_handler() and atk_component_remove_focus_handler(). See those methods for more information. the #AtkObject that receives/lose the focus TRUE if the object receives the focus An AtkFunction is a function definition used for padding which has been added to class and interface structures to allow for expansion in the future. not used custom data defined by the user This object class is derived from AtkObject and can be used as a basis implementing accessible objects. This object class is derived from AtkObject. It can be used as a basis for implementing accessible objects for GObjects which are not derived from GtkWidget. One example of its use is in providing an accessible object for GnomeCanvasItem in the GAIL library. Gets the accessible object for the specified @obj. a #AtkObject which is the accessible object for the @obj a #GObject Gets the GObject for which @obj is the accessible object. a #GObject which is the object for which @obj is the accessible object a #AtkGObjectAccessible An ATK object which encapsulates a link or set of links in a hypertext document. An ATK object which encapsulates a link or set of links (for instance in the case of client-side image maps) in a hypertext document. It may implement the AtkAction interface. AtkHyperlink may also be used to refer to inline embedded content, since it allows specification of a start and end offset within the host AtkHypertext object. Gets the index with the hypertext document at which this link ends. the index with the hypertext document at which this link ends an #AtkHyperlink Gets the number of anchors associated with this hyperlink. the number of anchors associated with this hyperlink an #AtkHyperlink Returns the item associated with this hyperlinks nth anchor. For instance, the returned #AtkObject will implement #AtkText if @link_ is a text hyperlink, #AtkImage if @link_ is an image hyperlink etc. Multiple anchors are primarily used by client-side image maps. an #AtkObject associated with this hyperlinks i-th anchor an #AtkHyperlink a (zero-index) integer specifying the desired anchor Gets the index with the hypertext document at which this link begins. the index with the hypertext document at which this link begins an #AtkHyperlink Get a the URI associated with the anchor specified by @i of @link_. Multiple anchors are primarily used by client-side image maps. a string specifying the URI an #AtkHyperlink a (zero-index) integer specifying the desired anchor Determines whether this AtkHyperlink is selected Please use ATK_STATE_FOCUSABLE for all links, and ATK_STATE_FOCUSED for focused links. True if the AtkHyperlink is selected, False otherwise an #AtkHyperlink Since the document that a link is associated with may have changed this method returns %TRUE if the link is still valid (with respect to the document it references) and %FALSE otherwise. whether or not this link is still valid an #AtkHyperlink Gets the index with the hypertext document at which this link ends. the index with the hypertext document at which this link ends an #AtkHyperlink Gets the number of anchors associated with this hyperlink. the number of anchors associated with this hyperlink an #AtkHyperlink Returns the item associated with this hyperlinks nth anchor. For instance, the returned #AtkObject will implement #AtkText if @link_ is a text hyperlink, #AtkImage if @link_ is an image hyperlink etc. Multiple anchors are primarily used by client-side image maps. an #AtkObject associated with this hyperlinks i-th anchor an #AtkHyperlink a (zero-index) integer specifying the desired anchor Gets the index with the hypertext document at which this link begins. the index with the hypertext document at which this link begins an #AtkHyperlink Get a the URI associated with the anchor specified by @i of @link_. Multiple anchors are primarily used by client-side image maps. a string specifying the URI an #AtkHyperlink a (zero-index) integer specifying the desired anchor Indicates whether the link currently displays some or all of its content inline. Ordinary HTML links will usually return %FALSE, but an inline &lt;src&gt; HTML element will return %TRUE. whether or not this link displays its content inline. an #AtkHyperlink Determines whether this AtkHyperlink is selected Please use ATK_STATE_FOCUSABLE for all links, and ATK_STATE_FOCUSED for focused links. True if the AtkHyperlink is selected, False otherwise an #AtkHyperlink Since the document that a link is associated with may have changed this method returns %TRUE if the link is still valid (with respect to the document it references) and %FALSE otherwise. whether or not this link is still valid an #AtkHyperlink Selected link Please use ATK_STATE_FOCUSABLE for all links, and ATK_STATE_FOCUSED for focused links. The signal link-activated is emitted when a link is activated. a string specifying the URI an #AtkHyperlink a (zero-index) integer specifying the desired anchor an #AtkObject associated with this hyperlinks i-th anchor an #AtkHyperlink a (zero-index) integer specifying the desired anchor the index with the hypertext document at which this link ends an #AtkHyperlink the index with the hypertext document at which this link begins an #AtkHyperlink whether or not this link is still valid an #AtkHyperlink the number of anchors associated with this hyperlink an #AtkHyperlink True if the AtkHyperlink is selected, False otherwise an #AtkHyperlink A queryable interface which allows AtkHyperlink instances associated with an AtkObject to be obtained. AtkHyperlinkImpl corresponds to AT-SPI's Hyperlink interface, and differs from AtkHyperlink in that AtkHyperlink is an object type, rather than an interface, and thus cannot be directly queried. FTW Gets the hyperlink associated with this object. an AtkHyperlink object which points to this implementing AtkObject. a #GObject instance that implements AtkHyperlinkImplIface Gets the hyperlink associated with this object. an AtkHyperlink object which points to this implementing AtkObject. a #GObject instance that implements AtkHyperlinkImplIface an AtkHyperlink object which points to this implementing AtkObject. a #GObject instance that implements AtkHyperlinkImplIface Describes the type of link Link is inline The ATK interface which provides standard mechanism for manipulating hyperlinks. An interface used for objects which implement linking between multiple resource or content locations, or multiple 'markers' within a single document. A Hypertext instance is associated with one or more Hyperlinks, which are associated with particular offsets within the Hypertext's included content. While this interface is derived from Text, there is no requirement that Hypertext instances have textual content; they may implement Image as well, and Hyperlinks need not have non-zero text offsets. Gets the link in this hypertext document at index @link_index the link in this hypertext document at index @link_index an #AtkHypertext an integer specifying the desired link Gets the index into the array of hyperlinks that is associated with the character specified by @char_index. an index into the array of hyperlinks in @hypertext, or -1 if there is no hyperlink associated with this character. an #AtkHypertext a character index Gets the number of links within this hypertext document. the number of links within this hypertext document an #AtkHypertext Gets the link in this hypertext document at index @link_index the link in this hypertext document at index @link_index an #AtkHypertext an integer specifying the desired link Gets the index into the array of hyperlinks that is associated with the character specified by @char_index. an index into the array of hyperlinks in @hypertext, or -1 if there is no hyperlink associated with this character. an #AtkHypertext a character index Gets the number of links within this hypertext document. the number of links within this hypertext document an #AtkHypertext The "link-selected" signal is emitted by an AtkHyperText object when one of the hyperlinks associated with the object is selected. the index of the hyperlink which is selected the link in this hypertext document at index @link_index an #AtkHypertext an integer specifying the desired link the number of links within this hypertext document an #AtkHypertext an index into the array of hyperlinks in @hypertext, or -1 if there is no hyperlink associated with this character. an #AtkHypertext a character index Like atk_get_interface_age(), but from the headers used at application compile time, rather than from the library linked against at application run time. The ATK Interface implemented by components which expose image or pixmap content on-screen. #AtkImage should be implemented by #AtkObject subtypes on behalf of components which display image/pixmap information onscreen, and which provide information (other than just widget borders, etc.) via that image content. For instance, icons, buttons with icons, toolbar elements, and image viewing panes typically should implement #AtkImage. #AtkImage primarily provides two types of information: coordinate information (useful for screen review mode of screenreaders, and for use by onscreen magnifiers), and descriptive information. The descriptive information is provided for alternative, text-only presentation of the most significant information present in the image. Get a textual description of this image. a string representing the image description a #GObject instance that implements AtkImageIface Retrieves the locale identifier associated to the #AtkImage. a string corresponding to the POSIX `LC_MESSAGES` locale used by the image description, or %NULL if the image does not specify a locale. An #AtkImage Gets the position of the image in the form of a point specifying the images top-left corner. If the position can not be obtained (e.g. missing support), x and y are set to -1. a #GObject instance that implements AtkImageIface address of #gint to put x coordinate position; otherwise, -1 if value cannot be obtained. address of #gint to put y coordinate position; otherwise, -1 if value cannot be obtained. specifies whether the coordinates are relative to the screen or to the components top level window Get the width and height in pixels for the specified image. The values of @width and @height are returned as -1 if the values cannot be obtained (for instance, if the object is not onscreen). If the size can not be obtained (e.g. missing support), x and y are set to -1. a #GObject instance that implements AtkImageIface filled with the image width, or -1 if the value cannot be obtained. filled with the image height, or -1 if the value cannot be obtained. Sets the textual description for this image. boolean TRUE, or FALSE if operation could not be completed. a #GObject instance that implements AtkImageIface a string description to set for @image Get a textual description of this image. a string representing the image description a #GObject instance that implements AtkImageIface Retrieves the locale identifier associated to the #AtkImage. a string corresponding to the POSIX `LC_MESSAGES` locale used by the image description, or %NULL if the image does not specify a locale. An #AtkImage Gets the position of the image in the form of a point specifying the images top-left corner. If the position can not be obtained (e.g. missing support), x and y are set to -1. a #GObject instance that implements AtkImageIface address of #gint to put x coordinate position; otherwise, -1 if value cannot be obtained. address of #gint to put y coordinate position; otherwise, -1 if value cannot be obtained. specifies whether the coordinates are relative to the screen or to the components top level window Get the width and height in pixels for the specified image. The values of @width and @height are returned as -1 if the values cannot be obtained (for instance, if the object is not onscreen). If the size can not be obtained (e.g. missing support), x and y are set to -1. a #GObject instance that implements AtkImageIface filled with the image width, or -1 if the value cannot be obtained. filled with the image height, or -1 if the value cannot be obtained. Sets the textual description for this image. boolean TRUE, or FALSE if operation could not be completed. a #GObject instance that implements AtkImageIface a string description to set for @image a #GObject instance that implements AtkImageIface address of #gint to put x coordinate position; otherwise, -1 if value cannot be obtained. address of #gint to put y coordinate position; otherwise, -1 if value cannot be obtained. specifies whether the coordinates are relative to the screen or to the components top level window a string representing the image description a #GObject instance that implements AtkImageIface a #GObject instance that implements AtkImageIface filled with the image width, or -1 if the value cannot be obtained. filled with the image height, or -1 if the value cannot be obtained. boolean TRUE, or FALSE if operation could not be completed. a #GObject instance that implements AtkImageIface a string description to set for @image a string corresponding to the POSIX `LC_MESSAGES` locale used by the image description, or %NULL if the image does not specify a locale. An #AtkImage Gets a reference to an object's #AtkObject implementation, if the object implements #AtkObjectIface a reference to an object's #AtkObject implementation The #GObject instance which should implement #AtkImplementorIface if a non-null return value is required. The AtkImplementor interface is implemented by objects for which AtkObject peers may be obtained via calls to iface->(ref_accessible)(implementor); Encapsulates information about a key event. An AtkKeyEventType, generally one of ATK_KEY_EVENT_PRESS or ATK_KEY_EVENT_RELEASE A bitmask representing the state of the modifier keys immediately after the event takes place. The meaning of the bits is currently defined to match the bitmask used by GDK in GdkEventType.state, see http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html#GdkEventKey A guint representing a keysym value corresponding to those used by GDK and X11: see /usr/X11/include/keysymdef.h. The length of member #string. A string containing one of the following: either a string approximating the text that would result from this keypress, if the key is a control or graphic character, or a symbolic name for this keypress. Alphanumeric and printable keys will have the symbolic key name in this string member, for instance "A". "0", "semicolon", "aacute". Keypad keys have the prefix "KP". The raw hardware code that generated the key event. This field is raraly useful. A timestamp in milliseconds indicating when the event occurred. These timestamps are relative to a starting point which should be considered arbitrary, and only used to compare the dispatch times of events to one another. Specifies the type of a keyboard evemt. specifies a key press event specifies a key release event Not a valid value; specifies end of enumeration An #AtkKeySnoopFunc is a type of callback which is called whenever a key event occurs, if registered via atk_add_key_event_listener. It allows for pre-emptive interception of key events via the return code as described below. TRUE (nonzero) if the event emission should be stopped and the event discarded without being passed to the normal GUI recipient; FALSE (zero) if the event dispatch to the client application should proceed as normal. see [id@atk_add_key_event_listener] an AtkKeyEventStruct containing information about the key event for which notification is being given. a block of data which will be passed to the event listener, on notification. Describes the layer of a component These enumerated "layer values" are used when determining which UI rendering layer a component is drawn into, which can help in making determinations of when components occlude one another. The object does not have a layer This layer is reserved for the desktop background This layer is used for Canvas components This layer is normally used for components This layer is used for layered components This layer is used for popup components, such as menus This layer is reserved for future use. This layer is used for toplevel windows. Enumeration used to indicate a type of live region and how assertive it should be in terms of speaking notifications. Currently, this is only used for "notification" events, but it may be used for additional purposes in the future. No live region. This live region should be considered polite. This live region should be considered assertive. Like atk_get_major_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. Like atk_get_micro_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. Like atk_get_minor_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. A set of ATK utility functions for thread locking A set of utility functions for thread locking. This interface and all his related methods are deprecated since 2.12. Obtain the singleton instance of AtkMisc for this application. Since 2.12. The singleton instance of AtkMisc for this application. Take the thread mutex for the GUI toolkit, if one exists. (This method is implemented by the toolkit ATK implementation layer; for instance, for GTK+, GAIL implements this via GDK_THREADS_ENTER). Since 2.12. an AtkMisc instance for this application. Release the thread mutex for the GUI toolkit, if one exists. This method, and atk_misc_threads_enter, are needed in some situations by threaded application code which services ATK requests, since fulfilling ATK requests often requires calling into the GUI toolkit. If a long-running or potentially blocking call takes place inside such a block, it should be bracketed by atk_misc_threads_leave/atk_misc_threads_enter calls. (This method is implemented by the toolkit ATK implementation layer; for instance, for GTK+, GAIL implements this via GDK_THREADS_LEAVE). Since 2.12. an AtkMisc instance for this application. Take the thread mutex for the GUI toolkit, if one exists. (This method is implemented by the toolkit ATK implementation layer; for instance, for GTK+, GAIL implements this via GDK_THREADS_ENTER). Since 2.12. an AtkMisc instance for this application. Release the thread mutex for the GUI toolkit, if one exists. This method, and atk_misc_threads_enter, are needed in some situations by threaded application code which services ATK requests, since fulfilling ATK requests often requires calling into the GUI toolkit. If a long-running or potentially blocking call takes place inside such a block, it should be bracketed by atk_misc_threads_leave/atk_misc_threads_enter calls. (This method is implemented by the toolkit ATK implementation layer; for instance, for GTK+, GAIL implements this via GDK_THREADS_LEAVE). Since 2.12. an AtkMisc instance for this application. Usage of AtkMisc is deprecated since 2.12 and heavily discouraged. This virtual function is deprecated since 2.12 and it should not be overriden. an AtkMisc instance for this application. This virtual function is deprecated sice 2.12 and it should not be overriden. an AtkMisc instance for this application. An AtkObject which purports to implement all ATK interfaces. An AtkNoOpObject is an AtkObject which purports to implement all ATK interfaces. It is the type of AtkObject which is created if an accessible object is requested for an object type for which no factory type is specified. Provides a default (non-functioning stub) #AtkObject. Application maintainers should not use this method. a default (non-functioning stub) #AtkObject a #GObject The AtkObjectFactory which creates an AtkNoOpObject. The AtkObjectFactory which creates an AtkNoOpObject. An instance of this is created by an AtkRegistry if no factory type has not been specified to create an accessible object of a particular type. Creates an instance of an #AtkObjectFactory which generates primitive (non-functioning) #AtkObjects. an instance of an #AtkObjectFactory The base object class for the Accessibility Toolkit API. This class is the primary class for accessibility support via the Accessibility ToolKit (ATK). Objects which are instances of #AtkObject (or instances of AtkObject-derived types) are queried for properties which relate basic (and generic) properties of a UI component such as name and description. Instances of #AtkObject may also be queried as to whether they implement other ATK interfaces (e.g. #AtkAction, #AtkComponent, etc.), as appropriate to the role which a given UI component plays in a user interface. All UI components in an application which provide useful information or services to the user must provide corresponding #AtkObject instances on request (in GTK+, for instance, usually on a call to #gtk_widget_get_accessible ()), either via ATK support built into the toolkit for the widget class or ancestor class, or in the case of custom widgets, if the inherited #AtkObject implementation is insufficient, via instances of a new #AtkObject subclass. See [class@AtkObjectFactory], [class@AtkRegistry]. (GTK+ users see also #GtkAccessible). Calls @handler on property changes. Connect directly to #AtkObject::property-change or the relevant #GObject::notify signal for each desired property. a #guint which is the handler id used in atk_object_remove_property_change_handler() an #AtkObject a function to be called when a property changes its value The signal handler which is executed when there is a focus event for an object. This virtual function is deprecated since 2.9.4 and it should not be overriden. Use the #AtkObject::state-change "focused" signal instead. Get a list of properties applied to this object as a whole, as an #AtkAttributeSet consisting of name-value pairs. As such these attributes may be considered weakly-typed properties or annotations, as distinct from strongly-typed object data available via other get/set methods. Not all objects have explicit "name-value pair" #AtkAttributeSet properties. an #AtkAttributeSet consisting of all explicit properties/annotations applied to the object, or an empty set if the object has no name-value pair attributes assigned to it. This #atkattributeset should be freed by a call to atk_attribute_set_free(). An #AtkObject. Gets the accessible description of the accessible. a character string representing the accessible description of the accessible. an #AtkObject Gets the 0-based index of this accessible in its parent; returns -1 if the accessible does not have an accessible parent. an integer which is the index of the accessible in its parent an #AtkObject Gets the layer of the accessible. Use atk_component_get_layer instead. an #AtkLayer which is the layer of the accessible an #AtkObject Gets the zorder of the accessible. The value G_MININT will be returned if the layer of the accessible is not ATK_LAYER_MDI. Use atk_component_get_mdi_zorder instead. a gint which is the zorder of the accessible, i.e. the depth at which the component is shown in relation to other components in the same container. an #AtkObject Gets the accessible name of the accessible. a character string representing the accessible name of the object. an #AtkObject Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of @accessible. a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of @accessible. an #AtkObject Gets the accessible parent of the accessible. By default this is the one assigned with atk_object_set_parent(), but it is assumed that ATK implementors have ways to get the parent of the object without the need of assigning it manually with atk_object_set_parent(), and will return it with this method. If you are only interested on the parent assigned with atk_object_set_parent(), use atk_object_peek_parent(). an #AtkObject representing the accessible parent of the accessible an #AtkObject Gets the role of the accessible. an #AtkRole which is the role of the accessible an #AtkObject This function is called when implementing subclasses of #AtkObject. It does initialization required for the new object. It is intended that this function should called only in the ..._new() functions used to create an instance of a subclass of #AtkObject a #AtkObject a #gpointer which identifies the object for which the AtkObject was created. Gets the #AtkRelationSet associated with the object. an #AtkRelationSet representing the relation set of the object. an #AtkObject Gets a reference to the state set of the accessible; the caller must unreference it when it is no longer needed. a reference to an #AtkStateSet which is the state set of the accessible an #AtkObject Removes a property change handler. See atk_object_connect_property_change_handler() an #AtkObject a guint which identifies the handler to be removed. Sets the accessible description of the accessible. You can't set the description to NULL. This is reserved for the initial value. In this aspect NULL is similar to ATK_ROLE_UNKNOWN. If you want to set the name to a empty value you can use "". an #AtkObject a character string to be set as the accessible description Sets the accessible name of the accessible. You can't set the name to NULL. This is reserved for the initial value. In this aspect NULL is similar to ATK_ROLE_UNKNOWN. If you want to set the name to a empty value you can use "". an #AtkObject a character string to be set as the accessible name Sets the accessible parent of the accessible. @parent can be NULL. an #AtkObject an #AtkObject to be set as the accessible parent Sets the role of the accessible. an #AtkObject an #AtkRole to be set as the role Adds a relationship of the specified type with the specified target. TRUE if the relationship is added. The #AtkObject to which an AtkRelation is to be added. The #AtkRelationType of the relation The #AtkObject which is to be the target of the relation. Calls @handler on property changes. Connect directly to #AtkObject::property-change or the relevant #GObject::notify signal for each desired property. a #guint which is the handler id used in atk_object_remove_property_change_handler() an #AtkObject a function to be called when a property changes its value Gets the accessible id of the accessible. a character string representing the accessible id of the object, or NULL if no such string was set. an #AtkObject Get a list of properties applied to this object as a whole, as an #AtkAttributeSet consisting of name-value pairs. As such these attributes may be considered weakly-typed properties or annotations, as distinct from strongly-typed object data available via other get/set methods. Not all objects have explicit "name-value pair" #AtkAttributeSet properties. an #AtkAttributeSet consisting of all explicit properties/annotations applied to the object, or an empty set if the object has no name-value pair attributes assigned to it. This #atkattributeset should be freed by a call to atk_attribute_set_free(). An #AtkObject. Gets the accessible description of the accessible. a character string representing the accessible description of the accessible. an #AtkObject Gets the help text associated with the accessible. a character string representing the help text or the object, or NULL if no such string was set. an #AtkObject Gets the 0-based index of this accessible in its parent; returns -1 if the accessible does not have an accessible parent. an integer which is the index of the accessible in its parent an #AtkObject Gets the layer of the accessible. Use atk_component_get_layer instead. an #AtkLayer which is the layer of the accessible an #AtkObject Gets the zorder of the accessible. The value G_MININT will be returned if the layer of the accessible is not ATK_LAYER_MDI. Use atk_component_get_mdi_zorder instead. a gint which is the zorder of the accessible, i.e. the depth at which the component is shown in relation to other components in the same container. an #AtkObject Gets the number of accessible children of the accessible. an integer representing the number of accessible children of the accessible. an #AtkObject Gets the accessible name of the accessible. a character string representing the accessible name of the object. an #AtkObject Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of @accessible. a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of @accessible. an #AtkObject Gets the accessible parent of the accessible. By default this is the one assigned with atk_object_set_parent(), but it is assumed that ATK implementors have ways to get the parent of the object without the need of assigning it manually with atk_object_set_parent(), and will return it with this method. If you are only interested on the parent assigned with atk_object_set_parent(), use atk_object_peek_parent(). an #AtkObject representing the accessible parent of the accessible an #AtkObject Gets the role of the accessible. an #AtkRole which is the role of the accessible an #AtkObject This function is called when implementing subclasses of #AtkObject. It does initialization required for the new object. It is intended that this function should called only in the ..._new() functions used to create an instance of a subclass of #AtkObject a #AtkObject a #gpointer which identifies the object for which the AtkObject was created. Emits a state-change signal for the specified state. Note that as a general rule when the state of an existing object changes, emitting a notification is expected. an #AtkObject an #AtkState whose state is changed a gboolean which indicates whether the state is being set on or off Gets the accessible parent of the accessible, if it has been manually assigned with atk_object_set_parent. Otherwise, this function returns %NULL. This method is intended as an utility for ATK implementors, and not to be exposed to accessible tools. See atk_object_get_parent() for further reference. an #AtkObject representing the accessible parent of the accessible if assigned an #AtkObject Gets a reference to the specified accessible child of the object. The accessible children are 0-based so the first accessible child is at index 0, the second at index 1 and so on. an #AtkObject representing the specified accessible child of the accessible. an #AtkObject a gint representing the position of the child, starting from 0 Gets the #AtkRelationSet associated with the object. an #AtkRelationSet representing the relation set of the object. an #AtkObject Gets a reference to the state set of the accessible; the caller must unreference it when it is no longer needed. a reference to an #AtkStateSet which is the state set of the accessible an #AtkObject Removes a property change handler. See atk_object_connect_property_change_handler() an #AtkObject a guint which identifies the handler to be removed. Removes a relationship of the specified type with the specified target. TRUE if the relationship is removed. The #AtkObject from which an AtkRelation is to be removed. The #AtkRelationType of the relation The #AtkObject which is the target of the relation to be removed. Sets the accessible ID of the accessible. This is not meant to be presented to the user, but to be an ID which is stable over application development. Typically, this is the gtkbuilder ID. Such an ID will be available for instance to identify a given well-known accessible object for tailored screen reading, or for automatic regression testing. an #AtkObject a character string to be set as the accessible id Sets the accessible description of the accessible. You can't set the description to NULL. This is reserved for the initial value. In this aspect NULL is similar to ATK_ROLE_UNKNOWN. If you want to set the name to a empty value you can use "". an #AtkObject a character string to be set as the accessible description Sets the help text associated with the accessible. This can be used to expose context-sensitive information to help a user understand how to interact with the object. You can't set the help text to NULL. This is reserved for the initial value. If you want to set the name to an empty value, you can use "". an #AtkObject a character string to be set as the accessible's help text Sets the accessible name of the accessible. You can't set the name to NULL. This is reserved for the initial value. In this aspect NULL is similar to ATK_ROLE_UNKNOWN. If you want to set the name to a empty value you can use "". an #AtkObject a character string to be set as the accessible name Sets the accessible parent of the accessible. @parent can be NULL. an #AtkObject an #AtkObject to be set as the accessible parent Sets the role of the accessible. an #AtkObject an #AtkRole to be set as the role Table caption. Since 1.3. Use table-caption-object instead. Accessible table column description. Since 2.12. Use atk_table_get_column_description() and atk_table_set_column_description() instead. Accessible table column header. Since 2.12. Use atk_table_get_column_header() and atk_table_set_column_header() instead. Accessible table row description. Since 2.12. Use atk_table_get_row_description() and atk_table_set_row_description() instead. Accessible table row header. Since 2.12. Use atk_table_get_row_header() and atk_table_set_row_header() instead. Numeric value of this object, in case being and AtkValue. Since 2.12. Use atk_value_get_value_and_text() to get the value, and value-changed signal to be notified on their value changes. The "active-descendant-changed" signal is emitted by an object which has the state ATK_STATE_MANAGES_DESCENDANTS when the focus object in the object changes. For instance, a table will emit the signal when the cell in the table which has focus changes. the newly focused object. The "announcement" signal can be emitted to pass an announcement on to be read by a screen reader. Depcrecated (2.50): Use AtkObject::notification instead. the text to be announced. The "attribute-changed" signal should be emitted when one of an object's attributes changes. the name of the attribute being modified, or %NULL if not available. the attribute's new value, or %null if not available. The signal "children-changed" is emitted when a child is added or removed from an object. It supports two details: "add" and "remove" The index of the added or removed child. The value can be -1. This is used if the value is not known by the implementor when the child is added/removed or irrelevant. A gpointer to the child AtkObject which was added or removed. If the child was removed, it is possible that it is not available for the implementor. In that case this pointer can be NULL. The signal "focus-event" is emitted when an object gained or lost focus. Use the #AtkObject::state-change signal instead. a boolean value which indicates whether the object gained or lost focus. The "notification" signal can be emitted to pass an announcement on to be read by a screen reader. the text to be announced. an #AtkLive specifying the politeness of the notification. Should be either ATK_LIVE_POLITE or ATK_LIVE_ASSERTIVE. The signal "property-change" is emitted when an object's property value changes. @arg1 contains an #AtkPropertyValues with the name and the new value of the property whose value has changed. Note that, as with GObject notify, getting this signal does not guarantee that the value of the property has actually changed; it may also be emitted when the setter of the property is called to reinstate the previous value. Toolkit implementor note: ATK implementors should use g_object_notify() to emit property-changed notifications. #AtkObject::property-changed is needed by the implementation of atk_add_global_event_listener() because GObject notify doesn't support emission hooks. an #AtkPropertyValues containing the new value of the property which changed. The "state-change" signal is emitted when an object's state changes. The detail value identifies the state type which has changed. The name of the state which has changed A boolean which indicates whether the state has been set or unset. The "visible-data-changed" signal is emitted when the visual appearance of the object changed. a character string representing the accessible name of the object. an #AtkObject a character string representing the accessible description of the accessible. an #AtkObject an #AtkObject representing the accessible parent of the accessible an #AtkObject an integer which is the index of the accessible in its parent an #AtkObject an #AtkRelationSet representing the relation set of the object. an #AtkObject an #AtkRole which is the role of the accessible an #AtkObject an #AtkLayer which is the layer of the accessible an #AtkObject a gint which is the zorder of the accessible, i.e. the depth at which the component is shown in relation to other components in the same container. an #AtkObject a reference to an #AtkStateSet which is the state set of the accessible an #AtkObject an #AtkObject a character string to be set as the accessible name an #AtkObject a character string to be set as the accessible description an #AtkObject an #AtkObject to be set as the accessible parent an #AtkObject an #AtkRole to be set as the role specifies a function to be called when a property changes value. This virtual function is deprecated since 2.12 and it should not be overriden. Connect directly to property-change or notify signal instead. a #guint which is the handler id used in atk_object_remove_property_change_handler() an #AtkObject a function to be called when a property changes its value removes a property changed handler as returned by @connect_property_change_handler. This virtual function is deprecated sice 2.12 and it should not be overriden. an #AtkObject a guint which identifies the handler to be removed. a #AtkObject a #gpointer which identifies the object for which the AtkObject was created. The signal handler which is executed when there is a focus event for an object. This virtual function is deprecated since 2.9.4 and it should not be overriden. Use the #AtkObject::state-change "focused" signal instead. an #AtkAttributeSet consisting of all explicit properties/annotations applied to the object, or an empty set if the object has no name-value pair attributes assigned to it. This #atkattributeset should be freed by a call to atk_attribute_set_free(). An #AtkObject. a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of @accessible. an #AtkObject The base object class for a factory used to create accessible objects for objects of a specific GType. This class is the base object class for a factory used to create an accessible object for a specific GType. The function atk_registry_set_factory_type() is normally called to store in the registry the factory type to be used to create an accessible of a particular GType. Inform @factory that it is no longer being used to create accessibles. When called, @factory may need to inform #AtkObjects which it has created that they need to be re-instantiated. Note: primarily used for runtime replacement of #AtkObjectFactorys in object registries. an #AtkObjectFactory to invalidate Provides an #AtkObject that implements an accessibility interface on behalf of @obj an #AtkObject that implements an accessibility interface on behalf of @obj The #AtkObjectFactory associated with @obj's object type a #GObject Gets the GType of the accessible which is created by the factory. the type of the accessible which is created by the @factory. The value G_TYPE_INVALID is returned if no type if found. an #AtkObjectFactory Inform @factory that it is no longer being used to create accessibles. When called, @factory may need to inform #AtkObjects which it has created that they need to be re-instantiated. Note: primarily used for runtime replacement of #AtkObjectFactorys in object registries. an #AtkObjectFactory to invalidate an #AtkObjectFactory to invalidate Toplevel for embedding into other processes See [class@AtkSocket] Creates a new #AtkPlug instance. the newly created #AtkPlug Gets the unique ID of an #AtkPlug object, which can be used to embed inside of an #AtkSocket using atk_socket_embed(). Internally, this calls a class function that should be registered by the IPC layer (usually at-spi2-atk). The implementor of an #AtkPlug object should call this function (after atk-bridge is loaded) and pass the value to the process implementing the #AtkSocket, so it could embed the plug. the unique ID for the plug an #AtkPlug An AtkPropertyChangeHandler is a function which is executed when an AtkObject's property changes value. It is specified in a call to atk_object_connect_property_change_handler(). Since 2.12. atkobject which property changes values changed Note: @old_value field of #AtkPropertyValues will not contain a valid value. This is a field defined with the purpose of contain the previous value of the property, but is not used anymore. The name of the ATK property which has changed. NULL. This field is not used anymore. The new value of the named property. A given range or subrange, to be used with #AtkValue #AtkRange are used on #AtkValue, in order to represent the full range of a given component (for example an slider or a range control), or to define each individual subrange this full range is splitted if available. See #AtkValue documentation for further details. Creates a new #AtkRange. a new #AtkRange inferior limit for this range superior limit for this range human readable description of this range. Returns a new #AtkRange that is a exact copy of @src a new #AtkRange copy of @src #AtkRange to copy Free @range #AtkRange to free Returns the human readable description of @range the human-readable description of @range an #AtkRange Returns the lower limit of @range the lower limit of @range an #AtkRange Returns the upper limit of @range the upper limit of @range an #AtkRange A data structure for holding a rectangle. Those coordinates are relative to the component top-level parent. X coordinate of the left side of the rectangle. Y coordinate of the top side of the rectangle. width of the rectangle. height of the rectangle. An object used to store the GType of the factories used to create an accessible object for an object of a particular GType. The AtkRegistry is normally used to create appropriate ATK "peers" for user interface components. Application developers usually need only interact with the AtkRegistry by associating appropriate ATK implementation classes with GObject classes via the atk_registry_set_factory_type call, passing the appropriate GType for application custom widget classes. Gets an #AtkObjectFactory appropriate for creating #AtkObjects appropriate for @type. an #AtkObjectFactory appropriate for creating #AtkObjects appropriate for @type. an #AtkRegistry a #GType with which to look up the associated #AtkObjectFactory Provides a #GType indicating the #AtkObjectFactory subclass associated with @type. a #GType associated with type @type an #AtkRegistry a #GType with which to look up the associated #AtkObjectFactory subclass Associate an #AtkObjectFactory subclass with a #GType. Note: The associated @factory_type will thereafter be responsible for the creation of new #AtkObject implementations for instances appropriate for @type. the #AtkRegistry in which to register the type association an #AtkObject type an #AtkObjectFactory type to associate with @type. Must implement AtkObject appropriate for @type. An object used to describe a relation between a object and one or more other objects. An AtkRelation describes a relation between an object and one or more other objects. The actual relations that an object has with other objects are defined as an AtkRelationSet, which is a set of AtkRelations. Create a new relation for the specified key and the specified list of targets. See also atk_object_add_relationship(). a pointer to a new #AtkRelation an array of pointers to #AtkObjects number of #AtkObjects pointed to by @targets an #AtkRelationType with which to create the new #AtkRelation Adds the specified AtkObject to the target for the relation, if it is not already present. See also atk_object_add_relationship(). an #AtkRelation an #AtkObject Gets the type of @relation the type of @relation an #AtkRelation Gets the target list of @relation the target list of @relation an #AtkRelation Remove the specified AtkObject from the target for the relation. TRUE if the removal is successful. an #AtkRelation an #AtkObject A set of AtkRelations, normally the set of AtkRelations which an AtkObject has. The AtkRelationSet held by an object establishes its relationships with objects beyond the normal "parent/child" hierarchical relationships that all user interface objects have. AtkRelationSets establish whether objects are labelled or controlled by other components, share group membership with other components (for instance within a radio-button group), or share content which "flows" between them, among other types of possible relationships. Creates a new empty relation set. a new #AtkRelationSet Add a new relation to the current relation set if it is not already present. This function ref's the AtkRelation so the caller of this function should unref it to ensure that it will be destroyed when the AtkRelationSet is destroyed. an #AtkRelationSet an #AtkRelation Add a new relation of the specified type with the specified target to the current relation set if the relation set does not contain a relation of that type. If it is does contain a relation of that typea the target is added to the relation. an #AtkRelationSet an #AtkRelationType an #AtkObject Determines whether the relation set contains a relation that matches the specified type. %TRUE if @relationship is the relationship type of a relation in @set, %FALSE otherwise an #AtkRelationSet an #AtkRelationType Determines whether the relation set contains a relation that matches the specified pair formed by type @relationship and object @target. %TRUE if @set contains a relation with the relationship type @relationship with an object @target, %FALSE otherwise an #AtkRelationSet an #AtkRelationType an #AtkObject Determines the number of relations in a relation set. an integer representing the number of relations in the set. an #AtkRelationSet Determines the relation at the specified position in the relation set. a #AtkRelation, which is the relation at position i in the set. an #AtkRelationSet a gint representing a position in the set, starting from 0. Finds a relation that matches the specified type. an #AtkRelation, which is a relation matching the specified type. an #AtkRelationSet an #AtkRelationType Removes a relation from the relation set. This function unref's the #AtkRelation so it will be deleted unless there is another reference to it. an #AtkRelationSet an #AtkRelation Describes the type of the relation Not used, represens "no relationship" or an error condition. Indicates an object controlled by one or more target objects. Indicates an object is an controller for one or more target objects. Indicates an object is a label for one or more target objects. Indicates an object is labelled by one or more target objects. Indicates an object is a member of a group of one or more target objects. Indicates an object is a cell in a treetable which is displayed because a cell in the same column is expanded and identifies that cell. Indicates that the object has content that flows logically to another AtkObject in a sequential way, (for instance text-flow). Indicates that the object has content that flows logically from another AtkObject in a sequential way, (for instance text-flow). Indicates a subwindow attached to a component but otherwise has no connection in the UI heirarchy to that component. Indicates that the object visually embeds another object's content, i.e. this object's content flows around another's content. Reciprocal of %ATK_RELATION_EMBEDS, indicates that this object's content is visualy embedded in another object. Indicates that an object is a popup for another object. Indicates that an object is a parent window of another object. Reciprocal of %ATK_RELATION_DESCRIPTION_FOR. Indicates that one or more target objects provide descriptive information about this object. This relation type is most appropriate for information that is not essential as its presentation may be user-configurable and/or limited to an on-demand mechanism such as an assistive technology command. For brief, essential information such as can be found in a widget's on-screen label, use %ATK_RELATION_LABELLED_BY. For an on-screen error message, use %ATK_RELATION_ERROR_MESSAGE. For lengthy extended descriptive information contained in an on-screen object, consider using %ATK_RELATION_DETAILS as assistive technologies may provide a means for the user to navigate to objects containing detailed descriptions so that their content can be more closely reviewed. Reciprocal of %ATK_RELATION_DESCRIBED_BY. Indicates that this object provides descriptive information about the target object(s). See also %ATK_RELATION_DETAILS_FOR and %ATK_RELATION_ERROR_FOR. Indicates an object is a cell in a treetable and is expanded to display other cells in the same column. Reciprocal of %ATK_RELATION_DETAILS_FOR. Indicates that this object has a detailed or extended description, the contents of which can be found in the target object(s). This relation type is most appropriate for information that is sufficiently lengthy as to make navigation to the container of that information desirable. For less verbose information suitable for announcement only, see %ATK_RELATION_DESCRIBED_BY. If the detailed information describes an error condition, %ATK_RELATION_ERROR_FOR should be used instead. @Since: ATK-2.26. Reciprocal of %ATK_RELATION_DETAILS. Indicates that this object provides a detailed or extended description about the target object(s). See also %ATK_RELATION_DESCRIPTION_FOR and %ATK_RELATION_ERROR_FOR. @Since: ATK-2.26. Reciprocal of %ATK_RELATION_ERROR_FOR. Indicates that this object has one or more errors, the nature of which is described in the contents of the target object(s). Objects that have this relation type should also contain %ATK_STATE_INVALID_ENTRY in their #AtkStateSet. @Since: ATK-2.26. Reciprocal of %ATK_RELATION_ERROR_MESSAGE. Indicates that this object contains an error message describing an invalid condition in the target object(s). @Since: ATK_2.26. Not used, this value indicates the end of the enumeration. Get the #AtkRelationType type corresponding to a relation name. the #AtkRelationType enumerated type corresponding to the specified name, or #ATK_RELATION_NULL if no matching relation type is found. a string which is the (non-localized) name of an ATK relation type. Gets the description string describing the #AtkRelationType @type. the string describing the AtkRelationType The #AtkRelationType whose name is required Associate @name with a new #AtkRelationType an #AtkRelationType associated with @name a name string Describes the role of an object These are the built-in enumerated roles that UI components can have in ATK. Other roles may be added at runtime, so an AtkRole >= %ATK_ROLE_LAST_DEFINED is not necessarily an error. Invalid role A label which represents an accelerator An object which is an alert to the user. Assistive Technologies typically respond to ATK_ROLE_ALERT by reading the entire onscreen contents of containers advertising this role. Should be used for warning dialogs, etc. An object which is an animated image An arrow in one of the four cardinal directions An object that displays a calendar and allows the user to select a date An object that can be drawn into and is used to trap events A choice that can be checked or unchecked and provides a separate indicator for the current state A menu item with a check box A specialized dialog that lets the user choose a color The header for a column of data A collapsible list of choices the user can select from An object whose purpose is to allow a user to edit a date An inconifed internal frame within a DESKTOP_PANE A pane that supports internal frames and iconified versions of those internal frames An object whose purpose is to allow a user to set a value A top level window with title bar and a border A pane that allows the user to navigate through and select the contents of a directory An object used for drawing custom user interface elements A specialized dialog that lets the user choose a file A object that fills up space in a user interface A specialized dialog that lets the user choose a font A top level window with a title bar, border, menubar, etc. A pane that is guaranteed to be painted on top of all panes beneath it A document container for HTML, whose children represent the document content A small fixed size picture, typically used to decorate components An object whose primary purpose is to display an image A frame-like object that is clipped by a desktop pane An object used to present an icon or short string in an interface A specialized pane that allows its children to be drawn in layers, providing a form of stacking order An object that presents a list of objects to the user and allows the user to select one or more of them An object that represents an element of a list An object usually found inside a menu bar that contains a list of actions the user can choose from An object usually drawn at the top of the primary dialog box of an application that contains a list of menus the user can choose from An object usually contained in a menu that presents an action the user can choose A specialized pane whose primary use is inside a DIALOG An object that is a child of a page tab list An object that presents a series of panels (or page tabs), one at a time, through some mechanism provided by the object A generic container that is often used to group objects A text object uses for passwords, or other places where the text content is not shown visibly to the user A temporary window that is usually used to offer the user a list of choices, and then hides when the user selects one of those choices An object used to indicate how much of a task has been completed An object the user can manipulate to tell the application to do something A specialized check box that will cause other radio buttons in the same group to become unchecked when this one is checked A check menu item which belongs to a group. At each instant exactly one of the radio menu items from a group is selected A specialized pane that has a glass pane and a layered pane as its children The header for a row of data An object usually used to allow a user to incrementally view a large amount of data. An object that allows a user to incrementally view a large amount of information An object usually contained in a menu to provide a visible and logical separation of the contents in a menu An object that allows the user to select from a bounded range A specialized panel that presents two other panels at the same time An object used to get an integer or floating point number from the user An object which reports messages of minor importance to the user An object used to represent information in terms of rows and columns A cell in a table The header for a column of a table The header for a row of a table A menu item used to tear off and reattach its menu An object that represents an accessible terminal. (Since: 0.6) An interactive widget that supports multiple lines of text and optionally accepts user input, but whose purpose is not to solicit user input. Thus ATK_ROLE_TEXT is appropriate for the text view in a plain text editor but inappropriate for an input field in a dialog box or web form. For widgets whose purpose is to solicit input from the user, see ATK_ROLE_ENTRY and ATK_ROLE_PASSWORD_TEXT. For generic objects which display a brief amount of textual information, see ATK_ROLE_STATIC. A specialized push button that can be checked or unchecked, but does not provide a separate indicator for the current state A bar or palette usually composed of push buttons or toggle buttons An object that provides information about another object An object used to represent hierarchical information to the user An object capable of expanding and collapsing rows as well as showing multiple columns of data. (Since: 0.7) The object contains some Accessible information, but its role is not known An object usually used in a scroll pane A top level window with no title or border. An object that serves as a document header. (Since: 1.1.1) An object that serves as a document footer. (Since: 1.1.1) An object which is contains a paragraph of text content. (Since: 1.1.1) An object which describes margins and tab stops, etc. for text objects which it controls (should have CONTROLLER_FOR relation to such). (Since: 1.1.1) The object is an application object, which may contain @ATK_ROLE_FRAME objects or other types of accessibles. The root accessible of any application's ATK hierarchy should have ATK_ROLE_APPLICATION. (Since: 1.1.4) The object is a dialog or list containing items for insertion into an entry widget, for instance a list of words for completion of a text entry. (Since: 1.3) The object is an editable text object in a toolbar. (Since: 1.5) The object is an embedded container within a document or panel. This role is a grouping "hint" indicating that the contained objects share a context. (Since: 1.7.2) The object is a component whose textual content may be entered or modified by the user, provided @ATK_STATE_EDITABLE is present. (Since: 1.11) The object is a graphical depiction of quantitative data. It may contain multiple subelements whose attributes and/or description may be queried to obtain both the quantitative data and information about how the data is being presented. The LABELLED_BY relation is particularly important in interpreting objects of this type, as is the accessible-description property. (Since: 1.11) The object contains descriptive information, usually textual, about another user interface element such as a table, chart, or image. (Since: 1.11) The object is a visual frame or container which contains a view of document content. Document frames may occur within another Document instance, in which case the second document may be said to be embedded in the containing instance. HTML frames are often ROLE_DOCUMENT_FRAME. Either this object, or a singleton descendant, should implement the Document interface. (Since: 1.11) The object serves as a heading for content which follows it in a document. The 'heading level' of the heading, if availabe, may be obtained by querying the object's attributes. The object is a containing instance which encapsulates a page of information. @ATK_ROLE_PAGE is used in documents and content which support a paginated navigation model. (Since: 1.11) The object is a containing instance of document content which constitutes a particular 'logical' section of the document. The type of content within a section, and the nature of the section division itself, may be obtained by querying the object's attributes. Sections may be nested. (Since: 1.11) The object is redundant with another object in the hierarchy, and is exposed for purely technical reasons. Objects of this role should normally be ignored by clients. (Since: 1.11) The object is a container for form controls, for instance as part of a web form or user-input form within a document. This role is primarily a tag/convenience for clients when navigating complex documents, it is not expected that ordinary GUI containers will always have ATK_ROLE_FORM. (Since: 1.12.0) The object is a hypertext anchor, i.e. a "link" in a hypertext document. Such objects are distinct from 'inline' content which may also use the Hypertext/Hyperlink interfaces to indicate the range/location within a text object where an inline or embedded object lies. (Since: 1.12.1) The object is a window or similar viewport which is used to allow composition or input of a 'complex character', in other words it is an "input method window." (Since: 1.12.1) A row in a table. (Since: 2.1.0) An object that represents an element of a tree. (Since: 2.1.0) A document frame which contains a spreadsheet. (Since: 2.1.0) A document frame which contains a presentation or slide content. (Since: 2.1.0) A document frame which contains textual content, such as found in a word processing application. (Since: 2.1.0) A document frame which contains HTML or other markup suitable for display in a web browser. (Since: 2.1.0) A document frame which contains email content to be displayed or composed either in plain text or HTML. (Since: 2.1.0) An object found within a document and designed to present a comment, note, or other annotation. In some cases, this object might not be visible until activated. (Since: 2.1.0) A non-collapsible list of choices the user can select from. (Since: 2.1.0) A group of related widgets. This group typically has a label. (Since: 2.1.0) An image map object. Usually a graphic with multiple hotspots, where each hotspot can be activated resulting in the loading of another document or section of a document. (Since: 2.1.0) A transitory object designed to present a message to the user, typically at the desktop level rather than inside a particular application. (Since: 2.1.0) An object designed to present a message to the user within an existing window. (Since: 2.1.0) A bar that serves as a level indicator to, for instance, show the strength of a password or the state of a battery. (Since: 2.7.3) A bar that serves as the title of a window or a dialog. (Since: 2.12) An object which contains a text section that is quoted from another source. (Since: 2.12) An object which represents an audio element. (Since: 2.12) An object which represents a video element. (Since: 2.12) A definition of a term or concept. (Since: 2.12) A section of a page that consists of a composition that forms an independent part of a document, page, or site. Examples: A blog entry, a news story, a forum post. (Since: 2.12) A region of a web page intended as a navigational landmark. This is designed to allow Assistive Technologies to provide quick navigation among key regions within a document. (Since: 2.12) A text widget or container holding log content, such as chat history and error logs. In this role there is a relationship between the arrival of new items in the log and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points. (Since: 2.12) A container where non-essential information changes frequently. Common usages of marquee include stock tickers and ad banners. The primary difference between a marquee and a log is that logs usually have a meaningful order or sequence of important content changes. (Since: 2.12) A text widget or container that holds a mathematical expression. (Since: 2.12) A widget whose purpose is to display a rating, such as the number of stars associated with a song in a media player. Objects of this role should also implement AtkValue. (Since: 2.12) An object containing a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point. (Since: 2.12) An object that represents a list of term-value groups. A term-value group represents a individual description and consist of one or more names (ATK_ROLE_DESCRIPTION_TERM) followed by one or more values (ATK_ROLE_DESCRIPTION_VALUE). For each list, there should not be more than one group with the same term name. (Since: 2.12) An object that represents a term or phrase with a corresponding definition. (Since: 2.12) An object that represents the description, definition or value of a term. (Since: 2.12) A generic non-container object whose purpose is to display a brief amount of information to the user and whose role is known by the implementor but lacks semantic value for the user. Examples in which %ATK_ROLE_STATIC is appropriate include the message displayed in a message box and an image used as an alternative means to display text. %ATK_ROLE_STATIC should not be applied to widgets which are traditionally interactive, objects which display a significant amount of content, or any object which has an accessible relation pointing to another object. Implementors should expose the displayed information through the accessible name of the object. If doing so seems inappropriate, it may indicate that a different role should be used. For labels which describe another widget, see %ATK_ROLE_LABEL. For text views, see %ATK_ROLE_TEXT. For generic containers, see %ATK_ROLE_PANEL. For objects whose role is not known by the implementor, see %ATK_ROLE_UNKNOWN. (Since: 2.16) An object that represents a mathematical fraction. (Since: 2.16) An object that represents a mathematical expression displayed with a radical. (Since: 2.16) An object that contains text that is displayed as a subscript. (Since: 2.16) An object that contains text that is displayed as a superscript. (Since: 2.16) An object that contains the text of a footnote. (Since: 2.26) Content previously deleted or proposed to be deleted, e.g. in revision history or a content view providing suggestions from reviewers. (Since: 2.34) Content previously inserted or proposed to be inserted, e.g. in revision history or a content view providing suggestions from reviewers. (Since: 2.34) A run of content that is marked or highlighted, such as for reference purposes, or to call it out as having a special purpose. If the marked content has an associated section in the document elaborating on the reason for the mark, then %ATK_RELATION_DETAILS should be used on the mark to point to that associated section. In addition, the reciprocal relation %ATK_RELATION_DETAILS_FOR should be used on the associated content section to point back to the mark. (Since: 2.36) A container for content that is called out as a proposed change from the current version of the document, such as by a reviewer of the content. This role should include either %ATK_ROLE_CONTENT_DELETION and/or %ATK_ROLE_CONTENT_INSERTION children, in any order, to indicate what the actual change is. (Since: 2.36) A specialized push button to open a menu. (Since: 2.46) A switch that can be toggled on/off. (Since: 2.56) not a valid role, used for finding end of the enumeration Get the #AtkRole type corresponding to a rolew name. the #AtkRole enumerated type corresponding to the specified name, or #ATK_ROLE_INVALID if no matching role is found. a string which is the (non-localized) name of an ATK role. Gets the localized description string describing the #AtkRole @role. the localized string describing the AtkRole The #AtkRole whose localized name is required Gets the description string describing the #AtkRole @role. the string describing the AtkRole The #AtkRole whose name is required Registers the role specified by @name. @name must be a meaningful name. So it should not be empty, or consisting on whitespaces. Since 2.12. If your application/toolkit doesn't find a suitable role for a specific object defined at #AtkRole, please submit a bug in order to add a new role to the specification. an #AtkRole for the new role if added properly. ATK_ROLE_INVALID in case of error. a character string describing the new role. Specifies where an object should be placed on the screen when using scroll_to. Scroll the object vertically and horizontally to bring its top left corner to the top left corner of the window. Scroll the object vertically and horizontally to bring its bottom right corner to the bottom right corner of the window. Scroll the object vertically to bring its top edge to the top edge of the window. Scroll the object vertically to bring its bottom edge to the bottom edge of the window. Scroll the object vertically and horizontally to bring its left edge to the left edge of the window. Scroll the object vertically and horizontally to bring its right edge to the right edge of the window. Scroll the object vertically and horizontally so that as much as possible of the object becomes visible. The exact placement is determined by the application. The ATK interface implemented by container objects whose #AtkObject children can be selected. #AtkSelection should be implemented by UI components with children which are exposed by #atk_object_ref_child and #atk_object_get_n_children, if the use of the parent UI component ordinarily involves selection of one or more of the objects corresponding to those #AtkObject children - for example, selectable lists. Note that other types of "selection" (for instance text selection) are accomplished a other ATK interfaces - #AtkSelection is limited to the selection/deselection of children. Adds the specified accessible child of the object to the object's selection. TRUE if success, FALSE otherwise. a #GObject instance that implements AtkSelectionIface a #gint specifying the child index. Clears the selection in the object so that no children in the object are selected. TRUE if success, FALSE otherwise. a #GObject instance that implements AtkSelectionIface Gets the number of accessible children currently selected. Note: callers should not rely on %NULL or on a zero value for indication of whether AtkSelectionIface is implemented, they should use type checking/interface checking macros or the atk_get_accessible_value() convenience method. a gint representing the number of items selected, or 0 if @selection does not implement this interface. a #GObject instance that implements AtkSelectionIface Determines if the current child of this object is selected Note: callers should not rely on %NULL or on a zero value for indication of whether AtkSelectionIface is implemented, they should use type checking/interface checking macros or the atk_get_accessible_value() convenience method. a gboolean representing the specified child is selected, or 0 if @selection does not implement this interface. a #GObject instance that implements AtkSelectionIface a #gint specifying the child index. Gets a reference to the accessible object representing the specified selected child of the object. Note: callers should not rely on %NULL or on a zero value for indication of whether AtkSelectionIface is implemented, they should use type checking/interface checking macros or the atk_get_accessible_value() convenience method. an #AtkObject representing the selected accessible, or %NULL if @selection does not implement this interface. a #GObject instance that implements AtkSelectionIface a #gint specifying the index in the selection set. (e.g. the ith selection as opposed to the ith child). Removes the specified child of the object from the object's selection. TRUE if success, FALSE otherwise. a #GObject instance that implements AtkSelectionIface a #gint specifying the index in the selection set. (e.g. the ith selection as opposed to the ith child). Causes every child of the object to be selected if the object supports multiple selections. TRUE if success, FALSE otherwise. a #GObject instance that implements AtkSelectionIface Adds the specified accessible child of the object to the object's selection. TRUE if success, FALSE otherwise. a #GObject instance that implements AtkSelectionIface a #gint specifying the child index. Clears the selection in the object so that no children in the object are selected. TRUE if success, FALSE otherwise. a #GObject instance that implements AtkSelectionIface Gets the number of accessible children currently selected. Note: callers should not rely on %NULL or on a zero value for indication of whether AtkSelectionIface is implemented, they should use type checking/interface checking macros or the atk_get_accessible_value() convenience method. a gint representing the number of items selected, or 0 if @selection does not implement this interface. a #GObject instance that implements AtkSelectionIface Determines if the current child of this object is selected Note: callers should not rely on %NULL or on a zero value for indication of whether AtkSelectionIface is implemented, they should use type checking/interface checking macros or the atk_get_accessible_value() convenience method. a gboolean representing the specified child is selected, or 0 if @selection does not implement this interface. a #GObject instance that implements AtkSelectionIface a #gint specifying the child index. Gets a reference to the accessible object representing the specified selected child of the object. Note: callers should not rely on %NULL or on a zero value for indication of whether AtkSelectionIface is implemented, they should use type checking/interface checking macros or the atk_get_accessible_value() convenience method. an #AtkObject representing the selected accessible, or %NULL if @selection does not implement this interface. a #GObject instance that implements AtkSelectionIface a #gint specifying the index in the selection set. (e.g. the ith selection as opposed to the ith child). Removes the specified child of the object from the object's selection. TRUE if success, FALSE otherwise. a #GObject instance that implements AtkSelectionIface a #gint specifying the index in the selection set. (e.g. the ith selection as opposed to the ith child). Causes every child of the object to be selected if the object supports multiple selections. TRUE if success, FALSE otherwise. a #GObject instance that implements AtkSelectionIface The "selection-changed" signal is emitted by an object which implements AtkSelection interface when the selection changes. TRUE if success, FALSE otherwise. a #GObject instance that implements AtkSelectionIface a #gint specifying the child index. TRUE if success, FALSE otherwise. a #GObject instance that implements AtkSelectionIface an #AtkObject representing the selected accessible, or %NULL if @selection does not implement this interface. a #GObject instance that implements AtkSelectionIface a #gint specifying the index in the selection set. (e.g. the ith selection as opposed to the ith child). a gint representing the number of items selected, or 0 if @selection does not implement this interface. a #GObject instance that implements AtkSelectionIface a gboolean representing the specified child is selected, or 0 if @selection does not implement this interface. a #GObject instance that implements AtkSelectionIface a #gint specifying the child index. TRUE if success, FALSE otherwise. a #GObject instance that implements AtkSelectionIface a #gint specifying the index in the selection set. (e.g. the ith selection as opposed to the ith child). TRUE if success, FALSE otherwise. a #GObject instance that implements AtkSelectionIface Container for AtkPlug objects from other processes Together with #AtkPlug, #AtkSocket provides the ability to embed accessibles from one process into another in a fashion that is transparent to assistive technologies. #AtkSocket works as the container of #AtkPlug, embedding it using the method atk_socket_embed(). Any accessible contained in the #AtkPlug will appear to the assistive technologies as being inside the application that created the #AtkSocket. The communication between a #AtkSocket and a #AtkPlug is done by the IPC layer of the accessibility framework, normally implemented by the D-Bus based implementation of AT-SPI (at-spi2). If that is the case, at-spi-atk2 is the responsible to implement the abstract methods atk_plug_get_id() and atk_socket_embed(), so an ATK implementor shouldn't reimplement them. The process that contains the #AtkPlug is responsible to send the ID returned by atk_plug_id() to the process that contains the #AtkSocket, so it could call the method atk_socket_embed() in order to embed it. For the same reasons, an implementor doesn't need to implement atk_object_get_n_accessible_children() and atk_object_ref_accessible_child(). All the logic related to those functions will be implemented by the IPC layer. See [class@AtkPlug] Creates a new #AtkSocket. the newly created #AtkSocket instance Embeds the children of an #AtkPlug as the children of the #AtkSocket. The plug may be in the same process or in a different process. The class item used by this function should be filled in by the IPC layer (usually at-spi2-atk). The implementor of the AtkSocket should call this function and pass the id for the plug as returned by atk_plug_get_id(). It is the responsibility of the application to pass the plug id on to the process implementing the #AtkSocket as needed. an #AtkSocket the ID of an #AtkPlug Embeds the children of an #AtkPlug as the children of the #AtkSocket. The plug may be in the same process or in a different process. The class item used by this function should be filled in by the IPC layer (usually at-spi2-atk). The implementor of the AtkSocket should call this function and pass the id for the plug as returned by atk_plug_get_id(). It is the responsibility of the application to pass the plug id on to the process implementing the #AtkSocket as needed. an #AtkSocket the ID of an #AtkPlug Determines whether or not the socket has an embedded plug. TRUE if a plug is embedded in the socket an #AtkSocket an #AtkSocket the ID of an #AtkPlug An AtkStateSet contains the states of an object. An AtkStateSet is a read-only representation of the full set of #AtkStates that apply to an object at a given time. This set is not meant to be modified, but rather created when #atk_object_ref_state_set() is called. Creates a new empty state set. a new #AtkStateSet Adds the state of the specified type to the state set if it is not already present. Note that because an #AtkStateSet is a read-only object, this method should be used to add a state to a newly-created set which will then be returned by #atk_object_ref_state_set. It should not be used to modify the existing state of an object. See also #atk_object_notify_state_change. %TRUE if the state for @type is not already in @set. an #AtkStateSet an #AtkStateType Adds the states of the specified types to the state set. Note that because an #AtkStateSet is a read-only object, this method should be used to add states to a newly-created set which will then be returned by #atk_object_ref_state_set. It should not be used to modify the existing state of an object. See also #atk_object_notify_state_change. an #AtkStateSet an array of #AtkStateType The number of elements in the array Constructs the intersection of the two sets, returning %NULL if the intersection is empty. a new #AtkStateSet which is the intersection of the two sets. an #AtkStateSet another #AtkStateSet Removes all states from the state set. an #AtkStateSet Checks whether the state for the specified type is in the specified set. %TRUE if @type is the state type is in @set. an #AtkStateSet an #AtkStateType Checks whether the states for all the specified types are in the specified set. %TRUE if all the states for @type are in @set. an #AtkStateSet an array of #AtkStateType The number of elements in the array Checks whether the state set is empty, i.e. has no states set. %TRUE if @set has no states set, otherwise %FALSE an #AtkStateType Constructs the union of the two sets. a new #AtkStateSet which is the union of the two sets, returning %NULL is empty. an #AtkStateSet another #AtkStateSet Removes the state for the specified type from the state set. Note that because an #AtkStateSet is a read-only object, this method should be used to remove a state to a newly-created set which will then be returned by #atk_object_ref_state_set. It should not be used to modify the existing state of an object. See also #atk_object_notify_state_change. %TRUE if @type was the state type is in @set. an #AtkStateSet an #AtkType Constructs the exclusive-or of the two sets, returning %NULL is empty. The set returned by this operation contains the states in exactly one of the two sets. a new #AtkStateSet which contains the states which are in exactly one of the two sets. an #AtkStateSet another #AtkStateSet The possible types of states of an object Indicates an invalid state - probably an error condition. Indicates a window is currently the active window, or an object is the active subelement within a container or table. ATK_STATE_ACTIVE should not be used for objects which have ATK_STATE_FOCUSABLE or ATK_STATE_SELECTABLE: Those objects should use ATK_STATE_FOCUSED and ATK_STATE_SELECTED respectively. ATK_STATE_ACTIVE is a means to indicate that an object which is not focusable and not selectable is the currently-active item within its parent container. Indicates that the object is 'armed', i.e. will be activated by if a pointer button-release event occurs within its bounds. Buttons often enter this state when a pointer click occurs within their bounds, as a precursor to activation. ATK_STATE_ARMED has been deprecated since ATK-2.16 and should not be used in newly-written code. Indicates the current object is busy, i.e. onscreen representation is in the process of changing, or the object is temporarily unavailable for interaction due to activity already in progress. This state may be used by implementors of Document to indicate that content loading is underway. It also may indicate other 'pending' conditions; clients may wish to interrogate this object when the ATK_STATE_BUSY flag is removed. Indicates this object is currently checked, for instance a checkbox is 'non-empty'. Indicates that this object no longer has a valid backing widget (for instance, if its peer object has been destroyed) Indicates that this object can contain text, and that the user can change the textual contents of this object by editing those contents directly. For an object which is expected to be editable due to its type, but which cannot be edited due to the application or platform preventing the user from doing so, that object's #AtkStateSet should lack ATK_STATE_EDITABLE and should contain ATK_STATE_READ_ONLY. Indicates that this object is enabled, i.e. that it currently reflects some application state. Objects that are "greyed out" may lack this state, and may lack the STATE_SENSITIVE if direct user interaction cannot cause them to acquire STATE_ENABLED. See also: ATK_STATE_SENSITIVE Indicates this object allows progressive disclosure of its children Indicates this object its expanded - see ATK_STATE_EXPANDABLE above Indicates this object can accept keyboard focus, which means all events resulting from typing on the keyboard will normally be passed to it when it has focus Indicates this object currently has the keyboard focus Indicates the orientation of this object is horizontal; used, for instance, by objects of ATK_ROLE_SCROLL_BAR. For objects where vertical/horizontal orientation is especially meaningful. Indicates this object is minimized and is represented only by an icon Indicates something must be done with this object before the user can interact with an object in a different window Indicates this (text) object can contain multiple lines of text Indicates this object allows more than one of its children to be selected at the same time, or in the case of text objects, that the object supports non-contiguous text selections. Indicates this object paints every pixel within its rectangular region. Indicates this object is currently pressed. Indicates the size of this object is not fixed Indicates this object is the child of an object that allows its children to be selected and that this child is one of those children that can be selected Indicates this object is the child of an object that allows its children to be selected and that this child is one of those children that has been selected Indicates this object is sensitive, e.g. to user interaction. STATE_SENSITIVE usually accompanies STATE_ENABLED for user-actionable controls, but may be found in the absence of STATE_ENABLED if the current visible state of the control is "disconnected" from the application state. In such cases, direct user interaction can often result in the object gaining STATE_SENSITIVE, for instance if a user makes an explicit selection using an object whose current state is ambiguous or undefined. @see STATE_ENABLED, STATE_INDETERMINATE. Indicates this object, the object's parent, the object's parent's parent, and so on, are all 'shown' to the end-user, i.e. subject to "exposure" if blocking or obscuring objects do not interpose between this object and the top of the window stack. Indicates this (text) object can contain only a single line of text Indicates that the information returned for this object may no longer be synchronized with the application state. This is implied if the object has STATE_TRANSIENT, and can also occur towards the end of the object peer's lifecycle. It can also be used to indicate that the index associated with this object has changed since the user accessed the object (in lieu of "index-in-parent-changed" events). Indicates this object is transient, i.e. a snapshot which may not emit events when its state changes. Data from objects with ATK_STATE_TRANSIENT should not be cached, since there may be no notification given when the cached data becomes obsolete. Indicates the orientation of this object is vertical Indicates this object is visible, e.g. has been explicitly marked for exposure to the user. **note**: %ATK_STATE_VISIBLE is no guarantee that the object is actually unobscured on the screen, only that it is 'potentially' visible, barring obstruction, being scrolled or clipped out of the field of view, or having an ancestor container that has not yet made visible. A widget is potentially onscreen if it has both %ATK_STATE_VISIBLE and %ATK_STATE_SHOWING. The absence of %ATK_STATE_VISIBLE and %ATK_STATE_SHOWING is semantically equivalent to saying that an object is 'hidden'. See also %ATK_STATE_TRUNCATED, which applies if an object with %ATK_STATE_VISIBLE and %ATK_STATE_SHOWING set lies within a viewport which means that its contents are clipped, e.g. a truncated spreadsheet cell or an image within a scrolling viewport. Mostly useful for screen-review and magnification algorithms. Indicates that "active-descendant-changed" event is sent when children become 'active' (i.e. are selected or navigated to onscreen). Used to prevent need to enumerate all children in very large containers, like tables. The presence of STATE_MANAGES_DESCENDANTS is an indication to the client. that the children should not, and need not, be enumerated by the client. Objects implementing this state are expected to provide relevant state notifications to listening clients, for instance notifications of visibility changes and activation of their contained child objects, without the client having previously requested references to those children. Indicates that the value, or some other quantifiable property, of this AtkObject cannot be fully determined. In the case of a large data set in which the total number of items in that set is unknown (e.g. 1 of 999+), implementors should expose the currently-known set size (999) along with this state. In the case of a check box, this state should be used to indicate that the check box is a tri-state check box which is currently neither checked nor unchecked. Indicates that an object is truncated, e.g. a text value in a speradsheet cell. Indicates that explicit user interaction with an object is required by the user interface, e.g. a required field in a "web-form" interface. Indicates that the object has encountered an error condition due to failure of input validation. For instance, a form control may acquire this state in response to invalid or malformed user input. Indicates that the object in question implements some form of ¨typeahead¨ or pre-selection behavior whereby entering the first character of one or more sub-elements causes those elements to scroll into view or become selected. Subsequent character input may narrow the selection further as long as one or more sub-elements match the string. This state is normally only useful and encountered on objects that implement Selection. In some cases the typeahead behavior may result in full or partial ¨completion¨ of the data in the input field, in which case these input events may trigger text-changed events from the AtkText interface. This state supplants @ATK_ROLE_AUTOCOMPLETE. Indicates that the object in question supports text selection. It should only be exposed on objects which implement the Text interface, in order to distinguish this state from @ATK_STATE_SELECTABLE, which infers that the object in question is a selectable child of an object which implements Selection. While similar, text selection and subelement selection are distinct operations. Indicates that the object is the "default" active component, i.e. the object which is activated by an end-user press of the "Enter" or "Return" key. Typically a "close" or "submit" button. Indicates that the object changes its appearance dynamically as an inherent part of its presentation. This state may come and go if an object is only temporarily animated on the way to a 'final' onscreen presentation. **note**: some applications, notably content viewers, may not be able to detect all kinds of animated content. Therefore the absence of this state should not be taken as definitive evidence that the object's visual representation is static; this state is advisory. Indicates that the object (typically a hyperlink) has already been 'activated', and/or its backing data has already been downloaded, rendered, or otherwise "visited". Indicates this object has the potential to be checked, such as a checkbox or toggle-able table cell. @Since: ATK-2.12 Indicates that the object has a popup context menu or sub-level menu which may or may not be showing. This means that activation renders conditional content. Note that ordinary tooltips are not considered popups in this context. @Since: ATK-2.12 Indicates this object has a tooltip. @Since: ATK-2.16 Indicates that a widget which is ENABLED and SENSITIVE has a value which can be read, but not modified, by the user. Note that this state should only be applied to widget types whose value is normally directly user modifiable, such as check boxes, radio buttons, spin buttons, text input fields, and combo boxes, as a means to convey that the expected interaction with that widget is not possible. When the expected interaction with a widget does not include modification by the user, as is the case with labels and containers, ATK_STATE_READ_ONLY should not be applied. See also ATK_STATE_EDITABLE. @Since: ATK-2-16 Indicates this object is collapsed. @Since: ATK-2.38 Not a valid state, used for finding end of enumeration Gets the #AtkStateType corresponding to the description string @name. an #AtkStateType corresponding to @name a character string state name Gets the description string describing the #AtkStateType @type. the string describing the AtkStateType The #AtkStateType whose name is required Register a new object state. an #AtkState value for the new state. a character string describing the new state. The ATK interface which provides access to streamable content. An interface whereby an object allows its backing content to be streamed to clients. Typical implementors would be images or icons, HTML content, or multimedia display/rendering widgets. Negotiation of content type is allowed. Clients may examine the backing data and transform, convert, or parse the content in order to present it in an alternate form to end-users. The AtkStreamableContent interface is particularly useful for saving, printing, or post-processing entire documents, or for persisting alternate views of a document. If document content itself is being serialized, stored, or converted, then use of the AtkStreamableContent interface can help address performance issues. Unlike most ATK interfaces, this interface is not strongly tied to the current user-agent view of the a particular document, but may in some cases give access to the underlying model data. Gets the character string of the specified mime type. The first mime type is at position 0, the second at position 1, and so on. a gchar* representing the specified mime type; the caller should not free the character string. a GObject instance that implements AtkStreamableContent a gint representing the position of the mime type starting from 0 Gets the number of mime types supported by this object. a gint which is the number of mime types supported by the object. a GObject instance that implements AtkStreamableContentIface Gets the content in the specified mime type. A #GIOChannel which contains the content in the specified mime type. a GObject instance that implements AtkStreamableContentIface a gchar* representing the mime type Get a string representing a URI in IETF standard format (see http://www.ietf.org/rfc/rfc2396.txt) from which the object's content may be streamed in the specified mime-type, if one is available. If mime_type is NULL, the URI for the default (and possibly only) mime-type is returned. Note that it is possible for get_uri to return NULL but for get_stream to work nonetheless, since not all GIOChannels connect to URIs. Returns a string representing a URI, or %NULL if no corresponding URI can be constructed. a GObject instance that implements AtkStreamableContentIface a gchar* representing the mime type, or NULL to request a URI for the default mime type. Gets the character string of the specified mime type. The first mime type is at position 0, the second at position 1, and so on. a gchar* representing the specified mime type; the caller should not free the character string. a GObject instance that implements AtkStreamableContent a gint representing the position of the mime type starting from 0 Gets the number of mime types supported by this object. a gint which is the number of mime types supported by the object. a GObject instance that implements AtkStreamableContentIface Gets the content in the specified mime type. A #GIOChannel which contains the content in the specified mime type. a GObject instance that implements AtkStreamableContentIface a gchar* representing the mime type Get a string representing a URI in IETF standard format (see http://www.ietf.org/rfc/rfc2396.txt) from which the object's content may be streamed in the specified mime-type, if one is available. If mime_type is NULL, the URI for the default (and possibly only) mime-type is returned. Note that it is possible for get_uri to return NULL but for get_stream to work nonetheless, since not all GIOChannels connect to URIs. Returns a string representing a URI, or %NULL if no corresponding URI can be constructed. a GObject instance that implements AtkStreamableContentIface a gchar* representing the mime type, or NULL to request a URI for the default mime type. a gint which is the number of mime types supported by the object. a GObject instance that implements AtkStreamableContentIface a gchar* representing the specified mime type; the caller should not free the character string. a GObject instance that implements AtkStreamableContent a gint representing the position of the mime type starting from 0 A #GIOChannel which contains the content in the specified mime type. a GObject instance that implements AtkStreamableContentIface a gchar* representing the mime type Returns a string representing a URI, or %NULL if no corresponding URI can be constructed. a GObject instance that implements AtkStreamableContentIface a gchar* representing the mime type, or NULL to request a URI for the default mime type. The ATK interface implemented for UI components which contain tabular or row/column information. #AtkTable should be implemented by components which present elements ordered via rows and columns. It may also be used to present tree-structured information if the nodes of the trees can be said to contain multiple "columns". Individual elements of an #AtkTable are typically referred to as "cells". Those cells should implement the interface #AtkTableCell, but #Atk doesn't require them to be direct children of the current #AtkTable. They can be grand-children, grand-grand-children etc. #AtkTable provides the API needed to get a individual cell based on the row and column numbers. Children of #AtkTable are frequently "lightweight" objects, that is, they may not have backing widgets in the host UI toolkit. They are therefore often transient. Since tables are often very complex, #AtkTable includes provision for offering simplified summary information, as well as row and column headers and captions. Headers and captions are #AtkObjects which may implement other interfaces (#AtkText, #AtkImage, etc.) as appropriate. #AtkTable summaries may themselves be (simplified) #AtkTables, etc. Note for implementors: in the past, #AtkTable required that all the cells should be direct children of #AtkTable, and provided some index based methods to request the cells. The practice showed that that forcing made #AtkTable implementation complex, and hard to expose other kind of children, like rows or captions. Right now, index-based methods are deprecated. Adds the specified @column to the selection. a gboolean representing if the column was successfully added to the selection, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in @table Adds the specified @row to the selection. a gboolean representing if row was successfully added to selection, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table Gets the caption for the @table. a AtkObject* representing the table caption, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableInterface Gets a #gint representing the column at the specified @index_. Since 2.12. a gint representing the column at the specified index, or -1 if the table does not implement this method. a GObject instance that implements AtkTableInterface a #gint representing an index in @table Gets the description text of the specified @column in the table a gchar* representing the column description, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in @table Gets the number of columns occupied by the accessible object at the specified @row and @column in the @table. a gint representing the column extent at specified position, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table Gets the column header of a specified column in an accessible table. a AtkObject* representing the specified column header, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in the table Gets a #gint representing the index at the specified @row and @column. Since 2.12. Use atk_table_ref_at() in order to get the accessible that represents the cell at (@row, @column) a #gint representing the index at specified position. The value -1 is returned if the object at row,column is not a child of table or table does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table Gets the number of columns in the table. a gint representing the number of columns, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface Gets the number of rows in the table. a gint representing the number of rows, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface Gets a #gint representing the row at the specified @index_. since 2.12. a gint representing the row at the specified index, or -1 if the table does not implement this method. a GObject instance that implements AtkTableInterface a #gint representing an index in @table Gets the description text of the specified row in the table a gchar* representing the row description, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table Gets the number of rows occupied by the accessible object at a specified @row and @column in the @table. a gint representing the row extent at specified position, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table Gets the row header of a specified row in an accessible table. a AtkObject* representing the specified row header, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in the table Gets the selected columns of the table by initializing **selected with the selected column numbers. This array should be freed by the caller. a gint representing the number of selected columns, or %0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint** that is to contain the selected columns numbers Gets the selected rows of the table by initializing **selected with the selected row numbers. This array should be freed by the caller. a gint representing the number of selected rows, or zero if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint** that is to contain the selected row numbers Gets the summary description of the table. a AtkObject* representing a summary description of the table, or zero if value does not implement this interface. a GObject instance that implements AtkTableIface Gets a boolean value indicating whether the specified @column is selected a gboolean representing if the column is selected, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in @table Gets a boolean value indicating whether the specified @row is selected a gboolean representing if the row is selected, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table Gets a boolean value indicating whether the accessible object at the specified @row and @column is selected a gboolean representing if the cell is selected, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table Get a reference to the table cell at @row, @column. This cell should implement the interface #AtkTableCell an #AtkObject representing the referred to accessible a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table Adds the specified @column to the selection. a gboolean representing if the column was successfully removed from the selection, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in @table Removes the specified @row from the selection. a gboolean representing if the row was successfully removed from the selection, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table Sets the caption for the table. a GObject instance that implements AtkTableIface a #AtkObject representing the caption to set for @table Sets the description text for the specified @column of the @table. a GObject instance that implements AtkTableIface a #gint representing a column in @table a #gchar representing the description text to set for the specified @column of the @table Sets the specified column header to @header. a GObject instance that implements AtkTableIface a #gint representing a column in @table an #AtkTable Sets the description text for the specified @row of @table. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gchar representing the description text to set for the specified @row of @table Sets the specified row header to @header. a GObject instance that implements AtkTableIface a #gint representing a row in @table an #AtkTable Sets the summary description of the table. a GObject instance that implements AtkTableIface an #AtkObject representing the summary description to set for @table Adds the specified @column to the selection. a gboolean representing if the column was successfully added to the selection, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in @table Adds the specified @row to the selection. a gboolean representing if row was successfully added to selection, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table Gets the caption for the @table. a AtkObject* representing the table caption, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableInterface Gets a #gint representing the column at the specified @index_. Since 2.12. a gint representing the column at the specified index, or -1 if the table does not implement this method. a GObject instance that implements AtkTableInterface a #gint representing an index in @table Gets the description text of the specified @column in the table a gchar* representing the column description, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in @table Gets the number of columns occupied by the accessible object at the specified @row and @column in the @table. a gint representing the column extent at specified position, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table Gets the column header of a specified column in an accessible table. a AtkObject* representing the specified column header, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in the table Gets a #gint representing the index at the specified @row and @column. Since 2.12. Use atk_table_ref_at() in order to get the accessible that represents the cell at (@row, @column) a #gint representing the index at specified position. The value -1 is returned if the object at row,column is not a child of table or table does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table Gets the number of columns in the table. a gint representing the number of columns, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface Gets the number of rows in the table. a gint representing the number of rows, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface Gets a #gint representing the row at the specified @index_. since 2.12. a gint representing the row at the specified index, or -1 if the table does not implement this method. a GObject instance that implements AtkTableInterface a #gint representing an index in @table Gets the description text of the specified row in the table a gchar* representing the row description, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table Gets the number of rows occupied by the accessible object at a specified @row and @column in the @table. a gint representing the row extent at specified position, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table Gets the row header of a specified row in an accessible table. a AtkObject* representing the specified row header, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in the table Gets the selected columns of the table by initializing **selected with the selected column numbers. This array should be freed by the caller. a gint representing the number of selected columns, or %0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint** that is to contain the selected columns numbers Gets the selected rows of the table by initializing **selected with the selected row numbers. This array should be freed by the caller. a gint representing the number of selected rows, or zero if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint** that is to contain the selected row numbers Gets the summary description of the table. a AtkObject* representing a summary description of the table, or zero if value does not implement this interface. a GObject instance that implements AtkTableIface Gets a boolean value indicating whether the specified @column is selected a gboolean representing if the column is selected, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in @table Gets a boolean value indicating whether the specified @row is selected a gboolean representing if the row is selected, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table Gets a boolean value indicating whether the accessible object at the specified @row and @column is selected a gboolean representing if the cell is selected, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table Get a reference to the table cell at @row, @column. This cell should implement the interface #AtkTableCell an #AtkObject representing the referred to accessible a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table Adds the specified @column to the selection. a gboolean representing if the column was successfully removed from the selection, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in @table Removes the specified @row from the selection. a gboolean representing if the row was successfully removed from the selection, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table Sets the caption for the table. a GObject instance that implements AtkTableIface a #AtkObject representing the caption to set for @table Sets the description text for the specified @column of the @table. a GObject instance that implements AtkTableIface a #gint representing a column in @table a #gchar representing the description text to set for the specified @column of the @table Sets the specified column header to @header. a GObject instance that implements AtkTableIface a #gint representing a column in @table an #AtkTable Sets the description text for the specified @row of @table. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gchar representing the description text to set for the specified @row of @table Sets the specified row header to @header. a GObject instance that implements AtkTableIface a #gint representing a row in @table an #AtkTable Sets the summary description of the table. a GObject instance that implements AtkTableIface an #AtkObject representing the summary description to set for @table The "column-deleted" signal is emitted by an object which implements the AtkTable interface when a column is deleted. The index of the first column deleted. The number of columns deleted. The "column-inserted" signal is emitted by an object which implements the AtkTable interface when a column is inserted. The index of the column inserted. The number of colums inserted. The "column-reordered" signal is emitted by an object which implements the AtkTable interface when the columns are reordered. The "model-changed" signal is emitted by an object which implements the AtkTable interface when the model displayed by the table changes. The "row-deleted" signal is emitted by an object which implements the AtkTable interface when a row is deleted. The index of the first row deleted. The number of rows deleted. The "row-inserted" signal is emitted by an object which implements the AtkTable interface when a row is inserted. The index of the first row inserted. The number of rows inserted. The "row-reordered" signal is emitted by an object which implements the AtkTable interface when the rows are reordered. The ATK interface implemented for a cell inside a two-dimentional #AtkTable Being #AtkTable a component which present elements ordered via rows and columns, an #AtkTableCell is the interface which each of those elements, so "cells" should implement. See [iface@AtkTable] Returns the column headers as an array of cell accessibles. a GPtrArray of AtkObjects representing the column header cells. a GObject instance that implements AtkTableCellIface Returns the number of columns occupied by this cell accessible. a gint representing the number of columns occupied by this cell, or 0 if the cell does not implement this method. a GObject instance that implements AtkTableCellIface Retrieves the tabular position of this cell. TRUE if successful; FALSE otherwise. a GObject instance that implements AtkTableCellIface the row of the given cell. the column of the given cell. Gets the row and column indexes and span of this cell accessible. Note: If the object does not implement this function, then, by default, atk will implement this function by calling get_row_span and get_column_span on the object. TRUE if successful; FALSE otherwise. a GObject instance that implements AtkTableCellIface the row index of the given cell. the column index of the given cell. the number of rows occupied by this cell. the number of columns occupied by this cell. Returns the row headers as an array of cell accessibles. a GPtrArray of AtkObjects representing the row header cells. a GObject instance that implements AtkTableCellIface Returns the number of rows occupied by this cell accessible. a gint representing the number of rows occupied by this cell, or 0 if the cell does not implement this method. a GObject instance that implements AtkTableCellIface Returns a reference to the accessible of the containing table. the atk object for the containing table. a GObject instance that implements AtkTableCellIface Returns the column headers as an array of cell accessibles. a GPtrArray of AtkObjects representing the column header cells. a GObject instance that implements AtkTableCellIface Returns the number of columns occupied by this cell accessible. a gint representing the number of columns occupied by this cell, or 0 if the cell does not implement this method. a GObject instance that implements AtkTableCellIface Retrieves the tabular position of this cell. TRUE if successful; FALSE otherwise. a GObject instance that implements AtkTableCellIface the row of the given cell. the column of the given cell. Gets the row and column indexes and span of this cell accessible. Note: If the object does not implement this function, then, by default, atk will implement this function by calling get_row_span and get_column_span on the object. TRUE if successful; FALSE otherwise. a GObject instance that implements AtkTableCellIface the row index of the given cell. the column index of the given cell. the number of rows occupied by this cell. the number of columns occupied by this cell. Returns the row headers as an array of cell accessibles. a GPtrArray of AtkObjects representing the row header cells. a GObject instance that implements AtkTableCellIface Returns the number of rows occupied by this cell accessible. a gint representing the number of rows occupied by this cell, or 0 if the cell does not implement this method. a GObject instance that implements AtkTableCellIface Returns a reference to the accessible of the containing table. the atk object for the containing table. a GObject instance that implements AtkTableCellIface AtkTableCell is an interface for cells inside an #AtkTable. virtual function that returns the number of columns occupied by this cell accessible a gint representing the number of columns occupied by this cell, or 0 if the cell does not implement this method. a GObject instance that implements AtkTableCellIface virtual function that returns the column headers as an array of cell accessibles a GPtrArray of AtkObjects representing the column header cells. a GObject instance that implements AtkTableCellIface virtual function that retrieves the tabular position of this cell TRUE if successful; FALSE otherwise. a GObject instance that implements AtkTableCellIface the row of the given cell. the column of the given cell. virtual function that returns the number of rows occupied by this cell a gint representing the number of rows occupied by this cell, or 0 if the cell does not implement this method. a GObject instance that implements AtkTableCellIface virtual function that returns the row headers as an array of cell accessibles a GPtrArray of AtkObjects representing the row header cells. a GObject instance that implements AtkTableCellIface virtual function that get the row an column indexes and span of this cell TRUE if successful; FALSE otherwise. a GObject instance that implements AtkTableCellIface the row index of the given cell. the column index of the given cell. the number of rows occupied by this cell. the number of columns occupied by this cell. virtual function that returns a reference to the accessible of the containing table the atk object for the containing table. a GObject instance that implements AtkTableCellIface an #AtkObject representing the referred to accessible a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table a #gint representing the index at specified position. The value -1 is returned if the object at row,column is not a child of table or table does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table a gint representing the column at the specified index, or -1 if the table does not implement this method. a GObject instance that implements AtkTableInterface a #gint representing an index in @table a gint representing the row at the specified index, or -1 if the table does not implement this method. a GObject instance that implements AtkTableInterface a #gint representing an index in @table a gint representing the number of columns, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a gint representing the number of rows, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a gint representing the column extent at specified position, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table a gint representing the row extent at specified position, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table a AtkObject* representing the table caption, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableInterface a gchar* representing the column description, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in @table a AtkObject* representing the specified column header, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in the table a gchar* representing the row description, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a AtkObject* representing the specified row header, or %NULL if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in the table a AtkObject* representing a summary description of the table, or zero if value does not implement this interface. a GObject instance that implements AtkTableIface a GObject instance that implements AtkTableIface a #AtkObject representing the caption to set for @table a GObject instance that implements AtkTableIface a #gint representing a column in @table a #gchar representing the description text to set for the specified @column of the @table a GObject instance that implements AtkTableIface a #gint representing a column in @table an #AtkTable a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gchar representing the description text to set for the specified @row of @table a GObject instance that implements AtkTableIface a #gint representing a row in @table an #AtkTable a GObject instance that implements AtkTableIface an #AtkObject representing the summary description to set for @table a gint representing the number of selected columns, or %0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint** that is to contain the selected columns numbers a gint representing the number of selected rows, or zero if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint** that is to contain the selected row numbers a gboolean representing if the column is selected, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in @table a gboolean representing if the row is selected, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a gboolean representing if the cell is selected, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a #gint representing a column in @table a gboolean representing if row was successfully added to selection, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a gboolean representing if the row was successfully removed from the selection, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a row in @table a gboolean representing if the column was successfully added to the selection, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in @table a gboolean representing if the column was successfully removed from the selection, or 0 if value does not implement this interface. a GObject instance that implements AtkTableIface a #gint representing a column in @table The ATK interface implemented by components with text content. #AtkText should be implemented by #AtkObjects on behalf of widgets that have text content which is either attributed or otherwise non-trivial. #AtkObjects whose text content is simple, unattributed, and very brief may expose that content via #atk_object_get_name instead; however if the text is editable, multi-line, typically longer than three or four words, attributed, selectable, or if the object already uses the 'name' ATK property for other information, the #AtkText interface should be used to expose the text content. In the case of editable text content, #AtkEditableText (a subtype of the #AtkText interface) should be implemented instead. #AtkText provides not only traversal facilities and change notification for text content, but also caret tracking and glyph bounding box calculations. Note that the text strings are exposed as UTF-8, and are therefore potentially multi-byte, and caret-to-byte offset mapping makes no assumptions about the character length; also bounding box glyph-to-offset mapping may be complex for languages which use ligatures. Frees the memory associated with an array of AtkTextRange. It is assumed that the array was returned by the function atk_text_get_bounded_ranges and is NULL terminated. A pointer to an array of #AtkTextRange which is to be freed. Adds a selection bounded by the specified offsets. %TRUE if successful, %FALSE otherwise an #AtkText the starting character offset of the selected region the offset of the first character after the selected region. Get the ranges of text in the specified bounding box. Array of AtkTextRange. The last element of the array returned by this function will be NULL. an #AtkText An AtkTextRectangle giving the dimensions of the bounding box. Specify whether coordinates are relative to the screen or widget window. Specify the horizontal clip type. Specify the vertical clip type. Gets the offset of the position of the caret (cursor). the character offset of the position of the caret or -1 if the caret is not located inside the element or in the case of any other failure. an #AtkText Gets the specified text. the character at @offset or 0 in the case of failure. an #AtkText a character offset within @text Gets the character count. the number of characters or -1 in case of failure. an #AtkText If the extent can not be obtained (e.g. missing support), all of x, y, width, height are set to -1. Get the bounding box containing the glyph representing the character at a particular text offset. an #AtkText The offset of the text character for which bounding information is required. Pointer for the x coordinate of the bounding box Pointer for the y coordinate of the bounding box Pointer for the width of the bounding box Pointer for the height of the bounding box specify whether coordinates are relative to the screen or widget window Creates an #AtkAttributeSet which consists of the default values of attributes for the text. See the enum AtkTextAttribute for types of text attributes that can be returned. Note that other attributes may also be returned. an #AtkAttributeSet which contains the default text attributes for this #AtkText. This #AtkAttributeSet should be freed by a call to atk_attribute_set_free(). an #AtkText Gets the number of selected regions. The number of selected regions, or -1 in the case of failure. an #AtkText Gets the offset of the character located at coordinates @x and @y. @x and @y are interpreted as being relative to the screen or this widget's window depending on @coords. the offset to the character which is located at the specified @x and @y coordinates of -1 in case of failure. an #AtkText screen x-position of character screen y-position of character specify whether coordinates are relative to the screen or widget window Get the bounding box for text within the specified range. If the extents can not be obtained (e.g. or missing support), the rectangle fields are set to -1. an #AtkText The offset of the first text character for which boundary information is required. The offset of the text character after the last character for which boundary information is required. Specify whether coordinates are relative to the screen or widget window. A pointer to a AtkTextRectangle which is filled in by this function. Creates an #AtkAttributeSet which consists of the attributes explicitly set at the position @offset in the text. @start_offset and @end_offset are set to the start and end of the range around @offset where the attributes are invariant. Note that @end_offset is the offset of the first character after the range. See the enum AtkTextAttribute for types of text attributes that can be returned. Note that other attributes may also be returned. an #AtkAttributeSet which contains the attributes explicitly set at @offset. This #AtkAttributeSet should be freed by a call to atk_attribute_set_free(). an #AtkText the character offset at which to get the attributes, -1 means the offset of the character to be inserted at the caret location. the address to put the start offset of the range the address to put the end offset of the range Gets the text from the specified selection. a newly allocated string containing the selected text. Use g_free() to free the returned string. an #AtkText The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering. passes back the starting character offset of the selected region passes back the ending character offset (offset immediately past) of the selected region Gets a portion of the text exposed through an #AtkText according to a given @offset and a specific @granularity, along with the start and end offsets defining the boundaries of such a portion of text. If @granularity is ATK_TEXT_GRANULARITY_CHAR the character at the offset is returned. If @granularity is ATK_TEXT_GRANULARITY_WORD the returned string is from the word start at or before the offset to the word start after the offset. The returned string will contain the word at the offset if the offset is inside a word and will contain the word before the offset if the offset is not inside a word. If @granularity is ATK_TEXT_GRANULARITY_SENTENCE the returned string is from the sentence start at or before the offset to the sentence start after the offset. The returned string will contain the sentence at the offset if the offset is inside a sentence and will contain the sentence before the offset if the offset is not inside a sentence. If @granularity is ATK_TEXT_GRANULARITY_LINE the returned string is from the line start at or before the offset to the line start after the offset. If @granularity is ATK_TEXT_GRANULARITY_PARAGRAPH the returned string is from the start of the paragraph at or before the offset to the start of the following paragraph after the offset. a newly allocated string containing the text at the @offset bounded by the specified @granularity. Use g_free() to free the returned string. Returns %NULL if the offset is invalid or no implementation is available. an #AtkText position An #AtkTextGranularity the starting character offset of the returned string, or -1 in the case of error (e.g. invalid offset, not implemented) the offset of the first character after the returned string, or -1 in the case of error (e.g. invalid offset, not implemented) Gets the specified text. a newly allocated string containing the text from @start_offset up to, but not including @end_offset. Use g_free() to free the returned string. an #AtkText a starting character offset within @text an ending character offset within @text, or -1 for the end of the string. Gets the specified text. Please use atk_text_get_string_at_offset() instead. a newly allocated string containing the text after @offset bounded by the specified @boundary_type. Use g_free() to free the returned string. an #AtkText position An #AtkTextBoundary the starting character offset of the returned string the offset of the first character after the returned substring Gets the specified text. If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character at the offset is returned. If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string is from the word start at or before the offset to the word start after the offset. The returned string will contain the word at the offset if the offset is inside a word and will contain the word before the offset if the offset is not inside a word. If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned string is from the sentence start at or before the offset to the sentence start after the offset. The returned string will contain the sentence at the offset if the offset is inside a sentence and will contain the sentence before the offset if the offset is not inside a sentence. If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned string is from the line start at or before the offset to the line start after the offset. This method is deprecated since ATK version 2.9.4. Please use atk_text_get_string_at_offset() instead. a newly allocated string containing the text at @offset bounded by the specified @boundary_type. Use g_free() to free the returned string. an #AtkText position An #AtkTextBoundary the starting character offset of the returned string the offset of the first character after the returned substring Gets the specified text. Please use atk_text_get_string_at_offset() instead. a newly allocated string containing the text before @offset bounded by the specified @boundary_type. Use g_free() to free the returned string. an #AtkText position An #AtkTextBoundary the starting character offset of the returned string the offset of the first character after the returned substring Removes the specified selection. %TRUE if successful, %FALSE otherwise an #AtkText The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering. Makes a substring of @text visible on the screen by scrolling all necessary parents. whether scrolling was successful. an #AtkText start offset in the @text end offset in the @text, or -1 for the end of the text. specify where the object should be made visible. Move the top-left of a substring of @text to a given position of the screen by scrolling all necessary parents. whether scrolling was successful. an #AtkText start offset in the @text end offset in the @text, or -1 for the end of the text. specify whether coordinates are relative to the screen or to the parent object. x-position where to scroll to y-position where to scroll to Sets the caret (cursor) position to the specified @offset. In the case of rich-text content, this method should either grab focus or move the sequential focus navigation starting point (if the application supports this concept) as if the user had clicked on the new caret position. Typically, this means that the target of this operation is the node containing the new caret position or one of its ancestors. In other words, after this method is called, if the user advances focus, it should move to the first focusable node following the new caret position. Calling this method should also scroll the application viewport in a way that matches the behavior of the application's typical caret motion or tab navigation as closely as possible. This also means that if the application's caret motion or focus navigation does not trigger a scroll operation, this method should not trigger one either. If the application does not have a caret motion or focus navigation operation, this method should try to scroll the new caret position into view while minimizing unnecessary scroll motion. %TRUE if successful, %FALSE otherwise. an #AtkText the character offset of the new caret position Changes the start and end offset of the specified selection. %TRUE if successful, %FALSE otherwise an #AtkText The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering. the new starting character offset of the selection the new end position of (e.g. offset immediately past) the selection the signal handler which is executed when there is a text change. This virtual function is deprecated sice 2.9.4 and it should not be overriden. Adds a selection bounded by the specified offsets. %TRUE if successful, %FALSE otherwise an #AtkText the starting character offset of the selected region the offset of the first character after the selected region. Get the ranges of text in the specified bounding box. Array of AtkTextRange. The last element of the array returned by this function will be NULL. an #AtkText An AtkTextRectangle giving the dimensions of the bounding box. Specify whether coordinates are relative to the screen or widget window. Specify the horizontal clip type. Specify the vertical clip type. Gets the offset of the position of the caret (cursor). the character offset of the position of the caret or -1 if the caret is not located inside the element or in the case of any other failure. an #AtkText Gets the specified text. the character at @offset or 0 in the case of failure. an #AtkText a character offset within @text Gets the character count. the number of characters or -1 in case of failure. an #AtkText If the extent can not be obtained (e.g. missing support), all of x, y, width, height are set to -1. Get the bounding box containing the glyph representing the character at a particular text offset. an #AtkText The offset of the text character for which bounding information is required. Pointer for the x coordinate of the bounding box Pointer for the y coordinate of the bounding box Pointer for the width of the bounding box Pointer for the height of the bounding box specify whether coordinates are relative to the screen or widget window Creates an #AtkAttributeSet which consists of the default values of attributes for the text. See the enum AtkTextAttribute for types of text attributes that can be returned. Note that other attributes may also be returned. an #AtkAttributeSet which contains the default text attributes for this #AtkText. This #AtkAttributeSet should be freed by a call to atk_attribute_set_free(). an #AtkText Gets the number of selected regions. The number of selected regions, or -1 in the case of failure. an #AtkText Gets the offset of the character located at coordinates @x and @y. @x and @y are interpreted as being relative to the screen or this widget's window depending on @coords. the offset to the character which is located at the specified @x and @y coordinates of -1 in case of failure. an #AtkText screen x-position of character screen y-position of character specify whether coordinates are relative to the screen or widget window Get the bounding box for text within the specified range. If the extents can not be obtained (e.g. or missing support), the rectangle fields are set to -1. an #AtkText The offset of the first text character for which boundary information is required. The offset of the text character after the last character for which boundary information is required. Specify whether coordinates are relative to the screen or widget window. A pointer to a AtkTextRectangle which is filled in by this function. Creates an #AtkAttributeSet which consists of the attributes explicitly set at the position @offset in the text. @start_offset and @end_offset are set to the start and end of the range around @offset where the attributes are invariant. Note that @end_offset is the offset of the first character after the range. See the enum AtkTextAttribute for types of text attributes that can be returned. Note that other attributes may also be returned. an #AtkAttributeSet which contains the attributes explicitly set at @offset. This #AtkAttributeSet should be freed by a call to atk_attribute_set_free(). an #AtkText the character offset at which to get the attributes, -1 means the offset of the character to be inserted at the caret location. the address to put the start offset of the range the address to put the end offset of the range Gets the text from the specified selection. a newly allocated string containing the selected text. Use g_free() to free the returned string. an #AtkText The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering. passes back the starting character offset of the selected region passes back the ending character offset (offset immediately past) of the selected region Gets a portion of the text exposed through an #AtkText according to a given @offset and a specific @granularity, along with the start and end offsets defining the boundaries of such a portion of text. If @granularity is ATK_TEXT_GRANULARITY_CHAR the character at the offset is returned. If @granularity is ATK_TEXT_GRANULARITY_WORD the returned string is from the word start at or before the offset to the word start after the offset. The returned string will contain the word at the offset if the offset is inside a word and will contain the word before the offset if the offset is not inside a word. If @granularity is ATK_TEXT_GRANULARITY_SENTENCE the returned string is from the sentence start at or before the offset to the sentence start after the offset. The returned string will contain the sentence at the offset if the offset is inside a sentence and will contain the sentence before the offset if the offset is not inside a sentence. If @granularity is ATK_TEXT_GRANULARITY_LINE the returned string is from the line start at or before the offset to the line start after the offset. If @granularity is ATK_TEXT_GRANULARITY_PARAGRAPH the returned string is from the start of the paragraph at or before the offset to the start of the following paragraph after the offset. a newly allocated string containing the text at the @offset bounded by the specified @granularity. Use g_free() to free the returned string. Returns %NULL if the offset is invalid or no implementation is available. an #AtkText position An #AtkTextGranularity the starting character offset of the returned string, or -1 in the case of error (e.g. invalid offset, not implemented) the offset of the first character after the returned string, or -1 in the case of error (e.g. invalid offset, not implemented) Gets the specified text. a newly allocated string containing the text from @start_offset up to, but not including @end_offset. Use g_free() to free the returned string. an #AtkText a starting character offset within @text an ending character offset within @text, or -1 for the end of the string. Gets the specified text. Please use atk_text_get_string_at_offset() instead. a newly allocated string containing the text after @offset bounded by the specified @boundary_type. Use g_free() to free the returned string. an #AtkText position An #AtkTextBoundary the starting character offset of the returned string the offset of the first character after the returned substring Gets the specified text. If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character at the offset is returned. If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string is from the word start at or before the offset to the word start after the offset. The returned string will contain the word at the offset if the offset is inside a word and will contain the word before the offset if the offset is not inside a word. If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned string is from the sentence start at or before the offset to the sentence start after the offset. The returned string will contain the sentence at the offset if the offset is inside a sentence and will contain the sentence before the offset if the offset is not inside a sentence. If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned string is from the line start at or before the offset to the line start after the offset. This method is deprecated since ATK version 2.9.4. Please use atk_text_get_string_at_offset() instead. a newly allocated string containing the text at @offset bounded by the specified @boundary_type. Use g_free() to free the returned string. an #AtkText position An #AtkTextBoundary the starting character offset of the returned string the offset of the first character after the returned substring Gets the specified text. Please use atk_text_get_string_at_offset() instead. a newly allocated string containing the text before @offset bounded by the specified @boundary_type. Use g_free() to free the returned string. an #AtkText position An #AtkTextBoundary the starting character offset of the returned string the offset of the first character after the returned substring Removes the specified selection. %TRUE if successful, %FALSE otherwise an #AtkText The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering. Makes a substring of @text visible on the screen by scrolling all necessary parents. whether scrolling was successful. an #AtkText start offset in the @text end offset in the @text, or -1 for the end of the text. specify where the object should be made visible. Move the top-left of a substring of @text to a given position of the screen by scrolling all necessary parents. whether scrolling was successful. an #AtkText start offset in the @text end offset in the @text, or -1 for the end of the text. specify whether coordinates are relative to the screen or to the parent object. x-position where to scroll to y-position where to scroll to Sets the caret (cursor) position to the specified @offset. In the case of rich-text content, this method should either grab focus or move the sequential focus navigation starting point (if the application supports this concept) as if the user had clicked on the new caret position. Typically, this means that the target of this operation is the node containing the new caret position or one of its ancestors. In other words, after this method is called, if the user advances focus, it should move to the first focusable node following the new caret position. Calling this method should also scroll the application viewport in a way that matches the behavior of the application's typical caret motion or tab navigation as closely as possible. This also means that if the application's caret motion or focus navigation does not trigger a scroll operation, this method should not trigger one either. If the application does not have a caret motion or focus navigation operation, this method should try to scroll the new caret position into view while minimizing unnecessary scroll motion. %TRUE if successful, %FALSE otherwise. an #AtkText the character offset of the new caret position Changes the start and end offset of the specified selection. %TRUE if successful, %FALSE otherwise an #AtkText The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering. the new starting character offset of the selection the new end position of (e.g. offset immediately past) the selection The "text-attributes-changed" signal is emitted when the text attributes of the text of an object which implements AtkText changes. The "text-caret-moved" signal is emitted when the caret position of the text of an object which implements AtkText changes. The new position of the text caret. The "text-changed" signal is emitted when the text of the object which implements the AtkText interface changes, This signal will have a detail which is either "insert" or "delete" which identifies whether the text change was an insertion or a deletion. Use #AtkObject::text-insert or #AtkObject::text-remove instead. The position (character offset) of the insertion or deletion. The length (in characters) of text inserted or deleted. The "text-insert" signal is emitted when a new text is inserted. If the signal was not triggered by the user (e.g. typing or pasting text), the "system" detail should be included. The position (character offset) of the insertion. The length (in characters) of text inserted. The new text inserted The "text-remove" signal is emitted when a new text is removed. If the signal was not triggered by the user (e.g. typing or pasting text), the "system" detail should be included. The position (character offset) of the removal. The length (in characters) of text removed. The old text removed The "text-selection-changed" signal is emitted when the selected text of an object which implements AtkText changes. Describes the text attributes supported Invalid attribute, like bad spelling or grammar. The pixel width of the left margin The pixel width of the right margin The number of pixels that the text is indented Either "true" or "false" indicating whether text is visible or not Either "true" or "false" indicating whether text is editable or not Pixels of blank space to leave above each newline-terminated line. Pixels of blank space to leave below each newline-terminated line. Pixels of blank space to leave between wrapped lines inside the same newline-terminated line (paragraph). "true" or "false" whether to make the background color for each character the height of the highest font used on the current line, or the height of the font used for the current character. Number of pixels that the characters are risen above the baseline. See also ATK_TEXT_ATTR_TEXT_POSITION. "none", "single", "double", "low", or "error" "true" or "false" whether the text is strikethrough The size of the characters in points. eg: 10 The scale of the characters. The value is a string representation of a double The weight of the characters. The language used The font family name The background color. The value is an RGB value of the format "%u,%u,%u" The foreground color. The value is an RGB value of the format "%u,%u,%u" "true" if a #GdkBitmap is set for stippling the background color. "true" if a #GdkBitmap is set for stippling the foreground color. The wrap mode of the text, if any. Values are "none", "char", "word", or "word_char". The direction of the text, if set. Values are "none", "ltr" or "rtl" The justification of the text, if set. Values are "left", "right", "center" or "fill" The stretch of the text, if set. Values are "ultra_condensed", "extra_condensed", "condensed", "semi_condensed", "normal", "semi_expanded", "expanded", "extra_expanded" or "ultra_expanded" The capitalization variant of the text, if set. Values are "normal" or "small_caps" The slant style of the text, if set. Values are "normal", "oblique" or "italic" The vertical position with respect to the baseline. Values are "baseline", "super", or "sub". Note that a super or sub text attribute refers to position with respect to the baseline of the prior character. not a valid text attribute, used for finding end of enumeration Get the #AtkTextAttribute type corresponding to a text attribute name. the #AtkTextAttribute enumerated type corresponding to the specified name, or #ATK_TEXT_ATTRIBUTE_INVALID if no matching text attribute is found. a string which is the (non-localized) name of an ATK text attribute. Gets the name corresponding to the #AtkTextAttribute a string containing the name; this string should not be freed The #AtkTextAttribute whose name is required Gets the value for the index of the #AtkTextAttribute a string containing the value; this string should not be freed; %NULL is returned if there are no values maintained for the attr value. The #AtkTextAttribute for which a value is required The index of the required value Associate @name with a new #AtkTextAttribute an #AtkTextAttribute associated with @name a name string Text boundary types used for specifying boundaries for regions of text. This enumeration is deprecated since 2.9.4 and should not be used. Use AtkTextGranularity with #atk_text_get_string_at_offset instead. Boundary is the boundary between characters (including non-printing characters) Boundary is the start (i.e. first character) of a word. Boundary is the end (i.e. last character) of a word. Boundary is the first character in a sentence. Boundary is the last (terminal) character in a sentence; in languages which use "sentence stop" punctuation such as English, the boundary is thus the '.', '?', or similar terminal punctuation character. Boundary is the initial character of the content or a character immediately following a newline, linefeed, or return character. Boundary is the linefeed, or return character. Describes the type of clipping required. No clipping to be done Text clipped by min coordinate is omitted Text clipped by max coordinate is omitted Only text fully within mix/max bound is retained Text granularity types used for specifying the granularity of the region of text we are interested in. Granularity is defined by the boundaries between characters (including non-printing characters) Granularity is defined by the boundaries of a word, starting at the beginning of the current word and finishing at the beginning of the following one, if present. Granularity is defined by the boundaries of a sentence, starting at the beginning of the current sentence and finishing at the beginning of the following one, if present. Granularity is defined by the boundaries of a line, starting at the beginning of the current line and finishing at the beginning of the following one, if present. Granularity is defined by the boundaries of a paragraph, starting at the beginning of the current paragraph and finishing at the beginning of the following one, if present. a newly allocated string containing the text from @start_offset up to, but not including @end_offset. Use g_free() to free the returned string. an #AtkText a starting character offset within @text an ending character offset within @text, or -1 for the end of the string. Gets specified text. This virtual function is deprecated and it should not be overridden. a newly allocated string containing the text after @offset bounded by the specified @boundary_type. Use g_free() to free the returned string. an #AtkText position An #AtkTextBoundary the starting character offset of the returned string the offset of the first character after the returned substring Gets specified text. This virtual function is deprecated and it should not be overridden. a newly allocated string containing the text at @offset bounded by the specified @boundary_type. Use g_free() to free the returned string. an #AtkText position An #AtkTextBoundary the starting character offset of the returned string the offset of the first character after the returned substring the character at @offset or 0 in the case of failure. an #AtkText a character offset within @text Gets specified text. This virtual function is deprecated and it should not be overridden. a newly allocated string containing the text before @offset bounded by the specified @boundary_type. Use g_free() to free the returned string. an #AtkText position An #AtkTextBoundary the starting character offset of the returned string the offset of the first character after the returned substring the character offset of the position of the caret or -1 if the caret is not located inside the element or in the case of any other failure. an #AtkText an #AtkAttributeSet which contains the attributes explicitly set at @offset. This #AtkAttributeSet should be freed by a call to atk_attribute_set_free(). an #AtkText the character offset at which to get the attributes, -1 means the offset of the character to be inserted at the caret location. the address to put the start offset of the range the address to put the end offset of the range an #AtkAttributeSet which contains the default text attributes for this #AtkText. This #AtkAttributeSet should be freed by a call to atk_attribute_set_free(). an #AtkText an #AtkText The offset of the text character for which bounding information is required. Pointer for the x coordinate of the bounding box Pointer for the y coordinate of the bounding box Pointer for the width of the bounding box Pointer for the height of the bounding box specify whether coordinates are relative to the screen or widget window the number of characters or -1 in case of failure. an #AtkText the offset to the character which is located at the specified @x and @y coordinates of -1 in case of failure. an #AtkText screen x-position of character screen y-position of character specify whether coordinates are relative to the screen or widget window The number of selected regions, or -1 in the case of failure. an #AtkText a newly allocated string containing the selected text. Use g_free() to free the returned string. an #AtkText The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering. passes back the starting character offset of the selected region passes back the ending character offset (offset immediately past) of the selected region %TRUE if successful, %FALSE otherwise an #AtkText the starting character offset of the selected region the offset of the first character after the selected region. %TRUE if successful, %FALSE otherwise an #AtkText The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering. %TRUE if successful, %FALSE otherwise an #AtkText The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering. the new starting character offset of the selection the new end position of (e.g. offset immediately past) the selection %TRUE if successful, %FALSE otherwise. an #AtkText the character offset of the new caret position the signal handler which is executed when there is a text change. This virtual function is deprecated sice 2.9.4 and it should not be overriden. an #AtkText The offset of the first text character for which boundary information is required. The offset of the text character after the last character for which boundary information is required. Specify whether coordinates are relative to the screen or widget window. A pointer to a AtkTextRectangle which is filled in by this function. Array of AtkTextRange. The last element of the array returned by this function will be NULL. an #AtkText An AtkTextRectangle giving the dimensions of the bounding box. Specify whether coordinates are relative to the screen or widget window. Specify the horizontal clip type. Specify the vertical clip type. Gets a portion of the text exposed through an AtkText according to a given offset and a specific granularity, along with the start and end offsets defining the boundaries of such a portion of text. a newly allocated string containing the text at the @offset bounded by the specified @granularity. Use g_free() to free the returned string. Returns %NULL if the offset is invalid or no implementation is available. an #AtkText position An #AtkTextGranularity the starting character offset of the returned string, or -1 in the case of error (e.g. invalid offset, not implemented) the offset of the first character after the returned string, or -1 in the case of error (e.g. invalid offset, not implemented) whether scrolling was successful. an #AtkText start offset in the @text end offset in the @text, or -1 for the end of the text. specify where the object should be made visible. whether scrolling was successful. an #AtkText start offset in the @text end offset in the @text, or -1 for the end of the text. specify whether coordinates are relative to the screen or to the parent object. x-position where to scroll to y-position where to scroll to A structure used to describe a text range. A rectangle giving the bounds of the text range The start offset of a AtkTextRange The end offset of a AtkTextRange The text in the text range A structure used to store a rectangle used by AtkText. The horizontal coordinate of a rectangle The vertical coordinate of a rectangle The width of a rectangle The height of a rectangle This structure represents a single text selection within a document. This selection is defined by two points in the content, where each one is defined by an AtkObject supporting the AtkText interface and a character offset relative to it. The end object must appear after the start object in the accessibility tree, i.e. the end object must be reachable from the start object by navigating forward (next, first child etc). This struct also contains a @start_is_active boolean, to communicate if the start of the selection is the active point or not. The active point corresponds to the user's focus or point of interest. The user moves the active point to expand or collapse the range. The anchor point is the other point of the range and typically remains constant. In most cases, anchor is the start of the range and active is the end. However, when selecting backwards (e.g. pressing shift+left arrow in a text field), the start of the range is the active point, as the user moves this to manipulate the selection. the AtkText containing the start of the selection. the text offset of the beginning of the selection within @start_object. the AtkText containing the end of the selection. the text offset of the end of the selection within @end_object. a gboolean indicating whether the start of the selection is the active point. A set of ATK utility functions for event and toolkit support. A set of ATK utility functions which are used to support event registration of various types, and obtaining the 'root' accessible of a process and information about the current ATK implementation and toolkit version. adds the specified function to the list of functions to be called when an ATK event occurs. ATK implementors are discouraged from reimplementing this method. removes the specified function to the list of functions to be called when an ATK event occurs. ATK implementors are discouraged from reimplementing this method. adds the specified function to the list of functions to be called when a key event occurs. remove the specified function to the list of functions to be called when a key event occurs. gets the root accessible container for the current application. gets name string for the GUI toolkit implementing ATK for this application. gets version string for the GUI toolkit implementing ATK for this application. A macro that should be defined by the user prior to including the atk/atk.h header. The definition should be one of the predefined ATK version macros: %ATK_VERSION_2_12, %ATK_VERSION_2_14,... This macro defines the earliest version of ATK that the package is required to be able to compile against. If the compiler is configured to warn about the use of deprecated functions, then using functions that were deprecated in version %ATK_VERSION_MIN_REQUIRED or earlier will cause warnings (but using functions deprecated in later releases will not). The ATK interface implemented by valuators and components which display or select a value from a bounded range of values. #AtkValue should be implemented for components which either display a value from a bounded range, or which allow the user to specify a value from a bounded range, or both. For instance, most sliders and range controls, as well as dials, should have #AtkObject representations which implement #AtkValue on the component's behalf. #AtKValues may be read-only, in which case attempts to alter the value return would fail. <refsect1 id="current-value-text"> <title>On the subject of current value text</title> <para> In addition to providing the current value, implementors can optionally provide an end-user-consumable textual description associated with this value. This description should be included when the numeric value fails to convey the full, on-screen representation seen by users. </para> <example> <title>Password strength</title> A password strength meter whose value changes as the user types their new password. Red is used for values less than 4.0, yellow for values between 4.0 and 7.0, and green for values greater than 7.0. In this instance, value text should be provided by the implementor. Appropriate value text would be "weak", "acceptable," and "strong" respectively. </example> A level bar whose value changes to reflect the battery charge. The color remains the same regardless of the charge and there is no on-screen text reflecting the fullness of the battery. In this case, because the position within the bar is the only indication the user has of the current charge, value text should not be provided by the implementor. <refsect2 id="implementor-notes"> <title>Implementor Notes</title> <para> Implementors should bear in mind that assistive technologies will likely prefer the value text provided over the numeric value when presenting a widget's value. As a result, strings not intended for end users should not be exposed in the value text, and strings which are exposed should be localized. In the case of widgets which display value text on screen, for instance through a separate label in close proximity to the value-displaying widget, it is still expected that implementors will expose the value text using the above API. </para> <para> #AtkValue should NOT be implemented for widgets whose displayed value is not reflective of a meaningful amount. For instance, a progress pulse indicator whose value alternates between 0.0 and 1.0 to indicate that some process is still taking place should not implement #AtkValue because the current value does not reflect progress towards completion. </para> </refsect2> </refsect1> <refsect1 id="ranges"> <title>On the subject of ranges</title> <para> In addition to providing the minimum and maximum values, implementors can optionally provide details about subranges associated with the widget. These details should be provided by the implementor when both of the following are communicated visually to the end user: </para> <itemizedlist> <listitem>The existence of distinct ranges such as "weak", "acceptable", and "strong" indicated by color, bar tick marks, and/or on-screen text.</listitem> <listitem>Where the current value stands within a given subrange, for instance illustrating progression from very "weak" towards nearly "acceptable" through changes in shade and/or position on the bar within the "weak" subrange.</listitem> </itemizedlist> <para> If both of the above do not apply to the widget, it should be sufficient to expose the numeric value, along with the value text if appropriate, to make the widget accessible. </para> <refsect2 id="ranges-implementor-notes"> <title>Implementor Notes</title> <para> If providing subrange details is deemed necessary, all possible values of the widget are expected to fall within one of the subranges defined by the implementor. </para> </refsect2> </refsect1> <refsect1 id="localization"> <title>On the subject of localization of end-user-consumable text values</title> <para> Because value text and subrange descriptors are human-consumable, implementors are expected to provide localized strings which can be directly presented to end users via their assistive technology. In order to simplify this for implementors, implementors can use atk_value_type_get_localized_name() with the following already-localized constants for commonly-needed values can be used: </para> <itemizedlist> <listitem>ATK_VALUE_VERY_WEAK</listitem> <listitem>ATK_VALUE_WEAK</listitem> <listitem>ATK_VALUE_ACCEPTABLE</listitem> <listitem>ATK_VALUE_STRONG</listitem> <listitem>ATK_VALUE_VERY_STRONG</listitem> <listitem>ATK_VALUE_VERY_LOW</listitem> <listitem>ATK_VALUE_LOW</listitem> <listitem>ATK_VALUE_MEDIUM</listitem> <listitem>ATK_VALUE_HIGH</listitem> <listitem>ATK_VALUE_VERY_HIGH</listitem> <listitem>ATK_VALUE_VERY_BAD</listitem> <listitem>ATK_VALUE_BAD</listitem> <listitem>ATK_VALUE_GOOD</listitem> <listitem>ATK_VALUE_VERY_GOOD</listitem> <listitem>ATK_VALUE_BEST</listitem> <listitem>ATK_VALUE_SUBSUBOPTIMAL</listitem> <listitem>ATK_VALUE_SUBOPTIMAL</listitem> <listitem>ATK_VALUE_OPTIMAL</listitem> </itemizedlist> <para> Proposals for additional constants, along with their use cases, should be submitted to the GNOME Accessibility Team. </para> </refsect1> <refsect1 id="changes"> <title>On the subject of changes</title> <para> Note that if there is a textual description associated with the new numeric value, that description should be included regardless of whether or not it has also changed. </para> </refsect1> Gets the value of this object. Since 2.12. Use atk_value_get_value_and_text() instead. a GObject instance that implements AtkValueIface a #GValue representing the current accessible value Gets the minimum increment by which the value of this object may be changed. If zero, the minimum increment is undefined, which may mean that it is limited only by the floating point precision of the platform. the minimum increment by which the value of this object may be changed. zero if undefined. a GObject instance that implements AtkValueIface Gets the maximum value of this object. Since 2.12. Use atk_value_get_range() instead. a GObject instance that implements AtkValueIface a #GValue representing the maximum accessible value Gets the minimum increment by which the value of this object may be changed. If zero, the minimum increment is undefined, which may mean that it is limited only by the floating point precision of the platform. Since 2.12. Use atk_value_get_increment() instead. a GObject instance that implements AtkValueIface a #GValue representing the minimum increment by which the accessible value may be changed Gets the minimum value of this object. Since 2.12. Use atk_value_get_range() instead. a GObject instance that implements AtkValueIface a #GValue representing the minimum accessible value Gets the range of this object. a newly allocated #AtkRange that represents the minimum, maximum and descriptor (if available) of @obj. NULL if that range is not defined. a GObject instance that implements AtkValueIface Gets the list of subranges defined for this object. See #AtkValue introduction for examples of subranges and when to expose them. an #GSList of #AtkRange which each of the subranges defined for this object. Free the returns list with g_slist_free(). a GObject instance that implements AtkValueIface Gets the current value and the human readable text alternative of @obj. @text is a newly created string, that must be freed by the caller. Can be NULL if no descriptor is available. a GObject instance that implements AtkValueIface address of #gdouble to put the current value of @obj address of #gchar to put the human readable text alternative for @value Sets the value of this object. Since 2.12. Use atk_value_set_value() instead. %TRUE if new value is successfully set, %FALSE otherwise. a GObject instance that implements AtkValueIface a #GValue which is the desired new accessible value. Sets the value of this object. This method is intended to provide a way to change the value of the object. In any case, it is possible that the value can't be modified (ie: a read-only component). If the value changes due this call, it is possible that the text could change, and will trigger an #AtkValue::value-changed signal emission. Note for implementors: the deprecated atk_value_set_current_value() method returned TRUE or FALSE depending if the value was assigned or not. In the practice several implementors were not able to decide it, and returned TRUE in any case. For that reason it is not required anymore to return if the value was properly assigned or not. a GObject instance that implements AtkValueIface a double which is the desired new accessible value. Gets the value of this object. Since 2.12. Use atk_value_get_value_and_text() instead. a GObject instance that implements AtkValueIface a #GValue representing the current accessible value Gets the minimum increment by which the value of this object may be changed. If zero, the minimum increment is undefined, which may mean that it is limited only by the floating point precision of the platform. the minimum increment by which the value of this object may be changed. zero if undefined. a GObject instance that implements AtkValueIface Gets the maximum value of this object. Since 2.12. Use atk_value_get_range() instead. a GObject instance that implements AtkValueIface a #GValue representing the maximum accessible value Gets the minimum increment by which the value of this object may be changed. If zero, the minimum increment is undefined, which may mean that it is limited only by the floating point precision of the platform. Since 2.12. Use atk_value_get_increment() instead. a GObject instance that implements AtkValueIface a #GValue representing the minimum increment by which the accessible value may be changed Gets the minimum value of this object. Since 2.12. Use atk_value_get_range() instead. a GObject instance that implements AtkValueIface a #GValue representing the minimum accessible value Gets the range of this object. a newly allocated #AtkRange that represents the minimum, maximum and descriptor (if available) of @obj. NULL if that range is not defined. a GObject instance that implements AtkValueIface Gets the list of subranges defined for this object. See #AtkValue introduction for examples of subranges and when to expose them. an #GSList of #AtkRange which each of the subranges defined for this object. Free the returns list with g_slist_free(). a GObject instance that implements AtkValueIface Gets the current value and the human readable text alternative of @obj. @text is a newly created string, that must be freed by the caller. Can be NULL if no descriptor is available. a GObject instance that implements AtkValueIface address of #gdouble to put the current value of @obj address of #gchar to put the human readable text alternative for @value Sets the value of this object. Since 2.12. Use atk_value_set_value() instead. %TRUE if new value is successfully set, %FALSE otherwise. a GObject instance that implements AtkValueIface a #GValue which is the desired new accessible value. Sets the value of this object. This method is intended to provide a way to change the value of the object. In any case, it is possible that the value can't be modified (ie: a read-only component). If the value changes due this call, it is possible that the text could change, and will trigger an #AtkValue::value-changed signal emission. Note for implementors: the deprecated atk_value_set_current_value() method returned TRUE or FALSE depending if the value was assigned or not. In the practice several implementors were not able to decide it, and returned TRUE in any case. For that reason it is not required anymore to return if the value was properly assigned or not. a GObject instance that implements AtkValueIface a double which is the desired new accessible value. The 'value-changed' signal is emitted when the current value that represent the object changes. @value is the numerical representation of this new value. @text is the human readable text alternative of @value, and can be NULL if it is not available. Note that if there is a textual description associated with the new numeric value, that description should be included regardless of whether or not it has also changed. Example: a password meter whose value changes as the user types their new password. Appropiate value text would be "weak", "acceptable" and "strong". the new value in a numerical form. human readable text alternative (also called description) of this object. NULL if not available. This virtual function is deprecated since 2.12 and it should not be overriden. a GObject instance that implements AtkValueIface a #GValue representing the current accessible value This virtual function is deprecated since 2.12 and it should not be overriden. a GObject instance that implements AtkValueIface a #GValue representing the maximum accessible value This virtual function is deprecated since 2.12 and it should not be overriden. a GObject instance that implements AtkValueIface a #GValue representing the minimum accessible value This virtual function is deprecated since 2.12 and it should not be overriden. %TRUE if new value is successfully set, %FALSE otherwise. a GObject instance that implements AtkValueIface a #GValue which is the desired new accessible value. This virtual function is deprecated since 2.12 and it should not be overriden. a GObject instance that implements AtkValueIface a #GValue representing the minimum increment by which the accessible value may be changed gets the current value and the human readable text alternative (if available) of this object. Since 2.12. a GObject instance that implements AtkValueIface address of #gdouble to put the current value of @obj address of #gchar to put the human readable text alternative for @value gets the range that defines the minimum and maximum value of this object. Returns NULL if there is no range defined. Since 2.12. a newly allocated #AtkRange that represents the minimum, maximum and descriptor (if available) of @obj. NULL if that range is not defined. a GObject instance that implements AtkValueIface gets the minimum increment by which the value of this object may be changed. If zero it is undefined. Since 2.12. the minimum increment by which the value of this object may be changed. zero if undefined. a GObject instance that implements AtkValueIface returns a list of different subranges, and their description (if available) of this object. Returns NULL if there is not subranges defined. Since 2.12. an #GSList of #AtkRange which each of the subranges defined for this object. Free the returns list with g_slist_free(). a GObject instance that implements AtkValueIface sets the value of this object. Since 2.12. a GObject instance that implements AtkValueIface a double which is the desired new accessible value. Default types for a given value. Those are defined in order to easily get localized strings to describe a given value or a given subrange, using atk_value_type_get_localized_name(). Gets the localized description string describing the #AtkValueType @value_type. the localized string describing the #AtkValueType The #AtkValueType whose localized name is required Gets the description string describing the #AtkValueType @value_type. the string describing the #AtkValueType The #AtkValueType whose name is required The ATK Interface provided by UI components that represent a top-level window. #AtkWindow should be implemented by the UI elements that represent a top-level window, such as the main window of an application or dialog. See [class@AtkObject] The signal #AtkWindow::activate is emitted when a window becomes the active window of the application or session. The signal #AtkWindow::create is emitted when a new window is created. The signal #AtkWindow::deactivate is emitted when a window is no longer the active window of the application or session. The signal #AtkWindow::destroy is emitted when a window is destroyed. The signal #AtkWindow::maximize is emitted when a window is maximized. The signal #AtkWindow::minimize is emitted when a window is minimized. The signal #AtkWindow::move is emitted when a window is moved. The signal #AtkWindow::resize is emitted when a window is resized. The signal #AtkWindow::restore is emitted when a window is restored. Adds the specified function to the list of functions to be called when an object receives focus. Focus tracking has been dropped as a feature to be implemented by ATK itself. If you need focus tracking on your implementation, subscribe to the #AtkObject::state-change "focused" signal. added focus tracker id, or 0 on failure. Function to be added to the list of functions to be called when an object receives focus. Adds the specified function to the list of functions to be called when an ATK event of type event_type occurs. The format of event_type is the following: "ATK:&lt;atk_type&gt;:&lt;atk_event&gt;:&lt;atk_event_detail&gt; Where "ATK" works as the namespace, &lt;atk_interface&gt; is the name of the ATK type (interface or object), &lt;atk_event&gt; is the name of the signal defined on that interface and &lt;atk_event_detail&gt; is the gsignal detail of that signal. You can find more info about gsignal details here: http://developer.gnome.org/gobject/stable/gobject-Signals.html The first three parameters are mandatory. The last one is optional. For example: ATK:AtkObject:state-change ATK:AtkText:text-selection-changed ATK:AtkText:text-insert:system Toolkit implementor note: ATK provides a default implementation for this virtual method. ATK implementors are discouraged from reimplementing this method. Toolkit implementor note: this method is not intended to be used by ATK implementors but by ATK consumers. ATK consumers note: as this method adds a listener for a given ATK type, that type should be already registered on the GType system before calling this method. A simple way to do that is creating an instance of #AtkNoOpObject. This class implements all ATK interfaces, so creating the instance will register all ATK types as a collateral effect. added event listener id, or 0 on failure. the listener to notify the type of event for which notification is requested Adds the specified function to the list of functions to be called when a key event occurs. The @data element will be passed to the #AtkKeySnoopFunc (@listener) as the @func_data param, on notification. added event listener id, or 0 on failure. the listener to notify a #gpointer that points to a block of data that should be sent to the registered listeners, along with the event notification, when it occurs. Frees the memory used by an #AtkAttributeSet, including all its #AtkAttributes. The #AtkAttributeSet to free Specifies the function to be called for focus tracker initialization. This function should be called by an implementation of the ATK interface if any specific work needs to be done to enable focus tracking. Focus tracking has been dropped as a feature to be implemented by ATK itself. Function to be called for focus tracker initialization Cause the focus tracker functions which have been specified to be executed for the object. Focus tracking has been dropped as a feature to be implemented by ATK itself. As #AtkObject::focus-event was deprecated in favor of a #AtkObject::state-change signal, in order to notify a focus change on your implementation, you can use atk_object_notify_state_change() instead. an #AtkObject Returns the binary age as passed to libtool when building the ATK library the process is running against. the binary age of the ATK library Gets a default implementation of the #AtkObjectFactory/type registry. Note: For most toolkit maintainers, this will be the correct registry for registering new #AtkObject factories. Following a call to this function, maintainers may call atk_registry_set_factory_type() to associate an #AtkObjectFactory subclass with the GType of objects for whom accessibility information will be provided. a default implementation of the #AtkObjectFactory/type registry Gets the currently focused object. the currently focused object for the current application Returns the interface age as passed to libtool when building the ATK library the process is running against. the interface age of the ATK library Returns the major version number of the ATK library. (e.g. in ATK version 2.7.4 this is 2.) This function is in the library, so it represents the ATK library your code is running against. In contrast, the #ATK_MAJOR_VERSION macro represents the major version of the ATK headers you have included when compiling your code. the major version number of the ATK library Returns the micro version number of the ATK library. (e.g. in ATK version 2.7.4 this is 4.) This function is in the library, so it represents the ATK library your code is are running against. In contrast, the #ATK_MICRO_VERSION macro represents the micro version of the ATK headers you have included when compiling your code. the micro version number of the ATK library Returns the minor version number of the ATK library. (e.g. in ATK version 2.7.4 this is 7.) This function is in the library, so it represents the ATK library your code is are running against. In contrast, the #ATK_MINOR_VERSION macro represents the minor version of the ATK headers you have included when compiling your code. the minor version number of the ATK library Gets the root accessible container for the current application. the root accessible container for the current application Gets name string for the GUI toolkit implementing ATK for this application. name string for the GUI toolkit implementing ATK for this application Gets version string for the GUI toolkit implementing ATK for this application. version string for the GUI toolkit implementing ATK for this application Gets the current version for ATK. version string for ATK Get the #AtkRelationType type corresponding to a relation name. the #AtkRelationType enumerated type corresponding to the specified name, or #ATK_RELATION_NULL if no matching relation type is found. a string which is the (non-localized) name of an ATK relation type. Gets the description string describing the #AtkRelationType @type. the string describing the AtkRelationType The #AtkRelationType whose name is required Associate @name with a new #AtkRelationType an #AtkRelationType associated with @name a name string Removes the specified focus tracker from the list of functions to be called when any object receives focus. Focus tracking has been dropped as a feature to be implemented by ATK itself. If you need focus tracking on your implementation, subscribe to the #AtkObject::state-change "focused" signal. the id of the focus tracker to remove @listener_id is the value returned by #atk_add_global_event_listener when you registered that event listener. Toolkit implementor note: ATK provides a default implementation for this virtual method. ATK implementors are discouraged from reimplementing this method. Toolkit implementor note: this method is not intended to be used by ATK implementors but by ATK consumers. Removes the specified event listener the id of the event listener to remove @listener_id is the value returned by #atk_add_key_event_listener when you registered that event listener. Removes the specified event listener. the id of the event listener to remove Get the #AtkRole type corresponding to a rolew name. the #AtkRole enumerated type corresponding to the specified name, or #ATK_ROLE_INVALID if no matching role is found. a string which is the (non-localized) name of an ATK role. Gets the localized description string describing the #AtkRole @role. the localized string describing the AtkRole The #AtkRole whose localized name is required Gets the description string describing the #AtkRole @role. the string describing the AtkRole The #AtkRole whose name is required Registers the role specified by @name. @name must be a meaningful name. So it should not be empty, or consisting on whitespaces. Since 2.12. If your application/toolkit doesn't find a suitable role for a specific object defined at #AtkRole, please submit a bug in order to add a new role to the specification. an #AtkRole for the new role if added properly. ATK_ROLE_INVALID in case of error. a character string describing the new role. Gets the #AtkStateType corresponding to the description string @name. an #AtkStateType corresponding to @name a character string state name Gets the description string describing the #AtkStateType @type. the string describing the AtkStateType The #AtkStateType whose name is required Register a new object state. an #AtkState value for the new state. a character string describing the new state. Get the #AtkTextAttribute type corresponding to a text attribute name. the #AtkTextAttribute enumerated type corresponding to the specified name, or #ATK_TEXT_ATTRIBUTE_INVALID if no matching text attribute is found. a string which is the (non-localized) name of an ATK text attribute. Gets the name corresponding to the #AtkTextAttribute a string containing the name; this string should not be freed The #AtkTextAttribute whose name is required Gets the value for the index of the #AtkTextAttribute a string containing the value; this string should not be freed; %NULL is returned if there are no values maintained for the attr value. The #AtkTextAttribute for which a value is required The index of the required value Associate @name with a new #AtkTextAttribute an #AtkTextAttribute associated with @name a name string Frees the memory associated with an array of AtkTextRange. It is assumed that the array was returned by the function atk_text_get_bounded_ranges and is NULL terminated. A pointer to an array of #AtkTextRange which is to be freed. Gets the localized description string describing the #AtkValueType @value_type. the localized string describing the #AtkValueType The #AtkValueType whose localized name is required Gets the description string describing the #AtkValueType @value_type. the string describing the #AtkValueType The #AtkValueType whose name is required soup3-0.9.0/gir-files/GL-1.0.gir000064400000000000000000000020741046102023000140700ustar 00000000000000 soup3-0.9.0/gir-files/GLib-2.0.gir000064400000000000000000135214771046102023000144250ustar 00000000000000 Integer representing a day of the month; between 1 and 31. The %G_DATE_BAD_DAY value represents an invalid day of the month. Integer type representing a year. The %G_DATE_BAD_YEAR value is the invalid value. The year must be 1 or higher; negative ([BCE](https://en.wikipedia.org/wiki/Common_Era)) years are not allowed. The year is represented with four digits. Opaque type. See g_main_context_pusher_new() for details. Opaque type. See g_mutex_locker_new() for details. A type which is used to hold a process identification. On UNIX, processes are identified by a process id (an integer), while Windows uses process handles (which are pointers). GPid is used in GLib only for descendant processes spawned with the g_spawn functions. A GQuark is a non-zero integer which uniquely identifies a particular string. A GQuark value of zero is associated to `NULL`. Given either the string or the `GQuark` identifier it is possible to retrieve the other. Quarks are used for both [datasets and keyed data lists](datalist-and-dataset.html). To create a new quark from a string, use [func@GLib.quark_from_string] or [func@GLib.quark_from_static_string]. To find the string corresponding to a given `GQuark`, use [func@GLib.quark_to_string]. To find the `GQuark` corresponding to a given string, use [func@GLib.quark_try_string]. Another use for the string pool maintained for the quark functions is string interning, using [func@GLib.intern_string] or [func@GLib.intern_static_string]. An interned string is a canonical representation for a string. One important advantage of interned strings is that they can be compared for equality by a simple pointer comparison, rather than using `strcmp()`. Opaque type. See g_rw_lock_reader_locker_new() for details. Opaque type. See g_rw_lock_writer_locker_new() for details. Opaque type. See g_rec_mutex_locker_new() for details. A typedef for a reference-counted string. A pointer to a #GRefString can be treated like a standard `char*` array by all code, but can additionally have `g_ref_string_*()` methods called on it. `g_ref_string_*()` methods cannot be called on `char*` arrays not allocated using g_ref_string_new(). If using #GRefString with autocleanups, g_autoptr() must be used rather than g_autofree(), so that the reference counting metadata is also freed. A typedef alias for gchar**. This is mostly useful when used together with `g_auto()`. Simply a replacement for `time_t`. It has been deprecated since it is not equivalent to `time_t` on 64-bit platforms with a 64-bit `time_t`. Unrelated to #GTimer. Note that #GTime is defined to always be a 32-bit integer, unlike `time_t` which may be 64-bit on some systems. Therefore, #GTime will overflow in the year 2038, and you cannot use the address of a #GTime variable as argument to the UNIX time() function. Instead, do the following: |[<!-- language="C" --> time_t ttime; GTime gtime; time (&ttime); gtime = (GTime)ttime; ]| This is not [Y2038-safe](https://en.wikipedia.org/wiki/Year_2038_problem). Use #GDateTime or #time_t instead. A value representing an interval of time, in microseconds. Return the minimal alignment required by the platform ABI for values of the given type. The address of a variable or struct member of the given type must always be a multiple of this alignment. For example, most platforms require int variables to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms. Note this is not necessarily the same as the value returned by GCC’s `__alignof__` operator, which returns the preferred alignment for a type. The preferred alignment may be a stricter alignment than the minimal alignment. a type-name Evaluates to a truth value if the absolute difference between @a and @b is smaller than @epsilon, and to a false value otherwise. For example, - `G_APPROX_VALUE (5, 6, 2)` evaluates to true - `G_APPROX_VALUE (3.14, 3.15, 0.001)` evaluates to false - `G_APPROX_VALUE (n, 0.f, FLT_EPSILON)` evaluates to true if `n` is within the single precision floating point epsilon from zero a numeric value a numeric value a numeric value that expresses the tolerance between @a and @b A good size for a buffer to be passed into [func@GLib.ascii_dtostr]. It is guaranteed to be enough for all output of that function on systems with 64bit IEEE-compatible doubles. The typical usage would be something like: ```C char buf[G_ASCII_DTOSTR_BUF_SIZE]; fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); ``` Evaluates to the initial reference count for `gatomicrefcount`. This macro is useful for initializing `gatomicrefcount` fields inside structures, for instance: |[<!-- language="C" --> typedef struct { gatomicrefcount ref_count; char *name; char *address; } Person; static const Person default_person = { .ref_count = G_ATOMIC_REF_COUNT_INIT, .name = "Default name", .address = "Default address", }; ]| Works like [func@GLib.MUTEX_AUTO_LOCK], but for a lock defined with [func@GLib.LOCK_DEFINE]. This feature is only supported on GCC and clang. This macro is not defined on other compilers and should not be used in programs that are intended to be portable to those compilers. the name of the lock Contains the public fields of a `GArray`. a pointer to the element data. The data may be moved as elements are added to the `GArray`. the number of elements in the `GArray` not including the possible terminating zero element Adds @len elements onto the end of the array. @data may be `NULL` if (and only if) @len is zero. If @len is zero, this function is a no-op. The `GArray` an array a pointer to the elements to append to the end of the array the number of elements to append Checks whether @target exists in @array by performing a binary search based on the given comparison function @compare_func which gets pointers to items as arguments. If the element is found, true is returned and the element’s index is returned in @out_match_index (if non-`NULL`). Otherwise, false is returned and @out_match_index is undefined. This search is using a binary search, so the @array must absolutely be sorted to return a correct result (if not, the function may produce false-negative). This example defines a comparison function and searches an element in a `GArray`: ```c static gint cmpint (gconstpointer a, gconstpointer b) { const gint *_a = a; const gint *_b = b; return *_a - *_b; } ... gint i = 424242; guint matched_index; gboolean result = g_array_binary_search (garray, &i, cmpint, &matched_index); ... ``` true if @target is one of the elements of @array; false otherwise an array a pointer to the item to look up a comparison function to locate @target the return location for the index of the element, if found Creates a shallow copy of a #GArray. If the array elements consist of pointers to data, the pointers are copied but the actual data is not. The copy of @array an array Frees the memory allocated for the `GArray`. If @free_segment is true it frees the memory block holding the elements as well. Pass false if you want to free the `GArray` wrapper but preserve the underlying array for use elsewhere. If the reference count of @array is greater than one, the `GArray` wrapper is preserved but the size of @array will be set to zero. If array contents point to dynamically-allocated memory, they should be freed separately if @free_segment is true and no @clear_func function has been set for @array. This function is not thread-safe. If using a `GArray` from multiple threads, use only the atomic [func@GLib.Array.ref] and [func@GLib.Array.unref] functions. The allocated element data if @free_segment is false, otherwise `NULL` an array if true, the actual element data is freed as well Gets the size of the elements in @array. The size of each element, in bytes an array Inserts @len elements into a `GArray` at the given index. If @index_ is greater than the array’s current length, the array is expanded. The elements between the old end of the array and the newly inserted elements will be initialised to zero if the array was configured to clear elements; otherwise their values will be undefined. If @index_ is less than the array’s current length, new entries will be inserted into the array, and the existing entries above @index_ will be moved upwards. @data may be `NULL` if (and only if) @len is zero. If @len is zero, this function is a no-op. The `GArray` an array the index to place the elements at a pointer to the elements to insert the number of elements to insert Creates a new `GArray` with a reference count of 1. The new `GArray` if true, the array should have an extra element at the end which is set to 0 if true, `GArray` elements should be automatically cleared to 0 when they are allocated the size of each element in bytes Creates a new `GArray` with @data as array data, @len as length and a reference count of 1. This avoids having to copy the data manually, when it can just be inherited. After this call, @data belongs to the `GArray` and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with [func@GLib.free]. In case the elements need to be cleared when the array is freed, use [func@GLib.Array.set_clear_func] to set a [callback@GLib.DestroyNotify] function to perform such task. Do not use it if @len or @element_size are greater than [`G_MAXUINT`](types.html#guint). `GArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new #GArray an array of elements of @element_size the number of elements in @data if true, `GArray` elements should be automatically cleared to 0 when they are allocated the size of each element in bytes Creates a new `GArray` with @data as array data, computing the length of it and setting the reference count to 1. This avoids having to copy the data manually, when it can just be inherited. After this call, @data belongs to the `GArray` and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with [func@GLib.free]. The length is calculated by iterating through @data until the first `NULL` element is found. In case the elements need to be cleared when the array is freed, use [func@GLib.Array.set_clear_func] to set a [callback@GLib.DestroyNotify] function to perform such task. Do not use it if @data length or @element_size are greater than [`G_MAXUINT`](types.html#guint). `GArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new `GArray` an array of elements of @element_size, `NULL` terminated if true, `GArray` elements should be automatically cleared to 0 when they are allocated the size of each element in bytes Adds @len elements onto the start of the array. @data may be `NULL` if (and only if) @len is zero. If @len is zero, this function is a no-op. This operation is slower than [func@GLib.Array.append_vals] since the existing elements in the array have to be moved to make space for the new elements. The `GArray` an array a pointer to the elements to prepend to the start of the array the number of elements to prepend, which may be zero Atomically increments the reference count of @array by one. This function is thread-safe and may be called from any thread. The passed in `GArray` an array Removes the element at the given index from a `GArray`. The following elements are moved down one place. The `GArray` an array the index of the element to remove Removes the element at the given index from a `GArray`. The last element in the array is used to fill in the space, so this function does not preserve the order of the `GArray`. But it is faster than [func@GLib.Array.remove_index]. The `GArray` an array the index of the element to remove Removes the given number of elements starting at the given index from a `GArray`. The following elements are moved to close the gap. The `GArray` an array the index of the first element to remove the number of elements to remove Sets a function to clear an element of @array. The @clear_func will be called when an element in the array data segment is removed and when the array is freed and data segment is deallocated as well. @clear_func will be passed a pointer to the element to clear, rather than the element itself. Note that in contrast with other uses of [callback@GLib.DestroyNotify] functions, @clear_func is expected to clear the contents of the array element it is given, but not free the element itself. ```c typedef struct { gchar *str; GObject *obj; } ArrayElement; static void array_element_clear (ArrayElement *element) { g_clear_pointer (&element->str, g_free); g_clear_object (&element->obj); } // main code GArray *garray = g_array_new (FALSE, FALSE, sizeof (ArrayElement)); g_array_set_clear_func (garray, (GDestroyNotify) array_element_clear); // assign data to the structure g_array_free (garray, TRUE); ``` an array a function to clear an element of @array Sets the size of the array, expanding it if necessary. If the array was created with @clear_ set to true, the new elements are set to 0. The `GArray` an array the new size of the #GArray Creates a new `GArray` with @reserved_size elements preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many elements to the array. Note however that the size of the array is still 0. The new `GArray` if true, the array should have an extra element at the end with all bits cleared if true, all bits in the array should be cleared to 0 on allocation the size of each element in the array the number of elements preallocated Sorts a `GArray` using @compare_func which should be a `qsort()`-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater zero if first arg is greater than second arg). This is guaranteed to be a stable sort since version 2.32. an array a comparison function Like [func@GLib.Array.sort], but the comparison function receives an extra user data argument. This is guaranteed to be a stable sort since version 2.32. There used to be a comment here about making the sort stable by using the addresses of the elements in the comparison function. This did not actually work, so any such code should be removed. an array a comparison function the data to pass to @compare_func Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller. Note that if the array was created with the @zero_terminate property set to true, this may still return `NULL` if the length of the array was zero and data was not yet allocated. If array elements contain dynamically-allocated memory, the array elements should also be freed by the caller. A short example of use: ```c ... gpointer data; gsize data_len; data = g_array_steal (some_array, &data_len); ... ``` The allocated element data an array a pointer to retrieve the number of elements of the original array Atomically decrements the reference count of @array by one. If the reference count drops to 0, the effect is the same as calling [func@GLib.Array.free] with @free_segment set to true. This function is thread-safe and may be called from any thread. an array An opaque data structure which represents an asynchronous queue. It should only be accessed through the `g_async_queue_*` functions. Returns the length of the queue. Actually this function returns the number of data items in the queue minus the number of waiting threads, so a negative value means waiting threads, and a positive value means available entries in the @queue. A return value of 0 could mean n entries in the queue and n threads waiting. This can happen due to locking of the queue or due to scheduling. the length of the @queue a #GAsyncQueue. Returns the length of the queue. Actually this function returns the number of data items in the queue minus the number of waiting threads, so a negative value means waiting threads, and a positive value means available entries in the @queue. A return value of 0 could mean n entries in the queue and n threads waiting. This can happen due to locking of the queue or due to scheduling. This function must be called while holding the @queue's lock. the length of the @queue. a #GAsyncQueue Acquires the @queue's lock. If another thread is already holding the lock, this call will block until the lock becomes available. Call g_async_queue_unlock() to drop the lock again. While holding the lock, you can only call the g_async_queue_*_unlocked() functions on @queue. Otherwise, deadlock may occur. a #GAsyncQueue Pops data from the @queue. If @queue is empty, this function blocks until data becomes available. data from the queue a #GAsyncQueue Pops data from the @queue. If @queue is empty, this function blocks until data becomes available. This function must be called while holding the @queue's lock. data from the queue. a #GAsyncQueue Pushes the @data into the @queue. The @data parameter must not be %NULL. a #GAsyncQueue data to push onto the @queue Pushes the @item into the @queue. @item must not be %NULL. In contrast to g_async_queue_push(), this function pushes the new item ahead of the items already in the queue, so that it will be the next one to be popped off the queue. a #GAsyncQueue data to push into the @queue Pushes the @item into the @queue. @item must not be %NULL. In contrast to g_async_queue_push_unlocked(), this function pushes the new item ahead of the items already in the queue, so that it will be the next one to be popped off the queue. This function must be called while holding the @queue's lock. a #GAsyncQueue data to push into the @queue Inserts @data into @queue using @func to determine the new position. This function requires that the @queue is sorted before pushing on new elements, see g_async_queue_sort(). This function will lock @queue before it sorts the queue and unlock it when it is finished. For an example of @func see g_async_queue_sort(). a #GAsyncQueue the @data to push into the @queue the #GCompareDataFunc is used to sort @queue user data passed to @func. Inserts @data into @queue using @func to determine the new position. The sort function @func is passed two elements of the @queue. It should return 0 if they are equal, a negative value if the first element should be higher in the @queue or a positive value if the first element should be lower in the @queue than the second element. This function requires that the @queue is sorted before pushing on new elements, see g_async_queue_sort(). This function must be called while holding the @queue's lock. For an example of @func see g_async_queue_sort(). a #GAsyncQueue the data to push into the @queue the #GCompareDataFunc is used to sort @queue user data passed to @func. Pushes the @data into the @queue. The @data parameter must not be %NULL. This function must be called while holding the @queue's lock. a #GAsyncQueue data to push onto the @queue Increases the reference count of the asynchronous @queue by 1. You do not need to hold the lock to call this function. the @queue that was passed in (since 2.6) a #GAsyncQueue Increases the reference count of the asynchronous @queue by 1. Reference counting is done atomically. so g_async_queue_ref() can be used regardless of the @queue's lock. a #GAsyncQueue Remove an item from the queue. %TRUE if the item was removed a #GAsyncQueue the data to remove from the @queue Remove an item from the queue. This function must be called while holding the @queue's lock. %TRUE if the item was removed a #GAsyncQueue the data to remove from the @queue Sorts @queue using @func. The sort function @func is passed two elements of the @queue. It should return 0 if they are equal, a negative value if the first element should be higher in the @queue or a positive value if the first element should be lower in the @queue than the second element. This function will lock @queue before it sorts the queue and unlock it when it is finished. If you were sorting a list of priority numbers to make sure the lowest priority would be at the top of the queue, you could use: |[<!-- language="C" --> gint32 id1; gint32 id2; id1 = GPOINTER_TO_INT (element1); id2 = GPOINTER_TO_INT (element2); return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1); ]| a #GAsyncQueue the #GCompareDataFunc is used to sort @queue user data passed to @func Sorts @queue using @func. The sort function @func is passed two elements of the @queue. It should return 0 if they are equal, a negative value if the first element should be higher in the @queue or a positive value if the first element should be lower in the @queue than the second element. This function must be called while holding the @queue's lock. a #GAsyncQueue the #GCompareDataFunc is used to sort @queue user data passed to @func Pops data from the @queue. If the queue is empty, blocks until @end_time or until data becomes available. If no data is received before @end_time, %NULL is returned. To easily calculate @end_time, a combination of g_get_real_time() and g_time_val_add() can be used. use g_async_queue_timeout_pop(). data from the queue or %NULL, when no data is received before @end_time. a #GAsyncQueue a #GTimeVal, determining the final time Pops data from the @queue. If the queue is empty, blocks until @end_time or until data becomes available. If no data is received before @end_time, %NULL is returned. To easily calculate @end_time, a combination of g_get_real_time() and g_time_val_add() can be used. This function must be called while holding the @queue's lock. use g_async_queue_timeout_pop_unlocked(). data from the queue or %NULL, when no data is received before @end_time. a #GAsyncQueue a #GTimeVal, determining the final time Pops data from the @queue. If the queue is empty, blocks for @timeout microseconds, or until data becomes available. If no data is received before the timeout, %NULL is returned. data from the queue or %NULL, when no data is received before the timeout. a #GAsyncQueue the number of microseconds to wait Pops data from the @queue. If the queue is empty, blocks for @timeout microseconds, or until data becomes available. If no data is received before the timeout, %NULL is returned. This function must be called while holding the @queue's lock. data from the queue or %NULL, when no data is received before the timeout. a #GAsyncQueue the number of microseconds to wait Tries to pop data from the @queue. If no data is available, %NULL is returned. data from the queue or %NULL, when no data is available immediately. a #GAsyncQueue Tries to pop data from the @queue. If no data is available, %NULL is returned. This function must be called while holding the @queue's lock. data from the queue or %NULL, when no data is available immediately. a #GAsyncQueue Releases the queue's lock. Calling this function when you have not acquired the with g_async_queue_lock() leads to undefined behaviour. a #GAsyncQueue Decreases the reference count of the asynchronous @queue by 1. If the reference count went to 0, the @queue will be destroyed and the memory allocated will be freed. So you are not allowed to use the @queue afterwards, as it might have disappeared. You do not need to hold the lock to call this function. a #GAsyncQueue. Decreases the reference count of the asynchronous @queue by 1 and releases the lock. This function must be called while holding the @queue's lock. If the reference count went to 0, the @queue will be destroyed and the memory allocated will be freed. Reference counting is done atomically. so g_async_queue_unref() can be used regardless of the @queue's lock. a #GAsyncQueue Creates a new asynchronous queue. a new #GAsyncQueue. Free with g_async_queue_unref() Creates a new asynchronous queue and sets up a destroy notify function that is used to free any remaining queue items when the queue is destroyed after the final unref. a new #GAsyncQueue. Free with g_async_queue_unref() function to free queue elements Specifies one of the possible types of byte order. See %G_BYTE_ORDER. Inserts a breakpoint instruction into the code. On architectures which support it, this is implemented as a soft interrupt and on other architectures it raises a `SIGTRAP` signal. `SIGTRAP` is used rather than abort() to allow breakpoints to be skipped past in a debugger if they are not the desired target of debugging. `GBookmarkFile` lets you parse, edit or create files containing bookmarks. Bookmarks refer to a URI, along with some meta-data about the resource pointed by the URI like its MIME type, the application that is registering the bookmark and the icon that should be used to represent the bookmark. The data is stored using the [Desktop Bookmark Specification](https://www.freedesktop.org/wiki/Specifications/desktop-bookmark-spec/). The syntax of the bookmark files is described in detail inside the Desktop Bookmark Specification, here is a quick summary: bookmark files use a sub-class of the XML Bookmark Exchange Language specification, consisting of valid UTF-8 encoded XML, under the `<xbel>` root element; each bookmark is stored inside a `<bookmark>` element, using its URI: no relative paths can be used inside a bookmark file. The bookmark may have a user defined title and description, to be used instead of the URI. Under the `<metadata>` element, with its owner attribute set to `http://freedesktop.org`, is stored the meta-data about a resource pointed by its URI. The meta-data consists of the resource's MIME type; the applications that have registered a bookmark; the groups to which a bookmark belongs to; a visibility flag, used to set the bookmark as "private" to the applications and groups that has it registered; the URI and MIME type of an icon, to be used when displaying the bookmark inside a GUI. Here is an example of a bookmark file: [bookmarks.xbel](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/glib/tests/bookmarks.xbel) A bookmark file might contain more than one bookmark; each bookmark is accessed through its URI. The important caveat of bookmark files is that when you add a new bookmark you must also add the application that is registering it, using [method@GLib.BookmarkFile.add_application] or [method@GLib.BookmarkFile.set_application_info]. If a bookmark has no applications then it won't be dumped when creating the on disk representation, using [method@GLib.BookmarkFile.to_data] or [method@GLib.BookmarkFile.to_file]. Creates a new empty #GBookmarkFile object. Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data() or g_bookmark_file_load_from_data_dirs() to read an existing bookmark file. an empty #GBookmarkFile Adds the application with @name and @exec to the list of applications that have registered a bookmark for @uri into @bookmark. Every bookmark inside a #GBookmarkFile must have at least an application registered. Each application must provide a name, a command line useful for launching the bookmark, the number of times the bookmark has been registered by the application and the last time the application registered this bookmark. If @name is %NULL, the name of the application will be the same returned by g_get_application_name(); if @exec is %NULL, the command line will be a composition of the program name as returned by g_get_prgname() and the "\%u" modifier, which will be expanded to the bookmark's URI. This function will automatically take care of updating the registrations count and timestamping in case an application with the same @name had already registered a bookmark for @uri inside @bookmark. If no bookmark for @uri is found, one is created. a #GBookmarkFile a valid URI the name of the application registering the bookmark or %NULL command line to be used to launch the bookmark or %NULL Adds @group to the list of groups to which the bookmark for @uri belongs to. If no bookmark for @uri is found then it is created. a #GBookmarkFile a valid URI the group name to be added Deeply copies a @bookmark #GBookmarkFile object to a new one. the copy of @bookmark. Use g_bookmark_free() when finished using it. A #GBookmarkFile Frees a #GBookmarkFile. a #GBookmarkFile Gets the time the bookmark for @uri was added to @bookmark In the event the URI cannot be found, -1 is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. Use g_bookmark_file_get_added_date_time() instead, as `time_t` is deprecated due to the year 2038 problem. a timestamp a #GBookmarkFile a valid URI Gets the time the bookmark for @uri was added to @bookmark In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. a #GDateTime a #GBookmarkFile a valid URI Gets the registration information of @app_name for the bookmark for @uri. See g_bookmark_file_set_application_info() for more information about the returned data. The string returned in @app_exec must be freed. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the event that no application with name @app_name has registered a bookmark for @uri, %FALSE is returned and error is set to %G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting the command line fails, an error of the %G_SHELL_ERROR domain is set and %FALSE is returned. Use g_bookmark_file_get_application_info() instead, as `time_t` is deprecated due to the year 2038 problem. %TRUE on success. a #GBookmarkFile a valid URI an application's name return location for the command line of the application, or %NULL return location for the registration count, or %NULL return location for the last registration time, or %NULL Gets the registration information of @app_name for the bookmark for @uri. See g_bookmark_file_set_application_info() for more information about the returned data. The string returned in @app_exec must be freed. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the event that no application with name @app_name has registered a bookmark for @uri, %FALSE is returned and error is set to %G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting the command line fails, an error of the %G_SHELL_ERROR domain is set and %FALSE is returned. %TRUE on success. a #GBookmarkFile a valid URI an application's name return location for the command line of the application, or %NULL return location for the registration count, or %NULL return location for the last registration time, or %NULL Retrieves the names of the applications that have registered the bookmark for @uri. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. a #GBookmarkFile a valid URI return location of the length of the returned list, or %NULL Retrieves the description of the bookmark for @uri. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. a newly allocated string or %NULL if the specified URI cannot be found. a #GBookmarkFile a valid URI Retrieves the list of group names of the bookmark for @uri. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. The returned array is %NULL terminated, so @length may optionally be %NULL. a newly allocated %NULL-terminated array of group names. Use g_strfreev() to free it. a #GBookmarkFile a valid URI return location for the length of the returned string, or %NULL Gets the icon of the bookmark for @uri. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. %TRUE if the icon for the bookmark for the URI was found. You should free the returned strings. a #GBookmarkFile a valid URI return location for the icon's location or %NULL return location for the icon's MIME type or %NULL Gets whether the private flag of the bookmark for @uri is set. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the event that the private flag cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_INVALID_VALUE. %TRUE if the private flag is set, %FALSE otherwise. a #GBookmarkFile a valid URI Retrieves the MIME type of the resource pointed by @uri. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the event that the MIME type cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_INVALID_VALUE. a newly allocated string or %NULL if the specified URI cannot be found. a #GBookmarkFile a valid URI Gets the time when the bookmark for @uri was last modified. In the event the URI cannot be found, -1 is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. Use g_bookmark_file_get_modified_date_time() instead, as `time_t` is deprecated due to the year 2038 problem. a timestamp a #GBookmarkFile a valid URI Gets the time when the bookmark for @uri was last modified. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. a #GDateTime a #GBookmarkFile a valid URI Gets the number of bookmarks inside @bookmark. the number of bookmarks a #GBookmarkFile Returns the title of the bookmark for @uri. If @uri is %NULL, the title of @bookmark is returned. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. a newly allocated string or %NULL if the specified URI cannot be found. a #GBookmarkFile a valid URI or %NULL Returns all URIs of the bookmarks in the bookmark file @bookmark. The array of returned URIs will be %NULL-terminated, so @length may optionally be %NULL. a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. a #GBookmarkFile return location for the number of returned URIs, or %NULL Gets the time the bookmark for @uri was last visited. In the event the URI cannot be found, -1 is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. Use g_bookmark_file_get_visited_date_time() instead, as `time_t` is deprecated due to the year 2038 problem. a timestamp. a #GBookmarkFile a valid URI Gets the time the bookmark for @uri was last visited. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. a #GDateTime a #GBookmarkFile a valid URI Checks whether the bookmark for @uri inside @bookmark has been registered by application @name. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. %TRUE if the application @name was found a #GBookmarkFile a valid URI the name of the application Checks whether @group appears in the list of groups to which the bookmark for @uri belongs to. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. %TRUE if @group was found. a #GBookmarkFile a valid URI the group name to be searched Looks whether the desktop bookmark has an item with its URI set to @uri. %TRUE if @uri is inside @bookmark, %FALSE otherwise a #GBookmarkFile a valid URI Loads a bookmark file from memory into an empty #GBookmarkFile structure. If the object cannot be created then @error is set to a #GBookmarkFileError. %TRUE if a desktop bookmark could be loaded. an empty #GBookmarkFile struct desktop bookmarks loaded in memory the length of @data in bytes This function looks for a desktop bookmark file named @file in the paths returned from g_get_user_data_dir() and g_get_system_data_dirs(), loads the file into @bookmark and returns the file's full path in @full_path. If the file could not be loaded then @error is set to either a #GFileError or #GBookmarkFileError. %TRUE if a key file could be loaded, %FALSE otherwise a #GBookmarkFile a relative path to a filename to open and parse return location for a string containing the full path of the file, or %NULL Loads a desktop bookmark file into an empty #GBookmarkFile structure. If the file could not be loaded then @error is set to either a #GFileError or #GBookmarkFileError. %TRUE if a desktop bookmark file could be loaded an empty #GBookmarkFile struct the path of a filename to load, in the GLib file name encoding Changes the URI of a bookmark item from @old_uri to @new_uri. Any existing bookmark for @new_uri will be overwritten. If @new_uri is %NULL, then the bookmark is removed. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. %TRUE if the URI was successfully changed a #GBookmarkFile a valid URI a valid URI, or %NULL Removes application registered with @name from the list of applications that have registered a bookmark for @uri inside @bookmark. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the event that no application with name @app_name has registered a bookmark for @uri, %FALSE is returned and error is set to %G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. %TRUE if the application was successfully removed. a #GBookmarkFile a valid URI the name of the application Removes @group from the list of groups to which the bookmark for @uri belongs to. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the event no group was defined, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_INVALID_VALUE. %TRUE if @group was successfully removed. a #GBookmarkFile a valid URI the group name to be removed Removes the bookmark for @uri from the bookmark file @bookmark. %TRUE if the bookmark was removed successfully. a #GBookmarkFile a valid URI Sets the time the bookmark for @uri was added into @bookmark. If no bookmark for @uri is found then it is created. Use g_bookmark_file_set_added_date_time() instead, as `time_t` is deprecated due to the year 2038 problem. a #GBookmarkFile a valid URI a timestamp or -1 to use the current time Sets the time the bookmark for @uri was added into @bookmark. If no bookmark for @uri is found then it is created. a #GBookmarkFile a valid URI a #GDateTime Sets the meta-data of application @name inside the list of applications that have registered a bookmark for @uri inside @bookmark. You should rarely use this function; use g_bookmark_file_add_application() and g_bookmark_file_remove_application() instead. @name can be any UTF-8 encoded string used to identify an application. @exec can have one of these two modifiers: "\%f", which will be expanded as the local file name retrieved from the bookmark's URI; "\%u", which will be expanded as the bookmark's URI. The expansion is done automatically when retrieving the stored command line using the g_bookmark_file_get_application_info() function. @count is the number of times the application has registered the bookmark; if is < 0, the current registration count will be increased by one, if is 0, the application with @name will be removed from the list of registered applications. @stamp is the Unix time of the last registration; if it is -1, the current time will be used. If you try to remove an application by setting its registration count to zero, and no bookmark for @uri is found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly, in the event that no application @name has registered a bookmark for @uri, %FALSE is returned and error is set to %G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark for @uri is found, one is created. Use g_bookmark_file_set_application_info() instead, as `time_t` is deprecated due to the year 2038 problem. %TRUE if the application's meta-data was successfully changed. a #GBookmarkFile a valid URI an application's name an application's command line the number of registrations done for this application the time of the last registration for this application Sets the meta-data of application @name inside the list of applications that have registered a bookmark for @uri inside @bookmark. You should rarely use this function; use g_bookmark_file_add_application() and g_bookmark_file_remove_application() instead. @name can be any UTF-8 encoded string used to identify an application. @exec can have one of these two modifiers: "\%f", which will be expanded as the local file name retrieved from the bookmark's URI; "\%u", which will be expanded as the bookmark's URI. The expansion is done automatically when retrieving the stored command line using the g_bookmark_file_get_application_info() function. @count is the number of times the application has registered the bookmark; if is < 0, the current registration count will be increased by one, if is 0, the application with @name will be removed from the list of registered applications. @stamp is the Unix time of the last registration. If you try to remove an application by setting its registration count to zero, and no bookmark for @uri is found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly, in the event that no application @name has registered a bookmark for @uri, %FALSE is returned and error is set to %G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark for @uri is found, one is created. %TRUE if the application's meta-data was successfully changed. a #GBookmarkFile a valid URI an application's name an application's command line the number of registrations done for this application the time of the last registration for this application, which may be %NULL if @count is 0 Sets @description as the description of the bookmark for @uri. If @uri is %NULL, the description of @bookmark is set. If a bookmark for @uri cannot be found then it is created. a #GBookmarkFile a valid URI or %NULL a string Sets a list of group names for the item with URI @uri. Each previously set group name list is removed. If @uri cannot be found then an item for it is created. a #GBookmarkFile an item's URI an array of group names, or %NULL to remove all groups number of group name values in @groups Sets the icon for the bookmark for @uri. If @href is %NULL, unsets the currently set icon. @href can either be a full URL for the icon file or the icon name following the Icon Naming specification. If no bookmark for @uri is found one is created. a #GBookmarkFile a valid URI the URI of the icon for the bookmark, or %NULL the MIME type of the icon for the bookmark Sets the private flag of the bookmark for @uri. If a bookmark for @uri cannot be found then it is created. a #GBookmarkFile a valid URI %TRUE if the bookmark should be marked as private Sets @mime_type as the MIME type of the bookmark for @uri. If a bookmark for @uri cannot be found then it is created. a #GBookmarkFile a valid URI a MIME type Sets the last time the bookmark for @uri was last modified. If no bookmark for @uri is found then it is created. The "modified" time should only be set when the bookmark's meta-data was actually changed. Every function of #GBookmarkFile that modifies a bookmark also changes the modification time, except for g_bookmark_file_set_visited_date_time(). Use g_bookmark_file_set_modified_date_time() instead, as `time_t` is deprecated due to the year 2038 problem. a #GBookmarkFile a valid URI a timestamp or -1 to use the current time Sets the last time the bookmark for @uri was last modified. If no bookmark for @uri is found then it is created. The "modified" time should only be set when the bookmark's meta-data was actually changed. Every function of #GBookmarkFile that modifies a bookmark also changes the modification time, except for g_bookmark_file_set_visited_date_time(). a #GBookmarkFile a valid URI a #GDateTime Sets @title as the title of the bookmark for @uri inside the bookmark file @bookmark. If @uri is %NULL, the title of @bookmark is set. If a bookmark for @uri cannot be found then it is created. a #GBookmarkFile a valid URI or %NULL a UTF-8 encoded string Sets the time the bookmark for @uri was last visited. If no bookmark for @uri is found then it is created. The "visited" time should only be set if the bookmark was launched, either using the command line retrieved by g_bookmark_file_get_application_info() or by the default application for the bookmark's MIME type, retrieved using g_bookmark_file_get_mime_type(). Changing the "visited" time does not affect the "modified" time. Use g_bookmark_file_set_visited_date_time() instead, as `time_t` is deprecated due to the year 2038 problem. a #GBookmarkFile a valid URI a timestamp or -1 to use the current time Sets the time the bookmark for @uri was last visited. If no bookmark for @uri is found then it is created. The "visited" time should only be set if the bookmark was launched, either using the command line retrieved by g_bookmark_file_get_application_info() or by the default application for the bookmark's MIME type, retrieved using g_bookmark_file_get_mime_type(). Changing the "visited" time does not affect the "modified" time. a #GBookmarkFile a valid URI a #GDateTime This function outputs @bookmark as a string. a newly allocated string holding the contents of the #GBookmarkFile a #GBookmarkFile return location for the length of the returned string, or %NULL This function outputs @bookmark into a file. The write process is guaranteed to be atomic by using g_file_set_contents() internally. %TRUE if the file was successfully written. a #GBookmarkFile path of the output file Error codes returned by bookmark file parsing. URI was ill-formed a requested field was not found a requested application did not register a bookmark a requested URI was not found document was ill formed the text being parsed was in an unknown encoding an error occurred while writing requested file was not found Contains the public fields of a `GByteArray`. a pointer to the element data. The data may be moved as elements are added to the `GByteArray` the number of elements in the `GByteArray` Adds the given bytes to the end of the `GByteArray`. The array will grow in size automatically if necessary. The `GByteArray` a byte array the byte data to be added the number of bytes to add Frees the memory allocated by the `GByteArray`. If @free_segment is true it frees the actual byte data. If the reference count of @array is greater than one, the `GByteArray` wrapper is preserved but the size of @array will be set to zero. The allocated element data if @free_segment is false, otherwise `NULL`. a byte array if true, the actual byte data is freed as well Transfers the data from the `GByteArray` into a new immutable [struct@GLib.Bytes]. The `GByteArray` is freed unless the reference count of @array is greater than one, in which the `GByteArray` wrapper is preserved but the size of @array will be set to zero. This is identical to using [ctor@GLib.Bytes.new_take] and [func@GLib.ByteArray.free] together. The new immutable [struct@GLib.Bytes] representing same byte data that was in the array a byte array Creates a new `GByteArray` with a reference count of 1. The new `GByteArray` Creates a byte array containing the @data. After this call, @data belongs to the `GByteArray` and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with [func@GLib.free]. Do not use it if @len is greater than [`G_MAXUINT`](types.html#guint). `GByteArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new `GByteArray` the byte data for the array the length of @data Adds the given data to the start of the `GByteArray`. The array will grow in size automatically if necessary. The `GByteArray` a byte array the byte data to be added the number of bytes to add Atomically increments the reference count of @array by one. This function is thread-safe and may be called from any thread. The passed in `GByteArray` a byte array Removes the byte at the given index from a `GByteArray`. The following bytes are moved down one place. The `GByteArray` a byte array the index of the byte to remove Removes the byte at the given index from a `GByteArray`. The last element in the array is used to fill in the space, so this function does not preserve the order of the `GByteArray`. But it is faster than [func@GLib.ByteArray.remove_index]. The `GByteArray` a byte array the index of the byte to remove Removes the given number of bytes starting at the given index from a `GByteArray`. The following elements are moved to close the gap. The `GByteArray` a byte array the index of the first byte to remove the number of bytes to remove Sets the size of the `GByteArray`, expanding it if necessary. The `GByteArray` a byte array the new size of the `GByteArray` Creates a new `GByteArray` with @reserved_size bytes preallocated. This avoids frequent reallocation, if you are going to add many bytes to the array. Note however that the size of the array is still 0. The new `GByteArray` the number of bytes preallocated Sorts a byte array, using @compare_func which should be a `qsort()`-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater than zero if first arg is greater than second arg). If two array elements compare equal, their order in the sorted array is undefined. If you want equal elements to keep their order (i.e. you want a stable sort) you can write a comparison function that, if two elements would otherwise compare equal, compares them by their addresses. a byte array the comparison function Like [func@GLib.ByteArray.sort], but the comparison function takes an extra user data argument. a byte array the comparison function the data to pass to @compare_func Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller. The allocated element data a byte array the pointer to retrieve the number of elements of the original array Atomically decrements the reference count of @array by one. If the reference count drops to 0, all memory allocated by the array is released. This function is thread-safe and may be called from any thread. a byte array A simple reference counted data type representing an immutable sequence of zero or more bytes from an unspecified origin. The purpose of a `GBytes` is to keep the memory region that it holds alive for as long as anyone holds a reference to the bytes. When the last reference count is dropped, the memory is released. Multiple unrelated callers can use byte data in the `GBytes` without coordinating their activities, resting assured that the byte data will not change or move while they hold a reference. A `GBytes` can come from many different origins that may have different procedures for freeing the memory region. Examples are memory from [func@GLib.malloc], from memory slices, from a [struct@GLib.MappedFile] or memory from other allocators. `GBytes` work well as keys in [struct@GLib.HashTable]. Use [method@GLib.Bytes.equal] and [method@GLib.Bytes.hash] as parameters to [func@GLib.HashTable.new] or [func@GLib.HashTable.new_full]. `GBytes` can also be used as keys in a [struct@GLib.Tree] by passing the [method@GLib.Bytes.compare] function to [ctor@GLib.Tree.new]. The data pointed to by this bytes must not be modified. For a mutable array of bytes see [struct@GLib.ByteArray]. Use [method@GLib.Bytes.unref_to_array] to create a mutable array for a `GBytes` sequence. To create an immutable `GBytes` from a mutable [struct@GLib.ByteArray], use the [func@GLib.ByteArray.free_to_bytes] function. Creates a new [struct@GLib.Bytes] from @data. @data is copied. If @size is 0, @data may be `NULL`. As an optimization, [ctor@GLib.Bytes.new] may avoid an extra allocation by copying the data within the resulting bytes structure if sufficiently small (since GLib 2.84). a new [struct@GLib.Bytes] the data to be used for the bytes the size of @data Creates a [struct@GLib.Bytes] which is a subsection of another `GBytes`. The @offset + @length may not be longer than the size of @bytes. A reference to @bytes will be held by the newly created `GBytes` until the byte data is no longer needed. Since 2.56, if @offset is 0 and @length matches the size of @bytes, then @bytes will be returned with the reference count incremented by 1. If @bytes is a slice of another `GBytes`, then the resulting `GBytes` will reference the same `GBytes` instead of @bytes. This allows consumers to simplify the usage of `GBytes` when asynchronously writing to streams. a new [struct@GLib.Bytes] a [struct@GLib.Bytes] offset which subsection starts at length of subsection Creates a new [struct@GLib.Bytes] from static data. @data must be static (ie: never modified or freed). It may be `NULL` if @size is 0. a new [struct@GLib.Bytes] the data to be used for the bytes the size of @data Creates a new [struct@GLib.Bytes] from @data. After this call, @data belongs to the `GBytes` and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with [func@GLib.free]. For creating `GBytes` with memory from other allocators, see [ctor@GLib.Bytes.new_with_free_func]. @data may be `NULL` if @size is 0. a new [struct@GLib.Bytes] the data to be used for the bytes the size of @data Creates a [struct@GLib.Bytes] from @data. When the last reference is dropped, @free_func will be called with the @user_data argument. @data must not be modified after this call is made until @free_func has been called to indicate that the bytes is no longer in use. @data may be `NULL` if @size is 0. a new [struct@GLib.Bytes] the data to be used for the bytes the size of @data the function to call to release the data data to pass to @free_func Compares the two [struct@GLib.Bytes] values. This function can be used to sort `GBytes` instances in lexicographical order. If @bytes1 and @bytes2 have different length but the shorter one is a prefix of the longer one then the shorter one is considered to be less than the longer one. Otherwise the first byte where both differ is used for comparison. If @bytes1 has a smaller value at that position it is considered less, otherwise greater than @bytes2. a negative value if @bytes1 is less than @bytes2, a positive value if @bytes1 is greater than @bytes2, and zero if @bytes1 is equal to @bytes2 a pointer to a [struct@GLib.Bytes] a pointer to a [struct@GLib.Bytes] to compare with @bytes1 Compares the two [struct@GLib.Bytes] values being pointed to and returns `TRUE` if they are equal. This function can be passed to [func@GLib.HashTable.new] as the @key_equal_func parameter, when using non-`NULL` `GBytes` pointers as keys in a [struct@GLib.HashTable]. `TRUE` if the two keys match. a pointer to a [struct@GLib.Bytes] a pointer to a [struct@GLib.Bytes] to compare with @bytes1 Get the byte data in the [struct@GLib.Bytes]. This data should not be modified. This function will always return the same pointer for a given `GBytes`. `NULL` may be returned if @size is 0. This is not guaranteed, as the `GBytes` may represent an empty string with @data non-`NULL` and @size as 0. `NULL` will not be returned if @size is non-zero. a pointer to the byte data a [struct@GLib.Bytes] location to return size of byte data Gets a pointer to a region in @bytes. The region starts at @offset many bytes from the start of the data and contains @n_elements many elements of @element_size size. @n_elements may be zero, but @element_size must always be non-zero. Ideally, @element_size is a static constant (eg: `sizeof` a struct). This function does careful bounds checking (including checking for arithmetic overflows) and returns a non-`NULL` pointer if the specified region lies entirely within the @bytes. If the region is in some way out of range, or if an overflow has occurred, then `NULL` is returned. Note: it is possible to have a valid zero-size region. In this case, the returned pointer will be equal to the base pointer of the data of @bytes, plus @offset. This will be non-`NULL` except for the case where @bytes itself was a zero-sized region. Since it is unlikely that you will be using this function to check for a zero-sized region in a zero-sized @bytes, `NULL` effectively always means ‘error’. the requested region, or `NULL` in case of an error a [struct@GLib.Bytes] a non-zero element size an offset to the start of the region within the @bytes the number of elements in the region Get the size of the byte data in the [struct@GLib.Bytes]. This function will always return the same value for a given `GBytes`. the size a [struct@GLib.Bytes] Creates an integer hash code for the byte data in the [struct@GLib.Bytes]. This function can be passed to [func@GLib.HashTable.new] as the @key_hash_func parameter, when using non-`NULL` `GBytes` pointers as keys in a [struct@GLib.HashTable]. a hash value corresponding to the key. a pointer to a [struct@GLib.Bytes] key Increase the reference count on @bytes. the [struct@GLib.Bytes] a [struct@GLib.Bytes] Releases a reference on @bytes. This may result in the bytes being freed. If @bytes is `NULL`, it will return immediately. a [struct@GLib.Bytes] Unreferences the bytes, and returns a new mutable [struct@GLib.ByteArray] containing the same byte data. As an optimization, the byte data is transferred to the array without copying if this was the last reference to @bytes and @bytes was created with [ctor@GLib.Bytes.new], [ctor@GLib.Bytes.new_take] or [func@GLib.ByteArray.free_to_bytes] and the buffer was larger than the size [struct@GLib.Bytes] may internalize within its allocation. In all other cases the data is copied. Do not use it if @bytes contains more than %G_MAXUINT bytes. [struct@GLib.ByteArray] stores the length of its data in `guint`, which may be shorter than `gsize`, that @bytes is using. a new mutable [struct@GLib.ByteArray] containing the same byte data a [struct@GLib.Bytes] Unreferences the bytes, and returns a pointer the same byte data contents. As an optimization, the byte data is returned without copying if this was the last reference to @bytes and @bytes was created with [ctor@GLib.Bytes.new], [ctor@GLib.Bytes.new_take] or [func@GLib.ByteArray.free_to_bytes] and the buffer was larger than the size [struct@GLib.Bytes] may internalize within its allocation. In all other cases the data is copied. a pointer to the same byte data, which should be freed with [func@GLib.free] a [struct@GLib.Bytes] location to place the length of the returned data Checks whether the version of the GLib library that is being compiled against is greater than or equal to the given one. See glib_check_version() for a runtime check. the major version to check for the minor version to check for the micro version to check for The set of uppercase ASCII alphabet characters. Used for specifying valid identifier characters in #GScannerConfig. The set of ASCII digits. Used for specifying valid identifier characters in #GScannerConfig. The set of lowercase ASCII alphabet characters. Used for specifying valid identifier characters in #GScannerConfig. Macro to check if the current compiler supports a specified @version of the C++ standard. Such value must be numeric and can be provided both in the short form for the well-known versions (e.g. `11`, `17`...) or in the complete form otherwise (e.g. `201103L`, `201703L`, `205503L`...). When a C compiler is used, the macro is defined and returns always %FALSE. This value is compared against %G_CXX_STD_VERSION. |[<!-- language="C" --> #if G_CXX_STD_CHECK_VERSION(20) #endif ]| See also: %G_C_STD_CHECK_VERSION The C++ version to be checked for compatibility Macro to check if the current compiler supports a specified @version of the C standard. Such value must be numeric and can be provided both in the short form for the well-known versions (e.g. `90`, `99`...) or in the complete form otherwise (e.g. `199000L`, `199901L`, `205503L`...). When a C++ compiler is used, the macro is defined and returns always %FALSE. This value is compared against %G_C_STD_VERSION. |[<!-- language="C" --> #if G_C_STD_CHECK_VERSION(17) #endif ]| See also: %G_CXX_STD_CHECK_VERSION The C version to be checked for compatibility The C standard version the code is compiling against, it's normally defined with the same value of `__STDC_VERSION__` for C standard compatible compilers, while it uses the lowest standard version in pure MSVC, given that in such compiler the definition depends on a compilation flag. This is granted to be undefined when compiling with a C++ compiler. See also: %G_C_STD_CHECK_VERSION and %G_CXX_STD_VERSION A `GCache` allows sharing of complex data structures, in order to save system resources. `GCache` uses keys and values. A `GCache` key describes the properties of a particular resource. A `GCache` value is the actual resource. `GCache` has been marked as deprecated, since this API is rarely used and not very actively maintained. Use a #GHashTable instead Frees the memory allocated for the #GCache. Note that it does not destroy the keys and values which were contained in the #GCache. Use a #GHashTable instead a #GCache Gets the value corresponding to the given key, creating it if necessary. It first checks if the value already exists in the #GCache, by using the @key_equal_func function passed to g_cache_new(). If it does already exist it is returned, and its reference count is increased by one. If the value does not currently exist, if is created by calling the @value_new_func. The key is duplicated by calling @key_dup_func and the duplicated key and value are inserted into the #GCache. Use a #GHashTable instead a pointer to a #GCache value a #GCache a key describing a #GCache object Calls the given function for each of the keys in the #GCache. NOTE @func is passed three parameters, the value and key of a cache entry and the @user_data. The order of value and key is different from the order in which g_hash_table_foreach() passes key-value pairs to its callback function ! Use a #GHashTable instead a #GCache the function to call with each #GCache key user data to pass to the function Decreases the reference count of the given value. If it drops to 0 then the value and its corresponding key are destroyed, using the @value_destroy_func and @key_destroy_func passed to g_cache_new(). Use a #GHashTable instead a #GCache the value to remove Calls the given function for each of the values in the #GCache. The reason is that it passes pointers to internal data structures to @func; use g_cache_key_foreach() instead a #GCache the function to call with each #GCache value user data to pass to the function Creates a new #GCache. Use a #GHashTable instead a new #GCache a function to create a new object given a key. This is called by g_cache_insert() if an object with the given key does not already exist a function to destroy an object. It is called by g_cache_remove() when the object is no longer needed (i.e. its reference count drops to 0) a function to copy a key. It is called by g_cache_insert() if the key does not already exist in the #GCache a function to destroy a key. It is called by g_cache_remove() when the object is no longer needed (i.e. its reference count drops to 0) a function to create a hash value from a key a function to create a hash value from a value a function to compare two keys. It should return %TRUE if the two keys are equivalent Specifies the type of the @value_destroy_func and @key_destroy_func functions passed to g_cache_new(). The functions are passed a pointer to the #GCache key or #GCache value and should free any memory and other resources associated with it. Use a #GHashTable instead the #GCache value to destroy Specifies the type of the @key_dup_func function passed to g_cache_new(). The function is passed a key (__not__ a value as the prototype implies) and should return a duplicate of the key. Use a #GHashTable instead a copy of the #GCache key the #GCache key to destroy (__not__ a #GCache value as it seems) Specifies the type of the @value_new_func function passed to g_cache_new(). It is passed a #GCache key and should create the value corresponding to the key. Use a #GHashTable instead a new #GCache value corresponding to the key. a #GCache key GLib provides a generic API for computing checksums (or ‘digests’) for a sequence of arbitrary bytes, using various hashing algorithms like MD5, SHA-1 and SHA-256. Checksums are commonly used in various environments and specifications. To create a new `GChecksum`, use [ctor@GLib.Checksum.new]. To free a `GChecksum`, use [method@GLib.Checksum.free]. GLib supports incremental checksums using the `GChecksum` data structure, by calling [method@GLib.Checksum.update] as long as there’s data available and then using [method@GLib.Checksum.get_string] or [method@GLib.Checksum.get_digest] to compute the checksum and return it either as a string in hexadecimal form, or as a raw sequence of bytes. To compute the checksum for binary blobs and nul-terminated strings in one go, use the convenience functions [func@GLib.compute_checksum_for_data] and [func@GLib.compute_checksum_for_string], respectively. Creates a new #GChecksum, using the checksum algorithm @checksum_type. If the @checksum_type is not known, %NULL is returned. A #GChecksum can be used to compute the checksum, or digest, of an arbitrary binary blob, using different hashing algorithms. A #GChecksum works by feeding a binary blob through g_checksum_update() until there is data to be checked; the digest can then be extracted using g_checksum_get_string(), which will return the checksum as a hexadecimal string; or g_checksum_get_digest(), which will return a vector of raw bytes. Once either g_checksum_get_string() or g_checksum_get_digest() have been called on a #GChecksum, the checksum will be closed and it won't be possible to call g_checksum_update() on it anymore. the newly created #GChecksum, or %NULL. Use g_checksum_free() to free the memory allocated by it. the desired type of checksum Copies a #GChecksum. If @checksum has been closed, by calling g_checksum_get_string() or g_checksum_get_digest(), the copied checksum will be closed as well. the copy of the passed #GChecksum. Use g_checksum_free() when finished using it. the #GChecksum to copy Frees the memory allocated for @checksum. a #GChecksum Gets the digest from @checksum as a raw binary vector and places it into @buffer. The size of the digest depends on the type of checksum. Once this function has been called, the #GChecksum is closed and can no longer be updated with g_checksum_update(). a #GChecksum output buffer an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest. Gets the digest as a hexadecimal string. Once this function has been called the #GChecksum can no longer be updated with g_checksum_update(). The hexadecimal characters will be lower case. the hexadecimal representation of the checksum. The returned string is owned by the checksum and should not be modified or freed. a #GChecksum Resets the state of the @checksum back to its initial state. the #GChecksum to reset Feeds @data into an existing #GChecksum. The checksum must still be open, that is g_checksum_get_string() or g_checksum_get_digest() must not have been called on @checksum. a #GChecksum buffer used to compute the checksum size of the buffer, or -1 if it is a null-terminated string. Gets the length in bytes of digests of type @checksum_type the checksum length, or -1 if @checksum_type is not supported. a #GChecksumType The hashing algorithm to be used by #GChecksum when performing the digest of some data. Note that the #GChecksumType enumeration may be extended at a later date to include new hashing algorithm types. Use the MD5 hashing algorithm Use the SHA-1 hashing algorithm Use the SHA-256 hashing algorithm Use the SHA-512 hashing algorithm (Since: 2.36) Use the SHA-384 hashing algorithm (Since: 2.51) Prototype of a #GChildWatchSource callback, called when a child process has exited. To interpret @wait_status, see the documentation for [func@GLib.spawn_check_wait_status]. In particular, on Unix platforms, note that it is usually not equal to the integer passed to `exit()` or returned from `main()`. the process id of the child process Status information about the child process, encoded in a platform-specific manner user data passed to [func@GLib.child_watch_add] Specifies the type of function passed to [func@GLib.clear_handle_id] The implementation is expected to free the resource identified by @handle_id; for instance, if @handle_id is a [struct@GLib.Source] ID, [func@GLib.Source.remove] can be used. the handle ID to clear Specifies the type of a comparison function used to compare two values. The function should return a negative integer if the first value comes before the second, 0 if they are equal, or a positive integer if the first value comes after the second. negative value if @a < @b; zero if @a = @b; positive value if @a > @b a value a value to compare with user data Specifies the type of a comparison function used to compare two values. The function should return a negative integer if the first value comes before the second, 0 if they are equal, or a positive integer if the first value comes after the second. negative value if @a < @b; zero if @a = @b; positive value if @a > @b a value a value to compare with `GCompletion` provides support for automatic completion of a string using any group of target strings. It is typically used for file name completion as is common in many UNIX shells. A `GCompletion` is created using [func@GLib.Completion.new]. Target items are added and removed with [method@GLib.Completion.add_items], [method@GLib.Completion.remove_items] and [method@GLib.Completion.clear_items]. A completion attempt is requested with [method@GLib.Completion.complete] or [method@GLib.Completion.complete_utf8]. When no longer needed, the `GCompletion` is freed with [method@GLib.Completion.free]. Items in the completion can be simple strings (e.g. filenames), or pointers to arbitrary data structures. If data structures are used you must provide a [type@GLib.CompletionFunc] in [func@GLib.Completion.new], which retrieves the item’s string from the data structure. You can change the way in which strings are compared by setting a different [type@GLib.CompletionStrncmpFunc] in [method@GLib.Completion.set_compare]. `GCompletion` has been marked as deprecated, since this API is rarely used and not very actively maintained. Rarely used API list of target items (strings or data structures). function which is called to get the string associated with a target item. It is %NULL if the target items are strings. the last prefix passed to g_completion_complete() or g_completion_complete_utf8(). the list of items which begin with @prefix. The function to use when comparing strings. Use g_completion_set_compare() to modify this function. Adds items to the #GCompletion. Rarely used API the #GCompletion. the list of items to add. Removes all items from the #GCompletion. The items are not freed, so if the memory was dynamically allocated, it should be freed after calling this function. Rarely used API the #GCompletion. Attempts to complete the string @prefix using the #GCompletion target items. Rarely used API the list of items whose strings begin with @prefix. This should not be changed. the #GCompletion. the prefix string, typically typed by the user, which is compared with each of the items. if non-%NULL, returns the longest prefix which is common to all items that matched @prefix, or %NULL if no items matched @prefix. This string should be freed when no longer needed. Attempts to complete the string @prefix using the #GCompletion target items. In contrast to g_completion_complete(), this function returns the largest common prefix that is a valid UTF-8 string, omitting a possible common partial character. You should use this function instead of g_completion_complete() if your items are UTF-8 strings. Rarely used API the list of items whose strings begin with @prefix. This should not be changed. the #GCompletion the prefix string, typically used by the user, which is compared with each of the items if non-%NULL, returns the longest prefix which is common to all items that matched @prefix, or %NULL if no items matched @prefix. This string should be freed when no longer needed. Frees all memory used by the #GCompletion. The items are not freed, so if the memory was dynamically allocated, it should be freed after calling this function. Rarely used API the #GCompletion. Removes items from a #GCompletion. The items are not freed, so if the memory was dynamically allocated, free @items with g_list_free_full() after calling this function. Rarely used API the #GCompletion. the items to remove. Sets the function to use for string comparisons. The default string comparison function is strncmp(). Rarely used API a #GCompletion. the string comparison function. Creates a new #GCompletion. Rarely used API the new #GCompletion. the function to be called to return the string representing an item in the #GCompletion, or %NULL if strings are going to be used as the #GCompletion items. Specifies the type of the function passed to g_completion_new(). It should return the string corresponding to the given target item. This is used when you use data structures as #GCompletion items. Rarely used API the string corresponding to the item. the completion item. Specifies the type of the function passed to g_completion_set_compare(). This is used when you use strings as #GCompletion items. Rarely used API an integer less than, equal to, or greater than zero if the first @n bytes of @s1 is found, respectively, to be less than, to match, or to be greater than the first @n bytes of @s2. string to compare with @s2. string to compare with @s1. maximal number of bytes to compare. The #GCond struct is an opaque data structure that represents a condition. Threads can block on a #GCond if they find a certain condition to be false. If other threads change the state of this condition they signal the #GCond, and that causes the waiting threads to be woken up. Consider the following example of a shared variable. One or more threads can wait for data to be published to the variable and when another thread publishes the data, it can signal one of the waiting threads to wake up to collect the data. Here is an example for using GCond to block a thread until a condition is satisfied: |[<!-- language="C" --> gpointer current_data = NULL; GMutex data_mutex; GCond data_cond; void push_data (gpointer data) { g_mutex_lock (&data_mutex); current_data = data; g_cond_signal (&data_cond); g_mutex_unlock (&data_mutex); } gpointer pop_data (void) { gpointer data; g_mutex_lock (&data_mutex); while (!current_data) g_cond_wait (&data_cond, &data_mutex); data = current_data; current_data = NULL; g_mutex_unlock (&data_mutex); return data; } ]| Whenever a thread calls pop_data() now, it will wait until current_data is non-%NULL, i.e. until some other thread has called push_data(). The example shows that use of a condition variable must always be paired with a mutex. Without the use of a mutex, there would be a race between the check of @current_data by the while loop in pop_data() and waiting. Specifically, another thread could set @current_data after the check, and signal the cond (with nobody waiting on it) before the first thread goes to sleep. #GCond is specifically useful for its ability to release the mutex and go to sleep atomically. It is also important to use the g_cond_wait() and g_cond_wait_until() functions only inside a loop which checks for the condition to be true. See g_cond_wait() for an explanation of why the condition may not be true even after it returns. If a #GCond is allocated in static storage then it can be used without initialisation. Otherwise, you should call g_cond_init() on it and g_cond_clear() when done. A #GCond should only be accessed via the g_cond_ functions. If threads are waiting for @cond, all of them are unblocked. If no threads are waiting for @cond, this function has no effect. It is good practice to lock the same mutex as the waiting threads while calling this function, though not required. a #GCond Frees the resources allocated to a #GCond with g_cond_init(). This function should not be used with a #GCond that has been statically allocated. Calling g_cond_clear() for a #GCond on which threads are blocking leads to undefined behaviour. an initialised #GCond Destroys a #GCond that has been created with g_cond_new(). Calling g_cond_free() for a #GCond on which threads are blocking leads to undefined behaviour. GCond can now be statically allocated, or embedded in structures and initialised with g_cond_init(). a #GCond Initialises a #GCond so that it can be used. This function is useful to initialise a #GCond that has been allocated as part of a larger structure. It is not necessary to initialise a #GCond that has been statically allocated. To undo the effect of g_cond_init() when a #GCond is no longer needed, use g_cond_clear(). Calling g_cond_init() on an already-initialised #GCond leads to undefined behaviour. an uninitialized #GCond If threads are waiting for @cond, at least one of them is unblocked. If no threads are waiting for @cond, this function has no effect. It is good practice to hold the same lock as the waiting thread while calling this function, though not required. a #GCond Waits until this thread is woken up on @cond, but not longer than until the time specified by @abs_time. The @mutex is unlocked before falling asleep and locked again before resuming. If @abs_time is %NULL, g_cond_timed_wait() acts like g_cond_wait(). This function can be used even if g_thread_init() has not yet been called, and, in that case, will immediately return %TRUE. To easily calculate @abs_time a combination of g_get_real_time() and g_time_val_add() can be used. Use g_cond_wait_until() instead. %TRUE if @cond was signalled, or %FALSE on timeout a #GCond a #GMutex that is currently locked a #GTimeVal, determining the final time Atomically releases @mutex and waits until @cond is signalled. When this function returns, @mutex is locked again and owned by the calling thread. When using condition variables, it is possible that a spurious wakeup may occur (ie: g_cond_wait() returns even though g_cond_signal() was not called). It's also possible that a stolen wakeup may occur. This is when g_cond_signal() is called, but another thread acquires @mutex before this thread and modifies the state of the program in such a way that when g_cond_wait() is able to return, the expected condition is no longer met. For this reason, g_cond_wait() must always be used in a loop. See the documentation for #GCond for a complete example. a #GCond a #GMutex that is currently locked Waits until either @cond is signalled or @end_time has passed. As with g_cond_wait() it is possible that a spurious or stolen wakeup could occur. For that reason, waiting on a condition variable should always be in a loop, based on an explicitly-checked predicate. %TRUE is returned if the condition variable was signalled (or in the case of a spurious wakeup). %FALSE is returned if @end_time has passed. The following code shows how to correctly perform a timed wait on a condition variable (extending the example presented in the documentation for #GCond): |[<!-- language="C" --> gpointer pop_data_timed (void) { gint64 end_time; gpointer data; g_mutex_lock (&data_mutex); end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND; while (!current_data) if (!g_cond_wait_until (&data_cond, &data_mutex, end_time)) { // timeout has passed. g_mutex_unlock (&data_mutex); return NULL; } // there is data for us data = current_data; current_data = NULL; g_mutex_unlock (&data_mutex); return data; } ]| Notice that the end time is calculated once, before entering the loop and reused. This is the motivation behind the use of absolute time on this API -- if a relative time of 5 seconds were passed directly to the call and a spurious wakeup occurred, the program would have to start over waiting again (which would lead to a total wait time of more than 5 seconds). %TRUE on a signal, %FALSE on a timeout a #GCond a #GMutex that is currently locked the monotonic time to wait until Allocates and initializes a new #GCond. GCond can now be statically allocated, or embedded in structures and initialised with g_cond_init(). a newly allocated #GCond. Free with g_cond_free() Error codes returned by character set conversion routines. Conversion between the requested character sets is not supported. Invalid byte sequence in conversion input; or the character sequence could not be represented in the target character set. Conversion failed for some reason. Partial character sequence at end of input. URI is invalid. Pathname is not an absolute path. No memory available. Since: 2.40 An embedded NUL character is present in conversion output where a NUL-terminated string is expected. Since: 2.56 A function of this signature is used to copy the node data when doing a deep-copy of a tree. A pointer to the copy A pointer to the data which should be copied Additional data A bitmask that restricts the possible flags passed to g_datalist_set_flags(). Passing a flags value where flags & ~G_DATALIST_FLAGS_MASK != 0 is an error. Represents an invalid #GDateDay. Represents an invalid Julian day number. Represents an invalid year. A convenience form of g_log_structured(), recommended to be added to functions when debugging. It prints the current monotonic time and the code location using %G_STRLOC. Defines the appropriate cleanup function for a pointer type. The function will not be called if the variable to be cleaned up contains %NULL. This will typically be the `_free()` or `_unref()` function for the given type. With this definition, it will be possible to use g_autoptr() with @TypeName. |[ G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref) ]| This macro should be used unconditionally; it is a no-op on compilers where cleanup is not supported. a type name to define a g_autoptr() cleanup function for the cleanup function Defines the appropriate cleanup function for a type. This will typically be the `_clear()` function for the given type. With this definition, it will be possible to use g_auto() with @TypeName. |[ G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear) ]| This macro should be used unconditionally; it is a no-op on compilers where cleanup is not supported. a type name to define a g_auto() cleanup function for the clear function Defines the appropriate cleanup function for a type. With this definition, it will be possible to use g_auto() with @TypeName. This function will be rarely used. It is used with pointer-based typedefs and non-pointer types where the value of the variable represents a resource that must be freed. Two examples are #GStrv and file descriptors. @none specifies the "none" value for the type in question. It is probably something like %NULL or `-1`. If the variable is found to contain this value then the free function will not be called. |[ G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL) ]| This macro should be used unconditionally; it is a no-op on compilers where cleanup is not supported. a type name to define a g_auto() cleanup function for the free function the "none" value for the type A convenience macro which defines two functions. First, returning the #GQuark for the extended error type @ErrorType; it is called `error_type_quark()`. Second, returning the private data from a passed #GError; it is called `error_type_get_private()`. For this macro to work, a type named `ErrorTypePrivate` should be defined, `error_type_private_init()`, `error_type_private_copy()` and `error_type_private_clear()` functions need to be either declared or defined. The functions should be similar to #GErrorInitFunc, #GErrorCopyFunc and #GErrorClearFunc, respectively, but they should receive the private data type instead of #GError. See [Extended #GError Domains](error-reporting.html#extended-gerror-domains) for an example. name to return a #GQuark for prefix for the function name A convenience macro which defines a function returning the #GQuark for the name @QN. The function will be named @q_n_quark(). Note that the quark name will be stringified automatically in the macro, so you shouldn't use double quotes. the name to return a #GQuark for prefix for the function name The directory separator character. This is `'/'` on UNIX machines and `'\'` under Windows. The directory separator as a string. This is `"/"` on UNIX machines and `"\"` under Windows. An opaque data structure that represents a keyed data list. See also: [Keyed data lists](datalist-and-dataset.html). Specifies the type of function passed to g_dataset_foreach(). It is called with each #GQuark id and associated data element, together with the @user_data parameter supplied to g_dataset_foreach(). the #GQuark id to identifying the data element. the data element. user data passed to g_dataset_foreach(). `GDate` is a struct for calendrical calculations. The `GDate` data structure represents a day between January 1, Year 1, and sometime a few thousand years in the future (right now it will go to the year 65535 or so, but [method@GLib.Date.set_parse] only parses up to the year 8000 or so - just count on "a few thousand"). `GDate` is meant to represent everyday dates, not astronomical dates or historical dates or ISO timestamps or the like. It extrapolates the current Gregorian calendar forward and backward in time; there is no attempt to change the calendar to match time periods or locations. `GDate` does not store time information; it represents a day. The `GDate` implementation has several nice features; it is only a 64-bit struct, so storing large numbers of dates is very efficient. It can keep both a Julian and day-month-year representation of the date, since some calculations are much easier with one representation or the other. A Julian representation is simply a count of days since some fixed day in the past; for #GDate the fixed day is January 1, 1 AD. ("Julian" dates in the #GDate API aren't really Julian dates in the technical sense; technically, Julian dates count from the start of the Julian period, Jan 1, 4713 BC). `GDate` is simple to use. First you need a "blank" date; you can get a dynamically allocated date from [ctor@GLib.Date.new], or you can declare an automatic variable or array and initialize it by calling [method@GLib.Date.clear]. A cleared date is safe; it's safe to call [method@GLib.Date.set_dmy] and the other mutator functions to initialize the value of a cleared date. However, a cleared date is initially invalid, meaning that it doesn't represent a day that exists. It is undefined to call any of the date calculation routines on an invalid date. If you obtain a date from a user or other unpredictable source, you should check its validity with the [method@GLib.Date.valid] predicate. [method@GLib.Date.valid] is also used to check for errors with [method@GLib.Date.set_parse] and other functions that can fail. Dates can be invalidated by calling [method@GLib.Date.clear] again. It is very important to use the API to access the `GDate` struct. Often only the day-month-year or only the Julian representation is valid. Sometimes neither is valid. Use the API. GLib also features `GDateTime` which represents a precise time. the Julian representation of the date this bit is set if @julian_days is valid this is set if @day, @month and @year are valid the day of the day-month-year representation of the date, as a number between 1 and 31 the month of the day-month-year representation of the date, as a number between 1 and 12 the year of the day-month-year representation of the date Allocates a #GDate and initializes it to a safe state. The new date will be cleared (as if you'd called g_date_clear()) but invalid (it won't represent an existing day). Free the return value with g_date_free(). a newly-allocated #GDate Create a new #GDate representing the given day-month-year triplet. The triplet you pass in must represent a valid date. Use g_date_valid_dmy() if needed to validate it. The returned #GDate is guaranteed to be non-%NULL and valid. a newly-allocated #GDate initialized with @day, @month, and @year day of the month month of the year year Create a new #GDate representing the given Julian date. The @julian_day you pass in must be valid. Use g_date_valid_julian() if needed to validate it. The returned #GDate is guaranteed to be non-%NULL and valid. a newly-allocated #GDate initialized with @julian_day days since January 1, Year 1 Increments a date some number of days. To move forward by weeks, add weeks*7 days. The date must be valid. a #GDate to increment number of days to move the date forward Increments a date by some number of months. If the day of the month is greater than 28, this routine may change the day of the month (because the destination month may not have the current day in it). The date must be valid. a #GDate to increment number of months to move forward Increments a date by some number of years. If the date is February 29, and the destination year is not a leap year, the date will be changed to February 28. The date must be valid. a #GDate to increment number of years to move forward If @date is prior to @min_date, sets @date equal to @min_date. If @date falls after @max_date, sets @date equal to @max_date. Otherwise, @date is unchanged. Either of @min_date and @max_date may be %NULL. All non-%NULL dates must be valid. a #GDate to clamp minimum accepted value for @date maximum accepted value for @date Initializes one or more #GDate structs to a safe but invalid state. The cleared dates will not represent an existing date, but will not contain garbage. Useful to init a date declared on the stack. Validity can be tested with g_date_valid(). pointer to one or more dates to clear number of dates to clear qsort()-style comparison function for dates. Both dates must be valid. 0 for equal, less than zero if @lhs is less than @rhs, greater than zero if @lhs is greater than @rhs first date to compare second date to compare Copies a GDate to a newly-allocated GDate. If the input was invalid (as determined by g_date_valid()), the invalid state will be copied as is into the new object. a newly-allocated #GDate initialized from @date a #GDate to copy Computes the number of days between two dates. If @date2 is prior to @date1, the returned value is negative. Both dates must be valid. the number of days between @date1 and @date2 the first date the second date Frees a #GDate returned from g_date_new(). a #GDate to free Returns the day of the month. The date must be valid. day of the month a #GDate to extract the day of the month from Returns the day of the year, where Jan 1 is the first day of the year. The date must be valid. day of the year a #GDate to extract day of year from Returns the week of the year, where weeks are interpreted according to ISO 8601. ISO 8601 week number of the year. a valid #GDate Returns the Julian day or "serial number" of the #GDate. The Julian day is simply the number of days since January 1, Year 1; i.e., January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2, etc. The date must be valid. Julian day a #GDate to extract the Julian day from Returns the week of the year, where weeks are understood to start on Monday. If the date is before the first Monday of the year, return 0. The date must be valid. week of the year a #GDate Returns the month of the year. The date must be valid. month of the year as a #GDateMonth a #GDate to get the month from Returns the week of the year during which this date falls, if weeks are understood to begin on Sunday. The date must be valid. Can return 0 if the day is before the first Sunday of the year. week number a #GDate Calculates the week of the year during which this date falls. The result depends on which day is considered the first day of the week, which varies by locale. Both `date` and `first_day_of_week` must be valid. If @date is before the start of the first week of the year (for example, before the first Monday in January if @first_day_of_week is [enum@GLib.DateWeekday.MONDAY]) then zero will be returned. week number (starting from 1), or `0` if @date is before the start of the first week of the year a [struct@GLib.Date] the day which is considered the first day of the week (for example, this would be [enum@GLib.DateWeekday.SUNDAY] in US locales, [enum@GLib.DateWeekday.MONDAY] in British locales, and [enum@GLib.DateWeekday.SATURDAY] in Egyptian locales Returns the day of the week for a #GDate. The date must be valid. day of the week as a #GDateWeekday. a #GDate Returns the year of a #GDate. The date must be valid. year in which the date falls a #GDate Returns %TRUE if the date is on the first of a month. The date must be valid. %TRUE if the date is the first of the month a #GDate to check Returns %TRUE if the date is the last day of the month. The date must be valid. %TRUE if the date is the last day of the month a #GDate to check Checks if @date1 is less than or equal to @date2, and swap the values if this is not the case. the first date the second date Sets the day of the month for a #GDate. If the resulting day-month-year triplet is invalid, the date will be invalid. a #GDate day to set Sets the value of a #GDate from a day, month, and year. The day-month-year triplet must be valid; if you aren't sure it is, call g_date_valid_dmy() to check before you set it. a #GDate day month year Sets the value of a #GDate from a Julian day number. a #GDate Julian day number (days since January 1, Year 1) Sets the month of the year for a #GDate. If the resulting day-month-year triplet is invalid, the date will be invalid. a #GDate month to set Parses a user-inputted string @str, and try to figure out what date it represents, taking the [current locale](running.html#locale) into account. If the string is successfully parsed, the date will be valid after the call. Otherwise, it will be invalid. You should check using g_date_valid() to see whether the parsing succeeded. This function is not appropriate for file formats and the like; it isn't very precise, and its exact behavior varies with the locale. It's intended to be a heuristic routine that guesses what the user means by a given string (and it does work pretty well in that capacity). a #GDate to fill in string to parse Sets the value of a date from a #GTime value. The time to date conversion is done using the user's current timezone. Use g_date_set_time_t() instead. a #GDate. #GTime value to set. Sets the value of a date to the date corresponding to a time specified as a time_t. The time to date conversion is done using the user's current timezone. To set the value of a date to the current day, you could write: |[<!-- language="C" --> time_t now = time (NULL); if (now == (time_t) -1) // handle the error g_date_set_time_t (date, now); ]| a #GDate time_t value to set Sets the value of a date from a #GTimeVal value. Note that the @tv_usec member is ignored, because #GDate can't make use of the additional precision. The time to date conversion is done using the user's current timezone. #GTimeVal is not year-2038-safe. Use g_date_set_time_t() instead. a #GDate #GTimeVal value to set Sets the year for a #GDate. If the resulting day-month-year triplet is invalid, the date will be invalid. a #GDate year to set Moves a date some number of days into the past. To move by weeks, just move by weeks*7 days. The date must be valid. a #GDate to decrement number of days to move Moves a date some number of months into the past. If the current day of the month doesn't exist in the destination month, the day of the month may change. The date must be valid. a #GDate to decrement number of months to move Moves a date some number of years into the past. If the current day doesn't exist in the destination year (i.e. it's February 29 and you move to a non-leap-year) then the day is changed to February 29. The date must be valid. a #GDate to decrement number of years to move Fills in the date-related bits of a struct tm using the @date value. Initializes the non-date parts with something safe but meaningless. a #GDate to set the struct tm from struct tm to fill Returns %TRUE if the #GDate represents an existing day. The date must not contain garbage; it should have been initialized with g_date_clear() if it wasn't allocated by one of the g_date_new() variants. Whether the date is valid a #GDate to check Returns the number of days in a month, taking leap years into account. number of days in @month during the @year month year Returns the number of weeks in the year, where weeks are taken to start on Monday. Will be 52 or 53. The date must be valid. (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it's a leap year. This function is basically telling you how many Mondays are in the year, i.e. there are 53 Mondays if one of the extra days happens to be a Monday.) number of Mondays in the year a year Returns the number of weeks in the year, where weeks are taken to start on Sunday. Will be 52 or 53. The date must be valid. (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it's a leap year. This function is basically telling you how many Sundays are in the year, i.e. there are 53 Sundays if one of the extra days happens to be a Sunday.) the number of weeks in @year year to count weeks in Calculates the number of weeks in the year. The result depends on which day is considered the first day of the week, which varies by locale. `first_day_of_week` must be valid. The result will be either 52 or 53. Years always have 52 seven-day periods, plus one or two extra days depending on whether it’s a leap year. This function effectively calculates how many @first_day_of_week days there are in the year. the number of weeks in @year year to count weeks in the day which is considered the first day of the week (for example, this would be [enum@GLib.DateWeekday.SUNDAY] in US locales, [enum@GLib.DateWeekday.MONDAY] in British locales, and [enum@GLib.DateWeekday.SATURDAY] in Egyptian locales Returns %TRUE if the year is a leap year. For the purposes of this function, leap year is every year divisible by 4 unless that year is divisible by 100. If it is divisible by 100 it would be a leap year only if that year is also divisible by 400. %TRUE if the year is a leap year year to check Generates a printed representation of the date, in a [locale](running.html#locale)-specific way. Works just like the platform's C library strftime() function, but only accepts date-related formats; time-related formats give undefined results. Date must be valid. Unlike strftime() (which uses the locale encoding), works on a UTF-8 format string and stores a UTF-8 result. This function does not provide any conversion specifiers in addition to those implemented by the platform's C library. For example, don't expect that using g_date_strftime() would make the \%F provided by the C99 strftime() work on Windows where the C library only complies to C89. number of characters written to the buffer, or `0` if the buffer was too small destination buffer buffer size format string valid #GDate Returns %TRUE if the day of the month is valid (a day is valid if it's between 1 and 31 inclusive). %TRUE if the day is valid day to check Returns %TRUE if the day-month-year triplet forms a valid, existing day in the range of days #GDate understands (Year 1 or later, no more than a few thousand years in the future). %TRUE if the date is a valid one day month year Returns %TRUE if the Julian day is valid. Anything greater than zero is basically a valid Julian, though there is a 32-bit limit. %TRUE if the Julian day is valid Julian day to check Returns %TRUE if the month value is valid. The 12 #GDateMonth enumeration values are the only valid months. %TRUE if the month is valid month Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration values are the only valid weekdays. %TRUE if the weekday is valid weekday Returns %TRUE if the year is valid. Any year greater than 0 is valid, though there is a 16-bit limit to what #GDate will understand. %TRUE if the year is valid year This enumeration isn't used in the API, but may be useful if you need to mark a number as a day, month, or year. a day a month a year Enumeration representing a month; values are %G_DATE_JANUARY, %G_DATE_FEBRUARY, etc. %G_DATE_BAD_MONTH is the invalid value. invalid value January February March April May June July August September October November December `GDateTime` is a structure that combines a Gregorian date and time into a single structure. `GDateTime` provides many conversion and methods to manipulate dates and times. Time precision is provided down to microseconds and the time can range (proleptically) from 0001-01-01 00:00:00 to 9999-12-31 23:59:59.999999. `GDateTime` follows POSIX time in the sense that it is oblivious to leap seconds. `GDateTime` is an immutable object; once it has been created it cannot be modified further. All modifiers will create a new `GDateTime`. Nearly all such functions can fail due to the date or time going out of range, in which case %NULL will be returned. `GDateTime` is reference counted: the reference count is increased by calling [method@GLib.DateTime.ref] and decreased by calling [method@GLib.DateTime.unref]. When the reference count drops to 0, the resources allocated by the `GDateTime` structure are released. Many parts of the API may produce non-obvious results. As an example, adding two months to January 31st will yield March 31st whereas adding one month and then one month again will yield either March 28th or March 29th. Also note that adding 24 hours is not always the same as adding one day (since days containing daylight savings time transitions are either 23 or 25 hours in length). Creates a new #GDateTime corresponding to the given date and time in the time zone @tz. The @year must be between 1 and 9999, @month between 1 and 12 and @day between 1 and 28, 29, 30 or 31 depending on the month and the year. @hour must be between 0 and 23 and @minute must be between 0 and 59. @seconds must be at least 0.0 and must be strictly less than 60.0. It will be rounded down to the nearest microsecond. If the given time is not representable in the given time zone (for example, 02:30 on March 14th 2010 in Toronto, due to daylight savings time) then the time will be rounded up to the nearest existing time (in this case, 03:00). If this matters to you then you should verify the return value for containing the same as the numbers you gave. In the case that the given time is ambiguous in the given time zone (for example, 01:30 on November 7th 2010 in Toronto, due to daylight savings time) then the time falling within standard (ie: non-daylight) time is taken. It not considered a programmer error for the values to this function to be out of range, but in the case that they are, the function will return %NULL. You should release the return value by calling g_date_time_unref() when you are done with it. a new #GDateTime, or %NULL a #GTimeZone the year component of the date the month component of the date the day component of the date the hour component of the date the minute component of the date the number of seconds past the minute Creates a #GDateTime corresponding to the given [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601) @text. ISO 8601 strings of the form `<date><sep><time><tz>` are supported, with some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as mentioned below. Note that as #GDateTime "is oblivious to leap seconds", leap seconds information in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as `23:59:59`. `<sep>` is the separator and can be either 'T', 't' or ' '. The latter two separators are an extension from [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6). `<date>` is in the form: - `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24. - `YYYYMMDD` - Same as above without dividers. - `YYYY-DDD` - Ordinal day where DDD is from 001 to 366, e.g. 2016-237. - `YYYYDDD` - Same as above without dividers. - `YYYY-Www-D` - Week day where ww is from 01 to 52 and D from 1-7, e.g. 2016-W34-3. - `YYYYWwwD` - Same as above without dividers. `<time>` is in the form: - `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123. - `hhmmss(.sss)` - Same as above without dividers. `<tz>` is an optional timezone suffix of the form: - `Z` - UTC. - `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00. - `+hh` or `-hh` - Offset from UTC in hours, e.g. +12. If the timezone is not provided in @text it must be provided in @default_tz (this field is otherwise ignored). This call can fail (returning %NULL) if @text is not a valid ISO 8601 formatted string. You should release the return value by calling g_date_time_unref() when you are done with it. a new #GDateTime, or %NULL an ISO 8601 formatted time string. a #GTimeZone to use if the text doesn't contain a timezone, or %NULL. Creates a #GDateTime corresponding to the given #GTimeVal @tv in the local time zone. The time contained in a #GTimeVal is always stored in the form of seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the local time offset. This call can fail (returning %NULL) if @tv represents a time outside of the supported range of #GDateTime. You should release the return value by calling g_date_time_unref() when you are done with it. #GTimeVal is not year-2038-safe. Use g_date_time_new_from_unix_local() instead. a new #GDateTime, or %NULL a #GTimeVal Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC. The time contained in a #GTimeVal is always stored in the form of seconds elapsed since 1970-01-01 00:00:00 UTC. This call can fail (returning %NULL) if @tv represents a time outside of the supported range of #GDateTime. You should release the return value by calling g_date_time_unref() when you are done with it. #GTimeVal is not year-2038-safe. Use g_date_time_new_from_unix_utc() instead. a new #GDateTime, or %NULL a #GTimeVal Creates a #GDateTime corresponding to the given Unix time @t in the local time zone. Unix time is the number of seconds that have elapsed since 1970-01-01 00:00:00 UTC, regardless of the local time offset. This call can fail (returning %NULL) if @t represents a time outside of the supported range of #GDateTime. You should release the return value by calling g_date_time_unref() when you are done with it. a new #GDateTime, or %NULL the Unix time Creates a [struct@GLib.DateTime] corresponding to the given Unix time @t in the local time zone. Unix time is the number of microseconds that have elapsed since 1970-01-01 00:00:00 UTC, regardless of the local time offset. This call can fail (returning `NULL`) if @t represents a time outside of the supported range of #GDateTime. You should release the return value by calling [method@GLib.DateTime.unref] when you are done with it. a new [struct@GLib.DateTime], or `NULL` the Unix time in microseconds Creates a #GDateTime corresponding to the given Unix time @t in UTC. Unix time is the number of seconds that have elapsed since 1970-01-01 00:00:00 UTC. This call can fail (returning %NULL) if @t represents a time outside of the supported range of #GDateTime. You should release the return value by calling g_date_time_unref() when you are done with it. a new #GDateTime, or %NULL the Unix time Creates a [struct@GLib.DateTime] corresponding to the given Unix time @t in UTC. Unix time is the number of microseconds that have elapsed since 1970-01-01 00:00:00 UTC. This call can fail (returning `NULL`) if @t represents a time outside of the supported range of #GDateTime. You should release the return value by calling [method@GLib.DateTime.unref] when you are done with it. a new [struct@GLib.DateTime], or `NULL` the Unix time in microseconds Creates a new #GDateTime corresponding to the given date and time in the local time zone. This call is equivalent to calling g_date_time_new() with the time zone returned by g_time_zone_new_local(). a #GDateTime, or %NULL the year component of the date the month component of the date the day component of the date the hour component of the date the minute component of the date the number of seconds past the minute Creates a #GDateTime corresponding to this exact instant in the given time zone @tz. The time is as accurate as the system allows, to a maximum accuracy of 1 microsecond. This function will always succeed unless GLib is still being used after the year 9999. You should release the return value by calling g_date_time_unref() when you are done with it. a new #GDateTime, or %NULL a #GTimeZone Creates a #GDateTime corresponding to this exact instant in the local time zone. This is equivalent to calling g_date_time_new_now() with the time zone returned by g_time_zone_new_local(). a new #GDateTime, or %NULL Creates a #GDateTime corresponding to this exact instant in UTC. This is equivalent to calling g_date_time_new_now() with the time zone returned by g_time_zone_new_utc(). a new #GDateTime, or %NULL Creates a new #GDateTime corresponding to the given date and time in UTC. This call is equivalent to calling g_date_time_new() with the time zone returned by g_time_zone_new_utc(). a #GDateTime, or %NULL the year component of the date the month component of the date the day component of the date the hour component of the date the minute component of the date the number of seconds past the minute Creates a copy of @datetime and adds the specified timespan to the copy. the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime a #GTimeSpan Creates a copy of @datetime and adds the specified number of days to the copy. Add negative values to subtract days. the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime the number of days Creates a new #GDateTime adding the specified values to the current date and time in @datetime. Add negative values to subtract. the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime the number of years to add the number of months to add the number of days to add the number of hours to add the number of minutes to add the number of seconds to add Creates a copy of @datetime and adds the specified number of hours. Add negative values to subtract hours. the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime the number of hours to add Creates a copy of @datetime adding the specified number of minutes. Add negative values to subtract minutes. the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime the number of minutes to add Creates a copy of @datetime and adds the specified number of months to the copy. Add negative values to subtract months. The day of the month of the resulting #GDateTime is clamped to the number of days in the updated calendar month. For example, if adding 1 month to 31st January 2018, the result would be 28th February 2018. In 2020 (a leap year), the result would be 29th February. the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime the number of months Creates a copy of @datetime and adds the specified number of seconds. Add negative values to subtract seconds. the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime the number of seconds to add Creates a copy of @datetime and adds the specified number of weeks to the copy. Add negative values to subtract weeks. the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime the number of weeks Creates a copy of @datetime and adds the specified number of years to the copy. Add negative values to subtract years. As with g_date_time_add_months(), if the resulting date would be 29th February on a non-leap year, the day will be clamped to 28th February. the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime the number of years A comparison function for #GDateTimes that is suitable as a #GCompareFunc. Both #GDateTimes must be non-%NULL. -1, 0 or 1 if @dt1 is less than, equal to or greater than @dt2. first #GDateTime to compare second #GDateTime to compare Calculates the difference in time between @end and @begin. The #GTimeSpan that is returned is effectively @end - @begin (ie: positive if the first parameter is larger). the difference between the two #GDateTime, as a time span expressed in microseconds. a #GDateTime a #GDateTime Checks to see if @dt1 and @dt2 are equal. Equal here means that they represent the same moment after converting them to the same time zone. %TRUE if @dt1 and @dt2 are equal a #GDateTime a #GDateTime Creates a newly allocated string representing the requested @format. The format strings understood by this function are a subset of the `strftime()` format language as specified by C99. The `%D`, `%U` and `%W` conversions are not supported, nor is the `E` modifier. The GNU extensions `%k`, `%l`, `%s` and `%P` are supported, however, as are the `0`, `_` and `-` modifiers. The Python extension `%f` is also supported. In contrast to `strftime()`, this function always produces a UTF-8 string, regardless of the current locale. Note that the rendering of many formats is locale-dependent and may not match the `strftime()` output exactly. The following format specifiers are supported: - `%a`: the abbreviated weekday name according to the current locale - `%A`: the full weekday name according to the current locale - `%b`: the abbreviated month name according to the current locale - `%B`: the full month name according to the current locale - `%c`: the preferred date and time representation for the current locale - `%C`: the century number (year/100) as a 2-digit integer (00-99) - `%d`: the day of the month as a decimal number (range 01 to 31) - `%e`: the day of the month as a decimal number (range 1 to 31); single digits are preceded by a figure space (U+2007) - `%F`: equivalent to `%Y-%m-%d` (the ISO 8601 date format) - `%g`: the last two digits of the ISO 8601 week-based year as a decimal number (00-99). This works well with `%V` and `%u`. - `%G`: the ISO 8601 week-based year as a decimal number. This works well with `%V` and `%u`. - `%h`: equivalent to `%b` - `%H`: the hour as a decimal number using a 24-hour clock (range 00 to 23) - `%I`: the hour as a decimal number using a 12-hour clock (range 01 to 12) - `%j`: the day of the year as a decimal number (range 001 to 366) - `%k`: the hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a figure space (U+2007) - `%l`: the hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a figure space (U+2007) - `%m`: the month as a decimal number (range 01 to 12) - `%M`: the minute as a decimal number (range 00 to 59) - `%f`: the microsecond as a decimal number (range 000000 to 999999) - `%p`: either ‘AM’ or ‘PM’ according to the given time value, or the corresponding strings for the current locale. Noon is treated as ‘PM’ and midnight as ‘AM’. Use of this format specifier is discouraged, as many locales have no concept of AM/PM formatting. Use `%c` or `%X` instead. - `%P`: like `%p` but lowercase: ‘am’ or ‘pm’ or a corresponding string for the current locale. Use of this format specifier is discouraged, as many locales have no concept of AM/PM formatting. Use `%c` or `%X` instead. - `%r`: the time in a.m. or p.m. notation. Use of this format specifier is discouraged, as many locales have no concept of AM/PM formatting. Use `%c` or `%X` instead. - `%R`: the time in 24-hour notation (`%H:%M`) - `%s`: the number of seconds since the Epoch, that is, since 1970-01-01 00:00:00 UTC - `%S`: the second as a decimal number (range 00 to 60) - `%t`: a tab character - `%T`: the time in 24-hour notation with seconds (`%H:%M:%S`) - `%u`: the ISO 8601 standard day of the week as a decimal, range 1 to 7, Monday being 1. This works well with `%G` and `%V`. - `%V`: the ISO 8601 standard week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the new year. See g_date_time_get_week_of_year(). This works well with `%G` and `%u`. - `%w`: the day of the week as a decimal, range 0 to 6, Sunday being 0. This is not the ISO 8601 standard format — use `%u` instead. - `%x`: the preferred date representation for the current locale without the time - `%X`: the preferred time representation for the current locale without the date - `%y`: the year as a decimal number without the century - `%Y`: the year as a decimal number including the century - `%z`: the time zone as an offset from UTC (`+hhmm`) - `%:z`: the time zone as an offset from UTC (`+hh:mm`). This is a gnulib `strftime()` extension. Since: 2.38 - `%::z`: the time zone as an offset from UTC (`+hh:mm:ss`). This is a gnulib `strftime()` extension. Since: 2.38 - `%:::z`: the time zone as an offset from UTC, with `:` to necessary precision (e.g., `-04`, `+05:30`). This is a gnulib `strftime()` extension. Since: 2.38 - `%Z`: the time zone or name or abbreviation - `%%`: a literal `%` character Some conversion specifications can be modified by preceding the conversion specifier by one or more modifier characters. The following modifiers are supported for many of the numeric conversions: - `O`: Use alternative numeric symbols, if the current locale supports those. - `_`: Pad a numeric result with spaces. This overrides the default padding for the specifier. - `-`: Do not pad a numeric result. This overrides the default padding for the specifier. - `0`: Pad a numeric result with zeros. This overrides the default padding for the specifier. The following modifiers are supported for many of the alphabetic conversions: - `^`: Use upper case if possible. This is a gnulib `strftime()` extension. Since: 2.80 - `#`: Use opposite case if possible. This is a gnulib `strftime()` extension. Since: 2.80 Additionally, when `O` is used with `B`, `b`, or `h`, it produces the alternative form of a month name. The alternative form should be used when the month name is used without a day number (e.g., standalone). It is required in some languages (Baltic, Slavic, Greek, and more) due to their grammatical rules. For other languages there is no difference. `%OB` is a GNU and BSD `strftime()` extension expected to be added to the future POSIX specification, `%Ob` and `%Oh` are GNU `strftime()` extensions. Since: 2.56 Since GLib 2.80, when `E` is used with `%c`, `%C`, `%x`, `%X`, `%y` or `%Y`, the date is formatted using an alternate era representation specific to the locale. This is typically used for the Thai solar calendar or Japanese era names, for example. - `%Ec`: the preferred date and time representation for the current locale, using the alternate era representation - `%EC`: the name of the era - `%Ex`: the preferred date representation for the current locale without the time, using the alternate era representation - `%EX`: the preferred time representation for the current locale without the date, using the alternate era representation - `%Ey`: the year since the beginning of the era denoted by the `%EC` specifier - `%EY`: the full alternative year representation a newly allocated string formatted to the requested format or %NULL in the case that there was an error (such as a format specifier not being supported in the current locale). The string should be freed with g_free(). A #GDateTime a valid UTF-8 string, containing the format for the #GDateTime Format @datetime in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601), including the date, time and time zone, and return that as a UTF-8 encoded string. Since GLib 2.66, this will output to sub-second precision if needed. a newly allocated string formatted in ISO 8601 format or %NULL in the case that there was an error. The string should be freed with g_free(). A #GDateTime Retrieves the day of the month represented by @datetime in the gregorian calendar. the day of the month a #GDateTime Retrieves the ISO 8601 day of the week on which @datetime falls (1 is Monday, 2 is Tuesday... 7 is Sunday). the day of the week a #GDateTime Retrieves the day of the year represented by @datetime in the Gregorian calendar. the day of the year a #GDateTime Retrieves the hour of the day represented by @datetime the hour of the day a #GDateTime Retrieves the microsecond of the date represented by @datetime the microsecond of the second a #GDateTime Retrieves the minute of the hour represented by @datetime the minute of the hour a #GDateTime Retrieves the month of the year represented by @datetime in the Gregorian calendar. the month represented by @datetime a #GDateTime Retrieves the second of the minute represented by @datetime the second represented by @datetime a #GDateTime Retrieves the number of seconds since the start of the last minute, including the fractional part. the number of seconds a #GDateTime Get the time zone for this @datetime. the time zone a #GDateTime Determines the time zone abbreviation to be used at the time and in the time zone of @datetime. For example, in Toronto this is currently "EST" during the winter months and "EDT" during the summer months when daylight savings time is in effect. the time zone abbreviation. The returned string is owned by the #GDateTime and it should not be modified or freed a #GDateTime Determines the offset to UTC in effect at the time and in the time zone of @datetime. The offset is the number of microseconds that you add to UTC time to arrive at local time for the time zone (ie: negative numbers for time zones west of GMT, positive numbers for east). If @datetime represents UTC time, then the offset is always zero. the number of microseconds that should be added to UTC to get the local time a #GDateTime Returns the ISO 8601 week-numbering year in which the week containing @datetime falls. This function, taken together with g_date_time_get_week_of_year() and g_date_time_get_day_of_week() can be used to determine the full ISO week date on which @datetime falls. This is usually equal to the normal Gregorian year (as returned by g_date_time_get_year()), except as detailed below: For Thursday, the week-numbering year is always equal to the usual calendar year. For other days, the number is such that every day within a complete week (Monday to Sunday) is contained within the same week-numbering year. For Monday, Tuesday and Wednesday occurring near the end of the year, this may mean that the week-numbering year is one greater than the calendar year (so that these days have the same week-numbering year as the Thursday occurring early in the next year). For Friday, Saturday and Sunday occurring near the start of the year, this may mean that the week-numbering year is one less than the calendar year (so that these days have the same week-numbering year as the Thursday occurring late in the previous year). An equivalent description is that the week-numbering year is equal to the calendar year containing the majority of the days in the current week (Monday to Sunday). Note that January 1 0001 in the proleptic Gregorian calendar is a Monday, so this function never returns 0. the ISO 8601 week-numbering year for @datetime a #GDateTime Returns the ISO 8601 week number for the week containing @datetime. The ISO 8601 week number is the same for every day of the week (from Moday through Sunday). That can produce some unusual results (described below). The first week of the year is week 1. This is the week that contains the first Thursday of the year. Equivalently, this is the first week that has more than 4 of its days falling within the calendar year. The value 0 is never returned by this function. Days contained within a year but occurring before the first ISO 8601 week of that year are considered as being contained in the last week of the previous year. Similarly, the final days of a calendar year may be considered as being part of the first ISO 8601 week of the next year if 4 or more days of that week are contained within the new year. the ISO 8601 week number for @datetime. a #GDateTime Retrieves the year represented by @datetime in the Gregorian calendar. the year represented by @datetime A #GDateTime Retrieves the Gregorian day, month, and year of a given #GDateTime. a #GDateTime. the return location for the gregorian year, or %NULL. the return location for the month of the year, or %NULL. the return location for the day of the month, or %NULL. Hashes @datetime into a #guint, suitable for use within #GHashTable. a #guint containing the hash a #GDateTime Determines if daylight savings time is in effect at the time and in the time zone of @datetime. %TRUE if daylight savings time is in effect a #GDateTime Atomically increments the reference count of @datetime by one. the #GDateTime with the reference count increased a #GDateTime Creates a new #GDateTime corresponding to the same instant in time as @datetime, but in the local time zone. This call is equivalent to calling g_date_time_to_timezone() with the time zone returned by g_time_zone_new_local(). the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime Stores the instant in time that @datetime represents into @tv. The time contained in a #GTimeVal is always stored in the form of seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time zone associated with @datetime. On systems where 'long' is 32bit (ie: all 32bit systems and all Windows systems), a #GTimeVal is incapable of storing the entire range of values that #GDateTime is capable of expressing. On those systems, this function returns %FALSE to indicate that the time is out of range. On systems where 'long' is 64bit, this function never fails. #GTimeVal is not year-2038-safe. Use g_date_time_to_unix() instead. %TRUE if successful, else %FALSE a #GDateTime a #GTimeVal to modify Create a new #GDateTime corresponding to the same instant in time as @datetime, but in the time zone @tz. This call can fail in the case that the time goes out of bounds. For example, converting 0001-01-01 00:00:00 UTC to a time zone west of Greenwich will fail (due to the year 0 being out of range). the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime the new #GTimeZone Gives the Unix time corresponding to @datetime, rounding down to the nearest second. Unix time is the number of seconds that have elapsed since 1970-01-01 00:00:00 UTC, regardless of the time zone associated with @datetime. the Unix time corresponding to @datetime a #GDateTime Gives the Unix time corresponding to @datetime, in microseconds. Unix time is the number of microseconds that have elapsed since 1970-01-01 00:00:00 UTC, regardless of the time zone associated with @datetime. the Unix time corresponding to @datetime a #GDateTime Creates a new #GDateTime corresponding to the same instant in time as @datetime, but in UTC. This call is equivalent to calling g_date_time_to_timezone() with the time zone returned by g_time_zone_new_utc(). the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime Atomically decrements the reference count of @datetime by one. When the reference count reaches zero, the resources allocated by @datetime are freed a #GDateTime Enumeration representing a day of the week; %G_DATE_MONDAY, %G_DATE_TUESDAY, etc. %G_DATE_BAD_WEEKDAY is an invalid weekday. invalid value Monday Tuesday Wednesday Thursday Friday Saturday Sunday Associates a string with a bit flag. Used in g_parse_debug_string(). the string the flag Specifies the type of function which is called when a data element is destroyed. It is passed the pointer to the data element and should free any memory and resources allocated for it. the data element. An opaque structure representing an opened directory. Opens a directory for reading. The names of the files in the directory can then be retrieved using g_dir_read_name(). Note that the ordering is not defined. a newly allocated #GDir on success, %NULL on failure. If non-%NULL, you must free the result with g_dir_close() when you are finished with it. the path to the directory you are interested in. On Unix in the on-disk encoding. On Windows in UTF-8 Currently must be set to 0. Reserved for future use. Closes the directory immediately and decrements the reference count. Once the reference count reaches zero, the `GDir` structure itself will be freed. Prior to GLib 2.80, `GDir` was not reference counted. It is an error to call any of the `GDir` methods other than [method@GLib.Dir.ref] and [method@GLib.Dir.unref] on a `GDir` after calling [method@GLib.Dir.close] on it. a #GDir* created by g_dir_open() Retrieves the name of another entry in the directory, or %NULL. The order of entries returned from this function is not defined, and may vary by file system or other operating-system dependent factors. %NULL may also be returned in case of errors. On Unix, you can check `errno` to find out if %NULL was returned because of an error. On Unix, the '.' and '..' entries are omitted, and the returned name is in the on-disk encoding. On Windows, as is true of all GLib functions which operate on filenames, the returned name is in UTF-8. The entry's name or %NULL if there are no more entries. The return value is owned by GLib and must not be modified or freed. a #GDir* created by g_dir_open() Increment the reference count of `dir`. the same pointer as `dir` a `GDir` Resets the given directory. The next call to g_dir_read_name() will return the first entry again. a #GDir* created by g_dir_open() Decrements the reference count of `dir`. Once the reference count reaches zero, the directory will be closed and all resources associated with it will be freed. If [method@GLib.Dir.close] is called when the reference count is greater than zero, the directory is closed but the `GDir` structure will not be freed until its reference count reaches zero. It is an error to call any of the `GDir` methods other than [method@GLib.Dir.ref] and [method@GLib.Dir.unref] on a `GDir` after calling [method@GLib.Dir.close] on it. a `GDir` Creates a subdirectory in the preferred directory for temporary files (as returned by g_get_tmp_dir()). @tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, as the parameter to g_mkstemp(). However, unlike these functions, the template should only be a basename, no directory components are allowed. If template is %NULL, a default template is used. Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not modified, and might thus be a read-only literal string. The actual name used. This string should be freed with g_free() when not needed any longer and is is in the GLib file name encoding. In case of errors, %NULL is returned and @error will be set. Template for directory name, as in g_mkdtemp(), basename only, or %NULL for a default template The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, mantissa and exponent of IEEE floats and doubles. These unions are defined as appropriate for a given platform. IEEE floats and doubles are supported (used for storage) by at least Intel, PPC and Sparc. the double value The type of functions that are used to 'duplicate' an object. What this means depends on the context, it could just be incrementing the reference count, if @data is a ref-counted object. a duplicate of data the data to duplicate user data that was specified in g_datalist_id_dup_data() The base of natural logarithms. Specifies the type of a function used to test two values for equality. The function should return %TRUE if both values are equal and %FALSE otherwise. %TRUE if @a = @b; %FALSE otherwise a value a value to compare with Specifies the type of a function used to test two values for equality. The function should return %TRUE if both values are equal and %FALSE otherwise. This is a version of #GEqualFunc which provides a @user_data closure from the caller. %TRUE if @a = @b; %FALSE otherwise a value a value to compare with user data provided by the caller The `GError` structure contains information about an error that has occurred. error domain, e.g. %G_FILE_ERROR error code, e.g. %G_FILE_ERROR_NOENT human-readable informative error message Creates a new #GError with the given @domain and @code, and a message formatted with @format. a new #GError error domain error code printf()-style format for error message parameters for message format Creates a new #GError; unlike g_error_new(), @message is not a printf()-style format string. Use this function if @message contains text you don't have control over, that could include printf() escape sequences. a new #GError error domain error code error message Creates a new #GError with the given @domain and @code, and a message formatted with @format. a new #GError error domain error code printf()-style format for error message #va_list of parameters for the message format Makes a copy of @error. a new #GError a #GError Frees a #GError and associated resources. a #GError Returns %TRUE if @error matches @domain and @code, %FALSE otherwise. In particular, when @error is %NULL, %FALSE will be returned. If @domain contains a `FAILED` (or otherwise generic) error code, you should generally not check for it explicitly, but should instead treat any not-explicitly-recognized error code as being equivalent to the `FAILED` code. This way, if the domain is extended in the future to provide a more specific error code for a certain case, your code will still work. whether @error has @domain and @code a #GError an error domain an error code This function registers an extended #GError domain. @error_type_name will be duplicated. Otherwise does the same as g_error_domain_register_static(). #GQuark representing the error domain string to create a #GQuark from size of the private error data in bytes function initializing fields of the private error data function copying fields of the private error data function freeing fields of the private error data This function registers an extended #GError domain. @error_type_name should not be freed. @error_type_private_size must be greater than 0. @error_type_init receives an initialized #GError and should then initialize the private data. @error_type_copy is a function that receives both original and a copy #GError and should copy the fields of the private error data. The standard #GError fields are already handled. @error_type_clear receives the pointer to the error, and it should free the fields of the private error data. It should not free the struct itself though. Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of passing valid information to this function. #GQuark representing the error domain static string to create a #GQuark from size of the private error data in bytes function initializing fields of the private error data function copying fields of the private error data function freeing fields of the private error data Specifies the type of function which is called when an extended error instance is freed. It is passed the error pointer about to be freed, and should free the error's private data fields. Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from @error. extended error to clear Specifies the type of function which is called when an extended error instance is copied. It is passed the pointer to the destination error and source error, and should copy only the fields of the private data from @src_error to @dest_error. Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from @src_error and @dest_error. source extended error destination extended error Specifies the type of function which is called just after an extended error instance is created and its fields filled. It should only initialize the fields in the private data, which can be received with the generated `*_get_private()` function. Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from @error. extended error The possible errors, used in the @v_error field of #GTokenValue, when the token is a %G_TOKEN_ERROR. unknown error unexpected end of file unterminated string constant unterminated comment non-digit character in a number digit beyond radix in a number non-decimal floating point number malformed floating point number Values corresponding to @errno codes returned from file operations on UNIX. Unlike @errno codes, GFileError values are available on all systems, even Windows. The exact meaning of each code depends on what sort of file operation you were performing; the UNIX documentation gives more details. The following error code descriptions come from the GNU C Library manual, and are under the copyright of that manual. It's not very portable to make detailed assumptions about exactly which errors will be returned from a given operation. Some errors don't occur on some systems, etc., sometimes there are subtle differences in when a system will report a given error, etc. Operation not permitted; only the owner of the file (or other resource) or processes with special privileges can perform the operation. File is a directory; you cannot open a directory for writing, or create or remove hard links to it. Permission denied; the file permissions do not allow the attempted operation. Filename too long. No such file or directory. This is a "file doesn't exist" error for ordinary files that are referenced in contexts where they are expected to already exist. A file that isn't a directory was specified when a directory is required. No such device or address. The system tried to use the device represented by a file you specified, and it couldn't find the device. This can mean that the device file was installed incorrectly, or that the physical device is missing or not correctly attached to the computer. The underlying file system of the specified file does not support memory mapping. The directory containing the new link can't be modified because it's on a read-only file system. Text file busy. You passed in a pointer to bad memory. (GLib won't reliably return this, don't pass in pointers to bad memory.) Too many levels of symbolic links were encountered in looking up a file name. This often indicates a cycle of symbolic links. No space left on device; write operation on a file failed because the disk is full. No memory available. The system cannot allocate more virtual memory because its capacity is full. The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. There are too many distinct file openings in the entire system. Bad file descriptor; for example, I/O on a descriptor that has been closed or reading from a descriptor open only for writing (or vice versa). Invalid argument. This is used to indicate various kinds of problems with passing the wrong argument to a library function. Broken pipe; there is no process reading from the other end of a pipe. Every library function that returns this error code also generates a 'SIGPIPE' signal; this signal terminates the program if not handled or blocked. Thus, your program will never actually see this code unless it has handled or blocked 'SIGPIPE'. Resource temporarily unavailable; the call might work if you try again later. Interrupted function call; an asynchronous signal occurred and prevented completion of the call. When this happens, you should try the call again. Input/output error; usually used for physical read or write errors. i.e. the disk or other physical device hardware is returning errors. Operation not permitted; only the owner of the file (or other resource) or processes with special privileges can perform the operation. Function not implemented; this indicates that the system is missing some functionality. Does not correspond to a UNIX error code; this is the standard "failed for unspecified reason" error code present in all #GError error code enumerations. Returned if no specific code applies. Flags to pass to g_file_set_contents_full() to affect its safety and performance. No guarantees about file consistency or durability. The most dangerous setting, which is slightly faster than other settings. Guarantee file consistency: after a crash, either the old version of the file or the new version of the file will be available, but not a mixture. On Unix systems this equates to an `fsync()` on the file and use of an atomic `rename()` of the new version of the file over the old. Guarantee file durability: after a crash, the new version of the file will be available. On Unix systems this equates to an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the directory containing the file after calling `rename()`. Only apply consistency and durability guarantees if the file already exists. This may speed up file operations if the file doesn’t currently exist, but may result in a corrupted version of the new file if the system crashes while writing it. A test to perform on a file using g_file_test(). %TRUE if the file is a regular file (not a directory). Note that this test will also return %TRUE if the tested file is a symlink to a regular file. %TRUE if the file is a symlink. %TRUE if the file is a directory. %TRUE if the file is executable. %TRUE if the file exists. It may or may not be a regular file. The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, mantissa and exponent of IEEE floats and doubles. These unions are defined as appropriate for a given platform. IEEE floats and doubles are supported (used for storage) by at least Intel, PPC and Sparc. the double value Flags to modify the format of the string returned by g_format_size_full(). behave the same as g_format_size() include the exact number of bytes as part of the returned string. For example, "45.6 kB (45,612 bytes)". use IEC (base 1024) units with "KiB"-style suffixes. IEC units should only be used for reporting things with a strong "power of 2" basis, like RAM sizes or RAID stripe sizes. Network and storage sizes should be reported in the normal SI units. set the size as a quantity in bits, rather than bytes, and return units in bits. For example, ‘Mbit’ rather than ‘MB’. return only value, without unit; this should not be used together with @G_FORMAT_SIZE_LONG_FORMAT nor @G_FORMAT_SIZE_ONLY_UNIT. Since: 2.74 return only unit, without value; this should not be used together with @G_FORMAT_SIZE_LONG_FORMAT nor @G_FORMAT_SIZE_ONLY_VALUE. Since: 2.74 Declares a type of function which takes an arbitrary data pointer argument and has no return value. It is not currently used in GLib or GTK. a data pointer Specifies the type of functions passed to g_list_foreach() and g_slist_foreach(). the element's data user data passed to g_list_foreach() or g_slist_foreach() Expands to the GNU C `alloc_size` function attribute if the compiler is a new enough gcc. This attribute tells the compiler that the function returns a pointer to memory of a size that is specified by the @xth function parameter. Place the attribute after the function declaration, just before the semicolon. |[<!-- language="C" --> gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1); ]| See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details. the index of the argument specifying the allocation size Expands to the GNU C `alloc_size` function attribute if the compiler is a new enough gcc. This attribute tells the compiler that the function returns a pointer to memory of a size that is specified by the product of two function parameters. Place the attribute after the function declaration, just before the semicolon. |[<!-- language="C" --> gpointer g_malloc_n (gsize n_blocks, gsize n_block_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE2(1, 2); ]| See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details. the index of the argument specifying one factor of the allocation size the index of the argument specifying the second factor of the allocation size Expands to a check for a compiler with __GNUC__ defined and a version greater than or equal to the major and minor numbers provided. For example, the following would only match on compilers such as GCC 4.8 or newer. |[<!-- language="C" --> #if G_GNUC_CHECK_VERSION(4, 8) #endif ]| major version to check against minor version to check against Like %G_GNUC_DEPRECATED, but names the intended replacement for the deprecated symbol if the version of gcc in use is new enough to support custom deprecation messages. Place the attribute after the declaration, just before the semicolon. |[<!-- language="C" --> int my_mistake (void) G_GNUC_DEPRECATED_FOR(my_replacement); ]| See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details. Note that if @f is a macro, it will be expanded in the warning message. You can enclose it in quotes to prevent this. (The quotes will show up in the warning, but it's better than showing the macro expansion.) the intended replacement for the deprecated symbol, such as the name of a function Expands to the GNU C `format_arg` function attribute if the compiler is gcc. This function attribute specifies that a function takes a format string for a `printf()`, `scanf()`, `strftime()` or `strfmon()` style function and modifies it, so that the result can be passed to a `printf()`, `scanf()`, `strftime()` or `strfmon()` style function (with the remaining arguments to the format function the same as they would have been for the unmodified string). Place the attribute after the function declaration, just before the semicolon. See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-nonliteral-1) for more details. |[<!-- language="C" --> gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); ]| the index of the argument Expands to "" on all modern compilers, and to __FUNCTION__ on gcc version 2.x. Don't use it. Use G_STRFUNC() instead Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__ on gcc version 2.x. Don't use it. Use G_STRFUNC() instead Expands to the GNU C `format` function attribute if the compiler is gcc. This is used for declaring functions which take a variable number of arguments, with the same syntax as `printf()`. It allows the compiler to type-check the arguments passed to the function. Place the attribute after the function declaration, just before the semicolon. See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) for more details. |[<!-- language="C" --> gint g_snprintf (gchar *string, gulong n, gchar const *format, ...) G_GNUC_PRINTF (3, 4); ]| the index of the argument corresponding to the format string (the arguments are numbered from 1) the index of the first of the format arguments, or 0 if there are no format arguments Expands to the GNU C `format` function attribute if the compiler is gcc. This is used for declaring functions which take a variable number of arguments, with the same syntax as `scanf()`. It allows the compiler to type-check the arguments passed to the function. |[<!-- language="C" --> int my_scanf (MyStream *stream, const char *format, ...) G_GNUC_SCANF (2, 3); int my_vscanf (MyStream *stream, const char *format, va_list ap) G_GNUC_SCANF (2, 0); ]| See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) for details. the index of the argument corresponding to the format string (the arguments are numbered from 1) the index of the first of the format arguments, or 0 if there are no format arguments Expands to the GNU C `strftime` format function attribute if the compiler is gcc. This is used for declaring functions which take a format argument which is passed to `strftime()` or an API implementing its formats. It allows the compiler check the format passed to the function. |[<!-- language="C" --> gsize my_strftime (MyBuffer *buffer, const char *format, const struct tm *tm) G_GNUC_STRFTIME (2); ]| See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) for details. the index of the argument corresponding to the format string (the arguments are numbered from 1) Defined to 1 if gcc-style visibility handling is supported. Specifies the type of the function passed to g_hash_table_foreach(). It is called with each key/value pair, together with the @user_data parameter which is passed to g_hash_table_foreach(). a key the value corresponding to the key user data passed to g_hash_table_foreach() Casts a pointer to a `GHook*`. a pointer Returns %TRUE if the #GHook is active, which is normally the case until the #GHook is destroyed. a #GHook Gets the flags of a hook. a #GHook The position of the first bit which is not reserved for internal use be the #GHook implementation, i.e. `1 << G_HOOK_FLAG_USER_SHIFT` is the first bit which can be used for application-defined flags. Returns %TRUE if the #GHook function is currently executing. a #GHook Returns %TRUE if the #GHook is not in a #GHookList. a #GHook Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active and it has not been destroyed. a #GHook Specifies the type of the function passed to [func@GLib.HashTable.find], [func@GLib.HashTable.foreach_remove], and [func@GLib.HashTable.foreach_steal]. The function is called with each key/value pair, together with the @user_data parameter passed to the calling function. The function should return true if the key/value pair should be selected, meaning it has been found or it should be removed from the [struct@GLib.HashTable], depending on the calling function. true if the key/value pair should be selected, and false otherwise a key the value associated with the key user data passed to the calling function Specifies the type of the hash function which is passed to g_hash_table_new() when a #GHashTable is created. The function is passed a key and should return a #guint hash value. The functions g_direct_hash(), g_int_hash() and g_str_hash() provide hash functions which can be used when the key is a #gpointer, #gint*, and #gchar* respectively. g_direct_hash() is also the appropriate hash function for keys of the form `GINT_TO_POINTER (n)` (or similar macros). A good hash functions should produce hash values that are evenly distributed over a fairly large range. The modulus is taken with the hash table size (a prime number) to find the 'bucket' to place each key into. The function should also be very fast, since it is called for each key lookup. Note that the hash functions provided by GLib have these qualities, but are not particularly robust against manufactured keys that cause hash collisions. Therefore, you should consider choosing a more secure hash function when using a GHashTable with keys that originate in untrusted data (such as HTTP requests). Using g_str_hash() in that situation might make your application vulnerable to [Algorithmic Complexity Attacks](https://lwn.net/Articles/474912/). The key to choosing a good hash is unpredictability. Even cryptographic hashes are very easy to find collisions for when the remainder is taken modulo a somewhat predictable prime number. There must be an element of randomness that an attacker is unable to guess. the hash value corresponding to the key a key The #GHashTable struct is an opaque data structure to represent a [Hash Table](data-structures.html#hash-tables). It should only be accessed via the following functions. This is a convenience function for using a #GHashTable as a set. It is equivalent to calling g_hash_table_replace() with @key as both the key and the value. In particular, this means that if @key already exists in the hash table, then the old copy of @key in the hash table is freed and @key replaces it in the table. When a hash table only ever contains keys that have themselves as the corresponding value it is able to be stored more efficiently. See the discussion in the section description. Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not. %TRUE if the key did not exist yet a #GHashTable a key to insert Checks if @key is in @hash_table. %TRUE if @key is in @hash_table, %FALSE otherwise. a #GHashTable a key to check Destroys all keys and values in the #GHashTable and decrements its reference count by 1. If keys and/or values are dynamically allocated, you should either free them first or create the #GHashTable with destroy notifiers using g_hash_table_new_full(). In the latter case the destroy functions you supplied will be called on all keys and values during the destruction phase. a #GHashTable Calls the given function for key/value pairs in the #GHashTable until @predicate returns %TRUE. The function is passed the key and value of each pair, and the given @user_data parameter. The hash table may not be modified while iterating over it (you can't add/remove items). Note, that hash tables are really only optimized for forward lookups, i.e. g_hash_table_lookup(). So code that frequently issues g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of once per every entry in a hash table) should probably be reworked to use additional or different data structures for reverse lookups (keep in mind that an O(n) find/foreach operation issued for all n values in a hash table ends up needing O(n*n) operations). The value of the first key/value pair is returned, for which @predicate evaluates to %TRUE. If no pair with the requested property is found, %NULL is returned. a #GHashTable function to test the key/value pairs for a certain property user data to pass to the function Calls the given function for each of the key/value pairs in the #GHashTable. The function is passed the key and value of each pair, and the given @user_data parameter. The hash table may not be modified while iterating over it (you can't add/remove items). To remove all items matching a predicate, use g_hash_table_foreach_remove(). The order in which g_hash_table_foreach() iterates over the keys/values in the hash table is not defined. See g_hash_table_find() for performance caveats for linear order searches in contrast to g_hash_table_lookup(). a #GHashTable the function to call for each key/value pair user data to pass to the function Calls the given function for each key/value pair in the #GHashTable. If the function returns %TRUE, then the key/value pair is removed from the #GHashTable. If you supplied key or value destroy functions when creating the #GHashTable, they are used to free the memory allocated for the removed keys and values. See #GHashTableIter for an alternative way to loop over the key/value pairs in the hash table. the number of key/value pairs removed a #GHashTable the function to call for each key/value pair user data to pass to the function Calls the given function for each key/value pair in the #GHashTable. If the function returns %TRUE, then the key/value pair is removed from the #GHashTable, but no key or value destroy functions are called. See #GHashTableIter for an alternative way to loop over the key/value pairs in the hash table. the number of key/value pairs removed. a #GHashTable the function to call for each key/value pair user data to pass to the function Retrieves every key inside @hash_table. The returned data is valid until changes to the hash release those keys. This iterates over every entry in the hash table to build its return value. To iterate over the entries in a #GHashTable more efficiently, use a #GHashTableIter. a #GList containing all the keys inside the hash table. The content of the list is owned by the hash table and should not be modified or freed. Use g_list_free() when done using the list. a #GHashTable Retrieves every key inside @hash_table, as an array. The returned array is %NULL-terminated but may contain %NULL as a key. Use @length to determine the true length if it's possible that %NULL was used as the value for a key. Note: in the common case of a string-keyed #GHashTable, the return value of this function can be conveniently cast to (const gchar **). This iterates over every entry in the hash table to build its return value. To iterate over the entries in a #GHashTable more efficiently, use a #GHashTableIter. You should always free the return result with g_free(). In the above-mentioned case of a string-keyed hash table, it may be appropriate to use g_strfreev() if you call g_hash_table_steal_all() first to transfer ownership of the keys. a %NULL-terminated array containing each key from the table. a #GHashTable the length of the returned array Retrieves every key inside @hash_table, as a #GPtrArray. The returned data is valid until changes to the hash release those keys. This iterates over every entry in the hash table to build its return value. To iterate over the entries in a #GHashTable more efficiently, use a #GHashTableIter. You should always unref the returned array with g_ptr_array_unref(). a #GPtrArray containing each key from the table. Unref with g_ptr_array_unref() when done. a #GHashTable Retrieves every value inside @hash_table. The returned data is valid until @hash_table is modified. This iterates over every entry in the hash table to build its return value. To iterate over the entries in a #GHashTable more efficiently, use a #GHashTableIter. a #GList containing all the values inside the hash table. The content of the list is owned by the hash table and should not be modified or freed. Use g_list_free() when done using the list. a #GHashTable Retrieves every value inside @hash_table, as a #GPtrArray. The returned data is valid until changes to the hash release those values. This iterates over every entry in the hash table to build its return value. To iterate over the entries in a #GHashTable more efficiently, use a #GHashTableIter. You should always unref the returned array with g_ptr_array_unref(). a #GPtrArray containing each value from the table. Unref with g_ptr_array_unref() when done. a #GHashTable Inserts a new key and value into a #GHashTable. If the key already exists in the #GHashTable its current value is replaced with the new value. If you supplied a @value_destroy_func when creating the #GHashTable, the old value is freed using that function. If you supplied a @key_destroy_func when creating the #GHashTable, the passed key is freed using that function. Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not. %TRUE if the key did not exist yet a #GHashTable a key to insert the value to associate with the key Looks up a key in a #GHashTable. Note that this function cannot distinguish between a key that is not present and one which is present and has the value %NULL. If you need this distinction, use g_hash_table_lookup_extended(). the associated value, or %NULL if the key is not found a #GHashTable the key to look up Looks up a key in the #GHashTable, returning the original key and the associated value and a #gboolean which is %TRUE if the key was found. This is useful if you need to free the memory allocated for the original key, for example before calling g_hash_table_remove(). You can actually pass %NULL for @lookup_key to test whether the %NULL key exists, provided the hash and equal functions of @hash_table are %NULL-safe. %TRUE if the key was found in the #GHashTable a #GHashTable the key to look up return location for the original key return location for the value associated with the key Creates a new #GHashTable with a reference count of 1. Hash values returned by @hash_func are used to determine where keys are stored within the #GHashTable data structure. The g_direct_hash(), g_int_hash(), g_int64_hash(), g_double_hash() and g_str_hash() functions are provided for some common types of keys. If @hash_func is %NULL, g_direct_hash() is used. @key_equal_func is used when looking up keys in the #GHashTable. The g_direct_equal(), g_int_equal(), g_int64_equal(), g_double_equal() and g_str_equal() functions are provided for the most common types of keys. If @key_equal_func is %NULL, keys are compared directly in a similar fashion to g_direct_equal(), but without the overhead of a function call. @key_equal_func is called with the key from the hash table as its first parameter, and the user-provided key to check against as its second. a new #GHashTable a function to create a hash value from a key a function to check two keys for equality Creates a new #GHashTable like g_hash_table_new() with a reference count of 1 and allows to specify functions to free the memory allocated for the key and value that get called when removing the entry from the #GHashTable. Since version 2.42 it is permissible for destroy notify functions to recursively remove further items from the hash table. This is only permissible if the application still holds a reference to the hash table. This means that you may need to ensure that the hash table is empty by calling g_hash_table_remove_all() before releasing the last reference using g_hash_table_unref(). a new #GHashTable a function to create a hash value from a key a function to check two keys for equality a function to free the memory allocated for the key used when removing the entry from the #GHashTable, or %NULL if you don't want to supply such a function. a function to free the memory allocated for the value used when removing the entry from the #GHashTable, or %NULL if you don't want to supply such a function. Creates a new #GHashTable like g_hash_table_new_full() with a reference count of 1. It inherits the hash function, the key equal function, the key destroy function, as well as the value destroy function, from @other_hash_table. The returned hash table will be empty; it will not contain the keys or values from @other_hash_table. a new #GHashTable Another #GHashTable Atomically increments the reference count of @hash_table by one. This function is MT-safe and may be called from any thread. the passed in #GHashTable a valid #GHashTable Removes a key and its associated value from a #GHashTable. If the #GHashTable was created using g_hash_table_new_full(), the key and value are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself. %TRUE if the key was found and removed from the #GHashTable a #GHashTable the key to remove Removes all keys and their associated values from a #GHashTable. If the #GHashTable was created using g_hash_table_new_full(), the keys and values are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself. a #GHashTable Inserts a new key and value into a #GHashTable similar to g_hash_table_insert(). The difference is that if the key already exists in the #GHashTable, it gets replaced by the new key. If you supplied a @value_destroy_func when creating the #GHashTable, the old value is freed using that function. If you supplied a @key_destroy_func when creating the #GHashTable, the old key is freed using that function. Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not. %TRUE if the key did not exist yet a #GHashTable a key to insert the value to associate with the key Returns the number of elements contained in the #GHashTable. the number of key/value pairs in the #GHashTable. a #GHashTable Removes a key and its associated value from a #GHashTable without calling the key and value destroy functions. %TRUE if the key was found and removed from the #GHashTable a #GHashTable the key to remove Removes all keys and their associated values from a #GHashTable without calling the key and value destroy functions. a #GHashTable Removes all keys and their associated values from a #GHashTable without calling the key destroy functions, returning the keys as a #GPtrArray with the free func set to the @hash_table key destroy function. a #GPtrArray containing each key of the table. Unref with g_ptr_array_unref() when done. a #GHashTable Removes all keys and their associated values from a #GHashTable without calling the value destroy functions, returning the values as a #GPtrArray with the free func set to the @hash_table value destroy function. a #GPtrArray containing each value of the table. Unref with g_ptr_array_unref() when done. a #GHashTable Looks up a key in the #GHashTable, stealing the original key and the associated value and returning %TRUE if the key was found. If the key was not found, %FALSE is returned. If found, the stolen key and value are removed from the hash table without calling the key and value destroy functions, and ownership is transferred to the caller of this method, as with g_hash_table_steal(). That is the case regardless whether @stolen_key or @stolen_value output parameters are requested. You can pass %NULL for @lookup_key, provided the hash and equal functions of @hash_table are %NULL-safe. The dictionary implementation optimizes for having all values identical to their keys, for example by using g_hash_table_add(). Before 2.82, when stealing both the key and the value from such a dictionary, the value was %NULL. Since 2.82, the returned value and key will be the same. %TRUE if the key was found in the #GHashTable a #GHashTable the key to look up return location for the original key return location for the value associated with the key Atomically decrements the reference count of @hash_table by one. If the reference count drops to 0, all keys and values will be destroyed, and all memory allocated by the hash table is released. This function is MT-safe and may be called from any thread. a valid #GHashTable A GHashTableIter structure represents an iterator that can be used to iterate over the elements of a #GHashTable. GHashTableIter structures are typically allocated on the stack and then initialized with g_hash_table_iter_init(). The iteration order of a #GHashTableIter over the keys/values in a hash table is not defined. Returns the #GHashTable associated with @iter. the #GHashTable associated with @iter. an initialized #GHashTableIter Initializes a key/value pair iterator and associates it with @hash_table. Modifying the hash table after calling this function invalidates the returned iterator. The iteration order of a #GHashTableIter over the keys/values in a hash table is not defined. |[<!-- language="C" --> GHashTableIter iter; gpointer key, value; g_hash_table_iter_init (&iter, hash_table); while (g_hash_table_iter_next (&iter, &key, &value)) { // do something with key and value } ]| an uninitialized #GHashTableIter a #GHashTable Advances @iter and retrieves the key and/or value that are now pointed to as a result of this advancement. If %FALSE is returned, @key and @value are not set, and the iterator becomes invalid. %FALSE if the end of the #GHashTable has been reached. an initialized #GHashTableIter a location to store the key a location to store the value Removes the key/value pair currently pointed to by the iterator from its associated #GHashTable. Can only be called after g_hash_table_iter_next() returned %TRUE, and cannot be called more than once for the same key/value pair. If the #GHashTable was created using g_hash_table_new_full(), the key and value are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself. It is safe to continue iterating the #GHashTable afterward: |[<!-- language="C" --> while (g_hash_table_iter_next (&iter, &key, &value)) { if (condition) g_hash_table_iter_remove (&iter); } ]| an initialized #GHashTableIter Replaces the value currently pointed to by the iterator from its associated #GHashTable. Can only be called after g_hash_table_iter_next() returned %TRUE. If you supplied a @value_destroy_func when creating the #GHashTable, the old value is freed using that function. an initialized #GHashTableIter the value to replace with Removes the key/value pair currently pointed to by the iterator from its associated #GHashTable, without calling the key and value destroy functions. Can only be called after g_hash_table_iter_next() returned %TRUE, and cannot be called more than once for the same key/value pair. an initialized #GHashTableIter HMACs should be used when producing a cookie or hash based on data and a key. Simple mechanisms for using SHA1 and other algorithms to digest a key and data together are vulnerable to various security issues. [HMAC](http://en.wikipedia.org/wiki/HMAC) uses algorithms like SHA1 in a secure way to produce a digest of a key and data. Both the key and data are arbitrary byte arrays of bytes or characters. Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512 in GLib 2.42. Support for SHA-384 was added in GLib 2.52. To create a new `GHmac`, use [ctor@GLib.Hmac.new]. To free a `GHmac`, use [method@GLib.Hmac.unref]. Creates a new #GHmac, using the digest algorithm @digest_type. If the @digest_type is not known, %NULL is returned. A #GHmac can be used to compute the HMAC of a key and an arbitrary binary blob, using different hashing algorithms. A #GHmac works by feeding a binary blob through g_hmac_update() until the data is complete; the digest can then be extracted using g_hmac_get_string(), which will return the checksum as a hexadecimal string; or g_hmac_get_digest(), which will return a array of raw bytes. Once either g_hmac_get_string() or g_hmac_get_digest() have been called on a #GHmac, the HMAC will be closed and it won't be possible to call g_hmac_update() on it anymore. Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42. Support for %G_CHECKSUM_SHA384 was added in GLib 2.52. the newly created #GHmac, or %NULL. Use g_hmac_unref() to free the memory allocated by it. the desired type of digest the key for the HMAC the length of the keys Copies a #GHmac. If @hmac has been closed, by calling g_hmac_get_string() or g_hmac_get_digest(), the copied HMAC will be closed as well. the copy of the passed #GHmac. Use g_hmac_unref() when finished using it. the #GHmac to copy Gets the digest from @checksum as a raw binary array and places it into @buffer. The size of the digest depends on the type of checksum. Once this function has been called, the #GHmac is closed and can no longer be updated with g_checksum_update(). a #GHmac output buffer an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest Gets the HMAC as a hexadecimal string. Once this function has been called the #GHmac can no longer be updated with g_hmac_update(). The hexadecimal characters will be lower case. the hexadecimal representation of the HMAC. The returned string is owned by the HMAC and should not be modified or freed. a #GHmac Atomically increments the reference count of @hmac by one. This function is MT-safe and may be called from any thread. the passed in #GHmac. a valid #GHmac Atomically decrements the reference count of @hmac by one. If the reference count drops to 0, all keys and values will be destroyed, and all memory allocated by the hash table is released. This function is MT-safe and may be called from any thread. Frees the memory allocated for @hmac. a #GHmac Feeds @data into an existing #GHmac. The HMAC must still be open, that is g_hmac_get_string() or g_hmac_get_digest() must not have been called on @hmac. a #GHmac buffer used to compute the checksum size of the buffer, or -1 if it is a nul-terminated string The #GHook struct represents a single hook function in a #GHookList. data which is passed to func when this hook is invoked pointer to the next hook in the list pointer to the previous hook in the list the reference count of this hook the id of this hook, which is unique within its list flags which are set for this hook. See #GHookFlagMask for predefined flags the function to call when this hook is invoked. The possible signatures for this function are #GHookFunc and #GHookCheckFunc the default @finalize_hook function of a #GHookList calls this member of the hook that is being finalized Compares the ids of two #GHook elements, returning a negative value if the second id is greater than the first. a value <= 0 if the id of @sibling is >= the id of @new_hook a #GHook a #GHook to compare with @new_hook Allocates space for a #GHook and initializes it. a new #GHook a #GHookList Destroys a #GHook, given its ID. %TRUE if the #GHook was found in the #GHookList and destroyed a #GHookList a hook ID Removes one #GHook from a #GHookList, marking it inactive and calling g_hook_unref() on it. a #GHookList the #GHook to remove Finds a #GHook in a #GHookList using the given function to test for a match. the found #GHook or %NULL if no matching #GHook is found a #GHookList %TRUE if #GHook elements which have been destroyed should be skipped the function to call for each #GHook, which should return %TRUE when the #GHook has been found the data to pass to @func Finds a #GHook in a #GHookList with the given data. the #GHook with the given @data or %NULL if no matching #GHook is found a #GHookList %TRUE if #GHook elements which have been destroyed should be skipped the data to find Finds a #GHook in a #GHookList with the given function. the #GHook with the given @func or %NULL if no matching #GHook is found a #GHookList %TRUE if #GHook elements which have been destroyed should be skipped the function to find Finds a #GHook in a #GHookList with the given function and data. the #GHook with the given @func and @data or %NULL if no matching #GHook is found a #GHookList %TRUE if #GHook elements which have been destroyed should be skipped the function to find the data to find Returns the first #GHook in a #GHookList which has not been destroyed. The reference count for the #GHook is incremented, so you must call g_hook_unref() to restore it when no longer needed. (Or call g_hook_next_valid() if you are stepping through the #GHookList.) the first valid #GHook, or %NULL if none are valid a #GHookList %TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped Calls the #GHookList @finalize_hook function if it exists, and frees the memory allocated for the #GHook. a #GHookList the #GHook to free Returns the #GHook with the given id, or %NULL if it is not found. the #GHook with the given id, or %NULL if it is not found a #GHookList a hook id Inserts a #GHook into a #GHookList, before a given #GHook. a #GHookList the #GHook to insert the new #GHook before the #GHook to insert Inserts a #GHook into a #GHookList, sorted by the given function. a #GHookList the #GHook to insert the comparison function used to sort the #GHook elements Returns the next #GHook in a #GHookList which has not been destroyed. The reference count for the #GHook is incremented, so you must call g_hook_unref() to restore it when no longer needed. (Or continue to call g_hook_next_valid() until %NULL is returned.) the next valid #GHook, or %NULL if none are valid a #GHookList the current #GHook %TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped Prepends a #GHook on the start of a #GHookList. a #GHookList the #GHook to add to the start of @hook_list Increments the reference count for a #GHook. the @hook that was passed in (since 2.6) a #GHookList the #GHook to increment the reference count of Decrements the reference count of a #GHook. If the reference count falls to 0, the #GHook is removed from the #GHookList and g_hook_free() is called to free it. a #GHookList the #GHook to unref Defines the type of a hook function that can be invoked by g_hook_list_invoke_check(). %FALSE if the #GHook should be destroyed the data field of the #GHook is passed to the hook function here Defines the type of function used by g_hook_list_marshal_check(). %FALSE if @hook should be destroyed a #GHook user data Defines the type of function used to compare #GHook elements in g_hook_insert_sorted(). a value <= 0 if @new_hook should be before @sibling the #GHook being inserted the #GHook to compare with @new_hook Defines the type of function to be called when a hook in a list of hooks gets finalized. a #GHookList the hook in @hook_list that gets finalized Defines the type of the function passed to g_hook_find(). %TRUE if the required #GHook has been found a #GHook user data passed to g_hook_find_func() Flags used internally in the #GHook implementation. set if the hook has not been destroyed set if the hook is currently being run Defines the type of a hook function that can be invoked by g_hook_list_invoke(). the data field of the #GHook is passed to the hook function here The #GHookList struct represents a list of hook functions. the next free #GHook id the size of the #GHookList elements, in bytes 1 if the #GHookList has been initialized the first #GHook element in the list unused the function to call to finalize a #GHook element. The default behaviour is to call the hooks @destroy function unused Removes all the #GHook elements from a #GHookList. a #GHookList Initializes a #GHookList. This must be called before the #GHookList is used. a #GHookList the size of each element in the #GHookList, typically `sizeof (GHook)`. Calls all of the #GHook functions in a #GHookList. a #GHookList %TRUE if functions which are already running (e.g. in another thread) can be called. If set to %FALSE, these are skipped Calls all of the #GHook functions in a #GHookList. Any function which returns %FALSE is removed from the #GHookList. a #GHookList %TRUE if functions which are already running (e.g. in another thread) can be called. If set to %FALSE, these are skipped Calls a function on each valid #GHook. a #GHookList %TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped the function to call for each #GHook data to pass to @marshaller Calls a function on each valid #GHook and destroys it if the function returns %FALSE. a #GHookList %TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped the function to call for each #GHook data to pass to @marshaller Defines the type of function used by g_hook_list_marshal(). a #GHook user data The GIConv struct wraps an iconv() conversion descriptor. It contains private data and should only be accessed using the following functions. Same as the standard UNIX routine iconv(), but may be implemented via libiconv on UNIX flavors that lack a native implementation. GLib provides g_convert() and g_locale_to_utf8() which are likely more convenient than the raw iconv wrappers. Note that the behaviour of iconv() for characters which are valid in the input character set, but which have no representation in the output character set, is implementation defined. This function may return success (with a positive number of non-reversible conversions as replacement characters were used), or it may return -1 and set an error such as %EILSEQ, in such a situation. See [`iconv(3posix)`](man:iconv(3posix)) and [`iconv(3)`](man:iconv(3)) for more details about behavior when an error occurs. count of non-reversible conversions, or -1 on error conversion descriptor from g_iconv_open() bytes to convert inout parameter, bytes remaining to convert in @inbuf converted output bytes inout parameter, bytes available to fill in @outbuf Same as the standard UNIX routine iconv_close(), but may be implemented via libiconv on UNIX flavors that lack a native implementation. Should be called to clean up the conversion descriptor from g_iconv_open() when you are done converting things. GLib provides g_convert() and g_locale_to_utf8() which are likely more convenient than the raw iconv wrappers. -1 on error, 0 on success a conversion descriptor from g_iconv_open() Same as the standard UNIX routine iconv_open(), but may be implemented via libiconv on UNIX flavors that lack a native implementation. GLib provides g_convert() and g_locale_to_utf8() which are likely more convenient than the raw iconv wrappers. a "conversion descriptor", or (GIConv)-1 if opening the converter failed. destination codeset source codeset The bias by which exponents in double-precision floats are offset. The bias by which exponents in single-precision floats are offset. The `GIOChannel` data type aims to provide a portable method for using file descriptors, pipes, and sockets, and integrating them into the main event loop (see [struct@GLib.MainContext]). Currently, full support is available on UNIX platforms; support for Windows is only partially complete. To create a new `GIOChannel` on UNIX systems use [ctor@GLib.IOChannel.unix_new]. This works for plain file descriptors, pipes and sockets. Alternatively, a channel can be created for a file in a system independent manner using [ctor@GLib.IOChannel.new_file]. Once a `GIOChannel` has been created, it can be used in a generic manner with the functions [method@GLib.IOChannel.read_chars], [method@GLib.IOChannel.write_chars], [method@GLib.IOChannel.seek_position], and [method@GLib.IOChannel.shutdown]. To add a `GIOChannel` to the main event loop, use [func@GLib.io_add_watch] or [func@GLib.io_add_watch_full]. Here you specify which events you are interested in on the `GIOChannel`, and provide a function to be called whenever these events occur. `GIOChannel` instances are created with an initial reference count of 1. [method@GLib.IOChannel.ref] and [method@GLib.IOChannel.unref] can be used to increment or decrement the reference count respectively. When the reference count falls to 0, the `GIOChannel` is freed. (Though it isn’t closed automatically, unless it was created using [ctor@GLib.IOChannel.new_file].) Using [func@GLib.io_add_watch] or [func@GLib.io_add_watch_full] increments a channel’s reference count. The new functions [method@GLib.IOChannel.read_chars], [method@GLib.IOChannel.read_line], [method@GLib.IOChannel.read_line_string], [method@GLib.IOChannel.read_to_end], [method@GLib.IOChannel.write_chars], [method@GLib.IOChannel.seek_position], and [method@GLib.IOChannel.flush] should not be mixed with the deprecated functions [method@GLib.IOChannel.read], [method@GLib.IOChannel.write], and [method@GLib.IOChannel.seek] on the same channel. Open a file @filename as a #GIOChannel using mode @mode. This channel will be closed when the last reference to it is dropped, so there is no need to call g_io_channel_close() (though doing so will not cause problems, as long as no attempt is made to access the channel after it is closed). A #GIOChannel on success, %NULL on failure. A string containing the name of a file One of "r", "w", "a", "r+", "w+", "a+". These have the same meaning as in fopen() Creates a new #GIOChannel given a file descriptor. On UNIX systems this works for plain files, pipes, and sockets. The returned #GIOChannel has a reference count of 1. The default encoding for #GIOChannel is UTF-8. If your application is reading output from a command using via pipe, you may need to set the encoding to the encoding of the current locale (see g_get_charset()) with the g_io_channel_set_encoding() function. By default, the fd passed will not be closed when the final reference to the #GIOChannel data structure is dropped. If you want to read raw binary data without interpretation, then call the g_io_channel_set_encoding() function with %NULL for the encoding argument. This function is available in GLib on Windows, too, but you should avoid using it on Windows. The domain of file descriptors and sockets overlap. There is no way for GLib to know which one you mean in case the argument you pass to this function happens to be both a valid file descriptor and socket. If that happens a warning is issued, and GLib assumes that it is the file descriptor you mean. a new #GIOChannel. a file descriptor. Close an IO channel. Any pending data to be written will be flushed, ignoring errors. The channel will not be freed until the last reference is dropped using g_io_channel_unref(). Use g_io_channel_shutdown() instead. A #GIOChannel Flushes the write buffer for the GIOChannel. the status of the operation: One of %G_IO_STATUS_NORMAL, %G_IO_STATUS_AGAIN, or %G_IO_STATUS_ERROR. a #GIOChannel This function returns a #GIOCondition depending on whether there is data to be read/space to write data in the internal buffers in the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set. A #GIOCondition A #GIOChannel Gets the buffer size. the size of the buffer. a #GIOChannel Returns whether @channel is buffered. %TRUE if the @channel is buffered. a #GIOChannel Returns whether the file/socket/whatever associated with @channel will be closed when @channel receives its final unref and is destroyed. The default value of this is %TRUE for channels created by g_io_channel_new_file (), and %FALSE for all other channels. %TRUE if the channel will be closed, %FALSE otherwise. a #GIOChannel. Gets the encoding for the input/output of the channel. The internal encoding is always UTF-8. The encoding %NULL makes the channel safe for binary data. A string containing the encoding, this string is owned by GLib and must not be freed. a #GIOChannel Gets the current flags for a #GIOChannel, including read-only flags such as %G_IO_FLAG_IS_READABLE. The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITABLE are cached for internal use by the channel when it is created. If they should change at some later point (e.g. partial shutdown of a socket with the UNIX shutdown() function), the user should immediately call g_io_channel_get_flags() to update the internal values of these flags. the flags which are set on the channel a #GIOChannel This returns the string that #GIOChannel uses to determine where in the file a line break occurs. A value of %NULL indicates autodetection. Since 2.84, the return value is always nul-terminated. The line termination string. This value is owned by GLib and must not be freed. a #GIOChannel a location to return the length of the line terminator Initializes a #GIOChannel struct. This is called by each of the above functions when creating a #GIOChannel, and so is not often needed by the application programmer (unless you are creating a new type of #GIOChannel). a #GIOChannel Reads data from a #GIOChannel. Use g_io_channel_read_chars() instead. %G_IO_ERROR_NONE if the operation was successful. a #GIOChannel a buffer to read the data into (which should be at least count bytes long) the number of bytes to read from the #GIOChannel returns the number of bytes actually read Replacement for g_io_channel_read() with the new API. the status of the operation. a #GIOChannel a buffer to read data into the size of the buffer. Note that the buffer may not be completely filled even if there is data in the buffer if the remaining data is not a complete character. The number of bytes read. This may be zero even on success if count < 6 and the channel's encoding is non-%NULL. This indicates that the next UTF-8 character is too wide for the buffer. Reads a line, including the terminating character(s), from a #GIOChannel into a newly-allocated string. @str_return will contain allocated memory if the return is %G_IO_STATUS_NORMAL. the status of the operation. a #GIOChannel The line read from the #GIOChannel, including the line terminator. This data should be freed with g_free() when no longer needed. This is a nul-terminated string. If a @length of zero is returned, this will be %NULL instead. location to store length of the read data, or %NULL location to store position of line terminator, or %NULL Reads a line from a #GIOChannel, using a #GString as a buffer. the status of the operation. a #GIOChannel a #GString into which the line will be written. If @buffer already contains data, the old data will be overwritten. location to store position of line terminator, or %NULL Reads all the remaining data from the file. %G_IO_STATUS_NORMAL on success. This function never returns %G_IO_STATUS_EOF. a #GIOChannel Location to store a pointer to a string holding the remaining data in the #GIOChannel. This data should be freed with g_free() when no longer needed. This data is terminated by an extra nul character, but there may be other nuls in the intervening data. location to store length of the data Reads a Unicode character from @channel. This function cannot be called on a channel with %NULL encoding. a #GIOStatus a #GIOChannel a location to return a character Increments the reference count of a #GIOChannel. the @channel that was passed in (since 2.6) a #GIOChannel Sets the current position in the #GIOChannel, similar to the standard library function fseek(). Use g_io_channel_seek_position() instead. %G_IO_ERROR_NONE if the operation was successful. a #GIOChannel an offset, in bytes, which is added to the position specified by @type the position in the file, which can be %G_SEEK_CUR (the current position), %G_SEEK_SET (the start of the file), or %G_SEEK_END (the end of the file) Replacement for g_io_channel_seek() with the new API. the status of the operation. a #GIOChannel The offset in bytes from the position specified by @type a #GSeekType. The type %G_SEEK_CUR is only allowed in those cases where a call to g_io_channel_set_encoding () is allowed. See the documentation for g_io_channel_set_encoding () for details. Sets the buffer size. a #GIOChannel the size of the buffer, or 0 to let GLib pick a good size The buffering state can only be set if the channel's encoding is %NULL. For any other encoding, the channel must be buffered. A buffered channel can only be set unbuffered if the channel's internal buffers have been flushed. Newly created channels or channels which have returned %G_IO_STATUS_EOF not require such a flush. For write-only channels, a call to g_io_channel_flush () is sufficient. For all other channels, the buffers may be flushed by a call to g_io_channel_seek_position (). This includes the possibility of seeking with seek type %G_SEEK_CUR and an offset of zero. Note that this means that socket-based channels cannot be set unbuffered once they have had data read from them. On unbuffered channels, it is safe to mix read and write calls from the new and old APIs, if this is necessary for maintaining old code. The default state of the channel is buffered. a #GIOChannel whether to set the channel buffered or unbuffered Whether to close the channel on the final unref of the #GIOChannel data structure. The default value of this is %TRUE for channels created by g_io_channel_new_file (), and %FALSE for all other channels. Setting this flag to %TRUE for a channel you have already closed can cause problems when the final reference to the #GIOChannel is dropped. a #GIOChannel Whether to close the channel on the final unref of the GIOChannel data structure. Sets the encoding for the input/output of the channel. The internal encoding is always UTF-8. The default encoding for the external file is UTF-8. The encoding %NULL is safe to use with binary data. The encoding can only be set if one of the following conditions is true: - The channel was just created, and has not been written to or read from yet. - The channel is write-only. - The channel is a file, and the file pointer was just repositioned by a call to g_io_channel_seek_position(). (This flushes all the internal buffers.) - The current encoding is %NULL or UTF-8. - One of the (new API) read functions has just returned %G_IO_STATUS_EOF (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL). - One of the functions g_io_channel_read_chars() or g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or %G_IO_STATUS_ERROR. This may be useful in the case of %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Returning one of these statuses from g_io_channel_read_line(), g_io_channel_read_line_string(), or g_io_channel_read_to_end() does not guarantee that the encoding can be changed. Channels which do not meet one of the above conditions cannot call g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if they are "seekable", cannot call g_io_channel_write_chars() after calling one of the API "read" functions. %G_IO_STATUS_NORMAL if the encoding was successfully set a #GIOChannel the encoding type Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK). the status of the operation. a #GIOChannel the flags to set on the IO channel This sets the string that #GIOChannel uses to determine where in the file a line break occurs. a #GIOChannel The line termination string. Use %NULL for autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0", and the Unicode paragraph separator. Autodetection should not be used for anything other than file-based channels. The length of the termination string. If -1 is passed, the string is assumed to be nul-terminated. This option allows termination strings with embedded nuls. Close an IO channel. Any pending data to be written will be flushed if @flush is %TRUE. The channel will not be freed until the last reference is dropped using g_io_channel_unref(). the status of the operation. a #GIOChannel if %TRUE, flush pending Returns the file descriptor of the #GIOChannel. On Windows this function returns the file descriptor or socket of the #GIOChannel. the file descriptor of the #GIOChannel. a #GIOChannel, created with g_io_channel_unix_new(). Decrements the reference count of a #GIOChannel. a #GIOChannel Writes data to a #GIOChannel. Use g_io_channel_write_chars() instead. %G_IO_ERROR_NONE if the operation was successful. a #GIOChannel the buffer containing the data to write the number of bytes to write the number of bytes actually written Replacement for g_io_channel_write() with the new API. On seekable channels with encodings other than %NULL or UTF-8, generic mixing of reading and writing is not allowed. A call to g_io_channel_write_chars () may only be made on a channel from which data has been read in the cases described in the documentation for g_io_channel_set_encoding (). the status of the operation. a #GIOChannel a buffer to write data from the size of the buffer. If -1, the buffer is taken to be a nul-terminated string. The number of bytes written. This can be nonzero even if the return value is not %G_IO_STATUS_NORMAL. If the return value is %G_IO_STATUS_NORMAL and the channel is blocking, this will always be equal to @count if @count >= 0. Writes a Unicode character to @channel. This function cannot be called on a channel with %NULL encoding. a #GIOStatus a #GIOChannel a character Converts an `errno` error number to a #GIOChannelError. a #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL. an `errno` error number, e.g. `EINVAL` Error codes returned by #GIOChannel operations. File too large. Invalid argument. IO error. File is a directory. No space left on device. No such device or address. Value too large for defined datatype. Broken pipe. Some other error. A bitwise combination representing a condition to watch for on an event source. There is data to read. Data can be written (without blocking). There is urgent data to read. Error condition. Hung up (the connection has been broken, usually for pipes and sockets). Invalid request. The file descriptor is not open. #GIOError is only used by the deprecated functions g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek(). no error an EAGAIN error occurred an EINVAL error occurred another error occurred Specifies properties of a #GIOChannel. Some of the flags can only be read with g_io_channel_get_flags(), but not changed with g_io_channel_set_flags(). no special flags set. Since: 2.74 turns on append mode, corresponds to %O_APPEND (see the documentation of the UNIX open() syscall) turns on nonblocking mode, corresponds to %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open() syscall) indicates that the io channel is readable. This flag cannot be changed. indicates that the io channel is writable. This flag cannot be changed. a misspelled version of @G_IO_FLAG_IS_WRITABLE that existed before the spelling was fixed in GLib 2.30. It is kept here for compatibility reasons. Deprecated since 2.30 indicates that the io channel is seekable, i.e. that g_io_channel_seek_position() can be used on it. This flag cannot be changed. the mask that specifies all the valid flags. the mask of the flags that are returned from g_io_channel_get_flags() the mask of the flags that the user can modify with g_io_channel_set_flags() Specifies the type of function passed to g_io_add_watch() or g_io_add_watch_full(), which is called when the requested condition on a #GIOChannel is satisfied. the function should return %FALSE if the event source should be removed the #GIOChannel event source the condition which has been satisfied user data set in g_io_add_watch() or g_io_add_watch_full() A table of functions used to handle different types of #GIOChannel in a generic way. reads raw bytes from the channel. This is called from various functions such as g_io_channel_read_chars() to read raw bytes from the channel. Encoding and buffering issues are dealt with at a higher level. writes raw bytes to the channel. This is called from various functions such as g_io_channel_write_chars() to write raw bytes to the channel. Encoding and buffering issues are dealt with at a higher level. seeks the channel. This is called from g_io_channel_seek() on channels that support it. closes the channel. This is called from g_io_channel_close() after flushing the buffers. creates a watch on the channel. This call corresponds directly to g_io_create_watch(). called from g_io_channel_unref() when the channel needs to be freed. This function must free the memory associated with the channel, including freeing the #GIOChannel structure itself. The channel buffers have been flushed and possibly @io_close has been called by the time this function is called. sets the #GIOFlags on the channel. This is called from g_io_channel_set_flags() with all flags except for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked out. gets the #GIOFlags for the channel. This function need only return the %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags() automatically adds the others as appropriate. Statuses returned by most of the #GIOFuncs functions. An error occurred. Success. End of file. Resource temporarily unavailable. Checks whether a character is a directory separator. It returns true for `'/'` on UNIX machines and for `'\'` or `'/'` under Windows. a character The name of the main group of a desktop entry file, as defined in the [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/). Consult the specification for more details about the meanings of the keys below. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string list giving the available application actions. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a list of strings giving the categories in which the desktop entry should be shown in a menu. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a localized string giving the tooltip for the desktop entry. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean set to true if the application is D-Bus activatable. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string giving the command line to execute. It is only valid for desktop entries with the `Application` type. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a localized string giving the generic name of the desktop entry. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean stating whether the desktop entry has been deleted by the user. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a localized string giving the name of the icon to be displayed for the desktop entry. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a list of strings giving the MIME types supported by this desktop entry. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a localized string giving the specific name of the desktop entry. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a list of strings identifying the environments that should not display the desktop entry. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean stating whether the desktop entry should be shown in menus. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a list of strings identifying the environments that should display the desktop entry. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string containing the working directory to run the program in. It is only valid for desktop entries with the `Application` type. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean stating whether the application supports the [Startup Notification Protocol Specification](https://specifications.freedesktop.org/startup-notification-spec/latest/). A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is string identifying the WM class or name hint of a window that the application will create, which can be used to emulate [Startup Notification](https://specifications.freedesktop.org/startup-notification-spec/latest/) with older applications. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean stating whether the program should be run in a terminal window. It is only valid for desktop entries with the `Application` type. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string giving the file name of a binary on disk used to determine if the program is actually installed. It is only valid for desktop entries with the `Application` type. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string giving the type of the desktop entry. Usually [const@GLib.KEY_FILE_DESKTOP_TYPE_APPLICATION], [const@GLib.KEY_FILE_DESKTOP_TYPE_LINK], or [const@GLib.KEY_FILE_DESKTOP_TYPE_DIRECTORY]. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string giving the URL to access. It is only valid for desktop entries with the `Link` type. A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string giving the version of the Desktop Entry Specification used for the desktop entry file. The value of the [const@GLib.KEY_FILE_DESKTOP_KEY_TYPE], key for desktop entries representing applications. The value of the [const@GLib.KEY_FILE_DESKTOP_KEY_TYPE], key for desktop entries representing directories. The value of the [const@GLib.KEY_FILE_DESKTOP_KEY_TYPE], key for desktop entries representing links to documents. `GKeyFile` parses .ini-like config files. `GKeyFile` lets you parse, edit or create files containing groups of key-value pairs, which we call ‘key files’ for lack of a better name. Several freedesktop.org specifications use key files. For example, the [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/) and the [Icon Theme Specification](https://specifications.freedesktop.org/icon-theme-spec/latest/). The syntax of key files is described in detail in the [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/), here is a quick summary: Key files consists of groups of key-value pairs, interspersed with comments. ```txt # this is just an example # there can be comments before the first group [First Group] Name=Key File Example\tthis value shows\nescaping # localized strings are stored in multiple key-value pairs Welcome=Hello Welcome[de]=Hallo Welcome[fr_FR]=Bonjour Welcome[it]=Ciao [Another Group] Numbers=2;20;-200;0 Booleans=true;false;true;true ``` Lines beginning with a `#` and blank lines are considered comments. Groups are started by a header line containing the group name enclosed in `[` and `]`, and ended implicitly by the start of the next group or the end of the file. Each key-value pair must be contained in a group. Key-value pairs generally have the form `key=value`, with the exception of localized strings, which have the form `key[locale]=value`, with a locale identifier of the form `lang_COUNTRY@MODIFIER` where `COUNTRY` and `MODIFIER` are optional. As a special case, the locale `C` is associated with the untranslated pair `key=value` (since GLib 2.84). Space before and after the `=` character is ignored. Newline, tab, carriage return and backslash characters in value are escaped as `\n`, `\t`, `\r`, and `\\\\`, respectively. To preserve leading spaces in values, these can also be escaped as `\s`. Key files can store strings (possibly with localized variants), integers, booleans and lists of these. Lists are separated by a separator character, typically `;` or `,`. To use the list separator character in a value in a list, it has to be escaped by prefixing it with a backslash. This syntax is obviously inspired by the .ini files commonly met on Windows, but there are some important differences: - .ini files use the `;` character to begin comments, key files use the `#` character. - Key files do not allow for ungrouped keys meaning only comments can precede the first group. - Key files are always encoded in UTF-8. - Key and Group names are case-sensitive. For example, a group called `[GROUP]` is a different from `[group]`. - .ini files don’t have a strongly typed boolean entry type, they only have `GetProfileInt()`. In key files, only `true` and `false` (in lower case) are allowed. Note that in contrast to the [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/), groups in key files may contain the same key multiple times; the last entry wins. Key files may also contain multiple groups with the same name; they are merged together. Another difference is that keys and group names in key files are not restricted to ASCII characters. Here is an example of loading a key file and reading a value: ```c g_autoptr(GError) error = NULL; g_autoptr(GKeyFile) key_file = g_key_file_new (); if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error)) { if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT)) g_warning ("Error loading key file: %s", error->message); return; } g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error); if (val == NULL && !g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND)) { g_warning ("Error finding key in key file: %s", error->message); return; } else if (val == NULL) { // Fall back to a default value. val = g_strdup ("default-value"); } ``` Here is an example of creating and saving a key file: ```c g_autoptr(GKeyFile) key_file = g_key_file_new (); const gchar *val = …; g_autoptr(GError) error = NULL; g_key_file_set_string (key_file, "Group Name", "SomeKey", val); // Save as a file. if (!g_key_file_save_to_file (key_file, "key-file.ini", &error)) { g_warning ("Error saving key file: %s", error->message); return; } // Or store to a GBytes for use elsewhere. gsize data_len; g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error); if (data == NULL) { g_warning ("Error saving key file: %s", error->message); return; } g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len); ``` Creates a new empty [struct@GLib.KeyFile] object. Use [method@GLib.KeyFile.load_from_file], [method@GLib.KeyFile.load_from_data], [method@GLib.KeyFile.load_from_dirs] or [method@GLib.KeyFile.load_from_data_dirs] to read an existing key file. an empty [struct@GLib.KeyFile]. Clears all keys and groups from @key_file, and decreases the reference count by 1. If the reference count reaches zero, frees the key file and all its allocated memory. a key file Returns the value associated with @key under @group_name as a boolean. If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. Likewise, if the value associated with @key cannot be interpreted as a boolean then [error@GLib.KeyFileError.INVALID_VALUE] is returned. the value associated with the key as a boolean, or false if the key was not found or could not be parsed. a key file a group name a key Returns the values associated with @key under @group_name as booleans. If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. Likewise, if the values associated with @key cannot be interpreted as booleans then [error@GLib.KeyFileError.INVALID_VALUE] is returned. the values associated with the key as a list of booleans, or `NULL` if the key was not found or could not be parsed. The returned list of booleans should be freed with [func@GLib.free] when no longer needed. a key file a group name a key the number of booleans returned Retrieves a comment above @key from @group_name. If @key is `NULL` then @comment will be read from above @group_name. If both @key and @group_name are `NULL`, then @comment will be read from above the first group in the file. Note that the returned string does not include the `#` comment markers, but does include any whitespace after them (on each line). It includes the line breaks between lines, but does not include the final line break. a comment that should be freed with [func@GLib.free] a key file a group name, or `NULL` to get a top-level comment a key, or `NULL` to get a group comment Returns the value associated with @key under @group_name as a double. If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. Likewise, if the value associated with @key cannot be interpreted as a double then [error@GLib.KeyFileError.INVALID_VALUE] is returned. the value associated with the key as a double, or `0.0` if the key was not found or could not be parsed. a key file a group name a key Returns the values associated with @key under @group_name as doubles. If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. Likewise, if the values associated with @key cannot be interpreted as doubles then [error@GLib.KeyFileError.INVALID_VALUE] is returned. the values associated with the key as a list of doubles, or `NULL` if the key was not found or could not be parsed. The returned list of doubles should be freed with [func@GLib.free] when no longer needed. a key file a group name a key the number of doubles returned Returns all groups in the key file loaded with @key_file. The array of returned groups will be `NULL`-terminated, so @length may optionally be `NULL`. a newly-allocated `NULL`-terminated array of strings. Use [func@GLib.strfreev] to free it. a key file return location for the number of returned groups, or `NULL` to ignore Returns the value associated with @key under @group_name as a signed 64-bit integer. This is similar to [method@GLib.KeyFile.get_integer] but can return 64-bit results without truncation. the value associated with the key as a signed 64-bit integer, or `0` if the key was not found or could not be parsed. a key file a group name a key Returns the value associated with @key under @group_name as an integer. If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. Likewise, if the value associated with @key cannot be interpreted as an integer, or is out of range for a `gint`, then [error@GLib.KeyFileError.INVALID_VALUE] is returned. the value associated with the key as an integer, or `0` if the key was not found or could not be parsed. a key file a group name a key Returns the values associated with @key under @group_name as integers. If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. Likewise, if the values associated with @key cannot be interpreted as integers, or are out of range for `gint`, then [error@GLib.KeyFileError.INVALID_VALUE] is returned. the values associated with the key as a list of integers, or `NULL` if the key was not found or could not be parsed. The returned list of integers should be freed with [func@GLib.free] when no longer needed. a key file a group name a key the number of integers returned Returns all keys for the group name @group_name. The array of returned keys will be `NULL`-terminated, so @length may optionally be `NULL`. If the @group_name cannot be found, [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned. a newly-allocated `NULL`-terminated array of strings. Use [func@GLib.strfreev] to free it. a key file a group name return location for the number of keys returned, or `NULL` to ignore Returns the actual locale which the result of [method@GLib.KeyFile.get_locale_string] or [method@GLib.KeyFile.get_locale_string_list] came from. If calling [method@GLib.KeyFile.get_locale_string] or [method@GLib.KeyFile.get_locale_string_list] with exactly the same @key_file, @group_name, @key and @locale, the result of those functions will have originally been tagged with the locale that is the result of this function. the locale from the file, or `NULL` if the key was not found or the entry in the file was was untranslated a key file a group name a key a locale identifier or `NULL` to use the current locale Returns the value associated with @key under @group_name translated in the given @locale if available. If @locale is `C` then the untranslated value is returned (since GLib 2.84). If @locale is `NULL` then the current locale is assumed. If @locale is to be non-`NULL`, or if the current locale will change over the lifetime of the [struct@GLib.KeyFile], it must be loaded with [flags@GLib.KeyFileFlags.KEEP_TRANSLATIONS] in order to load strings for all locales. If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. If the value associated with @key cannot be interpreted or no suitable translation can be found then the untranslated value is returned. a newly allocated string or `NULL` if the specified key cannot be found. a key file a group name a key a locale identifier or `NULL` to use the current locale Returns the values associated with @key under @group_name translated in the given @locale if available. If @locale is `C` then the untranslated value is returned (since GLib 2.84). If @locale is `NULL` then the current locale is assumed. If @locale is to be non-`NULL`, or if the current locale will change over the lifetime of the [struct@GLib.KeyFile], it must be loaded with [flags@GLib.KeyFileFlags.KEEP_TRANSLATIONS] in order to load strings for all locales. If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. If the values associated with @key cannot be interpreted or no suitable translations can be found then the untranslated values are returned. The returned array is `NULL`-terminated, so @length may optionally be `NULL`. a newly allocated `NULL`-terminated string array or `NULL` if the key isn’t found. The string array should be freed with [func@GLib.strfreev]. a key file a group name a key a locale identifier or `NULL` to use the current locale return location for the number of returned strings or `NULL` to ignore Returns the name of the start group of the file. The start group of the key file. a key file Returns the string value associated with @key under @group_name. Unlike [method@GLib.KeyFile.get_value], this function handles escape sequences like `\s`. If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. If the @group_name cannot be found, [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned. a newly allocated string or `NULL` if the specified key cannot be found. a key file a group name a key Returns the values associated with @key under @group_name. If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. If the @group_name cannot be found, [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned. a `NULL`-terminated string array or `NULL` if the specified key cannot be found. The array should be freed with [func@GLib.strfreev]. a key file a group name a key return location for the number of returned strings, or `NULL` to ignore Returns the value associated with @key under @group_name as an unsigned 64-bit integer. This is similar to [method@GLib.KeyFile.get_integer] but can return large positive results without truncation. the value associated with the key as an unsigned 64-bit integer, or `0` if the key was not found or could not be parsed. a key file a group name a key Returns the raw value associated with @key under @group_name. Use [method@GLib.KeyFile.get_string] to retrieve an unescaped UTF-8 string. If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. If the @group_name cannot be found, [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned. a newly allocated string or `NULL` if the specified key cannot be found. a key file a group name a key Looks whether the key file has the group @group_name. true if @group_name is a part of @key_file, false otherwise. a key file a group name Looks whether the key file has the key @key in the group @group_name. Note that this function does not follow the rules for [struct@GLib.Error] strictly; the return value both carries meaning and signals an error. To use this function, you must pass a [struct@GLib.Error] pointer in @error, and check whether it is not `NULL` to see if an error occurred. Language bindings should use [method@GLib.KeyFile.get_value] to test whether a key exists. true if @key is a part of @group_name, false otherwise a key file a group name a key name Loads a key file from the data in @bytes into an empty [struct@GLib.KeyFile] structure. If the object cannot be created then a [error@GLib.KeyFileError] is returned. true if a key file could be loaded, false otherwise an empty [struct@GLib.KeyFile] struct a [struct@GLib.Bytes] flags from [flags@GLib.KeyFileFlags] Loads a key file from memory into an empty [struct@GLib.KeyFile] structure. If the object cannot be created then a [error@GLib.KeyFileError is returned. true if a key file could be loaded, false otherwise an empty key file key file loaded in memory the length of @data in bytes (or `(gsize)-1` if data is nul-terminated) flags from [flags@GLib.KeyFileFlags] Looks for a key file named @file in the paths returned from [func@GLib.get_user_data_dir] and [func@GLib.get_system_data_dirs]. The search algorithm from [method@GLib.KeyFile.load_from_dirs] is used. If @file is found, it’s loaded into @key_file and its full path is returned in @full_path. If the file could not be loaded then either a [error@GLib.FileError] or [error@GLib.KeyFileError] is returned. true if a key file could be loaded, false otherwise an empty [struct@GLib.KeyFile] struct a relative path to a filename to open and parse return location for a string containing the full path of the file, or `NULL` to ignore flags from [flags@GLib.KeyFileFlags] Looks for a key file named @file in the paths specified in @search_dirs, loads the file into @key_file and returns the file’s full path in @full_path. @search_dirs are checked in the order listed in the array, with the highest priority directory listed first. Within each directory, @file is looked for. If it’s not found, `-` characters in @file are progressively replaced with directory separators to search subdirectories of the search directory. If the file has not been found after all `-` characters have been replaced, the next search directory in @search_dirs is checked. If the file could not be found in any of the @search_dirs, [error@GLib.KeyFileError.NOT_FOUND] is returned. If the file is found but the OS returns an error when opening or reading the file, a [error@GLib.FileError] is returned. If there is a problem parsing the file, a [error@GLib.KeyFileError] is returned. true if a key file could be loaded, false otherwise an empty [struct@GLib.KeyFile] struct a relative path to a filename to open and parse `NULL`-terminated array of directories to search return location for a string containing the full path of the file, or `NULL` to ignore flags from [flags@GLib.KeyFileFlags] Loads a key file into an empty [struct@GLib.KeyFile] structure. If the OS returns an error when opening or reading the file, a [error@GLib.FileError] is returned. If there is a problem parsing the file, a [error@GLib.KeyFileError] is returned. This function will never return a [error@GLib.KeyFileError.NOT_FOUND] error. If the @file is not found, [error@GLib.FileError.NOENT] is returned. true if a key file could be loaded, false otherwise an empty key file the path of a filename to load, in the GLib filename encoding flags from [flags@GLib.KeyFileFlags] Increases the reference count of @key_file. the same @key_file. a key file Removes a comment above @key from @group_name. If @key is `NULL` then @comment will be removed above @group_name. If both @key and @group_name are `NULL`, then @comment will be removed above the first group in the file. true if the comment was removed, false otherwise a key file a group name, or `NULL` to get a top-level comment a key, or `NULL` to get a group comment Removes the specified group, @group_name, from the key file. true if the group was removed, false otherwise a key file a group name Removes @key in @group_name from the key file. true if the key was removed, false otherwise a key file a group name a key name to remove Writes the contents of @key_file to @filename using [func@GLib.file_set_contents]. If you need stricter guarantees about durability of the written file than are provided by [func@GLib.file_set_contents], use [func@GLib.file_set_contents_full] with the return value of [method@GLib.KeyFile.to_data]. This function can fail for any of the reasons that [func@GLib.file_set_contents] may fail. true if successful, false otherwise a key file the name of the file to write to Associates a new boolean value with @key under @group_name. If @key cannot be found then it is created. a key file a group name a key true or false Associates a list of boolean values with @key under @group_name. If @key cannot be found then it is created. a key file a group name a key an array of boolean values length of @list Places a comment above @key from @group_name. If @key is `NULL` then @comment will be written above @group_name. If both @key and @group_name are `NULL`, then @comment will be written above the first group in the file. Passing a non-existent @group_name or @key to this function returns false and populates @error. (In contrast, passing a non-existent `group_name` or `key` to [method@GLib.KeyFile.set_string] creates the associated group name and key.) Note that this function prepends a `#` comment marker to each line of @comment. true if the comment was written, false otherwise a key file a group name, or `NULL` to write a top-level comment a key, or `NULL` to write a group comment a comment Associates a new double value with @key under @group_name. If @key cannot be found then it is created. a key file a group name a key a double value Associates a list of double values with @key under @group_name. If @key cannot be found then it is created. a key file a group name a key an array of double values number of double values in @list Associates a new integer value with @key under @group_name. If @key cannot be found then it is created. a key file a group name a key an integer value Associates a new integer value with @key under @group_name. If @key cannot be found then it is created. a key file a group name a key an integer value Associates a list of integer values with @key under @group_name. If @key cannot be found then it is created. a key file a group name a key an array of integer values number of integer values in @list Sets the character which is used to separate values in lists. Typically `;` or `,` are used as separators. The default list separator is `;`. a key file the separator Associates a string value for @key and @locale under @group_name. If the translation for @key cannot be found then it is created. If @locale is `C` then the untranslated value is set (since GLib 2.84). a key file a group name a key a locale identifier a string Associates a list of string values for @key and @locale under @group_name. If @locale is `C` then the untranslated value is set (since GLib 2.84). If the translation for @key cannot be found then it is created. a key file a group name a key a locale identifier a `NULL`-terminated array of locale string values the length of @list Associates a new string value with @key under @group_name. If @key cannot be found then it is created. If @group_name cannot be found then it is created. Unlike [method@GLib.KeyFile.set_value], this function handles characters that need escaping, such as newlines. a key file a group name a key a string Associates a list of string values for @key under @group_name. If @key cannot be found then it is created. If @group_name cannot be found then it is created. a key file a group name a key an array of string values number of string values in @list Associates a new integer value with @key under @group_name. If @key cannot be found then it is created. a key file a group name a key an integer value Associates a new value with @key under @group_name. If @key cannot be found then it is created. If @group_name cannot be found then it is created. To set an UTF-8 string which may contain characters that need escaping (such as newlines or spaces), use [method@GLib.KeyFile.set_string]. a key file a group name a key a string Outputs @key_file as a string. Note that this function never reports an error. a newly allocated string holding the contents of the key file a key file return location for the length of the returned string, or `NULL` to ignore Decreases the reference count of @key_file by 1. If the reference count reaches zero, frees the key file and all its allocated memory. a key file Error codes returned by key file parsing. the text being parsed was in an unknown encoding document was ill-formed the file was not found a requested key was not found a requested group was not found a value could not be parsed Flags which influence the parsing. No flags, default behaviour Use this flag if you plan to write the (possibly modified) contents of the key file back to a file; otherwise all comments will be lost when the key file is written back. Use this flag if you plan to write the (possibly modified) contents of the key file back to a file; otherwise only the translations for the current language will be written back. Hints the compiler that the expression is likely to evaluate to a true value. The compiler may use this information for optimizations. |[<!-- language="C" --> if (G_LIKELY (random () != 1)) g_print ("not one"); ]| the expression Specifies one of the possible types of byte order. See %G_BYTE_ORDER. The natural logarithm of 10. The natural logarithm of 2. Works like g_mutex_lock(), but for a lock defined with %G_LOCK_DEFINE. the name of the lock The `G_LOCK_` macros provide a convenient interface to #GMutex. %G_LOCK_DEFINE defines a lock. It can appear in any place where variable definitions may appear in programs, i.e. in the first block of a function or outside of functions. The @name parameter will be mangled to get the name of the #GMutex. This means that you can use names of existing variables as the parameter - e.g. the name of the variable you intend to protect with the lock. Look at our give_me_next_number() example using the `G_LOCK` macros: Here is an example for using the `G_LOCK` convenience macros: |[<!-- language="C" --> G_LOCK_DEFINE (current_number); int give_me_next_number (void) { static int current_number = 0; int ret_val; G_LOCK (current_number); ret_val = current_number = calc_next_number (current_number); G_UNLOCK (current_number); return ret_val; } ]| the name of the lock This works like %G_LOCK_DEFINE, but it creates a static object. the name of the lock This declares a lock, that is defined with %G_LOCK_DEFINE in another module. the name of the lock Multiplying the base 2 exponent by this number yields the base 10 exponent. Defines the log domain. See [Log Domains](#log-domains). Libraries should define this so that any messages which they log can be differentiated from messages from other libraries and application code. But be careful not to define it in any public header files. Log domains must be unique, and it is recommended that they are the application or library name, optionally followed by a hyphen and a sub-domain name. For example, `bloatpad` or `bloatpad-io`. If undefined, it defaults to the default %NULL (or `""`) log domain; this is not advisable, as it cannot be filtered against using the `G_MESSAGES_DEBUG` environment variable. For example, GTK uses this in its `Makefile.am`: |[ AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\" ]| Applications can choose to leave it as the default %NULL (or `""`) domain. However, defining the domain offers the same advantages as above. GLib log levels that are considered fatal by default. This is not used if structured logging is enabled; see [Using Structured Logging](logging.html#using-structured-logging). Log levels below `1<<G_LOG_LEVEL_USER_SHIFT` are used by GLib. Higher bits can be used for user-defined log levels. The #GList struct is used for each element in a doubly-linked list. holds the element's data, which can be a pointer to any kind of data, or any integer value using the [Type Conversion Macros](conversion-macros.html#conversion-macros) contains the link to the next element in the list contains the link to the previous element in the list Allocates space for one #GList element. It is called by g_list_append(), g_list_prepend(), g_list_insert() and g_list_insert_sorted() and so is rarely used on its own. a pointer to the newly-allocated #GList element Adds a new element on to the end of the list. Note that the return value is the new start of the list, if @list was empty; make sure you store the new value. g_list_append() has to traverse the entire list to find the end, which is inefficient when adding multiple elements. A common idiom to avoid the inefficiency is to use g_list_prepend() and reverse the list with g_list_reverse() when all elements have been added. |[<!-- language="C" --> // Notice that these are initialized to the empty list. GList *string_list = NULL, *number_list = NULL; // This is a list of strings. string_list = g_list_append (string_list, "first"); string_list = g_list_append (string_list, "second"); // This is a list of integers. number_list = g_list_append (number_list, GINT_TO_POINTER (27)); number_list = g_list_append (number_list, GINT_TO_POINTER (14)); ]| either @list or the new start of the #GList if @list was %NULL a pointer to a #GList the data for the new element Adds the second #GList onto the end of the first #GList. Note that the elements of the second #GList are not copied. They are used directly. This function is for example used to move an element in the list. The following example moves an element to the top of the list: |[<!-- language="C" --> list = g_list_remove_link (list, llink); list = g_list_concat (llink, list); ]| the start of the new #GList, which equals @list1 if not %NULL a #GList, this must point to the top of the list the #GList to add to the end of the first #GList, this must point to the top of the list Copies a #GList. Note that this is a "shallow" copy. If the list elements consist of pointers to data, the pointers are copied but the actual data is not. See g_list_copy_deep() if you need to copy the data as well. the start of the new list that holds the same data as @list a #GList, this must point to the top of the list Makes a full (deep) copy of a #GList. In contrast with g_list_copy(), this function uses @func to make a copy of each list element, in addition to copying the list container itself. @func, as a #GCopyFunc, takes two arguments, the data to be copied and a @user_data pointer. On common processor architectures, it's safe to pass %NULL as @user_data if the copy function takes only one argument. You may get compiler warnings from this though if compiling with GCC’s `-Wcast-function-type` warning. For instance, if @list holds a list of GObjects, you can do: |[<!-- language="C" --> another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL); ]| And, to entirely free the new list, you could do: |[<!-- language="C" --> g_list_free_full (another_list, g_object_unref); ]| the start of the new list that holds a full copy of @list, use g_list_free_full() to free it a #GList, this must point to the top of the list a copy function used to copy every element in the list user data passed to the copy function @func, or %NULL Removes the node link_ from the list and frees it. Compare this to g_list_remove_link() which removes the node without freeing it. the (possibly changed) start of the #GList a #GList, this must point to the top of the list node to delete from @list Finds the element in a #GList which contains the given data. the found #GList element, or %NULL if it is not found a #GList, this must point to the top of the list the element data to find Finds an element in a #GList, using a supplied function to find the desired element. It iterates over the list, calling the given function which should return 0 when the desired element is found. The function takes two #gconstpointer arguments, the #GList element's data as the first argument and the given user data. the found #GList element, or %NULL if it is not found a #GList, this must point to the top of the list user data passed to the function the function to call for each element. It should return 0 when the desired element is found Gets the first element in a #GList. the first element in the #GList, or %NULL if the #GList has no elements any #GList element Calls a function for each element of a #GList. It is safe for @func to remove the element from @list, but it must not modify any part of the list after that element. a #GList, this must point to the top of the list the function to call with each element's data user data to pass to the function Frees all of the memory used by a #GList. The freed elements are returned to the slice allocator. If list elements contain dynamically-allocated memory, you should either use g_list_free_full() or free them manually first. It can be combined with g_steal_pointer() to ensure the list head pointer is not left dangling: |[<!-- language="C" --> GList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/ g_list_free (g_steal_pointer (&list_of_borrowed_things)); ]| the first link of a #GList Frees one #GList element, but does not update links from the next and previous elements in the list, so you should not call this function on an element that is currently part of a list. It is usually used after g_list_remove_link(). a #GList element Convenience method, which frees all the memory used by a #GList, and calls @free_func on every element's data. @free_func must not modify the list (eg, by removing the freed element from it). It can be combined with g_steal_pointer() to ensure the list head pointer is not left dangling ­— this also has the nice property that the head pointer is cleared before any of the list elements are freed, to prevent double frees from @free_func: |[<!-- language="C" --> GList *list_of_owned_things = …; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/ g_list_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref); ]| the first link of a #GList the function to be called to free each element's data Gets the position of the element containing the given data (starting from 0). the index of the element containing the data, or -1 if the data is not found a #GList, this must point to the top of the list the data to find Inserts a new element into the list at the given position. the (possibly changed) start of the #GList a pointer to a #GList, this must point to the top of the list the data for the new element the position to insert the element. If this is negative, or is larger than the number of elements in the list, the new element is added on to the end of the list. Inserts a new element into the list before the given position. the (possibly changed) start of the #GList a pointer to a #GList, this must point to the top of the list the list element before which the new element is inserted or %NULL to insert at the end of the list the data for the new element Inserts @link_ into the list before the given position. the (possibly changed) start of the #GList a pointer to a #GList, this must point to the top of the list the list element before which the new element is inserted or %NULL to insert at the end of the list the list element to be added, which must not be part of any other list Inserts a new element into the list, using the given comparison function to determine its position. If you are adding many new elements to a list, and the number of new elements is much larger than the length of the list, use g_list_prepend() to add the new items and sort the list afterwards with g_list_sort(). the (possibly changed) start of the #GList a pointer to a #GList, this must point to the top of the already sorted list the data for the new element the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. Inserts a new element into the list, using the given comparison function to determine its position. If you are adding many new elements to a list, and the number of new elements is much larger than the length of the list, use g_list_prepend() to add the new items and sort the list afterwards with g_list_sort(). the (possibly changed) start of the #GList a pointer to a #GList, this must point to the top of the already sorted list the data for the new element the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. user data to pass to comparison function Gets the last element in a #GList. the last element in the #GList, or %NULL if the #GList has no elements any #GList element Gets the number of elements in a #GList. This function iterates over the whole list to count its elements. Use a #GQueue instead of a GList if you regularly need the number of items. To check whether the list is non-empty, it is faster to check @list against %NULL. the number of elements in the #GList a #GList, this must point to the top of the list Gets the element at the given position in a #GList. This iterates over the list until it reaches the @n-th position. If you intend to iterate over every element, it is better to use a for-loop as described in the #GList introduction. the element, or %NULL if the position is off the end of the #GList a #GList, this must point to the top of the list the position of the element, counting from 0 Gets the data of the element at the given position. This iterates over the list until it reaches the @n-th position. If you intend to iterate over every element, it is better to use a for-loop as described in the #GList introduction. the element's data, or %NULL if the position is off the end of the #GList a #GList, this must point to the top of the list the position of the element Gets the element @n places before @list. the element, or %NULL if the position is off the end of the #GList a #GList the position of the element, counting from 0 Gets the position of the given element in the #GList (starting from 0). the position of the element in the #GList, or -1 if the element is not found a #GList, this must point to the top of the list an element in the #GList Prepends a new element on to the start of the list. Note that the return value is the new start of the list, which will have changed, so make sure you store the new value. |[<!-- language="C" --> // Notice that it is initialized to the empty list. GList *list = NULL; list = g_list_prepend (list, "last"); list = g_list_prepend (list, "first"); ]| Do not use this function to prepend a new element to a different element than the start of the list. Use g_list_insert_before() instead. a pointer to the newly prepended element, which is the new start of the #GList a pointer to a #GList, this must point to the top of the list the data for the new element Removes an element from a #GList. If two elements contain the same data, only the first is removed. If none of the elements contain the data, the #GList is unchanged. the (possibly changed) start of the #GList a #GList, this must point to the top of the list the data of the element to remove Removes all list nodes with data equal to @data. Returns the new head of the list. Contrast with g_list_remove() which removes only the first node matching the given data. the (possibly changed) start of the #GList a #GList, this must point to the top of the list data to remove Removes an element from a #GList, without freeing the element. The removed element's prev and next links are set to %NULL, so that it becomes a self-contained list with one element. This function is for example used to move an element in the list (see the example for g_list_concat()) or to remove an element in the list before freeing its data: |[<!-- language="C" --> list = g_list_remove_link (list, llink); free_some_data_that_may_access_the_list_again (llink->data); g_list_free (llink); ]| the (possibly changed) start of the #GList a #GList, this must point to the top of the list an element in the #GList Reverses a #GList. It simply switches the next and prev pointers of each element. the start of the reversed #GList a #GList, this must point to the top of the list Sorts a #GList using the given comparison function. The algorithm used is a stable sort. the (possibly changed) start of the #GList a #GList, this must point to the top of the list the comparison function used to sort the #GList. This function is passed the data from 2 elements of the #GList and should return 0 if they are equal, a negative value if the first element comes before the second, or a positive value if the first element comes after the second. Like g_list_sort(), but the comparison function accepts a user data argument. the (possibly changed) start of the #GList a #GList, this must point to the top of the list comparison function user data to pass to comparison function Structure representing a single field in a structured log entry. See g_log_structured() for details. Log fields may contain arbitrary values, including binary with embedded nul bytes. If the field contains a string, the string must be UTF-8 encoded and have a trailing nul byte. Otherwise, @length must be set to a non-negative value. field name (UTF-8 string) field value (arbitrary bytes) length of @value, in bytes, or -1 if it is nul-terminated Specifies the prototype of log handler functions. The default log handler, [func@GLib.log_default_handler], automatically appends a new-line character to @message when printing it. It is advised that any custom log handler functions behave similarly, so that logging calls in user code do not need modifying to add a new-line character to the message if the log handler is changed. The `log_domain` parameter can be set to `NULL` or an empty string to use the default application domain. This is not used if structured logging is enabled; see [Using Structured Logging](logging.html#using-structured-logging). the log domain of the message the log level of the message (including the fatal and recursion flags) the message to process user data, set in [func@GLib.log_set_handler] Flags specifying the level of log messages. It is possible to change how GLib treats messages of the various levels using [func@GLib.log_set_handler] and [func@GLib.log_set_fatal_mask]. internal flag internal flag log level for errors, see [func@GLib.error]. This level is also used for messages produced by [func@GLib.assert]. log level for critical warning messages, see [func@GLib.critical]. This level is also used for messages produced by [func@GLib.return_if_fail] and [func@GLib.return_val_if_fail]. log level for warnings, see [func@GLib.warning] log level for messages, see [func@GLib.message] log level for informational messages, see [func@GLib.info] log level for debug messages, see [func@GLib.debug] a mask including all log levels Writer function for log entries. A log entry is a collection of one or more #GLogFields, using the standard [field names from journal specification](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html). See g_log_structured() for more information. Writer functions must ignore fields which they do not recognise, unless they can write arbitrary binary output, as field values may be arbitrary binary. @log_level is guaranteed to be included in @fields as the `PRIORITY` field, but is provided separately for convenience of deciding whether or where to output the log entry. Writer functions should return %G_LOG_WRITER_HANDLED if they handled the log message successfully or if they deliberately ignored it. If there was an error handling the message (for example, if the writer function is meant to send messages to a remote logging server and there is a network error), it should return %G_LOG_WRITER_UNHANDLED. This allows writer functions to be chained and fall back to simpler handlers in case of failure. %G_LOG_WRITER_HANDLED if the log entry was handled successfully; %G_LOG_WRITER_UNHANDLED otherwise log level of the message fields forming the message number of @fields user data passed to g_log_set_writer_func() Return values from #GLogWriterFuncs to indicate whether the given log entry was successfully handled by the writer, or whether there was an error in handling it (and hence a fallback writer should be used). If a #GLogWriterFunc ignores a log entry, it should return %G_LOG_WRITER_HANDLED. Log writer has handled the log entry. Log writer could not handle the log entry. The major version number of the GLib library. Like #glib_major_version, but from the headers used at application compile time, rather than from the library linked against at application run time. The micro version number of the GLib library. Like #gtk_micro_version, but from the headers used at application compile time, rather than from the library linked against at application run time. The minimum value which can be held in a #gint16. The minimum value which can be held in a #gint32. The minimum value which can be held in a #gint64. The minimum value which can be held in a #gint8. The minor version number of the GLib library. Like #gtk_minor_version, but from the headers used at application compile time, rather than from the library linked against at application run time. Declare a [type@GLib.MutexLocker] variable with `g_autoptr()` and lock the mutex. The mutex will be unlocked automatically when leaving the scope. The variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it is not used in the scope. This feature is only supported on GCC and clang. This macro is not defined on other compilers and should not be used in programs that are intended to be portable to those compilers. Note that this should be used in a place where it is allowed to declare a variable, which could be before any statement in the case `-Wdeclaration-after-statement` is used, or C standard prior to C99. ```c { G_MUTEX_AUTO_LOCK (&obj->mutex, locker); obj->stuff_with_lock (); if (condition) { // No need to unlock return; } // Unlock before end of scope g_clear_pointer (&locker, g_mutex_locker_free); obj->stuff_without_lock (); } ``` a [type@GLib.Mutex] a variable name to be declared The `GMainContext` struct is an opaque data type representing a set of sources to be handled in a main loop. Creates a new [struct@GLib.MainContext] structure. the new main context Creates a new [struct@GLib.MainContext] structure. the new main context a bitwise-OR combination of flags that can only be set at creation time Tries to become the owner of the specified context. If some other thread is the owner of the context, returns false immediately. Ownership is properly recursive: the owner can require ownership again and will release ownership when [method@GLib.MainContext.release] is called as many times as [method@GLib.MainContext.acquire]. You must be the owner of a context before you can call [method@GLib.MainContext.prepare], [method@GLib.MainContext.query], [method@GLib.MainContext.check], [method@GLib.MainContext.dispatch], [method@GLib.MainContext.release]. Since 2.76 @context can be `NULL` to use the global-default main context. true if this thread is now the owner of @context, false otherwise a main context (if `NULL`, the global-default main context will be used) Adds a file descriptor to the set of file descriptors polled for this context. This will very seldom be used directly. Instead a typical event source will use `g_source_add_unix_fd()` instead. a main context (or `NULL` for the global-default main context) a [struct@GLib.PollFD] structure holding information about a file descriptor to watch. the priority for this file descriptor which should be the same as the priority used for [method@GLib.Source.attach] to ensure that the file descriptor is polled whenever the results may be needed. Passes the results of polling back to the main loop. You should be careful to pass @fds and its length @n_fds as received from [method@GLib.MainContext.query], as this functions relies on assumptions on how @fds is filled. You must have successfully acquired the context with [method@GLib.MainContext.acquire] before you may call this function. Since 2.76 @context can be `NULL` to use the global-default main context. true if some sources are ready to be dispatched, false otherwise a main context (if `NULL`, the global-default main context will be used) the maximum numerical priority of sources to check array of [struct@GLib.PollFD]s that was passed to the last call to [method@GLib.MainContext.query] return value of [method@GLib.MainContext.query] Dispatches all pending sources. You must have successfully acquired the context with [method@GLib.MainContext.acquire] before you may call this function. Since 2.76 @context can be `NULL` to use the global-default main context. a main context (if `NULL`, the global-default main context will be used) Finds a source with the given source functions and user data. If multiple sources exist with the same source function and user data, the first one found will be returned. the source, if one was found, otherwise `NULL` a main context (if `NULL`, the global-default main context will be used). the @source_funcs passed to [ctor@GLib.Source.new] the user data from the callback Finds a [struct@GLib.Source] given a pair of context and ID. It is a programmer error to attempt to look up a non-existent source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source. the source a main context (if `NULL`, the global-default main context will be used) the source ID, as returned by [method@GLib.Source.get_id] Finds a source with the given user data for the callback. If multiple sources exist with the same user data, the first one found will be returned. the source, if one was found, otherwise `NULL` a main context (if `NULL`, the global-default main context will be used) the user_data for the callback Gets the poll function set by [method@GLib.MainContext.set_poll_func]. the poll function a main context (if `NULL`, the global-default main context will be used) Invokes a function in such a way that @context is owned during the invocation of @function. If @context is `NULL` then the global-default main context — as returned by [func@GLib.MainContext.default] — is used. If @context is owned by the current thread, @function is called directly. Otherwise, if @context is the thread-default main context of the current thread and [method@GLib.MainContext.acquire] succeeds, then @function is called and [method@GLib.MainContext.release] is called afterwards. In any other case, an idle source is created to call @function and that source is attached to @context (presumably to be run in another thread). The idle source is attached with [const@GLib.PRIORITY_DEFAULT] priority. If you want a different priority, use [method@GLib.MainContext.invoke_full]. Note that, as with normal idle functions, @function should probably return [const@GLib.SOURCE_REMOVE]. If it returns [const@GLib.SOURCE_CONTINUE], it will be continuously run in a loop (and may prevent this call from returning). a main context, or `NULL` for the global-default main context function to call data to pass to @function Invokes a function in such a way that @context is owned during the invocation of @function. This function is the same as [method@GLib.MainContext.invoke] except that it lets you specify the priority in case @function ends up being scheduled as an idle and also lets you give a [callback@GLib.DestroyNotify] for @data. The @notify function should not assume that it is called from any particular thread or with any particular context acquired. a main context, or `NULL` for the global-default main context the priority at which to run @function function to call data to pass to @function a function to call when @data is no longer in use Determines whether this thread holds the (recursive) ownership of this [struct@GLib.MainContext]. This is useful to know before waiting on another thread that may be blocking to get ownership of @context. true if current thread is owner of @context, false otherwise a main context (if `NULL`, the global-default main context will be used) Runs a single iteration for the given main loop. This involves checking to see if any event sources are ready to be processed, then if no events sources are ready and @may_block is true, waiting for a source to become ready, then dispatching the highest priority events sources that are ready. Otherwise, if @may_block is false, this function does not wait for sources to become ready, and only the highest priority sources which are already ready (if any) will be dispatched. Note that even when @may_block is true, it is still possible for [method@GLib.MainContext.iteration] to return false, since the wait may be interrupted for other reasons than an event source becoming ready. true if events were dispatched, false otherwise a main context (if `NULL`, the global-default main context will be used) whether the call may block Checks if any sources have pending events for the given context. true if events are pending, false otherwise a main context (if `NULL`, the global-default main context will be used) Pops @context off the thread-default context stack (verifying that it was on the top of the stack). a main context, or `NULL` for the global-default main context Prepares to poll sources within a main loop. The resulting information for polling is determined by calling [method@GLib.MainContext.query]. You must have successfully acquired the context with [method@GLib.MainContext.acquire] before you may call this function. true if some source is ready to be dispatched prior to polling, false otherwise a main context (if `NULL`, the global-default main context will be used) location to store priority of highest priority source already ready Acquires @context and sets it as the thread-default context for the current thread. This will cause certain asynchronous operations (such as most [Gio](../gio/index.html)-based I/O) which are started in this thread to run under @context and deliver their results to its main loop, rather than running under the global default main context in the main thread. Note that calling this function changes the context returned by [func@GLib.MainContext.get_thread_default], not the one returned by [func@GLib.MainContext.default], so it does not affect the context used by functions like [func@GLib.idle_add]. Normally you would call this function shortly after creating a new thread, passing it a [struct@GLib.MainContext] which will be run by a [struct@GLib.MainLoop] in that thread, to set a new default context for all async operations in that thread. In this case you may not need to ever call [method@GLib.MainContext.pop_thread_default], assuming you want the new [struct@GLib.MainContext] to be the default for the whole lifecycle of the thread. If you don’t have control over how the new thread was created (e.g. in the new thread isn’t newly created, or if the thread life cycle is managed by a #GThreadPool), it is always suggested to wrap the logic that needs to use the new [struct@GLib.MainContext] inside a [method@GLib.MainContext.push_thread_default] / [method@GLib.MainContext.pop_thread_default] pair, otherwise threads that are re-used will end up never explicitly releasing the [struct@GLib.MainContext] reference they hold. In some cases you may want to schedule a single operation in a non-default context, or temporarily use a non-default context in the main thread. In that case, you can wrap the call to the asynchronous operation inside a [method@GLib.MainContext.push_thread_default] / [method@GLib.MainContext.pop_thread_default] pair, but it is up to you to ensure that no other asynchronous operations accidentally get started while the non-default context is active. Beware that libraries that predate this function may not correctly handle being used from a thread with a thread-default context. For example, see `g_file_supports_thread_contexts()`. a main context, or `NULL` for the global-default main context Push @main_context as the new thread-default main context for the current thread, using [method@GLib.MainContext.push_thread_default], and return a new [alias@GLib.MainContextPusher]. Pop with g_main_context_pusher_free(). Using [method@GLib.MainContext.pop_thread_default] on @main_context while a [alias@GLib.MainContextPusher] exists for it can lead to undefined behaviour. Using two [alias@GLib.MainContextPusher]s in the same scope is not allowed, as it leads to an undefined pop order. This is intended to be used with g_autoptr(). Note that g_autoptr() is only available when using GCC or clang, so the following example will only work with those compilers: |[ typedef struct { ... GMainContext *context; ... } MyObject; static void my_object_do_stuff (MyObject *self) { g_autoptr(GMainContextPusher) pusher = g_main_context_pusher_new (self->context); // Code with main context as the thread default here if (cond) // No need to pop return; // Optionally early pop g_clear_pointer (&pusher, g_main_context_pusher_free); // Code with main context no longer the thread default here } ]| a #GMainContextPusher a main context to push Determines information necessary to poll this main loop. You should be careful to pass the resulting @fds array and its length @n_fds as-is when calling [method@GLib.MainContext.check], as this function relies on assumptions made when the array is filled. You must have successfully acquired the context with [method@GLib.MainContext.acquire] before you may call this function. the number of records actually stored in @fds, or, if more than @n_fds records need to be stored, the number of records that need to be stored a main context (if `NULL`, the global-default main context will be used) maximum priority source to check location to store timeout to be used in polling location to store [struct@GLib.PollFD] records that need to be polled length of @fds Increases the reference count on a [struct@GLib.MainContext] object by one. the @context that was passed in (since 2.6) a main context Releases ownership of a context previously acquired by this thread with [method@GLib.MainContext.acquire]. If the context was acquired multiple times, the ownership will be released only when [method@GLib.MainContext.release] is called as many times as it was acquired. You must have successfully acquired the context with [method@GLib.MainContext.acquire] before you may call this function. a main context (if `NULL`, the global-default main context will be used) Removes file descriptor from the set of file descriptors to be polled for a particular context. a main context (if `NULL`, the global-default main context will be used) a [struct@GLib.PollFD] descriptor previously added with [method@GLib.MainContext.add_poll] Sets the function to use to handle polling of file descriptors. It will be used instead of the [`poll()`](man:poll(2)) system call (or GLib’s replacement function, which is used where `poll()` isn’t available). This function could possibly be used to integrate the GLib event loop with an external event loop. a main context (if `NULL`, the global-default main context will be used) the function to call to poll all file descriptors Decreases the reference count on a [struct@GLib.MainContext] object by one. If the result is zero, free the context and free all associated memory. a main context Tries to become the owner of the specified context, and waits on @cond if another thread is the owner. This is the same as [method@GLib.MainContext.acquire], but if another thread is the owner, atomically drop @mutex and wait on @cond until that owner releases ownership or until @cond is signaled, then try again (once) to become the owner. Use [method@GLib.MainContext.is_owner] and separate locking instead. true if this thread is now the owner of @context, false otherwise a main context (if `NULL`, the global-default main context will be used) a condition variable a mutex, currently held Wake up @context if it’s currently blocking in [method@GLib.MainContext.iteration], causing it to stop blocking. The @context could be blocking waiting for a source to become ready. Otherwise, if @context is not currently blocking, this function causes the next invocation of [method@GLib.MainContext.iteration] to return without blocking. This API is useful for low-level control over [struct@GLib.MainContext]; for example, integrating it with main loop implementations such as [struct@GLib.MainLoop]. Another related use for this function is when implementing a main loop with a termination condition, computed from multiple threads: ```c #define NUM_TASKS 10 static gint tasks_remaining = NUM_TASKS; // (atomic) ... while (g_atomic_int_get (&tasks_remaining) != 0) g_main_context_iteration (NULL, TRUE); ``` Then in a thread: ```c perform_work (); if (g_atomic_int_dec_and_test (&tasks_remaining)) g_main_context_wakeup (NULL); ``` a main context (if `NULL`, the global-default main context will be used) Returns the global-default main context. This is the main context used for main loop functions when a main loop is not explicitly specified, and corresponds to the ‘main’ main loop. See also [func@GLib.MainContext.get_thread_default]. the global-default main context. Gets the thread-default main context for this thread. Asynchronous operations that want to be able to be run in contexts other than the default one should call this method or [func@GLib.MainContext.ref_thread_default] to get a [struct@GLib.MainContext] to add their [struct@GLib.Source]s to. (Note that even in single-threaded programs applications may sometimes want to temporarily push a non-default context, so it is not safe to assume that this will always return `NULL` if you are running in the default thread.) If you need to hold a reference on the context, use [func@GLib.MainContext.ref_thread_default] instead. the thread-default main context, or `NULL` if the thread-default context is the global-default main context Pop @pusher’s main context as the thread default main context. See g_main_context_pusher_new() for details. This will pop the [struct@GLib.MainContext] as the current thread-default main context, but will not call [method@GLib.MainContext.unref] on it. a #GMainContextPusher Gets a reference to the thread-default [struct@GLib.MainContext] for this thread This is the same as [func@GLib.MainContext.get_thread_default], but it also adds a reference to the returned main context with [method@GLib.MainContext.ref]. In addition, unlike [func@GLib.MainContext.get_thread_default], if the thread-default context is the global-default context, this will return that [struct@GLib.MainContext] (with a ref added to it) rather than returning `NULL`. the thread-default main context Flags to pass to [ctor@GLib.MainContext.new_with_flags] which affect the behaviour of a [struct@GLib.MainContext]. Default behaviour. Assume that polling for events will free the thread to process other jobs. That's useful if you're using `g_main_context_{prepare,query,check,dispatch}` to integrate GMainContext in other event loops. The `GMainLoop` struct is an opaque data type representing the main event loop of a GLib or GTK application. Creates a new [struct@GLib.MainLoop] structure. a new main loop a main context (if `NULL`, the global-default main context will be used). set to true to indicate that the loop is running. This is not very important since calling [method@GLib.MainLoop.run] will set this to true anyway. Returns the [struct@GLib.MainContext] of @loop. the [struct@GLib.MainContext] of @loop a main loop Checks to see if the main loop is currently being run via [method@GLib.MainLoop.run]. true if the main loop is currently being run, false otherwise a main loop Stops a [struct@GLib.MainLoop] from running. Any calls to [method@GLib.MainLoop.run] for the loop will return. Note that sources that have already been dispatched when [method@GLib.MainLoop.quit] is called will still be executed. a main loop Increases the reference count on a [struct@GLib.MainLoop] object by one. @loop a main loop Runs a main loop until [method@GLib.MainLoop.quit] is called on the loop. If this is called from the thread of the loop’s [struct@GLib.MainContext], it will process events from the loop, otherwise it will simply wait. a main loop Decreases the reference count on a [struct@GLib.MainLoop] object by one. If the result is zero, the loop and all associated memory are freed. a main loop The #GMappedFile represents a file mapping created with g_mapped_file_new(). It has only private members and should not be accessed directly. Maps a file into memory. On UNIX, this is using the mmap() function. If @writable is %TRUE, the mapped buffer may be modified, otherwise it is an error to modify the mapped buffer. Modifications to the buffer are not visible to other processes mapping the same file, and are not written back to the file. Note that modifications of the underlying file might affect the contents of the #GMappedFile. Therefore, mapping should only be used if the file will not be modified, or if all modifications of the file are done atomically (e.g. using g_file_set_contents()). If @filename is the name of an empty, regular file, the function will successfully return an empty #GMappedFile. In other cases of size 0 (e.g. device files such as /dev/null), @error will be set to the #GFileError value %G_FILE_ERROR_INVAL. a newly allocated #GMappedFile which must be unref'd with g_mapped_file_unref(), or %NULL if the mapping failed. The path of the file to load, in the GLib filename encoding whether the mapping should be writable Maps a file into memory. On UNIX, this is using the mmap() function. If @writable is %TRUE, the mapped buffer may be modified, otherwise it is an error to modify the mapped buffer. Modifications to the buffer are not visible to other processes mapping the same file, and are not written back to the file. Note that modifications of the underlying file might affect the contents of the #GMappedFile. Therefore, mapping should only be used if the file will not be modified, or if all modifications of the file are done atomically (e.g. using g_file_set_contents()). a newly allocated #GMappedFile which must be unref'd with g_mapped_file_unref(), or %NULL if the mapping failed. The file descriptor of the file to load whether the mapping should be writable This call existed before #GMappedFile had refcounting and is currently exactly the same as g_mapped_file_unref(). Use g_mapped_file_unref() instead. a #GMappedFile Creates a new #GBytes which references the data mapped from @file. The mapped contents of the file must not be modified after creating this bytes object, because a #GBytes should be immutable. A newly allocated #GBytes referencing data from @file a #GMappedFile Returns the contents of a #GMappedFile. Note that the contents may not be zero-terminated, even if the #GMappedFile is backed by a text file. If the file is empty then %NULL is returned. the contents of @file, or %NULL. a #GMappedFile Returns the length of the contents of a #GMappedFile. the length of the contents of @file. a #GMappedFile Increments the reference count of @file by one. It is safe to call this function from any thread. the passed in #GMappedFile. a #GMappedFile Decrements the reference count of @file by one. If the reference count drops to 0, unmaps the buffer of @file and frees it. It is safe to call this function from any thread. Since 2.22 a #GMappedFile A mixed enumerated type and flags field. You must specify one type (string, strdup, boolean, tristate). Additionally, you may optionally bitwise OR the type with the flag %G_MARKUP_COLLECT_OPTIONAL. It is likely that this enum will be extended in the future to support other types. used to terminate the list of attributes to collect collect the string pointer directly from the attribute_values[] array. Expects a parameter of type (const char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the attribute isn't present then the pointer will be set to %NULL as with %G_MARKUP_COLLECT_STRING, but expects a parameter of type (char **) and g_strdup()s the returned pointer. The pointer must be freed with g_free() expects a parameter of type (`gboolean *`) and parses the attribute value as a boolean. Sets %FALSE if the attribute isn't present. Valid boolean values consist of (case-insensitive) "false", "f", "no", "n", "0" and "true", "t", "yes", "y", "1" as with %G_MARKUP_COLLECT_BOOLEAN, but in the case of a missing attribute a value is set that compares equal to neither %FALSE nor %TRUE %G_MARKUP_COLLECT_OPTIONAL is implied can be bitwise ORed with the other fields. If present, allows the attribute not to appear. A default value is set depending on what value type is used Error codes returned by markup parsing. text being parsed was not valid UTF-8 document contained nothing, or only whitespace document was ill-formed error should be set by #GMarkupParser functions; element wasn't known error should be set by #GMarkupParser functions; attribute wasn't known error should be set by #GMarkupParser functions; content was invalid error should be set by #GMarkupParser functions; a required attribute was missing A parse context is used to parse a stream of bytes that you expect to contain marked-up text. See g_markup_parse_context_new(), #GMarkupParser, and so on for more details. Creates a new parse context. A parse context is used to parse marked-up documents. You can feed any number of documents into a context, as long as no errors occur; once an error occurs, the parse context can't continue to parse text (you have to free it and create a new parse context). a new #GMarkupParseContext a #GMarkupParser one or more #GMarkupParseFlags user data to pass to #GMarkupParser functions user data destroy notifier called when the parse context is freed Signals to the #GMarkupParseContext that all data has been fed into the parse context with g_markup_parse_context_parse(). This function reports an error if the document isn't complete, for example if elements are still open. %TRUE on success, %FALSE if an error was set a #GMarkupParseContext Frees a #GMarkupParseContext. This function can't be called from inside one of the #GMarkupParser functions or while a subparser is pushed. a #GMarkupParseContext Retrieves the name of the currently open element. If called from the start_element or end_element handlers this will give the element_name as passed to those functions. For the parent elements, see g_markup_parse_context_get_element_stack(). the name of the currently open element, or %NULL a #GMarkupParseContext Retrieves the element stack from the internal state of the parser. The returned #GSList is a list of strings where the first item is the currently open tag (as would be returned by g_markup_parse_context_get_element()) and the next item is its immediate parent. This function is intended to be used in the start_element and end_element handlers where g_markup_parse_context_get_element() would merely return the name of the element that is being processed. the element stack, which must not be modified a #GMarkupParseContext Retrieves the current offset from the beginning of the document, in bytes. The information is meant to accompany the values returned by [method@GLib.MarkupParseContext.get_position], and comes with the same accuracy guarantees. the offset a #GMarkupParseContext Retrieves the current line number and the number of the character on that line. Intended for use in error messages; there are no strict semantics for what constitutes the "current" line number other than "the best number we could come up with for error messages." a #GMarkupParseContext return location for a line number, or %NULL return location for a char-on-line number, or %NULL Retrieves the start position of the current start or end tag. This function can be used in the `start_element` or `end_element` callbacks to obtain location information for error reporting. Note that @line_number and @char_number are intended for human readable error messages and are therefore 1-based and in Unicode characters. @offset on the other hand is meant for programmatic use, and thus is 0-based and in bytes. The information is meant to accompany the values returned by [method@GLib.MarkupParseContext.get_position], and comes with the same accuracy guarantees. a #GMarkupParseContext return location for the line number return location for the character number return location for offset from the beginning of the document Returns the user_data associated with @context. This will either be the user_data that was provided to g_markup_parse_context_new() or to the most recent call of g_markup_parse_context_push(). the provided user_data. The returned data belongs to the markup context and will be freed when g_markup_parse_context_free() is called. a #GMarkupParseContext Feed some data to the #GMarkupParseContext. The data need not be valid UTF-8; an error will be signaled if it's invalid. The data need not be an entire document; you can feed a document into the parser incrementally, via multiple calls to this function. Typically, as you receive data from a network connection or file, you feed each received chunk of data into this function, aborting the process if an error occurs. Once an error is reported, no further data may be fed to the #GMarkupParseContext; all errors are fatal. %FALSE if an error occurred, %TRUE on success a #GMarkupParseContext chunk of text to parse length of @text in bytes Completes the process of a temporary sub-parser redirection. This function exists to collect the user_data allocated by a matching call to g_markup_parse_context_push(). It must be called in the end_element handler corresponding to the start_element handler during which g_markup_parse_context_push() was called. You must not call this function from the error callback -- the @user_data is provided directly to the callback in that case. This function is not intended to be directly called by users interested in invoking subparsers. Instead, it is intended to be used by the subparsers themselves to implement a higher-level interface. the user data passed to g_markup_parse_context_push() a #GMarkupParseContext Temporarily redirects markup data to a sub-parser. This function may only be called from the start_element handler of a #GMarkupParser. It must be matched with a corresponding call to g_markup_parse_context_pop() in the matching end_element handler (except in the case that the parser aborts due to an error). All tags, text and other data between the matching tags is redirected to the subparser given by @parser. @user_data is used as the user_data for that parser. @user_data is also passed to the error callback in the event that an error occurs. This includes errors that occur in subparsers of the subparser. The end tag matching the start tag for which this call was made is handled by the previous parser (which is given its own user_data) which is why g_markup_parse_context_pop() is provided to allow "one last access" to the @user_data provided to this function. In the case of error, the @user_data provided here is passed directly to the error callback of the subparser and g_markup_parse_context_pop() should not be called. In either case, if @user_data was allocated then it ought to be freed from both of these locations. This function is not intended to be directly called by users interested in invoking subparsers. Instead, it is intended to be used by the subparsers themselves to implement a higher-level interface. As an example, see the following implementation of a simple parser that counts the number of tags encountered. |[<!-- language="C" --> typedef struct { gint tag_count; } CounterData; static void counter_start_element (GMarkupParseContext *context, const gchar *element_name, const gchar **attribute_names, const gchar **attribute_values, gpointer user_data, GError **error) { CounterData *data = user_data; data->tag_count++; } static void counter_error (GMarkupParseContext *context, GError *error, gpointer user_data) { CounterData *data = user_data; g_slice_free (CounterData, data); } static GMarkupParser counter_subparser = { counter_start_element, NULL, NULL, NULL, counter_error }; ]| In order to allow this parser to be easily used as a subparser, the following interface is provided: |[<!-- language="C" --> void start_counting (GMarkupParseContext *context) { CounterData *data = g_slice_new (CounterData); data->tag_count = 0; g_markup_parse_context_push (context, &counter_subparser, data); } gint end_counting (GMarkupParseContext *context) { CounterData *data = g_markup_parse_context_pop (context); int result; result = data->tag_count; g_slice_free (CounterData, data); return result; } ]| The subparser would then be used as follows: |[<!-- language="C" --> static void start_element (context, element_name, ...) { if (strcmp (element_name, "count-these") == 0) start_counting (context); // else, handle other tags... } static void end_element (context, element_name, ...) { if (strcmp (element_name, "count-these") == 0) g_print ("Counted %d tags\n", end_counting (context)); // else, handle other tags... } ]| a #GMarkupParseContext a #GMarkupParser user data to pass to #GMarkupParser functions Increases the reference count of @context. the same @context a #GMarkupParseContext Decreases the reference count of @context. When its reference count drops to 0, it is freed. a #GMarkupParseContext Flags that affect the behaviour of the parser. No special behaviour. Since: 2.74 flag you should not use When this flag is set, CDATA marked sections are not passed literally to the @passthrough function of the parser. Instead, the content of the section (without the `<![CDATA[` and `]]>`) is passed to the @text function. This flag was added in GLib 2.12 Normally errors caught by GMarkup itself have line/column information prefixed to them to let the caller know the location of the error. When this flag is set the location information is also prefixed to errors generated by the #GMarkupParser implementation functions Ignore (don't report) qualified attributes and tags, along with their contents. A qualified attribute or tag is one that contains ':' in its name (ie: is in another namespace). Since: 2.40. Any of the fields in #GMarkupParser can be %NULL, in which case they will be ignored. Except for the @error function, any of these callbacks can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT, %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT errors are intended to be set from these callbacks. If you set an error from a callback, g_markup_parse_context_parse() will report that error back to its caller. Refer to the [GMarkup](../glib/markup.html) documentation to understand the scope and limitations of `GMarkupParser`. In particular, it is not a full XML parser and it must not be used to process untrusted data. Callback to invoke when the opening tag of an element is seen. The callback's @attribute_names and @attribute_values parameters are %NULL-terminated. Callback to invoke when the closing tag of an element is seen. Note that this is also called for empty tags like `<empty/>`. Callback to invoke when some text is seen (text is always inside an element). Note that the text of an element may be spread over multiple calls of this function. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is set, this function is also called for the content of CDATA marked sections. Callback to invoke for comments, processing instructions and doctype declarations; if you're re-writing the parsed document, write the passthrough text back out in the same position. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also called for CDATA marked sections. Callback to invoke when an error occurs. A GMatchInfo is an opaque struct used to return information about matches. Returns a new string containing the text in @string_to_expand with references and escape sequences expanded. References refer to the last match done with @string against @regex and have the same syntax used by g_regex_replace(). The @string_to_expand must be UTF-8 encoded even if %G_REGEX_RAW was passed to g_regex_new(). The backreferences are extracted from the string passed to the match function, so you cannot call this function after freeing the string. @match_info may be %NULL in which case @string_to_expand must not contain references. For instance "foo\n" does not refer to an actual pattern and '\n' merely will be replaced with \n character, while to expand "\0" (whole match) one needs the result of a match. Use g_regex_check_replacement() to find out whether @string_to_expand contains references. the expanded string, or %NULL if an error occurred a #GMatchInfo or %NULL the string to expand Retrieves the text matching the @match_num'th capturing parentheses. 0 is the full text of the match, 1 is the first paren set, 2 the second, and so on. If @match_num is a valid sub pattern but it didn't match anything (e.g. sub pattern 1, matching "b" against "(a)?b") then an empty string is returned. If the match was obtained using the DFA algorithm, that is using g_regex_match_all() or g_regex_match_all_full(), the retrieved string is not that of a set of parentheses but that of a matched substring. Substrings are matched in reverse order of length, so 0 is the longest match. The string is fetched from the string passed to the match function, so you cannot call this function after freeing the string. The matched substring, or %NULL if an error occurred. You have to free the string yourself #GMatchInfo structure number of the sub expression Bundles up pointers to each of the matching substrings from a match and stores them in an array of gchar pointers. The first element in the returned array is the match number 0, i.e. the entire matched text. If a sub pattern didn't match anything (e.g. sub pattern 1, matching "b" against "(a)?b") then an empty string is inserted. If the last match was obtained using the DFA algorithm, that is using g_regex_match_all() or g_regex_match_all_full(), the retrieved strings are not that matched by sets of parentheses but that of the matched substring. Substrings are matched in reverse order of length, so the first one is the longest match. The strings are fetched from the string passed to the match function, so you cannot call this function after freeing the string. a %NULL-terminated array of gchar * pointers. It must be freed using g_strfreev(). If the previous match failed %NULL is returned a #GMatchInfo structure Retrieves the text matching the capturing parentheses named @name. If @name is a valid sub pattern name but it didn't match anything (e.g. sub pattern `"X"`, matching `"b"` against `"(?P<X>a)?b"`) then an empty string is returned. The string is fetched from the string passed to the match function, so you cannot call this function after freeing the string. The matched substring, or %NULL if an error occurred. You have to free the string yourself #GMatchInfo structure name of the subexpression Retrieves the position in bytes of the capturing parentheses named @name. If @name is a valid sub pattern name but it didn't match anything (e.g. sub pattern `"X"`, matching `"b"` against `"(?P<X>a)?b"`) then @start_pos and @end_pos are set to -1 and %TRUE is returned. As @end_pos is set to the byte after the final byte of the match (on success), the length of the match can be calculated as `end_pos - start_pos`. %TRUE if the position was fetched, %FALSE otherwise. If the position cannot be fetched, @start_pos and @end_pos are left unchanged. #GMatchInfo structure name of the subexpression pointer to location where to store the start position, or %NULL pointer to location where to store the end position (the byte after the final byte of the match), or %NULL Returns the start and end positions (in bytes) of a successfully matching capture parenthesis. Valid values for @match_num are `0` for the full text of the match, `1` for the first paren set, `2` for the second, and so on. As @end_pos is set to the byte after the final byte of the match (on success), the length of the match can be calculated as `end_pos - start_pos`. As a best practice, initialize @start_pos and @end_pos to identifiable values, such as `G_MAXINT`, so that you can test if `g_match_info_fetch_pos()` actually changed the value for a given capture parenthesis. The parameter @match_num corresponds to a matched capture parenthesis. The actual value you use for @match_num depends on the method used to generate @match_info. The following sections describe those methods. ## Methods Using Non-deterministic Finite Automata Matching The methods [method@GLib.Regex.match] and [method@GLib.Regex.match_full] return a [struct@GLib.MatchInfo] using traditional (greedy) pattern matching, also known as [Non-deterministic Finite Automaton](https://en.wikipedia.org/wiki/Nondeterministic_finite_automaton) (NFA) matching. You pass the returned `GMatchInfo` from these methods to `g_match_info_fetch_pos()` to determine the start and end positions of capture parentheses. The values for @match_num correspond to the capture parentheses in order, with `0` corresponding to the entire matched string. @match_num can refer to a capture parenthesis with no match. For example, the string `b` matches against the pattern `(a)?b`, but the capture parenthesis `(a)` has no match. In this case, `g_match_info_fetch_pos()` returns true and sets @start_pos and @end_pos to `-1` when called with `match_num` as `1` (for `(a)`). For an expanded example, a regex pattern is `(a)?(.*?)the (.*)`, and a candidate string is `glib regexes are the best`. In this scenario there are four capture parentheses numbered 0–3: an implicit one for the entire string, and three explicitly declared in the regex pattern. Given this example, the following table describes the return values from `g_match_info_fetch_pos()` for various values of @match_num. `match_num` | Contents | Return value | Returned `start_pos` | Returned `end_pos` ----------- | -------- | ------------ | -------------------- | ------------------ 0 | Matches entire string | True | 0 | 25 1 | Does not match first character | True | -1 | -1 2 | All text before `the ` | True | 0 | 17 3 | All text after `the ` | True | 21 | 25 4 | Capture paren out of range | False | Unchanged | Unchanged The following code sample and output implements this example. ``` { .c } #include <glib.h> int main (int argc, char *argv[]) { g_autoptr(GError) local_error = NULL; const char *regex_pattern = "(a)?(.*?)the (.*)"; const char *test_string = "glib regexes are the best"; g_autoptr(GRegex) regex = NULL; regex = g_regex_new (regex_pattern, G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, &local_error); if (regex == NULL) { g_printerr ("Error creating regex: %s\n", local_error->message); return 1; } g_autoptr(GMatchInfo) match_info = NULL; g_regex_match (regex, test_string, G_REGEX_MATCH_DEFAULT, &match_info); int n_matched_strings = g_match_info_get_match_count (match_info); // Print header line g_print ("match_num Contents Return value returned start_pos returned end_pos\n"); // Iterate over each capture paren, including one that is out of range as a demonstration. for (int match_num = 0; match_num <= n_matched_strings; match_num++) { gboolean found_match; g_autofree char *paren_string = NULL; int start_pos = G_MAXINT; int end_pos = G_MAXINT; found_match = g_match_info_fetch_pos (match_info, match_num, &start_pos, &end_pos); // If no match, display N/A as the found string. if (start_pos == G_MAXINT || start_pos == -1) paren_string = g_strdup ("N/A"); else paren_string = g_strndup (test_string + start_pos, end_pos - start_pos); g_print ("%-9d %-25s %-12d %-18d %d\n", match_num, paren_string, found_match, start_pos, end_pos); } return 0; } ``` ``` match_num Contents Return value returned start_pos returned end_pos 0 glib regexes are the best 1 0 25 1 N/A 1 -1 -1 2 glib regexes are 1 0 17 3 best 1 21 25 4 N/A 0 2147483647 2147483647 ``` ## Methods Using Deterministic Finite Automata Matching The methods [method@GLib.Regex.match_all] and [method@GLib.Regex.match_all_full] return a `GMatchInfo` using [Deterministic Finite Automaton](https://en.wikipedia.org/wiki/Deterministic_finite_automaton) (DFA) pattern matching. This algorithm detects overlapping matches. You pass the returned `GMatchInfo` from these methods to `g_match_info_fetch_pos()` to determine the start and end positions of each overlapping match. Use the method [method@GLib.MatchInfo.get_match_count] to determine the number of overlapping matches. For example, a regex pattern is `<.*>`, and a candidate string is `<a> <b> <c>`. In this scenario there are three implicit capture parentheses: one for the entire string, one for `<a> <b>`, and one for `<a>`. Given this example, the following table describes the return values from `g_match_info_fetch_pos()` for various values of @match_num. `match_num` | Contents | Return value | Returned `start_pos` | Returned `end_pos` ----------- | -------- | ------------ | -------------------- | ------------------ 0 | Matches entire string | True | 0 | 11 1 | Matches `<a> <b>` | True | 0 | 7 2 | Matches `<a>` | True | 0 | 3 3 | Capture paren out of range | False | Unchanged | Unchanged The following code sample and output implements this example. ``` { .c } #include <glib.h> int main (int argc, char *argv[]) { g_autoptr(GError) local_error = NULL; const char *regex_pattern = "<.*>"; const char *test_string = "<a> <b> <c>"; g_autoptr(GRegex) regex = NULL; regex = g_regex_new (regex_pattern, G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, &local_error); if (regex == NULL) { g_printerr ("Error creating regex: %s\n", local_error->message); return -1; } g_autoptr(GMatchInfo) match_info = NULL; g_regex_match_all (regex, test_string, G_REGEX_MATCH_DEFAULT, &match_info); int n_matched_strings = g_match_info_get_match_count (match_info); // Print header line g_print ("match_num Contents Return value returned start_pos returned end_pos\n"); // Iterate over each capture paren, including one that is out of range as a demonstration. for (int match_num = 0; match_num <= n_matched_strings; match_num++) { gboolean found_match; g_autofree char *paren_string = NULL; int start_pos = G_MAXINT; int end_pos = G_MAXINT; found_match = g_match_info_fetch_pos (match_info, match_num, &start_pos, &end_pos); // If no match, display N/A as the found string. if (start_pos == G_MAXINT || start_pos == -1) paren_string = g_strdup ("N/A"); else paren_string = g_strndup (test_string + start_pos, end_pos - start_pos); g_print ("%-9d %-25s %-12d %-18d %d\n", match_num, paren_string, found_match, start_pos, end_pos); } return 0; } ``` ``` match_num Contents Return value returned start_pos returned end_pos 0 <a> <b> <c> 1 0 11 1 <a> <b> 1 0 7 2 <a> 1 0 3 3 N/A 0 2147483647 2147483647 ``` True if @match_num is within range, false otherwise. If the capture paren has a match, @start_pos and @end_pos contain the start and end positions (in bytes) of the matching substring. If the capture paren has no match, @start_pos and @end_pos are `-1`. If @match_num is out of range, @start_pos and @end_pos are left unchanged. #GMatchInfo structure number of the capture parenthesis pointer to location where to store the start position, or %NULL pointer to location where to store the end position (the byte after the final byte of the match), or %NULL If @match_info is not %NULL, calls g_match_info_unref(); otherwise does nothing. a #GMatchInfo, or %NULL Retrieves the number of matched substrings (including substring 0, that is the whole matched text), so 1 is returned if the pattern has no substrings in it and 0 is returned if the match failed. If the last match was obtained using the DFA algorithm, that is using g_regex_match_all() or g_regex_match_all_full(), the retrieved count is not that of the number of capturing parentheses but that of the number of matched substrings. Number of matched substrings, or -1 if an error occurred a #GMatchInfo structure Returns #GRegex object used in @match_info. It belongs to Glib and must not be freed. Use g_regex_ref() if you need to keep it after you free @match_info object. #GRegex object used in @match_info a #GMatchInfo Returns the string searched with @match_info. This is the string passed to g_regex_match() or g_regex_replace() so you may not free it before calling this function. the string searched with @match_info a #GMatchInfo Usually if the string passed to g_regex_match*() matches as far as it goes, but is too short to match the entire pattern, %FALSE is returned. There are circumstances where it might be helpful to distinguish this case from other cases in which there is no match. Consider, for example, an application where a human is required to type in data for a field with specific formatting requirements. An example might be a date in the form ddmmmyy, defined by the pattern "^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$". If the application sees the user’s keystrokes one by one, and can check that what has been typed so far is potentially valid, it is able to raise an error as soon as a mistake is made. GRegex supports the concept of partial matching by means of the %G_REGEX_MATCH_PARTIAL_SOFT and %G_REGEX_MATCH_PARTIAL_HARD flags. When they are used, the return code for g_regex_match() or g_regex_match_full() is, as usual, %TRUE for a complete match, %FALSE otherwise. But, when these functions return %FALSE, you can check if the match was partial calling g_match_info_is_partial_match(). The difference between %G_REGEX_MATCH_PARTIAL_SOFT and %G_REGEX_MATCH_PARTIAL_HARD is that when a partial match is encountered with %G_REGEX_MATCH_PARTIAL_SOFT, matching continues to search for a possible complete match, while with %G_REGEX_MATCH_PARTIAL_HARD matching stops at the partial match. When both %G_REGEX_MATCH_PARTIAL_SOFT and %G_REGEX_MATCH_PARTIAL_HARD are set, the latter takes precedence. There were formerly some restrictions on the pattern for partial matching. The restrictions no longer apply. See pcrepartial(3) for more information on partial matching. %TRUE if the match was partial, %FALSE otherwise a #GMatchInfo structure Returns whether the previous match operation succeeded. %TRUE if the previous match operation succeeded, %FALSE otherwise a #GMatchInfo structure Scans for the next match using the same parameters of the previous call to g_regex_match_full() or g_regex_match() that returned @match_info. The match is done on the string passed to the match function, so you cannot free it before calling this function. %TRUE is the string matched, %FALSE otherwise a #GMatchInfo structure Increases reference count of @match_info by 1. @match_info a #GMatchInfo Decreases reference count of @match_info by 1. When reference count drops to zero, it frees all the memory associated with the match_info structure. a #GMatchInfo A set of functions used to perform memory allocation. The same #GMemVTable must be used for all allocations in the same program; a call to g_mem_set_vtable(), if it exists, should be prior to any use of GLib. This functions related to this has been deprecated in 2.46, and no longer work. function to use for allocating memory. function to use for reallocating memory. function to use to free memory. function to use for allocating zero-filled memory. function to use for allocating memory without a default error handler. function to use for reallocating memory without a default error handler. The #GMutex struct is an opaque data structure to represent a mutex (mutual exclusion). It can be used to protect data against shared access. Take for example the following function: |[<!-- language="C" --> int give_me_next_number (void) { static int current_number = 0; // now do a very complicated calculation to calculate the new // number, this might for example be a random number generator current_number = calc_next_number (current_number); return current_number; } ]| It is easy to see that this won't work in a multi-threaded application. There current_number must be protected against shared access. A #GMutex can be used as a solution to this problem: |[<!-- language="C" --> int give_me_next_number (void) { static GMutex mutex; static int current_number = 0; int ret_val; g_mutex_lock (&mutex); ret_val = current_number = calc_next_number (current_number); g_mutex_unlock (&mutex); return ret_val; } ]| Notice that the #GMutex is not initialised to any particular value. Its placement in static storage ensures that it will be initialised to all-zeros, which is appropriate. If a #GMutex is placed in other contexts (eg: embedded in a struct) then it must be explicitly initialised using g_mutex_init(). A #GMutex should only be accessed via g_mutex_ functions. Frees the resources allocated to a mutex with g_mutex_init(). This function should not be used with a #GMutex that has been statically allocated. Calling g_mutex_clear() on a locked mutex leads to undefined behaviour. an initialized #GMutex Destroys a @mutex that has been created with g_mutex_new(). Calling g_mutex_free() on a locked mutex may result in undefined behaviour. GMutex can now be statically allocated, or embedded in structures and initialised with g_mutex_init(). a #GMutex Initializes a #GMutex so that it can be used. This function is useful to initialize a mutex that has been allocated on the stack, or as part of a larger structure. It is not necessary to initialize a mutex that has been statically allocated. |[<!-- language="C" --> typedef struct { GMutex m; ... } Blob; Blob *b; b = g_new (Blob, 1); g_mutex_init (&b->m); ]| To undo the effect of g_mutex_init() when a mutex is no longer needed, use g_mutex_clear(). Calling g_mutex_init() on an already initialized #GMutex leads to undefined behaviour. an uninitialized #GMutex Locks @mutex. If @mutex is already locked by another thread, the current thread will block until @mutex is unlocked by the other thread. #GMutex is neither guaranteed to be recursive nor to be non-recursive. As such, calling g_mutex_lock() on a #GMutex that has already been locked by the same thread results in undefined behaviour (including but not limited to deadlocks). a #GMutex Tries to lock @mutex. If @mutex is already locked by another thread, it immediately returns %FALSE. Otherwise it locks @mutex and returns %TRUE. #GMutex is neither guaranteed to be recursive nor to be non-recursive. As such, calling g_mutex_lock() on a #GMutex that has already been locked by the same thread results in undefined behaviour (including but not limited to deadlocks or arbitrary return values). %TRUE if @mutex could be locked a #GMutex Unlocks @mutex. If another thread is blocked in a g_mutex_lock() call for @mutex, it will become unblocked and can lock @mutex itself. Calling g_mutex_unlock() on a mutex that is not locked by the current thread leads to undefined behaviour. a #GMutex Allocates and initializes a new #GMutex. GMutex can now be statically allocated, or embedded in structures and initialised with g_mutex_init(). a newly allocated #GMutex. Use g_mutex_free() to free Returns %TRUE if a #GNode is a leaf node. a #GNode Returns %TRUE if a #GNode is the root of a tree. a #GNode Number of nanoseconds in one second (1 billion). This macro is provided for code readability. Determines the number of elements in an array. The array must be declared so the compiler knows its size at compile-time; this macro will not work on an array allocated on the heap, only static arrays or arrays on the stack. the array The #GNode struct represents one node in a [n-ary tree](data-structures.html#n-ary-trees). contains the actual data of the node. points to the node's next sibling (a sibling is another #GNode with the same parent). points to the node's previous sibling. points to the parent of the #GNode, or is %NULL if the #GNode is the root of the tree. points to the first child of the #GNode. The other children are accessed by using the @next pointer of each child. Gets the position of the first child of a #GNode which contains the given data. the index of the child of @node which contains @data, or -1 if the data is not found a #GNode the data to find Gets the position of a #GNode with respect to its siblings. @child must be a child of @node. The first child is numbered 0, the second 1, and so on. the position of @child with respect to its siblings a #GNode a child of @node Calls a function for each of the children of a #GNode. Note that it doesn't descend beneath the child nodes. @func must not do anything that would modify the structure of the tree. a #GNode which types of children are to be visited, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES the function to call for each visited node user data to pass to the function Recursively copies a #GNode (but does not deep-copy the data inside the nodes, see g_node_copy_deep() if you need that). a new #GNode containing the same data pointers a #GNode Recursively copies a #GNode and its data. a new #GNode containing copies of the data in @node. a #GNode the function which is called to copy the data inside each node, or %NULL to use the original data. data to pass to @copy_func Gets the depth of a #GNode. If @node is %NULL the depth is 0. The root node has a depth of 1. For the children of the root node the depth is 2. And so on. the depth of the #GNode a #GNode Removes @root and its children from the tree, freeing any memory allocated. the root of the tree/subtree to destroy Finds a #GNode in a tree. the found #GNode, or %NULL if the data is not found the root #GNode of the tree to search the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER which types of children are to be searched, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES the data to find Finds the first child of a #GNode with the given data. the found child #GNode, or %NULL if the data is not found a #GNode which types of children are to be searched, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES the data to find Gets the first sibling of a #GNode. This could possibly be the node itself. the first sibling of @node a #GNode Gets the root of a tree. the root of the tree a #GNode Inserts a #GNode beneath the parent at the given position. the inserted #GNode the #GNode to place @node under the position to place @node at, with respect to its siblings If position is -1, @node is inserted as the last child of @parent the #GNode to insert Inserts a #GNode beneath the parent after the given sibling. the inserted #GNode the #GNode to place @node under the sibling #GNode to place @node after. If sibling is %NULL, the node is inserted as the first child of @parent. the #GNode to insert Inserts a #GNode beneath the parent before the given sibling. the inserted #GNode the #GNode to place @node under the sibling #GNode to place @node before. If sibling is %NULL, the node is inserted as the last child of @parent. the #GNode to insert Returns %TRUE if @node is an ancestor of @descendant. This is true if node is the parent of @descendant, or if node is the grandparent of @descendant etc. %TRUE if @node is an ancestor of @descendant a #GNode a #GNode Gets the last child of a #GNode. the last child of @node, or %NULL if @node has no children a #GNode (must not be %NULL) Gets the last sibling of a #GNode. This could possibly be the node itself. the last sibling of @node a #GNode Gets the maximum height of all branches beneath a #GNode. This is the maximum distance from the #GNode to all leaf nodes. If @root is %NULL, 0 is returned. If @root has no children, 1 is returned. If @root has children, 2 is returned. And so on. the maximum height of the tree beneath @root a #GNode Gets the number of children of a #GNode. the number of children of @node a #GNode Gets the number of nodes in a tree. the number of nodes in the tree a #GNode which types of children are to be counted, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES Gets a child of a #GNode, using the given index. The first child is at index 0. If the index is too big, %NULL is returned. the child of @node at index @n a #GNode the index of the desired child Inserts a #GNode as the first child of the given parent. the inserted #GNode the #GNode to place the new #GNode under the #GNode to insert Reverses the order of the children of a #GNode. (It doesn't change the order of the grandchildren.) a #GNode. Traverses a tree starting at the given root #GNode. It calls the given function for each node visited. The traversal can be halted at any point by returning %TRUE from @func. @func must not do anything that would modify the structure of the tree. the root #GNode of the tree to traverse the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER. which types of children are to be visited, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES the maximum depth of the traversal. Nodes below this depth will not be visited. If max_depth is -1 all nodes in the tree are visited. If depth is 1, only the root is visited. If depth is 2, the root and its children are visited. And so on. the function to call for each visited #GNode user data to pass to the function Unlinks a #GNode from a tree, resulting in two separate trees. the #GNode to unlink, which becomes the root of a new tree Creates a new #GNode containing the given data. Used to create the first node in a tree. a new #GNode the data of the new node Specifies the type of function passed to g_node_children_foreach(). The function is called with each child node, together with the user data passed to g_node_children_foreach(). a #GNode. user data passed to g_node_children_foreach(). Specifies the type of function passed to g_node_traverse(). The function is called with each of the nodes visited, together with the user data passed to g_node_traverse(). If the function returns %TRUE, then the traversal is stopped. %TRUE to stop the traversal. a #GNode. user data passed to g_node_traverse(). Defines how a Unicode string is transformed in a canonical form, standardizing such issues as whether a character with an accent is represented as a base character and combining accent or as a single precomposed character. Unicode strings should generally be normalized before comparing them. standardize differences that do not affect the text content, such as the above-mentioned accent representation another name for %G_NORMALIZE_DEFAULT like %G_NORMALIZE_DEFAULT, but with composed forms rather than a maximally decomposed form another name for %G_NORMALIZE_DEFAULT_COMPOSE beyond %G_NORMALIZE_DEFAULT also standardize the "compatibility" characters in Unicode, such as SUPERSCRIPT THREE to the standard forms (in this case DIGIT THREE). Formatting information may be lost but for most text operations such characters should be considered the same another name for %G_NORMALIZE_ALL like %G_NORMALIZE_ALL, but with composed forms rather than a maximally decomposed form another name for %G_NORMALIZE_ALL_COMPOSE Error codes returned by functions converting a string to a number. string was not a valid number string was a number, but out of bounds If a long option in the main group has this name, it is not treated as a regular option. Instead it collects all non-option arguments which would otherwise be left in `argv`. The option must be of type %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY. Using %G_OPTION_REMAINING instead of simply scanning `argv` for leftover arguments has the advantage that GOption takes care of necessary encoding conversions for strings or filenames. A #GOnce struct controls a one-time initialization function. Any one-time initialization function must have its own unique #GOnce struct. the status of the #GOnce the value returned by the call to the function, if @status is %G_ONCE_STATUS_READY Function to be called when starting a critical initialization section. The argument @location must point to a static 0-initialized variable that will be set to a value other than 0 at the end of the initialization section. In combination with g_once_init_leave() and the unique address @value_location, it can be ensured that an initialization section will be executed only once during a program's life time, and that concurrent threads are blocked until initialization completed. To be used in constructs like this: |[<!-- language="C" --> static gsize initialization_value = 0; if (g_once_init_enter (&initialization_value)) { gsize setup_value = 42; // initialization code here g_once_init_leave (&initialization_value, setup_value); } // use initialization_value here ]| While @location has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. %TRUE if the initialization section should be entered, %FALSE and blocks otherwise location of a static initializable variable containing 0 This functions behaves in the same way as g_once_init_enter(), but can can be used to initialize pointers (or #guintptr) instead of #gsize. |[<!-- language="C" --> static MyStruct *interesting_struct = NULL; if (g_once_init_enter_pointer (&interesting_struct)) { MyStruct *setup_value = allocate_my_struct (); // initialization code here g_once_init_leave_pointer (&interesting_struct, g_steal_pointer (&setup_value)); } // use interesting_struct here ]| %TRUE if the initialization section should be entered, %FALSE and blocks otherwise location of a static initializable variable containing `NULL` Counterpart to g_once_init_enter(). Expects a location of a static 0-initialized initialization variable, and an initialization value other than 0. Sets the variable to the initialization value, and releases concurrent threads blocking in g_once_init_enter() on this initialization variable. While @location has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. location of a static initializable variable containing 0 new non-0 value for `*value_location` Counterpart to g_once_init_enter_pointer(). Expects a location of a static `NULL`-initialized initialization variable, and an initialization value other than `NULL`. Sets the variable to the initialization value, and releases concurrent threads blocking in g_once_init_enter_pointer() on this initialization variable. This functions behaves in the same way as g_once_init_leave(), but can be used to initialize pointers (or #guintptr) instead of #gsize. location of a static initializable variable containing `NULL` new non-`NULL` value for `*location` The possible statuses of a one-time initialization function controlled by a #GOnce struct. the function has not been called yet. the function call is currently in progress. the function has been called. The #GOptionArg enum values determine which type of extra argument the options expect to find. If an option expects an extra argument, it can be specified in several ways; with a short option: `-x arg`, with a long option: `--name arg` or combined in a single argument: `--name=arg`. No extra argument. This is useful for simple flags or booleans. The option takes a UTF-8 string argument. The option takes an integer argument. The option provides a callback (of type #GOptionArgFunc) to parse the extra argument. The option takes a filename as argument, which will be in the GLib filename encoding rather than UTF-8. The option takes a string argument, multiple uses of the option are collected into an array of strings. The option takes a filename as argument, multiple uses of the option are collected into an array of strings. The option takes a double argument. The argument can be formatted either for the user's locale or for the "C" locale. Since 2.12 The option takes a 64-bit integer. Like %G_OPTION_ARG_INT but for larger numbers. The number can be in decimal base, or in hexadecimal (when prefixed with `0x`, for example, `0xffffffff`). Since 2.12 The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK options. %TRUE if the option was successfully parsed, %FALSE if an error occurred, in which case @error should be set with g_set_error() The name of the option being parsed. This will be either a single dash followed by a single letter (for a short name) or two dashes followed by a long option name. The value to be parsed. User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() A `GOptionContext` struct defines which options are accepted by the commandline option parser. The struct has only private fields and should not be directly accessed. Adds a #GOptionGroup to the @context, so that parsing with @context will recognize the options in the group. Note that this will take ownership of the @group and thus the @group should not be freed. a #GOptionContext the group to add A convenience function which creates a main group if it doesn't exist, adds the @entries to it and sets the translation domain. a #GOptionContext a %NULL-terminated array of #GOptionEntrys a translation domain to use for translating the `--help` output for the options in @entries with gettext(), or %NULL Frees context and all the groups which have been added to it. Please note that parsed arguments need to be freed separately (see #GOptionEntry). a #GOptionContext Returns the description. See g_option_context_set_description(). the description a #GOptionContext Returns a formatted, translated help text for the given context. To obtain the text produced by `--help`, call `g_option_context_get_help (context, TRUE, NULL)`. To obtain the text produced by `--help-all`, call `g_option_context_get_help (context, FALSE, NULL)`. To obtain the help text for an option group, call `g_option_context_get_help (context, FALSE, group)`. A newly allocated string containing the help text a #GOptionContext if %TRUE, only include the main group the #GOptionGroup to create help for, or %NULL Returns whether automatic `--help` generation is turned on for @context. See g_option_context_set_help_enabled(). %TRUE if automatic help generation is turned on. a #GOptionContext Returns whether unknown options are ignored or not. See g_option_context_set_ignore_unknown_options(). %TRUE if unknown options are ignored. a #GOptionContext Returns a pointer to the main group of @context. the main group of @context, or %NULL if @context doesn't have a main group. Note that group belongs to @context and should not be modified or freed. a #GOptionContext Returns whether strict POSIX code is enabled. See g_option_context_set_strict_posix() for more information. %TRUE if strict POSIX is enabled, %FALSE otherwise. a #GOptionContext Returns the summary. See g_option_context_set_summary(). the summary a #GOptionContext Parses the command line arguments, recognizing options which have been added to @context. A side-effect of calling this function is that g_set_prgname() will be called. If the parsing is successful, any parsed arguments are removed from the array and @argc and @argv are updated accordingly. A '--' option is stripped from @argv unless there are unparsed options before and after it, or some of the options after it start with '-'. In case of an error, @argc and @argv are left unmodified. If automatic `--help` support is enabled (see g_option_context_set_help_enabled()), and the @argv array contains one of the recognized help options, this function will produce help output to stdout and call `exit (0)`. Note that function depends on the [current locale](running.html#locale) for automatic character set conversion of string and filename arguments. %TRUE if the parsing was successful, %FALSE if an error occurred a #GOptionContext a pointer to the number of command line arguments a pointer to the array of command line arguments Parses the command line arguments. This function is similar to g_option_context_parse() except that it respects the normal memory rules when dealing with a strv instead of assuming that the passed-in array is the argv of the main function. In particular, strings that are removed from the arguments list will be freed using g_free(). On Windows, the strings are expected to be in UTF-8. This is in contrast to g_option_context_parse() which expects them to be in the system codepage, which is how they are passed as @argv to main(). See g_win32_get_command_line() for a solution. This function is useful if you are trying to use #GOptionContext with #GApplication. %TRUE if the parsing was successful, %FALSE if an error occurred a #GOptionContext a pointer to the command line arguments (which must be in UTF-8 on Windows). Starting with GLib 2.62, @arguments can be %NULL, which matches g_option_context_parse(). Adds a string to be displayed in `--help` output after the list of options. This text often includes a bug reporting address. Note that the summary is translated (see g_option_context_set_translate_func()). a #GOptionContext a string to be shown in `--help` output after the list of options, or %NULL Enables or disables automatic generation of `--help` output. By default, g_option_context_parse() recognizes `--help`, `-h`, `-?`, `--help-all` and `--help-groupname` and creates suitable output to stdout. a #GOptionContext %TRUE to enable `--help`, %FALSE to disable it Sets whether to ignore unknown options or not. If an argument is ignored, it is left in the @argv array after parsing. By default, g_option_context_parse() treats unknown options as error. This setting does not affect non-option arguments (i.e. arguments which don't start with a dash). But note that GOption cannot reliably determine whether a non-option belongs to a preceding unknown option. a #GOptionContext %TRUE to ignore unknown options, %FALSE to produce an error when unknown options are met Sets a #GOptionGroup as main group of the @context. This has the same effect as calling g_option_context_add_group(), the only difference is that the options in the main group are treated differently when generating `--help` output. a #GOptionContext the group to set as main group Sets strict POSIX mode. By default, this mode is disabled. In strict POSIX mode, the first non-argument parameter encountered (eg: filename) terminates argument processing. Remaining arguments are treated as non-options and are not attempted to be parsed. If strict POSIX mode is disabled then parsing is done in the GNU way where option arguments can be freely mixed with non-options. As an example, consider "ls foo -l". With GNU style parsing, this will list "foo" in long mode. In strict POSIX style, this will list the files named "foo" and "-l". It may be useful to force strict POSIX mode when creating "verb style" command line tools. For example, the "gsettings" command line tool supports the global option "--schemadir" as well as many subcommands ("get", "set", etc.) which each have their own set of arguments. Using strict POSIX mode will allow parsing the global options up to the verb name while leaving the remaining options to be parsed by the relevant subcommand (which can be determined by examining the verb name, which should be present in argv[1] after parsing). a #GOptionContext the new value Adds a string to be displayed in `--help` output before the list of options. This is typically a summary of the program functionality. Note that the summary is translated (see g_option_context_set_translate_func() and g_option_context_set_translation_domain()). a #GOptionContext a string to be shown in `--help` output before the list of options, or %NULL Sets the function which is used to translate the contexts user-visible strings, for `--help` output. If @func is %NULL, strings are not translated. Note that option groups have their own translation functions, this function only affects the @parameter_string (see g_option_context_new()), the summary (see g_option_context_set_summary()) and the description (see g_option_context_set_description()). If you are using gettext(), you only need to set the translation domain, see g_option_context_set_translation_domain(). a #GOptionContext the #GTranslateFunc, or %NULL user data to pass to @func, or %NULL a function which gets called to free @data, or %NULL A convenience function to use gettext() for translating user-visible strings. a #GOptionContext the domain to use Creates a new option context. The @parameter_string can serve multiple purposes. It can be used to add descriptions for "rest" arguments, which are not parsed by the #GOptionContext, typically something like "FILES" or "FILE1 FILE2...". If you are using %G_OPTION_REMAINING for collecting "rest" arguments, GLib handles this automatically by using the @arg_description of the corresponding #GOptionEntry in the usage summary. Another usage is to give a short summary of the program functionality, like " - frob the strings", which will be displayed in the same line as the usage. For a longer description of the program functionality that should be displayed as a paragraph below the usage line, use g_option_context_set_summary(). Note that the @parameter_string is translated using the function set with g_option_context_set_translate_func(), so it should normally be passed untranslated. a newly created #GOptionContext, which must be freed with g_option_context_free() after use. a string which is displayed in the first line of `--help` output, after the usage summary `programname [OPTION...]` - %G_OPTION_ARG_NONE: %gboolean - %G_OPTION_ARG_STRING: %gchar* - %G_OPTION_ARG_INT: %gint - %G_OPTION_ARG_FILENAME: %gchar* - %G_OPTION_ARG_STRING_ARRAY: %gchar** - %G_OPTION_ARG_FILENAME_ARRAY: %gchar** - %G_OPTION_ARG_DOUBLE: %gdouble If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME, the location will contain a newly allocated string if the option was given. That string needs to be freed by the callee using g_free(). Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev(). A GOptionEntry struct defines a single option. To have an effect, they must be added to a #GOptionGroup with g_option_context_add_main_entries() or g_option_group_add_entries(). The long name of an option can be used to specify it in a commandline as `--long_name`. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as `--groupname-long_name`. If an option has a short name, it can be specified `-short_name` in a commandline. @short_name must be a printable ASCII character different from '-', or zero if the option has no short name. Flags from #GOptionFlags The type of the option, as a #GOptionArg If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must point to a #GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, @arg_data is a pointer to a location to store the value, the required type of the location depends on the @arg type: the description for the option in `--help` output. The @description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). The placeholder to use for the extra argument parsed by the option in `--help` output. The @arg_description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). Error codes returned by option parsing. An option was not known to the parser. This error will only be reported, if the parser hasn't been instructed to ignore unknown options, see g_option_context_set_ignore_unknown_options(). A value couldn't be parsed. A #GOptionArgFunc callback failed. The type of function to be used as callback when a parse error occurs. The active #GOptionContext The group to which the function belongs User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() Flags which modify individual options. No flags. The option doesn't appear in `--help` output. The option appears in the main section of the `--help` output, even if it is defined in a group. For options of the %G_OPTION_ARG_NONE kind, this flag indicates that the sense of the option is reversed. i.e. %FALSE will be stored into the argument rather than %TRUE. For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the callback does not take any argument (like a %G_OPTION_ARG_NONE option). Since 2.8 For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument should be passed to the callback in the GLib filename encoding rather than UTF-8. Since 2.8 For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument supply is optional. If no argument is given then data of %GOptionParseFunc will be set to NULL. Since 2.8 This flag turns off the automatic conflict resolution which prefixes long option names with `groupname-` if there is a conflict. This option should only be used in situations where aliasing is necessary to model some legacy commandline interface. It is not safe to use this option, unless all option groups are under your direct control. Since 2.8. This flag marks the option as deprecated in the `--help`. You should update the description of the option to describe what the user should do in response to the deprecation, for instance: remove the option, or replace it with another one. A `GOptionGroup` struct defines the options in a single group. The struct has only private fields and should not be directly accessed. All options in a group share the same translation function. Libraries which need to parse commandline options are expected to provide a function for getting a `GOptionGroup` holding their options, which the application can then add to its #GOptionContext. Creates a new #GOptionGroup. @description is typically used to provide a title for the group. If so, it is recommended that it’s written in title case, and has a trailing colon so that it matches the style of built-in GLib group titles such as ‘Application Options:’. a newly created option group. It should be added to a #GOptionContext or freed with g_option_group_unref(). the name for the option group, this is used to provide help for the options in this group with `--help-`@name a description for this group to be shown in `--help`. This string is translated using the translation domain or translation function of the group a description for the `--help-`@name option. This string is translated using the translation domain or translation function of the group user data that will be passed to the pre- and post-parse hooks, the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL a function that will be called to free @user_data, or %NULL Adds the options specified in @entries to @group. a #GOptionGroup a %NULL-terminated array of #GOptionEntrys Frees a #GOptionGroup. Note that you must not free groups which have been added to a #GOptionContext. Use g_option_group_unref() instead. a #GOptionGroup Increments the reference count of @group by one. a #GOptionGroup a #GOptionGroup Associates a function with @group which will be called from g_option_context_parse() when an error occurs. Note that the user data to be passed to @error_func can be specified when constructing the group with g_option_group_new(). a #GOptionGroup a function to call when an error occurs Associates two functions with @group which will be called from g_option_context_parse() before the first option is parsed and after the last option has been parsed, respectively. Note that the user data to be passed to @pre_parse_func and @post_parse_func can be specified when constructing the group with g_option_group_new(). a #GOptionGroup a function to call before parsing, or %NULL a function to call after parsing, or %NULL Sets the function which is used to translate user-visible strings, for `--help` output. Different groups can use different #GTranslateFuncs. If @func is %NULL, strings are not translated. If you are using gettext(), you only need to set the translation domain, see g_option_group_set_translation_domain(). a #GOptionGroup the #GTranslateFunc, or %NULL user data to pass to @func, or %NULL a function which gets called to free @data, or %NULL A convenience function to use gettext() for translating user-visible strings. a #GOptionGroup the domain to use Decrements the reference count of @group by one. If the reference count drops to 0, the @group will be freed. and all memory allocated by the @group is released. a #GOptionGroup The type of function that can be called before and after parsing. %TRUE if the function completed successfully, %FALSE if an error occurred, in which case @error should be set with g_set_error() The active #GOptionContext The group to which the function belongs User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() Yields a new preprocessor pasted identifier @identifier1identifier2 from its expanded arguments @identifier1 and @identifier2. For example, the following code: |[<!-- language="C" --> #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller) const gchar *name = GET (traveller, name); const gchar *quest = GET (traveller, quest); GdkColor *favourite = GET (traveller, favourite_colour); ]| is transformed by the preprocessor into: |[<!-- language="C" --> const gchar *name = traveller_get_name (traveller); const gchar *quest = traveller_get_quest (traveller); GdkColor *favourite = traveller_get_favourite_colour (traveller); ]| an identifier an identifier Specifies one of the possible types of byte order (currently unused). See %G_BYTE_ORDER. The value of pi (ratio of circle's circumference to its diameter). A format specifier that can be used in printf()-style format strings when printing a #GPid. Pi divided by 2. Pi divided by 4. A format specifier that can be used in printf()-style format strings when printing the @fd member of a #GPollFD. Use this for default priority event sources. In GLib this priority is used when adding timeout functions with [func@GLib.timeout_add]. In GDK this priority is used for events from the X server. Use this for default priority idle functions. In GLib this priority is used when adding idle functions with [func@GLib.idle_add]. Use this for high priority event sources. It is not used within GLib or GTK. Use this for high priority idle functions. GTK uses %G_PRIORITY_HIGH_IDLE + 10 for resizing operations, and %G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is done to ensure that any pending resizes are processed before any pending redraws, so that widgets are not redrawn twice unnecessarily.) Use this for very low priority background tasks. It is not used within GLib or GTK. A macro to assist with the static initialisation of a #GPrivate. This macro is useful for the case that a #GDestroyNotify function should be associated with the key. This is needed when the key will be used to point at memory that should be deallocated when the thread exits. Additionally, the #GDestroyNotify will also be called on the previous value stored in the key when g_private_replace() is used. If no #GDestroyNotify is needed, then use of this macro is not required -- if the #GPrivate is declared in static scope then it will be properly initialised by default (ie: to all zeros). See the examples below. |[<!-- language="C" --> static GPrivate name_key = G_PRIVATE_INIT (g_free); // return value should not be freed const gchar * get_local_name (void) { return g_private_get (&name_key); } void set_local_name (const gchar *name) { g_private_replace (&name_key, g_strdup (name)); } static GPrivate count_key; // no free function gint get_local_count (void) { return GPOINTER_TO_INT (g_private_get (&count_key)); } void set_local_count (gint count) { g_private_set (&count_key, GINT_TO_POINTER (count)); } ]| a #GDestroyNotify `GPathBuf` is a helper type that allows you to easily build paths from individual elements, using the platform specific conventions for path separators. ```c g_auto (GPathBuf) path; g_path_buf_init (&path); g_path_buf_push (&path, "usr"); g_path_buf_push (&path, "bin"); g_path_buf_push (&path, "echo"); g_autofree char *echo = g_path_buf_to_path (&path); g_assert_cmpstr (echo, ==, "/usr/bin/echo"); ``` You can also load a full path and then operate on its components: ```c g_auto (GPathBuf) path; g_path_buf_init_from_path (&path, "/usr/bin/echo"); g_path_buf_pop (&path); g_path_buf_push (&path, "sh"); g_autofree char *sh = g_path_buf_to_path (&path); g_assert_cmpstr (sh, ==, "/usr/bin/sh"); ``` Clears the contents of the path buffer. This function should be use to free the resources in a stack-allocated `GPathBuf` initialized using g_path_buf_init() or g_path_buf_init_from_path(). a path buffer Clears the contents of the path buffer and returns the built path. This function returns `NULL` if the `GPathBuf` is empty. See also: g_path_buf_to_path() the built path a path buffer Copies the contents of a path buffer into a new `GPathBuf`. the newly allocated path buffer a path buffer Frees a `GPathBuf` allocated by g_path_buf_new(). a path buffer Frees a `GPathBuf` allocated by g_path_buf_new(), and returns the path inside the buffer. This function returns `NULL` if the `GPathBuf` is empty. See also: g_path_buf_to_path() the path a path buffer Initializes a `GPathBuf` instance. the initialized path builder a path buffer Initializes a `GPathBuf` instance with the given path. the initialized path builder a path buffer a file system path Removes the last element of the path buffer. If there is only one element in the path buffer (for example, `/` on Unix-like operating systems or the drive on Windows systems), it will not be removed and %FALSE will be returned instead. |[<!-- language="C" --> GPathBuf buf, cmp; g_path_buf_init_from_path (&buf, "/bin/sh"); g_path_buf_pop (&buf); g_path_buf_init_from_path (&cmp, "/bin"); g_assert_true (g_path_buf_equal (&buf, &cmp)); g_path_buf_clear (&cmp); g_path_buf_pop (&buf); g_path_buf_init_from_path (&cmp, "/"); g_assert_true (g_path_buf_equal (&buf, &cmp)); g_path_buf_clear (&cmp); g_path_buf_clear (&buf); ]| `TRUE` if the buffer was modified and `FALSE` otherwise a path buffer Extends the given path buffer with @path. If @path is absolute, it replaces the current path. If @path contains a directory separator, the buffer is extended by as many elements the path provides. On Windows, both forward slashes and backslashes are treated as directory separators. On other platforms, %G_DIR_SEPARATOR_S is the only directory separator. |[<!-- language="C" --> GPathBuf buf, cmp; g_path_buf_init_from_path (&buf, "/tmp"); g_path_buf_push (&buf, ".X11-unix/X0"); g_path_buf_init_from_path (&cmp, "/tmp/.X11-unix/X0"); g_assert_true (g_path_buf_equal (&buf, &cmp)); g_path_buf_clear (&cmp); g_path_buf_push (&buf, "/etc/locale.conf"); g_path_buf_init_from_path (&cmp, "/etc/locale.conf"); g_assert_true (g_path_buf_equal (&buf, &cmp)); g_path_buf_clear (&cmp); g_path_buf_clear (&buf); ]| the same pointer to @buf, for convenience a path buffer a path Adds an extension to the file name in the path buffer. If @extension is `NULL`, the extension will be unset. If the path buffer does not have a file name set, this function returns `FALSE` and leaves the path buffer unmodified. `TRUE` if the extension was replaced, and `FALSE` otherwise a path buffer the file extension Sets the file name of the path. If the path buffer is empty, the filename is left unset and this function returns `FALSE`. If the path buffer only contains the root element (on Unix-like operating systems) or the drive (on Windows), this is the equivalent of pushing the new @file_name. If the path buffer contains a path, this is the equivalent of popping the path buffer and pushing @file_name, creating a sibling of the original path. |[<!-- language="C" --> GPathBuf buf, cmp; g_path_buf_init_from_path (&buf, "/"); g_path_buf_set_filename (&buf, "bar"); g_path_buf_init_from_path (&cmp, "/bar"); g_assert_true (g_path_buf_equal (&buf, &cmp)); g_path_buf_clear (&cmp); g_path_buf_set_filename (&buf, "baz.txt"); g_path_buf_init_from_path (&cmp, "/baz.txt"); g_assert_true (g_path_buf_equal (&buf, &cmp); g_path_buf_clear (&cmp); g_path_buf_clear (&buf); ]| `TRUE` if the file name was replaced, and `FALSE` otherwise a path buffer the file name in the path Retrieves the built path from the path buffer. On Windows, the result contains backslashes as directory separators, even if forward slashes were used in input. If the path buffer is empty, this function returns `NULL`. the path a path buffer Compares two path buffers for equality and returns `TRUE` if they are equal. The paths inside the path buffers are not going to be normalized, so `X/Y/Z/A/..`, `X/./Y/Z` and `X/Y/Z` are not going to be considered equal. This function can be passed to g_hash_table_new() as the `key_equal_func` parameter. `TRUE` if the two path buffers are equal, and `FALSE` otherwise a path buffer to compare a path buffer to compare Allocates a new `GPathBuf`. the newly allocated path buffer Allocates a new `GPathBuf` with the given @path. the newly allocated path buffer the path used to initialize the buffer A `GPatternSpec` struct is the ‘compiled’ form of a glob-style pattern. The [func@GLib.pattern_match_simple] and [method@GLib.PatternSpec.match] functions match a string against a pattern containing `*` and `?` wildcards with similar semantics as the standard `glob()` function: `*` matches an arbitrary, possibly empty, string, `?` matches an arbitrary character. Note that in contrast to [`glob()`](man:glob(3)), the `/` character can be matched by the wildcards, there are no `[…]` character ranges and `*` and `?` can not be escaped to include them literally in a pattern. When multiple strings must be matched against the same pattern, it is better to compile the pattern to a [struct@GLib.PatternSpec] using [ctor@GLib.PatternSpec.new] and use [method@GLib.PatternSpec.match_string] instead of [func@GLib.pattern_match_simple]. This avoids the overhead of repeated pattern compilation. Compiles a pattern to a [type@GLib.PatternSpec]. a newly-allocated [type@GLib.PatternSpec] a zero-terminated UTF-8 encoded string Copies @pspec in a new [type@GLib.PatternSpec]. a copy of @pspec. a #GPatternSpec Compares two compiled pattern specs and returns whether they will match the same set of strings. Whether the compiled patterns are equal a #GPatternSpec another #GPatternSpec Frees the memory allocated for the [type@GLib.PatternSpec]. a #GPatternSpec Matches a string against a compiled pattern. Passing the correct length of the string given is mandatory. The reversed string can be omitted by passing `NULL`, this is more efficient if the reversed version of the string to be matched is not at hand, as [method@GLib.PatternSpec.match] will only construct it if the compiled pattern requires reverse matches. Note that, if the user code will (possibly) match a string against a multitude of patterns containing wildcards, chances are high that some patterns will require a reversed string. In this case, it’s more efficient to provide the reversed string to avoid multiple constructions thereof in the various calls to [method@GLib.PatternSpec.match]. Note also that the reverse of a UTF-8 encoded string can in general not be obtained by [func@GLib.strreverse]. This works only if the string does not contain any multibyte characters. GLib offers the [func@GLib.utf8_strreverse] function to reverse UTF-8 encoded strings. %TRUE if @string matches @pspec a #GPatternSpec the length of @string (in bytes, i.e. `strlen()`, not [func@GLib.utf8_strlen]) the UTF-8 encoded string to match the reverse of @string Matches a string against a compiled pattern. If the string is to be matched against more than one pattern, consider using [method@GLib.PatternSpec.match] instead while supplying the reversed string. %TRUE if @string matches @pspec a #GPatternSpec the UTF-8 encoded string to match Represents a file descriptor, which events to poll for, and which events occurred. the file descriptor to poll (or a HANDLE on Win32) a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use %G_IO_OUT | %G_IO_ERR. a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred. Specifies the type of function passed to g_main_context_set_poll_func(). The semantics of the function should match those of the poll() system call. the number of #GPollFD elements which have events or errors reported, or -1 if an error occurred. an array of #GPollFD elements the number of elements in @ufds the maximum time to wait for an event of the file descriptors. A negative value indicates an infinite timeout. Specifies the type of the print handler functions. These are called with the complete formatted string to output. the message to output The #GPrivate struct is an opaque data structure to represent a thread-local data key. It is approximately equivalent to the pthread_setspecific()/pthread_getspecific() APIs on POSIX and to TlsSetValue()/TlsGetValue() on Windows. If you don't already know why you might want this functionality, then you probably don't need it. #GPrivate is a very limited resource (as far as 128 per program, shared between all libraries). It is also not possible to destroy a #GPrivate after it has been used. As such, it is only ever acceptable to use #GPrivate in static scope, and even then sparingly so. See G_PRIVATE_INIT() for a couple of examples. The #GPrivate structure should be considered opaque. It should only be accessed via the g_private_ functions. Returns the current value of the thread local variable @key. If the value has not yet been set in this thread, %NULL is returned. Values are never copied between threads (when a new thread is created, for example). the thread-local value a #GPrivate Sets the thread local variable @key to have the value @value in the current thread. This function differs from g_private_set() in the following way: if the previous value was non-%NULL then the #GDestroyNotify handler for @key is run on it. a #GPrivate the new value Sets the thread local variable @key to have the value @value in the current thread. This function differs from g_private_replace() in the following way: the #GDestroyNotify for @key is not called on the old value. a #GPrivate the new value Creates a new #GPrivate. dynamic allocation of #GPrivate is a bad idea. Use static storage and G_PRIVATE_INIT() instead. a newly allocated #GPrivate (which can never be destroyed) a #GDestroyNotify Contains the public fields of a `GPtrArray`. a pointer to the array of pointers, which may be moved when the array grows the number of pointers in the array Adds a pointer to the end of the pointer array. The array will grow in size automatically if necessary. a pointer array the pointer to add Makes a full (deep) copy of a `GPtrArray`. @func, as a [callback@GLib.CopyFunc], takes two arguments, the data to be copied and a @user_data pointer. On common processor architectures, it’s safe to pass `NULL` as @user_data if the copy function takes only one argument. You may get compiler warnings from this though if compiling with GCC’s `-Wcast-function-type` warning. If @func is `NULL`, then only the pointers (and not what they are pointing to) are copied to the new `GPtrArray`. The copy of @array will have the same [callback@GLib.DestroyNotify] for its elements as @array. The copy will also be `NULL` terminated if (and only if) the source array is. The deep copy of the initial `GPtrArray` a pointer array to duplicate a copy function used to copy every element in the array the user data passed to the copy function @func Adds all pointers of @array to the end of the array @array_to_extend. The array will grow in size automatically if needed. @array_to_extend is modified in-place. @func, as a [callback@GLib.CopyFunc], takes two arguments, the data to be copied and a @user_data pointer. On common processor architectures, it’s safe to pass `NULL` as @user_data if the copy function takes only one argument. You may get compiler warnings from this though if compiling with GCC’s `-Wcast-function-type` warning. If @func is `NULL`, then only the pointers (and not what they are pointing to) are copied to the new `GPtrArray`. Whether @array_to_extend is `NULL` terminated stays unchanged by this function. a pointer array a pointer array to add to the end of @array_to_extend a copy function used to copy every element in the array the user data passed to the copy function @func Adds all the pointers in @array to the end of @array_to_extend, transferring ownership of each element from @array to @array_to_extend and modifying @array_to_extend in-place. @array is then freed. As with [func@GLib.PtrArray.free], @array will be destroyed if its reference count is 1. If its reference count is higher, it will be decremented and the length of @array set to zero. a pointer array a pointer array to add to the end of @array_to_extend Checks whether @needle exists in @haystack. If the element is found, true is returned and the element’s index is returned in @index_ (if non-`NULL`). Otherwise, false is returned and @index_ is undefined. If @needle exists multiple times in @haystack, the index of the first instance is returned. This does pointer comparisons only. If you want to use more complex equality checks, such as string comparisons, use [func@GLib.PtrArray.find_with_equal_func]. true if @needle is one of the elements of @haystack; false otherwise the pointer array to be searched the pointer to look for the return location for the index of the element, if found Checks whether @needle exists in @haystack, using the given @equal_func. If the element is found, true is returned and the element’s index is returned in @index_ (if non-`NULL`). Otherwise, false is returned and @index_ is undefined. If @needle exists multiple times in @haystack, the index of the first instance is returned. @equal_func is called with the element from the array as its first parameter, and @needle as its second parameter. If @equal_func is `NULL`, pointer equality is used. true if @needle is one of the elements of @haystack; false otherwise the pointer array to be searched the pointer to look for the function to call for each element, which should return true when the desired element is found; or `NULL` to use pointer equality the return location for the index of the element, if found Calls a function for each element of a `GPtrArray`. @func must not add elements to or remove elements from the array. a pointer array the function to call for each array element the user data to pass to the function Frees the memory allocated for the `GPtrArray`. If @free_segment is true it frees the memory block holding the elements as well. Pass false if you want to free the `GPtrArray` wrapper but preserve the underlying array for use elsewhere. If the reference count of @array is greater than one, the `GPtrArray` wrapper is preserved but the size of @array will be set to zero. If array contents point to dynamically-allocated memory, they should be freed separately if @free_segment is true and no [callback@GLib.DestroyNotify] function has been set for @array. Note that if the array is `NULL` terminated and @free_segment is false then this will always return an allocated `NULL` terminated buffer. If `pdata` is previously `NULL`, a new buffer will be allocated. This function is not thread-safe. If using a `GPtrArray` from multiple threads, use only the atomic [func@GLib.PtrArray.ref] and [func@GLib.PtrArray.unref] functions. The allocated pointer array if @free_segment is false, otherwise `NULL`. a pointer array if true, the actual pointer array is freed as well Inserts an element into the pointer array at the given index. The array will grow in size automatically if necessary. a pointer array the index to place the new element at, or -1 to append the pointer to add Checks whether the @array was constructed as `NULL`-terminated. This will only return true for arrays constructed by passing true to the `null_terminated` argument of [func@GLib.PtrArray.new_null_terminated]. It will not return true for normal arrays which have had a `NULL` element appended to them. true if the array is made to be `NULL` terminated; false otherwise a pointer array Creates a new `GPtrArray` with a reference count of 1. The new `GPtrArray` Creates a new `GPtrArray`, copying @len pointers from @data, and setting the array’s reference count to 1. This avoids having to manually add each element one by one. If @copy_func is provided, then it is used to copy each element before adding them to the new array. If it is `NULL` then the pointers are copied directly. It also sets @element_free_func for freeing each element when the array is destroyed either via [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is called with @free_segment set to true or when removing elements. Do not use it if @len is greater than [`G_MAXUINT`](types.html#guint). `GPtrArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new `GPtrArray` an array of pointers the number of pointers in @data a copy function used to copy every element in the array the user data passed to @copy_func a function to free elements on @array destruction Creates a new `GPtrArray` copying the pointers from @data after having computed the length of it and with a reference count of 1. This avoids having to manually add each element one by one. If @copy_func is provided, then it is used to copy the data in the new array. It also sets @element_free_func for freeing each element when the array is destroyed either via [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is called with @free_segment set to true or when removing elements. Do not use it if the @data has more than [`G_MAXUINT`](types.html#guint) elements. `GPtrArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new `GPtrArray` an array of pointers, `NULL` terminated a copy function used to copy every element in the array the user data passed to @copy_func a function to free elements on @array destruction Creates a new `GPtrArray` with @reserved_size pointers preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many pointers to the array. Note however that the size of the array is still 0. It also sets @element_free_func for freeing each element when the array is destroyed either via [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is called with @free_segment set to true or when removing elements. The new `GPtrArray` the number of pointers preallocated a function to free elements with destroy @array Like [func@GLib.PtrArray.new_full] but also allows to set the array to be `NULL` terminated. A `NULL` terminated pointer array has an additional `NULL` pointer after the last element, beyond the current length. `GPtrArray` created by other constructors are not automatically `NULL` terminated. Note that if the @array’s length is zero and currently no data array is allocated, then `pdata` will still be `NULL`. `GPtrArray` will only `NULL` terminate `pdata`, if an actual array is allocated. It does not guarantee that an array is always allocated. In other words, if the length is zero, then `pdata` may either point to a `NULL` terminated array of length zero or be `NULL`. The new `GPtrArray` the number of pointers preallocated. If @null_terminated is `TRUE`, the actually allocated buffer size is @reserved_size plus 1, unless @reserved_size is zero, in which case no initial buffer gets allocated. a function to free elements during destruction of @array if true, make the array `NULL` terminated Creates a new `GPtrArray` with @data as pointers, @len as length and a reference count of 1. This avoids having to copy such data manually. After this call, @data belongs to the `GPtrArray` and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with [func@GLib.free]. It also sets @element_free_func for freeing each element when the array is destroyed either via [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is called with @free_segment set to true or when removing elements. Do not use it if @len is greater than [`G_MAXUINT`](types.html#guint). `GPtrArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new `GPtrArray` an array of pointers the number of pointers in @data a function to free elements on @array destruction Creates a new `GPtrArray` with @data as pointers, computing the length of it and setting the reference count to 1. This avoids having to copy such data manually. After this call, @data belongs to the `GPtrArray` and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with [func@GLib.free]. The length is calculated by iterating through @data until the first `NULL` element is found. It also sets @element_free_func for freeing each element when the array is destroyed either via [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is called with @free_segment set to true or when removing elements. Do not use it if the @data length is greater than [`G_MAXUINT`](types.html#guint). `GPtrArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new `GPtrArray` an array of pointers, `NULL` terminated a function to free elements on @array destruction Creates a new `GPtrArray` with a reference count of 1 and use @element_free_func for freeing each element when the array is destroyed either via [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is called with @free_segment set to true or when removing elements. The new `GPtrArray` a function to free elements with destroy @array Atomically increments the reference count of @array by one. This function is thread-safe and may be called from any thread. The passed in `GPtrArray` a pointer array Removes the first occurrence of the given pointer from the pointer array. The following elements are moved down one place. If @array has a non-`NULL` [callback@GLib.DestroyNotify] function it is called for the removed element. It returns true if the pointer was removed, or false if the pointer was not found. true if the pointer is found and removed; false otherwise a pointer array the pointer to remove Removes the first occurrence of the given pointer from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than [func@GLib.PtrArray.remove]. If @array has a non-`NULL` [callback@GLib.DestroyNotify] function it is called for the removed element. It returns true if the pointer was removed, or false if the pointer was not found. true if the pointer is found and removed; false otherwise a pointer array the pointer to remove Removes the pointer at the given index from the pointer array. The following elements are moved down one place. If @array has a non-`NULL` [callback@GLib.DestroyNotify] function it is called for the removed element. If so, the return value from this function will potentially point to freed memory (depending on the [callback@GLib.DestroyNotify] implementation). The pointer which was removed a pointer array the index of the pointer to remove Removes the pointer at the given index from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than [func@GLib.PtrArray.remove_index]. If @array has a non-`NULL` [callback@GLib.DestroyNotify] function it is called for the removed element. If so, the return value from this function will potentially point to freed memory (depending on the [callback@GLib.DestroyNotify] implementation). The pointer which was removed a pointer array the index of the pointer to remove Removes the given number of pointers starting at the given index from a `GPtrArray`. The following elements are moved to close the gap. If @array has a non-`NULL` [callback@GLib.DestroyNotify] function it is called for the removed elements. The @array a pointer array the index of the first pointer to remove the number of pointers to remove Sets a function for freeing each element when @array is destroyed either via [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is called with @free_segment set to true or when removing elements. a pointer array a function to free elements during destruction of @array Sets the size of the array. When making the array larger, newly-added elements will be set to `NULL`. When making it smaller, if @array has a non-`NULL` [callback@GLib.DestroyNotify] function then it will be called for the removed elements. a pointer array the new length of the pointer array Creates a new `GPtrArray` with @reserved_size pointers preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many pointers to the array. Note however that the size of the array is still 0. The new `GPtrArray` the number of pointers preallocated Sorts the array, using @compare_func which should be a `qsort()`-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater than zero if first arg is greater than second arg). Note that the comparison function for [func@GLib.PtrArray.sort] doesn’t take the pointers from the array as arguments, it takes pointers to the pointers in the array. Use [func@GLib.PtrArray.sort_values] if you want to use normal [callback@GLib.CompareFunc] instances, otherwise here is a full example of use: ```c typedef struct { gchar *name; gint size; } FileListEntry; static gint sort_filelist (gconstpointer a, gconstpointer b) { const FileListEntry *entry1 = *((FileListEntry **) a); const FileListEntry *entry2 = *((FileListEntry **) b); return g_ascii_strcasecmp (entry1->name, entry2->name); } … g_autoptr (GPtrArray) file_list = NULL; // initialize file_list array and load with many FileListEntry entries ... // now sort it with g_ptr_array_sort (file_list, sort_filelist); ``` This is guaranteed to be a stable sort since version 2.32. a pointer array a comparison function Sorts the array, using @compare_func which should be a `qsort()`-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater than zero if first arg is greater than second arg). This is guaranteed to be a stable sort. a pointer array a comparison function Like [func@GLib.PtrArray.sort_values], but the comparison function has an extra user data argument. This is guaranteed to be a stable sort. a pointer array a comparison function the data to pass to @compare_func Like [func@GLib.PtrArray.sort], but the comparison function has an extra user data argument. Note that the comparison function for [func@GLib.PtrArray.sort_with_data] doesn’t take the pointers from the array as arguments, it takes pointers to the pointers in the array. Use [func@GLib.PtrArray.sort_values_with_data] if you want to use normal [callback@GLib.CompareDataFunc] instances, otherwise here is a full example of use: ```c typedef enum { SORT_NAME, SORT_SIZE } SortMode; typedef struct { gchar *name; gint size; } FileListEntry; static gint sort_filelist (gconstpointer a, gconstpointer b, gpointer user_data) { gint order; const SortMode sort_mode = GPOINTER_TO_INT (user_data); const FileListEntry *entry1 = *((FileListEntry **) a); const FileListEntry *entry2 = *((FileListEntry **) b); switch (sort_mode) { case SORT_NAME: order = g_ascii_strcasecmp (entry1->name, entry2->name); break; case SORT_SIZE: order = entry1->size - entry2->size; break; default: order = 0; break; } return order; } ... g_autoptr (GPtrArray) file_list = NULL; SortMode sort_mode; // initialize file_list array and load with many FileListEntry entries ... // now sort it with sort_mode = SORT_NAME; g_ptr_array_sort_with_data (file_list, sort_filelist, GINT_TO_POINTER (sort_mode)); ``` This is guaranteed to be a stable sort since version 2.32. a pointer array a comparison function the data to pass to @compare_func Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller. Note that if the array is `NULL` terminated this may still return `NULL` if the length of the array was zero and pdata was not yet allocated. Even if set, the [callback@GLib.DestroyNotify] function will never be called on the current contents of the array and the caller is responsible for freeing the array elements. An example of use: ```c g_autoptr(GPtrArray) chunk_buffer = g_ptr_array_new_with_free_func (g_bytes_unref); // Some part of your application appends a number of chunks to the pointer array. g_ptr_array_add (chunk_buffer, g_bytes_new_static ("hello", 5)); g_ptr_array_add (chunk_buffer, g_bytes_new_static ("world", 5)); … // Periodically, the chunks need to be sent as an array-and-length to some // other part of the program. GBytes **chunks; gsize n_chunks; chunks = g_ptr_array_steal (chunk_buffer, &n_chunks); for (gsize i = 0; i < n_chunks; i++) { // Do something with each chunk here, and then free them, since // g_ptr_array_steal() transfers ownership of all the elements and the // array to the caller. … g_bytes_unref (chunks[i]); } g_free (chunks); // After calling g_ptr_array_steal(), the pointer array can be reused for the // next set of chunks. g_assert (chunk_buffer->len == 0); ``` The allocated element data. This may be `NULL`if the array doesn’t have any elements (i.e. if `*len` is zero). a pointer array a pointer to retrieve the number of elements of the original array Removes the pointer at the given index from the pointer array. The following elements are moved down one place. The [callback@GLib.DestroyNotify] for @array is *not* called on the removed element; ownership is transferred to the caller of this function. The pointer which was removed a pointer array the index of the pointer to steal Removes the pointer at the given index from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than [func@GLib.PtrArray.steal_index]. The [callback@GLib.DestroyNotify] for @array is *not* called on the removed element; ownership is transferred to the caller of this function. The pointer which was removed a pointer array the index of the pointer to steal Atomically decrements the reference count of @array by one. If the reference count drops to 0, the effect is the same as calling [func@GLib.PtrArray.free] with @free_segment set to true. This function is thread-safe and may be called from any thread. a pointer array Contains the public fields of a [Queue](data-structures.html#double-ended-queues). a pointer to the first element of the queue a pointer to the last element of the queue the number of elements in the queue Removes all the elements in @queue. If queue elements contain dynamically-allocated memory, they should be freed first. a #GQueue Convenience method, which frees all the memory used by a #GQueue, and calls the provided @free_func on each item in the #GQueue. a pointer to a #GQueue the function to be called to free memory allocated Copies a @queue. Note that is a shallow copy. If the elements in the queue consist of pointers to data, the pointers are copied, but the actual data is not. a copy of @queue a #GQueue Removes @link_ from @queue and frees it. @link_ must be part of @queue. a #GQueue a #GList link that must be part of @queue Finds the first link in @queue which contains @data. the first link in @queue which contains @data a #GQueue data to find Finds an element in a #GQueue, using a supplied function to find the desired element. It iterates over the queue, calling the given function which should return 0 when the desired element is found. The function takes two gconstpointer arguments, the #GQueue element's data as the first argument and the given user data as the second argument. the found link, or %NULL if it wasn't found a #GQueue user data passed to @func a #GCompareFunc to call for each element. It should return 0 when the desired element is found Calls @func for each element in the queue passing @user_data to the function. It is safe for @func to remove the element from @queue, but it must not modify any part of the queue after that element. a #GQueue the function to call for each element's data user data to pass to @func Frees the memory allocated for the #GQueue. Only call this function if @queue was created with g_queue_new(). If queue elements contain dynamically-allocated memory, they should be freed first. If queue elements contain dynamically-allocated memory, you should either use g_queue_free_full() or free them manually first. a #GQueue Convenience method, which frees all the memory used by a #GQueue, and calls the specified destroy function on every element's data. @free_func should not modify the queue (eg, by removing the freed element from it). a pointer to a #GQueue the function to be called to free each element's data Returns the number of items in @queue. the number of items in @queue a #GQueue Returns the position of the first element in @queue which contains @data. the position of the first element in @queue which contains @data, or -1 if no element in @queue contains @data a #GQueue the data to find A statically-allocated #GQueue must be initialized with this function before it can be used. Alternatively you can initialize it with %G_QUEUE_INIT. It is not necessary to initialize queues created with g_queue_new(). an uninitialized #GQueue Inserts @data into @queue after @sibling. @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the data at the head of the queue. a #GQueue a #GList link that must be part of @queue, or %NULL to push at the head of the queue. the data to insert Inserts @link_ into @queue after @sibling. @sibling must be part of @queue. a #GQueue a #GList link that must be part of @queue, or %NULL to push at the head of the queue. a #GList link to insert which must not be part of any other list. Inserts @data into @queue before @sibling. @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the data at the tail of the queue. a #GQueue a #GList link that must be part of @queue, or %NULL to push at the tail of the queue. the data to insert Inserts @link_ into @queue before @sibling. @sibling must be part of @queue. a #GQueue a #GList link that must be part of @queue, or %NULL to push at the tail of the queue. a #GList link to insert which must not be part of any other list. Inserts @data into @queue using @func to determine the new position. a #GQueue the data to insert the #GCompareDataFunc used to compare elements in the queue. It is called with two elements of the @queue and @user_data. It should return 0 if the elements are equal, a negative value if the first element comes before the second, and a positive value if the second element comes before the first. user data passed to @func Returns %TRUE if the queue is empty. %TRUE if the queue is empty a #GQueue. Returns the position of @link_ in @queue. the position of @link_, or -1 if the link is not part of @queue a #GQueue a #GList link Returns the first element of the queue. the data of the first element in the queue, or %NULL if the queue is empty a #GQueue Returns the first link in @queue. the first link in @queue, or %NULL if @queue is empty a #GQueue Returns the @n'th element of @queue. the data for the @n'th element of @queue, or %NULL if @n is off the end of @queue a #GQueue the position of the element Returns the link at the given position the link at the @n'th position, or %NULL if @n is off the end of the list a #GQueue the position of the link Returns the last element of the queue. the data of the last element in the queue, or %NULL if the queue is empty a #GQueue Returns the last link in @queue. the last link in @queue, or %NULL if @queue is empty a #GQueue Removes the first element of the queue and returns its data. the data of the first element in the queue, or %NULL if the queue is empty a #GQueue Removes and returns the first element of the queue. the #GList element at the head of the queue, or %NULL if the queue is empty a #GQueue Removes the @n'th element of @queue and returns its data. the element's data, or %NULL if @n is off the end of @queue a #GQueue the position of the element Removes and returns the link at the given position. the @n'th link, or %NULL if @n is off the end of @queue a #GQueue the link's position Removes the last element of the queue and returns its data. the data of the last element in the queue, or %NULL if the queue is empty a #GQueue Removes and returns the last element of the queue. the #GList element at the tail of the queue, or %NULL if the queue is empty a #GQueue Adds a new element at the head of the queue. a #GQueue. the data for the new element. Adds a new element at the head of the queue. a #GQueue a single #GList element, not a list with more than one element Inserts a new element into @queue at the given position. a #GQueue the data for the new element the position to insert the new element. If @n is negative or larger than the number of elements in the @queue, the element is added to the end of the queue. Inserts @link into @queue at the given position. a #GQueue the position to insert the link. If this is negative or larger than the number of elements in @queue, the link is added to the end of @queue. the link to add to @queue Adds a new element at the tail of the queue. a #GQueue the data for the new element Adds a new element at the tail of the queue. a #GQueue a single #GList element, not a list with more than one element Removes the first element in @queue that contains @data. %TRUE if @data was found and removed from @queue a #GQueue the data to remove Remove all elements whose data equals @data from @queue. the number of elements removed from @queue a #GQueue the data to remove Reverses the order of the items in @queue. a #GQueue Sorts @queue using @compare_func. a #GQueue the #GCompareDataFunc used to sort @queue. This function is passed two elements of the queue and should return 0 if they are equal, a negative value if the first comes before the second, and a positive value if the second comes before the first. user data passed to @compare_func Unlinks @link_ so that it will no longer be part of @queue. The link is not freed. @link_ must be part of @queue. a #GQueue a #GList link that must be part of @queue Creates a new #GQueue. a newly allocated #GQueue Declare a [type@GLib.RecMutexLocker] variable with `g_autoptr()` and lock the mutex. The mutex will be unlocked automatically when leaving the scope. The variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it is not used in the scope. This feature is only supported on GCC and clang. This macro is not defined on other compilers and should not be used in programs that are intended to be portable to those compilers. Note that this should be used in a place where it is allowed to declare a variable, which could be before any statement in the case `-Wdeclaration-after-statement` is used, or C standard prior to C99. ```c { G_REC_MUTEX_AUTO_LOCK (&obj->rec_mutex, locker); obj->stuff_with_lock (); if (condition) { // No need to unlock return; } // Unlock before end of scope g_clear_pointer (&locker, g_rec_mutex_locker_free); obj->stuff_without_lock (); } ``` a [type@GLib.RecMutex] a variable name to be declared Evaluates to the initial reference count for `grefcount`. This macro is useful for initializing `grefcount` fields inside structures, for instance: |[<!-- language="C" --> typedef struct { grefcount ref_count; char *name; char *address; } Person; static const Person default_person = { .ref_count = G_REF_COUNT_INIT, .name = "Default name", .address = "Default address", }; ]| The GRWLock struct is an opaque data structure to represent a reader-writer lock. It is similar to a #GMutex in that it allows multiple threads to coordinate access to a shared resource. The difference to a mutex is that a reader-writer lock discriminates between read-only ('reader') and full ('writer') access. While only one thread at a time is allowed write access (by holding the 'writer' lock via g_rw_lock_writer_lock()), multiple threads can gain simultaneous read-only access (by holding the 'reader' lock via g_rw_lock_reader_lock()). It is unspecified whether readers or writers have priority in acquiring the lock when a reader already holds the lock and a writer is queued to acquire it. Here is an example for an array with access functions: |[<!-- language="C" --> GRWLock lock; GPtrArray *array; gpointer my_array_get (guint index) { gpointer retval = NULL; if (!array) return NULL; g_rw_lock_reader_lock (&lock); if (index < array->len) retval = g_ptr_array_index (array, index); g_rw_lock_reader_unlock (&lock); return retval; } void my_array_set (guint index, gpointer data) { g_rw_lock_writer_lock (&lock); if (!array) array = g_ptr_array_new (); if (index >= array->len) g_ptr_array_set_size (array, index+1); g_ptr_array_index (array, index) = data; g_rw_lock_writer_unlock (&lock); } ]| This example shows an array which can be accessed by many readers (the my_array_get() function) simultaneously, whereas the writers (the my_array_set() function) will only be allowed one at a time and only if no readers currently access the array. This is because of the potentially dangerous resizing of the array. Using these functions is fully multi-thread safe now. If a #GRWLock is allocated in static storage then it can be used without initialisation. Otherwise, you should call g_rw_lock_init() on it and g_rw_lock_clear() when done. A GRWLock should only be accessed with the g_rw_lock_ functions. Frees the resources allocated to a lock with g_rw_lock_init(). This function should not be used with a #GRWLock that has been statically allocated. Calling g_rw_lock_clear() when any thread holds the lock leads to undefined behaviour. an initialized #GRWLock Initializes a #GRWLock so that it can be used. This function is useful to initialize a lock that has been allocated on the stack, or as part of a larger structure. It is not necessary to initialise a reader-writer lock that has been statically allocated. |[<!-- language="C" --> typedef struct { GRWLock l; ... } Blob; Blob *b; b = g_new (Blob, 1); g_rw_lock_init (&b->l); ]| To undo the effect of g_rw_lock_init() when a lock is no longer needed, use g_rw_lock_clear(). Calling g_rw_lock_init() on an already initialized #GRWLock leads to undefined behaviour. an uninitialized #GRWLock Obtain a read lock on @rw_lock. If another thread currently holds the write lock on @rw_lock, the current thread will block until the write lock was (held and) released. If another thread does not hold the write lock, but is waiting for it, it is implementation defined whether the reader or writer will block. Read locks can be taken recursively. Calling g_rw_lock_reader_lock() while the current thread already owns a write lock leads to undefined behaviour. Read locks however can be taken recursively, in which case you need to make sure to call g_rw_lock_reader_unlock() the same amount of times. It is implementation-defined how many read locks are allowed to be held on the same lock simultaneously. If the limit is hit, or if a deadlock is detected, a critical warning will be emitted. a #GRWLock Tries to obtain a read lock on @rw_lock and returns %TRUE if the read lock was successfully obtained. Otherwise it returns %FALSE. %TRUE if @rw_lock could be locked a #GRWLock Release a read lock on @rw_lock. Calling g_rw_lock_reader_unlock() on a lock that is not held by the current thread leads to undefined behaviour. a #GRWLock Obtain a write lock on @rw_lock. If another thread currently holds a read or write lock on @rw_lock, the current thread will block until all other threads have dropped their locks on @rw_lock. Calling g_rw_lock_writer_lock() while the current thread already owns a read or write lock on @rw_lock leads to undefined behaviour. a #GRWLock Tries to obtain a write lock on @rw_lock. If another thread currently holds a read or write lock on @rw_lock, it immediately returns %FALSE. Otherwise it locks @rw_lock and returns %TRUE. %TRUE if @rw_lock could be locked a #GRWLock Release a write lock on @rw_lock. Calling g_rw_lock_writer_unlock() on a lock that is not held by the current thread leads to undefined behaviour. a #GRWLock Declare a [type@GLib.RWLockReaderLocker] variable with `g_autoptr()` and lock for reading. The mutex will be unlocked automatically when leaving the scope. The variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it is not used in the scope. This feature is only supported on GCC and clang. This macro is not defined on other compilers and should not be used in programs that are intended to be portable to those compilers. Note that this should be used in a place where it is allowed to declare a variable, which could be before any statement in the case `-Wdeclaration-after-statement` is used, or C standard prior to C99. ```c { G_RW_LOCK_READER_AUTO_LOCK (&obj->rw_lock, locker); obj->stuff_with_lock (); if (condition) { // No need to unlock return; } // Unlock before end of scope g_clear_pointer (&locker, g_rw_lock_reader_locker_free); obj->stuff_without_lock (); } ``` a [type@GLib.RWLock] a variable name to be declared Declare a [type@GLib.RWLockWriterLocker] variable with `g_autoptr()` and lock for writing. The mutex will be unlocked automatically when leaving the scope. The variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it is not used in the scope. This feature is only supported on GCC and clang. This macro is not defined on other compilers and should not be used in programs that are intended to be portable to those compilers. Note that this should be used in a place where it is allowed to declare a variable, which could be before any statement in the case `-Wdeclaration-after-statement` is used, or C standard prior to C99. ```c { G_RW_LOCK_WRITER_AUTO_LOCK (&obj->rw_lock, locker); obj->stuff_with_lock (); if (condition) { // No need to unlock return; } // Unlock before end of scope g_clear_pointer (&locker, g_rw_lock_writer_locker_free); obj->stuff_without_lock (); } ``` a [type@GLib.RWLock] a variable name to be declared The GRand struct is an opaque data structure. It should only be accessed through the g_rand_* functions. Creates a new random number generator initialized with a seed taken either from `/dev/urandom` (if existing) or from the current time (as a fallback). On Windows, the seed is taken from rand_s(). the new #GRand Creates a new random number generator initialized with @seed. the new #GRand a value to initialize the random number generator Creates a new random number generator initialized with @seed. the new #GRand an array of seeds to initialize the random number generator an array of seeds to initialize the random number generator Copies a #GRand into a new one with the same exact state as before. This way you can take a snapshot of the random number generator for replaying later. the new #GRand a #GRand Returns the next random #gdouble from @rand_ equally distributed over the range [0..1). a random number a #GRand Returns the next random #gdouble from @rand_ equally distributed over the range [@begin..@end). a random number a #GRand lower closed bound of the interval upper open bound of the interval Frees the memory allocated for the #GRand. a #GRand Returns the next random #guint32 from @rand_ equally distributed over the range [0..2^32-1]. a random number a #GRand Returns the next random #gint32 from @rand_ equally distributed over the range [@begin..@end-1]. a random number a #GRand lower closed bound of the interval upper open bound of the interval Sets the seed for the random number generator #GRand to @seed. a #GRand a value to reinitialize the random number generator Initializes the random number generator by an array of longs. Array can be of arbitrary size, though only the first 624 values are taken. This function is useful if you have many low entropy seeds, or if you require more then 32 bits of actual entropy for your application. a #GRand array to initialize with length of array The GRecMutex struct is an opaque data structure to represent a recursive mutex. It is similar to a #GMutex with the difference that it is possible to lock a GRecMutex multiple times in the same thread without deadlock. When doing so, care has to be taken to unlock the recursive mutex as often as it has been locked. If a #GRecMutex is allocated in static storage then it can be used without initialisation. Otherwise, you should call g_rec_mutex_init() on it and g_rec_mutex_clear() when done. A GRecMutex should only be accessed with the g_rec_mutex_ functions. Frees the resources allocated to a recursive mutex with g_rec_mutex_init(). This function should not be used with a #GRecMutex that has been statically allocated. Calling g_rec_mutex_clear() on a locked recursive mutex leads to undefined behaviour. an initialized #GRecMutex Initializes a #GRecMutex so that it can be used. This function is useful to initialize a recursive mutex that has been allocated on the stack, or as part of a larger structure. It is not necessary to initialise a recursive mutex that has been statically allocated. |[<!-- language="C" --> typedef struct { GRecMutex m; ... } Blob; Blob *b; b = g_new (Blob, 1); g_rec_mutex_init (&b->m); ]| Calling g_rec_mutex_init() on an already initialized #GRecMutex leads to undefined behaviour. To undo the effect of g_rec_mutex_init() when a recursive mutex is no longer needed, use g_rec_mutex_clear(). an uninitialized #GRecMutex Locks @rec_mutex. If @rec_mutex is already locked by another thread, the current thread will block until @rec_mutex is unlocked by the other thread. If @rec_mutex is already locked by the current thread, the 'lock count' of @rec_mutex is increased. The mutex will only become available again when it is unlocked as many times as it has been locked. a #GRecMutex Tries to lock @rec_mutex. If @rec_mutex is already locked by another thread, it immediately returns %FALSE. Otherwise it locks @rec_mutex and returns %TRUE. %TRUE if @rec_mutex could be locked a #GRecMutex Unlocks @rec_mutex. If another thread is blocked in a g_rec_mutex_lock() call for @rec_mutex, it will become unblocked and can lock @rec_mutex itself. Calling g_rec_mutex_unlock() on a recursive mutex that is not locked by the current thread leads to undefined behaviour. a #GRecMutex A `GRegex` is a compiled form of a regular expression. After instantiating a `GRegex`, you can use its methods to find matches in a string, replace matches within a string, or split the string at matches. `GRegex` implements regular expression pattern matching using syntax and semantics (such as character classes, quantifiers, and capture groups) similar to Perl regular expression. See the [PCRE documentation](man:pcre2pattern(3)) for details. A typical scenario for regex pattern matching is to check if a string matches a pattern. The following statements implement this scenario. ``` { .c } const char *regex_pattern = ".*GLib.*"; const char *string_to_search = "You will love the GLib implementation of regex"; g_autoptr(GMatchInfo) match_info = NULL; g_autoptr(GRegex) regex = NULL; regex = g_regex_new (regex_pattern, G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, NULL); g_assert (regex != NULL); if (g_regex_match (regex, string_to_search, G_REGEX_MATCH_DEFAULT, &match_info)) { int start_pos, end_pos; g_match_info_fetch_pos (match_info, 0, &start_pos, &end_pos); g_print ("Match successful! Overall pattern matches bytes %d to %d\n", start_pos, end_pos); } else { g_print ("No match!\n"); } ``` The constructor for `GRegex` includes two sets of bitmapped flags: * [flags@GLib.RegexCompileFlags]—These flags control how GLib compiles the regex. There are options for case sensitivity, multiline, ignoring whitespace, etc. * [flags@GLib.RegexMatchFlags]—These flags control `GRegex`’s matching behavior, such as anchoring and customizing definitions for newline characters. Some regex patterns include backslash assertions, such as `\d` (digit) or `\D` (non-digit). The regex pattern must escape those backslashes. For example, the pattern `"\\d\\D"` matches a digit followed by a non-digit. GLib’s implementation of pattern matching includes a `start_position` argument for some of the match, replace, and split methods. Specifying a start position provides flexibility when you want to ignore the first _n_ characters of a string, but want to incorporate backslash assertions at character _n_ - 1. For example, a database field contains inconsistent spelling for a job title: `healthcare provider` and `health-care provider`. The database manager wants to make the spelling consistent by adding a hyphen when it is missing. The following regex pattern tests for the string `care` preceded by a non-word boundary character (instead of a hyphen) and followed by a space. ``` { .c } const char *regex_pattern = "\\Bcare\\s"; ``` An efficient way to match with this pattern is to start examining at `start_position` 6 in the string `healthcare` or `health-care`. ``` { .c } const char *regex_pattern = "\\Bcare\\s"; const char *string_to_search = "healthcare provider"; g_autoptr(GMatchInfo) match_info = NULL; g_autoptr(GRegex) regex = NULL; regex = g_regex_new ( regex_pattern, G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, NULL); g_assert (regex != NULL); g_regex_match_full ( regex, string_to_search, -1, 6, // position of 'c' in the test string. G_REGEX_MATCH_DEFAULT, &match_info, NULL); ``` The method [method@GLib.Regex.match_full] (and other methods implementing `start_pos`) allow for lookback before the start position to determine if the previous character satisfies an assertion. Unless you set the [flags@GLib.RegexCompileFlags.RAW] as one of the `GRegexCompileFlags`, all the strings passed to `GRegex` methods must be encoded in UTF-8. The lengths and the positions inside the strings are in bytes and not in characters, so, for instance, `\xc3\xa0` (i.e., `à`) is two bytes long but it is treated as a single character. If you set `G_REGEX_RAW`, the strings can be non-valid UTF-8 strings and a byte is treated as a character, so `\xc3\xa0` is two bytes and two characters long. Regarding line endings, `\n` matches a `\n` character, and `\r` matches a `\r` character. More generally, `\R` matches all typical line endings: CR + LF (`\r\n`), LF (linefeed, U+000A, `\n`), VT (vertical tab, U+000B, `\v`), FF (formfeed, U+000C, `\f`), CR (carriage return, U+000D, `\r`), NEL (next line, U+0085), LS (line separator, U+2028), and PS (paragraph separator, U+2029). The behaviour of the dot, circumflex, and dollar metacharacters are affected by newline characters. By default, `GRegex` matches any newline character matched by `\R`. You can limit the matched newline characters by specifying the [flags@GLib.RegexMatchFlags.NEWLINE_CR], [flags@GLib.RegexMatchFlags.NEWLINE_LF], and [flags@GLib.RegexMatchFlags.NEWLINE_CRLF] compile options, and with [flags@GLib.RegexMatchFlags.NEWLINE_ANY], [flags@GLib.RegexMatchFlags.NEWLINE_CR], [flags@GLib.RegexMatchFlags.NEWLINE_LF] and [flags@GLib.RegexMatchFlags.NEWLINE_CRLF] match options. These settings are also relevant when compiling a pattern if [flags@GLib.RegexCompileFlags.EXTENDED] is set and an unescaped `#` outside a character class is encountered. This indicates a comment that lasts until after the next newline. Because `GRegex` does not modify its internal state between creation and destruction, you can create and modify the same `GRegex` instance from different threads. In contrast, [struct@GLib.MatchInfo] is not thread safe. The regular expression low-level functionalities are obtained through the excellent [PCRE](http://www.pcre.org/) library written by Philip Hazel. Compiles the regular expression to an internal form, and does the initial setup of the #GRegex structure. a #GRegex structure or %NULL if an error occurred. Call g_regex_unref() when you are done with it the regular expression compile options for the regular expression, or 0 match options for the regular expression, or 0 Returns the number of capturing subpatterns in the pattern. the number of capturing subpatterns a #GRegex Returns the compile options that @regex was created with. Depending on the version of PCRE that is used, this may or may not include flags set by option expressions such as `(?i)` found at the top-level within the compiled pattern. flags from #GRegexCompileFlags a #GRegex Checks whether the pattern contains explicit CR or LF references. %TRUE if the pattern contains explicit CR or LF references a #GRegex structure Returns the match options that @regex was created with. flags from #GRegexMatchFlags a #GRegex Returns the number of the highest back reference in the pattern, or 0 if the pattern does not contain back references. the number of the highest back reference a #GRegex Gets the number of characters in the longest lookbehind assertion in the pattern. This information is useful when doing multi-segment matching using the partial matching facilities. the number of characters in the longest lookbehind assertion. a #GRegex structure Gets the pattern string associated with @regex, i.e. a copy of the string passed to g_regex_new(). the pattern of @regex a #GRegex structure Retrieves the number of the subexpression named @name. The number of the subexpression or -1 if @name does not exists #GRegex structure name of the subexpression Scans for a match in @string for the pattern in @regex. The @match_options are combined with the match options specified when the @regex structure was created, letting you have more flexibility in reusing #GRegex structures. Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8. A #GMatchInfo structure, used to get information on the match, is stored in @match_info if not %NULL. Note that if @match_info is not %NULL then it is created even if the function returns %FALSE, i.e. you must free it regardless if regular expression actually matched. To retrieve all the non-overlapping matches of the pattern in string you can use g_match_info_next(). |[<!-- language="C" --> static void print_uppercase_words (const gchar *string) { // Print all uppercase-only words. GRegex *regex; GMatchInfo *match_info; regex = g_regex_new ("[A-Z]+", G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, NULL); g_regex_match (regex, string, 0, &match_info); while (g_match_info_matches (match_info)) { gchar *word = g_match_info_fetch (match_info, 0); g_print ("Found: %s\n", word); g_free (word); g_match_info_next (match_info, NULL); } g_match_info_free (match_info); g_regex_unref (regex); } ]| @string is not copied and is used in #GMatchInfo internally. If you use any #GMatchInfo method (except g_match_info_free()) after freeing or modifying @string then the behaviour is undefined. %TRUE is the string matched, %FALSE otherwise a #GRegex structure from g_regex_new() the string to scan for matches match options pointer to location where to store the #GMatchInfo, or %NULL if you do not need it Using the standard algorithm for regular expression matching only the longest match in the string is retrieved. This function uses a different algorithm so it can retrieve all the possible matches. For more documentation see g_regex_match_all_full(). A #GMatchInfo structure, used to get information on the match, is stored in @match_info if not %NULL. Note that if @match_info is not %NULL then it is created even if the function returns %FALSE, i.e. you must free it regardless if regular expression actually matched. @string is not copied and is used in #GMatchInfo internally. If you use any #GMatchInfo method (except g_match_info_free()) after freeing or modifying @string then the behaviour is undefined. %TRUE is the string matched, %FALSE otherwise a #GRegex structure from g_regex_new() the string to scan for matches match options pointer to location where to store the #GMatchInfo, or %NULL if you do not need it Using the standard algorithm for regular expression matching only the longest match in the @string is retrieved, it is not possible to obtain all the available matches. For instance matching `"<a> <b> <c>"` against the pattern `"<.*>"` you get `"<a> <b> <c>"`. This function uses a different algorithm (called DFA, i.e. deterministic finite automaton), so it can retrieve all the possible matches, all starting at the same point in the string. For instance matching `"<a> <b> <c>"` against the pattern `"<.*>"` you would obtain three matches: `"<a> <b> <c>"`, `"<a> <b>"` and `"<a>"`. The number of matched strings is retrieved using g_match_info_get_match_count(). To obtain the matched strings and their position you can use, respectively, g_match_info_fetch() and g_match_info_fetch_pos(). Note that the strings are returned in reverse order of length; that is, the longest matching string is given first. Note that the DFA algorithm is slower than the standard one and it is not able to capture substrings, so backreferences do not work. Setting @start_position differs from just passing over a shortened string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern that begins with any kind of lookbehind assertion, such as "\b". Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8. A #GMatchInfo structure, used to get information on the match, is stored in @match_info if not %NULL. Note that if @match_info is not %NULL then it is created even if the function returns %FALSE, i.e. you must free it regardless if regular expression actually matched. @string is not copied and is used in #GMatchInfo internally. If you use any #GMatchInfo method (except g_match_info_free()) after freeing or modifying @string then the behaviour is undefined. %TRUE is the string matched, %FALSE otherwise a #GRegex structure from g_regex_new() the string to scan for matches the length of @string, in bytes, or -1 if @string is nul-terminated starting index of the string to match, in bytes match options pointer to location where to store the #GMatchInfo, or %NULL if you do not need it Scans for a match in @string for the pattern in @regex. The @match_options are combined with the match options specified when the @regex structure was created, letting you have more flexibility in reusing #GRegex structures. Setting @start_position differs from just passing over a shortened string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern that begins with any kind of lookbehind assertion, such as "\b". Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8. A #GMatchInfo structure, used to get information on the match, is stored in @match_info if not %NULL. Note that if @match_info is not %NULL then it is created even if the function returns %FALSE, i.e. you must free it regardless if regular expression actually matched. @string is not copied and is used in #GMatchInfo internally. If you use any #GMatchInfo method (except g_match_info_free()) after freeing or modifying @string then the behaviour is undefined. To retrieve all the non-overlapping matches of the pattern in string you can use g_match_info_next(). |[<!-- language="C" --> static void print_uppercase_words (const gchar *string) { // Print all uppercase-only words. GRegex *regex; GMatchInfo *match_info; GError *error = NULL; regex = g_regex_new ("[A-Z]+", G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, NULL); g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error); while (g_match_info_matches (match_info)) { gchar *word = g_match_info_fetch (match_info, 0); g_print ("Found: %s\n", word); g_free (word); g_match_info_next (match_info, &error); } g_match_info_free (match_info); g_regex_unref (regex); if (error != NULL) { g_printerr ("Error while matching: %s\n", error->message); g_error_free (error); } } ]| %TRUE is the string matched, %FALSE otherwise a #GRegex structure from g_regex_new() the string to scan for matches the length of @string, in bytes, or -1 if @string is nul-terminated starting index of the string to match, in bytes match options pointer to location where to store the #GMatchInfo, or %NULL if you do not need it Increases reference count of @regex by 1. @regex a #GRegex Replaces all occurrences of the pattern in @regex with the replacement text. Backreferences of the form `\number` or `\g<number>` in the replacement text are interpolated by the number-th captured subexpression of the match, `\g<name>` refers to the captured subexpression with the given name. `\0` refers to the complete match, but `\0` followed by a number is the octal representation of a character. To include a literal `\` in the replacement, write `\\\\`. There are also escapes that changes the case of the following text: - \l: Convert to lower case the next character - \u: Convert to upper case the next character - \L: Convert to lower case till \E - \U: Convert to upper case till \E - \E: End case modification If you do not need to use backreferences use g_regex_replace_literal(). The @replacement string must be UTF-8 encoded even if %G_REGEX_RAW was passed to g_regex_new(). If you want to use not UTF-8 encoded strings you can use g_regex_replace_literal(). Setting @start_position differs from just passing over a shortened string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern that begins with any kind of lookbehind assertion, such as "\b". a newly allocated string containing the replacements a #GRegex structure the string to perform matches against the length of @string, in bytes, or -1 if @string is nul-terminated starting index of the string to match, in bytes text to replace each match with options for the match Replaces occurrences of the pattern in regex with the output of @eval for that occurrence. Setting @start_position differs from just passing over a shortened string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern that begins with any kind of lookbehind assertion, such as "\b". The following example uses g_regex_replace_eval() to replace multiple strings at once: |[<!-- language="C" --> static gboolean eval_cb (const GMatchInfo *info, GString *res, gpointer data) { gchar *match; gchar *r; match = g_match_info_fetch (info, 0); r = g_hash_table_lookup ((GHashTable *)data, match); g_string_append (res, r); g_free (match); return FALSE; } ... GRegex *reg; GHashTable *h; gchar *res; h = g_hash_table_new (g_str_hash, g_str_equal); g_hash_table_insert (h, "1", "ONE"); g_hash_table_insert (h, "2", "TWO"); g_hash_table_insert (h, "3", "THREE"); g_hash_table_insert (h, "4", "FOUR"); reg = g_regex_new ("1|2|3|4", G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, NULL); res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL); g_hash_table_destroy (h); ... ]| a newly allocated string containing the replacements a #GRegex structure from g_regex_new() string to perform matches against the length of @string, in bytes, or -1 if @string is nul-terminated starting index of the string to match, in bytes options for the match a function to call for each match user data to pass to the function Replaces all occurrences of the pattern in @regex with the replacement text. @replacement is replaced literally, to include backreferences use g_regex_replace(). Setting @start_position differs from just passing over a shortened string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern that begins with any kind of lookbehind assertion, such as "\b". a newly allocated string containing the replacements a #GRegex structure the string to perform matches against the length of @string, in bytes, or -1 if @string is nul-terminated starting index of the string to match, in bytes text to replace each match with options for the match Breaks the string on the pattern, and returns an array of the tokens. If the pattern contains capturing parentheses, then the text for each of the substrings will also be returned. If the pattern does not match anywhere in the string, then the whole string is returned as the first token. As a special case, the result of splitting the empty string "" is an empty vector, not a vector containing a single string. The reason for this special case is that being able to represent an empty vector is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you'll need to check for the empty string before calling this function. A pattern that can match empty strings splits @string into separate characters wherever it matches the empty string between characters. For example splitting "ab c" using as a separator "\s*", you will get "a", "b" and "c". a %NULL-terminated gchar ** array. Free it using g_strfreev() a #GRegex structure the string to split with the pattern match time option flags Breaks the string on the pattern, and returns an array of the tokens. If the pattern contains capturing parentheses, then the text for each of the substrings will also be returned. If the pattern does not match anywhere in the string, then the whole string is returned as the first token. As a special case, the result of splitting the empty string "" is an empty vector, not a vector containing a single string. The reason for this special case is that being able to represent an empty vector is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you'll need to check for the empty string before calling this function. A pattern that can match empty strings splits @string into separate characters wherever it matches the empty string between characters. For example splitting "ab c" using as a separator "\s*", you will get "a", "b" and "c". Setting @start_position differs from just passing over a shortened string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern that begins with any kind of lookbehind assertion, such as "\b". a %NULL-terminated gchar ** array. Free it using g_strfreev() a #GRegex structure the string to split with the pattern the length of @string, in bytes, or -1 if @string is nul-terminated starting index of the string to match, in bytes match time option flags the maximum number of tokens to split @string into. If this is less than 1, the string is split completely Decreases reference count of @regex by 1. When reference count drops to zero, it frees all the memory associated with the regex structure. a #GRegex Checks whether @replacement is a valid replacement string (see g_regex_replace()), i.e. that all escape sequences in it are valid. If @has_references is not %NULL then @replacement is checked for pattern references. For instance, replacement text 'foo\n' does not contain references and may be evaluated without information about actual match, but '\0\1' (whole match followed by first subpattern) requires valid #GMatchInfo object. whether @replacement is a valid replacement string the replacement string location to store information about references in @replacement or %NULL Escapes the nul characters in @string to "\x00". It can be used to compile a regex with embedded nul characters. For completeness, @length can be -1 for a nul-terminated string. In this case the output string will be of course equal to @string. a newly-allocated escaped string the string to escape the length of @string Escapes the special characters used for regular expressions in @string, for instance "a.b*c" becomes "a\.b\*c". This function is useful to dynamically generate regular expressions. @string can contain nul characters that are replaced with "\0", in this case remember to specify the correct length of @string in @length. a newly-allocated escaped string the string to escape the length of @string, in bytes, or -1 if @string is nul-terminated Scans for a match in @string for @pattern. This function is equivalent to g_regex_match() but it does not require to compile the pattern with g_regex_new(), avoiding some lines of code when you need just to do a match without extracting substrings, capture counts, and so on. If this function is to be called on the same @pattern more than once, it's more efficient to compile the pattern once with g_regex_new() and then use g_regex_match(). %TRUE if the string matched, %FALSE otherwise the regular expression the string to scan for matches compile options for the regular expression, or 0 match options, or 0 Breaks the string on the pattern, and returns an array of the tokens. If the pattern contains capturing parentheses, then the text for each of the substrings will also be returned. If the pattern does not match anywhere in the string, then the whole string is returned as the first token. This function is equivalent to g_regex_split() but it does not require to compile the pattern with g_regex_new(), avoiding some lines of code when you need just to do a split without extracting substrings, capture counts, and so on. If this function is to be called on the same @pattern more than once, it's more efficient to compile the pattern once with g_regex_new() and then use g_regex_split(). As a special case, the result of splitting the empty string "" is an empty vector, not a vector containing a single string. The reason for this special case is that being able to represent an empty vector is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you'll need to check for the empty string before calling this function. A pattern that can match empty strings splits @string into separate characters wherever it matches the empty string between characters. For example splitting "ab c" using as a separator "\s*", you will get "a", "b" and "c". a %NULL-terminated array of strings. Free it using g_strfreev() the regular expression the string to scan for matches compile options for the regular expression, or 0 match options, or 0 Flags specifying compile-time options. No special options set. Since: 2.74 Letters in the pattern match both upper- and lowercase letters. This option can be changed within a pattern by a "(?i)" option setting. By default, GRegex treats the strings as consisting of a single line of characters (even if it actually contains newlines). The "start of line" metacharacter ("^") matches only at the start of the string, while the "end of line" metacharacter ("$") matches only at the end of the string, or before a terminating newline (unless %G_REGEX_DOLLAR_ENDONLY is set). When %G_REGEX_MULTILINE is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the string, respectively, as well as at the very start and end. This can be changed within a pattern by a "(?m)" option setting. A dot metacharacter (".") in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option can be changed within a pattern by a ("?s") option setting. Whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. Whitespace does not include the VT character (code 11). In addition, characters between an unescaped "#" outside a character class and the next newline character, inclusive, are also ignored. This can be changed within a pattern by a "(?x)" option setting. The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharacter. A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if %G_REGEX_MULTILINE is set. Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern. Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way). Since 2.74 and the port to pcre2, requests JIT compilation, which, if the just-in-time compiler is available, further processes a compiled pattern into machine code that executes much faster. However, it comes at the cost of extra processing before the match is performed, so it is most beneficial to use this when the same compiled pattern is used for matching many times. Before 2.74 this option used the built-in non-JIT optimizations in pcre1. Limits an unanchored pattern to match before (or at) the first newline. Since: 2.34 Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched. Usually any newline character or character sequence is recognized. If this option is set, the only recognized newline character is '\r'. Usually any newline character or character sequence is recognized. If this option is set, the only recognized newline character is '\n'. Error codes returned by regular expressions functions. Compilation of the regular expression failed. Optimization of the regular expression failed. Replacement failed due to an ill-formed replacement string. The match process failed. Internal error of the regular expression engine. Since 2.16 "\\" at end of pattern. Since 2.16 "\\c" at end of pattern. Since 2.16 Unrecognized character follows "\\". Since 2.16 Numbers out of order in "{}" quantifier. Since 2.16 Number too big in "{}" quantifier. Since 2.16 Missing terminating "]" for character class. Since 2.16 Invalid escape sequence in character class. Since 2.16 Range out of order in character class. Since 2.16 Nothing to repeat. Since 2.16 Unrecognized character after "(?", "(?<" or "(?P". Since 2.16 POSIX named classes are supported only within a class. Since 2.16 Missing terminating ")" or ")" without opening "(". Since 2.16 Reference to non-existent subpattern. Since 2.16 Missing terminating ")" after comment. Since 2.16 Regular expression too large. Since 2.16 Failed to get memory. Since 2.16 Lookbehind assertion is not fixed length. Since 2.16 Malformed number or name after "(?(". Since 2.16 Conditional group contains more than two branches. Since 2.16 Assertion expected after "(?(". Since 2.16 Unknown POSIX class name. Since 2.16 POSIX collating elements are not supported. Since 2.16 Character value in "\\x{...}" sequence is too large. Since 2.16 Invalid condition "(?(0)". Since 2.16 \\C not allowed in lookbehind assertion. Since 2.16 Recursive call could loop indefinitely. Since 2.16 Missing terminator in subpattern name. Since 2.16 Two named subpatterns have the same name. Since 2.16 Malformed "\\P" or "\\p" sequence. Since 2.16 Unknown property name after "\\P" or "\\p". Since 2.16 Subpattern name is too long (maximum 32 characters). Since 2.16 Too many named subpatterns (maximum 10,000). Since 2.16 Octal value is greater than "\\377". Since 2.16 "DEFINE" group contains more than one branch. Since 2.16 Repeating a "DEFINE" group is not allowed. This error is never raised. Since: 2.16 Deprecated: 2.34 Inconsistent newline options. Since 2.16 "\\g" is not followed by a braced, angle-bracketed, or quoted name or number, or by a plain number. Since: 2.16 relative reference must not be zero. Since: 2.34 the backtracing control verb used does not allow an argument. Since: 2.34 unknown backtracing control verb. Since: 2.34 number is too big in escape sequence. Since: 2.34 Missing subpattern name. Since: 2.34 Missing digit. Since 2.34 In JavaScript compatibility mode, "[" is an invalid data character. Since: 2.34 different names for subpatterns of the same number are not allowed. Since: 2.34 the backtracing control verb requires an argument. Since: 2.34 "\\c" must be followed by an ASCII character. Since: 2.34 "\\k" is not followed by a braced, angle-bracketed, or quoted name. Since: 2.34 "\\N" is not supported in a class. Since: 2.34 too many forward references. Since: 2.34 the name is too long in "(*MARK)", "(*PRUNE)", "(*SKIP)", or "(*THEN)". Since: 2.34 the character value in the \\u sequence is too large. Since: 2.34 Specifies the type of the function passed to g_regex_replace_eval(). It is called for each occurrence of the pattern in the string passed to g_regex_replace_eval(), and it should append the replacement to @result. %FALSE to continue the replacement process, %TRUE to stop it the #GMatchInfo generated by the match. Use g_match_info_get_regex() and g_match_info_get_string() if you need the #GRegex or the matched string. a #GString containing the new string user data passed to g_regex_replace_eval() Flags specifying match-time options. No special options set. Since: 2.74 The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharacter. Specifies that first character of the string is not the beginning of a line, so the circumflex metacharacter should not match before it. Setting this without %G_REGEX_MULTILINE (at compile time) causes circumflex never to match. This option affects only the behaviour of the circumflex metacharacter, it does not affect "\A". Specifies that the end of the subject string is not the end of a line, so the dollar metacharacter should not match it nor (except in multiline mode) a newline immediately before it. Setting this without %G_REGEX_MULTILINE (at compile time) causes dollar never to match. This option affects only the behaviour of the dollar metacharacter, it does not affect "\Z" or "\z". An empty string is not considered to be a valid match if this option is set. If there are alternatives in the pattern, they are tried. If all the alternatives match the empty string, the entire match fails. For example, if the pattern "a?b?" is applied to a string not beginning with "a" or "b", it matches the empty string at the start of the string. With this flag set, this match is not valid, so GRegex searches further into the string for occurrences of "a" or "b". Turns on the partial matching feature, for more documentation on partial matching see g_match_info_is_partial_match(). Overrides the newline definition set when creating a new #GRegex, setting the '\r' character as line terminator. Overrides the newline definition set when creating a new #GRegex, setting the '\n' character as line terminator. Overrides the newline definition set when creating a new #GRegex, setting the '\r\n' characters sequence as line terminator. Overrides the newline definition set when creating a new #GRegex, any Unicode newline sequence is recognised as a newline. These are '\r', '\n' and '\rn', and the single characters U+000B LINE TABULATION, U+000C FORM FEED (FF), U+0085 NEXT LINE (NEL), U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR. Overrides the newline definition set when creating a new #GRegex; any '\r', '\n', or '\r\n' character sequence is recognized as a newline. Since: 2.34 Overrides the newline definition for "\R" set when creating a new #GRegex; only '\r', '\n', or '\r\n' character sequences are recognized as a newline by "\R". Since: 2.34 Overrides the newline definition for "\R" set when creating a new #GRegex; any Unicode newline character or character sequence are recognized as a newline by "\R". These are '\r', '\n' and '\rn', and the single characters U+000B LINE TABULATION, U+000C FORM FEED (FF), U+0085 NEXT LINE (NEL), U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR. Since: 2.34 An alias for %G_REGEX_MATCH_PARTIAL. Since: 2.34 Turns on the partial matching feature. In contrast to to %G_REGEX_MATCH_PARTIAL_SOFT, this stops matching as soon as a partial match is found, without continuing to search for a possible complete match. See g_match_info_is_partial_match() for more information. Since: 2.34 Like %G_REGEX_MATCH_NOTEMPTY, but only applied to the start of the matched string. For anchored patterns this can only happen for pattern containing "\K". Since: 2.34 A `GRelation` is a table of data which can be indexed on any number of fields, rather like simple database tables. A `GRelation` contains a number of records, called tuples. Each record contains a number of fields. Records are not ordered, so it is not possible to find the record at a particular index. Note that `GRelation` tables are currently limited to 2 fields. To create a `GRelation`, use [func@GLib.Relation.new]. To specify which fields should be indexed, use [method@GLib.Relation.index]. Note that this must be called before any tuples are added to the `GRelation`. To add records to a `GRelation` use [method@GLib.Relation.insert]. To determine if a given record appears in a `GRelation`, use [method@GLib.Relation.exists]. Note that fields are compared directly, so pointers must point to the exact same position (i.e. different copies of the same string will not match.) To count the number of records which have a particular value in a given field, use [method@GLib.Relation.count]. To get all the records which have a particular value in a given field, use [method@GLib.Relation.select]. To access fields of the resulting records, use [method@GLib.Tuples.index]. To free the resulting records use [method@GLib.Tuples.destroy]. To delete all records which have a particular value in a given field, use [method@GLib.Relation.delete]. To destroy the `GRelation`, use [method@GLib.Relation.destroy]. To help debug `GRelation` objects, use [method@GLib.Relation.print]. `GRelation` has been marked as deprecated, since this API has never been fully implemented, is not very actively maintained and rarely used. Rarely used API Returns the number of tuples in a #GRelation that have the given value in the given field. Rarely used API the number of matches. a #GRelation. the value to compare with. the field of each record to match. Deletes any records from a #GRelation that have the given key value in the given field. Rarely used API the number of records deleted. a #GRelation. the value to compare with. the field of each record to match. Destroys the #GRelation, freeing all memory allocated. However, it does not free memory allocated for the tuple data, so you should free that first if appropriate. Rarely used API a #GRelation. Returns %TRUE if a record with the given values exists in a #GRelation. Note that the values are compared directly, so that, for example, two copies of the same string will not match. Rarely used API %TRUE if a record matches. a #GRelation. the fields of the record to compare. The number must match the number of fields in the #GRelation. Creates an index on the given field. Note that this must be called before any records are added to the #GRelation. Rarely used API a #GRelation. the field to index, counting from 0. a function to produce a hash value from the field data. a function to compare two values of the given field. Inserts a record into a #GRelation. Rarely used API a #GRelation. the fields of the record to add. These must match the number of fields in the #GRelation, and of type #gpointer or #gconstpointer. Outputs information about all records in a #GRelation, as well as the indexes. It is for debugging. Rarely used API a #GRelation. Returns all of the tuples which have the given key in the given field. Use g_tuples_index() to access the returned records. The returned records should be freed with g_tuples_destroy(). Rarely used API the records (tuples) that matched. a #GRelation. the value to compare with. the field of each record to match. Creates a new #GRelation with the given number of fields. Note that currently the number of fields must be 2. Rarely used API a new #GRelation. the number of fields. The search path separator character. This is ':' on UNIX machines and ';' under Windows. The search path separator as a string. This is ":" on UNIX machines and ";" under Windows. Returns the size of @member in the struct definition without having a declared instance of @struct_type. a structure type, e.g. #GOutputVector a field in the structure, e.g. `size` The #GSList struct is used for each element in the singly-linked list. holds the element's data, which can be a pointer to any kind of data, or any integer value using the [Type Conversion Macros](conversion-macros.html#conversion-macros) contains the link to the next element in the list. Allocates space for one #GSList element. It is called by the g_slist_append(), g_slist_prepend(), g_slist_insert() and g_slist_insert_sorted() functions and so is rarely used on its own. a pointer to the newly-allocated #GSList element. Adds a new element on to the end of the list. Note that the return value is the new start of the list if @list was empty; make sure you store the new value. Note that g_slist_append() has to traverse the entire list to find the end, which is inefficient when adding multiple elements. A common idiom to avoid the inefficiency is to prepend the elements and reverse the list when all elements have been added. |[<!-- language="C" --> // Notice that these are initialized to the empty list. GSList *list = NULL, *number_list = NULL; // This is a list of strings. list = g_slist_append (list, "first"); list = g_slist_append (list, "second"); // This is a list of integers. number_list = g_slist_append (number_list, GINT_TO_POINTER (27)); number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); ]| either @list or the new start of the #GSList if @list was %NULL a #GSList the data for the new element Adds the second #GSList onto the end of the first #GSList. Note that the elements of the second #GSList are not copied. They are used directly. the start of the new #GSList a #GSList the #GSList to add to the end of the first #GSList Copies a #GSList. Note that this is a "shallow" copy. If the list elements consist of pointers to data, the pointers are copied but the actual data isn't. See g_slist_copy_deep() if you need to copy the data as well. a copy of @list a #GSList Makes a full (deep) copy of a #GSList. In contrast with g_slist_copy(), this function uses @func to make a copy of each list element, in addition to copying the list container itself. @func, as a #GCopyFunc, takes two arguments, the data to be copied and a @user_data pointer. On common processor architectures, it's safe to pass %NULL as @user_data if the copy function takes only one argument. You may get compiler warnings from this though if compiling with GCC’s `-Wcast-function-type` warning. For instance, if @list holds a list of GObjects, you can do: |[<!-- language="C" --> another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL); ]| And, to entirely free the new list, you could do: |[<!-- language="C" --> g_slist_free_full (another_list, g_object_unref); ]| a full copy of @list, use g_slist_free_full() to free it a #GSList a copy function used to copy every element in the list user data passed to the copy function @func, or #NULL Removes the node link_ from the list and frees it. Compare this to g_slist_remove_link() which removes the node without freeing it. Removing arbitrary nodes from a singly-linked list requires time that is proportional to the length of the list (ie. O(n)). If you find yourself using g_slist_delete_link() frequently, you should consider a different data structure, such as the doubly-linked #GList. the new head of @list a #GSList node to delete Finds the element in a #GSList which contains the given data. the found #GSList element, or %NULL if it is not found a #GSList the element data to find Finds an element in a #GSList, using a supplied function to find the desired element. It iterates over the list, calling the given function which should return 0 when the desired element is found. The function takes two #gconstpointer arguments, the #GSList element's data as the first argument and the given user data. the found #GSList element, or %NULL if it is not found a #GSList user data passed to the function the function to call for each element. It should return 0 when the desired element is found Calls a function for each element of a #GSList. It is safe for @func to remove the element from @list, but it must not modify any part of the list after that element. a #GSList the function to call with each element's data user data to pass to the function Frees all of the memory used by a #GSList. The freed elements are returned to the slice allocator. If list elements contain dynamically-allocated memory, you should either use g_slist_free_full() or free them manually first. It can be combined with g_steal_pointer() to ensure the list head pointer is not left dangling: |[<!-- language="C" --> GSList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/ g_slist_free (g_steal_pointer (&list_of_borrowed_things)); ]| the first link of a #GSList Frees one #GSList element. It is usually used after g_slist_remove_link(). a #GSList element Convenience method, which frees all the memory used by a #GSList, and calls the specified destroy function on every element's data. @free_func must not modify the list (eg, by removing the freed element from it). It can be combined with g_steal_pointer() to ensure the list head pointer is not left dangling ­— this also has the nice property that the head pointer is cleared before any of the list elements are freed, to prevent double frees from @free_func: |[<!-- language="C" --> GSList *list_of_owned_things = …; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/ g_slist_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref); ]| the first link of a #GSList the function to be called to free each element's data Gets the position of the element containing the given data (starting from 0). the index of the element containing the data, or -1 if the data is not found a #GSList the data to find Inserts a new element into the list at the given position. the (possibly changed) start of the #GSList a #GSList the data for the new element the position to insert the element. If this is negative, or is larger than the number of elements in the list, the new element is added on to the end of the list. Inserts a node before @sibling containing @data. the new head of the list. a #GSList node to insert @data before data to put in the newly-inserted node Inserts a new element into the list, using the given comparison function to determine its position. the new start of the #GSList a #GSList the data for the new element the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. Inserts a new element into the list, using the given comparison function to determine its position. the new start of the #GSList a #GSList the data for the new element the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. data to pass to comparison function Gets the last element in a #GSList. This function iterates over the whole list. the last element in the #GSList, or %NULL if the #GSList has no elements a #GSList Gets the number of elements in a #GSList. This function iterates over the whole list to count its elements. To check whether the list is non-empty, it is faster to check @list against %NULL. the number of elements in the #GSList a #GSList Gets the element at the given position in a #GSList. the element, or %NULL if the position is off the end of the #GSList a #GSList the position of the element, counting from 0 Gets the data of the element at the given position. the element's data, or %NULL if the position is off the end of the #GSList a #GSList the position of the element Gets the position of the given element in the #GSList (starting from 0). the position of the element in the #GSList, or -1 if the element is not found a #GSList an element in the #GSList Adds a new element on to the start of the list. Note that the return value is the new start of the list, which will have changed, so make sure you store the new value. |[<!-- language="C" --> // Notice that it is initialized to the empty list. GSList *list = NULL; list = g_slist_prepend (list, "last"); list = g_slist_prepend (list, "first"); ]| a pointer to the newly prepended element, which is the new start of the #GSList a #GSList the data for the new element Removes an element from a #GSList. If two elements contain the same data, only the first is removed. If none of the elements contain the data, the #GSList is unchanged. the new start of the #GSList a #GSList the data of the element to remove Removes all list nodes with data equal to @data. Returns the new head of the list. Contrast with g_slist_remove() which removes only the first node matching the given data. new head of @list a #GSList data to remove Removes an element from a #GSList, without freeing the element. The removed element's next link is set to %NULL, so that it becomes a self-contained list with one element. Removing arbitrary nodes from a singly-linked list requires time that is proportional to the length of the list (ie. O(n)). If you find yourself using g_slist_remove_link() frequently, you should consider a different data structure, such as the doubly-linked #GList. the new start of the #GSList, without the element a #GSList an element in the #GSList Reverses a #GSList. the start of the reversed #GSList a #GSList Sorts a #GSList using the given comparison function. The algorithm used is a stable sort. the start of the sorted #GSList a #GSList the comparison function used to sort the #GSList. This function is passed the data from 2 elements of the #GSList and should return 0 if they are equal, a negative value if the first element comes before the second, or a positive value if the first element comes after the second. Like g_slist_sort(), but the sort function accepts a user data argument. new head of the list a #GSList comparison function data to pass to comparison function Use this macro as the return value of a [callback@GLib.SourceFunc] to leave the [struct@GLib.Source] in the main loop. Cast a function pointer to a [callback@GLib.SourceFunc], suppressing warnings from GCC 8 onwards with `-Wextra` or `-Wcast-function-type` enabled about the function types being incompatible. For example, the correct type of callback for a source created by [func@GLib.child_watch_source_new] is #GChildWatchFunc, which accepts more arguments than [callback@GLib.SourceFunc]. Casting the function with `(GSourceFunc)` to call [method@GLib.Source.set_callback] will trigger a warning, even though it will be cast back to the correct type before it is called by the source. a function pointer. Use this macro as the return value of a [callback@GLib.SourceFunc] to remove the [struct@GLib.Source] from the main loop. The square root of two. The G_STATIC_ASSERT() macro lets the programmer check a condition at compile time, the condition needs to be compile time computable. The macro can be used in any place where a typedef is valid. A typedef is generally allowed in exactly the same places that a variable declaration is allowed. For this reason, you should not use G_STATIC_ASSERT() in the middle of blocks of code. The macro should only be used once per source code line. a constant expression The G_STATIC_ASSERT_EXPR() macro lets the programmer check a condition at compile time. The condition needs to be compile time computable. Unlike G_STATIC_ASSERT(), this macro evaluates to an expression and, as such, can be used in the middle of other expressions. Its value should be ignored. This can be accomplished by placing it as the first argument of a comma expression. |[<!-- language="C" --> #define ADD_ONE_TO_INT(x) \ (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1)) ]| a constant expression Accepts a macro or a string and converts it into a string after preprocessor argument expansion. For example, the following code: |[<!-- language="C" --> #define AGE 27 const gchar *greeting = G_STRINGIFY (AGE) " today!"; ]| is transformed by the preprocessor into (code equivalent to): |[<!-- language="C" --> const gchar *greeting = "27 today!"; ]| a macro or a string Returns a member of a structure at a given offset, using the given type. the type of the struct field a pointer to a struct the offset of the field from the start of the struct, in bytes Returns an untyped pointer to a given offset of a struct. a pointer to a struct the offset from the start of the struct, in bytes Returns the offset, in bytes, of a member of a struct. Consider using standard C `offsetof()`, available since at least C89 and C++98, in new code (but note that `offsetof()` returns a `size_t` rather than a `long`). a structure type, e.g. #GtkWidget a field in the structure, e.g. @window The standard delimiters, used in [func@GLib.strdelimit]. `GScanner` provides a general-purpose lexical scanner. You should set @input_name after creating the scanner, since it is used by the default message handler when displaying warnings and errors. If you are scanning a file, the filename would be a good choice. The @user_data and @max_parse_errors fields are not used. If you need to associate extra data with the scanner you can place them here. If you want to use your own message handler you can set the @msg_handler field. The type of the message handler function is declared by #GScannerMsgFunc. unused unused g_scanner_error() increments this field name of input stream, featured by the default message handler quarked data link into the scanner configuration token parsed by the last g_scanner_get_next_token() value of the last token from g_scanner_get_next_token() line number of the last token from g_scanner_get_next_token() char number of the last token from g_scanner_get_next_token() token parsed by the last g_scanner_peek_next_token() value of the last token from g_scanner_peek_next_token() line number of the last token from g_scanner_peek_next_token() char number of the last token from g_scanner_peek_next_token() handler function for _warn and _error Returns the current line in the input stream (counting from 1). This is the line of the last token parsed via g_scanner_get_next_token(). the current line a #GScanner Returns the current position in the current line (counting from 0). This is the position of the last token parsed via g_scanner_get_next_token(). the current position on the line a #GScanner Gets the current token type. This is simply the @token field in the #GScanner structure. the current token type a #GScanner Gets the current token value. This is simply the @value field in the #GScanner structure. the current token value a #GScanner Frees all memory used by the #GScanner. a #GScanner Returns %TRUE if the scanner has reached the end of the file or text buffer. %TRUE if the scanner has reached the end of the file or text buffer a #GScanner Outputs an error message, via the #GScanner message handler. a #GScanner the message format. See the printf() documentation the parameters to insert into the format string Parses the next token just like g_scanner_peek_next_token() and also removes it from the input stream. The token data is placed in the @token, @value, @line, and @position fields of the #GScanner structure. the type of the token a #GScanner Prepares to scan a file. a #GScanner a file descriptor Prepares to scan a text buffer. a #GScanner the text buffer to scan the length of the text buffer Looks up a symbol in the current scope and return its value. If the symbol is not bound in the current scope, %NULL is returned. the value of @symbol in the current scope, or %NULL if @symbol is not bound in the current scope a #GScanner the symbol to look up Parses the next token, without removing it from the input stream. The token data is placed in the @next_token, @next_value, @next_line, and @next_position fields of the #GScanner structure. Note that, while the token is not removed from the input stream (i.e. the next call to g_scanner_get_next_token() will return the same token), it will not be reevaluated. This can lead to surprising results when changing scope or the scanner configuration after peeking the next token. Getting the next token after switching the scope or configuration will return whatever was peeked before, regardless of any symbols that may have been added or removed in the new scope. the type of the token a #GScanner Adds a symbol to the given scope. a #GScanner the scope id the symbol to add the value of the symbol Calls the given function for each of the symbol/value pairs in the given scope of the #GScanner. The function is passed the symbol and value of each pair, and the given @user_data parameter. a #GScanner the scope id the function to call for each symbol/value pair user data to pass to the function Looks up a symbol in a scope and return its value. If the symbol is not bound in the scope, %NULL is returned. the value of @symbol in the given scope, or %NULL if @symbol is not bound in the given scope. a #GScanner the scope id the symbol to look up Removes a symbol from a scope. a #GScanner the scope id the symbol to remove Sets the current scope. the old scope id a #GScanner the new scope id Rewinds the filedescriptor to the current buffer position and blows the file read ahead buffer. This is useful for third party uses of the scanners filedescriptor, which hooks onto the current scanning position. a #GScanner Outputs a message through the scanner's msg_handler, resulting from an unexpected token in the input stream. Note that you should not call g_scanner_peek_next_token() followed by g_scanner_unexp_token() without an intermediate call to g_scanner_get_next_token(), as g_scanner_unexp_token() evaluates the scanner's current token (not the peeked token) to construct part of the message. a #GScanner the expected token a string describing how the scanner's user refers to identifiers (%NULL defaults to "identifier"). This is used if @expected_token is %G_TOKEN_IDENTIFIER or %G_TOKEN_IDENTIFIER_NULL. a string describing how the scanner's user refers to symbols (%NULL defaults to "symbol"). This is used if @expected_token is %G_TOKEN_SYMBOL or any token value greater than %G_TOKEN_LAST. the name of the symbol, if the scanner's current token is a symbol. a message string to output at the end of the warning/error, or %NULL. if %TRUE it is output as an error. If %FALSE it is output as a warning. Outputs a warning message, via the #GScanner message handler. a #GScanner the message format. See the printf() documentation the parameters to insert into the format string Creates a new #GScanner. The @config_templ structure specifies the initial settings of the scanner, which are copied into the #GScanner @config field. If you pass %NULL then the default settings are used. the new #GScanner the initial scanner settings Specifies the #GScanner parser configuration. Most settings can be changed during the parsing phase and will affect the lexical parsing of the next unpeeked token. specifies which characters should be skipped by the scanner (the default is the whitespace characters: space, tab, carriage-return and line-feed). specifies the characters which can start identifiers (the default is %G_CSET_a_2_z, "_", and %G_CSET_A_2_Z). specifies the characters which can be used in identifiers, after the first character (the default is %G_CSET_a_2_z, "_0123456789", %G_CSET_A_2_Z, %G_CSET_LATINS, %G_CSET_LATINC). specifies the characters at the start and end of single-line comments. The default is "#\n" which means that single-line comments start with a '#' and continue until a '\n' (end of line). specifies if symbols are case sensitive (the default is %FALSE). specifies if multi-line comments are skipped and not returned as tokens (the default is %TRUE). specifies if single-line comments are skipped and not returned as tokens (the default is %TRUE). specifies if multi-line comments are recognized (the default is %TRUE). specifies if identifiers are recognized (the default is %TRUE). specifies if single-character identifiers are recognized (the default is %FALSE). specifies if %NULL is reported as %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE). specifies if symbols are recognized (the default is %TRUE). specifies if binary numbers are recognized (the default is %FALSE). specifies if octal numbers are recognized (the default is %TRUE). specifies if floating point numbers are recognized (the default is %TRUE). specifies if hexadecimal numbers are recognized (the default is %TRUE). specifies if '$' is recognized as a prefix for hexadecimal numbers (the default is %FALSE). specifies if strings can be enclosed in single quotes (the default is %TRUE). specifies if strings can be enclosed in double quotes (the default is %TRUE). specifies if binary, octal and hexadecimal numbers are reported as %G_TOKEN_INT (the default is %TRUE). specifies if all numbers are reported as %G_TOKEN_FLOAT (the default is %FALSE). specifies if identifiers are reported as strings (the default is %FALSE). specifies if characters are reported by setting `token = ch` or as %G_TOKEN_CHAR (the default is %TRUE). specifies if symbols are reported by setting `token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE). specifies if a symbol is searched for in the default scope in addition to the current scope (the default is %FALSE). use value.v_int64 rather than v_int Specifies the type of the message handler function. a #GScanner the message %TRUE if the message signals an error, %FALSE if it signals a warning. An enumeration specifying the base position for a g_io_channel_seek_position() operation. the current position in the file. the start of the file. the end of the file. The #GSequence struct is an opaque data type representing a [sequence](data-structures.html#scalable-lists) data type. Adds a new item to the end of @seq. an iterator pointing to the new item a #GSequence the data for the new item Calls @func for each item in the sequence passing @user_data to the function. @func must not modify the sequence itself. a #GSequence the function to call for each item in @seq user data passed to @func Frees the memory allocated for @seq. If @seq has a data destroy function associated with it, that function is called on all items in @seq. a #GSequence Returns the begin iterator for @seq. the begin iterator for @seq. a #GSequence Returns the end iterator for @seg the end iterator for @seq a #GSequence Returns the iterator at position @pos. If @pos is negative or larger than the number of items in @seq, the end iterator is returned. The #GSequenceIter at position @pos a #GSequence a position in @seq, or -1 for the end Returns the positive length (>= 0) of @seq. Note that this method is O(h) where `h' is the height of the tree. It is thus more efficient to use g_sequence_is_empty() when comparing the length to zero. the length of @seq a #GSequence Inserts @data into @seq using @cmp_func to determine the new position. The sequence must already be sorted according to @cmp_func; otherwise the new position of @data is undefined. @cmp_func is called with two items of the @seq, and @cmp_data. It should return 0 if the items are equal, a negative value if the first item comes before the second, and a positive value if the second item comes before the first. Note that when adding a large amount of data to a #GSequence, it is more efficient to do unsorted insertions and then call g_sequence_sort() or g_sequence_sort_iter(). a #GSequenceIter pointing to the new item. a #GSequence the data to insert the function used to compare items in the sequence user data passed to @cmp_func. Like g_sequence_insert_sorted(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function. @iter_cmp is called with two iterators pointing into @seq. It should return 0 if the iterators are equal, a negative value if the first iterator comes before the second, and a positive value if the second iterator comes before the first. Note that when adding a large amount of data to a #GSequence, it is more efficient to do unsorted insertions and then call g_sequence_sort() or g_sequence_sort_iter(). a #GSequenceIter pointing to the new item a #GSequence data for the new item the function used to compare iterators in the sequence user data passed to @iter_cmp Returns %TRUE if the sequence contains zero items. This function is functionally identical to checking the result of g_sequence_get_length() being equal to zero. However this function is implemented in O(1) running time. %TRUE if the sequence is empty, otherwise %FALSE. a #GSequence Returns an iterator pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data. If more than one item is equal, it is not guaranteed that it is the first which is returned. In that case, you can use g_sequence_iter_next() and g_sequence_iter_prev() to get others. @cmp_func is called with two items of the @seq, and @cmp_data. It should return 0 if the items are equal, a negative value if the first item comes before the second, and a positive value if the second item comes before the first. This function will fail if the data contained in the sequence is unsorted. an #GSequenceIter pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data, or %NULL if no such item exists a #GSequence data to look up the function used to compare items in the sequence user data passed to @cmp_func Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function. @iter_cmp is called with two iterators pointing into @seq. It should return 0 if the iterators are equal, a negative value if the first iterator comes before the second, and a positive value if the second iterator comes before the first. This function will fail if the data contained in the sequence is unsorted. an #GSequenceIter pointing to the position of the first item found equal to @data according to @iter_cmp and @cmp_data, or %NULL if no such item exists a #GSequence data to look up the function used to compare iterators in the sequence user data passed to @iter_cmp Adds a new item to the front of @seq an iterator pointing to the new item a #GSequence the data for the new item Returns an iterator pointing to the position where @data would be inserted according to @cmp_func and @cmp_data. @cmp_func is called with two items of the @seq, and @cmp_data. It should return 0 if the items are equal, a negative value if the first item comes before the second, and a positive value if the second item comes before the first. If you are simply searching for an existing element of the sequence, consider using g_sequence_lookup(). This function will fail if the data contained in the sequence is unsorted. an #GSequenceIter pointing to the position where @data would have been inserted according to @cmp_func and @cmp_data a #GSequence data for the new item the function used to compare items in the sequence user data passed to @cmp_func Like g_sequence_search(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function. @iter_cmp is called with two iterators pointing into @seq. It should return 0 if the iterators are equal, a negative value if the first iterator comes before the second, and a positive value if the second iterator comes before the first. If you are simply searching for an existing element of the sequence, consider using g_sequence_lookup_iter(). This function will fail if the data contained in the sequence is unsorted. a #GSequenceIter pointing to the position in @seq where @data would have been inserted according to @iter_cmp and @cmp_data a #GSequence data for the new item the function used to compare iterators in the sequence user data passed to @iter_cmp Sorts @seq using @cmp_func. @cmp_func is passed two items of @seq and should return 0 if they are equal, a negative value if the first comes before the second, and a positive value if the second comes before the first. a #GSequence the function used to sort the sequence user data passed to @cmp_func Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function @cmp_func is called with two iterators pointing into @seq. It should return 0 if the iterators are equal, a negative value if the first iterator comes before the second, and a positive value if the second iterator comes before the first. a #GSequence the function used to compare iterators in the sequence user data passed to @cmp_func Calls @func for each item in the range (@begin, @end) passing @user_data to the function. @func must not modify the sequence itself. a #GSequenceIter a #GSequenceIter a #GFunc user data passed to @func Returns the data that @iter points to. the data that @iter points to a #GSequenceIter Inserts a new item just before the item pointed to by @iter. an iterator pointing to the new item a #GSequenceIter the data for the new item Moves the item pointed to by @src to the position indicated by @dest. After calling this function @dest will point to the position immediately after @src. It is allowed for @src and @dest to point into different sequences. a #GSequenceIter pointing to the item to move a #GSequenceIter pointing to the position to which the item is moved Inserts the (@begin, @end) range at the destination pointed to by @dest. The @begin and @end iters must point into the same sequence. It is allowed for @dest to point to a different sequence than the one pointed into by @begin and @end. If @dest is %NULL, the range indicated by @begin and @end is removed from the sequence. If @dest points to a place within the (@begin, @end) range, the range does not move. a #GSequenceIter a #GSequenceIter a #GSequenceIter Creates a new GSequence. The @data_destroy function, if non-%NULL will be called on all items when the sequence is destroyed and on items that are removed from the sequence. a new #GSequence a #GDestroyNotify function, or %NULL Finds an iterator somewhere in the range (@begin, @end). This iterator will be close to the middle of the range, but is not guaranteed to be exactly in the middle. The @begin and @end iterators must both point to the same sequence and @begin must come before or be equal to @end in the sequence. a #GSequenceIter pointing somewhere in the (@begin, @end) range a #GSequenceIter a #GSequenceIter Removes the item pointed to by @iter. It is an error to pass the end iterator to this function. If the sequence has a data destroy function associated with it, this function is called on the data for the removed item. a #GSequenceIter Removes all items in the (@begin, @end) range. If the sequence has a data destroy function associated with it, this function is called on the data for the removed items. a #GSequenceIter a #GSequenceIter Changes the data for the item pointed to by @iter to be @data. If the sequence has a data destroy function associated with it, that function is called on the existing data that @iter pointed to. a #GSequenceIter new data for the item Moves the data pointed to by @iter to a new position as indicated by @cmp_func. This function should be called for items in a sequence already sorted according to @cmp_func whenever some aspect of an item changes so that @cmp_func may return different values for that item. @cmp_func is called with two items of the @seq, and @cmp_data. It should return 0 if the items are equal, a negative value if the first item comes before the second, and a positive value if the second item comes before the first. A #GSequenceIter the function used to compare items in the sequence user data passed to @cmp_func. Like g_sequence_sort_changed(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function. @iter_cmp is called with two iterators pointing into the #GSequence that @iter points into. It should return 0 if the iterators are equal, a negative value if the first iterator comes before the second, and a positive value if the second iterator comes before the first. a #GSequenceIter the function used to compare iterators in the sequence user data passed to @cmp_func Swaps the items pointed to by @a and @b. It is allowed for @a and @b to point into difference sequences. a #GSequenceIter a #GSequenceIter The #GSequenceIter struct is an opaque data type representing an iterator pointing into a #GSequence. Returns a negative number if @a comes before @b, 0 if they are equal, and a positive number if @a comes after @b. The @a and @b iterators must point into the same sequence. a negative number if @a comes before @b, 0 if they are equal, and a positive number if @a comes after @b a #GSequenceIter a #GSequenceIter Returns the position of @iter the position of @iter a #GSequenceIter Returns the #GSequence that @iter points into. the #GSequence that @iter points into a #GSequenceIter Returns whether @iter is the begin iterator whether @iter is the begin iterator a #GSequenceIter Returns whether @iter is the end iterator Whether @iter is the end iterator a #GSequenceIter Returns the #GSequenceIter which is @delta positions away from @iter. If @iter is closer than -@delta positions to the beginning of the sequence, the begin iterator is returned. If @iter is closer than @delta positions to the end of the sequence, the end iterator is returned. a #GSequenceIter which is @delta positions away from @iter a #GSequenceIter A positive or negative number indicating how many positions away from @iter the returned #GSequenceIter will be Returns an iterator pointing to the next position after @iter. If @iter is the end iterator, the end iterator is returned. a #GSequenceIter pointing to the next position after @iter a #GSequenceIter Returns an iterator pointing to the previous position before @iter. If @iter is the begin iterator, the begin iterator is returned. a #GSequenceIter pointing to the previous position before @iter a #GSequenceIter A #GSequenceIterCompareFunc is a function used to compare iterators. It must return zero if the iterators compare equal, a negative value if @a comes before @b, and a positive value if @b comes before @a. zero if the iterators are equal, a negative value if @a comes before @b, and a positive value if @b comes before @a. a #GSequenceIter a #GSequenceIter user data Error codes returned by shell functions. Mismatched or otherwise mangled quoting. String to be parsed was empty. Some other error. The `GSource` struct is an opaque data type representing an event source. Creates a new [struct@GLib.Source] structure. The size is specified to allow creating structures derived from [struct@GLib.Source] that contain additional data. The size passed in must be at least `sizeof (GSource)`. The source will not initially be associated with any [struct@GLib.MainContext] and must be added to one with [method@GLib.Source.attach] before it will be executed. the newly-created source structure containing functions that implement the source‘s behavior size of the [struct@GLib.Source] structure to create, in bytes Adds @child_source to @source as a ‘polled’ source. When @source is added to a [struct@GLib.MainContext], @child_source will be automatically added with the same priority. When @child_source is triggered, it will cause @source to dispatch (in addition to calling its own callback), and when @source is destroyed, it will destroy @child_source as well. The @source will also still be dispatched if its own prepare/check functions indicate that it is ready. If you don’t need @child_source to do anything on its own when it triggers, you can call `g_source_set_dummy_callback()` on it to set a callback that does nothing (except return true if appropriate). The @source will hold a reference on @child_source while @child_source is attached to it. This API is only intended to be used by implementations of [struct@GLib.Source]. Do not call this API on a [struct@GLib.Source] that you did not create. a source a second source that @source should ‘poll’ Adds a file descriptor to the set of file descriptors polled for this source. This is usually combined with [ctor@GLib.Source.new] to add an event source. The event source’s check function will typically test the @revents field in the [struct@GLib.PollFD] struct and return true if events need to be processed. This API is only intended to be used by implementations of [struct@GLib.Source]. Do not call this API on a [struct@GLib.Source] that you did not create. Using this API forces the linear scanning of event sources on each main loop iteration. Newly-written event sources should try to use `g_source_add_unix_fd()` instead of this API. a source a [struct@GLib.PollFD] structure holding information about a file descriptor to watch Monitors @fd for the IO events in @events. The tag returned by this function can be used to remove or modify the monitoring of the @fd using [method@GLib.Source.remove_unix_fd] or [method@GLib.Source.modify_unix_fd]. It is not necessary to remove the file descriptor before destroying the source; it will be cleaned up automatically. This API is only intended to be used by implementations of [struct@GLib.Source]. Do not call this API on a [struct@GLib.Source] that you did not create. As the name suggests, this function is not available on Windows. an opaque tag a source the file descriptor to monitor an event mask Adds a [struct@GLib.Source] to a @context so that it will be executed within that context. Remove it by calling [method@GLib.Source.destroy]. This function is safe to call from any thread, regardless of which thread the @context is running in. the ID (greater than 0) for the source within the [struct@GLib.MainContext] a source a main context (if `NULL`, the global-default main context will be used) Removes a source from its [struct@GLib.MainContext], if any, and marks it as destroyed. The source cannot be subsequently added to another context. It is safe to call this on sources which have already been removed from their context. This does not unref the [struct@GLib.Source]: if you still hold a reference, use [method@GLib.Source.unref] to drop it. This function is safe to call from any thread, regardless of which thread the [struct@GLib.MainContext] is running in. If the source is currently attached to a [struct@GLib.MainContext], destroying it will effectively unset the callback similar to calling [method@GLib.Source.set_callback]. This can mean, that the data’s [callback@GLib.DestroyNotify] gets called right away. a source Gets a reference to the [struct@GLib.MainContext] with which the source is associated. You can call this on a source that has been destroyed. You can always call this function on the source returned from [func@GLib.main_current_source]. the [struct@GLib.MainContext] with which the source is associated, or `NULL` if the context has not yet been added to a source a source Checks whether a source is allowed to be called recursively. See [method@GLib.Source.set_can_recurse]. whether recursion is allowed a source Gets the [struct@GLib.MainContext] with which the source is associated. You can call this on a source that has been destroyed, provided that the [struct@GLib.MainContext] it was attached to still exists (in which case it will return that [struct@GLib.MainContext]). In particular, you can always call this function on the source returned from [func@GLib.main_current_source]. But calling this function on a source whose [struct@GLib.MainContext] has been destroyed is an error. If the associated [struct@GLib.MainContext] could be destroy concurrently from a different thread, then this function is not safe to call and [method@GLib.Source.dup_context] should be used instead. the main context with which the source is associated, or `NULL` if the context has not yet been added to a source a source This function ignores @source and is otherwise the same as [func@GLib.get_current_time]. use [method@GLib.Source.get_time] instead a source [struct@GLib.TimeVal] structure in which to store current time Returns the numeric ID for a particular source. The ID of a source is a positive integer which is unique within a particular main loop context. The reverse mapping from ID to source is done by [method@GLib.MainContext.find_source_by_id]. You can only call this function while the source is associated to a [struct@GLib.MainContext] instance; calling this function before [method@GLib.Source.attach] or after [method@GLib.Source.destroy] yields undefined behavior. The ID returned is unique within the [struct@GLib.MainContext] instance passed to [method@GLib.Source.attach]. the ID (greater than 0) for the source a source Gets a name for the source, used in debugging and profiling. The name may be `NULL` if it has never been set with [method@GLib.Source.set_name]. the name of the source a source Gets the priority of a source. the priority of the source a source Gets the ‘ready time’ of @source, as set by [method@GLib.Source.set_ready_time]. Any time before or equal to the current monotonic time (including zero) is an indication that the source will fire immediately. the monotonic ready time, `-1` for ‘never’ a source Gets the time to be used when checking this source. The advantage of calling this function over calling [func@GLib.get_monotonic_time] directly is that when checking multiple sources, GLib can cache a single value instead of having to repeatedly get the system monotonic time. The time here is the system monotonic time, if available, or some other reasonable alternative otherwise. See [func@GLib.get_monotonic_time]. the monotonic time in microseconds a source Returns whether @source has been destroyed. This is important when you operate upon your objects from within idle handlers, but may have freed the object before the dispatch of your idle handler. ```c static gboolean idle_callback (gpointer data) { SomeWidget *self = data; g_mutex_lock (&self->idle_id_mutex); // do stuff with self self->idle_id = 0; g_mutex_unlock (&self->idle_id_mutex); return G_SOURCE_REMOVE; } static void some_widget_do_stuff_later (SomeWidget *self) { g_mutex_lock (&self->idle_id_mutex); self->idle_id = g_idle_add (idle_callback, self); g_mutex_unlock (&self->idle_id_mutex); } static void some_widget_init (SomeWidget *self) { g_mutex_init (&self->idle_id_mutex); // ... } static void some_widget_finalize (GObject *object) { SomeWidget *self = SOME_WIDGET (object); if (self->idle_id) g_source_remove (self->idle_id); g_mutex_clear (&self->idle_id_mutex); G_OBJECT_CLASS (parent_class)->finalize (object); } ``` This will fail in a multi-threaded application if the widget is destroyed before the idle handler fires due to the use after free in the callback. A solution, to this particular problem, is to check to if the source has already been destroy within the callback. ```c static gboolean idle_callback (gpointer data) { SomeWidget *self = data; g_mutex_lock (&self->idle_id_mutex); if (!g_source_is_destroyed (g_main_current_source ())) { // do stuff with self } g_mutex_unlock (&self->idle_id_mutex); return FALSE; } ``` Calls to this function from a thread other than the one acquired by the [struct@GLib.MainContext] the [struct@GLib.Source] is attached to are typically redundant, as the source could be destroyed immediately after this function returns. However, once a source is destroyed it cannot be un-destroyed, so this function can be used for opportunistic checks from any thread. true if the source has been destroyed, false otherwise a source Updates the event mask to watch for the file descriptor identified by @tag. The @tag is the tag returned from [method@GLib.Source.add_unix_fd]. If you want to remove a file descriptor, don’t set its event mask to zero. Instead, call [method@GLib.Source.remove_unix_fd]. This API is only intended to be used by implementations of [struct@GLib.Source]. Do not call this API on a [struct@GLib.Source] that you did not create. As the name suggests, this function is not available on Windows. a source the tag from [method@GLib.Source.add_unix_fd] the new event mask to watch Queries the events reported for the file descriptor corresponding to @tag on @source during the last poll. The return value of this function is only defined when the function is called from the check or dispatch functions for @source. This API is only intended to be used by implementations of [struct@GLib.Source]. Do not call this API on a [struct@GLib.Source] that you did not create. As the name suggests, this function is not available on Windows. the conditions reported on the file descriptor a source the tag from [method@GLib.Source.add_unix_fd] Increases the reference count on a source by one. @source a source Detaches @child_source from @source and destroys it. This API is only intended to be used by implementations of [struct@GLib.Source]. Do not call this API on a [struct@GLib.Source] that you did not create. a source a source previously passed to [method@GLib.Source.add_child_source] Removes a file descriptor from the set of file descriptors polled for this source. This API is only intended to be used by implementations of [struct@GLib.Source]. Do not call this API on a [struct@GLib.Source] that you did not create. a source a [struct@GLib.PollFD] structure previously passed to [method@GLib.Source.add_poll] Reverses the effect of a previous call to [method@GLib.Source.add_unix_fd]. You only need to call this if you want to remove a file descriptor from being watched while keeping the same source around. In the normal case you will just want to destroy the source. This API is only intended to be used by implementations of [struct@GLib.Source]. Do not call this API on a [struct@GLib.Source] that you did not create. As the name suggests, this function is not available on Windows. a source the tag from [method@GLib.Source.add_unix_fd] Sets the callback function for a source. The callback for a source is called from the source’s dispatch function. The exact type of @func depends on the type of source; ie. you should not count on @func being called with @data as its first parameter. Cast @func with [func@GLib.SOURCE_FUNC] to avoid warnings about incompatible function types. See [main loop memory management](main-loop.html#memory-management-of-sources) for details on how to handle memory management of @data. Typically, you won’t use this function. Instead use functions specific to the type of source you are using, such as [func@GLib.idle_add] or [func@GLib.timeout_add]. It is safe to call this function multiple times on a source which has already been attached to a context. The changes will take effect for the next time the source is dispatched after this call returns. Note that [method@GLib.Source.destroy] for a currently attached source has the effect of also unsetting the callback. the source a callback function the data to pass to callback function a function to call when @data is no longer in use Sets the callback function storing the data as a reference counted callback ‘object’. This is used internally. Note that calling [method@GLib.Source.set_callback_indirect] assumes an initial reference count on @callback_data, and thus `callback_funcs->unref` will eventually be called once more than `callback_funcs->ref`. It is safe to call this function multiple times on a source which has already been attached to a context. The changes will take effect for the next time the source is dispatched after this call returns. the source pointer to callback data ‘object’ functions for reference counting @callback_data and getting the callback and data Sets whether a source can be called recursively. If @can_recurse is true, then while the source is being dispatched then this source will be processed normally. Otherwise, all processing of this source is blocked until the dispatch function returns. a source whether recursion is allowed for this source Set @dispose as dispose function on @source. The @dispose function will be called once the reference count of @source reaches zero but before any of the state of the source is freed, especially before the finalize function (set as part of the [type@GLib.SourceFuncs]) is called. This means that at this point @source is still a valid [struct@GLib.Source] and it is allow for the reference count to increase again until @dispose returns. The dispose function can be used to clear any ‘weak’ references to the @source in other data structures in a thread-safe way where it is possible for another thread to increase the reference count of @source again while it is being freed. The finalize function can not be used for this purpose as at that point @source is already partially freed and not valid any more. This should only ever be called from [struct@GLib.Source] implementations. a source to set the dispose function on dispose function to set on the source Sets the source functions of an unattached source. These can be used to override the default implementations for the type of @source. a source the new source functions Sets a name for the source, used in debugging and profiling. The name defaults to `NULL`. The source name should describe in a human-readable way what the source does. For example, ‘X11 event queue’ or ‘GTK repaint idle handler’. It is permitted to call this function multiple times, but is not recommended due to the potential performance impact. For example, one could change the name in the `check` function of a [struct@GLib.SourceFuncs] to include details like the event type in the source name. Use caution if changing the name while another thread may be accessing it with [method@GLib.Source.get_name]; that function does not copy the value, and changing the value will free it while the other thread may be attempting to use it. Also see [method@GLib.Source.set_static_name]. a source debug name for the source Sets the priority of a source. While the main loop is being run, a source will be dispatched if it is ready to be dispatched and no sources at a higher (numerically smaller) priority are ready to be dispatched. A child source always has the same priority as its parent. It is not permitted to change the priority of a source once it has been added as a child of another source. a source the new priority Sets a source to be dispatched when the given monotonic time is reached (or passed). If the monotonic time is in the past (as it always will be if @ready_time is `0`) then the source will be dispatched immediately. If @ready_time is `-1` then the source is never woken up on the basis of the passage of time. Dispatching the source does not reset the ready time. You should do so yourself, from the source dispatch function. Note that if you have a pair of sources where the ready time of one suggests that it will be delivered first but the priority for the other suggests that it would be delivered first, and the ready time for both sources is reached during the same main context iteration, then the order of dispatch is undefined. It is a no-op to call this function on a [struct@GLib.Source] which has already been destroyed with [method@GLib.Source.destroy]. This API is only intended to be used by implementations of [struct@GLib.Source]. Do not call this API on a [struct@GLib.Source] that you did not create. a source the monotonic time at which the source will be ready; `0` for ‘immediately’, `-1` for ‘never’ A variant of [method@GLib.Source.set_name] that does not duplicate the @name, and can only be used with string literals. a source debug name for the source Decreases the reference count of a source by one. If the resulting reference count is zero the source and associated memory will be destroyed. a source Removes the source with the given ID from the default main context. You must use [method@GLib.Source.destroy] for sources added to a non-default main context. The ID of a [struct@GLib.Source] is given by [method@GLib.Source.get_id], or will be returned by the functions [method@GLib.Source.attach], [func@GLib.idle_add], [func@GLib.idle_add_full], [func@GLib.timeout_add], [func@GLib.timeout_add_full], [func@GLib.child_watch_add], [func@GLib.child_watch_add_full], [func@GLib.io_add_watch], and [func@GLib.io_add_watch_full]. It is a programmer error to attempt to remove a non-existent source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source. true if the source was found and removed, false otherwise the ID of the source to remove. Removes a source from the default main loop context given the source functions and user data. If multiple sources exist with the same source functions and user data, only one will be destroyed. true if a source was found and removed, false otherwise the @source_funcs passed to [ctor@GLib.Source.new] the user data for the callback Removes a source from the default main loop context given the user data for the callback. If multiple sources exist with the same user data, only one will be destroyed. true if a source was found and removed, false otherwise the user_data for the callback Sets the name of a source using its ID. This is a convenience utility to set source names from the return value of [func@GLib.idle_add], [func@GLib.timeout_add], etc. It is a programmer error to attempt to set the name of a non-existent source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source. a source ID debug name for the source The `GSourceCallbackFuncs` struct contains functions for managing callback objects. Called when a reference is added to the callback object Called when a reference to the callback object is dropped Called to extract the callback function and data from the callback object. Dispose function for @source. See [method@GLib.Source.set_dispose_function] for details. #GSource that is currently being disposed This is just a placeholder for #GClosureMarshal, which cannot be used here for dependency reasons. Specifies the type of function passed to [func@GLib.timeout_add], [func@GLib.timeout_add_full], [func@GLib.idle_add], and [func@GLib.idle_add_full]. When calling [method@GLib.Source.set_callback], you may need to cast a function of a different type to this type. Use [func@GLib.SOURCE_FUNC] to avoid warnings about incompatible function types. %FALSE if the source should be removed. [const@GLib.SOURCE_CONTINUE] and [const@GLib.SOURCE_REMOVE] are more memorable names for the return value. data passed to the function, set when the source was created with one of the above functions The `GSourceFuncs` struct contains a table of functions used to handle event sources in a generic manner. For idle sources, the prepare and check functions always return %TRUE to indicate that the source is always ready to be processed. The prepare function also returns a timeout value of 0 to ensure that the poll() call doesn't block (since that would be time wasted which could have been spent running the idle function). For timeout sources, the prepare and check functions both return %TRUE if the timeout interval has expired. The prepare function also returns a timeout value to ensure that the poll() call doesn't block too long and miss the next timeout. For file descriptor sources, the prepare function typically returns %FALSE, since it must wait until poll() has been called before it knows whether any events need to be processed. It sets the returned timeout to -1 to indicate that it doesn't mind how long the poll() call blocks. In the check function, it tests the results of the poll() call to see if the required condition has been met, and returns %TRUE if so. Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the @timeout_ values returned which were >= 0. Since 2.36 this may be %NULL, in which case the effect is as if the function always returns %FALSE with a timeout of -1. If @prepare returns a timeout and the source also has a ready time set, then the lower of the two will be used. Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here. Since 2.36 this may be %NULL, in which case the effect is as if the function always returns %FALSE. Called to dispatch the event source, after it has returned %TRUE in either its @prepare or its @check function, or if a ready time has been reached. The @dispatch function receives a callback function and user data. The callback function may be %NULL if the source was never connected to a callback using [method@GLib.Source.set_callback]. The @dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source. The return value of the @dispatch function should be [const@GLib.SOURCE_REMOVE] if the source should be removed or [const@GLib.SOURCE_CONTINUE] to keep it. Called when the source is finalized. At this point, the source will have been destroyed, had its callback cleared, and have been removed from its [struct@GLib.MainContext], but it will still have its final reference count, so methods can be called on it from within this function. This may be %NULL, in which case the effect is as if the function does nothing and returns. Checks if the source is ready to be dispatched. Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here. Since 2.36 this may be `NULL`, in which case the effect is as if the function always returns `FALSE`. %TRUE if ready to be dispatched, %FALSE otherwise The #GSource Dispatches the source callback. Called to dispatch the event source, after it has returned `TRUE` in either its prepare or its check function, or if a ready time has been reached. The dispatch function receives a callback function and user data. The callback function may be `NULL` if the source was never connected to a callback using [method@GLib.Source.set_callback]. The dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source. The return value of the dispatch function should be [const@GLib.SOURCE_REMOVE] if the source should be removed or [const@GLib.SOURCE_CONTINUE] to keep it. [const@GLib.SOURCE_REMOVE] if the source should be removed, [const@GLib.SOURCE_CONTINUE] otherwise. The #GSource The #GSourceFunc to call data to pass to @callback Finalizes the source. Called when the source is finalized. At this point, the source will have been destroyed, had its callback cleared, and have been removed from its [type@GLib.MainContext], but it will still have its final reference count, so methods can be called on it from within this function. The #GSource Checks the source for readiness. Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll call. The actual timeout used will be `-1` if all sources returned `-1`, or it will be the minimum of all the @timeout_ values returned which were greater than or equal to `0`. If the prepare function returns a timeout and the source also has a ready time set, then the lower of the two will be used. Since 2.36 this may be `NULL`, in which case the effect is as if the function always returns `FALSE` with a timeout of `-1`. %TRUE if the source is ready, %FALSE otherwise The #GSource the maximum timeout (in milliseconds) which should be passed to the poll call A source function that is only called once before being removed from the main context automatically. See: [func@GLib.idle_add_once], [func@GLib.timeout_add_once] data passed to the function, set when the source was created Specifies the type of the setup function passed to g_spawn_async(), g_spawn_sync() and g_spawn_async_with_pipes(), which can, in very limited ways, be used to affect the child's execution. On POSIX platforms, the function is called in the child after GLib has performed all the setup it plans to perform, but before calling exec(). Actions taken in this function will only affect the child, not the parent. On Windows, the function is called in the parent. Its usefulness on Windows is thus questionable. In many cases executing the child setup function in the parent can have ill effects, and you should be very careful when porting software to Windows that uses child setup functions. However, even on POSIX, you are extremely limited in what you can safely do from a #GSpawnChildSetupFunc, because any mutexes that were held by other threads in the parent process at the time of the fork() will still be locked in the child process, and they will never be unlocked (since the threads that held them don't exist in the child). POSIX allows only async-signal-safe functions (see signal(7)) to be called in the child between fork() and exec(), which drastically limits the usefulness of child setup functions. In particular, it is not safe to call any function which may call malloc(), which includes POSIX functions such as setenv(). If you need to set up the child environment differently from the parent, you should use g_get_environ(), g_environ_setenv(), and g_environ_unsetenv(), and then pass the complete environment list to the `g_spawn...` function. user data passed to the function. Error codes returned by spawning processes. Fork failed due to lack of memory. Read or select on pipes failed. Changing to working directory failed. execv() returned `EACCES` execv() returned `EPERM` execv() returned `E2BIG` deprecated alias for %G_SPAWN_ERROR_TOO_BIG (deprecated since GLib 2.32) execv() returned `ENOEXEC` execv() returned `ENAMETOOLONG` execv() returned `ENOENT` execv() returned `ENOMEM` execv() returned `ENOTDIR` execv() returned `ELOOP` execv() returned `ETXTBUSY` execv() returned `EIO` execv() returned `ENFILE` execv() returned `EMFILE` execv() returned `EINVAL` execv() returned `EISDIR` execv() returned `ELIBBAD` Some other fatal failure, `error->message` should explain. Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes(). no flags, default behaviour the parent's open file descriptors will be inherited by the child; otherwise all descriptors except stdin, stdout and stderr will be closed before calling exec() in the child. the child will not be automatically reaped; you must use g_child_watch_add() yourself (or call waitpid() or handle `SIGCHLD` yourself), or the child will become a zombie. `argv[0]` need not be an absolute path, it will be looked for in the user's `PATH`. the child's standard output will be discarded, instead of going to the same location as the parent's standard output. the child's standard error will be discarded. the child will inherit the parent's standard input (by default, the child's standard input is attached to `/dev/null`). the first element of `argv` is the file to execute, while the remaining elements are the actual argument vector to pass to the file. Normally g_spawn_async_with_pipes() uses `argv[0]` as the file to execute, and passes all of `argv` to the child. if `argv[0]` is not an absolute path, it will be looked for in the `PATH` from the passed child environment. Since: 2.34 create all pipes with the `O_CLOEXEC` flag set. Since: 2.40 The child will inherit the parent's standard output. The child will inherit the parent's standard error. The child's standard input is attached to `/dev/null`. A type corresponding to the appropriate struct type for the stat() system call, depending on the platform and/or compiler being used. See g_stat() for more information. A #GStaticMutex works like a #GMutex. Prior to GLib 2.32, GStaticMutex had the significant advantage that it doesn't need to be created at run-time, but can be defined at compile-time. Since 2.32, #GMutex can be statically allocated as well, and GStaticMutex has been deprecated. Here is a version of our give_me_next_number() example using a GStaticMutex: |[ int give_me_next_number (void) { static int current_number = 0; int ret_val; static GStaticMutex mutex = G_STATIC_MUTEX_INIT; g_static_mutex_lock (&mutex); ret_val = current_number = calc_next_number (current_number); g_static_mutex_unlock (&mutex); return ret_val; } ]| Sometimes you would like to dynamically create a mutex. If you don't want to require prior calling to g_thread_init(), because your code should also be usable in non-threaded programs, you are not able to use g_mutex_new() and thus #GMutex, as that requires a prior call to g_thread_init(). In these cases you can also use a #GStaticMutex. It must be initialized with g_static_mutex_init() before using it and freed with with g_static_mutex_free() when not needed anymore to free up any allocated resources. Even though #GStaticMutex is not opaque, it should only be used with the following functions, as it is defined differently on different platforms. All of the g_static_mutex_* functions apart from g_static_mutex_get_mutex() can also be used even if g_thread_init() has not yet been called. Then they do nothing, apart from g_static_mutex_trylock() which does nothing but returning %TRUE. All of the g_static_mutex_* functions are actually macros. Apart from taking their addresses, you can however use them as if they were functions. Releases all resources allocated to @mutex. You don't have to call this functions for a #GStaticMutex with an unbounded lifetime, i.e. objects declared 'static', but if you have a #GStaticMutex as a member of a structure and the structure is freed, you should also free the #GStaticMutex. Calling g_static_mutex_free() on a locked mutex may result in undefined behaviour. Use g_mutex_clear() a #GStaticMutex to be freed. Initializes @mutex. Alternatively you can initialize it with %G_STATIC_MUTEX_INIT. Use g_mutex_init() a #GStaticMutex to be initialized. A #GStaticPrivate works almost like a #GPrivate, but it has one significant advantage. It doesn't need to be created at run-time like a #GPrivate, but can be defined at compile-time. This is similar to the difference between #GMutex and #GStaticMutex. Now look at our give_me_next_number() example with #GStaticPrivate: |[ int give_me_next_number () { static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT; int *current_number = g_static_private_get (&current_number_key); if (!current_number) { current_number = g_new (int, 1); *current_number = 0; g_static_private_set (&current_number_key, current_number, g_free); } *current_number = calc_next_number (*current_number); return *current_number; } ]| Releases all resources allocated to @private_key. You don't have to call this functions for a #GStaticPrivate with an unbounded lifetime, i.e. objects declared 'static', but if you have a #GStaticPrivate as a member of a structure and the structure is freed, you should also free the #GStaticPrivate. a #GStaticPrivate to be freed Works like g_private_get() only for a #GStaticPrivate. This function works even if g_thread_init() has not yet been called. the corresponding pointer a #GStaticPrivate Initializes @private_key. Alternatively you can initialize it with %G_STATIC_PRIVATE_INIT. a #GStaticPrivate to be initialized Sets the pointer keyed to @private_key for the current thread and the function @notify to be called with that pointer (%NULL or non-%NULL), whenever the pointer is set again or whenever the current thread ends. This function works even if g_thread_init() has not yet been called. If g_thread_init() is called later, the @data keyed to @private_key will be inherited only by the main thread, i.e. the one that called g_thread_init(). @notify is used quite differently from @destructor in g_private_new(). a #GStaticPrivate the new pointer a function to be called with the pointer whenever the current thread ends or sets this pointer again The #GStaticRWLock struct represents a read-write lock. A read-write lock can be used for protecting data that some portions of code only read from, while others also write. In such situations it is desirable that several readers can read at once, whereas of course only one writer may write at a time. Take a look at the following example: |[ GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT; GPtrArray *array; gpointer my_array_get (guint index) { gpointer retval = NULL; if (!array) return NULL; g_static_rw_lock_reader_lock (&rwlock); if (index < array->len) retval = g_ptr_array_index (array, index); g_static_rw_lock_reader_unlock (&rwlock); return retval; } void my_array_set (guint index, gpointer data) { g_static_rw_lock_writer_lock (&rwlock); if (!array) array = g_ptr_array_new (); if (index >= array->len) g_ptr_array_set_size (array, index + 1); g_ptr_array_index (array, index) = data; g_static_rw_lock_writer_unlock (&rwlock); } ]| This example shows an array which can be accessed by many readers (the my_array_get() function) simultaneously, whereas the writers (the my_array_set() function) will only be allowed once at a time and only if no readers currently access the array. This is because of the potentially dangerous resizing of the array. Using these functions is fully multi-thread safe now. Most of the time, writers should have precedence over readers. That means, for this implementation, that as soon as a writer wants to lock the data, no other reader is allowed to lock the data, whereas, of course, the readers that already have locked the data are allowed to finish their operation. As soon as the last reader unlocks the data, the writer will lock it. Even though #GStaticRWLock is not opaque, it should only be used with the following functions. All of the g_static_rw_lock_* functions can be used even if g_thread_init() has not been called. Then they do nothing, apart from g_static_rw_lock_*_trylock, which does nothing but returning %TRUE. A read-write lock has a higher overhead than a mutex. For example, both g_static_rw_lock_reader_lock() and g_static_rw_lock_reader_unlock() have to lock and unlock a #GStaticMutex, so it takes at least twice the time to lock and unlock a #GStaticRWLock that it does to lock and unlock a #GStaticMutex. So only data structures that are accessed by multiple readers, and which keep the lock for a considerable time justify a #GStaticRWLock. The above example most probably would fare better with a #GStaticMutex. Use a #GRWLock instead Releases all resources allocated to @lock. You don't have to call this functions for a #GStaticRWLock with an unbounded lifetime, i.e. objects declared 'static', but if you have a #GStaticRWLock as a member of a structure, and the structure is freed, you should also free the #GStaticRWLock. Use a #GRWLock instead a #GStaticRWLock to be freed. A #GStaticRWLock must be initialized with this function before it can be used. Alternatively you can initialize it with %G_STATIC_RW_LOCK_INIT. Use g_rw_lock_init() instead a #GStaticRWLock to be initialized. Locks @lock for reading. There may be unlimited concurrent locks for reading of a #GStaticRWLock at the same time. If @lock is already locked for writing by another thread or if another thread is already waiting to lock @lock for writing, this function will block until @lock is unlocked by the other writing thread and no other writing threads want to lock @lock. This lock has to be unlocked by g_static_rw_lock_reader_unlock(). #GStaticRWLock is not recursive. It might seem to be possible to recursively lock for reading, but that can result in a deadlock, due to writer preference. Use g_rw_lock_reader_lock() instead a #GStaticRWLock to lock for reading. Tries to lock @lock for reading. If @lock is already locked for writing by another thread or if another thread is already waiting to lock @lock for writing, immediately returns %FALSE. Otherwise locks @lock for reading and returns %TRUE. This lock has to be unlocked by g_static_rw_lock_reader_unlock(). Use g_rw_lock_reader_trylock() instead %TRUE, if @lock could be locked for reading a #GStaticRWLock to lock for reading Unlocks @lock. If a thread waits to lock @lock for writing and all locks for reading have been unlocked, the waiting thread is woken up and can lock @lock for writing. Use g_rw_lock_reader_unlock() instead a #GStaticRWLock to unlock after reading Locks @lock for writing. If @lock is already locked for writing or reading by other threads, this function will block until @lock is completely unlocked and then lock @lock for writing. While this functions waits to lock @lock, no other thread can lock @lock for reading. When @lock is locked for writing, no other thread can lock @lock (neither for reading nor writing). This lock has to be unlocked by g_static_rw_lock_writer_unlock(). Use g_rw_lock_writer_lock() instead a #GStaticRWLock to lock for writing Tries to lock @lock for writing. If @lock is already locked (for either reading or writing) by another thread, it immediately returns %FALSE. Otherwise it locks @lock for writing and returns %TRUE. This lock has to be unlocked by g_static_rw_lock_writer_unlock(). Use g_rw_lock_writer_trylock() instead %TRUE, if @lock could be locked for writing a #GStaticRWLock to lock for writing Unlocks @lock. If a thread is waiting to lock @lock for writing and all locks for reading have been unlocked, the waiting thread is woken up and can lock @lock for writing. If no thread is waiting to lock @lock for writing, and some thread or threads are waiting to lock @lock for reading, the waiting threads are woken up and can lock @lock for reading. Use g_rw_lock_writer_unlock() instead a #GStaticRWLock to unlock after writing. A #GStaticRecMutex works like a #GStaticMutex, but it can be locked multiple times by one thread. If you enter it n times, you have to unlock it n times again to let other threads lock it. An exception is the function g_static_rec_mutex_unlock_full(): that allows you to unlock a #GStaticRecMutex completely returning the depth, (i.e. the number of times this mutex was locked). The depth can later be used to restore the state of the #GStaticRecMutex by calling g_static_rec_mutex_lock_full(). In GLib 2.32, #GStaticRecMutex has been deprecated in favor of #GRecMutex. Even though #GStaticRecMutex is not opaque, it should only be used with the following functions. All of the g_static_rec_mutex_* functions can be used even if g_thread_init() has not been called. Then they do nothing, apart from g_static_rec_mutex_trylock(), which does nothing but returning %TRUE. Releases all resources allocated to a #GStaticRecMutex. You don't have to call this functions for a #GStaticRecMutex with an unbounded lifetime, i.e. objects declared 'static', but if you have a #GStaticRecMutex as a member of a structure and the structure is freed, you should also free the #GStaticRecMutex. Use g_rec_mutex_clear() a #GStaticRecMutex to be freed. A #GStaticRecMutex must be initialized with this function before it can be used. Alternatively you can initialize it with %G_STATIC_REC_MUTEX_INIT. Use g_rec_mutex_init() a #GStaticRecMutex to be initialized. Locks @mutex. If @mutex is already locked by another thread, the current thread will block until @mutex is unlocked by the other thread. If @mutex is already locked by the calling thread, this functions increases the depth of @mutex and returns immediately. Use g_rec_mutex_lock() a #GStaticRecMutex to lock. Works like calling g_static_rec_mutex_lock() for @mutex @depth times. Use g_rec_mutex_lock() a #GStaticRecMutex to lock. number of times this mutex has to be unlocked to be completely unlocked. Tries to lock @mutex. If @mutex is already locked by another thread, it immediately returns %FALSE. Otherwise it locks @mutex and returns %TRUE. If @mutex is already locked by the calling thread, this functions increases the depth of @mutex and immediately returns %TRUE. Use g_rec_mutex_trylock() %TRUE, if @mutex could be locked. a #GStaticRecMutex to lock. Unlocks @mutex. Another thread will be allowed to lock @mutex only when it has been unlocked as many times as it had been locked before. If @mutex is completely unlocked and another thread is blocked in a g_static_rec_mutex_lock() call for @mutex, it will be woken and can lock @mutex itself. Use g_rec_mutex_unlock() a #GStaticRecMutex to unlock. Completely unlocks @mutex. If another thread is blocked in a g_static_rec_mutex_lock() call for @mutex, it will be woken and can lock @mutex itself. This function returns the number of times that @mutex has been locked by the current thread. To restore the state before the call to g_static_rec_mutex_unlock_full() you can call g_static_rec_mutex_lock_full() with the depth returned by this function. Use g_rec_mutex_unlock() number of times @mutex has been locked by the current thread. a #GStaticRecMutex to completely unlock. A `GString` is an object that handles the memory management of a C string. The emphasis of `GString` is on text, typically UTF-8. Crucially, the "str" member of a `GString` is guaranteed to have a trailing nul character, and it is therefore always safe to call functions such as `strchr()` or `strdup()` on it. However, a `GString` can also hold arbitrary binary data, because it has a "len" member, which includes any possible embedded nul characters in the data. Conceptually then, `GString` is like a `GByteArray` with the addition of many convenience methods for text, and a guaranteed nul terminator. points to the character data. It may move as text is added. The @str field is null-terminated and so can be used as an ordinary C string. contains the length of the string, not including the terminating nul byte. the number of bytes that can be stored in the string before it needs to be reallocated. May be larger than @len. Creates a new #GString, initialized with the given string. the new #GString the initial text to copy into the string, or %NULL to start with an empty string Creates a new #GString with @len bytes of the @init buffer. Because a length is provided, @init need not be nul-terminated, and can contain embedded nul bytes. Since this function does not stop at nul bytes, it is the caller's responsibility to ensure that @init has at least @len addressable bytes. a new #GString initial contents of the string length of @init to use Creates a new #GString, initialized with the given string. After this call, @init belongs to the #GString and may no longer be modified by the caller. The memory of @init has to be dynamically allocated and will eventually be freed with g_free(). the new #GString initial text used as the string. Ownership of the string is transferred to the #GString. Passing %NULL creates an empty string. Creates a new #GString, with enough space for @dfl_size bytes. This is useful if you are going to add a lot of text to the string and don't want it to be reallocated too often. the new #GString the default size of the space allocated to hold the string Adds a string onto the end of a #GString, expanding it if necessary. @string a #GString the string to append onto the end of @string Adds a byte onto the end of a #GString, expanding it if necessary. @string a #GString the byte to append onto the end of @string Appends @len bytes of @val to @string. If @len is positive, @val may contain embedded nuls and need not be nul-terminated. It is the caller's responsibility to ensure that @val has at least @len addressable bytes. If @len is negative, @val must be nul-terminated and @len is considered to request the entire string length. This makes g_string_append_len() equivalent to g_string_append(). @string a #GString bytes to append number of bytes of @val to use, or -1 for all of @val Appends a formatted string onto the end of a #GString. This function is similar to g_string_printf() except that the text is appended to the #GString. a #GString the string format. See the printf() documentation the parameters to insert into the format string Converts a Unicode character into UTF-8, and appends it to the string. @string a #GString a Unicode character Appends @unescaped to @string, escaping any characters that are reserved in URIs using URI-style escape sequences. @string a #GString a string a string of reserved characters allowed to be used, or %NULL set %TRUE if the escaped string may include UTF8 characters Appends a formatted string onto the end of a #GString. This function is similar to g_string_append_printf() except that the arguments to the format string are passed as a va_list. a #GString the string format. See the printf() documentation the list of arguments to insert in the output Converts all uppercase ASCII letters to lowercase ASCII letters. passed-in @string pointer, with all the uppercase characters converted to lowercase in place, with semantics that exactly match g_ascii_tolower(). a GString Converts all lowercase ASCII letters to uppercase ASCII letters. passed-in @string pointer, with all the lowercase characters converted to uppercase in place, with semantics that exactly match g_ascii_toupper(). a GString Copies the bytes from a string into a #GString, destroying any previous contents. It is rather like the standard strcpy() function, except that you do not have to worry about having enough space to copy the string. @string the destination #GString. Its current contents are destroyed. the string to copy into @string Copies the [struct@GLib.String] instance and its contents. This will preserve the allocation length of the [struct@GLib.String] in the copy. a copy of @string a string Converts a #GString to lowercase. This function uses the locale-specific tolower() function, which is almost never the right thing. Use g_string_ascii_down() or g_utf8_strdown() instead. the #GString a #GString Compares two strings for equality, returning %TRUE if they are equal. For use with #GHashTable. %TRUE if the strings are the same length and contain the same bytes a #GString another #GString Removes @len bytes from a #GString, starting at position @pos. The rest of the #GString is shifted down to fill the gap. @string a #GString the position of the content to remove the number of bytes to remove, or -1 to remove all following bytes Frees the memory allocated for the #GString. If @free_segment is %TRUE it also frees the character data. If it's %FALSE, the caller gains ownership of the buffer and must free it after use with g_free(). Instead of passing %FALSE to this function, consider using g_string_free_and_steal(). the character data of @string (i.e. %NULL if @free_segment is %TRUE) a #GString if %TRUE, the actual character data is freed as well Frees the memory allocated for the #GString. The caller gains ownership of the buffer and must free it after use with g_free(). the character data of @string a #GString Transfers ownership of the contents of @string to a newly allocated #GBytes. The #GString structure itself is deallocated, and it is therefore invalid to use @string after invoking this function. Note that while #GString ensures that its buffer always has a trailing nul character (not reflected in its "len"), the returned #GBytes does not include this extra nul; i.e. it has length exactly equal to the "len" member. A newly allocated #GBytes containing contents of @string; @string itself is freed a #GString Creates a hash code for @str; for use with #GHashTable. hash code for @str a string to hash Inserts a copy of a string into a #GString, expanding it if necessary. @string a #GString the position to insert the copy of the string the string to insert Inserts a byte into a #GString, expanding it if necessary. @string a #GString the position to insert the byte the byte to insert Inserts @len bytes of @val into @string at @pos. If @len is positive, @val may contain embedded nuls and need not be nul-terminated. It is the caller's responsibility to ensure that @val has at least @len addressable bytes. If @len is negative, @val must be nul-terminated and @len is considered to request the entire string length. If @pos is -1, bytes are inserted at the end of the string. @string a #GString position in @string where insertion should happen, or -1 for at the end bytes to insert number of bytes of @val to insert, or -1 for all of @val Converts a Unicode character into UTF-8, and insert it into the string at the given position. @string a #GString the position at which to insert character, or -1 to append at the end of the string a Unicode character Overwrites part of a string, lengthening it if necessary. @string a #GString the position at which to start overwriting the string that will overwrite the @string starting at @pos Overwrites part of a string, lengthening it if necessary. This function will work with embedded nuls. @string a #GString the position at which to start overwriting the string that will overwrite the @string starting at @pos the number of bytes to write from @val Adds a string on to the start of a #GString, expanding it if necessary. @string a #GString the string to prepend on the start of @string Adds a byte onto the start of a #GString, expanding it if necessary. @string a #GString the byte to prepend on the start of the #GString Prepends @len bytes of @val to @string. If @len is positive, @val may contain embedded nuls and need not be nul-terminated. It is the caller's responsibility to ensure that @val has at least @len addressable bytes. If @len is negative, @val must be nul-terminated and @len is considered to request the entire string length. This makes g_string_prepend_len() equivalent to g_string_prepend(). @string a #GString bytes to prepend number of bytes in @val to prepend, or -1 for all of @val Converts a Unicode character into UTF-8, and prepends it to the string. @string a #GString a Unicode character Writes a formatted string into a #GString. This is similar to the standard sprintf() function, except that the #GString buffer automatically expands to contain the results. The previous contents of the #GString are destroyed. a #GString the string format. See the printf() documentation the parameters to insert into the format string Replaces the string @find with the string @replace in a #GString up to @limit times. If the number of instances of @find in the #GString is less than @limit, all instances are replaced. If @limit is `0`, all instances of @find are replaced. If @find is the empty string, since versions 2.69.1 and 2.68.4 the replacement will be inserted no more than once per possible position (beginning of string, end of string and between characters). This did not work correctly in earlier versions. If @limit is zero and more than `G_MAXUINT` instances of @find are in the input string, they will all be replaced, but the return value will be capped at `G_MAXUINT`. the number of find and replace operations performed, up to `G_MAXUINT` a #GString the string to find in @string the string to insert in place of @find the maximum instances of @find to replace with @replace, or `0` for no limit Sets the length of a #GString. If the length is less than the current length, the string will be truncated. If the length is greater than the current length, the contents of the newly added area are undefined. (However, as always, string->str[string->len] will be a nul byte.) @string a #GString the new length Cuts off the end of the GString, leaving the first @len bytes. @string a #GString the new size of @string Converts a #GString to uppercase. This function uses the locale-specific toupper() function, which is almost never the right thing. Use g_string_ascii_up() or g_utf8_strup() instead. @string a #GString Writes a formatted string into a #GString. This function is similar to g_string_printf() except that the arguments to the format string are passed as a va_list. a #GString the string format. See the printf() documentation the parameters to insert into the format string `GStringChunk` provides efficient storage of groups of strings String chunks are used to store groups of strings. Memory is allocated in blocks, and as strings are added to the `GStringChunk` they are copied into the next free position in a block. When a block is full a new block is allocated. When storing a large number of strings, string chunks are more efficient than using [func@GLib.strdup] since fewer calls to `malloc()` are needed, and less memory is wasted in memory allocation overheads. By adding strings with [method@GLib.StringChunk.insert_const] it is also possible to remove duplicates. To create a new `GStringChunk` use [func@GLib.StringChunk.new]. To add strings to a `GStringChunk` use [method@GLib.StringChunk.insert]. To add strings to a `GStringChunk`, but without duplicating strings which are already in the `GStringChunk`, use [method@GLib.StringChunk.insert_const]. To free the entire `GStringChunk` use [method@GLib.StringChunk.free]. It is not possible to free individual strings. Frees all strings contained within the #GStringChunk. After calling g_string_chunk_clear() it is not safe to access any of the strings which were contained within it. a #GStringChunk Frees all memory allocated by the #GStringChunk. After calling g_string_chunk_free() it is not safe to access any of the strings which were contained within it. a #GStringChunk Adds a copy of @string to the #GStringChunk. It returns a pointer to the new copy of the string in the #GStringChunk. The characters in the string can be changed, if necessary, though you should not change anything after the end of the string. Unlike g_string_chunk_insert_const(), this function does not check for duplicates. Also strings added with g_string_chunk_insert() will not be searched by g_string_chunk_insert_const() when looking for duplicates. a pointer to the copy of @string within the #GStringChunk a #GStringChunk the string to add Adds a copy of @string to the #GStringChunk, unless the same string has already been added to the #GStringChunk with g_string_chunk_insert_const(). This function is useful if you need to copy a large number of strings but do not want to waste space storing duplicates. But you must remember that there may be several pointers to the same string, and so any changes made to the strings should be done very carefully. Note that g_string_chunk_insert_const() will not return a pointer to a string added with g_string_chunk_insert(), even if they do match. a pointer to the new or existing copy of @string within the #GStringChunk a #GStringChunk the string to add Adds a copy of the first @len bytes of @string to the #GStringChunk. The copy is nul-terminated. Since this function does not stop at nul bytes, it is the caller's responsibility to ensure that @string has at least @len addressable bytes. The characters in the returned string can be changed, if necessary, though you should not change anything after the end of the string. a pointer to the copy of @string within the #GStringChunk a #GStringChunk bytes to insert number of bytes of @string to insert, or -1 to insert a nul-terminated string Creates a new #GStringChunk. a new #GStringChunk the default size of the blocks of memory which are allocated to store the strings. If a particular string is larger than this default size, a larger block of memory will be allocated for it. `GStrvBuilder` is a helper object to build a %NULL-terminated string arrays. The following example shows how to build a two element array: ```c g_autoptr(GStrvBuilder) builder = g_strv_builder_new (); g_strv_builder_add (builder, "hello"); g_strv_builder_add (builder, "world"); g_auto(GStrv) array = g_strv_builder_end (builder); g_assert_true (g_strv_equal (array, (const char *[]) { "hello", "world", NULL })); ``` Creates a new #GStrvBuilder with a reference count of 1. Use g_strv_builder_unref() on the returned value when no longer needed. the new #GStrvBuilder Add a string to the end of the array. Since 2.68 a #GStrvBuilder a string. Appends all the given strings to the builder. Since 2.70 a #GStrvBuilder one or more strings followed by %NULL Appends all the strings in the given vector to the builder. Since 2.70 a #GStrvBuilder the vector of strings to add Ends the builder process and returns the constructed NULL-terminated string array. The returned value should be freed with g_strfreev() when no longer needed. the constructed string array. Since 2.68 a #GStrvBuilder Atomically increments the reference count of @builder by one. This function is thread-safe and may be called from any thread. The passed in #GStrvBuilder a #GStrvBuilder Add a string to the end of the array. After @value belongs to the #GStrvBuilder and may no longer be modified by the caller. Since 2.80 a #GStrvBuilder a string. Ownership of the string is transferred to the #GStrvBuilder Decreases the reference count on @builder. In the event that there are no more references, releases all memory associated with the #GStrvBuilder. a #GStrvBuilder allocated by g_strv_builder_new() Decreases the reference count on the string vector builder, and returns its contents as a `NULL`-terminated string array. This function is especially useful for cases where it's not possible to use `g_autoptr()`. ```c GStrvBuilder *builder = g_strv_builder_new (); g_strv_builder_add (builder, "hello"); g_strv_builder_add (builder, "world"); GStrv array = g_strv_builder_unref_to_strv (builder); g_assert_true (g_strv_equal (array, (const char *[]) { "hello", "world", NULL })); g_strfreev (array); ``` the constructed string array a #GStrvBuilder A value that can be passed as an option to [func@GLib.test_init]. Creates a unique temporary directory for each unit test and uses sets XDG directories to point into subdirectories of it for the duration of the unit test. The directory tree is cleaned up after the test finishes successfully. Note that this doesn’t take effect until [func@GLib.test_run] is called, so calls to (for example) [func@GLib.get_home_dir] will return the system-wide value when made in a test program’s main() function. The following functions will return subdirectories of the temporary directory when this option is used. The specific subdirectory paths in use are not guaranteed to be stable API — always use a getter function to retrieve them. - [func@GLib.get_home_dir] - [func@GLib.get_user_cache_dir] - [func@GLib.get_system_config_dirs] - [func@GLib.get_user_config_dir] - [func@GLib.get_system_data_dirs] - [func@GLib.get_user_data_dir] - [func@GLib.get_user_state_dir] - [func@GLib.get_user_runtime_dir] The subdirectories may not be created by the test harness; as with normal calls to functions like [func@GLib.get_user_cache_dir], the caller must be prepared to create the directory if it doesn’t exist. A value that can be passed as an option to [func@GLib.test_init]. If this option is given, assertions will not abort the process, but call [func@GLib.test_fail]. Equivalent to [func@GLib.test_set_nonfatal_assertions]. A value that can be passed as an option to [func@GLib.test_init]. If this option is given, [func@GLib.test_init] will not call [func@GLib.set_prgname]. Evaluates to a time span of one day. Evaluates to a time span of one hour. Evaluates to a time span of one millisecond. Evaluates to a time span of one minute. Evaluates to a time span of one second. Works like g_mutex_trylock(), but for a lock defined with %G_LOCK_DEFINE. the name of the lock An opaque structure representing a test case. Free the @test_case. a test case The type used for test case functions that take an extra pointer argument. the data provided when registering the test The type of file to return the filename for, when used with [func@GLib.test_build_filename]. These two options correspond rather directly to the 'dist' and 'built' terminology that automake uses and are explicitly used to distinguish between the 'srcdir' and 'builddir' being separate. All files in your project should either be dist (in the `EXTRA_DIST` or `dist_schema_DATA` sense, in which case they will always be in the srcdir) or built (in the `BUILT_SOURCES` sense, in which case they will always be in the builddir). Note: As a general rule of automake, files that are generated only as part of the build-from-git process (but then are distributed with the tarball) always go in srcdir (even if doing a srcdir != builddir build from git) and are considered as distributed files. The same principles apply for other build systems, such as meson. a file that was included in the distribution tarball a file that was built on the compiling machine The type used for functions that operate on test fixtures. This is used for the fixture setup and teardown functions as well as for the testcases themselves. @user_data is a pointer to the data that was given when registering the test case. @fixture will be a pointer to the area of memory allocated by the test framework, of the size requested. If the requested size was zero then @fixture will be equal to @user_data. the test fixture the data provided when registering the test The type used for test case functions. Internal function for gtester to free test log messages, no ABI guarantees provided. Internal function for gtester to retrieve test log messages, no ABI guarantees provided. Internal function for gtester to decode test log messages, no ABI guarantees provided. Internal function for gtester to decode test log messages, no ABI guarantees provided. Specifies the prototype of fatal log handler functions. %TRUE if the program should abort, %FALSE otherwise the log domain of the message the log level of the message (including the fatal and recursion flags) the message to process user data, set in g_test_log_set_fatal_handler() Internal function for gtester to free test log messages, no ABI guarantees provided. Flags to pass to [func@GLib.test_trap_subprocess] to control input and output. Note that in contrast with [func@GLib.test_trap_fork], the default behavior of [func@GLib.test_trap_subprocess] is to not show stdout and stderr. Default behaviour. Since: 2.74 If this flag is given, the child process will inherit the parent's stdin. Otherwise, the child's stdin is redirected to `/dev/null`. If this flag is given, the child process will inherit the parent's stdout. Otherwise, the child's stdout will not be visible, but it will be captured to allow later tests with [func@GLib.test_trap_assert_stdout]. If this flag is given, the child process will inherit the parent's stderr. Otherwise, the child's stderr will not be visible, but it will be captured to allow later tests with [func@GLib.test_trap_assert_stderr]. If this flag is given, the child process will inherit the parent’s open file descriptors. An opaque structure representing a test suite. Adds @test_case to @suite. a test suite a test case Adds @nestedsuite to @suite. a test suite another test suite Frees the @suite and all nested suites. a test suite Flags to pass to [func@GLib.test_trap_fork] to control input and output. Test traps are guards around forked tests. These flags determine what traps to set. `GTestTrapFlags` is used only with [func@GLib.test_trap_fork], which is deprecated. Its replacement, [func@GLib.test_trap_subprocess] uses [flags@GLib.TestSubprocessFlags]. Default behaviour. Since: 2.74 Redirect stdout of the test child to `/dev/null` so it cannot be observed on the console during test runs. The actual output is still captured though to allow later tests with g_test_trap_assert_stdout(). Redirect stderr of the test child to `/dev/null` so it cannot be observed on the console during test runs. The actual output is still captured though to allow later tests with g_test_trap_assert_stderr(). If this flag is given, stdin of the child process is shared with stdin of its parent process. It is redirected to `/dev/null` otherwise. The #GThread struct represents a running thread. This struct is returned by g_thread_new() or g_thread_try_new(). You can obtain the #GThread struct representing the current thread by calling g_thread_self(). GThread is refcounted, see g_thread_ref() and g_thread_unref(). The thread represented by it holds a reference while it is running, and g_thread_join() consumes the reference that it is given, so it is normally not necessary to manage GThread references explicitly. The structure is opaque -- none of its fields may be directly accessed. This function creates a new thread. The new thread starts by invoking @func with the argument data. The thread will run until @func returns or until g_thread_exit() is called from the new thread. The return value of @func becomes the return value of the thread, which can be obtained with g_thread_join(). The @name can be useful for discriminating threads in a debugger. It is not used for other purposes and does not have to be unique. Some systems restrict the length of @name to 16 bytes. If the thread can not be created the program aborts. See g_thread_try_new() if you want to attempt to deal with failures. If you are using threads to offload (potentially many) short-lived tasks, #GThreadPool may be more appropriate than manually spawning and tracking multiple #GThreads. To free the struct returned by this function, use g_thread_unref(). Note that g_thread_join() implicitly unrefs the #GThread as well. New threads by default inherit their scheduler policy (POSIX) or thread priority (Windows) of the thread creating the new thread. This behaviour changed in GLib 2.64: before threads on Windows were not inheriting the thread priority but were spawned with the default priority. Starting with GLib 2.64 the behaviour is now consistent between Windows and POSIX and all threads inherit their parent thread's priority. the new #GThread an (optional) name for the new thread a function to execute in the new thread an argument to supply to the new thread This function is the same as g_thread_new() except that it allows for the possibility of failure. If a thread can not be created (due to resource limits), @error is set and %NULL is returned. the new #GThread, or %NULL if an error occurred an (optional) name for the new thread a function to execute in the new thread an argument to supply to the new thread Gets the name of the thread. This function is intended for debugging purposes. the name of the thread a thread Waits until @thread finishes, i.e. the function @func, as given to g_thread_new(), returns or g_thread_exit() is called. If @thread has already terminated, then g_thread_join() returns immediately. Any thread can wait for any other thread by calling g_thread_join(), not just its 'creator'. Calling g_thread_join() from multiple threads for the same @thread leads to undefined behaviour. The value returned by @func or given to g_thread_exit() is returned by this function. g_thread_join() consumes the reference to the passed-in @thread. This will usually cause the #GThread struct and associated resources to be freed. Use g_thread_ref() to obtain an extra reference if you want to keep the GThread alive beyond the g_thread_join() call. the return value of the thread a #GThread Increase the reference count on @thread. a new reference to @thread a #GThread This function does nothing. Thread priorities no longer have any effect. a #GThread. ignored Decrease the reference count on @thread, possibly freeing all resources associated with it. Note that each thread holds a reference to its #GThread while it is running, so it is safe to drop your own reference to it if you don't need it anymore. a #GThread This function creates a new thread. The new thread executes the function @func with the argument @data. If the thread was created successfully, it is returned. @error can be %NULL to ignore errors, or non-%NULL to report errors. The error is set, if and only if the function returns %NULL. This function returns a reference to the created thread only if @joinable is %TRUE. In that case, you must free this reference by calling g_thread_unref() or g_thread_join(). If @joinable is %FALSE then you should probably not touch the return value. Use g_thread_new() instead the new #GThread on success a function to execute in the new thread an argument to supply to the new thread should this thread be joinable? This function creates a new thread. The @bound and @priority arguments are now ignored. Use g_thread_new(). the new #GThread on success. a function to execute in the new thread. an argument to supply to the new thread. a stack size for the new thread. should this thread be joinable? ignored ignored Terminates the current thread. If another thread is waiting for us using g_thread_join() then the waiting thread will be woken up and get @retval as the return value of g_thread_join(). Calling g_thread_exit() with a parameter @retval is equivalent to returning @retval from the function @func, as given to g_thread_new(). You must only call g_thread_exit() from a thread that you created yourself with g_thread_new() or related APIs. You must not call this function from a thread created with another threading library or or from within a #GThreadPool. the return value of this thread Call @thread_func on all #GThreads that have been created with g_thread_create(). Note that threads may decide to exit while @thread_func is running, so without intimate knowledge about the lifetime of foreign threads, @thread_func shouldn't access the GThread* pointer passed in as first argument. However, @thread_func will not be called for threads which are known to have exited already. Due to thread lifetime checks, this function has an execution complexity which is quadratic in the number of existing threads. There aren't many things you can do with a #GThread, except comparing it with one that was returned from g_thread_create(). There are better ways to find out if your thread is still alive. function to call for all #GThread structures second argument to @thread_func Indicates if g_thread_init() has been called. %TRUE if threads have been initialized. If you use GLib from more than one thread, you must initialize the thread system by calling g_thread_init(). Since version 2.24, calling g_thread_init() multiple times is allowed, but nothing happens except for the first call. Since version 2.32, GLib does not support custom thread implementations anymore and the @vtable parameter is ignored and you should pass %NULL. ::: note g_thread_init() must not be called directly or indirectly in a callback from GLib. Also no mutexes may be currently locked while calling g_thread_init(). ::: note To use g_thread_init() in your program, you have to link with the libraries that the command `pkg-config --libs gthread-2.0` outputs. This is not the case for all the other thread-related functions of GLib. Those can be used without having to link with the thread libraries. This function is no longer necessary. The GLib threading system is automatically initialized at the start of your program. a function table of type #GThreadFunctions, that provides the entry points to the thread system to be used. Since 2.32, this parameter is ignored and should always be %NULL This function returns the #GThread corresponding to the current thread. Note that this function does not increase the reference count of the returned struct. This function will return a #GThread even for threads that were not created by GLib (i.e. those created by other threading APIs). This may be useful for thread identification purposes (i.e. comparisons) but you must not use GLib functions (such as g_thread_join()) on these threads. the #GThread representing the current thread Causes the calling thread to voluntarily relinquish the CPU, so that other threads can run. This function is often used as a method to make busy wait less evil. Possible errors of thread related functions. a thread couldn't be created due to resource shortage. Try again later. Specifies the type of the @func functions passed to g_thread_new() or g_thread_try_new(). the return value of the thread data passed to the thread This function table is no longer used by g_thread_init() to initialize the thread system. virtual function pointer for g_mutex_new() virtual function pointer for g_mutex_lock() virtual function pointer for g_mutex_trylock() virtual function pointer for g_mutex_unlock() virtual function pointer for g_mutex_free() virtual function pointer for g_cond_new() virtual function pointer for g_cond_signal() virtual function pointer for g_cond_broadcast() virtual function pointer for g_cond_wait() virtual function pointer for g_cond_timed_wait() virtual function pointer for g_cond_free() virtual function pointer for g_private_new() virtual function pointer for g_private_get() virtual function pointer for g_private_set() virtual function pointer for g_thread_create() virtual function pointer for g_thread_yield() virtual function pointer for g_thread_join() virtual function pointer for g_thread_exit() virtual function pointer for g_thread_set_priority() virtual function pointer for g_thread_self() used internally by recursive mutex locks and by some assertion checks The `GThreadPool` struct represents a thread pool. A thread pool is useful when you wish to asynchronously fork out the execution of work and continue working in your own thread. If that will happen often, the overhead of starting and destroying a thread each time might be too high. In such cases reusing already started threads seems like a good idea. And it indeed is, but implementing this can be tedious and error-prone. Therefore GLib provides thread pools for your convenience. An added advantage is, that the threads can be shared between the different subsystems of your program, when they are using GLib. To create a new thread pool, you use [func@GLib.ThreadPool.new]. It is destroyed by [method@GLib.ThreadPool.free]. If you want to execute a certain task within a thread pool, use [method@GLib.ThreadPool.push]. To get the current number of running threads you call [method@GLib.ThreadPool.get_num_threads]. To get the number of still unprocessed tasks you call [method@GLib.ThreadPool.unprocessed]. To control the maximum number of threads for a thread pool, you use [method@GLib.ThreadPool.get_max_threads]. and [method@GLib.ThreadPool.set_max_threads]. Finally you can control the number of unused threads, that are kept alive by GLib for future use. The current number can be fetched with [func@GLib.ThreadPool.get_num_unused_threads]. The maximum number can be controlled by [func@GLib.ThreadPool.get_max_unused_threads] and [func@GLib.ThreadPool.set_max_unused_threads]. All currently unused threads can be stopped by calling [func@GLib.ThreadPool.stop_unused_threads]. the function to execute in the threads of this pool the user data for the threads of this pool are all threads exclusive to this pool Frees all resources allocated for @pool. If @immediate is %TRUE, no new task is processed for @pool. Otherwise @pool is not freed before the last task is processed. Note however, that no thread of this pool is interrupted while processing a task. Instead at least all still running threads can finish their tasks before the @pool is freed. If @wait_ is %TRUE, this function does not return before all tasks to be processed (dependent on @immediate, whether all or only the currently running) are ready. Otherwise this function returns immediately. After calling this function @pool must not be used anymore. a #GThreadPool should @pool shut down immediately? should the function wait for all tasks to be finished? Returns the maximal number of threads for @pool. the maximal number of threads a #GThreadPool Returns the number of threads currently running in @pool. the number of threads currently running a #GThreadPool Moves the item to the front of the queue of unprocessed items, so that it will be processed next. %TRUE if the item was found and moved a #GThreadPool an unprocessed item in the pool Inserts @data into the list of tasks to be executed by @pool. When the number of currently running threads is lower than the maximal allowed number of threads, a new thread is started (or reused) with the properties given to g_thread_pool_new(). Otherwise, @data stays in the queue until a thread in this pool finishes its previous task and processes @data. @error can be %NULL to ignore errors, or non-%NULL to report errors. An error can only occur when a new thread couldn't be created. In that case @data is simply appended to the queue of work to do. Before version 2.32, this function did not return a success status. %TRUE on success, %FALSE if an error occurred a #GThreadPool a new task for @pool Sets the maximal allowed number of threads for @pool. A value of -1 means that the maximal number of threads is unlimited. If @pool is an exclusive thread pool, setting the maximal number of threads to -1 is not allowed. Setting @max_threads to 0 means stopping all work for @pool. It is effectively frozen until @max_threads is set to a non-zero value again. A thread is never terminated while calling @func, as supplied by g_thread_pool_new(). Instead the maximal number of threads only has effect for the allocation of new threads in g_thread_pool_push(). A new thread is allocated, whenever the number of currently running threads in @pool is smaller than the maximal number. @error can be %NULL to ignore errors, or non-%NULL to report errors. An error can only occur when a new thread couldn't be created. Before version 2.32, this function did not return a success status. %TRUE on success, %FALSE if an error occurred a #GThreadPool a new maximal number of threads for @pool, or -1 for unlimited Sets the function used to sort the list of tasks. This allows the tasks to be processed by a priority determined by @func, and not just in the order in which they were added to the pool. Note, if the maximum number of threads is more than 1, the order that threads are executed cannot be guaranteed 100%. Threads are scheduled by the operating system and are executed at random. It cannot be assumed that threads are executed in the order they are created. a #GThreadPool the #GCompareDataFunc used to sort the list of tasks. This function is passed two tasks. It should return 0 if the order in which they are handled does not matter, a negative value if the first task should be processed before the second or a positive value if the second task should be processed first. user data passed to @func Returns the number of tasks still unprocessed in @pool. the number of unprocessed tasks a #GThreadPool This function will return the maximum @interval that a thread will wait in the thread pool for new tasks before being stopped. If this function returns 0, threads waiting in the thread pool for new work are not stopped. the maximum @interval (milliseconds) to wait for new tasks in the thread pool before stopping the thread Returns the maximal allowed number of unused threads. the maximal number of unused threads Returns the number of currently unused threads. the number of currently unused threads This function creates a new thread pool. Whenever you call g_thread_pool_push(), either a new thread is created or an unused one is reused. At most @max_threads threads are running concurrently for this thread pool. @max_threads = -1 allows unlimited threads to be created for this thread pool. The newly created or reused thread now executes the function @func with the two arguments. The first one is the parameter to g_thread_pool_push() and the second one is @user_data. Pass g_get_num_processors() to @max_threads to create as many threads as there are logical processors on the system. This will not pin each thread to a specific processor. The parameter @exclusive determines whether the thread pool owns all threads exclusive or shares them with other thread pools. If @exclusive is %TRUE, @max_threads threads are started immediately and they will run exclusively for this thread pool until it is destroyed by g_thread_pool_free(). If @exclusive is %FALSE, threads are created when needed and shared between all non-exclusive thread pools. This implies that @max_threads may not be -1 for exclusive thread pools. Besides, exclusive thread pools are not affected by g_thread_pool_set_max_idle_time() since their threads are never considered idle and returned to the global pool. Note that the threads used by exclusive thread pools will all inherit the scheduler settings of the current thread while the threads used by non-exclusive thread pools will inherit the scheduler settings from the first thread that created such a thread pool. At least one thread will be spawned when this function is called, either to create the @max_threads exclusive threads, or to preserve the scheduler settings of the current thread for future spawns. @error can be %NULL to ignore errors, or non-%NULL to report errors. An error can only occur when @exclusive is set to %TRUE and not all @max_threads threads could be created. See #GThreadError for possible errors that may occur. Note, even in case of error a valid #GThreadPool is returned. the new #GThreadPool a function to execute in the threads of the new thread pool user data that is handed over to @func every time it is called the maximal number of threads to execute concurrently in the new thread pool, -1 means no limit should this thread pool be exclusive? This function creates a new thread pool similar to g_thread_pool_new() but allowing @item_free_func to be specified to free the data passed to g_thread_pool_push() in the case that the #GThreadPool is stopped and freed before all tasks have been executed. @item_free_func will *not* be called on items successfully passed to @func. @func is responsible for freeing the items passed to it. the new #GThreadPool a function to execute in the threads of the new thread pool user data that is handed over to @func every time it is called used to pass as a free function to g_async_queue_new_full() the maximal number of threads to execute concurrently in the new thread pool, `-1` means no limit should this thread pool be exclusive? This function will set the maximum @interval that a thread waiting in the pool for new tasks can be idle for before being stopped. This function is similar to calling g_thread_pool_stop_unused_threads() on a regular timeout, except this is done on a per thread basis. By setting @interval to 0, idle threads will not be stopped. The default value is 15000 (15 seconds). the maximum @interval (in milliseconds) a thread can be idle Sets the maximal number of unused threads to @max_threads. If @max_threads is -1, no limit is imposed on the number of unused threads. The default value is 8 since GLib 2.84. Previously the default value was 2. maximal number of unused threads Stops all currently unused threads. This does not change the maximal number of unused threads. This function can be used to regularly stop all unused threads e.g. from g_timeout_add(). Thread priorities. Thread priorities no longer have any effect. a priority lower than normal the default priority a priority higher than normal the highest priority Disambiguates a given time in two ways. First, specifies if the given time is in universal or local time. Second, if the time is in local time, specifies if it is local standard time or local daylight time. This is important for the case where the same local time occurs twice (during daylight savings time transitions, for example). the time is in local standard time the time is in local daylight time the time is in UTC Represents a precise time, with seconds and microseconds. Similar to the struct timeval returned by the `gettimeofday()` UNIX system call. GLib is attempting to unify around the use of 64-bit integers to represent microsecond-precision time. As such, this type will be removed from a future version of GLib. A consequence of using `glong` for `tv_sec` is that on 32-bit systems `GTimeVal` is subject to the year 2038 problem. Use #GDateTime or #guint64 instead. seconds microseconds Adds the given number of microseconds to @time_. @microseconds can also be negative to decrease the value of @time_. #GTimeVal is not year-2038-safe. Use `guint64` for representing microseconds since the epoch, or use #GDateTime. a #GTimeVal number of microseconds to add to @time Converts @time_ into an RFC 3339 encoded string, relative to the Coordinated Universal Time (UTC). This is one of the many formats allowed by ISO 8601. ISO 8601 allows a large number of date/time formats, with or without punctuation and optional elements. The format returned by this function is a complete date and time, with optional punctuation included, the UTC time zone represented as "Z", and the @tv_usec part included if and only if it is nonzero, i.e. either "YYYY-MM-DDTHH:MM:SSZ" or "YYYY-MM-DDTHH:MM:SS.fffffZ". This corresponds to the Internet date/time format defined by [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt), and to either of the two most-precise formats defined by the W3C Note [Date and Time Formats](http://www.w3.org/TR/NOTE-datetime-19980827). Both of these documents are profiles of ISO 8601. Use g_date_time_format() or g_strdup_printf() if a different variation of ISO 8601 format is required. If @time_ represents a date which is too large to fit into a `struct tm`, %NULL will be returned. This is platform dependent. Note also that since `GTimeVal` stores the number of seconds as a `glong`, on 32-bit systems it is subject to the year 2038 problem. Accordingly, since GLib 2.62, this function has been deprecated. Equivalent functionality is available using: |[ GDateTime *dt = g_date_time_new_from_unix_utc (time_val); iso8601_string = g_date_time_format_iso8601 (dt); g_date_time_unref (dt); ]| The return value of g_time_val_to_iso8601() has been nullable since GLib 2.54; before then, GLib would crash under the same conditions. #GTimeVal is not year-2038-safe. Use g_date_time_format_iso8601(dt) instead. a newly allocated string containing an ISO 8601 date, or %NULL if @time_ was too large a #GTimeVal Converts a string containing an ISO 8601 encoded date and time to a #GTimeVal and puts it into @time_. @iso_date must include year, month, day, hours, minutes, and seconds. It can optionally include fractions of a second and a time zone indicator. (In the absence of any time zone indication, the timestamp is assumed to be in local time.) Any leading or trailing space in @iso_date is ignored. This function was deprecated, along with #GTimeVal itself, in GLib 2.62. Equivalent functionality is available using code like: |[ GDateTime *dt = g_date_time_new_from_iso8601 (iso8601_string, NULL); gint64 time_val = g_date_time_to_unix (dt); g_date_time_unref (dt); ]| #GTimeVal is not year-2038-safe. Use g_date_time_new_from_iso8601() instead. %TRUE if the conversion was successful. an ISO 8601 encoded date string a #GTimeVal A `GTimeZone` represents a time zone, at no particular point in time. The `GTimeZone` struct is refcounted and immutable. Each time zone has an identifier (for example, ‘Europe/London’) which is platform dependent. See [ctor@GLib.TimeZone.new] for information on the identifier formats. The identifier of a time zone can be retrieved using [method@GLib.TimeZone.get_identifier]. A time zone contains a number of intervals. Each interval has an abbreviation to describe it (for example, ‘PDT’), an offset to UTC and a flag indicating if the daylight savings time is in effect during that interval. A time zone always has at least one interval — interval 0. Note that interval abbreviations are not the same as time zone identifiers (apart from ‘UTC’), and cannot be passed to [ctor@GLib.TimeZone.new]. Every UTC time is contained within exactly one interval, but a given local time may be contained within zero, one or two intervals (due to incontinuities associated with daylight savings time). An interval may refer to a specific period of time (eg: the duration of daylight savings time during 2010) or it may refer to many periods of time that share the same properties (eg: all periods of daylight savings time). It is also possible (usually for political reasons) that some properties (like the abbreviation) change between intervals without other properties changing. A version of g_time_zone_new_identifier() which returns the UTC time zone if @identifier could not be parsed or loaded. If you need to check whether @identifier was loaded successfully, use g_time_zone_new_identifier(). Use g_time_zone_new_identifier() instead, as it provides error reporting. Change your code to handle a potentially %NULL return value. the requested timezone a timezone identifier Creates a #GTimeZone corresponding to @identifier. If @identifier cannot be parsed or loaded, %NULL is returned. @identifier can either be an RFC3339/ISO 8601 time offset or something that would pass as a valid value for the `TZ` environment variable (including %NULL). In Windows, @identifier can also be the unlocalized name of a time zone for standard time, for example "Pacific Standard Time". Valid RFC3339 time offsets are `"Z"` (for UTC) or `"±hh:mm"`. ISO 8601 additionally specifies `"±hhmm"` and `"±hh"`. Offsets are time values to be added to Coordinated Universal Time (UTC) to get the local time. In UNIX, the `TZ` environment variable typically corresponds to the name of a file in the zoneinfo database, an absolute path to a file somewhere else, or a string in "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format. There are no spaces in the specification. The name of standard and daylight savings time zone must be three or more alphabetic characters. Offsets are time values to be added to local time to get Coordinated Universal Time (UTC) and should be `"[±]hh[[:]mm[:ss]]"`. Dates are either `"Jn"` (Julian day with n between 1 and 365, leap years not counted), `"n"` (zero-based Julian day with n between 0 and 365) or `"Mm.w.d"` (day d (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day 0 is a Sunday). Times are in local wall clock time, the default is 02:00:00. In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also accepts POSIX format. The Windows format uses US rules for all time zones; daylight savings time is 60 minutes behind the standard time with date and time of change taken from Pacific Standard Time. Offsets are time values to be added to the local time to get Coordinated Universal Time (UTC). g_time_zone_new_local() calls this function with the value of the `TZ` environment variable. This function itself is independent of the value of `TZ`, but if @identifier is %NULL then `/etc/localtime` will be consulted to discover the correct time zone on UNIX and the registry will be consulted or GetTimeZoneInformation() will be used to get the local time zone on Windows. If intervals are not available, only time zone rules from `TZ` environment variable or other means, then they will be computed from year 1900 to 2037. If the maximum year for the rules is available and it is greater than 2037, then it will followed instead. See [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6) for a precise definition of valid RFC3339 time offsets (the `time-offset` expansion) and ISO 8601 for the full list of valid time offsets. See [The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html) for an explanation of the possible values of the `TZ` environment variable. See [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx) for the list of time zones on Windows. You should release the return value by calling g_time_zone_unref() when you are done with it. the requested timezone, or %NULL on failure a timezone identifier Creates a #GTimeZone corresponding to local time. The local time zone may change between invocations to this function; for example, if the system administrator changes it. This is equivalent to calling g_time_zone_new() with the value of the `TZ` environment variable (including the possibility of %NULL). You should release the return value by calling g_time_zone_unref() when you are done with it. the local timezone Creates a #GTimeZone corresponding to the given constant offset from UTC, in seconds. This is equivalent to calling g_time_zone_new() with a string in the form `[+|-]hh[:mm[:ss]]`. It is possible for this function to fail if @seconds is too big (greater than 24 hours), in which case this function will return the UTC timezone for backwards compatibility. To detect failures like this, use g_time_zone_new_identifier() directly. a timezone at the given offset from UTC, or UTC on failure offset to UTC, in seconds Creates a #GTimeZone corresponding to UTC. This is equivalent to calling g_time_zone_new() with a value like "Z", "UTC", "+00", etc. You should release the return value by calling g_time_zone_unref() when you are done with it. the universal timezone Finds an interval within @tz that corresponds to the given @time_, possibly adjusting @time_ if required to fit into an interval. The meaning of @time_ depends on @type. This function is similar to g_time_zone_find_interval(), with the difference that it always succeeds (by making the adjustments described below). In any of the cases where g_time_zone_find_interval() succeeds then this function returns the same value, without modifying @time_. This function may, however, modify @time_ in order to deal with non-existent times. If the non-existent local @time_ of 02:30 were requested on March 14th 2010 in Toronto then this function would adjust @time_ to be 03:00 and return the interval containing the adjusted time. the interval containing @time_, never -1 a #GTimeZone the #GTimeType of @time_ a pointer to a number of seconds since January 1, 1970 Finds an interval within @tz that corresponds to the given @time_. The meaning of @time_ depends on @type. If @type is %G_TIME_TYPE_UNIVERSAL then this function will always succeed (since universal time is monotonic and continuous). Otherwise @time_ is treated as local time. The distinction between %G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in the case that the given @time_ is ambiguous. In Toronto, for example, 01:30 on November 7th 2010 occurred twice (once inside of daylight savings time and the next, an hour later, outside of daylight savings time). In this case, the different value of @type would result in a different interval being returned. It is still possible for this function to fail. In Toronto, for example, 02:00 on March 14th 2010 does not exist (due to the leap forward to begin daylight savings time). -1 is returned in that case. the interval containing @time_, or -1 in case of failure a #GTimeZone the #GTimeType of @time_ a number of seconds since January 1, 1970 Determines the time zone abbreviation to be used during a particular @interval of time in the time zone @tz. For example, in Toronto this is currently "EST" during the winter months and "EDT" during the summer months when daylight savings time is in effect. the time zone abbreviation, which belongs to @tz a #GTimeZone an interval within the timezone Get the identifier of this #GTimeZone, as passed to g_time_zone_new(). If the identifier passed at construction time was not recognised, `UTC` will be returned. If it was %NULL, the identifier of the local timezone at construction time will be returned. The identifier will be returned in the same format as provided at construction time: if provided as a time offset, that will be returned by this function. identifier for this timezone a #GTimeZone Determines the offset to UTC in effect during a particular @interval of time in the time zone @tz. The offset is the number of seconds that you add to UTC time to arrive at local time for @tz (ie: negative numbers for time zones west of GMT, positive numbers for east). the number of seconds that should be added to UTC to get the local time in @tz a #GTimeZone an interval within the timezone Determines if daylight savings time is in effect during a particular @interval of time in the time zone @tz. %TRUE if daylight savings time is in effect a #GTimeZone an interval within the timezone Increases the reference count on @tz. a new reference to @tz. a #GTimeZone Decreases the reference count on @tz. a #GTimeZone `GTimer` records a start time, and counts microseconds elapsed since that time. This is done somewhat differently on different platforms, and can be tricky to get exactly right, so `GTimer` provides a portable/convenient interface. Resumes a timer that has previously been stopped with g_timer_stop(). g_timer_stop() must be called before using this function. a #GTimer. Destroys a timer, freeing associated resources. a #GTimer to destroy. If @timer has been started but not stopped, obtains the time since the timer was started. If @timer has been stopped, obtains the elapsed time between the time it was started and the time it was stopped. The return value is the number of seconds elapsed, including any fractional part. The @microseconds out parameter is essentially useless. seconds elapsed as a floating point value, including any fractional part. a #GTimer. return location for the fractional part of seconds elapsed, in microseconds (that is, the total number of microseconds elapsed, modulo 1000000), or %NULL Exposes whether the timer is currently active. %TRUE if the timer is running, %FALSE otherwise a #GTimer. This function is useless; it's fine to call g_timer_start() on an already-started timer to reset the start time, so g_timer_reset() serves no purpose. a #GTimer. Marks a start time, so that future calls to g_timer_elapsed() will report the time since g_timer_start() was called. g_timer_new() automatically marks the start time, so no need to call g_timer_start() immediately after creating the timer. a #GTimer. Marks an end time, so calls to g_timer_elapsed() will return the difference between this end time and the start time. a #GTimer. Creates a new timer, and starts timing (i.e. g_timer_start() is implicitly called for you). a new #GTimer. The possible types of token returned from each g_scanner_get_next_token() call. the end of the file a '(' character a ')' character a '{' character a '}' character a '[' character a ']' character a '=' character a ',' character not a token an error occurred a character a binary integer an octal integer an integer a hex integer a floating point number a string a symbol an identifier a null identifier one line comment multi line comment A union holding the value of the token. token symbol value token identifier value token binary integer value octal integer value integer value 64-bit integer value floating point value hex integer value string value comment value character value error value The type of functions which are used to translate user-visible strings, for <option>--help</option> output. a translation of the string for the current locale. The returned string is owned by GLib and must not be freed. the untranslated string user data specified when installing the function, e.g. in g_option_group_set_translate_func() A `GTrashStack` is an efficient way to keep a stack of unused allocated memory chunks. Each memory chunk is required to be large enough to hold a `gpointer`. This allows the stack to be maintained without any space overhead, since the stack pointers can be stored inside the memory chunks. There is no function to create a `GTrashStack`. A `NULL` `GTrashStack*` is a perfectly valid empty stack. Each piece of memory that is pushed onto the stack is cast to a `GTrashStack*`. There is no longer any good reason to use `GTrashStack`. If you have extra pieces of memory, `free()` them and allocate them again later. `GTrashStack` is deprecated without replacement pointer to the previous element of the stack, gets stored in the first `sizeof (gpointer)` bytes of the element Returns the height of a #GTrashStack. Note that execution of this function is of O(N) complexity where N denotes the number of items on the stack. #GTrashStack is deprecated without replacement the height of the stack a #GTrashStack Returns the element at the top of a #GTrashStack which may be %NULL. #GTrashStack is deprecated without replacement the element at the top of the stack a #GTrashStack Pops a piece of memory off a #GTrashStack. #GTrashStack is deprecated without replacement the element at the top of the stack a #GTrashStack Pushes a piece of memory onto a #GTrashStack. #GTrashStack is deprecated without replacement a #GTrashStack the piece of memory to push on the stack Specifies which nodes are visited during several of the tree functions, including g_node_traverse() and g_node_find(). only leaf nodes should be visited. This name has been introduced in 2.6, for older version use %G_TRAVERSE_LEAFS. only non-leaf nodes should be visited. This name has been introduced in 2.6, for older version use %G_TRAVERSE_NON_LEAFS. all nodes should be visited. a mask of all traverse flags. identical to %G_TRAVERSE_LEAVES. identical to %G_TRAVERSE_NON_LEAVES. Specifies the type of function passed to g_tree_traverse(). It is passed the key and value of each node, together with the @user_data parameter passed to g_tree_traverse(). If the function returns %TRUE, the traversal is stopped. %TRUE to stop the traversal a key of a #GTree node the value corresponding to the key user data passed to g_tree_traverse() Specifies the type of function passed to g_tree_foreach_node(). It is passed each node, together with the @user_data parameter passed to g_tree_foreach_node(). If the function returns %TRUE, the traversal is stopped. %TRUE to stop the traversal a #GTreeNode user data passed to g_tree_foreach_node() Specifies the type of traversal performed by g_tree_traverse(), g_node_traverse() and g_node_find(). The different orders are illustrated here: - In order: A, B, C, D, E, F, G, H, I <picture> <source srcset="Sorted_binary_tree_inorder-dark.svg" media="(prefers-color-scheme: dark)"> <img src="Sorted_binary_tree_inorder.svg" alt="Sorted binary tree, in-order traversal"> </picture> - Pre order: F, B, A, D, C, E, G, I, H <picture> <source srcset="Sorted_binary_tree_preorder-dark.svg" media="(prefers-color-scheme: dark)"> <img src="Sorted_binary_tree_preorder.svg" alt="Sorted binary tree, pre-order traversal"> </picture> - Post order: A, C, E, D, B, H, I, G, F <picture> <source srcset="Sorted_binary_tree_postorder-dark.svg" media="(prefers-color-scheme: dark)"> <img src="Sorted_binary_tree_postorder.svg" alt="Sorted binary tree, post-order traversal"> </picture> - Level order: F, B, G, A, D, I, C, E, H <picture> <source srcset="Sorted_binary_tree_breadth-first_traversal-dark.svg" media="(prefers-color-scheme: dark)"> <img src="Sorted_binary_tree_breadth-first_traversal.svg" alt="Sorted binary tree, breadth-first level order traversal"> </picture> visits a node's left child first, then the node itself, then its right child. This is the one to use if you want the output sorted according to the compare function. visits a node, then its children. visits the node's children, then the node itself. is not implemented for [balanced binary trees](data-structures.html#binary-trees). For [n-ary trees](data-structures.html#n-ary-trees), it visits the root node first, then its children, then its grandchildren, and so on. Note that this is less efficient than the other orders. The GTree struct is an opaque data structure representing a [balanced binary tree](data-structures.html#binary-trees). It should be accessed only by using the following functions. Creates a new #GTree. a newly allocated #GTree the function used to order the nodes in the #GTree. It should return values similar to the standard strcmp() function - 0 if the two arguments are equal, a negative value if the first argument comes before the second, or a positive value if the first argument comes after the second. Creates a new #GTree like g_tree_new() and allows to specify functions to free the memory allocated for the key and value that get called when removing the entry from the #GTree. a newly allocated #GTree qsort()-style comparison function data to pass to comparison function a function to free the memory allocated for the key used when removing the entry from the #GTree or %NULL if you don't want to supply such a function a function to free the memory allocated for the value used when removing the entry from the #GTree or %NULL if you don't want to supply such a function Creates a new #GTree with a comparison function that accepts user data. See g_tree_new() for more details. a newly allocated #GTree qsort()-style comparison function data to pass to comparison function Removes all keys and values from the #GTree and decreases its reference count by one. If keys and/or values are dynamically allocated, you should either free them first or create the #GTree using g_tree_new_full(). In the latter case the destroy functions you supplied will be called on all keys and values before destroying the #GTree. a #GTree Calls the given function for each of the key/value pairs in the #GTree. The function is passed the key and value of each pair, and the given @data parameter. The tree is traversed in sorted order. The tree may not be modified while iterating over it (you can't add/remove items). To remove all items matching a predicate, you need to add each item to a list in your #GTraverseFunc as you walk over the tree, then walk the list and remove each item. a #GTree the function to call for each node visited. If this function returns %TRUE, the traversal is stopped. user data to pass to the function Calls the given function for each of the nodes in the #GTree. The function is passed the pointer to the particular node, and the given @data parameter. The tree traversal happens in-order. The tree may not be modified while iterating over it (you can't add/remove items). To remove all items matching a predicate, you need to add each item to a list in your #GTraverseFunc as you walk over the tree, then walk the list and remove each item. a #GTree the function to call for each node visited. If this function returns %TRUE, the traversal is stopped. user data to pass to the function Gets the height of a #GTree. If the #GTree contains no nodes, the height is 0. If the #GTree contains only one root node the height is 1. If the root node has children the height is 2, etc. the height of @tree a #GTree Inserts a key/value pair into a #GTree. Inserts a new key and value into a #GTree as g_tree_insert_node() does, only this function does not return the inserted or set node. a #GTree the key to insert the value corresponding to the key Inserts a key/value pair into a #GTree. If the given key already exists in the #GTree its corresponding value is set to the new value. If you supplied a @value_destroy_func when creating the #GTree, the old value is freed using that function. If you supplied a @key_destroy_func when creating the #GTree, the passed key is freed using that function. The tree is automatically 'balanced' as new key/value pairs are added, so that the distance from the root to every leaf is as small as possible. The cost of maintaining a balanced tree while inserting new key/value result in a O(n log(n)) operation where most of the other operations are O(log(n)). the inserted (or set) node or %NULL if insertion would overflow the tree node counter. a #GTree the key to insert the value corresponding to the key Gets the value corresponding to the given key. Since a #GTree is automatically balanced as key/value pairs are added, key lookup is O(log n) (where n is the number of key/value pairs in the tree). the value corresponding to the key, or %NULL if the key was not found a #GTree the key to look up Looks up a key in the #GTree, returning the original key and the associated value. This is useful if you need to free the memory allocated for the original key, for example before calling g_tree_remove(). %TRUE if the key was found in the #GTree a #GTree the key to look up returns the original key returns the value associated with the key Gets the tree node corresponding to the given key. Since a #GTree is automatically balanced as key/value pairs are added, key lookup is O(log n) (where n is the number of key/value pairs in the tree). the tree node corresponding to the key, or %NULL if the key was not found a #GTree the key to look up Gets the lower bound node corresponding to the given key, or %NULL if the tree is empty or all the nodes in the tree have keys that are strictly lower than the searched key. The lower bound is the first node that has its key greater than or equal to the searched key. the tree node corresponding to the lower bound, or %NULL if the tree is empty or has only keys strictly lower than the searched key. a #GTree the key to calculate the lower bound for Gets the number of nodes in a #GTree. the number of nodes in @tree The node counter value type is really a #guint, but it is returned as a #gint due to backward compatibility issues (can be cast back to #guint to support its full range of values). a #GTree Returns the first in-order node of the tree, or %NULL for an empty tree. the first node in the tree a #GTree Returns the last in-order node of the tree, or %NULL for an empty tree. the last node in the tree a #GTree Increments the reference count of @tree by one. It is safe to call this function from any thread. the passed in #GTree a #GTree Removes a key/value pair from a #GTree. If the #GTree was created using g_tree_new_full(), the key and value are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself. If the key does not exist in the #GTree, the function does nothing. The cost of maintaining a balanced tree while removing a key/value result in a O(n log(n)) operation where most of the other operations are O(log(n)). %TRUE if the key was found (prior to 2.8, this function returned nothing) a #GTree the key to remove Removes all nodes from a #GTree and destroys their keys and values, then resets the #GTree’s root to %NULL. a #GTree Inserts a new key and value into a #GTree as g_tree_replace_node() does, only this function does not return the inserted or set node. a #GTree the key to insert the value corresponding to the key Inserts a new key and value into a #GTree similar to g_tree_insert_node(). The difference is that if the key already exists in the #GTree, it gets replaced by the new key. If you supplied a @value_destroy_func when creating the #GTree, the old value is freed using that function. If you supplied a @key_destroy_func when creating the #GTree, the old key is freed using that function. The tree is automatically 'balanced' as new key/value pairs are added, so that the distance from the root to every leaf is as small as possible. the inserted (or set) node or %NULL if insertion would overflow the tree node counter. a #GTree the key to insert the value corresponding to the key Searches a #GTree using @search_func. The @search_func is called with a pointer to the key of a key/value pair in the tree, and the passed in @user_data. If @search_func returns 0 for a key/value pair, then the corresponding value is returned as the result of g_tree_search(). If @search_func returns -1, searching will proceed among the key/value pairs that have a smaller key; if @search_func returns 1, searching will proceed among the key/value pairs that have a larger key. the value corresponding to the found key, or %NULL if the key was not found a #GTree a function used to search the #GTree the data passed as the second argument to @search_func Searches a #GTree using @search_func. The @search_func is called with a pointer to the key of a key/value pair in the tree, and the passed in @user_data. If @search_func returns 0 for a key/value pair, then the corresponding node is returned as the result of g_tree_search(). If @search_func returns -1, searching will proceed among the key/value pairs that have a smaller key; if @search_func returns 1, searching will proceed among the key/value pairs that have a larger key. the node corresponding to the found key, or %NULL if the key was not found a #GTree a function used to search the #GTree the data passed as the second argument to @search_func Removes a key and its associated value from a #GTree without calling the key and value destroy functions. If the key does not exist in the #GTree, the function does nothing. %TRUE if the key was found (prior to 2.8, this function returned nothing) a #GTree the key to remove Calls the given function for each node in the #GTree. The order of a balanced tree is somewhat arbitrary. If you just want to visit all nodes in sorted order, use g_tree_foreach() instead. If you really need to visit nodes in a different order, consider using an [n-ary tree](data-structures.html#n-ary-trees). a #GTree the function to call for each node visited. If this function returns %TRUE, the traversal is stopped. the order in which nodes are visited, one of %G_IN_ORDER, %G_PRE_ORDER and %G_POST_ORDER user data to pass to the function Decrements the reference count of @tree by one. If the reference count drops to 0, all keys and values will be destroyed (if destroy functions were specified) and all memory allocated by @tree will be released. It is safe to call this function from any thread. a #GTree Gets the upper bound node corresponding to the given key, or %NULL if the tree is empty or all the nodes in the tree have keys that are lower than or equal to the searched key. The upper bound is the first node that has its key strictly greater than the searched key. the tree node corresponding to the upper bound, or %NULL if the tree is empty or has only keys lower than or equal to the searched key. a #GTree the key to calculate the upper bound for An opaque type which identifies a specific node in a #GTree. Gets the key stored at a particular tree node. the key at the node. a #GTree node Returns the next in-order node of the tree, or %NULL if the passed node was already the last one. the next node in the tree a #GTree node Returns the previous in-order node of the tree, or %NULL if the passed node was already the first one. the previous node in the tree a #GTree node Gets the value stored at a particular tree node. the value at the node. a #GTree node The #GTuples struct is used to return records (or tuples) from the #GRelation by g_relation_select(). It only contains one public member - the number of records that matched. To access the matched records, you must use g_tuples_index(). Rarely used API the number of records that matched. Frees the records which were returned by g_relation_select(). This should always be called after g_relation_select() when you are finished with the records. The records are not removed from the #GRelation. Rarely used API the tuple data to free. Gets a field from the records returned by g_relation_select(). It returns the given field of the record at the given index. The returned value should not be changed. Rarely used API the field of the record. the tuple data, returned by g_relation_select(). the index of the record. the field to return. The maximum length (in codepoints) of a compatibility or canonical decomposition of a single Unicode character. This is as defined by Unicode 6.1. Hints the compiler that the expression is unlikely to evaluate to a true value. The compiler may use this information for optimizations. |[<!-- language="C" --> if (G_UNLIKELY (random () == 1)) g_print ("a random one"); ]| the expression Works like g_mutex_unlock(), but for a lock defined with %G_LOCK_DEFINE. the name of the lock Generic delimiters characters as defined in [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `:/?#[]@`. Subcomponent delimiter characters as defined in [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=`. Number of microseconds in one second (1 million). This macro is provided for code readability. These are the possible line break classifications. Since new Unicode versions may add new types here, applications should be ready to handle unknown values. They may be regarded as %G_UNICODE_BREAK_UNKNOWN. See [Unicode Line Breaking Algorithm](https://www.unicode.org/reports/tr14/). Mandatory Break (BK) Carriage Return (CR) Line Feed (LF) Attached Characters and Combining Marks (CM) Surrogates (SG) Zero Width Space (ZW) Inseparable (IN) Non-breaking ("Glue") (GL) Contingent Break Opportunity (CB) Space (SP) Break Opportunity After (BA) Break Opportunity Before (BB) Break Opportunity Before and After (B2) Hyphen (HY) Nonstarter (NS) Opening Punctuation (OP) Closing Punctuation (CL) Ambiguous Quotation (QU) Exclamation/Interrogation (EX) Ideographic (ID) Numeric (NU) Infix Separator (Numeric) (IS) Symbols Allowing Break After (SY) Ordinary Alphabetic and Symbol Characters (AL) Prefix (Numeric) (PR) Postfix (Numeric) (PO) Complex Content Dependent (South East Asian) (SA) Ambiguous (Alphabetic or Ideographic) (AI) Unknown (XX) Next Line (NL) Word Joiner (WJ) Hangul L Jamo (JL) Hangul V Jamo (JV) Hangul T Jamo (JT) Hangul LV Syllable (H2) Hangul LVT Syllable (H3) Closing Parenthesis (CP). Since 2.28. Deprecated: 2.70: Use %G_UNICODE_BREAK_CLOSE_PARENTHESIS instead. Closing Parenthesis (CP). Since 2.70 Conditional Japanese Starter (CJ). Since: 2.32 Hebrew Letter (HL). Since: 2.32 Regional Indicator (RI). Since: 2.36 Emoji Base (EB). Since: 2.50 Emoji Modifier (EM). Since: 2.50 Zero Width Joiner (ZWJ). Since: 2.50 Aksara (AK). Since: 2.80 Aksara Pre-Base (AP). Since: 2.80 Aksara Start (AS). Since: 2.80 Virama Final (VF). Since: 2.80 Virama (VI). Since: 2.80 Unambiguous Hyphen (HH). Since: 2.88 The #GUnicodeScript enumeration identifies different writing systems. The values correspond to the names as defined in the Unicode standard. The enumeration has been added in GLib 2.14, and is interchangeable with #PangoScript. Note that new types may be added in the future. Applications should be ready to handle unknown values. See [Unicode Standard Annex #24: Script names](http://www.unicode.org/reports/tr24/). a value never returned from g_unichar_get_script() a character used by multiple different scripts a mark glyph that takes its script from the base glyph to which it is attached Arabic Armenian Bengali Bopomofo Cherokee Coptic Cyrillic Deseret Devanagari Ethiopic Georgian Gothic Greek Gujarati Gurmukhi Han Hangul Hebrew Hiragana Kannada Katakana Khmer Lao Latin Malayalam Mongolian Myanmar Ogham Old Italic Oriya Runic Sinhala Syriac Tamil Telugu Thaana Thai Tibetan Canadian Aboriginal Yi Tagalog Hanunoo Buhid Tagbanwa Braille Cypriot Limbu Osmanya Shavian Linear B Tai Le Ugaritic New Tai Lue Buginese Glagolitic Tifinagh Syloti Nagri Old Persian Kharoshthi an unassigned code point Balinese Cuneiform Phoenician Phags-pa N'Ko Kayah Li. Since 2.16.3 Lepcha. Since 2.16.3 Rejang. Since 2.16.3 Sundanese. Since 2.16.3 Saurashtra. Since 2.16.3 Cham. Since 2.16.3 Ol Chiki. Since 2.16.3 Vai. Since 2.16.3 Carian. Since 2.16.3 Lycian. Since 2.16.3 Lydian. Since 2.16.3 Avestan. Since 2.26 Bamum. Since 2.26 Egyptian Hieroglpyhs. Since 2.26 Imperial Aramaic. Since 2.26 Inscriptional Pahlavi. Since 2.26 Inscriptional Parthian. Since 2.26 Javanese. Since 2.26 Kaithi. Since 2.26 Lisu. Since 2.26 Meetei Mayek. Since 2.26 Old South Arabian. Since 2.26 Old Turkic. Since 2.28 Samaritan. Since 2.26 Tai Tham. Since 2.26 Tai Viet. Since 2.26 Batak. Since 2.28 Brahmi. Since 2.28 Mandaic. Since 2.28 Chakma. Since: 2.32 Meroitic Cursive. Since: 2.32 Meroitic Hieroglyphs. Since: 2.32 Miao. Since: 2.32 Sharada. Since: 2.32 Sora Sompeng. Since: 2.32 Takri. Since: 2.32 Bassa. Since: 2.42 Caucasian Albanian. Since: 2.42 Duployan. Since: 2.42 Elbasan. Since: 2.42 Grantha. Since: 2.42 Kjohki. Since: 2.42 Khudawadi, Sindhi. Since: 2.42 Linear A. Since: 2.42 Mahajani. Since: 2.42 Manichaean. Since: 2.42 Mende Kikakui. Since: 2.42 Modi. Since: 2.42 Mro. Since: 2.42 Nabataean. Since: 2.42 Old North Arabian. Since: 2.42 Old Permic. Since: 2.42 Pahawh Hmong. Since: 2.42 Palmyrene. Since: 2.42 Pau Cin Hau. Since: 2.42 Psalter Pahlavi. Since: 2.42 Siddham. Since: 2.42 Tirhuta. Since: 2.42 Warang Citi. Since: 2.42 Ahom. Since: 2.48 Anatolian Hieroglyphs. Since: 2.48 Hatran. Since: 2.48 Multani. Since: 2.48 Old Hungarian. Since: 2.48 Signwriting. Since: 2.48 Adlam. Since: 2.50 Bhaiksuki. Since: 2.50 Marchen. Since: 2.50 Newa. Since: 2.50 Osage. Since: 2.50 Tangut. Since: 2.50 Masaram Gondi. Since: 2.54 Nushu. Since: 2.54 Soyombo. Since: 2.54 Zanabazar Square. Since: 2.54 Dogra. Since: 2.58 Gunjala Gondi. Since: 2.58 Hanifi Rohingya. Since: 2.58 Makasar. Since: 2.58 Medefaidrin. Since: 2.58 Old Sogdian. Since: 2.58 Sogdian. Since: 2.58 Elym. Since: 2.62 Nand. Since: 2.62 Rohg. Since: 2.62 Wcho. Since: 2.62 Chorasmian. Since: 2.66 Dives Akuru. Since: 2.66 Khitan small script. Since: 2.66 Yezidi. Since: 2.66 Cypro-Minoan. Since: 2.72 Old Uyghur. Since: 2.72 Tangsa. Since: 2.72 Toto. Since: 2.72 Vithkuqi. Since: 2.72 Mathematical notation. Since: 2.72 Kawi. Since 2.74 Nag Mundari. Since 2.74 Todhri. Since: 2.84 Garay. Since: 2.84 Tulu-Tigalari. Since: 2.84 Sunuwar. Since: 2.84 Gurung Khema. Since: 2.84 Kirat Rai. Since: 2.84 Ol Onal. Since: 2.84 Sidetic. Since: 2.88 Tolong Siki. Since: 2.88 Tai Yo. Since: 2.88 Beria Erfe. Since: 2.88 Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter codes to scripts. For example, the code for Arabic is 'Arab'. This function accepts four letter codes encoded as a @guint32 in a big-endian fashion. That is, the code expected for Arabic is 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). See [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) for details. the Unicode script for @iso15924, or of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown. a Unicode script Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter codes to scripts. For example, the code for Arabic is 'Arab'. The four letter codes are encoded as a @guint32 by this function in a big-endian fashion. That is, the code returned for Arabic is 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). See [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) for details. the ISO 15924 code for @script, encoded as an integer, of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood. a Unicode script These are the possible character classifications from the Unicode specification. See [Unicode Character Database](http://www.unicode.org/reports/tr44/#General_Category_Values). General category "Other, Control" (Cc) General category "Other, Format" (Cf) General category "Other, Not Assigned" (Cn) General category "Other, Private Use" (Co) General category "Other, Surrogate" (Cs) General category "Letter, Lowercase" (Ll) General category "Letter, Modifier" (Lm) General category "Letter, Other" (Lo) General category "Letter, Titlecase" (Lt) General category "Letter, Uppercase" (Lu) General category "Mark, Spacing" (Mc) General category "Mark, Enclosing" (Me) General category "Mark, Nonspacing" (Mn) General category "Number, Decimal Digit" (Nd) General category "Number, Letter" (Nl) General category "Number, Other" (No) General category "Punctuation, Connector" (Pc) General category "Punctuation, Dash" (Pd) General category "Punctuation, Close" (Pe) General category "Punctuation, Final quote" (Pf) General category "Punctuation, Initial quote" (Pi) General category "Punctuation, Other" (Po) General category "Punctuation, Open" (Ps) General category "Symbol, Currency" (Sc) General category "Symbol, Modifier" (Sk) General category "Symbol, Math" (Sm) General category "Symbol, Other" (So) General category "Separator, Line" (Zl) General category "Separator, Paragraph" (Zp) General category "Separator, Space" (Zs) The `GUri` type and related functions can be used to parse URIs into their components, and build valid URIs from individual components. Since `GUri` only represents absolute URIs, all `GUri`s will have a URI scheme, so [method@GLib.Uri.get_scheme] will always return a non-`NULL` answer. Likewise, by definition, all URIs have a path component, so [method@GLib.Uri.get_path] will always return a non-`NULL` string (which may be empty). If the URI string has an [‘authority’ component](https://tools.ietf.org/html/rfc3986#section-3) (that is, if the scheme is followed by `://` rather than just `:`), then the `GUri` will contain a hostname, and possibly a port and ‘userinfo’. Additionally, depending on how the `GUri` was constructed/parsed (for example, using the `G_URI_FLAGS_HAS_PASSWORD` and `G_URI_FLAGS_HAS_AUTH_PARAMS` flags), the userinfo may be split out into a username, password, and additional authorization-related parameters. Normally, the components of a `GUri` will have all `%`-encoded characters decoded. However, if you construct/parse a `GUri` with `G_URI_FLAGS_ENCODED`, then the `%`-encoding will be preserved instead in the userinfo, path, and query fields (and in the host field if also created with `G_URI_FLAGS_NON_DNS`). In particular, this is necessary if the URI may contain binary data or non-UTF-8 text, or if decoding the components might change the interpretation of the URI. For example, with the encoded flag: ```c g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_ENCODED, &err); g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue"); ``` While the default `%`-decoding behaviour would give: ```c g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_NONE, &err); g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http://host/path?param=value"); ``` During decoding, if an invalid UTF-8 string is encountered, parsing will fail with an error indicating the bad string location: ```c g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fbad%3D%00alue", G_URI_FLAGS_NONE, &err); g_assert_error (err, G_URI_ERROR, G_URI_ERROR_BAD_QUERY); ``` You should pass `G_URI_FLAGS_ENCODED` or `G_URI_FLAGS_ENCODED_QUERY` if you need to handle that case manually. In particular, if the query string contains `=` characters that are `%`-encoded, you should let [func@GLib.Uri.parse_params] do the decoding once of the query. `GUri` is immutable once constructed, and can safely be accessed from multiple threads. Its reference counting is atomic. Note that the scope of `GUri` is to help manipulate URIs in various applications, following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular, it doesn't intend to cover web browser needs, and doesn’t implement the [WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to help prevent [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so `GUri` is not suitable for formatting URIs for display to the user for making security-sensitive decisions. ## Relative and absolute URIs As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the hierarchical nature of URIs means that they can either be ‘relative references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for clarity, ‘URIs’ are referred to in this documentation as ‘absolute URIs’ — although [in contrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3), fragment identifiers are always allowed). Relative references have one or more components of the URI missing. In particular, they have no scheme. Any other component, such as hostname, query, etc. may be missing, apart from a path, which has to be specified (but may be empty). The path may be relative, starting with `./` rather than `/`. For example, a valid relative reference is `./path?query`, `/?query#fragment` or `//example.com`. Absolute URIs have a scheme specified. Any other components of the URI which are missing are specified as explicitly unset in the URI, rather than being resolved relative to a base URI using [method@GLib.Uri.parse_relative]. For example, a valid absolute URI is `file:///home/bob` or `https://search.com?query=string`. A `GUri` instance is always an absolute URI. A string may be an absolute URI or a relative reference; see the documentation for individual functions as to what forms they accept. ## Parsing URIs The most minimalist APIs for parsing URIs are [func@GLib.Uri.split] and [func@GLib.Uri.split_with_user]. These split a URI into its component parts, and return the parts; the difference between the two is that [func@GLib.Uri.split] treats the ‘userinfo’ component of the URI as a single element, while [func@GLib.Uri.split_with_user] can (depending on the [flags@GLib.UriFlags] you pass) treat it as containing a username, password, and authentication parameters. Alternatively, [func@GLib.Uri.split_network] can be used when you are only interested in the components that are needed to initiate a network connection to the service (scheme, host, and port). [func@GLib.Uri.parse] is similar to [func@GLib.Uri.split], but instead of returning individual strings, it returns a `GUri` structure (and it requires that the URI be an absolute URI). [func@GLib.Uri.resolve_relative] and [method@GLib.Uri.parse_relative] allow you to resolve a relative URI relative to a base URI. [func@GLib.Uri.resolve_relative] takes two strings and returns a string, and [method@GLib.Uri.parse_relative] takes a `GUri` and a string and returns a `GUri`. All of the parsing functions take a [flags@GLib.UriFlags] argument describing exactly how to parse the URI; see the documentation for that type for more details on the specific flags that you can pass. If you need to choose different flags based on the type of URI, you can use [func@GLib.Uri.peek_scheme] on the URI string to check the scheme first, and use that to decide what flags to parse it with. For example, you might want to use `G_URI_PARAMS_WWW_FORM` when parsing the params for a web URI, so compare the result of [func@GLib.Uri.peek_scheme] against `http` and `https`. ## Building URIs [func@GLib.Uri.join] and [func@GLib.Uri.join_with_user] can be used to construct valid URI strings from a set of component strings. They are the inverse of [func@GLib.Uri.split] and [func@GLib.Uri.split_with_user]. Similarly, [func@GLib.Uri.build] and [func@GLib.Uri.build_with_user] can be used to construct a `GUri` from a set of component strings. As with the parsing functions, the building functions take a [flags@GLib.UriFlags] argument. In particular, it is important to keep in mind whether the URI components you are using are already `%`-encoded. If so, you must pass the `G_URI_FLAGS_ENCODED` flag. ## `file://` URIs Note that Windows and Unix both define special rules for parsing `file://` URIs (involving non-UTF-8 character sets on Unix, and the interpretation of path separators on Windows). `GUri` does not implement these rules. Use [func@GLib.filename_from_uri] and [func@GLib.filename_to_uri] if you want to properly convert between `file://` URIs and local filenames. ## URI Equality Note that there is no `g_uri_equal ()` function, because comparing URIs usefully requires scheme-specific knowledge that `GUri` does not have. `GUri` can help with normalization if you use the various encoded [flags@GLib.UriFlags] as well as `G_URI_FLAGS_SCHEME_NORMALIZE` however it is not comprehensive. For example, `data:,foo` and `data:;base64,Zm9v` resolve to the same thing according to the `data:` URI specification which GLib does not handle. Gets @uri's authentication parameters, which may contain `%`-encoding, depending on the flags with which @uri was created. (If @uri was not created with %G_URI_FLAGS_HAS_AUTH_PARAMS then this will be %NULL.) Depending on the URI scheme, g_uri_parse_params() may be useful for further parsing this information. @uri's authentication parameters. a #GUri Gets @uri's flags set upon construction. @uri's flags. a #GUri Gets @uri's fragment, which may contain `%`-encoding, depending on the flags with which @uri was created. @uri's fragment. a #GUri Gets @uri's host. This will never have `%`-encoded characters, unless it is non-UTF-8 (which can only be the case if @uri was created with %G_URI_FLAGS_NON_DNS). If @uri contained an IPv6 address literal, this value will be just that address, without the brackets around it that are necessary in the string form of the URI. Note that in this case there may also be a scope ID attached to the address. Eg, `fe80::1234%``em1` (or `fe80::1234%``25em1` if the string is still encoded). @uri's host. a #GUri Gets @uri's password, which may contain `%`-encoding, depending on the flags with which @uri was created. (If @uri was not created with %G_URI_FLAGS_HAS_PASSWORD then this will be %NULL.) @uri's password. a #GUri Gets @uri's path, which may contain `%`-encoding, depending on the flags with which @uri was created. @uri's path. a #GUri Gets @uri's port. @uri's port, or `-1` if no port was specified. a #GUri Gets @uri's query, which may contain `%`-encoding, depending on the flags with which @uri was created. For queries consisting of a series of `name=value` parameters, #GUriParamsIter or g_uri_parse_params() may be useful. @uri's query. a #GUri Gets @uri's scheme. Note that this will always be all-lowercase, regardless of the string or strings that @uri was created from. @uri's scheme. a #GUri Gets the ‘username’ component of @uri's userinfo, which may contain `%`-encoding, depending on the flags with which @uri was created. If @uri was not created with %G_URI_FLAGS_HAS_PASSWORD or %G_URI_FLAGS_HAS_AUTH_PARAMS, this is the same as g_uri_get_userinfo(). @uri's user. a #GUri Gets @uri's userinfo, which may contain `%`-encoding, depending on the flags with which @uri was created. @uri's userinfo. a #GUri Parses @uri_ref according to @flags and, if it is a [relative URI](#relative-and-absolute-uris), resolves it relative to @base_uri. If the result is not a valid absolute URI, it will be discarded, and an error returned. a new #GUri, or NULL on error. a base absolute URI a string representing a relative or absolute URI flags describing how to parse @uri_ref Increments the reference count of @uri by one. @uri a #GUri Returns a string representing @uri. This is not guaranteed to return a string which is identical to the string that @uri was parsed from. However, if the source URI was syntactically correct (according to RFC 3986), and it was parsed with %G_URI_FLAGS_ENCODED, then g_uri_to_string() is guaranteed to return a string which is at least semantically equivalent to the source URI (according to RFC 3986). If @uri might contain sensitive details, such as authentication parameters, or private data in its query string, and the returned string is going to be logged, then consider using g_uri_to_string_partial() to redact parts. a string representing @uri, which the caller must free. a #GUri Returns a string representing @uri, subject to the options in @flags. See g_uri_to_string() and #GUriHideFlags for more details. a string representing @uri, which the caller must free. a #GUri flags describing what parts of @uri to hide Atomically decrements the reference count of @uri by one. When the reference count reaches zero, the resources allocated by @uri are freed a #GUri Creates a new #GUri from the given components according to @flags. See also g_uri_build_with_user(), which allows specifying the components of the "userinfo" separately. a new #GUri flags describing how to build the #GUri the URI scheme the userinfo component, or %NULL the host component, or %NULL the port, or `-1` the path component the query component, or %NULL the fragment, or %NULL Creates a new #GUri from the given components according to @flags (%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be coherent with the passed values, in particular use `%`-encoded values with %G_URI_FLAGS_ENCODED. In contrast to g_uri_build(), this allows specifying the components of the ‘userinfo’ field separately. Note that @user must be non-%NULL if either @password or @auth_params is non-%NULL. a new #GUri flags describing how to build the #GUri the URI scheme the user component of the userinfo, or %NULL the password component of the userinfo, or %NULL the auth params of the userinfo, or %NULL the host component, or %NULL the port, or `-1` the path component the query component, or %NULL the fragment, or %NULL Escapes arbitrary data for use in a URI. Normally all characters that are not ‘unreserved’ (i.e. ASCII alphanumerical characters plus dash, dot, underscore and tilde) are escaped. But if you specify characters in @reserved_chars_allowed they are not escaped. This is useful for the ‘reserved’ characters in the URI specification, since those are allowed unescaped in some portions of a URI. Though technically incorrect, this will also allow escaping nul bytes as `%``00`. an escaped version of @unescaped. The returned string should be freed when no longer needed. the unescaped input data. the length of @unescaped a string of reserved characters that are allowed to be used, or %NULL. Escapes a string for use in a URI. Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical characters plus dash, dot, underscore and tilde) are escaped. But if you specify characters in @reserved_chars_allowed they are not escaped. This is useful for the "reserved" characters in the URI specification, since those are allowed unescaped in some portions of a URI. an escaped version of @unescaped. The returned string should be freed when no longer needed. the unescaped input string. a string of reserved characters that are allowed to be used, or %NULL. %TRUE if the result can include UTF-8 characters. Parses @uri_string according to @flags, to determine whether it is a valid [absolute URI](#relative-and-absolute-uris), i.e. it does not need to be resolved relative to another URI using g_uri_parse_relative(). If it’s not a valid URI, an error is returned explaining how it’s invalid. See g_uri_split(), and the definition of #GUriFlags, for more information on the effect of @flags. %TRUE if @uri_string is a valid absolute URI, %FALSE on error. a string containing an absolute URI flags for parsing @uri_string Joins the given components together according to @flags to create an absolute URI string. @path may not be %NULL (though it may be the empty string). When @host is present, @path must either be empty or begin with a slash (`/`) character. When @host is not present, @path cannot begin with two slash characters (`//`). See [RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3). See also g_uri_join_with_user(), which allows specifying the components of the ‘userinfo’ separately. %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set in @flags. an absolute URI string flags describing how to build the URI string the URI scheme, or %NULL the userinfo component, or %NULL the host component, or %NULL the port, or `-1` the path component the query component, or %NULL the fragment, or %NULL Joins the given components together according to @flags to create an absolute URI string. @path may not be %NULL (though it may be the empty string). In contrast to g_uri_join(), this allows specifying the components of the ‘userinfo’ separately. It otherwise behaves the same. %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set in @flags. an absolute URI string flags describing how to build the URI string the URI scheme, or %NULL the user component of the userinfo, or %NULL the password component of the userinfo, or %NULL the auth params of the userinfo, or %NULL the host component, or %NULL the port, or `-1` the path component the query component, or %NULL the fragment, or %NULL Splits an URI list conforming to the text/uri-list mime type defined in RFC 2483 into individual URIs, discarding any comments. The URIs are not validated. a newly allocated %NULL-terminated list of strings holding the individual URIs. The array should be freed with g_strfreev(). an URI list Parses @uri_string according to @flags. If the result is not a valid [absolute URI](#relative-and-absolute-uris), it will be discarded, and an error returned. a new #GUri, or NULL on error. a string representing an absolute URI flags describing how to parse @uri_string Many URI schemes include one or more attribute/value pairs as part of the URI value. This method can be used to parse them into a hash table. When an attribute has multiple occurrences, the last value is the final returned value. If you need to handle repeated attributes differently, use #GUriParamsIter. The @params string is assumed to still be `%`-encoded, but the returned values will be fully decoded. (Thus it is possible that the returned values may contain `=` or @separators, if the value was encoded in the input.) Invalid `%`-encoding is treated as with the %G_URI_FLAGS_PARSE_RELAXED rules for g_uri_parse(). (However, if @params is the path or query string from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED and %G_URI_FLAGS_ENCODED, then you already know that it does not contain any invalid encoding.) %G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init(). If %G_URI_PARAMS_CASE_INSENSITIVE is passed to @flags, attributes will be compared case-insensitively, so a params string `attr=123&Attr=456` will only return a single attribute–value pair, `Attr=456`. Case will be preserved in the returned attributes. If @params cannot be parsed (for example, it contains two @separators characters in a row), then @error is set and %NULL is returned. A hash table of attribute/value pairs, with both names and values fully-decoded; or %NULL on error. a `%`-encoded string containing `attribute=value` parameters the length of @params, or `-1` if it is nul-terminated the separator byte character set between parameters. (usually `&`, but sometimes `;` or both `&;`). Note that this function works on bytes not characters, so it can't be used to delimit UTF-8 strings for anything but ASCII characters. You may pass an empty set, in which case no splitting will occur. flags to modify the way the parameters are handled. Gets the scheme portion of a URI string. [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme as: |[ URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] ]| Common schemes include `file`, `https`, `svn+ssh`, etc. The ‘scheme’ component of the URI, or %NULL on error. The returned string should be freed when no longer needed. a valid URI. Gets the scheme portion of a URI string. [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme as: |[ URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] ]| Common schemes include `file`, `https`, `svn+ssh`, etc. Unlike g_uri_parse_scheme(), the returned scheme is normalized to all-lowercase and does not need to be freed. The ‘scheme’ component of the URI, or %NULL on error. The returned string is normalized to all-lowercase, and interned via g_intern_string(), so it does not need to be freed. a valid URI. Parses @uri_ref according to @flags and, if it is a [relative URI](#relative-and-absolute-uris), resolves it relative to @base_uri_string. If the result is not a valid absolute URI, it will be discarded, and an error returned. (If @base_uri_string is %NULL, this just returns @uri_ref, or %NULL if @uri_ref is invalid or not absolute.) the resolved URI string, or NULL on error. a string representing a base URI a string representing a relative or absolute URI flags describing how to parse @uri_ref Parses @uri_ref (which can be an [absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces. Any component that doesn't appear in @uri_ref will be returned as %NULL (but note that all URIs always have a path component, though it may be the empty string). If @flags contains %G_URI_FLAGS_ENCODED, then `%`-encoded characters in @uri_ref will remain encoded in the output strings. (If not, then all such characters will be decoded.) Note that decoding will only work if the URI components are ASCII or UTF-8, so you will need to use %G_URI_FLAGS_ENCODED if they are not. Note that the %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(), since it always returns only the full userinfo; use g_uri_split_with_user() if you want it split up. %TRUE if @uri_ref parsed successfully, %FALSE on error. a string containing a relative or absolute URI flags for parsing @uri_ref on return, contains the scheme (converted to lowercase), or %NULL on return, contains the userinfo, or %NULL on return, contains the host, or %NULL on return, contains the port, or `-1` on return, contains the path on return, contains the query, or %NULL on return, contains the fragment, or %NULL Parses @uri_string (which must be an [absolute URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces relevant to connecting to a host. See the documentation for g_uri_split() for more details; this is mostly a wrapper around that function with simpler arguments. However, it will return an error if @uri_string is a relative URI, or does not contain a hostname component. %TRUE if @uri_string parsed successfully, %FALSE on error. a string containing an absolute URI flags for parsing @uri_string on return, contains the scheme (converted to lowercase), or %NULL on return, contains the host, or %NULL on return, contains the port, or `-1` Parses @uri_ref (which can be an [absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces. Any component that doesn't appear in @uri_ref will be returned as %NULL (but note that all URIs always have a path component, though it may be the empty string). See g_uri_split(), and the definition of #GUriFlags, for more information on the effect of @flags. Note that @password will only be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and @auth_params will only be parsed out if @flags contains %G_URI_FLAGS_HAS_AUTH_PARAMS. %TRUE if @uri_ref parsed successfully, %FALSE on error. a string containing a relative or absolute URI flags for parsing @uri_ref on return, contains the scheme (converted to lowercase), or %NULL on return, contains the user, or %NULL on return, contains the password, or %NULL on return, contains the auth_params, or %NULL on return, contains the host, or %NULL on return, contains the port, or `-1` on return, contains the path on return, contains the query, or %NULL on return, contains the fragment, or %NULL Unescapes a segment of an escaped string as binary data. Note that in contrast to g_uri_unescape_string(), this does allow nul bytes to appear in the output. If any of the characters in @illegal_characters appears as an escaped character in @escaped_string, then that is an error and %NULL will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. an unescaped version of @escaped_string or %NULL on error (if decoding failed, using %G_URI_ERROR_FAILED error code). The returned #GBytes should be unreffed when no longer needed. A URI-escaped string the length (in bytes) of @escaped_string to escape, or `-1` if it is nul-terminated. a string of illegal characters not to be allowed, or %NULL. Unescapes a segment of an escaped string. If any of the characters in @illegal_characters or the NUL character appears as an escaped character in @escaped_string, then that is an error and %NULL will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. Note: `NUL` byte is not accepted in the output, in contrast to g_uri_unescape_bytes(). an unescaped version of @escaped_string, or %NULL on error. The returned string should be freed when no longer needed. As a special case if %NULL is given for @escaped_string, this function will return %NULL. A string, may be %NULL Pointer to end of @escaped_string, may be %NULL An optional string of illegal characters not to be allowed, may be %NULL Unescapes a whole escaped string. If any of the characters in @illegal_characters or the NUL character appears as an escaped character in @escaped_string, then that is an error and %NULL will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. an unescaped version of @escaped_string. The returned string should be freed when no longer needed. an escaped string to be unescaped. a string of illegal characters not to be allowed, or %NULL. Error codes returned by #GUri methods. Generic error if no more specific error is available. See the error message for details. The scheme of a URI could not be parsed. The user/userinfo of a URI could not be parsed. The password of a URI could not be parsed. The authentication parameters of a URI could not be parsed. The host of a URI could not be parsed. The port of a URI could not be parsed. The path of a URI could not be parsed. The query of a URI could not be parsed. The fragment of a URI could not be parsed. Flags that describe a URI. When parsing a URI, if you need to choose different flags based on the type of URI, you can use g_uri_peek_scheme() on the URI string to check the scheme first, and use that to decide what flags to parse it with. No flags set. Parse the URI more relaxedly than the [RFC 3986](https://tools.ietf.org/html/rfc3986) grammar specifies, fixing up or ignoring common mistakes in URIs coming from external sources. This is also needed for some obscure URI schemes where `;` separates the host from the path. Don’t use this flag unless you need to. The userinfo field may contain a password, which will be separated from the username by `:`. The userinfo may contain additional authentication-related parameters, which will be separated from the username and/or password by `;`. When parsing a URI, this indicates that `%`-encoded characters in the userinfo, path, query, and fragment fields should not be decoded. (And likewise the host field if %G_URI_FLAGS_NON_DNS is also set.) When building a URI, it indicates that you have already `%`-encoded the components, and so #GUri should not do any encoding itself. The host component should not be assumed to be a DNS hostname or IP address (for example, for `smb` URIs with NetBIOS hostnames). Same as %G_URI_FLAGS_ENCODED, for the query field only. Same as %G_URI_FLAGS_ENCODED, for the path only. Same as %G_URI_FLAGS_ENCODED, for the fragment only. A scheme-based normalization will be applied. For example, when parsing an HTTP URI changing omitted path to `/` and omitted port to `80`; and when building a URI, changing empty path to `/` and default port `80`). This only supports a subset of known schemes. (Since: 2.68) Flags describing what parts of the URI to hide in g_uri_to_string_partial(). Note that %G_URI_HIDE_PASSWORD and %G_URI_HIDE_AUTH_PARAMS will only work if the #GUri was parsed with the corresponding flags. No flags set. Hide the userinfo. Hide the password. Hide the auth_params. Hide the query. Hide the fragment. Flags modifying the way parameters are handled by g_uri_parse_params() and #GUriParamsIter. No flags set. Parameter names are case insensitive. Replace `+` with space character. Only useful for URLs on the web, using the `https` or `http` schemas. See %G_URI_FLAGS_PARSE_RELAXED. Many URI schemes include one or more attribute/value pairs as part of the URI value. For example `scheme://server/path?query=string&is=there` has two attributes – `query=string` and `is=there` – in its query part. A #GUriParamsIter structure represents an iterator that can be used to iterate over the attribute/value pairs of a URI query string. #GUriParamsIter structures are typically allocated on the stack and then initialized with g_uri_params_iter_init(). See the documentation for g_uri_params_iter_init() for a usage example. Initializes an attribute/value pair iterator. The iterator keeps pointers to the @params and @separators arguments, those variables must thus outlive the iterator and not be modified during the iteration. If %G_URI_PARAMS_WWW_FORM is passed in @flags, `+` characters in the param string will be replaced with spaces in the output. For example, `foo=bar+baz` will give attribute `foo` with value `bar baz`. This is commonly used on the web (the `https` and `http` schemes only), but is deprecated in favour of the equivalent of encoding spaces as `%20`. Unlike with g_uri_parse_params(), %G_URI_PARAMS_CASE_INSENSITIVE has no effect if passed to @flags for g_uri_params_iter_init(). The caller is responsible for doing their own case-insensitive comparisons. |[<!-- language="C" --> GUriParamsIter iter; GError *error = NULL; gchar *unowned_attr, *unowned_value; g_uri_params_iter_init (&iter, "foo=bar&baz=bar&Foo=frob&baz=bar2", -1, "&", G_URI_PARAMS_NONE); while (g_uri_params_iter_next (&iter, &unowned_attr, &unowned_value, &error)) { g_autofree gchar *attr = g_steal_pointer (&unowned_attr); g_autofree gchar *value = g_steal_pointer (&unowned_value); // do something with attr and value; this code will be called 4 times // for the params string in this example: once with attr=foo and value=bar, // then with baz/bar, then Foo/frob, then baz/bar2. } if (error) // handle parsing error ]| an uninitialized #GUriParamsIter a `%`-encoded string containing `attribute=value` parameters the length of @params, or `-1` if it is nul-terminated the separator byte character set between parameters. (usually `&`, but sometimes `;` or both `&;`). Note that this function works on bytes not characters, so it can't be used to delimit UTF-8 strings for anything but ASCII characters. You may pass an empty set, in which case no splitting will occur. flags to modify the way the parameters are handled. Advances @iter and retrieves the next attribute/value. %FALSE is returned if an error has occurred (in which case @error is set), or if the end of the iteration is reached (in which case @attribute and @value are set to %NULL and the iterator becomes invalid). If %TRUE is returned, g_uri_params_iter_next() may be called again to receive another attribute/value pair. Note that the same @attribute may be returned multiple times, since URIs allow repeated attributes. %FALSE if the end of the parameters has been reached or an error was encountered. %TRUE otherwise. an initialized #GUriParamsIter on return, contains the attribute, or %NULL. on return, contains the value, or %NULL. These are logical ids for special directories which are defined depending on the platform used. You should use g_get_user_special_dir() to retrieve the full path associated to the logical id. The #GUserDirectory enumeration can be extended at later date. Not every platform has a directory for every logical id in this enumeration. the user's Desktop directory the user's Documents directory the user's Downloads directory the user's Music directory the user's Pictures directory the user's shared directory the user's Templates directory the user's Movies directory the number of enum values A stack-allocated [struct@GLib.VariantBuilder] must be initialized if it is used together with [`g_auto()`](auto-cleanup.html#variable-declaration). This macro can be used as initializer when declaring the builder, but it cannot be assigned to a variable. The effects of initializing the builder with `G_VARIANT_BUILDER_INIT` is the same as initializing it with [func@GLib.VARIANT_BUILDER_INIT_UNSET], followed by a call to [method@GLib.VariantBuilder.init]. The passed @variant_type should be a static [type@GLib.VariantType] to avoid lifetime issues, as copying the @variant_type does not happen in the `G_VARIANT_BUILDER_INIT` call, but rather in functions that make sure that [struct@GLib.VariantBuilder] is valid. ```c g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT (G_VARIANT_TYPE_BYTESTRING); ``` a const GVariantType* A stack-allocated [struct@GLib.VariantBuilder] must be initialized if it is used together with [`g_auto()`](auto-cleanup.html#variable-declaration). This macro can be used as initializer when declaring the builder, but it cannot be assigned to a variable. The builder can be initialized to a specific [type@GLib.VariantType] later with [method@GLib.VariantBuilder.init]. Use [func@GLib.VARIANT_BUILDER_INIT] to directly initialize the builder with a specific [type@GLib.VariantType]. ```c g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT_UNSET (); if (condition) return NULL; g_variant_builder_init (&builder, G_VARIANT_TYPE ("a{su}")); return g_variant_ref_sink (g_variant_builder_end (&builder)); ``` A stack-allocated #GVariantDict must be initialized if it is used together with g_auto() to avoid warnings or crashes if function returns before g_variant_dict_init() is called on the builder. This macro can be used as initializer instead of an explicit zeroing a variable when declaring it and a following g_variant_dict_init(), but it cannot be assigned to a variable. The passed @asv has to live long enough for #GVariantDict to gather the entries from, as the gathering does not happen in the G_VARIANT_DICT_INIT() call, but rather in functions that make sure that #GVariantDict is valid. In context where the initialization value has to be a constant expression, the only possible value of @asv is %NULL. It is still possible to call g_variant_dict_init() safely with a different @asv right after the variable was initialized with G_VARIANT_DICT_INIT(). |[<!-- language="C" --> g_autoptr(GVariant) variant = get_asv_variant (); g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant); ]| a GVariant* Converts a string to a const [type@GLib.VariantType]. Depending on the current debugging level, this function may perform a runtime check to ensure that @string is a valid [type@GLib.Variant] type string. It is always a programmer error to use this macro with an invalid type string. If in doubt, use [func@GLib.variant_type_string_is_valid] to check if the string is valid. Since 2.24 a well-formed [type@GLib.VariantType] type string A macro that should be defined by the user prior to including the glib.h header. The definition should be one of the predefined GLib version macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,... This macro defines the earliest version of GLib that the package is required to be able to compile against. If the compiler is configured to warn about the use of deprecated functions, then using functions that were deprecated in version %GLIB_VERSION_MIN_REQUIRED or earlier will cause warnings (but using functions deprecated in later releases will not). `GVariant` is a variant datatype; it can contain one or more values along with information about the type of the values. A `GVariant` may contain simple types, like an integer, or a boolean value; or complex types, like an array of two strings, or a dictionary of key value pairs. A `GVariant` is also immutable: once it’s been created neither its type nor its content can be modified further. `GVariant` is useful whenever data needs to be serialized, for example when sending method parameters in D-Bus, or when saving settings using [`GSettings`](../gio/class.Settings.html). When creating a new `GVariant`, you pass the data you want to store in it along with a string representing the type of data you wish to pass to it. For instance, if you want to create a `GVariant` holding an integer value you can use: ```c GVariant *v = g_variant_new ("u", 40); ``` The string `u` in the first argument tells `GVariant` that the data passed to the constructor (`40`) is going to be an unsigned integer. More advanced examples of `GVariant` in use can be found in documentation for [`GVariant` format strings](gvariant-format-strings.html#pointers). The range of possible values is determined by the type. The type system used by `GVariant` is [type@GLib.VariantType]. `GVariant` instances always have a type and a value (which are given at construction time). The type and value of a `GVariant` instance can never change other than by the `GVariant` itself being destroyed. A `GVariant` cannot contain a pointer. `GVariant` is reference counted using [method@GLib.Variant.ref] and [method@GLib.Variant.unref]. `GVariant` also has floating reference counts — see [method@GLib.Variant.ref_sink]. `GVariant` is completely threadsafe. A `GVariant` instance can be concurrently accessed in any way from any number of threads without problems. `GVariant` is heavily optimised for dealing with data in serialized form. It works particularly well with data located in memory-mapped files. It can perform nearly all deserialization operations in a small constant time, usually touching only a single memory page. Serialized `GVariant` data can also be sent over the network. `GVariant` is largely compatible with D-Bus. Almost all types of `GVariant` instances can be sent over D-Bus. See [type@GLib.VariantType] for exceptions. (However, `GVariant`’s serialization format is not the same as the serialization format of a D-Bus message body: use [GDBusMessage](../gio/class.DBusMessage.html), in the GIO library, for those.) For space-efficiency, the `GVariant` serialization format does not automatically include the variant’s length, type or endianness, which must either be implied from context (such as knowledge that a particular file format always contains a little-endian `G_VARIANT_TYPE_VARIANT` which occupies the whole length of the file) or supplied out-of-band (for instance, a length, type and/or endianness indicator could be placed at the beginning of a file, network message or network stream). A `GVariant`’s size is limited mainly by any lower level operating system constraints, such as the number of bits in `gsize`. For example, it is reasonable to have a 2GB file mapped into memory with [struct@GLib.MappedFile], and call [ctor@GLib.Variant.new_from_data] on it. For convenience to C programmers, `GVariant` features powerful varargs-based value construction and destruction. This feature is designed to be embedded in other libraries. There is a Python-inspired text language for describing `GVariant` values. `GVariant` includes a printer for this language and a parser with type inferencing. ## Memory Use `GVariant` tries to be quite efficient with respect to memory use. This section gives a rough idea of how much memory is used by the current implementation. The information here is subject to change in the future. The memory allocated by `GVariant` can be grouped into 4 broad purposes: memory for serialized data, memory for the type information cache, buffer management memory and memory for the `GVariant` structure itself. ## Serialized Data Memory This is the memory that is used for storing `GVariant` data in serialized form. This is what would be sent over the network or what would end up on disk, not counting any indicator of the endianness, or of the length or type of the top-level variant. The amount of memory required to store a boolean is 1 byte. 16, 32 and 64 bit integers and double precision floating point numbers use their ‘natural’ size. Strings (including object path and signature strings) are stored with a nul terminator, and as such use the length of the string plus 1 byte. ‘Maybe’ types use no space at all to represent the null value and use the same amount of space (sometimes plus one byte) as the equivalent non-maybe-typed value to represent the non-null case. Arrays use the amount of space required to store each of their members, concatenated. Additionally, if the items stored in an array are not of a fixed-size (ie: strings, other arrays, etc) then an additional framing offset is stored for each item. The size of this offset is either 1, 2 or 4 bytes depending on the overall size of the container. Additionally, extra padding bytes are added as required for alignment of child values. Tuples (including dictionary entries) use the amount of space required to store each of their members, concatenated, plus one framing offset (as per arrays) for each non-fixed-sized item in the tuple, except for the last one. Additionally, extra padding bytes are added as required for alignment of child values. Variants use the same amount of space as the item inside of the variant, plus 1 byte, plus the length of the type string for the item inside the variant. As an example, consider a dictionary mapping strings to variants. In the case that the dictionary is empty, 0 bytes are required for the serialization. If we add an item ‘width’ that maps to the int32 value of 500 then we will use 4 bytes to store the int32 (so 6 for the variant containing it) and 6 bytes for the string. The variant must be aligned to 8 after the 6 bytes of the string, so that’s 2 extra bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used for the dictionary entry. An additional 1 byte is added to the array as a framing offset making a total of 15 bytes. If we add another entry, ‘title’ that maps to a nullable string that happens to have a value of null, then we use 0 bytes for the null value (and 3 bytes for the variant to contain it along with its type string) plus 6 bytes for the string. Again, we need 2 padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. We now require extra padding between the two items in the array. After the 14 bytes of the first item, that’s 2 bytes required. We now require 2 framing offsets for an extra two bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item dictionary. ## Type Information Cache For each `GVariant` type that currently exists in the program a type information structure is kept in the type information cache. The type information structure is required for rapid deserialization. Continuing with the above example, if a `GVariant` exists with the type `a{sv}` then a type information struct will exist for `a{sv}`, `{sv}`, `s`, and `v`. Multiple uses of the same type will share the same type information. Additionally, all single-digit types are stored in read-only static memory and do not contribute to the writable memory footprint of a program using `GVariant`. Aside from the type information structures stored in read-only memory, there are two forms of type information. One is used for container types where there is a single element type: arrays and maybe types. The other is used for container types where there are multiple element types: tuples and dictionary entries. Array type info structures are `6 * sizeof (void *)`, plus the memory required to store the type string itself. This means that on 32-bit systems, the cache entry for `a{sv}` would require 30 bytes of memory (plus allocation overhead). Tuple type info structures are `6 * sizeof (void *)`, plus `4 * sizeof (void *)` for each item in the tuple, plus the memory required to store the type string itself. A 2-item tuple, for example, would have a type information structure that consumed writable memory in the size of `14 * sizeof (void *)` (plus type string) This means that on 32-bit systems, the cache entry for `{sv}` would require 61 bytes of memory (plus allocation overhead). This means that in total, for our `a{sv}` example, 91 bytes of type information would be allocated. The type information cache, additionally, uses a [struct@GLib.HashTable] to store and look up the cached items and stores a pointer to this hash table in static storage. The hash table is freed when there are zero items in the type cache. Although these sizes may seem large it is important to remember that a program will probably only have a very small number of different types of values in it and that only one type information structure is required for many different values of the same type. ## Buffer Management Memory `GVariant` uses an internal buffer management structure to deal with the various different possible sources of serialized data that it uses. The buffer is responsible for ensuring that the correct call is made when the data is no longer in use by `GVariant`. This may involve a [func@GLib.free] or even [method@GLib.MappedFile.unref]. One buffer management structure is used for each chunk of serialized data. The size of the buffer management structure is `4 * (void *)`. On 32-bit systems, that’s 16 bytes. ## GVariant structure The size of a `GVariant` structure is `6 * (void *)`. On 32-bit systems, that’s 24 bytes. `GVariant` structures only exist if they are explicitly created with API calls. For example, if a `GVariant` is constructed out of serialized data for the example given above (with the dictionary) then although there are 9 individual values that comprise the entire dictionary (two keys, two values, two variants containing the values, two dictionary entries, plus the dictionary itself), only 1 `GVariant` instance exists — the one referring to the dictionary. If calls are made to start accessing the other values then `GVariant` instances will exist for those values only for as long as they are in use (ie: until you call [method@GLib.Variant.unref]). The type information is shared. The serialized data and the buffer management structure for that serialized data is shared by the child. ## Summary To put the entire example together, for our dictionary mapping strings to variants (with two entries, as given above), we are using 91 bytes of memory for type information, 29 bytes of memory for the serialized data, 16 bytes for buffer management and 24 bytes for the `GVariant` instance, or a total of 160 bytes, plus allocation overhead. If we were to use [method@GLib.Variant.get_child_value] to access the two dictionary entries, we would use an additional 48 bytes. If we were to have other dictionaries of the same type, we would use more memory for the serialized data and buffer management for those dictionaries, but the type information would be shared. Creates a new #GVariant instance. Think of this function as an analogue to g_strdup_printf(). The type of the created instance and the arguments that are expected by this function are determined by @format_string. See the section on [GVariant format strings](gvariant-format-strings.html). Please note that the syntax of the format string is very likely to be extended in the future. The first character of the format string must not be '*' '?' '@' or 'r'; in essence, a new #GVariant must always be constructed by this function (and not merely passed through it unmodified). Note that the arguments must be of the correct width for their types specified in @format_string. This can be achieved by casting them. See the [GVariant varargs documentation](gvariant-format-strings.html#varargs). |[<!-- language="C" --> MyFlags some_flags = FLAG_ONE | FLAG_TWO; const gchar *some_strings[] = { "a", "b", "c", NULL }; GVariant *new_variant; new_variant = g_variant_new ("(t^as)", // This cast is required. (guint64) some_flags, some_strings); ]| a new floating #GVariant instance a #GVariant format string arguments, as per @format_string Creates a new #GVariant array from @children. @child_type must be non-%NULL if @n_children is zero. Otherwise, the child type is determined by inspecting the first element of the @children array. If @child_type is non-%NULL then it must be a definite type. The items of the array are taken from the @children array. No entry in the @children array may be %NULL. All items in the array must have the same type, which must be the same as @child_type, if given. If the @children are floating references (see g_variant_ref_sink()), the new instance takes ownership of them as if via g_variant_ref_sink(). a floating reference to a new #GVariant array the element type of the new array an array of #GVariant pointers, the children the length of @children Creates a new boolean #GVariant instance -- either %TRUE or %FALSE. a floating reference to a new boolean #GVariant instance a #gboolean value Creates a new byte #GVariant instance. a floating reference to a new byte #GVariant instance a #guint8 value Creates an array-of-bytes #GVariant with the contents of @string. This function is just like g_variant_new_string() except that the string need not be valid UTF-8. The nul terminator character at the end of the string is stored in the array. a floating reference to a new bytestring #GVariant instance a normal nul-terminated string in no particular encoding Constructs an array of bytestring #GVariant from the given array of strings. If @length is -1 then @strv is %NULL-terminated. a new floating #GVariant instance an array of strings the length of @strv, or -1 Creates a new dictionary entry #GVariant. @key and @value must be non-%NULL. @key must be a value of a basic type (ie: not a container). If the @key or @value are floating references (see g_variant_ref_sink()), the new instance takes ownership of them as if via g_variant_ref_sink(). a floating reference to a new dictionary entry #GVariant a basic #GVariant, the key a #GVariant, the value Creates a new double #GVariant instance. a floating reference to a new double #GVariant instance a #gdouble floating point value Constructs a new array #GVariant instance, where the elements are of @element_type type. @elements must be an array with fixed-sized elements. Numeric types are fixed-size as are tuples containing only other fixed-sized types. @element_size must be the size of a single element in the array. For example, if calling this function for an array of 32-bit integers, you might say sizeof(gint32). This value isn't used except for the purpose of a double-check that the form of the serialized data matches the caller's expectation. @n_elements must be the length of the @elements array. a floating reference to a new array #GVariant instance the #GVariantType of each element a pointer to the fixed array of contiguous elements the number of elements the size of each element Constructs a new serialized-mode #GVariant instance. This is the inner interface for creation of new serialized values that gets called from various functions in gvariant.c. A reference is taken on @bytes. The data in @bytes must be aligned appropriately for the @type being loaded. Otherwise this function will internally create a copy of the memory (since GLib 2.60) or (in older versions) fail and exit the process. a new #GVariant with a floating reference a #GVariantType a #GBytes if the contents of @bytes are trusted Creates a new #GVariant instance from serialized data. @type is the type of #GVariant instance that will be constructed. The interpretation of @data depends on knowing the type. @data is not modified by this function and must remain valid with an unchanging value until such a time as @notify is called with @user_data. If the contents of @data change before that time then the result is undefined. If @data is trusted to be serialized data in normal form then @trusted should be %TRUE. This applies to serialized data created within this process or read from a trusted location on the disk (such as a file installed in /usr/lib alongside your application). You should set trusted to %FALSE if @data is read from the network, a file in the user's home directory, etc. If @data was not stored in this machine's native endianness, any multi-byte numeric values in the returned variant will also be in non-native endianness. g_variant_byteswap() can be used to recover the original values. @notify will be called with @user_data when @data is no longer needed. The exact time of this call is unspecified and might even be before this function returns. Note: @data must be backed by memory that is aligned appropriately for the @type being loaded. Otherwise this function will internally create a copy of the memory (since GLib 2.60) or (in older versions) fail and exit the process. a new floating #GVariant of type @type a definite #GVariantType the serialized data the size of @data %TRUE if @data is definitely in normal form function to call when @data is no longer needed data for @notify Creates a new handle #GVariant instance. By convention, handles are indexes into an array of file descriptors that are sent alongside a D-Bus message. If you're not interacting with D-Bus, you probably don't need them. a floating reference to a new handle #GVariant instance a #gint32 value Creates a new int16 #GVariant instance. a floating reference to a new int16 #GVariant instance a #gint16 value Creates a new int32 #GVariant instance. a floating reference to a new int32 #GVariant instance a #gint32 value Creates a new int64 #GVariant instance. a floating reference to a new int64 #GVariant instance a #gint64 value Depending on if @child is %NULL, either wraps @child inside of a maybe container or creates a Nothing instance for the given @type. At least one of @child_type and @child must be non-%NULL. If @child_type is non-%NULL then it must be a definite type. If they are both non-%NULL then @child_type must be the type of @child. If @child is a floating reference (see g_variant_ref_sink()), the new instance takes ownership of @child. a floating reference to a new #GVariant maybe instance the #GVariantType of the child, or %NULL the child value, or %NULL Creates a D-Bus object path #GVariant with the contents of @object_path. @object_path must be a valid D-Bus object path. Use g_variant_is_object_path() if you're not sure. a floating reference to a new object path #GVariant instance a normal C nul-terminated string Constructs an array of object paths #GVariant from the given array of strings. Each string must be a valid #GVariant object path; see g_variant_is_object_path(). If @length is -1 then @strv is %NULL-terminated. a new floating #GVariant instance an array of strings the length of @strv, or -1 Parses @format and returns the result. @format must be a text format #GVariant with one extension: at any point that a value may appear in the text, a '%' character followed by a GVariant format string (as per g_variant_new()) may appear. In that case, the same arguments are collected from the argument list as g_variant_new() would have collected. Note that the arguments must be of the correct width for their types specified in @format. This can be achieved by casting them. See the [GVariant varargs documentation](gvariant-format-strings.html#varargs). Consider this simple example: |[<!-- language="C" --> g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three"); ]| In the example, the variable argument parameters are collected and filled in as if they were part of the original string to produce the result of |[<!-- language="C" --> [('one', 1), ('two', 2), ('three', 3)] ]| This function is intended only to be used with @format as a string literal. Any parse error is fatal to the calling process. If you want to parse data from untrusted sources, use g_variant_parse(). You may not use this function to return, unmodified, a single #GVariant pointer from the argument list. ie: @format may not solely be anything along the lines of "%*", "%?", "\%r", or anything starting with "%@". a new floating #GVariant instance a text format #GVariant arguments as per @format Parses @format and returns the result. This is the version of g_variant_new_parsed() intended to be used from libraries. The return value will be floating if it was a newly created GVariant instance. In the case that @format simply specified the collection of a #GVariant pointer (eg: @format was "%*") then the collected #GVariant pointer will be returned unmodified, without adding any additional references. Note that the arguments in @app must be of the correct width for their types specified in @format when collected into the #va_list. See the [GVariant varargs documentation](gvariant-format-strings.html#varargs). In order to behave correctly in all cases it is necessary for the calling function to g_variant_ref_sink() the return result before returning control to the user that originally provided the pointer. At this point, the caller will have their own full reference to the result. This can also be done by adding the result to a container, or by passing it to another g_variant_new() call. a new, usually floating, #GVariant a text format #GVariant a pointer to a #va_list Creates a string-type GVariant using printf formatting. This is similar to calling g_strdup_printf() and then g_variant_new_string() but it saves a temporary variable and an unnecessary copy. a floating reference to a new string #GVariant instance a printf-style format string arguments for @format_string Creates a D-Bus type signature #GVariant with the contents of @string. @string must be a valid D-Bus type signature. Use g_variant_is_signature() if you're not sure. a floating reference to a new signature #GVariant instance a normal C nul-terminated string Creates a string #GVariant with the contents of @string. @string must be valid UTF-8, and must not be %NULL. To encode potentially-%NULL strings, use g_variant_new() with `ms` as the [format string](gvariant-format-strings.html#maybe-types). a floating reference to a new string #GVariant instance a normal UTF-8 nul-terminated string Constructs an array of strings #GVariant from the given array of strings. If @length is -1 then @strv is %NULL-terminated. a new floating #GVariant instance an array of strings the length of @strv, or -1 Creates a string #GVariant with the contents of @string. @string must be valid UTF-8, and must not be %NULL. To encode potentially-%NULL strings, use this with g_variant_new_maybe(). After this call, @string belongs to the #GVariant and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with g_free(). You must not modify or access @string in any other way after passing it to this function. It is even possible that @string is immediately freed. a floating reference to a new string #GVariant instance a normal UTF-8 nul-terminated string Creates a new tuple #GVariant out of the items in @children. The type is determined from the types of @children. No entry in the @children array may be %NULL. If @n_children is 0 then the unit tuple is constructed. If the @children are floating references (see g_variant_ref_sink()), the new instance takes ownership of them as if via g_variant_ref_sink(). a floating reference to a new #GVariant tuple the items to make the tuple out of the length of @children Creates a new uint16 #GVariant instance. a floating reference to a new uint16 #GVariant instance a #guint16 value Creates a new uint32 #GVariant instance. a floating reference to a new uint32 #GVariant instance a #guint32 value Creates a new uint64 #GVariant instance. a floating reference to a new uint64 #GVariant instance a #guint64 value This function is intended to be used by libraries based on #GVariant that want to provide g_variant_new()-like functionality to their users. The API is more general than g_variant_new() to allow a wider range of possible uses. @format_string must still point to a valid format string, but it only needs to be nul-terminated if @endptr is %NULL. If @endptr is non-%NULL then it is updated to point to the first character past the end of the format string. @app is a pointer to a #va_list. The arguments, according to @format_string, are collected from this #va_list and the list is left pointing to the argument following the last. Note that the arguments in @app must be of the correct width for their types specified in @format_string when collected into the #va_list. See the [GVariant varargs documentation](gvariant-format-strings.html#varargs). These two generalisations allow mixing of multiple calls to g_variant_new_va() and g_variant_get_va() within a single actual varargs call by the user. The return value will be floating if it was a newly created GVariant instance (for example, if the format string was "(ii)"). In the case that the format_string was '*', '?', 'r', or a format starting with '@' then the collected #GVariant pointer will be returned unmodified, without adding any additional references. In order to behave correctly in all cases it is necessary for the calling function to g_variant_ref_sink() the return result before returning control to the user that originally provided the pointer. At this point, the caller will have their own full reference to the result. This can also be done by adding the result to a container, or by passing it to another g_variant_new() call. a new, usually floating, #GVariant a string that is prefixed with a format string location to store the end pointer, or %NULL a pointer to a #va_list Boxes @value. The result is a #GVariant instance representing a variant containing the original value. If @child is a floating reference (see g_variant_ref_sink()), the new instance takes ownership of @child. a floating reference to a new variant #GVariant instance a #GVariant instance Performs a byteswapping operation on the contents of @value. The result is that all multi-byte numeric data contained in @value is byteswapped. That includes 16, 32, and 64bit signed and unsigned integers as well as file handles and double precision floating point values. This function is an identity mapping on any value that does not contain multi-byte numeric data. That include strings, booleans, bytes and containers containing only these things (recursively). While this function can safely handle untrusted, non-normal data, it is recommended to check whether the input is in normal form beforehand, using g_variant_is_normal_form(), and to reject non-normal inputs if your application can be strict about what inputs it rejects. The returned value is always in normal form and is marked as trusted. A full, not floating, reference is returned. the byteswapped form of @value a #GVariant Checks if calling g_variant_get() with @format_string on @value would be valid from a type-compatibility standpoint. @format_string is assumed to be a valid format string (from a syntactic standpoint). If @copy_only is %TRUE then this function additionally checks that it would be safe to call g_variant_unref() on @value immediately after the call to g_variant_get() without invalidating the result. This is only possible if deep copies are made (ie: there are no pointers to the data inside of the soon-to-be-freed #GVariant instance). If this check fails then a g_critical() is printed and %FALSE is returned. This function is meant to be used by functions that wish to provide varargs accessors to #GVariant values of uncertain values (eg: g_variant_lookup() or g_menu_model_get_item_attribute()). %TRUE if @format_string is safe to use a #GVariant a valid #GVariant format string %TRUE to ensure the format string makes deep copies Classifies @value according to its top-level type. the #GVariantClass of @value a #GVariant Compares @one and @two. The types of @one and @two are #gconstpointer only to allow use of this function with #GTree, #GPtrArray, etc. They must each be a #GVariant. Comparison is only defined for basic types (ie: booleans, numbers, strings). For booleans, %FALSE is less than %TRUE. Numbers are ordered in the usual way. Strings are in ASCII lexographical order. It is a programmer error to attempt to compare container values or two values that have types that are not exactly equal. For example, you cannot compare a 32-bit signed integer with a 32-bit unsigned integer. Also note that this function is not particularly well-behaved when it comes to comparison of doubles; in particular, the handling of incomparable values (ie: NaN) is undefined. If you only require an equality comparison, g_variant_equal() is more general. negative value if a < b; zero if a = b; positive value if a > b. a basic-typed #GVariant instance a #GVariant instance of the same type Similar to g_variant_get_bytestring() except that instead of returning a constant string, the string is duplicated. The return value must be freed using g_free(). a newly allocated string an array-of-bytes #GVariant instance a pointer to a #gsize, to store the length (not including the nul terminator) Gets the contents of an array of array of bytes #GVariant. This call makes a deep copy; the return result should be released with g_strfreev(). If @length is non-%NULL then the number of elements in the result is stored there. In any case, the resulting array will be %NULL-terminated. For an empty array, @length will be set to 0 and a pointer to a %NULL pointer will be returned. an array of strings an array of array of bytes #GVariant ('aay') the length of the result, or %NULL Gets the contents of an array of object paths #GVariant. This call makes a deep copy; the return result should be released with g_strfreev(). If @length is non-%NULL then the number of elements in the result is stored there. In any case, the resulting array will be %NULL-terminated. For an empty array, @length will be set to 0 and a pointer to a %NULL pointer will be returned. an array of strings an array of object paths #GVariant the length of the result, or %NULL Similar to g_variant_get_string() except that instead of returning a constant string, the string is duplicated. The string will always be UTF-8 encoded. The return value must be freed using g_free(). a newly allocated string, UTF-8 encoded a string #GVariant instance a pointer to a #gsize, to store the length Gets the contents of an array of strings #GVariant. This call makes a deep copy; the return result should be released with g_strfreev(). If @length is non-%NULL then the number of elements in the result is stored there. In any case, the resulting array will be %NULL-terminated. For an empty array, @length will be set to 0 and a pointer to a %NULL pointer will be returned. an array of strings an array of strings #GVariant the length of the result, or %NULL Checks if @one and @two have the same type and value. The types of @one and @two are #gconstpointer only to allow use of this function with #GHashTable. They must each be a #GVariant. %TRUE if @one and @two are equal a #GVariant instance a #GVariant instance Deconstructs a #GVariant instance. Think of this function as an analogue to scanf(). The arguments that are expected by this function are entirely determined by @format_string. @format_string also restricts the permissible types of @value. It is an error to give a value with an incompatible type. See the section on [GVariant format strings](gvariant-format-strings.html). Please note that the syntax of the format string is very likely to be extended in the future. @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on [`GVariant` format strings](gvariant-format-strings.html#pointers). a #GVariant instance a #GVariant format string arguments, as per @format_string Returns the boolean value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_BOOLEAN. %TRUE or %FALSE a boolean #GVariant instance Returns the byte value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_BYTE. a #guint8 a byte #GVariant instance Returns the string value of a #GVariant instance with an array-of-bytes type. The string has no particular encoding. If the array does not end with a nul terminator character, the empty string is returned. For this reason, you can always trust that a non-%NULL nul-terminated string will be returned by this function. If the array contains a nul terminator character somewhere other than the last byte then the returned string is the string, up to the first such nul character. g_variant_get_fixed_array() should be used instead if the array contains arbitrary data that could not be nul-terminated or could contain nul bytes. It is an error to call this function with a @value that is not an array of bytes. The return value remains valid as long as @value exists. the constant string an array-of-bytes #GVariant instance Gets the contents of an array of array of bytes #GVariant. This call makes a shallow copy; the return result should be released with g_free(), but the individual strings must not be modified. If @length is non-%NULL then the number of elements in the result is stored there. In any case, the resulting array will be %NULL-terminated. For an empty array, @length will be set to 0 and a pointer to a %NULL pointer will be returned. an array of constant strings an array of array of bytes #GVariant ('aay') the length of the result, or %NULL Reads a child item out of a container #GVariant instance and deconstructs it according to @format_string. This call is essentially a combination of g_variant_get_child_value() and g_variant_get(). @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on [`GVariant` format strings](gvariant-format-strings.html#pointers). a container #GVariant the index of the child to deconstruct a #GVariant format string arguments, as per @format_string Reads a child item out of a container #GVariant instance. This includes variants, maybes, arrays, tuples and dictionary entries. It is an error to call this function on any other type of #GVariant. It is an error if @index_ is greater than the number of child items in the container. See g_variant_n_children(). The returned value is never floating. You should free it with g_variant_unref() when you're done with it. Note that values borrowed from the returned child are not guaranteed to still be valid after the child is freed even if you still hold a reference to @value, if @value has not been serialized at the time this function is called. To avoid this, you can serialize @value by calling g_variant_get_data() and optionally ignoring the return value. There may be implementation specific restrictions on deeply nested values, which would result in the unit tuple being returned as the child value, instead of further nested children. #GVariant is guaranteed to handle nesting up to at least 64 levels. This function is O(1). the child at the specified index a container #GVariant the index of the child to fetch Returns a pointer to the serialized form of a #GVariant instance. The returned data may not be in fully-normalised form if read from an untrusted source. The returned data must not be freed; it remains valid for as long as @value exists. If @value is a fixed-sized value that was deserialized from a corrupted serialized container then %NULL may be returned. In this case, the proper thing to do is typically to use the appropriate number of nul bytes in place of @value. If @value is not fixed-sized then %NULL is never returned. In the case that @value is already in serialized form, this function is O(1). If the value is not already in serialized form, serialization occurs implicitly and is approximately O(n) in the size of the result. To deserialize the data returned by this function, in addition to the serialized data, you must know the type of the #GVariant, and (if the machine might be different) the endianness of the machine that stored it. As a result, file formats or network messages that incorporate serialized #GVariants must include this information either implicitly (for instance "the file always contains a %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or explicitly (by storing the type and/or endianness in addition to the serialized data). the serialized form of @value, or %NULL a #GVariant instance Returns a pointer to the serialized form of a #GVariant instance. The semantics of this function are exactly the same as g_variant_get_data(), except that the returned #GBytes holds a reference to the variant data. A new #GBytes representing the variant data a #GVariant Returns the double precision floating point value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_DOUBLE. a #gdouble a double #GVariant instance Provides access to the serialized data for an array of fixed-sized items. @value must be an array with fixed-sized elements. Numeric types are fixed-size, as are tuples containing only other fixed-sized types. @element_size must be the size of a single element in the array, as given by the section on [serialized data memory](struct.Variant.html#serialized-data-memory). In particular, arrays of these fixed-sized types can be interpreted as an array of the given C type, with @element_size set to the size the appropriate type: - %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.) - %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!) - %G_VARIANT_TYPE_BYTE: #guint8 - %G_VARIANT_TYPE_HANDLE: #guint32 - %G_VARIANT_TYPE_DOUBLE: #gdouble For example, if calling this function for an array of 32-bit integers, you might say `sizeof(gint32)`. This value isn't used except for the purpose of a double-check that the form of the serialized data matches the caller's expectation. @n_elements, which must be non-%NULL, is set equal to the number of items in the array. a pointer to the fixed array a #GVariant array with fixed-sized elements a pointer to the location to store the number of items the size of each element Returns the 32-bit signed integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_HANDLE. By convention, handles are indexes into an array of file descriptors that are sent alongside a D-Bus message. If you're not interacting with D-Bus, you probably don't need them. a #gint32 a handle #GVariant instance Returns the 16-bit signed integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_INT16. a #gint16 an int16 #GVariant instance Returns the 32-bit signed integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_INT32. a #gint32 an int32 #GVariant instance Returns the 64-bit signed integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_INT64. a #gint64 an int64 #GVariant instance Given a maybe-typed #GVariant instance, extract its value. If the value is Nothing, then this function returns %NULL. the contents of @value, or %NULL a maybe-typed value Gets a #GVariant instance that has the same value as @value and is trusted to be in normal form. If @value is already trusted to be in normal form then a new reference to @value is returned. If @value is not already trusted, then it is scanned to check if it is in normal form. If it is found to be in normal form then it is marked as trusted and a new reference to it is returned. If @value is found not to be in normal form then a new trusted #GVariant is created with the same value as @value. The non-normal parts of @value will be replaced with default values which are guaranteed to be in normal form. It makes sense to call this function if you've received #GVariant data from untrusted sources and you want to ensure your serialized output is definitely in normal form. If @value is already in normal form, a new reference will be returned (which will be floating if @value is floating). If it is not in normal form, the newly created #GVariant will be returned with a single non-floating reference. Typically, g_variant_take_ref() should be called on the return value from this function to guarantee ownership of a single non-floating reference to it. a trusted #GVariant a #GVariant Gets the contents of an array of object paths #GVariant. This call makes a shallow copy; the return result should be released with g_free(), but the individual strings must not be modified. If @length is non-%NULL then the number of elements in the result is stored there. In any case, the resulting array will be %NULL-terminated. For an empty array, @length will be set to 0 and a pointer to a %NULL pointer will be returned. an array of constant strings an array of object paths #GVariant the length of the result, or %NULL Determines the number of bytes that would be required to store @value with g_variant_store(). If @value has a fixed-sized type then this function always returned that fixed size. In the case that @value is already in serialized form or the size has already been calculated (ie: this function has been called before) then this function is O(1). Otherwise, the size is calculated, an operation which is approximately O(n) in the number of values involved. the serialized size of @value a #GVariant instance Returns the string value of a #GVariant instance with a string type. This includes the types %G_VARIANT_TYPE_STRING, %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE. The string will always be UTF-8 encoded, will never be %NULL, and will never contain nul bytes. If @length is non-%NULL then the length of the string (in bytes) is returned there. For trusted values, this information is already known. Untrusted values will be validated and, if valid, a strlen() will be performed. If invalid, a default value will be returned — for %G_VARIANT_TYPE_OBJECT_PATH, this is `"/"`, and for other types it is the empty string. It is an error to call this function with a @value of any type other than those three. The return value remains valid as long as @value exists. the constant string, UTF-8 encoded a string #GVariant instance a pointer to a #gsize, to store the length Gets the contents of an array of strings #GVariant. This call makes a shallow copy; the return result should be released with g_free(), but the individual strings must not be modified. If @length is non-%NULL then the number of elements in the result is stored there. In any case, the resulting array will be %NULL-terminated. For an empty array, @length will be set to 0 and a pointer to a %NULL pointer will be returned. an array of constant strings an array of strings #GVariant the length of the result, or %NULL Determines the type of @value. The return value is valid for the lifetime of @value and must not be freed. a #GVariantType a #GVariant Returns the type string of @value. Unlike the result of calling g_variant_type_peek_string(), this string is nul-terminated. This string belongs to #GVariant and must not be freed. the type string for the type of @value a #GVariant Returns the 16-bit unsigned integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_UINT16. a #guint16 a uint16 #GVariant instance Returns the 32-bit unsigned integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_UINT32. a #guint32 a uint32 #GVariant instance Returns the 64-bit unsigned integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_UINT64. a #guint64 a uint64 #GVariant instance This function is intended to be used by libraries based on #GVariant that want to provide g_variant_get()-like functionality to their users. The API is more general than g_variant_get() to allow a wider range of possible uses. @format_string must still point to a valid format string, but it only need to be nul-terminated if @endptr is %NULL. If @endptr is non-%NULL then it is updated to point to the first character past the end of the format string. @app is a pointer to a #va_list. The arguments, according to @format_string, are collected from this #va_list and the list is left pointing to the argument following the last. These two generalisations allow mixing of multiple calls to g_variant_new_va() and g_variant_get_va() within a single actual varargs call by the user. @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on [`GVariant` format strings](gvariant-format-strings.html#pointers). a #GVariant a string that is prefixed with a format string location to store the end pointer, or %NULL a pointer to a #va_list Unboxes @value. The result is the #GVariant instance that was contained in @value. the item contained in the variant a variant #GVariant instance Generates a hash value for a #GVariant instance. The output of this function is guaranteed to be the same for a given value only per-process. It may change between different processor architectures or even different versions of GLib. Do not use this function as a basis for building protocols or file formats. The type of @value is #gconstpointer only to allow use of this function with #GHashTable. @value must be a #GVariant. a hash value corresponding to @value a basic #GVariant value as a #gconstpointer Checks if @value is a container. %TRUE if @value is a container a #GVariant instance Checks whether @value has a floating reference count. This function should only ever be used to assert that a given variant is or is not floating, or for debug purposes. To acquire a reference to a variant that might be floating, always use g_variant_ref_sink() or g_variant_take_ref(). See g_variant_ref_sink() for more information about floating reference counts. whether @value is floating a #GVariant Checks if @value is in normal form. The main reason to do this is to detect if a given chunk of serialized data is in normal form: load the data into a #GVariant using g_variant_new_from_data() and then use this function to check. If @value is found to be in normal form then it will be marked as being trusted. If the value was already marked as being trusted then this function will immediately return %TRUE. There may be implementation specific restrictions on deeply nested values. GVariant is guaranteed to handle nesting up to at least 64 levels. %TRUE if @value is in normal form a #GVariant instance Checks if a value has a type matching the provided type. %TRUE if the type of @value matches @type a #GVariant instance a #GVariantType Creates a heap-allocated #GVariantIter for iterating over the items in @value. Use g_variant_iter_free() to free the return value when you no longer need it. A reference is taken to @value and will be released only when g_variant_iter_free() is called. a new heap-allocated #GVariantIter a container #GVariant Looks up a value in a dictionary #GVariant. This function is a wrapper around g_variant_lookup_value() and g_variant_get(). In the case that %NULL would have been returned, this function returns %FALSE. Otherwise, it unpacks the returned value and returns %TRUE. @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on [`GVariant` format strings](gvariant-format-strings.html#pointers). This function is currently implemented with a linear scan. If you plan to do many lookups then #GVariantDict may be more efficient. %TRUE if a value was unpacked a dictionary #GVariant the key to look up in the dictionary a GVariant format string the arguments to unpack the value into Looks up a value in a dictionary #GVariant. This function works with dictionaries of the type a{s*} (and equally well with type a{o*}, but we only further discuss the string case for sake of clarity). In the event that @dictionary has the type a{sv}, the @expected_type string specifies what type of value is expected to be inside of the variant. If the value inside the variant has a different type then %NULL is returned. In the event that @dictionary has a value type other than v then @expected_type must directly match the value type and it is used to unpack the value directly or an error occurs. In either case, if @key is not found in @dictionary, %NULL is returned. If the key is found and the value has the correct type, it is returned. If @expected_type was specified then any non-%NULL return value will have this type. This function is currently implemented with a linear scan. If you plan to do many lookups then #GVariantDict may be more efficient. the value of the dictionary key, or %NULL a dictionary #GVariant the key to look up in the dictionary a #GVariantType, or %NULL Determines the number of children in a container #GVariant instance. This includes variants, maybes, arrays, tuples and dictionary entries. It is an error to call this function on any other type of #GVariant. For variants, the return value is always 1. For values with maybe types, it is always zero or one. For arrays, it is the length of the array. For tuples it is the number of tuple items (which depends only on the type). For dictionary entries, it is always 2 This function is O(1). the number of children in the container a container #GVariant Pretty-prints @value in the format understood by g_variant_parse(). The format is described [here](gvariant-text-format.html). If @type_annotate is %TRUE, then type information is included in the output. a newly-allocated string holding the result. a #GVariant %TRUE if type information should be included in the output Behaves as g_variant_print(), but operates on a #GString. If @string is non-%NULL then it is appended to and returned. Else, a new empty #GString is allocated and it is returned. a #GString containing the string a #GVariant a #GString, or %NULL %TRUE if type information should be included in the output Increases the reference count of @value. the same @value a #GVariant #GVariant uses a floating reference count system. All functions with names starting with `g_variant_new_` return floating references. Calling g_variant_ref_sink() on a #GVariant with a floating reference will convert the floating reference into a full reference. Calling g_variant_ref_sink() on a non-floating #GVariant results in an additional normal reference being added. In other words, if the @value is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference. If the @value is not floating, then this call adds a new normal reference increasing the reference count by one. All calls that result in a #GVariant instance being inserted into a container will call g_variant_ref_sink() on the instance. This means that if the value was just created (and has only its floating reference) then the container will assume sole ownership of the value at that point and the caller will not need to unreference it. This makes certain common styles of programming much easier while still maintaining normal refcounting semantics in situations where values are not floating. the same @value a #GVariant Stores the serialized form of @value at @data. @data should be large enough. See g_variant_get_size(). The stored data is in machine native byte order but may not be in fully-normalised form if read from an untrusted source. See g_variant_get_normal_form() for a solution. As with g_variant_get_data(), to be able to deserialize the serialized variant successfully, its type and (if the destination machine might be different) its endianness must also be available. This function is approximately O(n) in the size of @data. the #GVariant to store the location to store the serialized data at If @value is floating, sink it. Otherwise, do nothing. Typically you want to use g_variant_ref_sink() in order to automatically do the correct thing with respect to floating or non-floating references, but there is one specific scenario where this function is helpful. The situation where this function is helpful is when creating an API that allows the user to provide a callback function that returns a #GVariant. We certainly want to allow the user the flexibility to return a non-floating reference from this callback (for the case where the value that is being returned already exists). At the same time, the style of the #GVariant API makes it likely that for newly-created #GVariant instances, the user can be saved some typing if they are allowed to return a #GVariant with a floating reference. Using this function on the return value of the user's callback allows the user to do whichever is more convenient for them. The caller will always receives exactly one full reference to the value: either the one that was returned in the first place, or a floating reference that has been converted to a full reference. This function has an odd interaction when combined with g_variant_ref_sink() running at the same time in another thread on the same #GVariant instance. If g_variant_ref_sink() runs first then the result will be that the floating reference is converted to a hard reference. If g_variant_take_ref() runs first then the result will be that the floating reference is converted to a hard reference and an additional reference on top of that one is added. It is best to avoid this situation. the same @value a #GVariant Decreases the reference count of @value. When its reference count drops to 0, the memory used by the variant is freed. a #GVariant Determines if a given string is a valid D-Bus object path. You should ensure that a string is a valid D-Bus object path before passing it to g_variant_new_object_path(). A valid object path starts with `/` followed by zero or more sequences of characters separated by `/` characters. Each sequence must contain only the characters `[A-Z][a-z][0-9]_`. No sequence (including the one following the final `/` character) may be empty. %TRUE if @string is a D-Bus object path a normal C nul-terminated string Determines if a given string is a valid D-Bus type signature. You should ensure that a string is a valid D-Bus type signature before passing it to g_variant_new_signature(). D-Bus type signatures consist of zero or more definite #GVariantType strings in sequence. %TRUE if @string is a D-Bus type signature a normal C nul-terminated string Parses a #GVariant from a text representation. A single #GVariant is parsed from the content of @text. The format is described [here](gvariant-text-format.html). The memory at @limit will never be accessed and the parser behaves as if the character at @limit is the nul terminator. This has the effect of bounding @text. If @endptr is non-%NULL then @text is permitted to contain data following the value that this function parses and @endptr will be updated to point to the first character past the end of the text parsed by this function. If @endptr is %NULL and there is extra data then an error is returned. If @type is non-%NULL then the value will be parsed to have that type. This may result in additional parse errors (in the case that the parsed value doesn't fit the type) but may also result in fewer errors (in the case that the type would have been ambiguous, such as with empty arrays). In the event that the parsing is successful, the resulting #GVariant is returned. It is never floating, and must be freed with [method@GLib.Variant.unref]. In case of any error, %NULL will be returned. If @error is non-%NULL then it will be set to reflect the error that occurred. Officially, the language understood by the parser is “any string produced by [method@GLib.Variant.print]”. This explicitly includes `g_variant_print()`’s annotated types like `int64 -1000`. There may be implementation specific restrictions on deeply nested values, which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is guaranteed to handle nesting up to at least 64 levels. a non-floating reference to a #GVariant, or %NULL a #GVariantType, or %NULL a string containing a GVariant in text form a pointer to the end of @text, or %NULL a location to store the end pointer, or %NULL Pretty-prints a message showing the context of a #GVariant parse error within the string for which parsing was attempted. The resulting string is suitable for output to the console or other monospace media where newlines are treated in the usual way. The message will typically look something like one of the following: |[ unterminated string constant: (1, 2, 3, 'abc ^^^^ ]| or |[ unable to find a common type: [1, 2, 3, 'str'] ^ ^^^^^ ]| The format of the message may change in a future version. @error must have come from a failed attempt to g_variant_parse() and @source_str must be exactly the same string that caused the error. If @source_str was not nul-terminated when you passed it to g_variant_parse() then you must add nul termination before using this function. the printed message a #GError from the #GVariantParseError domain the string that was given to the parser Same as g_variant_error_quark(). Use g_variant_parse_error_quark() instead. A utility type for constructing container-type #GVariant instances. This is an opaque structure and may only be accessed using the following functions. #GVariantBuilder is not threadsafe in any way. Do not attempt to access it from more than one thread. Allocates and initialises a new #GVariantBuilder. You should call g_variant_builder_unref() on the return value when it is no longer needed. The memory will not be automatically freed by any other call. In most cases it is easier to place a #GVariantBuilder directly on the stack of the calling function and initialise it with g_variant_builder_init_static(). a #GVariantBuilder a container type Adds to a #GVariantBuilder. This call is a convenience wrapper that is exactly equivalent to calling g_variant_new() followed by g_variant_builder_add_value(). Note that the arguments must be of the correct width for their types specified in @format_string. This can be achieved by casting them. See the [GVariant varargs documentation](gvariant-format-strings.html#varargs). This function might be used as follows: |[<!-- language="C" --> GVariant * make_pointless_dictionary (void) { GVariantBuilder builder; int i; g_variant_builder_init_static (&builder, G_VARIANT_TYPE_ARRAY); for (i = 0; i < 16; i++) { gchar buf[3]; sprintf (buf, "%d", i); g_variant_builder_add (&builder, "{is}", i, buf); } return g_variant_builder_end (&builder); } ]| a #GVariantBuilder a #GVariant varargs format string arguments, as per @format_string Adds to a #GVariantBuilder. This call is a convenience wrapper that is exactly equivalent to calling g_variant_new_parsed() followed by g_variant_builder_add_value(). Note that the arguments must be of the correct width for their types specified in @format_string. This can be achieved by casting them. See the [GVariant varargs documentation](gvariant-format-strings.html#varargs). This function might be used as follows: |[<!-- language="C" --> GVariant * make_pointless_dictionary (void) { GVariantBuilder builder; int i; g_variant_builder_init_static (&builder, G_VARIANT_TYPE_ARRAY); g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600); g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo"); g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}"); return g_variant_builder_end (&builder); } ]| a #GVariantBuilder a text format #GVariant arguments as per @format Adds @value to @builder. It is an error to call this function in any way that would create an inconsistent value to be constructed. Some examples of this are putting different types of items into an array, putting the wrong types or number of items in a tuple, putting more than one value into a variant, etc. If @value is a floating reference (see g_variant_ref_sink()), the @builder instance takes ownership of @value. a #GVariantBuilder a #GVariant Releases all memory associated with a #GVariantBuilder without freeing the #GVariantBuilder structure itself. It typically only makes sense to do this on a stack-allocated #GVariantBuilder if you want to abort building the value part-way through. This function need not be called if you call g_variant_builder_end() and it also doesn't need to be called on builders allocated with g_variant_builder_new() (see g_variant_builder_unref() for that). This function leaves the #GVariantBuilder structure set to all-zeros. It is valid to call this function on either an initialised #GVariantBuilder or one that is set to all-zeros but it is not valid to call this function on uninitialised memory. a #GVariantBuilder Closes the subcontainer inside the given @builder that was opened by the most recent call to g_variant_builder_open(). It is an error to call this function in any way that would create an inconsistent value to be constructed (ie: too few values added to the subcontainer). a #GVariantBuilder Ends the builder process and returns the constructed value. It is not permissible to use @builder in any way after this call except for reference counting operations (in the case of a heap-allocated #GVariantBuilder) or by reinitialising it with g_variant_builder_init() (in the case of stack-allocated). This means that for the stack-allocated builders there is no need to call g_variant_builder_clear() after the call to g_variant_builder_end(). It is an error to call this function in any way that would create an inconsistent value to be constructed (ie: insufficient number of items added to a container with a specific number of children required). It is also an error to call this function if the builder was created with an indefinite array or maybe type and no children have been added; in this case it is impossible to infer the type of the empty array. a new, floating, #GVariant a #GVariantBuilder Initialises a #GVariantBuilder structure. @type must be non-%NULL. It specifies the type of container to construct. It can be an indefinite type such as %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)". Maybe, array, tuple, dictionary entry and variant-typed values may be constructed. If using a static type such as one of the `G_VARIANT_TYPE_*` constants or a `G_VARIANT_TYPE ("(ii)")` macro, it is more performant to use g_variant_builder_init_static() rather than g_variant_builder_init(). After the builder is initialised, values are added using g_variant_builder_add_value() or g_variant_builder_add(). After all the child values are added, g_variant_builder_end() frees the memory associated with the builder and returns the #GVariant that was created. This function completely ignores the previous contents of @builder. On one hand this means that it is valid to pass in completely uninitialised memory. On the other hand, this means that if you are initialising over top of an existing #GVariantBuilder you need to first call g_variant_builder_clear() in order to avoid leaking memory. You must not call g_variant_builder_ref() or g_variant_builder_unref() on a #GVariantBuilder that was initialised with this function. If you ever pass a reference to a #GVariantBuilder outside of the control of your own code then you should assume that the person receiving that reference may try to use reference counting; you should use g_variant_builder_new() instead of this function. a #GVariantBuilder a container type Initialises a #GVariantBuilder structure. This function works exactly like g_variant_builder_init() but does not make a copy of @type. Therefore, @type must remain valid for the lifetime of @builder. This is always true of type constants like `G_VARIANT_TYPE_*` or `G_VARIANT_TYPE ("(ii)")`. a #GVariantBuilder a container type Opens a subcontainer inside the given @builder. When done adding items to the subcontainer, g_variant_builder_close() must be called. @type is the type of the container: so to build a tuple of several values, @type must include the tuple itself. It is an error to call this function in any way that would cause an inconsistent value to be constructed (ie: adding too many values or a value of an incorrect type). Example of building a nested variant: |[<!-- language="C" --> GVariantBuilder builder; guint32 some_number = get_number (); g_autoptr (GHashTable) some_dict = get_dict (); GHashTableIter iter; const gchar *key; const GVariant *value; g_autoptr (GVariant) output = NULL; g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})")); g_variant_builder_add (&builder, "u", some_number); g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}")); g_hash_table_iter_init (&iter, some_dict); while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value)) { g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}")); g_variant_builder_add (&builder, "s", key); g_variant_builder_add (&builder, "v", value); g_variant_builder_close (&builder); } g_variant_builder_close (&builder); output = g_variant_builder_end (&builder); ]| a #GVariantBuilder the #GVariantType of the container Increases the reference count on @builder. Don't call this on stack-allocated #GVariantBuilder instances or bad things will happen. a new reference to @builder a #GVariantBuilder allocated by g_variant_builder_new() Decreases the reference count on @builder. In the event that there are no more references, releases all memory associated with the #GVariantBuilder. Don't call this on stack-allocated #GVariantBuilder instances or bad things will happen. a #GVariantBuilder allocated by g_variant_builder_new() The range of possible top-level types of #GVariant instances. The #GVariant is a boolean. The #GVariant is a byte. The #GVariant is a signed 16 bit integer. The #GVariant is an unsigned 16 bit integer. The #GVariant is a signed 32 bit integer. The #GVariant is an unsigned 32 bit integer. The #GVariant is a signed 64 bit integer. The #GVariant is an unsigned 64 bit integer. The #GVariant is a file handle index. The #GVariant is a double precision floating point value. The #GVariant is a normal string. The #GVariant is a D-Bus object path string. The #GVariant is a D-Bus signature string. The #GVariant is a variant. The #GVariant is a maybe-typed value. The #GVariant is an array. The #GVariant is a tuple. The #GVariant is a dictionary entry. #GVariantDict is a mutable interface to #GVariant dictionaries. It can be used for doing a sequence of dictionary lookups in an efficient way on an existing #GVariant dictionary or it can be used to construct new dictionaries with a hashtable-like interface. It can also be used for taking existing dictionaries and modifying them in order to create new ones. #GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT dictionaries. It is possible to use #GVariantDict allocated on the stack or on the heap. When using a stack-allocated #GVariantDict, you begin with a call to g_variant_dict_init() and free the resources with a call to g_variant_dict_clear(). Heap-allocated #GVariantDict follows normal refcounting rules: you allocate it with g_variant_dict_new() and use g_variant_dict_ref() and g_variant_dict_unref(). g_variant_dict_end() is used to convert the #GVariantDict back into a dictionary-type #GVariant. When used with stack-allocated instances, this also implicitly frees all associated memory, but for heap-allocated instances, you must still call g_variant_dict_unref() afterwards. You will typically want to use a heap-allocated #GVariantDict when you expose it as part of an API. For most other uses, the stack-allocated form will be more convenient. Consider the following two examples that do the same thing in each style: take an existing dictionary and look up the "count" uint32 key, adding 1 to it if it is found, or returning an error if the key is not found. Each returns the new dictionary as a floating #GVariant. ## Using a stack-allocated GVariantDict |[<!-- language="C" --> GVariant * add_to_count (GVariant *orig, GError **error) { GVariantDict dict; guint32 count; g_variant_dict_init (&dict, orig); if (!g_variant_dict_lookup (&dict, "count", "u", &count)) { g_set_error (...); g_variant_dict_clear (&dict); return NULL; } g_variant_dict_insert (&dict, "count", "u", count + 1); return g_variant_dict_end (&dict); } ]| ## Using heap-allocated GVariantDict |[<!-- language="C" --> GVariant * add_to_count (GVariant *orig, GError **error) { GVariantDict *dict; GVariant *result; guint32 count; dict = g_variant_dict_new (orig); if (g_variant_dict_lookup (dict, "count", "u", &count)) { g_variant_dict_insert (dict, "count", "u", count + 1); result = g_variant_dict_end (dict); } else { g_set_error (...); result = NULL; } g_variant_dict_unref (dict); return result; } ]| Allocates and initialises a new #GVariantDict. You should call g_variant_dict_unref() on the return value when it is no longer needed. The memory will not be automatically freed by any other call. In some cases it may be easier to place a #GVariantDict directly on the stack of the calling function and initialise it with g_variant_dict_init(). This is particularly useful when you are using #GVariantDict to construct a #GVariant. a #GVariantDict the #GVariant with which to initialise the dictionary Releases all memory associated with a #GVariantDict without freeing the #GVariantDict structure itself. It typically only makes sense to do this on a stack-allocated #GVariantDict if you want to abort building the value part-way through. This function need not be called if you call g_variant_dict_end() and it also doesn't need to be called on dicts allocated with g_variant_dict_new (see g_variant_dict_unref() for that). It is valid to call this function on either an initialised #GVariantDict or one that was previously cleared by an earlier call to g_variant_dict_clear() but it is not valid to call this function on uninitialised memory. a #GVariantDict Checks if @key exists in @dict. %TRUE if @key is in @dict a #GVariantDict the key to look up in the dictionary Returns the current value of @dict as a #GVariant of type %G_VARIANT_TYPE_VARDICT, clearing it in the process. It is not permissible to use @dict in any way after this call except for reference counting operations (in the case of a heap-allocated #GVariantDict) or by reinitialising it with g_variant_dict_init() (in the case of stack-allocated). a new, floating, #GVariant a #GVariantDict Initialises a #GVariantDict structure. If @from_asv is given, it is used to initialise the dictionary. This function completely ignores the previous contents of @dict. On one hand this means that it is valid to pass in completely uninitialised memory. On the other hand, this means that if you are initialising over top of an existing #GVariantDict you need to first call g_variant_dict_clear() in order to avoid leaking memory. You must not call g_variant_dict_ref() or g_variant_dict_unref() on a #GVariantDict that was initialised with this function. If you ever pass a reference to a #GVariantDict outside of the control of your own code then you should assume that the person receiving that reference may try to use reference counting; you should use g_variant_dict_new() instead of this function. a #GVariantDict the initial value for @dict Inserts a value into a #GVariantDict. This call is a convenience wrapper that is exactly equivalent to calling g_variant_new() followed by g_variant_dict_insert_value(). a #GVariantDict the key to insert a value for a #GVariant varargs format string arguments, as per @format_string Inserts (or replaces) a key in a #GVariantDict. @value is consumed if it is floating. a #GVariantDict the key to insert a value for the value to insert Looks up a value in a #GVariantDict. This function is a wrapper around g_variant_dict_lookup_value() and g_variant_get(). In the case that %NULL would have been returned, this function returns %FALSE and does not modify the values of the arguments passed in to @.... Otherwise, it unpacks the returned value and returns %TRUE. @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on [`GVariant` format strings](gvariant-format-strings.html#pointers). %TRUE if a value was unpacked a #GVariantDict the key to look up in the dictionary a GVariant format string the arguments to unpack the value into Looks up a value in a #GVariantDict. If @key is not found in @dictionary, %NULL is returned. The @expected_type string specifies what type of value is expected. If the value associated with @key has a different type then %NULL is returned. If the key is found and the value has the correct type, it is returned. If @expected_type was specified then any non-%NULL return value will have this type. the value of the dictionary key, or %NULL a #GVariantDict the key to look up in the dictionary a #GVariantType, or %NULL Increases the reference count on @dict. Don't call this on stack-allocated #GVariantDict instances or bad things will happen. a new reference to @dict a heap-allocated #GVariantDict Removes a key and its associated value from a #GVariantDict. %TRUE if the key was found and removed a #GVariantDict the key to remove Decreases the reference count on @dict. In the event that there are no more references, releases all memory associated with the #GVariantDict. Don't call this on stack-allocated #GVariantDict instances or bad things will happen. a heap-allocated #GVariantDict #GVariantIter is an opaque data structure and can only be accessed using the following functions. Creates a new heap-allocated #GVariantIter to iterate over the container that was being iterated over by @iter. Iteration begins on the new iterator from the current position of the old iterator but the two copies are independent past that point. Use g_variant_iter_free() to free the return value when you no longer need it. A reference is taken to the container that @iter is iterating over and will be related only when g_variant_iter_free() is called. a new heap-allocated #GVariantIter a #GVariantIter Frees a heap-allocated #GVariantIter. Only call this function on iterators that were returned by g_variant_iter_new() or g_variant_iter_copy(). a heap-allocated #GVariantIter Initialises (without allocating) a #GVariantIter. @iter may be completely uninitialised prior to this call; its old value is ignored. The iterator remains valid for as long as @value exists, and need not be freed in any way. the number of items in @value a pointer to a #GVariantIter a container #GVariant Gets the next item in the container and unpacks it into the variable argument list according to @format_string, returning %TRUE. If no more items remain then %FALSE is returned. On the first call to this function, the pointers appearing on the variable argument list are assumed to point at uninitialised memory. On the second and later calls, it is assumed that the same pointers will be given and that they will point to the memory as set by the previous call to this function. This allows the previous values to be freed, as appropriate. This function is intended to be used with a while loop as demonstrated in the following example. This function can only be used when iterating over an array. It is only valid to call this function with a string constant for the format string and the same string constant must be used each time. Mixing calls to this function and g_variant_iter_next() or g_variant_iter_next_value() on the same iterator causes undefined behavior. If you break out of a such a while loop using g_variant_iter_loop() then you must free or unreference all the unpacked values as you would with g_variant_get(). Failure to do so will cause a memory leak. Here is an example for memory management with g_variant_iter_loop(): |[<!-- language="C" --> // Iterates a dictionary of type 'a{sv}' void iterate_dictionary (GVariant *dictionary) { GVariantIter iter; GVariant *value; gchar *key; g_variant_iter_init (&iter, dictionary); while (g_variant_iter_loop (&iter, "{sv}", &key, &value)) { g_print ("Item '%s' has type '%s'\n", key, g_variant_get_type_string (value)); // no need to free 'key' and 'value' here // unless breaking out of this loop } } ]| For most cases you should use g_variant_iter_next(). This function is really only useful when unpacking into #GVariant or #GVariantIter in order to allow you to skip the call to g_variant_unref() or g_variant_iter_free(). For example, if you are only looping over simple integer and string types, g_variant_iter_next() is definitely preferred. For string types, use the '&' prefix to avoid allocating any memory at all (and thereby avoiding the need to free anything as well). @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed. See the section on [`GVariant` format strings](gvariant-format-strings.html#pointers). %TRUE if a value was unpacked, or %FALSE if there was no value a #GVariantIter a GVariant format string the arguments to unpack the value into Queries the number of child items in the container that we are iterating over. This is the total number of items -- not the number of items remaining. This function might be useful for preallocation of arrays. the number of children in the container a #GVariantIter Gets the next item in the container and unpacks it into the variable argument list according to @format_string, returning %TRUE. If no more items remain then %FALSE is returned. All of the pointers given on the variable arguments list of this function are assumed to point at uninitialised memory. It is the responsibility of the caller to free all of the values returned by the unpacking process. Here is an example for memory management with g_variant_iter_next(): |[<!-- language="C" --> // Iterates a dictionary of type 'a{sv}' void iterate_dictionary (GVariant *dictionary) { GVariantIter iter; GVariant *value; gchar *key; g_variant_iter_init (&iter, dictionary); while (g_variant_iter_next (&iter, "{sv}", &key, &value)) { g_print ("Item '%s' has type '%s'\n", key, g_variant_get_type_string (value)); // must free data for ourselves g_variant_unref (value); g_free (key); } } ]| For a solution that is likely to be more convenient to C programmers when dealing with loops, see g_variant_iter_loop(). @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed. See the section on [`GVariant` format strings](gvariant-format-strings.html#pointers). %TRUE if a value was unpacked, or %FALSE if there as no value a #GVariantIter a GVariant format string the arguments to unpack the value into Gets the next item in the container. If no more items remain then %NULL is returned. Use g_variant_unref() to drop your reference on the return value when you no longer need it. Here is an example for iterating with g_variant_iter_next_value(): |[<!-- language="C" --> // recursively iterate a container void iterate_container_recursive (GVariant *container) { GVariantIter iter; GVariant *child; g_variant_iter_init (&iter, container); while ((child = g_variant_iter_next_value (&iter))) { g_print ("type '%s'\n", g_variant_get_type_string (child)); if (g_variant_is_container (child)) iterate_container_recursive (child); g_variant_unref (child); } } ]| a #GVariant, or %NULL a #GVariantIter Error codes returned by parsing text-format GVariants. generic error (unused) a non-basic #GVariantType was given where a basic type was expected cannot infer the #GVariantType an indefinite #GVariantType was given where a definite type was expected extra data after parsing finished invalid character in number or unicode escape not a valid #GVariant format string not a valid object path not a valid type signature not a valid #GVariant type string could not find a common type for array entries the numerical value is out of range of the given type the numerical value is out of range for any type cannot parse as variant of the specified type an unexpected token was encountered an unknown keyword was encountered unterminated string constant no value given variant was too deeply nested; #GVariant is only guaranteed to handle nesting up to 64 levels (Since: 2.64) A type in the [type@GLib.Variant] type system. [type@GLib.Variant] types are represented as strings, but have a strict syntax described below. All [type@GLib.VariantType]s passed to GLib must be valid, and they are typically expected to be static (i.e. not provided by user input) as they determine how binary [type@GLib.Variant] data is interpreted. To convert a static string to a [type@GLib.VariantType] in C, use the [func@GLib.VARIANT_TYPE] casting macro. When GLib is compiled with checks enabled, it will validate the type. To check if an arbitrary string is a valid [type@GLib.VariantType], use [func@GLib.VariantType.string_is_valid]. ## GVariant Type System This section introduces the [type@GLib.Variant] type system. It is based, in large part, on the D-Bus type system, with two major changes and some minor lifting of restrictions. The [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html), therefore, provides a significant amount of information that is useful when working with [type@GLib.Variant]. The first major change with respect to the D-Bus type system is the introduction of maybe (or ‘nullable’) types. Any type in [type@GLib.Variant] can be converted to a maybe type, in which case, `nothing` (or `null`) becomes a valid value. Maybe types have been added by introducing the character `m` to type strings. The second major change is that the [type@GLib.Variant] type system supports the concept of ‘indefinite types’ — types that are less specific than the normal types found in D-Bus. For example, it is possible to speak of ‘an array of any type’ in [type@GLib.Variant], where the D-Bus type system would require you to speak of ‘an array of integers’ or ‘an array of strings’. Indefinite types have been added by introducing the characters `*`, `?` and `r` to type strings. Finally, all arbitrary restrictions relating to the complexity of types are lifted along with the restriction that dictionary entries may only appear nested inside of arrays. Just as in D-Bus, [type@GLib.Variant] types are described with strings (‘type strings’). Subject to the differences mentioned above, these strings are of the same form as those found in D-Bus. Note, however: D-Bus always works in terms of messages and therefore individual type strings appear nowhere in its interface. Instead, ‘signatures’ are a concatenation of the strings of the type of each argument in a message. [type@GLib.Variant] deals with single values directly so [type@GLib.Variant] type strings always describe the type of exactly one value. This means that a D-Bus signature string is generally not a valid [type@GLib.Variant] type string — except in the case that it is the signature of a message containing exactly one argument. An indefinite type is similar in spirit to what may be called an abstract type in other type systems. No value can exist that has an indefinite type as its type, but values can exist that have types that are subtypes of indefinite types. That is to say, [method@GLib.Variant.get_type] will never return an indefinite type, but calling [method@GLib.Variant.is_of_type] with an indefinite type may return true. For example, you cannot have a value that represents ‘an array of no particular type’, but you can have an ‘array of integers’ which certainly matches the type of ‘an array of no particular type’, since ‘array of integers’ is a subtype of ‘array of no particular type’. This is similar to how instances of abstract classes may not directly exist in other type systems, but instances of their non-abstract subtypes may. For example, in GTK, no object that has the type of [`GtkWidget`](https://docs.gtk.org/gtk4/class.Widget.html) can exist (since `GtkWidget` is an abstract class), but a [`GtkWindow`](https://docs.gtk.org/gtk4/class.Window.html) can certainly be instantiated, and you would say that a `GtkWindow` is a `GtkWidget` (since `GtkWindow` is a subclass of `GtkWidget`). Two types may not be compared by value; use [method@GLib.VariantType.equal] or [method@GLib.VariantType.is_subtype_of] May be copied using [method@GLib.VariantType.copy] and freed using [method@GLib.VariantType.free]. ## GVariant Type Strings A [type@GLib.Variant] type string can be any of the following: - any basic type string (listed below) - `v`, `r` or `*` - one of the characters `a` or `m`, followed by another type string - the character `(`, followed by a concatenation of zero or more other type strings, followed by the character `)` - the character `{`, followed by a basic type string (see below), followed by another type string, followed by the character `}` A basic type string describes a basic type (as per [method@GLib.VariantType.is_basic]) and is always a single character in length. The valid basic type strings are `b`, `y`, `n`, `q`, `i`, `u`, `x`, `t`, `h`, `d`, `s`, `o`, `g` and `?`. The above definition is recursive to arbitrary depth. `aaaaai` and `(ui(nq((y)))s)` are both valid type strings, as is `a(aa(ui)(qna{ya(yd)}))`. In order to not hit memory limits, [type@GLib.Variant] imposes a limit on recursion depth of 65 nested containers. This is the limit in the D-Bus specification (64) plus one to allow a [`GDBusMessage`](../gio/class.DBusMessage.html) to be nested in a top-level tuple. The meaning of each of the characters is as follows: - `b`: the type string of `G_VARIANT_TYPE_BOOLEAN`; a boolean value. - `y`: the type string of `G_VARIANT_TYPE_BYTE`; a byte. - `n`: the type string of `G_VARIANT_TYPE_INT16`; a signed 16 bit integer. - `q`: the type string of `G_VARIANT_TYPE_UINT16`; an unsigned 16 bit integer. - `i`: the type string of `G_VARIANT_TYPE_INT32`; a signed 32 bit integer. - `u`: the type string of `G_VARIANT_TYPE_UINT32`; an unsigned 32 bit integer. - `x`: the type string of `G_VARIANT_TYPE_INT64`; a signed 64 bit integer. - `t`: the type string of `G_VARIANT_TYPE_UINT64`; an unsigned 64 bit integer. - `h`: the type string of `G_VARIANT_TYPE_HANDLE`; a signed 32 bit value that, by convention, is used as an index into an array of file descriptors that are sent alongside a D-Bus message. - `d`: the type string of `G_VARIANT_TYPE_DOUBLE`; a double precision floating point value. - `s`: the type string of `G_VARIANT_TYPE_STRING`; a string. - `o`: the type string of `G_VARIANT_TYPE_OBJECT_PATH`; a string in the form of a D-Bus object path. - `g`: the type string of `G_VARIANT_TYPE_SIGNATURE`; a string in the form of a D-Bus type signature. - `?`: the type string of `G_VARIANT_TYPE_BASIC`; an indefinite type that is a supertype of any of the basic types. - `v`: the type string of `G_VARIANT_TYPE_VARIANT`; a container type that contain any other type of value. - `a`: used as a prefix on another type string to mean an array of that type; the type string `ai`, for example, is the type of an array of signed 32-bit integers. - `m`: used as a prefix on another type string to mean a ‘maybe’, or ‘nullable’, version of that type; the type string `ms`, for example, is the type of a value that maybe contains a string, or maybe contains nothing. - `()`: used to enclose zero or more other concatenated type strings to create a tuple type; the type string `(is)`, for example, is the type of a pair of an integer and a string. - `r`: the type string of `G_VARIANT_TYPE_TUPLE`; an indefinite type that is a supertype of any tuple type, regardless of the number of items. - `{}`: used to enclose a basic type string concatenated with another type string to create a dictionary entry type, which usually appears inside of an array to form a dictionary; the type string `a{sd}`, for example, is the type of a dictionary that maps strings to double precision floating point values. The first type (the basic type) is the key type and the second type is the value type. The reason that the first type is restricted to being a basic type is so that it can easily be hashed. - `*`: the type string of `G_VARIANT_TYPE_ANY`; the indefinite type that is a supertype of all types. Note that, as with all type strings, this character represents exactly one type. It cannot be used inside of tuples to mean ‘any number of items’. Any type string of a container that contains an indefinite type is, itself, an indefinite type. For example, the type string `a*` (corresponding to `G_VARIANT_TYPE_ARRAY`) is an indefinite type that is a supertype of every array type. `(*s)` is a supertype of all tuples that contain exactly two items where the second item is a string. `a{?*}` is an indefinite type that is a supertype of all arrays containing dictionary entries where the key is any basic type and the value is any type at all. This is, by definition, a dictionary, so this type string corresponds to `G_VARIANT_TYPE_DICTIONARY`. Note that, due to the restriction that the key of a dictionary entry must be a basic type, `{**}` is not a valid type string. Creates a new [type@GLib.VariantType] corresponding to the type string given by @type_string. It is appropriate to call [method@GLib.VariantType.free] on the return value. It is a programmer error to call this function with an invalid type string. Use [func@GLib.VariantType.string_is_valid] if you are unsure. a new [type@GLib.VariantType] a valid [GVariant type string](./struct.VariantType.html#gvariant-type-strings) Constructs the type corresponding to an array of elements of the type @type. It is appropriate to call [method@GLib.VariantType.first] on the return value. a new array type Since 2.24 an element type Constructs the type corresponding to a dictionary entry with a key of type @key and a value of type @value. It is appropriate to call [method@GLib.VariantType.free] on the return value. a new dictionary entry type Since 2.24 a basic type to use for the key a type to use for the value Constructs the type corresponding to a ‘maybe’ instance containing type @type or `Nothing`. It is appropriate to call [method@GLib.VariantType.free] on the return value. a new ‘maybe’ type Since 2.24 an element type Constructs a new tuple type, from @items. @length is the number of items in @items, or `-1` to indicate that @items is `NULL`-terminated. It is appropriate to call [method@GLib.VariantType.free] on the return value. a new tuple type Since 2.24 an array of types, one for each item the length of @items, or `-1` Makes a copy of a [type@GLib.VariantType]. It is appropriate to call [method@GLib.VariantType.free] on the return value. @type may not be `NULL`. a new [type@GLib.VariantType] Since 2.24 type to copy Returns a newly-allocated copy of the type string corresponding to @type. The returned string is nul-terminated. It is appropriate to call [func@GLib.free] on the return value. the corresponding type string Since 2.24 type to copy Determines the element type of an array or ‘maybe’ type. This function may only be used with array or ‘maybe’ types. the element type of @type Since 2.24 an array or ‘maybe’ type Compares @type1 and @type2 for equality. Only returns true if the types are exactly equal. Even if one type is an indefinite type and the other is a subtype of it, false will be returned if they are not exactly equal. If you want to check for subtypes, use [method@GLib.VariantType.is_subtype_of]. The argument types of @type1 and @type2 are only `gconstpointer` to allow use with [type@GLib.HashTable] without function pointer casting. For both arguments, a valid [type@GLib.VariantType] must be provided. true if @type1 and @type2 are exactly equal Since 2.24 type to compare another type to compare Determines the first item type of a tuple or dictionary entry type. This function may only be used with tuple or dictionary entry types, but must not be used with the generic tuple type `G_VARIANT_TYPE_TUPLE`. In the case of a dictionary entry type, this returns the type of the key. `NULL` is returned in case of @type being `G_VARIANT_TYPE_UNIT`. This call, together with [method@GLib.VariantType.next] provides an iterator interface over tuple and dictionary entry types. the first item type of @type, or `NULL` if the type has no item types Since 2.24 a tuple or dictionary entry type Frees a [type@GLib.VariantType] that was allocated with [method@GLib.VariantType.copy], [ctor@GLib.VariantType.new] or one of the container type constructor functions. In the case that @type is `NULL`, this function does nothing. Since 2.24 type to free Returns the length of the type string corresponding to the given @type. This function must be used to determine the valid extent of the memory region returned by [method@GLib.VariantType.peek_string]. the length of the corresponding type string Since 2.24 type to measure Hashes @type. The argument type of @type is only `gconstpointer` to allow use with [type@GLib.HashTable] without function pointer casting. A valid [type@GLib.VariantType] must be provided. the hash value Since 2.24 type to hash Determines if the given @type is an array type. This is true if the type string for @type starts with an `a`. This function returns true for any indefinite type for which every definite subtype is an array type — `G_VARIANT_TYPE_ARRAY`, for example. true if @type is an array type Since 2.24 type to check Determines if the given @type is a basic type. Basic types are booleans, bytes, integers, doubles, strings, object paths and signatures. Only a basic type may be used as the key of a dictionary entry. This function returns `FALSE` for all indefinite types except `G_VARIANT_TYPE_BASIC`. true if @type is a basic type Since 2.24 type to check Determines if the given @type is a container type. Container types are any array, maybe, tuple, or dictionary entry types plus the variant type. This function returns true for any indefinite type for which every definite subtype is a container — `G_VARIANT_TYPE_ARRAY`, for example. true if @type is a container type Since 2.24 type to check Determines if the given @type is definite (ie: not indefinite). A type is definite if its type string does not contain any indefinite type characters (`*`, `?`, or `r`). A [type@GLib.Variant] instance may not have an indefinite type, so calling this function on the result of [method@GLib.Variant.get_type] will always result in true being returned. Calling this function on an indefinite type like `G_VARIANT_TYPE_ARRAY`, however, will result in `FALSE` being returned. true if @type is definite Since 2.24 type to check Determines if the given @type is a dictionary entry type. This is true if the type string for @type starts with a `{`. This function returns true for any indefinite type for which every definite subtype is a dictionary entry type — `G_VARIANT_TYPE_DICT_ENTRY`, for example. true if @type is a dictionary entry type Since 2.24 type to check Determines if the given @type is a ‘maybe’ type. This is true if the type string for @type starts with an `m`. This function returns true for any indefinite type for which every definite subtype is a ‘maybe’ type — `G_VARIANT_TYPE_MAYBE`, for example. true if @type is a ‘maybe’ type Since 2.24 type to check Checks if @type is a subtype of @supertype. This function returns true if @type is a subtype of @supertype. All types are considered to be subtypes of themselves. Aside from that, only indefinite types can have subtypes. true if @type is a subtype of @supertype Since 2.24 type to check type of potential supertype Determines if the given @type is a tuple type. This is true if the type string for @type starts with a `(` or if @type is `G_VARIANT_TYPE_TUPLE`. This function returns true for any indefinite type for which every definite subtype is a tuple type — `G_VARIANT_TYPE_TUPLE`, for example. true if @type is a tuple type Since 2.24 type to check Determines if the given @type is the variant type. true if @type is the variant type Since 2.24 type to check Determines the key type of a dictionary entry type. This function may only be used with a dictionary entry type. Other than the additional restriction, this call is equivalent to [method@GLib.VariantType.first]. the key type of the dictionary entry Since 2.24 a dictionary entry type Determines the number of items contained in a tuple or dictionary entry type. This function may only be used with tuple or dictionary entry types, but must not be used with the generic tuple type `G_VARIANT_TYPE_TUPLE`. In the case of a dictionary entry type, this function will always return `2`. the number of items in @type Since 2.24 a tuple or dictionary entry type Determines the next item type of a tuple or dictionary entry type. @type must be the result of a previous call to [method@GLib.VariantType.first] or [method@GLib.VariantType.next]. If called on the key type of a dictionary entry then this call returns the value type. If called on the value type of a dictionary entry then this call returns `NULL`. For tuples, `NULL` is returned when @type is the last item in the tuple. the next type after @type, or `NULL` if there are no further types Since 2.24 a type from a previous call Returns the type string corresponding to the given @type. The result is not nul-terminated; in order to determine its length you must call [method@GLib.VariantType.get_string_length]. To get a nul-terminated string, see [method@GLib.VariantType.dup_string]. the corresponding type string (not nul-terminated) Since 2.24 type to peek at Determines the value type of a dictionary entry type. This function may only be used with a dictionary entry type. the value type of the dictionary entry Since 2.24 a dictionary entry type Checks if @type_string is a valid [GVariant type string](./struct.VariantType.html#gvariant-type-strings). This call is equivalent to calling [func@GLib.VariantType.string_scan] and confirming that the following character is a nul terminator. true if @type_string is exactly one valid type string Since 2.24 a pointer to any string Scan for a single complete and valid GVariant type string in @string. The memory pointed to by @limit (or bytes beyond it) is never accessed. If a valid type string is found, @endptr is updated to point to the first character past the end of the string that was found and %TRUE is returned. If there is no valid type string starting at @string, or if the type string does not end before @limit then %FALSE is returned. For the simple case of checking if a string is a valid type string, see [func@GLib.VariantType.string_is_valid]. true if a valid type string was found a pointer to any string the end of @string location to store the end pointer Declares a type of function which takes no arguments and has no return value. It is used to specify the type function passed to g_atexit(). On Windows, this macro defines a DllMain() function that stores the actual DLL name that the code being compiled will be included in. On non-Windows platforms, expands to nothing. empty or "static" the name of the (pointer to the) char array where the DLL name will be stored. If this is used, you must also include `windows.h`. If you need a more complex DLL entry point function, you cannot use this A wrapper for the POSIX abort() function. On Windows it is a function that makes extra effort (including a call to abort()) to ensure that a debugger-catchable exception is thrown before the program terminates. See your C library manual for more details about abort(). A wrapper for the POSIX access() function. This function is used to test a pathname for one or several of read, write or execute permissions, or just existence. On Windows, the file protection mechanism is not at all POSIX-like, and the underlying function in the C library only checks the FAT-style READONLY attribute, and does not look at the ACL of a file at all. This function is this in practise almost useless on Windows. Software that needs to handle file permissions on Windows more exactly should use the Win32 API. See your C library manual for more details about access(). zero if the pathname refers to an existing file system object that has all the tested permissions, or -1 otherwise or on error. a pathname in the GLib file name encoding (UTF-8 on Windows) as in access() This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to align the allocated memory to with the given alignment value. Additionally, it will detect possible overflow during multiplication. If the allocation fails (because the system is out of memory), the program is terminated. Aligned memory allocations returned by this function can only be freed using g_aligned_free_sized() or g_aligned_free(). the allocated memory the number of blocks to allocate the size of each block in bytes the alignment to be enforced, which must be a positive power of 2 and a multiple of `sizeof(void*)` This function is similar to g_aligned_alloc(), but it will also clear the allocated memory before returning it. the allocated, cleared memory the number of blocks to allocate the size of each block in bytes the alignment to be enforced, which must be a positive power of 2 and a multiple of `sizeof(void*)` Frees the memory allocated by g_aligned_alloc(). the memory to deallocate Frees the memory pointed to by @mem, assuming it is has the given @size and @alignment. If @mem is %NULL this is a no-op (and @size is ignored). It is an error if @size doesn’t match the size, or @alignment doesn’t match the alignment, passed when @mem was allocated. @size and @alignment are passed to this function to allow optimizations in the allocator. If you don’t know either of them, use g_aligned_free() instead. the memory to free alignment of @mem size of @mem, in bytes Allocates @size bytes on the stack; these bytes will be freed when the current stack frame is cleaned up. This macro essentially just wraps the alloca() function present on most UNIX variants. Thus it provides the same advantages and pitfalls as alloca(): - alloca() is very fast, as on most systems it's implemented by just adjusting the stack pointer register. - It doesn't cause any memory fragmentation, within its scope, separate alloca() blocks just build up and are released together at function end. - Allocation sizes have to fit into the current stack frame. For instance in a threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes, so be sparse with alloca() uses. - Allocation failure due to insufficient stack space is not indicated with a %NULL return like e.g. with malloc(). Instead, most systems probably handle it the same way as out of stack space situations from infinite function recursion, i.e. with a segmentation fault. - Allowing @size to be specified by an untrusted party would allow for them to trigger a segmentation fault by specifying a large size, leading to a denial of service vulnerability. @size must always be entirely under the control of the program. - Special care has to be taken when mixing alloca() with GNU C variable sized arrays. Stack space allocated with alloca() in the same scope as a variable sized array will be freed together with the variable sized array upon exit of that scope, and not upon exit of the enclosing function scope. number of bytes to allocate. Wraps g_alloca() and initializes allocated memory to zeroes. If @size is `0` it returns %NULL. Note that the @size argument will be evaluated multiple times. number of bytes to allocate. Adds the value on to the end of the array. The array will grow in size automatically if necessary. `g_array_append_val()` is a macro which uses a reference to the value parameter @v. This means that you cannot use it with literal values such as `"27"`. You must use variables. an array the value to append to the #GArray Returns the element of a `GArray` at the given index. The return value is cast to the given type. This is the main way to read or write an element in a `GArray`. Writing an element is typically done by reference, as in the following example. This example gets a pointer to an element in a `GArray`, and then writes to a field in it: ```c EDayViewEvent *event; // This gets a pointer to the 4th element in the array of // EDayViewEvent structs. event = &g_array_index (events, EDayViewEvent, 3); event->start_time = g_get_current_time (); ``` This example reads from and writes to an array of integers: ```c g_autoptr(GArray) int_array = g_array_new (FALSE, FALSE, sizeof (guint)); for (guint i = 0; i < 10; i++) g_array_append_val (int_array, i); guint *my_int = &g_array_index (int_array, guint, 1); g_print ("Int at index 1 is %u; decrementing it\n", *my_int); *my_int = *my_int - 1; ``` an array the type of the elements the index of the element to return Inserts an element into an array at the given index. `g_array_insert_val()` is a macro which uses a reference to the value parameter @v. This means that you cannot use it with literal values such as `"27"`. You must use variables. an array the index to place the element at the value to insert into the array Creates a new `GArray` with @data as array data, @len as length and a reference count of 1. This avoids having to copy the data manually, when it can just be inherited. After this call, @data belongs to the `GArray` and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with [func@GLib.free]. In case the elements need to be cleared when the array is freed, use [func@GLib.Array.set_clear_func] to set a [callback@GLib.DestroyNotify] function to perform such task. Do not use it if @len or @element_size are greater than [`G_MAXUINT`](types.html#guint). `GArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new #GArray an array of elements of @element_size the number of elements in @data if true, `GArray` elements should be automatically cleared to 0 when they are allocated the size of each element in bytes Creates a new `GArray` with @data as array data, computing the length of it and setting the reference count to 1. This avoids having to copy the data manually, when it can just be inherited. After this call, @data belongs to the `GArray` and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with [func@GLib.free]. The length is calculated by iterating through @data until the first `NULL` element is found. In case the elements need to be cleared when the array is freed, use [func@GLib.Array.set_clear_func] to set a [callback@GLib.DestroyNotify] function to perform such task. Do not use it if @data length or @element_size are greater than [`G_MAXUINT`](types.html#guint). `GArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new `GArray` an array of elements of @element_size, `NULL` terminated if true, `GArray` elements should be automatically cleared to 0 when they are allocated the size of each element in bytes Adds the value on to the start of the array. The array will grow in size automatically if necessary. This operation is slower than [func@GLib.array_append_val] since the existing elements in the array have to be moved to make space for the new element. `g_array_prepend_val()` is a macro which uses a reference to the value parameter @v. This means that you cannot use it with literal values such as `"27"`. You must use variables. an array the value to prepend to the #GArray Determines the numeric value of a character as a decimal digit. If the character is not a decimal digit according to [func@GLib.ascii_isdigit], `-1` is returned. Differs from [func@GLib.unichar_digit_value] because it takes a char, so there's no worry about sign extension if characters are signed. the numerical value of @c if it is a decimal digit, `-1` otherwise an ASCII character Converts a `gdouble` to a string, using the '.' as decimal point. This function generates enough precision that converting the string back using [func@GLib.ascii_strtod] gives the same machine-number (on machines with IEEE compatible 64bit doubles). It is guaranteed that the size of the resulting string will never be larger than [const@GLib.ASCII_DTOSTR_BUF_SIZE] bytes, including the terminating nul character, which is always added. the pointer to the buffer with the converted string a buffer to place the resulting string in the length of the buffer the value to convert Converts a `gdouble` to a string, using the '.' as decimal point. To format the number you pass in a `printf()`-style format string. Allowed conversion specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'. The @format must just be a single format specifier starting with `%`, expecting a `gdouble` argument. The returned buffer is guaranteed to be nul-terminated. If you just want to want to serialize the value into a string, use [func@GLib.ascii_dtostr]. the pointer to the buffer with the converted string a buffer to place the resulting string in the length of the buffer the `printf()`-style format to use for the code to use for converting the value to convert Determines whether a character is alphanumeric. Unlike the standard C library `isalnum()` function, this only recognizes standard ASCII letters and ignores the locale, returning false for all non-ASCII characters. Also, unlike the standard library function, this takes a `char`, not an `int`, so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. any character Determines whether a character is alphabetic (i.e. a letter). Unlike the standard C library `isalpha()` function, this only recognizes standard ASCII letters and ignores the locale, returning false for all non-ASCII characters. Also, unlike the standard library function, this takes a `char`, not an `int`, so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. any character Determines whether a character is a control character. Unlike the standard C library `iscntrl()` function, this only recognizes standard ASCII control characters and ignores the locale, returning false for all non-ASCII characters. Also, unlike the standard library function, this takes a `char`, not an `int`, so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. any character Determines whether a character is digit (0-9). Unlike the standard C library `isdigit()` function, this takes a `char`, not an `int`, so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. any character Determines whether a character is a printing character and not a space. Unlike the standard C library `isgraph()` function, this only recognizes standard ASCII characters and ignores the locale, returning false for all non-ASCII characters. Also, unlike the standard library function, this takes a `char`, not an `int`, so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. any character Determines whether a character is an ASCII lower case letter. Unlike the standard C library `islower()` function, this only recognizes standard ASCII letters and ignores the locale, returning false for all non-ASCII characters. Also, unlike the standard library function, this takes a `char`, not an `int`, so don't call it on `EOF`, but no need to worry about casting to `guchar` before passing a possibly non-ASCII character in. any character Determines whether a character is a printing character. Unlike the standard C library `isprint()` function, this only recognizes standard ASCII characters and ignores the locale, returning false for all non-ASCII characters. Also, unlike the standard library function, this takes a `char`, not an `int`, so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. any character Determines whether a character is a punctuation character. Unlike the standard C library `ispunct()` function, this only recognizes standard ASCII letters and ignores the locale, returning false for all non-ASCII characters. Also, unlike the standard library function, this takes a `char`, not an `int`, so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. any character Determines whether a character is a white-space character. Unlike the standard C library `isspace()` function, this only recognizes standard ASCII white-space and ignores the locale, returning false for all non-ASCII characters. Also, unlike the standard library function, this takes a `char`, not an `int`, so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. any character Determines whether a character is an ASCII upper case letter. Unlike the standard C library `isupper()` function, this only recognizes standard ASCII letters and ignores the locale, returning false for all non-ASCII characters. Also, unlike the standard library function, this takes a `char`, not an `int`, so don't call it on `EOF`, but no need to worry about casting to `guchar` before passing a possibly non-ASCII character in. any character Determines whether a character is a hexadecimal-digit character. Unlike the standard C library `isxdigit()` function, this takes a `char`, not an `int`, so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. any character Compare two strings, ignoring the case of ASCII characters. Unlike the BSD `strcasecmp()` function, this only recognizes standard ASCII letters and ignores the locale, treating all non-ASCII bytes as if they are not letters. This function should be used only on strings that are known to be in encodings where the bytes corresponding to ASCII letters always represent themselves. This includes UTF-8 and the ISO-8859-* charsets, but not for instance double-byte encodings like the Windows Codepage 932, where the trailing bytes of double-byte characters include all ASCII letters. If you compare two CP932 strings using this function, you will get false matches. Both @s1 and @s2 must be non-`NULL`. 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2 string to compare with @s2 string to compare with @s1 Converts all upper case ASCII letters to lower case ASCII letters, with semantics that exactly match [func@GLib.ascii_tolower]. a newly-allocated string, with all the upper case characters in @str converted to lower case. (Note that this is unlike the old [func@GLib.strdown], which modified the string in place.) a string length of @str in bytes, or `-1` if @str is nul-terminated A convenience function for converting a string to a signed number. This function assumes that @str contains only a number of the given @base that is within inclusive bounds limited by @min and @max. If this is true, then the converted number is stored in @out_num. An empty string is not a valid input. A string with leading or trailing whitespace is also an invalid input. @base can be between 2 and 36 inclusive. Hexadecimal numbers must not be prefixed with "0x" or "0X". Such a problem does not exist for octal numbers, since they were usually prefixed with a zero which does not change the value of the parsed number. Parsing failures result in an error with the `G_NUMBER_PARSER_ERROR` domain. If the input is invalid, the error code will be [error@GLib.NumberParserError.INVALID]. If the parsed number is out of bounds - [error@GLib.NumberParserError.OUT_OF_BOUNDS]. See [func@GLib.ascii_strtoll] if you have more complex needs such as parsing a string which starts with a number, but then has other characters. true if @str was a number, false otherwise a string to convert base of a parsed number a lower bound (inclusive) an upper bound (inclusive) a return location for a number A convenience function for converting a string to an unsigned number. This function assumes that @str contains only a number of the given @base that is within inclusive bounds limited by @min and @max. If this is true, then the converted number is stored in @out_num. An empty string is not a valid input. A string with leading or trailing whitespace is also an invalid input. A string with a leading sign (`-` or `+`) is not a valid input for the unsigned parser. @base can be between 2 and 36 inclusive. Hexadecimal numbers must not be prefixed with "0x" or "0X". Such a problem does not exist for octal numbers, since they were usually prefixed with a zero which does not change the value of the parsed number. Parsing failures result in an error with the `G_NUMBER_PARSER_ERROR` domain. If the input is invalid, the error code will be [error@GLib.NumberParserError.INVALID]. If the parsed number is out of bounds - [error@GLib.NumberParserError.OUT_OF_BOUNDS]. See [func@GLib.ascii_strtoull] if you have more complex needs such as parsing a string which starts with a number, but then has other characters. true if @str was a number, false otherwise a string base of a parsed number a lower bound (inclusive) an upper bound (inclusive) a return location for a number Compare @s1 and @s2, ignoring the case of ASCII characters and any characters after the first @n in each string. If either string is less than @n bytes long, comparison will stop at the first nul byte encountered. Unlike the BSD `strncasecmp()` function, this only recognizes standard ASCII letters and ignores the locale, treating all non-ASCII characters as if they are not letters. The same warning as in [func@GLib.ascii_strcasecmp] applies: Use this function only on strings known to be in encodings where bytes corresponding to ASCII letters always represent themselves. 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2 string to compare with @s2 string to compare with @s1 number of characters to compare Converts a string to a floating point value. This function behaves like the standard `strtod()` function does in the C locale. It does this without actually changing the current locale, since that would not be thread-safe. A limitation of the implementation is that this function will still accept localized versions of infinities and NANs. This function is typically used when reading configuration files or other non-user input that should be locale independent. To handle input from the user you should normally use the locale-sensitive system `strtod()` function. To convert from a gdouble to a string in a locale-insensitive way, use [func@GLib.ascii_dtostr]. If the correct value would cause overflow, plus or minus `HUGE_VAL` is returned (according to the sign of the value), and `ERANGE` is stored in `errno`. If the correct value would cause underflow, zero is returned and `ERANGE` is stored in `errno`. This function resets `errno` before calling `strtod()` so that you can reliably detect overflow and underflow. the converted value the string to convert to a numeric value if non-`NULL`, it returns the character after the last character used in the conversion Converts a string to a `gint64` value. This function behaves like the standard `strtoll()` function does in the C locale. It does this without actually changing the current locale, since that would not be thread-safe. This function is typically used when reading configuration files or other non-user input that should be locale independent. To handle input from the user you should normally use the locale-sensitive system `strtoll()` function. If the correct value would cause overflow, [const@GLib.MAXINT64] or [const@GLib.MININT64] is returned, and `ERANGE` is stored in `errno`. If the base is outside the valid range, zero is returned, and `EINVAL` is stored in `errno`. If the string conversion fails, zero is returned, and @endptr returns @nptr (if @endptr is non-`NULL`). the converted value, or zero on error the string to convert to a numeric value if non-`NULL`, it returns the character after the last character used in the conversion to be used for the conversion, 2..36 or 0 Converts a string to a `guint64` value. This function behaves like the standard `strtoull()` function does in the C locale. It does this without actually changing the current locale, since that would not be thread-safe. Note that input with a leading minus sign (`-`) is accepted, and will return the negation of the parsed number, unless that would overflow a `guint64`. Critically, this means you cannot assume that a short fixed length input will result in a low return value, as the input could have a leading `-`. This function is typically used when reading configuration files or other non-user input that should be locale independent. To handle input from the user you should normally use the locale-sensitive system `strtoull()` function. If the correct value would cause overflow, [const@GLib.MAXUINT64] is returned, and `ERANGE` is stored in `errno`. If the base is outside the valid range, zero is returned, and `EINVAL` is stored in `errno`. If the string conversion fails, zero is returned, and @endptr returns @nptr (if @endptr is non-`NULL`). the converted value, or zero on error the string to convert to a numeric value if non-`NULL`, it returns the character after the last character used in the conversion to be used for the conversion, 2..36 or 0 Converts all lower case ASCII letters to upper case ASCII letters, with semantics that exactly match [func@GLib.ascii_toupper]. a newly-allocated string, with all the lower case characters in @str converted to upper case. (Note that this is unlike the old [func@GLib.strup], which modified the string in place.) a string length of @str in bytes, or `-1` if @str is nul-terminated Convert a character to ASCII lower case. If the character is not an ASCII upper case letter, it is returned unchanged. Unlike the standard C library `tolower()` function, this only recognizes standard ASCII letters and ignores the locale, returning all non-ASCII characters unchanged, even if they are lower case letters in a particular character set. Also unlike the standard library function, this takes and returns a char, not an int, so don't call it on `EOF` but no need to worry about casting to `guchar` before passing a possibly non-ASCII character in. the result of the conversion any character Convert a character to ASCII upper case. If the character is not an ASCII lower case letter, it is returned unchanged. Unlike the standard C library `toupper()` function, this only recognizes standard ASCII letters and ignores the locale, returning all non-ASCII characters unchanged, even if they are upper case letters in a particular character set. Also unlike the standard library function, this takes and returns a char, not an int, so don't call it on `EOF` but no need to worry about casting to `guchar` before passing a possibly non-ASCII character in. the result of the conversion any character Determines the numeric value of a character as a hexadecimal digit. If the character is not a hex digit according to [func@GLib.ascii_isxdigit], `-1` is returned. Differs from [func@GLib.unichar_xdigit_value] because it takes a char, so there's no worry about sign extension if characters are signed. Differs from [func@GLib.unichar_xdigit_value] because it takes a char, so there's no worry about sign extension if characters are signed. the numerical value of @c if it is a hex digit, `-1` otherwise an ASCII character Debugging macro to terminate the application if the assertion fails. If the assertion fails (i.e. the expression is not true), an error message is logged and the application is terminated. The macro can be turned off in final releases of code by defining `G_DISABLE_ASSERT` when compiling the application, so code must not depend on any side effects from @expr. Similarly, it must not be used in unit tests, otherwise the unit tests will be ineffective if compiled with `G_DISABLE_ASSERT`. Use [func@GLib.assert_true] and related macros in unit tests instead. the expression to check Debugging macro to compare two floating point numbers. The effect of `g_assert_cmpfloat (n1, op, n2)` is the same as `g_assert_true (n1 op n2)`. The advantage of this macro is that it can produce a message that includes the actual values of @n1 and @n2. a floating point number the comparison operator to use. One of `==`, `!=`, `<`, `>`, `<=`, `>=` another floating point number Debugging macro to compare two floating point numbers within an epsilon. The effect of `g_assert_cmpfloat_with_epsilon (n1, n2, epsilon)` is the same as `g_assert_true (abs (n1 - n2) < epsilon)`. The advantage of this macro is that it can produce a message that includes the actual values of @n1 and @n2. a floating point number another floating point number a numeric value that expresses the expected tolerance between @n1 and @n2 Debugging macro to compare to unsigned integers. This is a variant of [func@GLib.assert_cmpuint] that displays the numbers in hexadecimal notation in the message. an unsigned integer the comparison operator to use. One of `==`, `!=`, `<`, `>`, `<=`, `>=` another unsigned integer Debugging macro to compare two integers. The effect of `g_assert_cmpint (n1, op, n2)` is the same as `g_assert_true (n1 op n2)`. The advantage of this macro is that it can produce a message that includes the actual values of @n1 and @n2. an integer the comparison operator to use. One of `==`, `!=`, `<`, `>`, `<=`, `>=` another integer Debugging macro to compare memory regions. If the comparison fails, an error message is logged and the application is either terminated or the testcase marked as failed. The effect of `g_assert_cmpmem (m1, l1, m2, l2)` is the same as `g_assert_true (l1 == l2 && memcmp (m1, m2, l1) == 0)`. The advantage of this macro is that it can produce a message that includes the actual values of @l1 and @l2. @m1 may be `NULL` if (and only if) @l1 is zero; similarly for @m2 and @l2. ```c g_assert_cmpmem (buf->data, buf->len, expected, sizeof (expected)); ``` pointer to a buffer length of @m1 in bytes pointer to another buffer length of @m2 in bytes Debugging macro to compare two strings. If the comparison fails, an error message is logged and the application is either terminated or the testcase marked as failed. The strings are compared using [GLib.strcmp0]. The effect of `g_assert_cmpstr (s1, op, s2)` is the same as `g_assert_true (g_strcmp0 (s1, s2) op 0)`. The advantage of this macro is that it can produce a message that includes the actual values of @s1 and @s2. ```c g_assert_cmpstr (mystring, ==, "fubar"); ``` a string the comparison operator to use. One of `==`, `!=`, `<`, `>`, `<=`, `>=` another string Debugging macro to check if two `NULL`-terminated string arrays (i.e. 2 `GStrv`) are equal. If they are not equal, an error message is logged and the application is either terminated or the testcase marked as failed. If both arrays are `NULL`, the check passes. If one array is `NULL` but the other is not, an error message is logged. The effect of `g_assert_cmpstrv (strv1, strv2)` is the same as `g_assert_true (g_strv_equal (strv1, strv2))` (if both arrays are not `NULL`). The advantage of this macro is that it can produce a message that includes how @strv1 and @strv2 are different. ```c const char *expected[] = { "one", "two", "three", NULL }; g_assert_cmpstrv (mystrv, expected); ``` a string array another string array Debugging macro to compare two unsigned integers. The effect of `g_assert_cmpuint (n1, op, n2)` is the same as `g_assert_true (n1 op n2)`. The advantage of this macro is that it can produce a message that includes the actual values of @n1 and @n2. an unsigned integer the comparison operator to use. One of `==`, `!=`, `<`, `>`, `<=`, `>=` another unsigned integer Debugging macro to compare two [struct@GLib.Variant] values. If the comparison fails, an error message is logged and the application is either terminated or the testcase marked as failed. The variants are compared using [method@GLib.Variant.equal]. The effect of `g_assert_cmpvariant (v1, v2)` is the same as `g_assert_true (g_variant_equal (v1, v2))`. The advantage of this macro is that it can produce a message that includes the actual values of @v1 and @v2. pointer to a `GVariant` pointer to another `GVariant` Debugging macro to check that a method has returned the correct [struct@GLib.Error]. The effect of `g_assert_error (err, dom, c)` is the same as `g_assert_true (err != NULL && err->domain == dom && err->code == c)`. The advantage of this macro is that it can produce a message that includes the incorrect error message and code. This can only be used to test for a specific error. If you want to test that @err is set, but don't care what it's set to, just use `g_assert_nonnull (err)`. a `GError` the expected error domain (a `GQuark`) the expected error code Debugging macro to check an expression is false. If the assertion fails (i.e. the expression is not false), an error message is logged and the application is either terminated or the testcase marked as failed. Note that unlike [func@GLib.assert], this macro is unaffected by whether `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, conversely, [func@GLib.assert] should not be used in tests. See [func@GLib.test_set_nonfatal_assertions]. the expression to check Debugging macro to check that an expression has a non-negative return value, as used by traditional POSIX functions (such as `rmdir()`) to indicate success. If the assertion fails (i.e. the @expr returns a negative value), an error message is logged and the testcase is marked as failed. The error message will contain the value of `errno` and its human-readable message from [func@GLib.strerror]. This macro will clear the value of `errno` before executing @expr. the expression to check Debugging macro to check that a [struct@GLib.Error] is not set. The effect of `g_assert_no_error (err)` is the same as `g_assert_true (err == NULL)`. The advantage of this macro is that it can produce a message that includes the error message and code. a `GError` Debugging macro to check an expression is not `NULL`. If the assertion fails (i.e. the expression is `NULL`), an error message is logged and the application is either terminated or the testcase marked as failed. Note that unlike [func@GLib.assert], this macro is unaffected by whether `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, conversely, [func@GLib.assert] should not be used in tests. See [func@GLib.test_set_nonfatal_assertions]. the expression to check Debugging macro to terminate the application if it is ever reached. If it is reached, an error message is logged and the application is terminated. The macro can be turned off in final releases of code by defining `G_DISABLE_ASSERT` when compiling the application. Hence, it should not be used in unit tests, where assertions should always be effective. Debugging macro to check an expression is `NULL`. If the assertion fails (i.e. the expression is not `NULL`), an error message is logged and the application is either terminated or the testcase marked as failed. Note that unlike [func@GLib.assert], this macro is unaffected by whether `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, conversely, [func@GLib.assert] should not be used in tests. See [func@GLib.test_set_nonfatal_assertions]. the expression to check Debugging macro to check that an expression is true. If the assertion fails (i.e. the expression is not true), an error message is logged and the application is either terminated or the testcase marked as failed. Note that unlike [func@GLib.assert], this macro is unaffected by whether `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, conversely, [func@GLib.assert] should not be used in tests. See [func@GLib.test_set_nonfatal_assertions]. the expression to check Internal function used to print messages from the public g_assert() and g_assert_not_reached() macros. log domain file containing the assertion line number of the assertion function containing the assertion expression which failed Creates a new asynchronous queue. a new #GAsyncQueue. Free with g_async_queue_unref() Creates a new asynchronous queue and sets up a destroy notify function that is used to free any remaining queue items when the queue is destroyed after the final unref. a new #GAsyncQueue. Free with g_async_queue_unref() function to free queue elements Specifies a function to be called at normal program termination. Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor macro that maps to a call to the atexit() function in the C library. This means that in case the code that calls g_atexit(), i.e. atexit(), is in a DLL, the function will be called when the DLL is detached from the program. This typically makes more sense than that the function is called when the GLib DLL is detached, which happened earlier when g_atexit() was a function in the GLib DLL. The behaviour of atexit() in the context of dynamically loaded modules is not formally specified and varies wildly. On POSIX systems, calling g_atexit() (or atexit()) in a dynamically loaded module which is unloaded before the program terminates might well cause a crash at program exit. Some POSIX systems implement atexit() like Windows, and have each dynamically loaded module maintain an own atexit chain that is called when the module is unloaded. On other POSIX systems, before a dynamically loaded module is unloaded, the registered atexit functions (if any) residing in that module are called, regardless where the code that registered them resided. This is presumably the most robust approach. As can be seen from the above, for portability it's best to avoid calling g_atexit() (or atexit()) except in the main executable of a program. It is best to avoid g_atexit(). the function to call on normal program termination. Atomically adds @val to the value of @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic += val; return tmp; }`. This call acts as a full compiler and hardware memory barrier. Before version 2.30, this function did not return a value (but g_atomic_int_exchange_and_add() did, and had the same meaning). While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. the value of @atomic before the add, signed a pointer to a #gint or #guint the value to add Performs an atomic bitwise 'and' of the value of @atomic and @val, storing the result back in @atomic. This call acts as a full compiler and hardware memory barrier. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic &= val; return tmp; }`. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. the value of @atomic before the operation, unsigned a pointer to a #gint or #guint the value to 'and' Compares @atomic to @oldval and, if equal, sets it to @newval. If @atomic was not equal to @oldval then no change occurs. This compare and exchange is done atomically. Think of this operation as an atomic version of `{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. %TRUE if the exchange took place a pointer to a #gint or #guint the value to compare with the value to conditionally replace with Compares @atomic to @oldval and, if equal, sets it to @newval. If @atomic was not equal to @oldval then no change occurs. In any case the value of @atomic before this operation is stored in @preval. This compare and exchange is done atomically. Think of this operation as an atomic version of `{ *preval = *atomic; if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. This call acts as a full compiler and hardware memory barrier. See also g_atomic_int_compare_and_exchange() %TRUE if the exchange took place a pointer to a #gint or #guint the value to compare with the value to conditionally replace with the contents of @atomic before this operation Decrements the value of @atomic by 1. Think of this operation as an atomic version of `{ *atomic -= 1; return (*atomic == 0); }`. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. %TRUE if the resultant value is zero a pointer to a #gint or #guint Sets the @atomic to @newval and returns the old value from @atomic. This exchange is done atomically. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic = val; return tmp; }`. This call acts as a full compiler and hardware memory barrier. the value of @atomic before the exchange, signed a pointer to a #gint or #guint the value to replace with This function existed before g_atomic_int_add() returned the prior value of the integer (which it now does). It is retained only for compatibility reasons. Don't use this function in new code. Use g_atomic_int_add() instead. the value of @atomic before the add, signed a pointer to a #gint the value to add Gets the current value of @atomic. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. the value of the integer a pointer to a #gint or #guint Increments the value of @atomic by 1. Think of this operation as an atomic version of `{ *atomic += 1; }`. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. a pointer to a #gint or #guint Performs an atomic bitwise 'or' of the value of @atomic and @val, storing the result back in @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic |= val; return tmp; }`. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. the value of @atomic before the operation, unsigned a pointer to a #gint or #guint the value to 'or' Sets the value of @atomic to @newval. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. a pointer to a #gint or #guint a new value to store Performs an atomic bitwise 'xor' of the value of @atomic and @val, storing the result back in @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic ^= val; return tmp; }`. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. the value of @atomic before the operation, unsigned a pointer to a #gint or #guint the value to 'xor' Atomically adds @val to the value of @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic += val; return tmp; }`. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. In GLib 2.80, the return type was changed from #gssize to #gintptr to add support for platforms with 128-bit pointers. This should not affect existing code. the value of @atomic before the add, signed a pointer to a #gpointer-sized value the value to add Performs an atomic bitwise 'and' of the value of @atomic and @val, storing the result back in @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic &= val; return tmp; }`. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. In GLib 2.80, the return type was changed from #gsize to #guintptr to add support for platforms with 128-bit pointers. This should not affect existing code. the value of @atomic before the operation, unsigned a pointer to a #gpointer-sized value the value to 'and' Compares @atomic to @oldval and, if equal, sets it to @newval. If @atomic was not equal to @oldval then no change occurs. This compare and exchange is done atomically. Think of this operation as an atomic version of `{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. %TRUE if the exchange took place a pointer to a #gpointer-sized value the value to compare with the value to conditionally replace with Compares @atomic to @oldval and, if equal, sets it to @newval. If @atomic was not equal to @oldval then no change occurs. In any case the value of @atomic before this operation is stored in @preval. This compare and exchange is done atomically. Think of this operation as an atomic version of `{ *preval = *atomic; if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. This call acts as a full compiler and hardware memory barrier. See also g_atomic_pointer_compare_and_exchange() %TRUE if the exchange took place a pointer to a #gpointer-sized value the value to compare with the value to conditionally replace with the contents of @atomic before this operation Sets the @atomic to @newval and returns the old value from @atomic. This exchange is done atomically. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic = val; return tmp; }`. This call acts as a full compiler and hardware memory barrier. the value of @atomic before the exchange a pointer to a #gpointer-sized value the value to replace with Gets the current value of @atomic. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. the value of the pointer a pointer to a #gpointer-sized value Performs an atomic bitwise 'or' of the value of @atomic and @val, storing the result back in @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic |= val; return tmp; }`. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. In GLib 2.80, the return type was changed from #gsize to #guintptr to add support for platforms with 128-bit pointers. This should not affect existing code. the value of @atomic before the operation, unsigned a pointer to a #gpointer-sized value the value to 'or' Sets the value of @atomic to @newval. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. a pointer to a #gpointer-sized value a new value to store Performs an atomic bitwise 'xor' of the value of @atomic and @val, storing the result back in @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic ^= val; return tmp; }`. This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. In GLib 2.80, the return type was changed from #gsize to #guintptr to add support for platforms with 128-bit pointers. This should not affect existing code. the value of @atomic before the operation, unsigned a pointer to a #gpointer-sized value the value to 'xor' Atomically acquires a reference on the data pointed by @mem_block. a pointer to the data, with its reference count increased a pointer to reference counted data Allocates @block_size bytes of memory, and adds atomic reference counting semantics to it. The data will be freed when its reference count drops to zero. The allocated data is guaranteed to be suitably aligned for any built-in type. a pointer to the allocated memory the size of the allocation, must be greater than 0 Allocates @block_size bytes of memory, and adds atomic reference counting semantics to it. The contents of the returned data is set to zero. The data will be freed when its reference count drops to zero. The allocated data is guaranteed to be suitably aligned for any built-in type. a pointer to the allocated memory the size of the allocation, must be greater than 0 Allocates a new block of data with atomic reference counting semantics, and copies @block_size bytes of @mem_block into it. a pointer to the allocated memory the number of bytes to copy, must be greater than 0 the memory to copy Retrieves the size of the reference counted data pointed by @mem_block. the size of the data, in bytes a pointer to reference counted data A convenience macro to allocate atomically reference counted data with the size of the given @type. This macro calls g_atomic_rc_box_alloc() with `sizeof (@type)` and casts the returned pointer to a pointer of the given @type, avoiding a type cast in the source code. the type to allocate, typically a structure name A convenience macro to allocate atomically reference counted data with the size of the given @type, and set its contents to zero. This macro calls g_atomic_rc_box_alloc0() with `sizeof (@type)` and casts the returned pointer to a pointer of the given @type, avoiding a type cast in the source code. the type to allocate, typically a structure name Atomically releases a reference on the data pointed by @mem_block. If the reference was the last one, it will free the resources allocated for @mem_block. a pointer to reference counted data Atomically releases a reference on the data pointed by @mem_block. If the reference was the last one, it will call @clear_func to clear the contents of @mem_block, and then will free the resources allocated for @mem_block. Note that implementing weak references via @clear_func is not thread-safe: clearing a pointer to the memory from the callback can race with another thread trying to access it as @mem_block already has a reference count of 0 when the callback is called and will be freed. a pointer to reference counted data a function to call when clearing the data Atomically compares the current value of @arc with @val. %TRUE if the reference count is the same as the given value the address of an atomic reference count variable the value to compare Atomically decreases the reference count. If %TRUE is returned, the reference count reached 0. After this point, @arc is an undefined state and must be reinitialized with g_atomic_ref_count_init() to be used again. %TRUE if the reference count reached 0, and %FALSE otherwise the address of an atomic reference count variable Atomically increases the reference count. the address of an atomic reference count variable Initializes a reference count variable to 1. the address of an atomic reference count variable Decode a sequence of Base-64 encoded text into binary data. Note that the returned binary data is not necessarily zero-terminated, so it should not be used as a character string. newly allocated buffer containing the binary data that @text represents. The returned buffer must be freed with g_free(). zero-terminated string with base64 text to decode The length of the decoded data is written here Decode a sequence of Base-64 encoded text into binary data by overwriting the input data. The binary data that @text responds. This pointer is the same as the input @text. zero-terminated string with base64 text to decode The length of the decoded data is written here Incrementally decode a sequence of binary data from its Base-64 stringified representation. By calling this function multiple times you can convert data in chunks to avoid having to have the full encoded data in memory. The output buffer must be large enough to fit all the data that will be written to it. Since base64 encodes 3 bytes in 4 chars you need at least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero state). The number of bytes of output that was written binary input data max length of @in data to decode output buffer Saved state between steps, initialize to 0 Saved state between steps, initialize to 0 Encode a sequence of binary data into its Base-64 stringified representation. a newly allocated, zero-terminated Base-64 encoded string representing @data. The returned string must be freed with g_free(). the binary data to encode the length of @data Flush the status from a sequence of calls to g_base64_encode_step(). The output buffer must be large enough to fit all the data that will be written to it. It will need up to 4 bytes, or up to 5 bytes if line-breaking is enabled. The @out array will not be automatically nul-terminated. The number of bytes of output that was written whether to break long lines pointer to destination buffer Saved state from g_base64_encode_step() Saved state from g_base64_encode_step() Incrementally encode a sequence of binary data into its Base-64 stringified representation. By calling this function multiple times you can convert data in chunks to avoid having to have the full encoded data in memory. When all of the data has been converted you must call g_base64_encode_close() to flush the saved state. The output buffer must be large enough to fit all the data that will be written to it. Due to the way base64 encodes you will need at least: (@len / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of non-zero state). If you enable line-breaking you will need at least: ((@len / 3 + 1) * 4 + 4) / 76 + 1 bytes of extra space. @break_lines is typically used when putting base64-encoded data in emails. It breaks the lines at 76 columns instead of putting all of the text on the same line. This avoids problems with long lines in the email system. Note however that it breaks the lines with `LF` characters, not `CR LF` sequences, so the result cannot be passed directly to SMTP or certain other protocols. The number of bytes of output that was written the binary data to encode the length of @in whether to break long lines pointer to destination buffer Saved state between steps, initialize to 0 Saved state between steps, initialize to 0 Gets the name of the file without any leading directory components. It returns a pointer into the given file name string. Use g_path_get_basename() instead, but notice that g_path_get_basename() allocates new memory for the returned string, unlike this function which returns a pointer into the argument. the name of the file without any leading directory components the name of the file Sets the indicated @lock_bit in @address. If the bit is already set, this call will block until g_bit_unlock() unsets the corresponding bit. Attempting to lock on two different bits within the same integer is not supported and will very probably cause deadlocks. The value of the bit that is set is (1u << @bit). If @bit is not between 0 and 31 then the result is undefined. This function accesses @address atomically. All other accesses to @address must be atomic in order for this function to work reliably. While @address has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. a pointer to an integer a bit value between 0 and 31 Sets the indicated @lock_bit in @address and atomically returns the new value. This is like [func@GLib.bit_lock], except it can atomically return the new value at @address (right after obtaining the lock). Thus the value returned in @out_val always has the @lock_bit set. a pointer to an integer a bit value between 0 and 31 return location for the new value of the integer Find the position of the first bit set in @mask, searching from (but not including) @nth_bit upwards. Bits are numbered from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the 0th bit, set @nth_bit to -1. the index of the first bit set which is higher than @nth_bit, or -1 if no higher bits are set a #gulong containing flags the index of the bit to start the search from Find the position of the first bit set in @mask, searching from (but not including) @nth_bit downwards. Bits are numbered from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the last bit, set @nth_bit to -1 or GLIB_SIZEOF_LONG * 8. the index of the first bit set which is lower than @nth_bit, or -1 if no lower bits are set a #gulong containing flags the index of the bit to start the search from Gets the number of bits used to hold @number, e.g. if @number is 4, 3 bits are needed. the number of bits used to hold @number a #guint Sets the indicated @lock_bit in @address, returning %TRUE if successful. If the bit is already set, returns %FALSE immediately. Attempting to lock on two different bits within the same integer is not supported. The value of the bit that is set is (1u << @bit). If @bit is not between 0 and 31 then the result is undefined. This function accesses @address atomically. All other accesses to @address must be atomic in order for this function to work reliably. While @address has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. %TRUE if the lock was acquired a pointer to an integer a bit value between 0 and 31 Clears the indicated @lock_bit in @address. If another thread is currently blocked in g_bit_lock() on this same bit then it will be woken up. This function accesses @address atomically. All other accesses to @address must be atomic in order for this function to work reliably. While @address has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. a pointer to an integer a bit value between 0 and 31 This is like [func@GLib.bit_unlock] but also atomically sets @address to @val. If @preserve_mask is not zero, then the @preserve_mask bits will be preserved in @address and are not set to @val. Note that the @lock_bit bit will always be unset regardless of @val, @preserve_mask and the currently set value in @address. a pointer to an integer a bit value between 0 and 31 the new value to set mask for bits from @address to preserve Creates a filename from a series of elements using the correct separator for the current platform. On Unix, this function behaves identically to `g_build_path (G_DIR_SEPARATOR_S, first_element, ....)`. On Windows, it takes into account that either the backslash (`\` or slash (`/`) can be used as separator in filenames, but otherwise behaves as on UNIX. When file pathname separators need to be inserted, the one that last previously occurred in the parameters (reading from left to right) is used. No attempt is made to force the resulting filename to be an absolute path. If the first element is a relative path, the result will be a relative path. If you are building a path programmatically you may want to use #GPathBuf instead. the newly allocated path the first element in the path remaining elements in path, terminated by %NULL Creates a filename from a list of elements using the correct separator for the current platform. Behaves exactly like g_build_filename(), but takes the path elements as a va_list. This function is mainly meant for implementing other variadic arguments functions. the newly allocated path the first element in the path va_list of remaining elements in path Creates a filename from a vector of elements using the correct separator for the current platform. This function behaves exactly like g_build_filename(), but takes the path elements as a string array, instead of varargs. This function is mainly meant for language bindings. If you are building a path programmatically you may want to use #GPathBuf instead. the newly allocated path %NULL-terminated array of strings containing the path elements. Creates a path from a series of elements using @separator as the separator between elements. At the boundary between two elements, any trailing occurrences of separator in the first element, or leading occurrences of separator in the second element are removed and exactly one copy of the separator is inserted. Empty elements are ignored. The number of leading copies of the separator on the result is the same as the number of leading copies of the separator on the first non-empty element. The number of trailing copies of the separator on the result is the same as the number of trailing copies of the separator on the last non-empty element. (Determination of the number of trailing copies is done without stripping leading copies, so if the separator is `ABA`, then `ABABA` has 1 trailing copy.) However, if there is only a single non-empty element, and there are no characters in that element not part of the leading or trailing separators, then the result is exactly the original value of that element. Other than for determination of the number of leading and trailing copies of the separator, elements consisting only of copies of the separator are ignored. the newly allocated path a string used to separate the elements of the path. the first element in the path remaining elements in path, terminated by %NULL Behaves exactly like g_build_path(), but takes the path elements as a string array, instead of variadic arguments. This function is mainly meant for language bindings. a newly-allocated string that must be freed with g_free(). a string used to separate the elements of the path. %NULL-terminated array of strings containing the path elements. Adds the given bytes to the end of the `GByteArray`. The array will grow in size automatically if necessary. The `GByteArray` a byte array the byte data to be added the number of bytes to add Frees the memory allocated by the `GByteArray`. If @free_segment is true it frees the actual byte data. If the reference count of @array is greater than one, the `GByteArray` wrapper is preserved but the size of @array will be set to zero. The allocated element data if @free_segment is false, otherwise `NULL`. a byte array if true, the actual byte data is freed as well Transfers the data from the `GByteArray` into a new immutable [struct@GLib.Bytes]. The `GByteArray` is freed unless the reference count of @array is greater than one, in which the `GByteArray` wrapper is preserved but the size of @array will be set to zero. This is identical to using [ctor@GLib.Bytes.new_take] and [func@GLib.ByteArray.free] together. The new immutable [struct@GLib.Bytes] representing same byte data that was in the array a byte array Creates a new `GByteArray` with a reference count of 1. The new `GByteArray` Creates a byte array containing the @data. After this call, @data belongs to the `GByteArray` and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with [func@GLib.free]. Do not use it if @len is greater than [`G_MAXUINT`](types.html#guint). `GByteArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new `GByteArray` the byte data for the array the length of @data Adds the given data to the start of the `GByteArray`. The array will grow in size automatically if necessary. The `GByteArray` a byte array the byte data to be added the number of bytes to add Atomically increments the reference count of @array by one. This function is thread-safe and may be called from any thread. The passed in `GByteArray` a byte array Removes the byte at the given index from a `GByteArray`. The following bytes are moved down one place. The `GByteArray` a byte array the index of the byte to remove Removes the byte at the given index from a `GByteArray`. The last element in the array is used to fill in the space, so this function does not preserve the order of the `GByteArray`. But it is faster than [func@GLib.ByteArray.remove_index]. The `GByteArray` a byte array the index of the byte to remove Removes the given number of bytes starting at the given index from a `GByteArray`. The following elements are moved to close the gap. The `GByteArray` a byte array the index of the first byte to remove the number of bytes to remove Sets the size of the `GByteArray`, expanding it if necessary. The `GByteArray` a byte array the new size of the `GByteArray` Creates a new `GByteArray` with @reserved_size bytes preallocated. This avoids frequent reallocation, if you are going to add many bytes to the array. Note however that the size of the array is still 0. The new `GByteArray` the number of bytes preallocated Sorts a byte array, using @compare_func which should be a `qsort()`-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater than zero if first arg is greater than second arg). If two array elements compare equal, their order in the sorted array is undefined. If you want equal elements to keep their order (i.e. you want a stable sort) you can write a comparison function that, if two elements would otherwise compare equal, compares them by their addresses. a byte array the comparison function Like [func@GLib.ByteArray.sort], but the comparison function takes an extra user data argument. a byte array the comparison function the data to pass to @compare_func Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller. The allocated element data a byte array the pointer to retrieve the number of elements of the original array Atomically decrements the reference count of @array by one. If the reference count drops to 0, all memory allocated by the array is released. This function is thread-safe and may be called from any thread. a byte array Gets the canonical file name from @filename. All triple slashes are turned into single slashes, and all `..` and `.`s resolved against @relative_to. Symlinks are not followed, and the returned path is guaranteed to be absolute. If @filename is an absolute path, @relative_to is ignored. Otherwise, @relative_to will be prepended to @filename to make it absolute. @relative_to must be an absolute path, or %NULL. If @relative_to is %NULL, it'll fallback to g_get_current_dir(). This function never fails, and will canonicalize file paths even if they don't exist. No file system I/O is done. a newly allocated string with the canonical file path the name of the file the relative directory, or %NULL to use the current working directory A wrapper for the POSIX chdir() function. The function changes the current directory of the process to @path. See your C library manual for more details about chdir(). 0 on success, -1 if an error occurred. a pathname in the GLib file name encoding (UTF-8 on Windows) Checks that the GLib library in use is compatible with the given version. Generally you would pass in the constants %GLIB_MAJOR_VERSION, %GLIB_MINOR_VERSION, %GLIB_MICRO_VERSION as the three arguments to this function; that produces a check that the library in use is compatible with the version of GLib the application or module was compiled against. Compatibility is defined by two things: first the version of the running library is newer than the version `@required_major.required_minor.@required_micro`. Second the running library must be binary compatible with the version `@required_major.@required_minor.@required_micro` (same major version.) %NULL if the GLib library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by GLib and must not be modified or freed. the required major version the required minor version the required micro version Gets the length in bytes of digests of type @checksum_type the checksum length, or -1 if @checksum_type is not supported. a #GChecksumType Sets a function to be called when the child indicated by @pid exits, at a default priority, [const@GLib.PRIORITY_DEFAULT]. If you obtain @pid from [func@GLib.spawn_async] or [func@GLib.spawn_async_with_pipes] you will need to pass [flags@GLib.SpawnFlags.DO_NOT_REAP_CHILD] as a flag to the spawn function for the child watching to work. Note that on platforms where [type@GLib.Pid] must be explicitly closed (see [func@GLib.spawn_close_pid]) @pid must not be closed while the source is still active. Typically, you will want to call [func@GLib.spawn_close_pid] in the callback function for the source. GLib supports only a single callback per process ID. On POSIX platforms, the same restrictions mentioned for [func@GLib.child_watch_source_new] apply to this function. This internally creates a main loop source using [func@GLib.child_watch_source_new] and attaches it to the main loop context using [method@GLib.Source.attach]. You can do these steps manually if you need greater control. the ID (greater than 0) of the event source process to watch — on POSIX systems, this is the positive PID of a child process; on Windows it is a handle for a process (which doesn’t have to be a child) function to call data to pass to @function Sets a function to be called when the child indicated by @pid exits, at the priority @priority. If you obtain @pid from [func@GLib.spawn_async] or [func@GLib.spawn_async_with_pipes] you will need to pass [flags@GLib.SpawnFlags.DO_NOT_REAP_CHILD] as a flag to the spawn function for the child watching to work. In many programs, you will want to call [func@GLib.spawn_check_wait_status] in the callback to determine whether or not the child exited successfully. Also, note that on platforms where [type@GLib.Pid] must be explicitly closed (see [func@GLib.spawn_close_pid]) @pid must not be closed while the source is still active. Typically, you should invoke [func@GLib.spawn_close_pid] in the callback function for the source. GLib supports only a single callback per process ID. On POSIX platforms, the same restrictions mentioned for [func@GLib.child_watch_source_new] apply to this function. This internally creates a main loop source using [func@GLib.child_watch_source_new] and attaches it to the main loop context using [method@GLib.Source.attach]. You can do these steps manually if you need greater control. the ID (greater than 0) of the event source the priority of the idle source; typically this will be in the range between [const@GLib.PRIORITY_DEFAULT_IDLE] and [const@GLib.PRIORITY_HIGH_IDLE] process to watch — on POSIX systems, this is the positive PID of a child process; on Windows it is a handle for a process (which doesn’t have to be a child) function to call data to pass to @function function to call when the idle is removed Creates a new child watch source. The source will not initially be associated with any [struct@GLib.MainContext] and must be added to one with [method@GLib.Source.attach] before it will be executed. Note that child watch sources can only be used in conjunction with `g_spawn...` when the [flags@GLib.SpawnFlags.DO_NOT_REAP_CHILD] flag is used. Note that on platforms where [type@GLib.Pid] must be explicitly closed (see [func@GLib.spawn_close_pid]) @pid must not be closed while the source is still active. Typically, you will want to call [func@GLib.spawn_close_pid] in the callback function for the source. On POSIX platforms, the following restrictions apply to this API due to limitations in POSIX process interfaces: * @pid must be a child of this process. * @pid must be positive. * The application must not call [`waitpid()`](man:waitpid(1)) with a non-positive first argument, for instance in another thread. * The application must not wait for @pid to exit by any other mechanism, including `waitpid(pid, ...)` or a second child-watch source for the same @pid. * The application must not ignore `SIGCHLD`. * Before 2.78, the application could not send a signal ([`kill()`](man:kill(2))) to the watched @pid in a race free manner. Since 2.78, you can do that while the associated [struct@GLib.MainContext] is acquired. * Before 2.78, even after destroying the [struct@GLib.Source], you could not be sure that @pid wasn’t already reaped. Hence, it was also not safe to `kill()` or `waitpid()` on the process ID after the child watch source was gone. Destroying the source before it fired made it impossible to reliably reap the process. If any of those conditions are not met, this and related APIs will not work correctly. This can often be diagnosed via a GLib warning stating that `ECHILD` was received by `waitpid()`. Calling [`waitpid()`](man:waitpid(2)) for specific processes other than @pid remains a valid thing to do. the newly-created child watch source process to watch — on POSIX systems, this is the positive PID of a child process; on Windows it is a handle for a process (which doesn’t have to be a child) A wrapper for the POSIX chmod() function. The chmod() function is used to set the permissions of a file system object. On Windows the file protection mechanism is not at all POSIX-like, and the underlying chmod() function in the C library just sets or clears the FAT-style READONLY attribute. It does not touch any ACL. Software that needs to manage file permissions on Windows exactly should use the Win32 API. See your C library manual for more details about chmod(). 0 if the operation succeeded, -1 on error a pathname in the GLib file name encoding (UTF-8 on Windows) as in chmod() If @err or `*err` is %NULL, does nothing. Otherwise, calls g_error_free() on `*err` and sets `*err` to %NULL. If @fd_ptr points to a file descriptor, close it and return whether closing it was successful, like g_close(). If @fd_ptr points to a negative number, return %TRUE without closing anything. In both cases, set @fd_ptr to `-1` before returning. Like g_close(), if closing the file descriptor fails, the error is stored in both %errno and @error. If this function succeeds, %errno is undefined. On POSIX platforms, this function is async-signal safe if @error is %NULL and @fd_ptr points to either a negative number or a valid open file descriptor. This makes it safe to call from a signal handler or a #GSpawnChildSetupFunc under those conditions. See [`signal(7)`](man:signal(7)) and [`signal-safety(7)`](man:signal-safety(7)) for more details. It is a programming error for @fd_ptr to point to a non-negative number that is not a valid file descriptor. A typical use of this function is to clean up a file descriptor at the end of its scope, whether it has been set successfully or not: |[ gboolean operate_on_fd (GError **error) { gboolean ret = FALSE; int fd = -1; fd = open_a_fd (error); if (fd < 0) goto out; if (!do_something (fd, error)) goto out; if (!g_clear_fd (&fd, error)) goto out; ret = TRUE; out: // OK to call even if fd was never opened or was already closed g_clear_fd (&fd, NULL); return ret; } ]| This function is also useful in conjunction with #g_autofd. %TRUE on success a pointer to a file descriptor Clears a numeric handler, such as a [struct@GLib.Source] ID. The @tag_ptr must be a valid pointer to the variable holding the handler. If the ID is zero then this function does nothing. Otherwise, @clear_func is called with the ID as a parameter, and the tag is set to zero. A macro is also included that allows this function to be used without pointer casts. a pointer to the handler ID the function to call to clear the handler Clears a pointer to a #GList, freeing it and, optionally, freeing its elements using @destroy. @list_ptr must be a valid pointer. If @list_ptr points to a null #GList, this does nothing. a #GList return location the function to pass to g_list_free_full() or %NULL to not free elements Clears a reference to a variable. @pp must not be %NULL. If the reference is %NULL then this function does nothing. Otherwise, the variable is destroyed using @destroy and the pointer is set to %NULL. A macro is also included that allows this function to be used without pointer casts. This will mask any warnings about incompatible function types or calling conventions, so you must ensure that your @destroy function is compatible with being called as [callback@GLib.DestroyNotify] using the standard calling convention for the platform that GLib was compiled for; otherwise the program will experience undefined behaviour. Examples of this kind of undefined behaviour include using many Windows Win32 APIs, as well as many if not all OpenGL and Vulkan calls on 32-bit Windows, which typically use the `__stdcall` calling convention rather than the `__cdecl` calling convention. The affected functions can be used by wrapping them in a [callback@GLib.DestroyNotify] that is declared with the standard calling convention: ```c // Wrapper needed to avoid mismatched calling conventions on Windows static void destroy_sync (void *sync) { glDeleteSync (sync); } // … g_clear_pointer (&sync, destroy_sync); ``` a pointer to a variable, struct member etc. holding a pointer a function to which a gpointer can be passed, to destroy `*pp` Clears a pointer to a #GSList, freeing it and, optionally, freeing its elements using @destroy. @slist_ptr must be a valid pointer. If @slist_ptr points to a null #GSList, this does nothing. a #GSList return location the function to pass to g_slist_free_full() or %NULL to not free elements This wraps the close() call. In case of error, %errno will be preserved, but the error will also be stored as a #GError in @error. In case of success, %errno is undefined. Besides using #GError, there is another major reason to prefer this function over the call provided by the system; on Unix, it will attempt to correctly handle %EINTR, which has platform-specific semantics. It is a bug to call this function with an invalid file descriptor. On POSIX platforms since GLib 2.76, this function is async-signal safe if (and only if) @error is %NULL and @fd is a valid open file descriptor. This makes it safe to call from a signal handler or a #GSpawnChildSetupFunc under those conditions. See [`signal(7)`](man:signal(7)) and [`signal-safety(7)`](man:signal-safety(7)) for more details. %TRUE on success, %FALSE if there was an error. A file descriptor Computes the checksum for a binary @data. This is a convenience wrapper for g_checksum_new(), g_checksum_get_string() and g_checksum_free(). The hexadecimal string returned will be in lower case. the digest of the binary data as a string in hexadecimal, or %NULL if g_checksum_new() fails for @checksum_type. The returned string should be freed with g_free() when done using it. a #GChecksumType binary blob to compute the digest of Computes the checksum for a binary @data of @length. This is a convenience wrapper for g_checksum_new(), g_checksum_get_string() and g_checksum_free(). The hexadecimal string returned will be in lower case. the digest of the binary data as a string in hexadecimal, or %NULL if g_checksum_new() fails for @checksum_type. The returned string should be freed with g_free() when done using it. a #GChecksumType binary blob to compute the digest of length of @data Computes the checksum of a string. The hexadecimal string returned will be in lower case. the checksum as a hexadecimal string, or %NULL if g_checksum_new() fails for @checksum_type. The returned string should be freed with g_free() when done using it. a #GChecksumType the string to compute the checksum of the length of the string, or -1 if the string is null-terminated. Computes the HMAC for a binary @data. This is a convenience wrapper for g_hmac_new(), g_hmac_get_string() and g_hmac_unref(). The hexadecimal string returned will be in lower case. the HMAC of the binary data as a string in hexadecimal. The returned string should be freed with g_free() when done using it. a #GChecksumType to use for the HMAC the key to use in the HMAC binary blob to compute the HMAC of Computes the HMAC for a binary @data of @length. This is a convenience wrapper for g_hmac_new(), g_hmac_get_string() and g_hmac_unref(). The hexadecimal string returned will be in lower case. the HMAC of the binary data as a string in hexadecimal. The returned string should be freed with g_free() when done using it. a #GChecksumType to use for the HMAC the key to use in the HMAC the length of the key binary blob to compute the HMAC of length of @data Computes the HMAC for a string. The hexadecimal string returned will be in lower case. the HMAC as a hexadecimal string. The returned string should be freed with g_free() when done using it. a #GChecksumType to use for the HMAC the key to use in the HMAC the length of the key the string to compute the HMAC for the length of the string, or -1 if the string is nul-terminated Allocates and initializes a new #GCond. GCond can now be statically allocated, or embedded in structures and initialised with g_cond_init(). a newly allocated #GCond. Free with g_cond_free() Converts a string from one character set to another. Note that you should use g_iconv() for streaming conversions. Despite the fact that @bytes_read can return information about partial characters, the g_convert_... functions are not generally suitable for streaming. If the underlying converter maintains internal state, then this won't be preserved across successive calls to g_convert(), g_convert_with_iconv() or g_convert_with_fallback(). (An example of this is the GNU C converter for CP1255 which does not emit a base character until it knows that the next character is not a mark that could combine with the base character.) Using extensions such as "//TRANSLIT" may not work (or may not work well) on many platforms. Consider using g_str_to_ascii() instead. If the conversion was successful, a newly allocated buffer containing the converted string, which must be freed with g_free(). Otherwise %NULL and @error will be set. the string to convert. the length of the string in bytes, or -1 if the string is nul-terminated (Note that some encodings may allow nul bytes to occur inside strings. In that case, using -1 for the @len parameter is unsafe) name of character set into which to convert @str character set of @str. location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will be the byte offset after the last valid input sequence. the number of bytes stored in the output buffer (not including the terminating nul). Converts a string from one character set to another, possibly including fallback sequences for characters not representable in the output. Note that it is not guaranteed that the specification for the fallback sequences in @fallback will be honored. Some systems may do an approximate conversion from @from_codeset to @to_codeset in their iconv() functions, in which case GLib will simply return that approximate conversion. Note that you should use g_iconv() for streaming conversions. Despite the fact that @bytes_read can return information about partial characters, the g_convert_... functions are not generally suitable for streaming. If the underlying converter maintains internal state, then this won't be preserved across successive calls to g_convert(), g_convert_with_iconv() or g_convert_with_fallback(). (An example of this is the GNU C converter for CP1255 which does not emit a base character until it knows that the next character is not a mark that could combine with the base character.) If the conversion was successful, a newly allocated buffer containing the converted string, which must be freed with g_free(). Otherwise %NULL and @error will be set. the string to convert. the length of the string in bytes, or -1 if the string is nul-terminated (Note that some encodings may allow nul bytes to occur inside strings. In that case, using -1 for the @len parameter is unsafe) name of character set into which to convert @str character set of @str. UTF-8 string to use in place of characters not present in the target encoding. (The string must be representable in the target encoding). If %NULL, characters not in the target encoding will be represented as Unicode escapes \uxxxx or \Uxxxxyyyy. location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. the number of bytes stored in the output buffer (not including the terminating nul). Converts a string from one character set to another. Note that you should use g_iconv() for streaming conversions. Despite the fact that @bytes_read can return information about partial characters, the g_convert_... functions are not generally suitable for streaming. If the underlying converter maintains internal state, then this won't be preserved across successive calls to g_convert(), g_convert_with_iconv() or g_convert_with_fallback(). (An example of this is the GNU C converter for CP1255 which does not emit a base character until it knows that the next character is not a mark that could combine with the base character.) Characters which are valid in the input character set, but which have no representation in the output character set will result in a %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error. This is in contrast to the iconv() specification, which leaves this behaviour implementation defined. Note that this is the same error code as is returned for an invalid byte sequence in the input character set. To get defined behaviour for conversion of unrepresentable characters, use g_convert_with_fallback(). If the conversion was successful, a newly allocated buffer containing the converted string, which must be freed with g_free(). Otherwise %NULL and @error will be set. the string to convert. the length of the string in bytes, or -1 if the string is nul-terminated (Note that some encodings may allow nul bytes to occur inside strings. In that case, using -1 for the @len parameter is unsafe) conversion descriptor from g_iconv_open() location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will be the byte offset after the last valid input sequence. the number of bytes stored in the output buffer (not including the terminating nul). A wrapper for the POSIX creat() function. The creat() function is used to convert a pathname into a file descriptor, creating a file if necessary. On POSIX systems file descriptors are implemented by the operating system. On Windows, it's the C library that implements creat() and file descriptors. The actual Windows API for opening files is different, see MSDN documentation for CreateFile(). The Win32 API uses file handles, which are more randomish integers, not small integers like file descriptors. Because file descriptors are specific to the C library on Windows, the file descriptor returned by this function makes sense only to functions in the same C library. Thus if the GLib-using code uses a different C library than GLib does, the file descriptor returned by this function cannot be passed to C library functions like write() or read(). See your C library manual for more details about creat(). a new file descriptor, or -1 if an error occurred. The return value can be used exactly like the return value from creat(). a pathname in the GLib file name encoding (UTF-8 on Windows) as in creat() Logs a ‘critical warning’ ([flags@GLib.LogLevelFlags.LEVEL_CRITICAL]). Critical warnings are intended to be used in the event of an error that originated in the current process (a programmer error). Logging of a critical error is by definition an indication of a bug somewhere in the current program (or its libraries). [func@GLib.return_if_fail], [func@GLib.return_val_if_fail], [func@GLib.return_if_reached] and [func@GLib.return_val_if_reached] log at [flags@GLib.LogLevelFlags.LEVEL_CRITICAL]. You can make critical warnings fatal at runtime by setting the `G_DEBUG` environment variable (see [Running GLib Applications](running.html)): ``` G_DEBUG=fatal-warnings gdb ./my-program ``` You can also use [func@GLib.log_set_always_fatal]. Any unrelated failures can be skipped over in [gdb](https://www.gnu.org/software/gdb/) using the `continue` command. The message should typically *not* be translated to the user’s language. If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. If structured logging is enabled, this will use [func@GLib.log_structured]; otherwise it will use [func@GLib.log]. See [Using Structured Logging](logging.html#using-structured-logging). format string, followed by parameters to insert into the format string (as with `printf()`) Frees all the data elements of the datalist. The data elements' destroy functions are called if they have been set. a datalist. Calls the given function for each data element of the datalist. The function is called with each data element's #GQuark id and data, together with the given @user_data parameter. Note that this function is NOT thread-safe. So unless @datalist can be protected from any modifications during invocation of this function, it should not be called. @func can make changes to @datalist, but the iteration will not reflect changes made during the g_datalist_foreach() call, other than skipping over elements that are removed. a datalist. the function to call for each data element. user data to pass to the function. Gets a data element, using its string identifier. This is slower than g_datalist_id_get_data() because it compares strings. the data element, or %NULL if it is not found. a datalist. the string identifying a data element. Gets flags values packed in together with the datalist. See g_datalist_set_flags(). the flags of the datalist pointer to the location that holds a list This is a variant of g_datalist_id_get_data() which returns a 'duplicate' of the value. @dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object. If the @key_id is not set in the datalist then @dup_func will be called with a %NULL argument. Note that @dup_func is called while the datalist is locked, so it is not allowed to read or modify the datalist. This function can be useful to avoid races when multiple threads are using the same datalist and the same key. the result of calling @dup_func on the value associated with @key_id in @datalist, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. location of a datalist the #GQuark identifying a data element function to duplicate the old value passed as user_data to @dup_func Retrieves the data element corresponding to @key_id. the data element, or %NULL if it is not found. a datalist. the #GQuark identifying a data element. Removes an element, using its #GQuark identifier. a datalist. the #GQuark identifying the data element. Removes multiple keys from a datalist. This is more efficient than calling g_datalist_id_remove_data() multiple times in a row. Before 2.80, @n_keys had to be not larger than 16. Since 2.84, performance is improved for larger number of keys. a datalist keys to remove length of @keys. Removes an element, without calling its destroy notification function. the data previously stored at @key_id, or %NULL if none. a datalist. the #GQuark identifying a data element. Compares the member that is associated with @key_id in @datalist to @oldval, and if they are the same, replace @oldval with @newval. This is like a typical atomic compare-and-exchange operation, for a member of @datalist. If the previous value was replaced then ownership of the old value (@oldval) is passed to the caller, including the registered destroy notify for it (passed out in @old_destroy). Its up to the caller to free this as they wish, which may or may not include using @old_destroy as sometimes replacement should not destroy the object in the normal way. %TRUE if the existing value for @key_id was replaced by @newval, %FALSE otherwise. location of a datalist the #GQuark identifying a data element the old value to compare against the new value to replace it with destroy notify for the new value destroy notify for the existing value Sets the data corresponding to the given #GQuark id. Any previous data with the same key is removed, and its destroy function is called. a datalist. the #GQuark to identify the data element. the data element, or %NULL to remove any previous element corresponding to @q. Sets the data corresponding to the given #GQuark id, and the function to be called when the element is removed from the datalist. Any previous data with the same key is removed, and its destroy function is called. a datalist. the #GQuark to identify the data element. the data element or %NULL to remove any previous element corresponding to @key_id. the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. If @data is %NULL, then @destroy_func must also be %NULL. Resets the datalist to %NULL. It does not free any memory or call any destroy functions. a pointer to a pointer to a datalist. Removes an element using its string identifier. The data element's destroy function is called if it has been set. a datalist. the string identifying the data element. Removes an element, without calling its destroy notifier. a datalist. the string identifying the data element. Sets the data element corresponding to the given string identifier. a datalist. the string to identify the data element. the data element, or %NULL to remove any previous element corresponding to @k. Sets the data element corresponding to the given string identifier, and the function to be called when the data element is removed. a datalist. the string to identify the data element. the data element, or %NULL to remove any previous element corresponding to @k. the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. If @d is %NULL, then @f must also be %NULL. Turns on flag values for a data list. This function is used to keep a small number of boolean flags in an object with a data list without using any additional space. It is not generally useful except in circumstances where space is very tight. (It is used in the base #GObject type, for example.) pointer to the location that holds a list the flags to turn on. The values of the flags are restricted by %G_DATALIST_FLAGS_MASK (currently 3; giving two possible boolean flags). A value for @flags that doesn't fit within the mask is an error. Turns off flag values for a data list. See g_datalist_unset_flags() pointer to the location that holds a list the flags to turn off. The values of the flags are restricted by %G_DATALIST_FLAGS_MASK (currently 3: giving two possible boolean flags). A value for @flags that doesn't fit within the mask is an error. Destroys the dataset, freeing all memory allocated, and calling any destroy functions set for data elements. the location identifying the dataset. Calls the given function for each data element which is associated with the given location. Note that this function is NOT thread-safe. So unless @dataset_location can be protected from any modifications during invocation of this function, it should not be called. @func can make changes to the dataset, but the iteration will not reflect changes made during the g_dataset_foreach() call, other than skipping over elements that are removed. the location identifying the dataset. the function to call for each data element. user data to pass to the function. Gets the data element corresponding to a string. the location identifying the dataset. the string identifying the data element. Gets the data element corresponding to a #GQuark. the data element corresponding to the #GQuark, or %NULL if it is not found. the location identifying the dataset. the #GQuark id to identify the data element. Removes a data element from a dataset. The data element's destroy function is called if it has been set. the location identifying the dataset. the #GQuark id identifying the data element. Removes an element, without calling its destroy notification function. the data previously stored at @key_id, or %NULL if none. the location identifying the dataset. the #GQuark ID identifying the data element. Sets the data element associated with the given #GQuark id. Any previous data with the same key is removed, and its destroy function is called. the location identifying the dataset. the #GQuark id to identify the data element. the data element. Sets the data element associated with the given #GQuark id, and also the function to call when the data element is destroyed. Any previous data with the same key is removed, and its destroy function is called. the location identifying the dataset. the #GQuark id to identify the data element. the data element. the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. Removes a data element corresponding to a string. Its destroy function is called if it has been set. the location identifying the dataset. the string identifying the data element. Removes an element, without calling its destroy notifier. the location identifying the dataset. the string identifying the data element. Sets the data corresponding to the given string identifier. the location identifying the dataset. the string to identify the data element. the data element. Sets the data corresponding to the given string identifier, and the function to call when the data element is destroyed. the location identifying the dataset. the string to identify the data element. the data element. the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. Returns the number of days in a month, taking leap years into account. number of days in @month during the @year month year Returns the number of weeks in the year, where weeks are taken to start on Monday. Will be 52 or 53. The date must be valid. (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it's a leap year. This function is basically telling you how many Mondays are in the year, i.e. there are 53 Mondays if one of the extra days happens to be a Monday.) number of Mondays in the year a year Returns the number of weeks in the year, where weeks are taken to start on Sunday. Will be 52 or 53. The date must be valid. (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it's a leap year. This function is basically telling you how many Sundays are in the year, i.e. there are 53 Sundays if one of the extra days happens to be a Sunday.) the number of weeks in @year year to count weeks in Calculates the number of weeks in the year. The result depends on which day is considered the first day of the week, which varies by locale. `first_day_of_week` must be valid. The result will be either 52 or 53. Years always have 52 seven-day periods, plus one or two extra days depending on whether it’s a leap year. This function effectively calculates how many @first_day_of_week days there are in the year. the number of weeks in @year year to count weeks in the day which is considered the first day of the week (for example, this would be [enum@GLib.DateWeekday.SUNDAY] in US locales, [enum@GLib.DateWeekday.MONDAY] in British locales, and [enum@GLib.DateWeekday.SATURDAY] in Egyptian locales Returns %TRUE if the year is a leap year. For the purposes of this function, leap year is every year divisible by 4 unless that year is divisible by 100. If it is divisible by 100 it would be a leap year only if that year is also divisible by 400. %TRUE if the year is a leap year year to check Generates a printed representation of the date, in a [locale](running.html#locale)-specific way. Works just like the platform's C library strftime() function, but only accepts date-related formats; time-related formats give undefined results. Date must be valid. Unlike strftime() (which uses the locale encoding), works on a UTF-8 format string and stores a UTF-8 result. This function does not provide any conversion specifiers in addition to those implemented by the platform's C library. For example, don't expect that using g_date_strftime() would make the \%F provided by the C99 strftime() work on Windows where the C library only complies to C89. number of characters written to the buffer, or `0` if the buffer was too small destination buffer buffer size format string valid #GDate Returns %TRUE if the day of the month is valid (a day is valid if it's between 1 and 31 inclusive). %TRUE if the day is valid day to check Returns %TRUE if the day-month-year triplet forms a valid, existing day in the range of days #GDate understands (Year 1 or later, no more than a few thousand years in the future). %TRUE if the date is a valid one day month year Returns %TRUE if the Julian day is valid. Anything greater than zero is basically a valid Julian, though there is a 32-bit limit. %TRUE if the Julian day is valid Julian day to check Returns %TRUE if the month value is valid. The 12 #GDateMonth enumeration values are the only valid months. %TRUE if the month is valid month Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration values are the only valid weekdays. %TRUE if the weekday is valid weekday Returns %TRUE if the year is valid. Any year greater than 0 is valid, though there is a 16-bit limit to what #GDate will understand. %TRUE if the year is valid year This is a variant of g_dgettext() that allows specifying a locale category instead of always using `LC_MESSAGES`. See g_dgettext() for more information about how this functions differs from calling dcgettext() directly. the translated string for the given locale category the translation domain to use, or %NULL to use the domain set with textdomain() message to translate a locale category A convenience function/macro to log a debug message. The message should typically *not* be translated to the user’s language. If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. Such messages are suppressed by the [func@GLib.log_default_handler] and [func@GLib.log_writer_default] unless the `G_MESSAGES_DEBUG` or `DEBUG_INVOCATION` environment variables are set appropriately. If you need to set the allowed domains at runtime, use [func@GLib.log_writer_default_set_debug_domains]. If structured logging is enabled, this will use [func@GLib.log_structured]; otherwise it will use [func@GLib.log]. See [Using Structured Logging](logging.html#using-structured-logging). format string, followed by parameters to insert into the format string (as with `printf()`) This function is a wrapper of dgettext() which does not translate the message if the default domain as set with textdomain() has no translations for the current locale. The advantage of using this function over dgettext() proper is that libraries using this function (like GTK) will not use translations if the application using the library does not have translations for the current locale. This results in a consistent English-only interface instead of one having partial translations. For this feature to work, the call to textdomain() and setlocale() should precede any g_dgettext() invocations. For GTK, it means calling textdomain() before gtk_init or its variants. This function disables translations if and only if upon its first call all the following conditions hold: - @domain is not %NULL - textdomain() has been called to set a default text domain - there is no translations available for the default text domain and the current locale - current locale is not "C" or any English locales (those starting with "en_") Note that this behavior may not be desired for example if an application has its untranslated messages in a language other than English. In those cases the application should call textdomain() after initializing GTK. Applications should normally not use this function directly, but use the _() macro for translations. The translated string the translation domain to use, or %NULL to use the domain set with textdomain() message to translate Creates a subdirectory in the preferred directory for temporary files (as returned by g_get_tmp_dir()). @tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, as the parameter to g_mkstemp(). However, unlike these functions, the template should only be a basename, no directory components are allowed. If template is %NULL, a default template is used. Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not modified, and might thus be a read-only literal string. The actual name used. This string should be freed with g_free() when not needed any longer and is is in the GLib file name encoding. In case of errors, %NULL is returned and @error will be set. Template for directory name, as in g_mkdtemp(), basename only, or %NULL for a default template Compares two #gpointer arguments and returns %TRUE if they are equal. It can be passed to g_hash_table_new() as the @key_equal_func parameter, when using opaque pointers compared by pointer value as keys in a #GHashTable. This equality function is also appropriate for keys that are integers stored in pointers, such as `GINT_TO_POINTER (n)`. %TRUE if the two keys match. a key a key to compare with @v1 Converts a gpointer to a hash value. It can be passed to g_hash_table_new() as the @hash_func parameter, when using opaque pointers compared by pointer value as keys in a #GHashTable. This hash function is also appropriate for keys that are integers stored in pointers, such as `GINT_TO_POINTER (n)`. a hash value corresponding to the key. a #gpointer key This function is a wrapper of dngettext() which does not translate the message if the default domain as set with textdomain() has no translations for the current locale. See g_dgettext() for details of how this differs from dngettext() proper. The translated string the translation domain to use, or %NULL to use the domain set with textdomain() message to translate plural form of the message the quantity for which translation is needed Compares the two #gdouble values being pointed to and returns %TRUE if they are equal. It can be passed to g_hash_table_new() as the @key_equal_func parameter, when using non-%NULL pointers to doubles as keys in a #GHashTable. %TRUE if the two keys match. a pointer to a #gdouble key a pointer to a #gdouble key to compare with @v1 Converts a pointer to a #gdouble to a hash value. It can be passed to g_hash_table_new() as the @hash_func parameter, It can be passed to g_hash_table_new() as the @hash_func parameter, when using non-%NULL pointers to doubles as keys in a #GHashTable. a hash value corresponding to the key. a pointer to a #gdouble key This function is a variant of g_dgettext() which supports a disambiguating message context. GNU gettext uses the '\004' character to separate the message context and message id in @msgctxtid. If 0 is passed as @msgidoffset, this function will fall back to trying to use the deprecated convention of using "|" as a separation character. This uses g_dgettext() internally. See that functions for differences with dgettext() proper. Applications should normally not use this function directly, but use the C_() macro for translations with context. The translated string the translation domain to use, or %NULL to use the domain set with textdomain() a combined message context and message id, separated by a \004 character the offset of the message id in @msgctxid This function is a variant of g_dgettext() which supports a disambiguating message context. GNU gettext uses the '\004' character to separate the message context and message id in @msgctxtid. This uses g_dgettext() internally. See that functions for differences with dgettext() proper. This function differs from C_() in that it is not a macro and thus you may use non-string-literals as context and msgid arguments. The translated string the translation domain to use, or %NULL to use the domain set with textdomain() the message context the message Returns the value of the environment variable @variable in the provided list @envp. the value of the environment variable, or %NULL if the environment variable is not set in @envp. The returned string is owned by @envp, and will be freed if @variable is set or unset again. an environment list (eg, as returned from g_get_environ()), or %NULL for an empty environment list the environment variable to get Sets the environment variable @variable in the provided list @envp to @value. the updated environment list. Free it using g_strfreev(). an environment list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), or %NULL for an empty environment list the environment variable to set, must not contain '=' the value for to set the variable to whether to change the variable if it already exists Removes the environment variable @variable from the provided environment @envp. the updated environment list. Free it using g_strfreev(). an environment list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), or %NULL for an empty environment list the environment variable to remove, must not contain '=' A convenience function/macro to log an error message. The message should typically *not* be translated to the user’s language. This is not intended for end user error reporting. Use of [type@GLib.Error] is preferred for that instead, as it allows calling functions to perform actions conditional on the type of error. Error messages are always fatal, resulting in a call to [func@GLib.BREAKPOINT] to terminate the application. This function will result in a core dump; don’t use it for errors you expect. Using this function indicates a bug in your program, i.e. an assertion failure. If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. If structured logging is enabled, this will use [func@GLib.log_structured]; otherwise it will use [func@GLib.log]. See [Using Structured Logging](logging.html#using-structured-logging). format string, followed by parameters to insert into the format string (as with `printf()`) This function registers an extended #GError domain. @error_type_name will be duplicated. Otherwise does the same as g_error_domain_register_static(). #GQuark representing the error domain string to create a #GQuark from size of the private error data in bytes function initializing fields of the private error data function copying fields of the private error data function freeing fields of the private error data This function registers an extended #GError domain. @error_type_name should not be freed. @error_type_private_size must be greater than 0. @error_type_init receives an initialized #GError and should then initialize the private data. @error_type_copy is a function that receives both original and a copy #GError and should copy the fields of the private error data. The standard #GError fields are already handled. @error_type_clear receives the pointer to the error, and it should free the fields of the private error data. It should not free the struct itself though. Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of passing valid information to this function. #GQuark representing the error domain static string to create a #GQuark from size of the private error data in bytes function initializing fields of the private error data function copying fields of the private error data function freeing fields of the private error data Gets a #GFileError constant based on the passed-in @err_no. For example, if you pass in `EEXIST` this function returns %G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably assume that all #GFileError values will exist. Normally a #GFileError value goes into a #GError returned from a function that manipulates files. So you would use g_file_error_from_errno() when constructing a #GError. #GFileError corresponding to the given @err_no an "errno" value Reads an entire file into allocated memory, with good error checking. If the call was successful, it returns %TRUE and sets @contents to the file contents and @length to the length of the file contents in bytes. The string stored in @contents will be nul-terminated, so for text files you can pass %NULL for the @length argument. If the call was not successful, it returns %FALSE and sets @error. The error domain is %G_FILE_ERROR. Possible error codes are those in the #GFileError enumeration. In the error case, @contents is set to %NULL and @length is set to zero. %TRUE on success, %FALSE if an error occurred name of a file to read contents from, in the GLib file name encoding location to store an allocated string, use g_free() to free the returned string location to store length in bytes of the contents, or %NULL Opens a file for writing in the preferred directory for temporary files (as returned by g_get_tmp_dir()). @tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, as the parameter to g_mkstemp(). However, unlike these functions, the template should only be a basename, no directory components are allowed. If template is %NULL, a default template is used. Note that in contrast to g_mkstemp() (and mkstemp()) @tmpl is not modified, and might thus be a read-only literal string. Upon success, and if @name_used is non-%NULL, the actual name used is returned in @name_used. This string should be freed with g_free() when not needed any longer. The returned name is in the GLib file name encoding. A file handle (as from open()) to the file opened for reading and writing. The file is opened in binary mode on platforms where there is a difference. The file handle should be closed with close(). In case of errors, -1 is returned and @error will be set. Template for file name, as in g_mkstemp(), basename only, or %NULL for a default template location to store actual name used, or %NULL Reads the contents of the symbolic link @filename like the POSIX `readlink()` function. The returned string is in the encoding used for filenames. Use g_filename_to_utf8() to convert it to UTF-8. The returned string may also be a relative path. Use g_build_filename() to convert it to an absolute path: |[<!-- language="C" --> g_autoptr(GError) local_error = NULL; g_autofree gchar *link_target = g_file_read_link ("/etc/localtime", &local_error); if (local_error != NULL) g_error ("Error reading link: %s", local_error->message); if (!g_path_is_absolute (link_target)) { g_autofree gchar *absolute_link_target = g_build_filename ("/etc", link_target, NULL); g_free (link_target); link_target = g_steal_pointer (&absolute_link_target); } ]| A newly-allocated string with the contents of the symbolic link, or %NULL if an error occurred. the symbolic link Writes all of @contents to a file named @filename. This is a convenience wrapper around calling g_file_set_contents_full() with `flags` set to `G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING` and `mode` set to `0666`. %TRUE on success, %FALSE if an error occurred name of a file to write @contents to, in the GLib file name encoding string to write to the file length of @contents, or -1 if @contents is a nul-terminated string Writes all of @contents to a file named @filename, with good error checking. If a file called @filename already exists it will be overwritten. @flags control the properties of the write operation: whether it’s atomic, and what the tradeoff is between returning quickly or being resilient to system crashes. As this function performs file I/O, it is recommended to not call it anywhere where blocking would cause problems, such as in the main loop of a graphical application. In particular, if @flags has any value other than %G_FILE_SET_CONTENTS_NONE then this function may call `fsync()`. If %G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, the operation is atomic in the sense that it is first written to a temporary file which is then renamed to the final name. Notes: - On UNIX, if @filename already exists hard links to @filename will break. Also since the file is recreated, existing permissions, access control lists, metadata etc. may be lost. If @filename is a symbolic link, the link itself will be replaced, not the linked file. - On UNIX, if @filename already exists and is non-empty, and if the system supports it (via a journalling filesystem or equivalent), and if %G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, the `fsync()` call (or equivalent) will be used to ensure atomic replacement: @filename will contain either its old contents or @contents, even in the face of system power loss, the disk being unsafely removed, etc. - On UNIX, if @filename does not already exist or is empty, there is a possibility that system power loss etc. after calling this function will leave @filename empty or full of NUL bytes, depending on the underlying filesystem, unless %G_FILE_SET_CONTENTS_DURABLE and %G_FILE_SET_CONTENTS_CONSISTENT are set in @flags. - On Windows renaming a file will not remove an existing file with the new name, so on Windows there is a race condition between the existing file being removed and the temporary file being renamed. - On Windows there is no way to remove a file that is open to some process, or mapped into memory. Thus, this function will fail if @filename already exists and is open. If the call was successful, it returns %TRUE. If the call was not successful, it returns %FALSE and sets @error. The error domain is %G_FILE_ERROR. Possible error codes are those in the #GFileError enumeration. Note that the name for the temporary file is constructed by appending up to 7 characters to @filename. If the file didn’t exist before and is created, it will be given the permissions from @mode. Otherwise, the permissions of the existing file will remain unchanged. %TRUE on success, %FALSE if an error occurred name of a file to write @contents to, in the GLib file name encoding string to write to the file length of @contents, or -1 if @contents is a nul-terminated string flags controlling the safety vs speed of the operation file mode, as passed to `open()`; typically this will be `0666` Returns %TRUE if any of the tests in the bitfield @test are %TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)` will return %TRUE if the file exists; the check whether it's a directory doesn't matter since the existence test is %TRUE. With the current set of available tests, there's no point passing in more than one test at a time. Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links, so for a symbolic link to a regular file g_file_test() will return %TRUE for both %G_FILE_TEST_IS_SYMLINK and %G_FILE_TEST_IS_REGULAR. Note, that for a dangling symbolic link g_file_test() will return %TRUE for %G_FILE_TEST_IS_SYMLINK and %FALSE for all other flags. You should never use g_file_test() to test whether it is safe to perform an operation, because there is always the possibility of the condition changing before you actually perform the operation, see [TOCTOU](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use). For example, you might think you could use %G_FILE_TEST_IS_SYMLINK to know whether it is safe to write to a file without being tricked into writing into a different location. It doesn't work! |[<!-- language="C" --> // DON'T DO THIS if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) { fd = g_open (filename, O_WRONLY); // write to fd } // DO THIS INSTEAD fd = g_open (filename, O_WRONLY | O_NOFOLLOW | O_CLOEXEC); if (fd == -1) { // check error if (errno == ELOOP) // file is a symlink and can be ignored else // handle errors as before } else { // write to fd } ]| Another thing to note is that %G_FILE_TEST_EXISTS and %G_FILE_TEST_IS_EXECUTABLE are implemented using the access() system call. This usually doesn't matter, but if your program is setuid or setgid it means that these tests will give you the answer for the real user ID and group ID, rather than the effective user ID and group ID. On Windows, there are no symlinks, so testing for %G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for %G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and its name indicates that it is executable, checking for well-known extensions and those listed in the `PATHEXT` environment variable. whether a test was %TRUE a filename to test in the GLib file name encoding bitfield of #GFileTest flags Returns the display basename for the particular filename, guaranteed to be valid UTF-8. The display name might not be identical to the filename, for instance there might be problems converting it to UTF-8, and some files can be translated in the display. If GLib cannot make sense of the encoding of @filename, as a last resort it replaces unknown characters with U+FFFD, the Unicode replacement character. You can search the result for the UTF-8 encoding of this character (which is "\357\277\275" in octal notation) to find out if @filename was in an invalid encoding. You must pass the whole absolute pathname to this functions so that translation of well known locations can be done. This function is preferred over g_filename_display_name() if you know the whole path, as it allows translation. a newly allocated string containing a rendition of the basename of the filename in valid UTF-8 an absolute pathname in the GLib file name encoding Converts a filename into a valid UTF-8 string. The conversion is not necessarily reversible, so you should keep the original around and use the return value of this function only for display purposes. Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL even if the filename actually isn't in the GLib file name encoding. If GLib cannot make sense of the encoding of @filename, as a last resort it replaces unknown characters with U+FFFD, the Unicode replacement character. You can search the result for the UTF-8 encoding of this character (which is "\357\277\275" in octal notation) to find out if @filename was in an invalid encoding. If you know the whole pathname of the file you should use g_filename_display_basename(), since that allows location-based translation of filenames. a newly allocated string containing a rendition of the filename in valid UTF-8 a pathname hopefully in the GLib file name encoding Converts an escaped ASCII-encoded URI to a local filename in the encoding used for filenames. Since GLib 2.78, the query string and fragment can be present in the URI, but are not part of the resulting filename. We take inspiration from https://url.spec.whatwg.org/#file-state, but we don't support the entire standard. a newly-allocated string holding the resulting filename, or %NULL on an error. a uri describing a filename (escaped, encoded in ASCII). Location to store hostname for the URI. If there is no hostname in the URI, %NULL will be stored in this location. Converts a string from UTF-8 to the encoding GLib uses for filenames. Note that on Windows GLib uses UTF-8 for filenames; on other platforms, this function indirectly depends on the [current locale](running.html#locale). The input string shall not contain nul characters even if the @len argument is positive. A nul character found inside the string will result in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. If the filename encoding is not UTF-8 and the conversion output contains a nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns %NULL. The converted string, or %NULL on an error. a UTF-8 encoded string. the length of the string, or -1 if the string is nul-terminated. location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will be the byte offset after the last valid input sequence. the number of bytes stored in the output buffer (not including the terminating nul). Converts an absolute filename to an escaped ASCII-encoded URI, with the path component following Section 3.3. of RFC 2396. a newly-allocated string holding the resulting URI, or %NULL on an error. an absolute filename specified in the GLib file name encoding, which is the on-disk file name bytes on Unix, and UTF-8 on Windows A UTF-8 encoded hostname, or %NULL for none. Converts a string which is in the encoding used by GLib for filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8 for filenames; on other platforms, this function indirectly depends on the [current locale](running.html#locale). The input string shall not contain nul characters even if the @len argument is positive. A nul character found inside the string will result in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. If the source encoding is not UTF-8 and the conversion output contains a nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns %NULL. Use g_convert() to produce output that may contain embedded nul characters. The converted string, or %NULL on an error. a string in the encoding for filenames the length of the string, or -1 if the string is nul-terminated (Note that some encodings may allow nul bytes to occur inside strings. In that case, using -1 for the @len parameter is unsafe) location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will be the byte offset after the last valid input sequence. the number of bytes stored in the output buffer (not including the terminating nul). Locates the first executable named @program in the user's path, in the same way that execvp() would locate it. Returns an allocated string with the absolute path name, or %NULL if the program is not found in the path. If @program is already an absolute path, returns a copy of @program if @program exists and is executable, and %NULL otherwise. On Windows, if @program does not have a file type suffix, tries with the suffixes .exe, .cmd, .bat and .com, and the suffixes in the `PATHEXT` environment variable. On Windows, it looks for the file in the same way as CreateProcess() would. This means first in the directory where the executing program was loaded from, then in the current directory, then in the Windows 32-bit system directory, then in the Windows directory, and finally in the directories in the `PATH` environment variable. If the program is found, the return value contains the full name including the type suffix. a newly-allocated string with the absolute path, or %NULL a program name in the GLib file name encoding A wrapper for the stdio `fopen()` function. The `fopen()` function opens a file and associates a new stream with it. Because file descriptors are specific to the C library on Windows, and a file descriptor is part of the `FILE` struct, the `FILE*` returned by this function makes sense only to functions in the same C library. Thus if the GLib-using code uses a different C library than GLib does, the FILE* returned by this function cannot be passed to C library functions like `fprintf()` or `fread()`. See your C library manual for more details about `fopen()`. As `close()` and `fclose()` are part of the C library, this implies that it is currently impossible to close a file if the application C library and the C library used by GLib are different. Convenience functions like g_file_set_contents_full() avoid this problem. Since GLib 2.86, the `e` option is supported in @mode on all platforms. On Unix platforms it will set `O_CLOEXEC` on the opened file descriptor. On Windows platforms it will be converted to the [`N` modifier](https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/fopen-wfopen?view=msvc-170). It is recommended to set `e` unconditionally, unless you know the returned file should be shared between this process and a new fork. A `FILE*` if the file was successfully opened, or %NULL if an error occurred a pathname in the GLib file name encoding (UTF-8 on Windows) a string describing the mode in which the file should be opened Formats a size (for example the size of a file) into a human readable string. Sizes are rounded to the nearest size prefix (kB, MB, GB) and are displayed rounded to the nearest tenth. E.g. the file size 3292528 bytes will be converted into the string "3.2 MB". The returned string is UTF-8, and may use a non-breaking space to separate the number and units, to ensure they aren’t separated when line wrapped. The prefix units base is 1000 (i.e. 1 kB is 1000 bytes). This string should be freed with g_free() when not needed any longer. See g_format_size_full() for more options about how the size might be formatted. a newly-allocated formatted string containing a human readable file size a size in bytes Formats a size (for example the size of a file) into a human readable string. Sizes are rounded to the nearest size prefix (KB, MB, GB) and are displayed rounded to the nearest tenth. E.g. the file size 3292528 bytes will be converted into the string "3.1 MB". The prefix units base is 1024 (i.e. 1 KB is 1024 bytes). This string should be freed with g_free() when not needed any longer. This function is broken due to its use of SI suffixes to denote IEC units. Use g_format_size() instead. a newly-allocated formatted string containing a human readable file size a size in bytes Formats a size. This function is similar to g_format_size() but allows for flags that modify the output. See #GFormatSizeFlags. a newly-allocated formatted string containing a human readable file size a size in bytes #GFormatSizeFlags to modify the output An implementation of the standard `fprintf()` function which supports positional parameters, as specified in the Single Unix Specification. `glib/gprintf.h` must be explicitly included in order to use this function. the number of bytes printed the stream to write to a standard `printf()` format string, but notice [string precision pitfalls](string-utils.html#string-precision-pitfalls) the arguments to insert in the output Frees the memory pointed to by @mem. If you know the allocated size of @mem, calling g_free_sized() may be faster, depending on the libc implementation in use. Starting from GLib 2.78, this may happen automatically in case a GCC compatible compiler is used with some optimization level and the allocated size is known at compile time (see [documentation of `__builtin_object_size()`](https://gcc.gnu.org/onlinedocs/gcc/Object-Size-Checking.html) to understand its caveats). If @mem is %NULL it simply returns, so there is no need to check @mem against %NULL before calling this function. the memory to free Frees the memory pointed to by @mem, assuming it is has the given @size. If @mem is %NULL this is a no-op (and @size is ignored). It is an error if @size doesn’t match the size passed when @mem was allocated. @size is passed to this function to allow optimizations in the allocator. If you don’t know the allocation size, use g_free() instead. In case a GCC compatible compiler is used, this function may be used automatically via g_free() if the allocated size is known at compile time, since GLib 2.78. the memory to free size of @mem, in bytes A wrapper for the POSIX freopen() function. The freopen() function opens a file and associates it with an existing stream. See your C library manual for more details about freopen(). Since GLib 2.86, the `e` option is supported in @mode on all platforms. See the documentation for [func@GLib.fopen] for more details. A FILE* if the file was successfully opened, or %NULL if an error occurred. a pathname in the GLib file name encoding (UTF-8 on Windows) a string describing the mode in which the file should be opened an existing stream which will be reused, or %NULL A wrapper for the POSIX `fsync()` function. On Windows, `_commit()` will be used. On macOS, `fcntl(F_FULLFSYNC)` will be used. The `fsync()` function is used to synchronize a file's in-core state with that of the disk. This wrapper will handle retrying on `EINTR`. See the C library manual for more details about fsync(). 0 on success, or -1 if an error occurred. The return value can be used exactly like the return value from fsync(). a file descriptor Gets a human-readable name for the application, as set by g_set_application_name(). This name should be localized if possible, and is intended for display to the user. Contrast with g_get_prgname(), which gets a non-localized name. If g_set_application_name() has not been called, returns the result of g_get_prgname() (which may be %NULL if g_set_prgname() has also not been called). human-readable application name. May return %NULL Obtains the character set for the [current locale](running.html#locale); you might use this character set as an argument to g_convert(), to convert from the current locale's encoding to some other encoding. (Frequently g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.) On Windows the character set returned by this function is the so-called system default ANSI code-page. That is the character set used by the "narrow" versions of C library and Win32 functions that handle file names. It might be different from the character set used by the C library's current locale. On Linux, the character set is found by consulting nl_langinfo() if available. If not, the environment variables `LC_ALL`, `LC_CTYPE`, `LANG` and `CHARSET` are queried in order. nl_langinfo() returns the C locale if no locale has been loaded by setlocale(). The return value is %TRUE if the locale's encoding is UTF-8, in that case you can perhaps avoid calling g_convert(). The string returned in @charset is not allocated, and should not be freed. %TRUE if the returned charset is UTF-8 return location for character set name, or %NULL. Gets the character set for the current locale. a newly allocated string containing the name of the character set. This string must be freed with g_free(). Obtains the character set used by the console attached to the process, which is suitable for printing output to the terminal. Usually this matches the result returned by g_get_charset(), but in environments where the locale's character set does not match the encoding of the console this function tries to guess a more suitable value instead. On Windows the character set returned by this function is the output code page used by the console associated with the calling process. If the codepage can't be determined (for example because there is no console attached) UTF-8 is assumed. The return value is %TRUE if the locale's encoding is UTF-8, in that case you can perhaps avoid calling g_convert(). The string returned in @charset is not allocated, and should not be freed. %TRUE if the returned charset is UTF-8 return location for character set name, or %NULL. Gets the current directory. The returned string should be freed when no longer needed. The encoding of the returned string is system defined. On Windows, it is always UTF-8. Since GLib 2.40, this function will return the value of the "PWD" environment variable if it is set and it happens to be the same as the current directory. This can make a difference in the case that the current directory is the target of a symbolic link. the current directory Queries the system wall-clock time. This is equivalent to the UNIX [`gettimeofday()`](man:gettimeofday(2)) function, but portable. You may find [func@GLib.get_real_time] to be more convenient. [struct@GLib.TimeVal] is not year-2038-safe. Use [func@GLib.get_real_time] instead. [struct@GLib.TimeVal] structure in which to store current time Gets the list of environment variables for the current process. The list is %NULL terminated and each item in the list is of the form 'NAME=VALUE'. This is equivalent to direct access to the 'environ' global variable, except portable. The return value is freshly allocated and it should be freed with g_strfreev() when it is no longer needed. the list of environment variables Determines the preferred character sets used for filenames. The first character set from the @charsets is the filename encoding, the subsequent character sets are used when trying to generate a displayable representation of a filename, see g_filename_display_name(). On Unix, the character sets are determined by consulting the environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`. On Windows, the character set used in the GLib API is always UTF-8 and said environment variables have no effect. `G_FILENAME_ENCODING` may be set to a comma-separated list of character set names. The special token `@locale` is taken to mean the character set for the [current locale](running.html#locale). If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is, the character set of the current locale is taken as the filename encoding. If neither environment variable is set, UTF-8 is taken as the filename encoding, but the character set of the current locale is also put in the list of encodings. The returned @charsets belong to GLib and must not be freed. Note that on Unix, regardless of the locale character set or `G_FILENAME_ENCODING` value, the actual file names present on a system might be in any random encoding or just gibberish. %TRUE if the filename encoding is UTF-8. return location for the %NULL-terminated list of encoding names Gets the current user's home directory. As with most UNIX tools, this function will return the value of the `HOME` environment variable if it is set to an existing absolute path name, falling back to the `passwd` file in the case that it is unset. If the path given in `HOME` is non-absolute, does not exist, or is not a directory, the result is undefined. Before version 2.36 this function would ignore the `HOME` environment variable, taking the value from the `passwd` database instead. This was changed to increase the compatibility of GLib with other programs (and the XDG basedir specification) and to increase testability of programs based on GLib (by making it easier to run them from test frameworks). If your program has a strong requirement for either the new or the old behaviour (and if you don't wish to increase your GLib dependency to ensure that the new behaviour is in effect) then you should either directly check the `HOME` environment variable yourself or unset it before calling any functions in GLib. the current user's home directory Return a name for the machine. The returned name is not necessarily a fully-qualified domain name, or even present in DNS or some other name service at all. It need not even be unique on your local network or site, but usually it is. Callers should not rely on the return value having any specific properties like uniqueness for security purposes. Even if the name of the machine is changed while an application is running, the return value from this function does not change. The returned string is owned by GLib and should not be modified or freed. If no name can be determined, a default fixed string "localhost" is returned. The encoding of the returned string is UTF-8. the host name of the machine. Computes a list of applicable locale names, which can be used to e.g. construct locale-dependent filenames or search paths. The returned list is sorted from most desirable to least desirable and always contains the default locale "C". For example, if LANGUAGE=de:en_US, then the returned list is "de", "en_US", "en", "C". This function consults the environment variables `LANGUAGE`, `LC_ALL`, `LC_MESSAGES` and `LANG` to find the list of locales specified by the user. a %NULL-terminated array of strings owned by GLib that must not be modified or freed. Computes a list of applicable locale names with a locale category name, which can be used to construct the fallback locale-dependent filenames or search paths. The returned list is sorted from most desirable to least desirable and always contains the default locale "C". This function consults the environment variables `LANGUAGE`, `LC_ALL`, @category_name, and `LANG` to find the list of locales specified by the user. g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES"). a %NULL-terminated array of strings owned by the thread g_get_language_names_with_category was called from. It must not be modified or freed. It must be copied if planned to be used in another thread. a locale category name Returns a list of derived variants of @locale, which can be used to e.g. construct locale-dependent filenames or search paths. The returned list is sorted from most desirable to least desirable. This function handles territory, charset and extra locale modifiers. See [`setlocale(3)`](man:setlocale) for information about locales and their format. @locale itself is guaranteed to be returned in the output. For example, if @locale is `fr_BE`, then the returned list is `fr_BE`, `fr`. If @locale is `en_GB.UTF-8@euro`, then the returned list is `en_GB.UTF-8@euro`, `en_GB.UTF-8`, `en_GB@euro`, `en_GB`, `en.UTF-8@euro`, `en.UTF-8`, `en@euro`, `en`. If you need the list of variants for the current locale, use g_get_language_names(). a newly allocated array of newly allocated strings with the locale variants. Free with g_strfreev(). a locale identifier Queries the system monotonic time in microseconds. The monotonic clock will always increase and doesn’t suffer discontinuities when the user (or NTP) changes the system time. It may or may not continue to tick during times where the machine is suspended. We try to use the clock that corresponds as closely as possible to the passage of time as measured by system calls such as [`poll()`](man:poll(2)) but it may not always be possible to do this. A more accurate version of this function exists. [func@GLib.get_monotonic_time_ns] returns the time in nanoseconds. the monotonic time, in microseconds Queries the system monotonic time in nanoseconds. The monotonic clock will always increase and doesn’t suffer discontinuities when the user (or NTP) changes the system time. It may or may not continue to tick during times where the machine is suspended. We try to use the clock that corresponds as closely as possible to the passage of time as measured by system calls such as [`poll()`](man:poll(2)) but it may not always be possible to do this. Another version of this function exists. [func@GLib.get_monotonic_time] returns the time in microseconds. If you want to support older GLib versions, it is an alternative. the monotonic time, in nanoseconds Determine the approximate number of threads that the system will schedule simultaneously for this process. This is intended to be used as a parameter to g_thread_pool_new() for CPU bound tasks and similar cases. Number of schedulable threads, always greater than 0 Get information about the operating system. On Linux this comes from the `/etc/os-release` file. On other systems, it may come from a variety of sources. You can either use the standard key names like %G_OS_INFO_KEY_NAME or pass any UTF-8 string key name. For example, `/etc/os-release` provides a number of other less commonly used values that may be useful. No key is guaranteed to be provided, so the caller should always check if the result is %NULL. The associated value for the requested key or %NULL if this information is not provided. a key for the OS info being requested, for example %G_OS_INFO_KEY_NAME. Gets the name of the program. This name should not be localized, in contrast to g_get_application_name(). If you are using #GApplication the program name is set in g_application_run(). In case of GDK or GTK it is set in gdk_init(), which is called by gtk_init() and the #GtkApplication::startup handler. The program name is found by taking the last component of @argv[0]. the name of the program, or %NULL if it has not been set yet. The returned string belongs to GLib and must not be modified or freed. Gets the real name of the user. This usually comes from the user's entry in the `passwd` file. The encoding of the returned string is system-defined. (On Windows, it is, however, always UTF-8.) If the real user name cannot be determined, the string "Unknown" is returned. the user's real name. Queries the system wall-clock time. This is equivalent to the UNIX [`gettimeofday()`](man:gettimeofday(2)) function, but portable. You should only use this call if you are actually interested in the real wall-clock time. [func@GLib.get_monotonic_time] is probably more useful for measuring intervals. the number of microseconds since [January 1, 1970 UTC](https://en.wikipedia.org/wiki/Unix_time) Returns an ordered list of base directories in which to access system-wide configuration information. On UNIX platforms this is determined using the mechanisms described in the [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`. On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_DIRS` is defined. If `XDG_CONFIG_DIRS` is undefined, the directory that contains application data for all users is used instead. A typical path is `C:\Documents and Settings\All Users\Application Data`. This folder is used for application data that is not user specific. For example, an application can store a spell-check dictionary, a database of clip art, or a log file in the FOLDERID_ProgramData folder. This information will not roam and is available to anyone using the computer. The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. a %NULL-terminated array of strings owned by GLib that must not be modified or freed. Returns an ordered list of base directories in which to access system-wide application data. On UNIX platforms this is determined using the mechanisms described in the [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec) In this case the list of directories retrieved will be `XDG_DATA_DIRS`. On Windows it follows XDG Base Directory Specification if `XDG_DATA_DIRS` is defined. If `XDG_DATA_DIRS` is undefined, the first elements in the list are the Application Data and Documents folders for All Users. (These can be determined only on Windows 2000 or later and are not present in the list on other Windows versions.) See documentation for FOLDERID_ProgramData and FOLDERID_PublicDocuments. Then follows the "share" subfolder in the installation folder for the package containing the DLL that calls this function, if it can be determined. Finally the list contains the "share" subfolder in the installation folder for GLib, and in the installation folder for the package the application's .exe file belongs to. The installation folders above are determined by looking up the folder where the module (DLL or EXE) in question is located. If the folder's name is "bin", its parent is used, otherwise the folder itself. Note that on Windows the returned list can vary depending on where this function is called. The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. a %NULL-terminated array of strings owned by GLib that must not be modified or freed. Gets the directory to use for temporary files. On UNIX, this is taken from the `TMPDIR` environment variable. If the variable is not set, `P_tmpdir` is used, as defined by the system C library. Failing that, a hard-coded default of "/tmp" is returned. On Windows, the `TEMP` environment variable is used, with the root directory of the Windows installation (eg: "C:\") used as a default. The encoding of the returned string is system-defined. On Windows, it is always UTF-8. The return value is never %NULL or the empty string. the directory to use for temporary files. Returns a base directory in which to store non-essential, cached data specific to particular user. On UNIX platforms this is determined using the mechanisms described in the [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). In this case the directory retrieved will be `XDG_CACHE_HOME`. On Windows it follows XDG Base Directory Specification if `XDG_CACHE_HOME` is defined. If `XDG_CACHE_HOME` is undefined, the directory that serves as a common repository for temporary Internet files is used instead. A typical path is `C:\Documents and Settings\username\Local Settings\Temporary Internet Files`. See the [documentation for `FOLDERID_InternetCache`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. a string owned by GLib that must not be modified or freed. Returns a base directory in which to store user-specific application configuration information such as user preferences and settings. On UNIX platforms this is determined using the mechanisms described in the [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). In this case the directory retrieved will be `XDG_CONFIG_HOME`. On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_HOME` is defined. If `XDG_CONFIG_HOME` is undefined, the folder to use for local (as opposed to roaming) application data is used instead. See the [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). Note that in this case on Windows it will be the same as what g_get_user_data_dir() returns. The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. a string owned by GLib that must not be modified or freed. Returns a base directory in which to access application data such as icons that is customized for a particular user. On UNIX platforms this is determined using the mechanisms described in the [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). In this case the directory retrieved will be `XDG_DATA_HOME`. On Windows it follows XDG Base Directory Specification if `XDG_DATA_HOME` is defined. If `XDG_DATA_HOME` is undefined, the folder to use for local (as opposed to roaming) application data is used instead. See the [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). Note that in this case on Windows it will be the same as what g_get_user_config_dir() returns. The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. a string owned by GLib that must not be modified or freed. Gets the user name of the current user. The encoding of the returned string is system-defined. On UNIX, it might be the preferred file name encoding, or something else, and there is no guarantee that it is even consistent on a machine. On Windows, it is always UTF-8. the user name of the current user. Returns a directory that is unique to the current user on the local system. This is determined using the mechanisms described in the [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). This is the directory specified in the `XDG_RUNTIME_DIR` environment variable. In the case that this variable is not set, we return the value of g_get_user_cache_dir(), after verifying that it exists. The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. a string owned by GLib that must not be modified or freed. Returns the full path of a special directory using its logical id. On UNIX this is done using the XDG special user directories. For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP falls back to `$HOME/Desktop` when XDG special user directories have not been set up. Depending on the platform, the user might be able to change the path of the special directory without requiring the session to restart; GLib will not reflect any change once the special directories are loaded. the path to the specified special directory, or %NULL if the logical id was not found. The returned string is owned by GLib and should not be modified or freed. the logical id of special directory Returns a base directory in which to store state files specific to particular user. On UNIX platforms this is determined using the mechanisms described in the [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). In this case the directory retrieved will be `XDG_STATE_HOME`. On Windows it follows XDG Base Directory Specification if `XDG_STATE_HOME` is defined. If `XDG_STATE_HOME` is undefined, the folder to use for local (as opposed to roaming) application data is used instead. See the [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). Note that in this case on Windows it will be the same as what g_get_user_data_dir() returns. The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. a string owned by GLib that must not be modified or freed. Returns the value of an environment variable. On UNIX, the name and value are byte strings which might or might not be in some consistent character set and encoding. On Windows, they are in UTF-8. On Windows, in case the environment variable's value contains references to other environment variables, they are expanded. the value of the environment variable, or %NULL if the environment variable is not found. The returned string may be overwritten by the next call to g_getenv(), g_setenv() or g_unsetenv(). the environment variable to get This is a convenience function for using a #GHashTable as a set. It is equivalent to calling g_hash_table_replace() with @key as both the key and the value. In particular, this means that if @key already exists in the hash table, then the old copy of @key in the hash table is freed and @key replaces it in the table. When a hash table only ever contains keys that have themselves as the corresponding value it is able to be stored more efficiently. See the discussion in the section description. Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not. %TRUE if the key did not exist yet a #GHashTable a key to insert Checks if @key is in @hash_table. %TRUE if @key is in @hash_table, %FALSE otherwise. a #GHashTable a key to check Destroys all keys and values in the #GHashTable and decrements its reference count by 1. If keys and/or values are dynamically allocated, you should either free them first or create the #GHashTable with destroy notifiers using g_hash_table_new_full(). In the latter case the destroy functions you supplied will be called on all keys and values during the destruction phase. a #GHashTable Calls the given function for key/value pairs in the #GHashTable until @predicate returns %TRUE. The function is passed the key and value of each pair, and the given @user_data parameter. The hash table may not be modified while iterating over it (you can't add/remove items). Note, that hash tables are really only optimized for forward lookups, i.e. g_hash_table_lookup(). So code that frequently issues g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of once per every entry in a hash table) should probably be reworked to use additional or different data structures for reverse lookups (keep in mind that an O(n) find/foreach operation issued for all n values in a hash table ends up needing O(n*n) operations). The value of the first key/value pair is returned, for which @predicate evaluates to %TRUE. If no pair with the requested property is found, %NULL is returned. a #GHashTable function to test the key/value pairs for a certain property user data to pass to the function Calls the given function for each of the key/value pairs in the #GHashTable. The function is passed the key and value of each pair, and the given @user_data parameter. The hash table may not be modified while iterating over it (you can't add/remove items). To remove all items matching a predicate, use g_hash_table_foreach_remove(). The order in which g_hash_table_foreach() iterates over the keys/values in the hash table is not defined. See g_hash_table_find() for performance caveats for linear order searches in contrast to g_hash_table_lookup(). a #GHashTable the function to call for each key/value pair user data to pass to the function Calls the given function for each key/value pair in the #GHashTable. If the function returns %TRUE, then the key/value pair is removed from the #GHashTable. If you supplied key or value destroy functions when creating the #GHashTable, they are used to free the memory allocated for the removed keys and values. See #GHashTableIter for an alternative way to loop over the key/value pairs in the hash table. the number of key/value pairs removed a #GHashTable the function to call for each key/value pair user data to pass to the function Calls the given function for each key/value pair in the #GHashTable. If the function returns %TRUE, then the key/value pair is removed from the #GHashTable, but no key or value destroy functions are called. See #GHashTableIter for an alternative way to loop over the key/value pairs in the hash table. the number of key/value pairs removed. a #GHashTable the function to call for each key/value pair user data to pass to the function This function is deprecated and will be removed in the next major release of GLib. It does nothing. a #GHashTable Retrieves every key inside @hash_table, as a #GPtrArray. The returned data is valid until changes to the hash release those keys. This iterates over every entry in the hash table to build its return value. To iterate over the entries in a #GHashTable more efficiently, use a #GHashTableIter. You should always unref the returned array with g_ptr_array_unref(). a #GPtrArray containing each key from the table. Unref with g_ptr_array_unref() when done. a #GHashTable Retrieves every value inside @hash_table, as a #GPtrArray. The returned data is valid until changes to the hash release those values. This iterates over every entry in the hash table to build its return value. To iterate over the entries in a #GHashTable more efficiently, use a #GHashTableIter. You should always unref the returned array with g_ptr_array_unref(). a #GPtrArray containing each value from the table. Unref with g_ptr_array_unref() when done. a #GHashTable Inserts a new key and value into a #GHashTable. If the key already exists in the #GHashTable its current value is replaced with the new value. If you supplied a @value_destroy_func when creating the #GHashTable, the old value is freed using that function. If you supplied a @key_destroy_func when creating the #GHashTable, the passed key is freed using that function. Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not. %TRUE if the key did not exist yet a #GHashTable a key to insert the value to associate with the key Looks up a key in a #GHashTable. Note that this function cannot distinguish between a key that is not present and one which is present and has the value %NULL. If you need this distinction, use g_hash_table_lookup_extended(). the associated value, or %NULL if the key is not found a #GHashTable the key to look up Looks up a key in the #GHashTable, returning the original key and the associated value and a #gboolean which is %TRUE if the key was found. This is useful if you need to free the memory allocated for the original key, for example before calling g_hash_table_remove(). You can actually pass %NULL for @lookup_key to test whether the %NULL key exists, provided the hash and equal functions of @hash_table are %NULL-safe. %TRUE if the key was found in the #GHashTable a #GHashTable the key to look up return location for the original key return location for the value associated with the key Creates a new #GHashTable like g_hash_table_new_full() with a reference count of 1. It inherits the hash function, the key equal function, the key destroy function, as well as the value destroy function, from @other_hash_table. The returned hash table will be empty; it will not contain the keys or values from @other_hash_table. a new #GHashTable Another #GHashTable Atomically increments the reference count of @hash_table by one. This function is MT-safe and may be called from any thread. the passed in #GHashTable a valid #GHashTable Removes a key and its associated value from a #GHashTable. If the #GHashTable was created using g_hash_table_new_full(), the key and value are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself. %TRUE if the key was found and removed from the #GHashTable a #GHashTable the key to remove Removes all keys and their associated values from a #GHashTable. If the #GHashTable was created using g_hash_table_new_full(), the keys and values are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself. a #GHashTable Inserts a new key and value into a #GHashTable similar to g_hash_table_insert(). The difference is that if the key already exists in the #GHashTable, it gets replaced by the new key. If you supplied a @value_destroy_func when creating the #GHashTable, the old value is freed using that function. If you supplied a @key_destroy_func when creating the #GHashTable, the old key is freed using that function. Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not. %TRUE if the key did not exist yet a #GHashTable a key to insert the value to associate with the key Returns the number of elements contained in the #GHashTable. the number of key/value pairs in the #GHashTable. a #GHashTable Removes a key and its associated value from a #GHashTable without calling the key and value destroy functions. %TRUE if the key was found and removed from the #GHashTable a #GHashTable the key to remove Removes all keys and their associated values from a #GHashTable without calling the key and value destroy functions. a #GHashTable Removes all keys and their associated values from a #GHashTable without calling the key destroy functions, returning the keys as a #GPtrArray with the free func set to the @hash_table key destroy function. a #GPtrArray containing each key of the table. Unref with g_ptr_array_unref() when done. a #GHashTable Removes all keys and their associated values from a #GHashTable without calling the value destroy functions, returning the values as a #GPtrArray with the free func set to the @hash_table value destroy function. a #GPtrArray containing each value of the table. Unref with g_ptr_array_unref() when done. a #GHashTable Looks up a key in the #GHashTable, stealing the original key and the associated value and returning %TRUE if the key was found. If the key was not found, %FALSE is returned. If found, the stolen key and value are removed from the hash table without calling the key and value destroy functions, and ownership is transferred to the caller of this method, as with g_hash_table_steal(). That is the case regardless whether @stolen_key or @stolen_value output parameters are requested. You can pass %NULL for @lookup_key, provided the hash and equal functions of @hash_table are %NULL-safe. The dictionary implementation optimizes for having all values identical to their keys, for example by using g_hash_table_add(). Before 2.82, when stealing both the key and the value from such a dictionary, the value was %NULL. Since 2.82, the returned value and key will be the same. %TRUE if the key was found in the #GHashTable a #GHashTable the key to look up return location for the original key return location for the value associated with the key This function is deprecated and will be removed in the next major release of GLib. It does nothing. a #GHashTable Atomically decrements the reference count of @hash_table by one. If the reference count drops to 0, all keys and values will be destroyed, and all memory allocated by the hash table is released. This function is MT-safe and may be called from any thread. a valid #GHashTable Appends a #GHook onto the end of a #GHookList. a #GHookList the #GHook to add to the end of @hook_list Destroys a #GHook, given its ID. %TRUE if the #GHook was found in the #GHookList and destroyed a #GHookList a hook ID Removes one #GHook from a #GHookList, marking it inactive and calling g_hook_unref() on it. a #GHookList the #GHook to remove Calls the #GHookList @finalize_hook function if it exists, and frees the memory allocated for the #GHook. a #GHookList the #GHook to free Inserts a #GHook into a #GHookList, before a given #GHook. a #GHookList the #GHook to insert the new #GHook before the #GHook to insert Inserts a #GHook into a #GHookList, sorted by the given function. a #GHookList the #GHook to insert the comparison function used to sort the #GHook elements Prepends a #GHook on the start of a #GHookList. a #GHookList the #GHook to add to the start of @hook_list Decrements the reference count of a #GHook. If the reference count falls to 0, the #GHook is removed from the #GHookList and g_hook_free() is called to free it. a #GHookList the #GHook to unref Tests if @hostname contains segments with an ASCII-compatible encoding of an Internationalized Domain Name. If this returns %TRUE, you should decode the hostname with g_hostname_to_unicode() before displaying it to the user. Note that a hostname might contain a mix of encoded and unencoded segments, and so it is possible for g_hostname_is_non_ascii() and g_hostname_is_ascii_encoded() to both return %TRUE for a name. %TRUE if @hostname contains any ASCII-encoded segments. a hostname Tests if @hostname is the string form of an IPv4 or IPv6 address. (Eg, "192.168.0.1".) Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874). %TRUE if @hostname is an IP address a hostname (or IP address in string form) Tests if @hostname contains Unicode characters. If this returns %TRUE, you need to encode the hostname with g_hostname_to_ascii() before using it in non-IDN-aware contexts. Note that a hostname might contain a mix of encoded and unencoded segments, and so it is possible for g_hostname_is_non_ascii() and g_hostname_is_ascii_encoded() to both return %TRUE for a name. %TRUE if @hostname contains any non-ASCII characters a hostname Converts @hostname to its canonical ASCII form; an ASCII-only string containing no uppercase letters and not ending with a trailing dot. an ASCII hostname, which must be freed, or %NULL if @hostname is in some way invalid. a valid UTF-8 or ASCII hostname Converts @hostname to its canonical presentation form; a UTF-8 string in Unicode normalization form C, containing no uppercase letters, no forbidden characters, and no ASCII-encoded segments, and not ending with a trailing dot. Of course if @hostname is not an internationalized hostname, then the canonical presentation form will be entirely ASCII. a UTF-8 hostname, which must be freed, or %NULL if @hostname is in some way invalid. a valid UTF-8 or ASCII hostname Converts a 32-bit integer value from host to network byte order. a 32-bit integer value in host byte order Converts a 16-bit integer value from host to network byte order. a 16-bit integer value in host byte order Same as the standard UNIX routine iconv(), but may be implemented via libiconv on UNIX flavors that lack a native implementation. GLib provides g_convert() and g_locale_to_utf8() which are likely more convenient than the raw iconv wrappers. Note that the behaviour of iconv() for characters which are valid in the input character set, but which have no representation in the output character set, is implementation defined. This function may return success (with a positive number of non-reversible conversions as replacement characters were used), or it may return -1 and set an error such as %EILSEQ, in such a situation. See [`iconv(3posix)`](man:iconv(3posix)) and [`iconv(3)`](man:iconv(3)) for more details about behavior when an error occurs. count of non-reversible conversions, or -1 on error conversion descriptor from g_iconv_open() bytes to convert inout parameter, bytes remaining to convert in @inbuf converted output bytes inout parameter, bytes available to fill in @outbuf Same as the standard UNIX routine iconv_open(), but may be implemented via libiconv on UNIX flavors that lack a native implementation. GLib provides g_convert() and g_locale_to_utf8() which are likely more convenient than the raw iconv wrappers. a "conversion descriptor", or (GIConv)-1 if opening the converter failed. destination codeset source codeset Adds a function to be called whenever there are no higher priority events pending to the default main loop. The function is given the default idle priority, [const@GLib.PRIORITY_DEFAULT_IDLE]. If the function returns [const@GLib.SOURCE_REMOVE] it is automatically removed from the list of event sources and will not be called again. See [main loop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. This internally creates a main loop source using [func@GLib.idle_source_new] and attaches it to the global [struct@GLib.MainContext] using [method@GLib.Source.attach], so the callback will be invoked in whichever thread is running that main context. You can do these steps manually if you need greater control or to use a custom main context. the ID (greater than 0) of the event source function to call data to pass to @function Adds a function to be called whenever there are no higher priority events pending. If the function returns [const@GLib.SOURCE_REMOVE] it is automatically removed from the list of event sources and will not be called again. See [main loop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. This internally creates a main loop source using [func@GLib.idle_source_new] and attaches it to the global [struct@GLib.MainContext] using [method@GLib.Source.attach], so the callback will be invoked in whichever thread is running that main context. You can do these steps manually if you need greater control or to use a custom main context. the ID (greater than 0) of the event source the priority of the idle source; typically this will be in the range between [const@GLib.PRIORITY_DEFAULT_IDLE] and [const@GLib.PRIORITY_HIGH_IDLE] function to call data to pass to @function function to call when the idle is removed Adds a function to be called whenever there are no higher priority events pending to the default main loop. The function is given the default idle priority, [const@GLib.PRIORITY_DEFAULT_IDLE]. The function will only be called once and then the source will be automatically removed from the main context. This function otherwise behaves like [func@GLib.idle_add]. the ID (greater than 0) of the event source function to call data to pass to @function Removes the idle function with the given data. true if an idle source was found and removed, false otherwise the data for the idle source’s callback. Creates a new idle source. The source will not initially be associated with any [struct@GLib.MainContext] and must be added to one with [method@GLib.Source.attach] before it will be executed. Note that the default priority for idle sources is [const@GLib.PRIORITY_DEFAULT_IDLE], as compared to other sources which have a default priority of [const@GLib.PRIORITY_DEFAULT]. the newly-created idle source A convenience function/macro to log an informational message. Seldom used. If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. Such messages are suppressed by the [func@GLib.log_default_handler] and [func@GLib.log_writer_default] unless the `G_MESSAGES_DEBUG` or `DEBUG_INVOCATION` environment variables are set appropriately. If you need to set the allowed domains at runtime, use [func@GLib.log_writer_default_set_debug_domains]. If structured logging is enabled, this will use [func@GLib.log_structured]; otherwise it will use [func@GLib.log]. See [Using Structured Logging](logging.html#using-structured-logging). format string, followed by parameters to insert into the format string (as with `printf()`) Compares the two #gint64 values being pointed to and returns %TRUE if they are equal. It can be passed to g_hash_table_new() as the @key_equal_func parameter, when using non-%NULL pointers to 64-bit integers as keys in a #GHashTable. %TRUE if the two keys match. a pointer to a #gint64 key a pointer to a #gint64 key to compare with @v1 Converts a pointer to a #gint64 to a hash value. It can be passed to g_hash_table_new() as the @hash_func parameter, when using non-%NULL pointers to 64-bit integer values as keys in a #GHashTable. a hash value corresponding to the key. a pointer to a #gint64 key Compares the two #gint values being pointed to and returns %TRUE if they are equal. It can be passed to g_hash_table_new() as the @key_equal_func parameter, when using non-%NULL pointers to integers as keys in a #GHashTable. Note that this function acts on pointers to #gint, not on #gint directly: if your hash table's keys are of the form `GINT_TO_POINTER (n)`, use g_direct_equal() instead. %TRUE if the two keys match. a pointer to a #gint key a pointer to a #gint key to compare with @v1 Converts a pointer to a #gint to a hash value. It can be passed to g_hash_table_new() as the @hash_func parameter, when using non-%NULL pointers to integer values as keys in a #GHashTable. Note that this function acts on pointers to #gint, not on #gint directly: if your hash table's keys are of the form `GINT_TO_POINTER (n)`, use g_direct_hash() instead. a hash value corresponding to the key. a pointer to a #gint key Returns a canonical representation for @string. Interned strings can be compared for equality by comparing the pointers, instead of using strcmp(). g_intern_static_string() does not copy the string, therefore @string must not be freed or modified. This function must not be used before library constructors have finished running. In particular, this means it cannot be used to initialize global variables in C++. a canonical representation for the string a static string Returns a canonical representation for @string. Interned strings can be compared for equality by comparing the pointers, instead of using strcmp(). This function must not be used before library constructors have finished running. In particular, this means it cannot be used to initialize global variables in C++. a canonical representation for the string a string Adds the #GIOChannel into the default main loop context with the default priority. the event source id a #GIOChannel the condition to watch for the function to call when the condition is satisfied user data to pass to @func Adds the #GIOChannel into the default main loop context with the given priority. This internally creates a main loop source using g_io_create_watch() and attaches it to the main loop context with g_source_attach(). You can do these steps manually if you need greater control. the event source id a #GIOChannel the priority of the #GIOChannel source the condition to watch for the function to call when the condition is satisfied user data to pass to @func the function to call when the source is removed Converts an `errno` error number to a #GIOChannelError. a #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL. an `errno` error number, e.g. `EINVAL` Creates a #GSource that's dispatched when @condition is met for the given @channel. For example, if condition is %G_IO_IN, the source will be dispatched when there's data available for reading. The callback function invoked by the #GSource should be added with g_source_set_callback(), but it has type #GIOFunc (not #GSourceFunc). g_io_add_watch() is a simpler interface to this same functionality, for the case where you want to add the source to the default main loop context at the default priority. On Windows, polling a #GSource created to watch a channel for a socket puts the socket in non-blocking mode. This is a side-effect of the implementation and unavoidable. a new #GSource a #GIOChannel to watch conditions to watch for A convenience macro to get the next element in a #GList. Note that it is considered perfectly acceptable to access @list->next directly. an element in a #GList A convenience macro to get the previous element in a #GList. Note that it is considered perfectly acceptable to access @list->prev directly. an element in a #GList Gets the names of all variables set in the environment. Programs that want to be portable to Windows should typically use this function and g_getenv() instead of using the environ array from the C library directly. On Windows, the strings in the environ array are in system codepage encoding, while in most of the typical use cases for environment variables in GLib-using programs you want the UTF-8 encoding that this function and g_getenv() provide. a %NULL-terminated list of strings which must be freed with g_strfreev(). Converts a string from UTF-8 to the encoding used for strings by the C runtime (usually the same as that used by the operating system) in the [current locale](running.html#locale). On Windows this means the system codepage. The input string shall not contain nul characters even if the @len argument is positive. A nul character found inside the string will result in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Use g_convert() to convert input that may contain embedded nul characters. A newly-allocated buffer containing the converted string, or %NULL on an error, and error will be set. a UTF-8 encoded string the length of the string, or -1 if the string is nul-terminated. location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will be the byte offset after the last valid input sequence. the number of bytes stored in the output buffer (not including the terminating nul). Converts a string which is in the encoding used for strings by the C runtime (usually the same as that used by the operating system) in the [current locale](running.html#locale) into a UTF-8 string. If the source encoding is not UTF-8 and the conversion output contains a nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns %NULL. If the source encoding is UTF-8, an embedded nul character is treated with the %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error for backward compatibility with earlier versions of this library. Use g_convert() to produce output that may contain embedded nul characters. The converted string, or %NULL on an error. a string in the encoding of the current locale. On Windows this means the system codepage. the length of the string, or -1 if the string is nul-terminated (Note that some encodings may allow nul bytes to occur inside strings. In that case, using -1 for the @len parameter is unsafe) location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will be the byte offset after the last valid input sequence. the number of bytes stored in the output buffer (not including the terminating nul). Logs an error or debugging message. If the log level has been set as fatal, [func@GLib.BREAKPOINT] is called to terminate the program. See the documentation for [func@GLib.BREAKPOINT] for details of the debugging options this provides. If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. If [structured logging is enabled](logging.html#using-structured-logging) this will output via the structured log writer function (see [func@GLib.log_set_writer_func]). the log domain, usually `G_LOG_DOMAIN`, or `NULL` for the default the log level, either from [type@GLib.LogLevelFlags] or a user-defined level the message format. See the `printf()` documentation the parameters to insert into the format string The default log handler set up by GLib; [func@GLib.log_set_default_handler] allows to install an alternate default log handler. This is used if no log handler has been set for the particular log domain and log level combination. It outputs the message to `stderr` or `stdout` and if the log level is fatal it calls [func@GLib.BREAKPOINT]. It automatically prints a new-line character after the message, so one does not need to be manually included in @message. The behavior of this log handler can be influenced by a number of environment variables: - `G_MESSAGES_PREFIXED`: A `:`-separated list of log levels for which messages should be prefixed by the program name and PID of the application. - `G_MESSAGES_DEBUG`: A space-separated list of log domains for which debug and informational messages are printed. By default these messages are not printed. If you need to set the allowed domains at runtime, use [func@GLib.log_writer_default_set_debug_domains]. - `DEBUG_INVOCATION`: If set to `1`, this is equivalent to `G_MESSAGES_DEBUG=all`. `DEBUG_INVOCATION` is a standard environment variable set by systemd to prompt debug output. (Since: 2.84) `stderr` is used for levels [flags@GLib.LogLevelFlags.LEVEL_ERROR], [flags@GLib.LogLevelFlags.LEVEL_CRITICAL], [flags@GLib.LogLevelFlags.LEVEL_WARNING] and [flags@GLib.LogLevelFlags.LEVEL_MESSAGE]. `stdout` is used for the rest, unless `stderr` was requested by [func@GLib.log_writer_default_set_use_stderr]. This has no effect if structured logging is enabled; see [Using Structured Logging](logging.html#using-structured-logging). the log domain of the message, or `NULL` for the default `""` application domain the level of the message the message data passed from [func@GLib.log] which is unused Gets the current fatal mask. This is mostly used by custom log writers to make fatal messages (`fatal-warnings`, `fatal-criticals`) work as expected, when using the `G_DEBUG` environment variable (see [Running GLib Applications](running.html)). An example usage is shown below: ```c static GLogWriterOutput my_custom_log_writer_fn (GLogLevelFlags log_level, const GLogField *fields, gsize n_fields, gpointer user_data) { // abort if the message was fatal if (log_level & g_log_get_always_fatal ()) g_abort (); // custom log handling code ... ... // success return G_LOG_WRITER_HANDLED; } ``` the current fatal mask Return whether debug output from the GLib logging system is enabled. Note that this should not be used to conditionalise calls to [func@GLib.debug] or other logging functions; it should only be used from [type@GLib.LogWriterFunc] implementations. Note also that the value of this does not depend on `G_MESSAGES_DEBUG`, nor `DEBUG_INVOCATION`, nor [func@GLib.log_writer_default_set_debug_domains]; see the docs for [func@GLib.log_set_debug_enabled]. `TRUE` if debug output is enabled, `FALSE` otherwise Removes the log handler. This has no effect if structured logging is enabled; see [Using Structured Logging](logging.html#using-structured-logging). the log domain the ID of the handler, which was returned in [func@GLib.log_set_handler] Sets the message levels which are always fatal, in any log domain. When a message with any of these levels is logged the program terminates. You can only set the levels defined by GLib to be fatal. [flags@GLib.LogLevelFlags.LEVEL_ERROR] is always fatal. You can also make some message levels fatal at runtime by setting the `G_DEBUG` environment variable (see [Running GLib Applications](running.html)). Libraries should not call this function, as it affects all messages logged by a process, including those from other libraries. Structured log messages (using [func@GLib.log_structured] and [func@GLib.log_structured_array]) are fatal only if the default log writer is used; otherwise it is up to the writer function to determine which log messages are fatal. See [Using Structured Logging](logging.html#using-structured-logging). the old fatal mask the mask containing bits set for each level of error which is to be fatal Enable or disable debug output from the GLib logging system for all domains. This value interacts disjunctively with `G_MESSAGES_DEBUG`, `DEBUG_INVOCATION` and [func@GLib.log_writer_default_set_debug_domains] — if any of them would allow a debug message to be outputted, it will be. Note that this should not be used from within library code to enable debug output — it is intended for external use. `TRUE` to enable debug output, `FALSE` otherwise Installs a default log handler which is used if no log handler has been set for the particular log domain and log level combination. By default, GLib uses [func@GLib.log_default_handler] as default log handler. This has no effect if structured logging is enabled; see [Using Structured Logging](logging.html#using-structured-logging). the previous default log handler the log handler function data passed to the log handler Sets the log levels which are fatal in the given domain. [flags@GLib.LogLevelFlags.LEVEL_ERROR] is always fatal. This has no effect on structured log messages (using [func@GLib.log_structured] or [func@GLib.log_structured_array]). To change the fatal behaviour for specific log messages, programs must install a custom log writer function using [func@GLib.log_set_writer_func]. See [Using Structured Logging](logging.html#using-structured-logging). This function is mostly intended to be used with [flags@GLib.LogLevelFlags.LEVEL_CRITICAL]. You should typically not set [flags@GLib.LogLevelFlags.LEVEL_WARNING], [flags@GLib.LogLevelFlags.LEVEL_MESSAGE], [flags@GLib.LogLevelFlags.LEVEL_INFO] or [flags@GLib.LogLevelFlags.LEVEL_DEBUG] as fatal except inside of test programs. the old fatal mask for the log domain the log domain the new fatal mask Sets the log handler for a domain and a set of log levels. To handle fatal and recursive messages the @log_levels parameter must be combined with the [flags@GLib.LogLevelFlags.FLAG_FATAL] and [flags@GLib.LogLevelFlags.FLAG_RECURSION] bit flags. Note that since the [flags@GLib.LogLevelFlags.LEVEL_ERROR] log level is always fatal, if you want to set a handler for this log level you must combine it with [flags@GLib.LogLevelFlags.FLAG_FATAL]. This has no effect if structured logging is enabled; see [Using Structured Logging](logging.html#using-structured-logging). The `log_domain` parameter can be set to `NULL` or an empty string to use the default application domain. Here is an example for adding a log handler for all warning messages in the default domain: ```c g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); ``` This example adds a log handler for all critical messages from GTK: ```c g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); ``` This example adds a log handler for all messages from GLib: ```c g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); ``` the id of the new handler the log domain application domain the log levels to apply the log handler for. To handle fatal and recursive messages as well, combine the log levels with the [flags@GLib.LogLevelFlags.FLAG_FATAL] and [flags@GLib.LogLevelFlags.FLAG_RECURSION] bit flags. the log handler function data passed to the log handler Like [func@GLib.log_set_handler], but takes a destroy notify for the @user_data. This has no effect if structured logging is enabled; see [Using Structured Logging](logging.html#using-structured-logging). The `log_domain` parameter can be set to `NULL` or an empty string to use the default application domain. the ID of the new handler the log domain application domain the log levels to apply the log handler for. To handle fatal and recursive messages as well, combine the log levels with the [flags@GLib.LogLevelFlags.FLAG_FATAL] and [flags@GLib.LogLevelFlags.FLAG_RECURSION] bit flags. the log handler function data passed to the log handler destroy notify for @user_data, or `NULL` Set a writer function which will be called to format and write out each log message. Each program should set a writer function, or the default writer ([func@GLib.log_writer_default]) will be used. Libraries **must not** call this function — only programs are allowed to install a writer function, as there must be a single, central point where log messages are formatted and outputted. There can only be one writer function. It is an error to set more than one. log writer function, which must not be `NULL` user data to pass to @func function to free @user_data once it’s finished with, if non-`NULL` Log a message with structured data. The message will be passed through to the log writer set by the application using [func@GLib.log_set_writer_func]. If the message is fatal (i.e. its log level is [flags@GLib.LogLevelFlags.LEVEL_ERROR]), the program will be aborted by calling [func@GLib.BREAKPOINT] at the end of this function. If the log writer returns [enum@GLib.LogWriterOutput.UNHANDLED] (failure), no other fallback writers will be tried. See the documentation for [type@GLib.LogWriterFunc] for information on chaining writers. The structured data is provided as key–value pairs, where keys are UTF-8 strings, and values are arbitrary pointers — typically pointing to UTF-8 strings, but that is not a requirement. To pass binary (non-nul-terminated) structured data, use [func@GLib.log_structured_array]. The keys for structured data should follow the [systemd journal fields](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html) specification. It is suggested that custom keys are namespaced according to the code which sets them. For example, custom keys from GLib all have a `GLIB_` prefix. Note that keys that expect UTF-8 strings (specifically `"MESSAGE"` and `"GLIB_DOMAIN"`) must be passed as nul-terminated UTF-8 strings until GLib version 2.74.1 because the default log handler did not consider the length of the `GLogField`. Starting with GLib 2.74.1 this is fixed and non-nul-terminated UTF-8 strings can be passed with their correct length, with the exception of `"GLIB_DOMAIN"` which was only fixed with GLib 2.82.3. The @log_domain will be converted into a `GLIB_DOMAIN` field. @log_level will be converted into a [`PRIORITY`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#PRIORITY=) field. The format string will have its placeholders substituted for the provided values and be converted into a [`MESSAGE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE=) field. Other fields you may commonly want to pass into this function: * [`MESSAGE_ID`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=) * [`CODE_FILE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=) * [`CODE_LINE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_LINE=) * [`CODE_FUNC`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FUNC=) * [`ERRNO`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=) Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by the logging macros, [func@GLib.DEBUG_HERE], [func@GLib.message], [func@GLib.warning], [func@GLib.critical], [func@GLib.error], etc, if the symbol `G_LOG_USE_STRUCTURED` is defined before including `glib.h`. For example: ```c g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", "MY_APPLICATION_CUSTOM_FIELD", "some debug string", "MESSAGE", "This is a debug message about pointer %p and integer %u.", some_pointer, some_integer); ``` Note that each `MESSAGE_ID` must be [uniquely and randomly generated](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=). If adding a `MESSAGE_ID`, consider shipping a [message catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with your software. To pass a user data pointer to the log writer function which is specific to this logging call, you must use [func@GLib.log_structured_array] and pass the pointer as a field with `GLogField.length` set to zero, otherwise it will be interpreted as a string. For example: ```c const GLogField fields[] = { { "MESSAGE", "This is a debug message.", -1 }, { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 }, { "MY_APPLICATION_CUSTOM_FIELD", "some debug string", -1 }, { "MY_APPLICATION_STATE", state_object, 0 }, }; g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields)); ``` Note also that, even if no other structured fields are specified, there must always be a `MESSAGE` key before the format string. The `MESSAGE`-format pair has to be the last of the key-value pairs, and `MESSAGE` is the only field for which `printf()`-style formatting is supported. The default writer function for `stdout` and `stderr` will automatically append a new-line character after the message, so you should not add one manually to the format string. log domain, usually `G_LOG_DOMAIN` log level, either from [type@GLib.LogLevelFlags], or a user-defined level key-value pairs of structured data to add to the log entry, followed by the key `MESSAGE`, followed by a `printf()`-style message format, followed by parameters to insert in the format string Log a message with structured data. The message will be passed through to the log writer set by the application using [func@GLib.log_set_writer_func]. If the message is fatal (i.e. its log level is [flags@GLib.LogLevelFlags.LEVEL_ERROR]), the program will be aborted at the end of this function. See [func@GLib.log_structured] for more documentation. This assumes that @log_level is already present in @fields (typically as the `PRIORITY` field). log level, either from [type@GLib.LogLevelFlags], or a user-defined level key–value pairs of structured data to add to the log message number of elements in the @fields array Log a message with structured data, accepting the data within a [type@GLib.Variant]. This version is especially useful for use in other languages, via introspection. The only mandatory item in the @fields dictionary is the `"MESSAGE"` which must contain the text shown to the user. The values in the @fields dictionary are likely to be of type `G_VARIANT_TYPE_STRING`. Array of bytes (`G_VARIANT_TYPE_BYTESTRING`) is also supported. In this case the message is handled as binary and will be forwarded to the log writer as such. The size of the array should not be higher than `G_MAXSSIZE`. Otherwise it will be truncated to this size. For other types [method@GLib.Variant.print] will be used to convert the value into a string. For more details on its usage and about the parameters, see [func@GLib.log_structured]. log domain, usually `G_LOG_DOMAIN` log level, either from [type@GLib.LogLevelFlags], or a user-defined level a dictionary ([type@GLib.Variant] of the type `G_VARIANT_TYPE_VARDICT`) containing the key-value pairs of message data. Format a structured log message and output it to the default log destination for the platform. On Linux, this is typically the systemd journal, falling back to `stdout` or `stderr` if running from the terminal or if output is being redirected to a file. Support for other platform-specific logging mechanisms may be added in future. Distributors of GLib may modify this function to impose their own (documented) platform-specific log writing policies. This is suitable for use as a [type@GLib.LogWriterFunc], and is the default writer used if no other is set using [func@GLib.log_set_writer_func]. As with [func@GLib.log_default_handler], this function drops debug and informational messages unless their log domain (or `all`) is listed in the space-separated `G_MESSAGES_DEBUG` environment variable, or `DEBUG_INVOCATION=1` is set in the environment, or set at runtime by [func@GLib.log_writer_default_set_debug_domains]. [func@GLib.log_writer_default] uses the mask set by [func@GLib.log_set_always_fatal] to determine which messages are fatal. When using a custom writer function instead it is up to the writer function to determine which log messages are fatal. [enum@GLib.LogWriterOutput.HANDLED] on success, [enum@GLib.LogWriterOutput.UNHANDLED] otherwise log level, either from [type@GLib.LogLevelFlags], or a user-defined level key–value pairs of structured data forming the log message number of elements in the @fields array user data passed to [func@GLib.log_set_writer_func] Reset the list of domains to be logged, that might be initially set by the `G_MESSAGES_DEBUG` or `DEBUG_INVOCATION` environment variables. This function is thread-safe. `NULL`-terminated array with domains to be printed. `NULL` or an array with no values means none. Array with a single value `"all"` means all. Configure whether the built-in log functions will output all log messages to `stderr`. The built-in log functions are [func@GLib.log_default_handler] for the old-style API, and both [func@GLib.log_writer_default] and [func@GLib.log_writer_standard_streams] for the structured API. By default, log messages of levels [flags@GLib.LogLevelFlags.LEVEL_INFO] and [flags@GLib.LogLevelFlags.LEVEL_DEBUG] are sent to `stdout`, and other log messages are sent to `stderr`. This is problematic for applications that intend to reserve `stdout` for structured output such as JSON or XML. This function sets global state. It is not thread-aware, and should be called at the very start of a program, before creating any other threads or creating objects that could create worker threads of their own. If `TRUE`, use `stderr` for log messages that would normally have appeared on `stdout` Check whether [func@GLib.log_writer_default] and [func@GLib.log_default_handler] would ignore a message with the given domain and level. As with [func@GLib.log_default_handler], this function drops debug and informational messages unless their log domain (or `all`) is listed in the space-separated `G_MESSAGES_DEBUG` environment variable, or `DEBUG_INVOCATION=1` is set in the environment, or by [func@GLib.log_writer_default_set_debug_domains]. This can be used when implementing log writers with the same filtering behaviour as the default, but a different destination or output format: ```c if (g_log_writer_default_would_drop (log_level, log_domain)) return G_LOG_WRITER_HANDLED; ]| or to skip an expensive computation if it is only needed for a debugging message, and `G_MESSAGES_DEBUG` and `DEBUG_INVOCATION` are not set: ```c if (!g_log_writer_default_would_drop (G_LOG_LEVEL_DEBUG, G_LOG_DOMAIN)) { g_autofree gchar *result = expensive_computation (my_object); g_debug ("my_object result: %s", result); } ``` `TRUE` if the log message would be dropped by GLib’s default log handlers log level, either from [type@GLib.LogLevelFlags], or a user-defined level log domain Format a structured log message as a string suitable for outputting to the terminal (or elsewhere). This will include the values of all fields it knows how to interpret, which includes `MESSAGE` and `GLIB_DOMAIN` (see the documentation for [func@GLib.log_structured]). It does not include values from unknown fields. The returned string does **not** have a trailing new-line character. It is encoded in the character set of the current locale, which is not necessarily UTF-8. string containing the formatted log message, in the character set of the current locale log level, either from [type@GLib.LogLevelFlags], or a user-defined level key–value pairs of structured data forming the log message number of elements in the @fields array `TRUE` to use [ANSI color escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) when formatting the message, `FALSE` to not Check whether the given @output_fd file descriptor is a connection to the systemd journal, or something else (like a log file or `stdout` or `stderr`). Invalid file descriptors are accepted and return `FALSE`, which allows for the following construct without needing any additional error handling: ```c is_journald = g_log_writer_is_journald (fileno (stderr)); ``` `TRUE` if @output_fd points to the journal, `FALSE` otherwise output file descriptor to check Format a structured log message and send it to the systemd journal as a set of key–value pairs. All fields are sent to the journal, but if a field has length zero (indicating program-specific data) then only its key will be sent. This is suitable for use as a [type@GLib.LogWriterFunc]. If GLib has been compiled without systemd support, this function is still defined, but will always return [enum@GLib.LogWriterOutput.UNHANDLED]. [enum@GLib.LogWriterOutput.HANDLED] on success, [enum@GLib.LogWriterOutput.UNHANDLED] otherwise log level, either from [type@GLib.LogLevelFlags], or a user-defined level key–value pairs of structured data forming the log message number of elements in the @fields array user data passed to [func@GLib.log_set_writer_func] Format a structured log message and print it to either `stdout` or `stderr`, depending on its log level. [flags@GLib.LogLevelFlags.LEVEL_INFO] and [flags@GLib.LogLevelFlags.LEVEL_DEBUG] messages are sent to `stdout`, or to `stderr` if requested by [func@GLib.log_writer_default_set_use_stderr]; all other log levels are sent to `stderr`. Only fields which are understood by this function are included in the formatted string which is printed. If the output stream supports [ANSI color escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code), they will be used in the output. A trailing new-line character is added to the log message when it is printed. This is suitable for use as a [type@GLib.LogWriterFunc]. [enum@GLib.LogWriterOutput.HANDLED] on success, [enum@GLib.LogWriterOutput.UNHANDLED] otherwise log level, either from [type@GLib.LogLevelFlags], or a user-defined level key–value pairs of structured data forming the log message number of elements in the @fields array user data passed to [func@GLib.log_set_writer_func] Check whether the given @output_fd file descriptor supports [ANSI color escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code). If so, they can safely be used when formatting log messages. `TRUE` if ANSI color escapes are supported, `FALSE` otherwise output file descriptor to check Format a structured log message and send it to the syslog daemon. Only fields which are understood by this function are included in the formatted string which is printed. Log facility will be defined via the SYSLOG_FACILITY field and accepts the following values: "auth", "daemon", and "user". If SYSLOG_FACILITY is not specified, LOG_USER facility will be used. This is suitable for use as a [type@GLib.LogWriterFunc]. If syslog is not supported, this function is still defined, but will always return [enum@GLib.LogWriterOutput.UNHANDLED]. [enum@GLib.LogWriterOutput.HANDLED] on success, [enum@GLib.LogWriterOutput.UNHANDLED] otherwise log level, either from [type@GLib.LogLevelFlags], or a user-defined level key–value pairs of structured data forming the log message number of elements in the @fields array user data passed to [func@GLib.log_set_writer_func] Logs an error or debugging message. If the log level has been set as fatal, [func@GLib.BREAKPOINT] is called to terminate the program. See the documentation for [func@GLib.BREAKPOINT] for details of the debugging options this provides. If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. If [structured logging is enabled](logging.html#using-structured-logging) this will output via the structured log writer function (see [func@GLib.log_set_writer_func]). The `log_domain` parameter can be set to `NULL` or an empty string to use the default application domain. the log domain application domain the log level the message format. See the `printf()` documentation the parameters to insert into the format string A wrapper for the POSIX lstat() function. The lstat() function is like stat() except that in the case of symbolic links, it returns information about the symbolic link itself and not the file that it refers to. If the system does not support symbolic links g_lstat() is identical to g_stat(). See your C library manual for more details about lstat(). 0 if the information was successfully retrieved, -1 if an error occurred a pathname in the GLib file name encoding (UTF-8 on Windows) a pointer to a stat struct, which will be filled with the file information Returns the global-default main context. This is the main context used for main loop functions when a main loop is not explicitly specified, and corresponds to the ‘main’ main loop. See also [func@GLib.MainContext.get_thread_default]. the global-default main context. Gets the thread-default main context for this thread. Asynchronous operations that want to be able to be run in contexts other than the default one should call this method or [func@GLib.MainContext.ref_thread_default] to get a [struct@GLib.MainContext] to add their [struct@GLib.Source]s to. (Note that even in single-threaded programs applications may sometimes want to temporarily push a non-default context, so it is not safe to assume that this will always return `NULL` if you are running in the default thread.) If you need to hold a reference on the context, use [func@GLib.MainContext.ref_thread_default] instead. the thread-default main context, or `NULL` if the thread-default context is the global-default main context Gets a reference to the thread-default [struct@GLib.MainContext] for this thread This is the same as [func@GLib.MainContext.get_thread_default], but it also adds a reference to the returned main context with [method@GLib.MainContext.ref]. In addition, unlike [func@GLib.MainContext.get_thread_default], if the thread-default context is the global-default context, this will return that [struct@GLib.MainContext] (with a ref added to it) rather than returning `NULL`. the thread-default main context Returns the currently firing source for this thread. the currently firing source, or `NULL` if none is firing Returns the depth of the stack of calls to [method@GLib.MainContext.dispatch] on any #GMainContext in the current thread. That is, when called from the top level, it gives `0`. When called from within a callback from [method@GLib.MainContext.iteration] (or [method@GLib.MainLoop.run], etc.) it returns `1`. When called from within a callback to a recursive call to [method@GLib.MainContext.iteration], it returns `2`. And so forth. This function is useful in a situation like the following: Imagine an extremely simple ‘garbage collected’ system. ```c static GList *free_list; gpointer allocate_memory (gsize size) { gpointer result = g_malloc (size); free_list = g_list_prepend (free_list, result); return result; } void free_allocated_memory (void) { GList *l; for (l = free_list; l; l = l->next); g_free (l->data); g_list_free (free_list); free_list = NULL; } [...] while (TRUE); { g_main_context_iteration (NULL, TRUE); free_allocated_memory(); } ``` This works from an application, however, if you want to do the same thing from a library, it gets more difficult, since you no longer control the main loop. You might think you can simply use an idle function to make the call to `free_allocated_memory()`, but that doesn’t work, since the idle function could be called from a recursive callback. This can be fixed by using [func@GLib.main_depth] ```c gpointer allocate_memory (gsize size) { FreeListBlock *block = g_new (FreeListBlock, 1); block->mem = g_malloc (size); block->depth = g_main_depth (); free_list = g_list_prepend (free_list, block); return block->mem; } void free_allocated_memory (void) { GList *l; int depth = g_main_depth (); for (l = free_list; l; ); { GList *next = l->next; FreeListBlock *block = l->data; if (block->depth > depth) { g_free (block->mem); g_free (block); free_list = g_list_delete_link (free_list, l); } l = next; } } ``` There is a temptation to use [func@GLib.main_depth] to solve problems with reentrancy. For instance, while waiting for data to be received from the network in response to a menu item, the menu item might be selected again. It might seem that one could make the menu item’s callback return immediately and do nothing if [func@GLib.main_depth] returns a value greater than 1. However, this should be avoided since the user then sees selecting the menu item do nothing. Furthermore, you’ll find yourself adding these checks all over your code, since there are doubtless many, many things that the user could do. Instead, you can use the following techniques: 1. Use `gtk_widget_set_sensitive()` or modal dialogs to prevent the user from interacting with elements while the main loop is recursing. 2. Avoid main loop recursion in situations where you can’t handle arbitrary callbacks. Instead, structure your code so that you simply return to the main loop and then get called again when there is more work to do. the main loop recursion level in the current thread Frees the memory allocated for the #GMainLoop. Use g_main_loop_unref() instead a #GMainLoop Checks if the main loop is running. Use g_main_loop_is_running() instead a #GMainLoop Runs a single iteration for the default #GMainContext. Use g_main_context_iteration() instead. set to %TRUE if it should block (i.e. wait) until an event source becomes ready. It will return after an event source has been processed. If set to %FALSE it will return immediately if no event source is ready to be processed. Creates a new #GMainLoop for th default main context. Use g_main_loop_new() instead set to %TRUE to indicate that the loop is running. This is not very important since calling g_main_run() will set this to %TRUE anyway. Checks if any events are pending for the default #GMainContext (i.e. ready to be processed). Use g_main_context_pending() instead. Stops the #GMainLoop. If g_main_run() was called to run the #GMainLoop, it will now return. Use g_main_loop_quit() instead a #GMainLoop Runs a main loop until it stops running. Use g_main_loop_run() instead a #GMainLoop Sets the function to use for the handle polling of file descriptors for the default main context. Use g_main_context_set_poll_func() again the function to call to poll all file descriptors Allocates @n_bytes bytes of memory. If @n_bytes is 0 it returns %NULL. If the allocation fails (because the system is out of memory), the program is terminated. a pointer to the allocated memory the number of bytes to allocate Allocates @n_bytes bytes of memory, initialized to 0's. If @n_bytes is 0 it returns %NULL. If the allocation fails (because the system is out of memory), the program is terminated. a pointer to the allocated memory the number of bytes to allocate This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication. If the allocation fails (because the system is out of memory), the program is terminated. a pointer to the allocated memory the number of blocks to allocate the size of each block in bytes This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication. If the allocation fails (because the system is out of memory), the program is terminated. a pointer to the allocated memory the number of blocks to allocate the size of each block in bytes Collects the attributes of the element from the data passed to the #GMarkupParser start_element function, dealing with common error conditions and supporting boolean values. This utility function is not required to write a parser but can save a lot of typing. The @element_name, @attribute_names, @attribute_values and @error parameters passed to the start_element callback should be passed unmodified to this function. Following these arguments is a list of "supported" attributes to collect. It is an error to specify multiple attributes with the same name. If any attribute not in the list appears in the @attribute_names array then an unknown attribute error will result. The #GMarkupCollectType field allows specifying the type of collection to perform and if a given attribute must appear or is optional. The attribute name is simply the name of the attribute to collect. The pointer should be of the appropriate type (see the descriptions under #GMarkupCollectType) and may be %NULL in case a particular attribute is to be allowed but ignored. This function deals with issuing errors for missing attributes (of type %G_MARKUP_ERROR_MISSING_ATTRIBUTE), unknown attributes (of type %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE) and duplicate attributes (of type %G_MARKUP_ERROR_INVALID_CONTENT) as well as parse errors for boolean-valued attributes (again of type %G_MARKUP_ERROR_INVALID_CONTENT). In all of these cases %FALSE will be returned and @error will be set as appropriate. %TRUE if successful the current tag name the attribute names the attribute values a pointer to a #GError or %NULL the #GMarkupCollectType of the first attribute the name of the first attribute a pointer to the storage location of the first attribute (or %NULL), followed by more types names and pointers, ending with %G_MARKUP_COLLECT_INVALID Escapes text so that the markup parser will parse it verbatim. Less than, greater than, ampersand, etc. are replaced with the corresponding entities. This function would typically be used when writing out a file to be parsed with the markup parser. Note that this function doesn't protect whitespace and line endings from being processed according to the XML rules for normalization of line endings and attribute values. Note also that this function will produce character references in the range of &#x1; ... &#x1f; for all control sequences except for tabstop, newline and carriage return. The character references in this range are not valid XML 1.0, but they are valid XML 1.1 and will be accepted by the GMarkup parser. a newly allocated string with the escaped text some valid UTF-8 text length of @text in bytes, or -1 if the text is nul-terminated Formats arguments according to @format, escaping all string and character arguments in the fashion of g_markup_escape_text(). This is useful when you want to insert literal strings into XML-style markup output, without having to worry that the strings might themselves contain markup. |[<!-- language="C" --> const char *store = "Fortnum & Mason"; const char *item = "Tea"; char *output; output = g_markup_printf_escaped ("<purchase>" "<store>%s</store>" "<item>%s</item>" "</purchase>", store, item); ]| newly allocated result from formatting operation. Free with g_free(). printf() style format string the arguments to insert in the format string Formats the data in @args according to @format, escaping all string and character arguments in the fashion of g_markup_escape_text(). See g_markup_printf_escaped(). newly allocated result from formatting operation. Free with g_free(). printf() style format string variable argument list, similar to vprintf() Checks whether the allocator used by g_malloc() is the system's malloc implementation. If it returns %TRUE memory allocated with malloc() can be used interchangeably with memory allocated using g_malloc(). This function is useful for avoiding an extra copy of allocated memory returned by a non-GLib-based API. GLib always uses the system malloc, so this function always returns %TRUE. if %TRUE, malloc() and g_malloc() can be mixed. GLib used to support some tools for memory profiling, but this no longer works. There are many other useful tools for memory profiling these days which can be used instead. Use other memory profiling tools instead This function used to let you override the memory allocation function. However, its use was incompatible with the use of global constructors in GLib and GIO, because those use the GLib allocators before main is reached. Therefore this function is now deprecated and is just a stub. This function now does nothing. Use other memory profiling tools instead table of memory allocation routines. Allocates @byte_size bytes of memory, and copies @byte_size bytes into it from @mem. If @mem is `NULL` it returns `NULL`. Use [func@GLib.memdup2] instead, as it accepts a gsize argument for @byte_size, avoiding the possibility of overflow in a `gsize` → `guint` conversion a pointer to the newly-allocated copy of the memory the memory to copy the number of bytes to copy Allocates @byte_size bytes of memory, and copies @byte_size bytes into it from @mem. If @mem is `NULL` it returns `NULL`. This replaces [func@GLib.memdup], which was prone to integer overflows when converting the argument from a `gsize` to a `guint`. a pointer to the newly-allocated copy of the memory the memory to copy the number of bytes to copy Copies a block of memory @len bytes long, from @src to @dest. The source and destination areas may overlap. Just use memmove(). the destination address to copy the bytes to. the source address to copy the bytes from. the number of bytes to copy. A convenience function/macro to log a normal message. If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. If structured logging is enabled, this will use [func@GLib.log_structured]; otherwise it will use [func@GLib.log]. See [Using Structured Logging](logging.html#using-structured-logging). format string, followed by parameters to insert into the format string (as with `printf()`) A wrapper for the POSIX mkdir() function. The mkdir() function attempts to create a directory with the given name and permissions. The mode argument is ignored on Windows. See your C library manual for more details about mkdir(). 0 if the directory was successfully created, -1 if an error occurred a pathname in the GLib file name encoding (UTF-8 on Windows) permissions to use for the newly created directory Create a directory if it doesn't already exist. Create intermediate parent directories as needed, too. 0 if the directory already exists, or was successfully created. Returns -1 if an error occurred, with errno set. a pathname in the GLib file name encoding permissions to use for newly created directories Creates a temporary directory in the current directory. See the [`mkdtemp()`](man:mkdtemp(3)) documentation on most UNIX-like systems. The parameter is a string that should follow the rules for mkdtemp() templates, i.e. contain the string "XXXXXX". g_mkdtemp() is slightly more flexible than mkdtemp() in that the sequence does not have to occur at the very end of the template. The X string will be modified to form the name of a directory that didn't exist. The string should be in the GLib file name encoding. Most importantly, on Windows it should be in UTF-8. If you are going to be creating a temporary directory inside the directory returned by g_get_tmp_dir(), you might want to use g_dir_make_tmp() instead. A pointer to @tmpl, which has been modified to hold the directory name. In case of errors, %NULL is returned and %errno will be set. template directory name Creates a temporary directory in the current directory. See the [`mkdtemp()`](man:mkdtemp(3)) documentation on most UNIX-like systems. The parameter is a string that should follow the rules for mkdtemp() templates, i.e. contain the string "XXXXXX". g_mkdtemp_full() is slightly more flexible than mkdtemp() in that the sequence does not have to occur at the very end of the template and you can pass a @mode. The X string will be modified to form the name of a directory that didn't exist. The string should be in the GLib file name encoding. Most importantly, on Windows it should be in UTF-8. If you are going to be creating a temporary directory inside the directory returned by g_get_tmp_dir(), you might want to use g_dir_make_tmp() instead. A pointer to @tmpl, which has been modified to hold the directory name. In case of errors, %NULL is returned, and %errno will be set. template directory name permissions to create the temporary directory with Opens a temporary file in the current directory. See the [`mkstemp()`](man:mkstemp(3)) documentation on most UNIX-like systems. The parameter is a string that should follow the rules for mkstemp() templates, i.e. contain the string "XXXXXX". g_mkstemp() is slightly more flexible than mkstemp() in that the sequence does not have to occur at the very end of the template. The X string will be modified to form the name of a file that didn't exist. The string should be in the GLib file name encoding. Most importantly, on Windows it should be in UTF-8. A file handle (as from open()) to the file opened for reading and writing. The file is opened in binary mode on platforms where there is a difference. The file handle should be closed with close(). In case of errors, -1 is returned and %errno will be set. template filename Opens a temporary file in the current directory. See the [`mkstemp()`](man:mkstemp(3)) documentation on most UNIX-like systems. The parameter is a string that should follow the rules for mkstemp() templates, i.e. contain the string "XXXXXX". g_mkstemp_full() is slightly more flexible than mkstemp() in that the sequence does not have to occur at the very end of the template and you can pass a @mode and additional @flags. The X string will be modified to form the name of a file that didn't exist. The string should be in the GLib file name encoding. Most importantly, on Windows it should be in UTF-8. A file handle (as from open()) to the file opened for reading and writing. The file handle should be closed with close(). In case of errors, -1 is returned and %errno will be set. template filename flags to pass to an open() call in addition to O_EXCL and O_CREAT, which are passed automatically permissions to create the temporary file with Allocates and initializes a new #GMutex. GMutex can now be statically allocated, or embedded in structures and initialised with g_mutex_init(). a newly allocated #GMutex. Use g_mutex_free() to free Allocates @n_structs elements of type @struct_type. The returned pointer is cast to a pointer to the given type. If @n_structs is 0 it returns %NULL. Care is taken to avoid overflow when calculating the size of the allocated block. Since the returned pointer is already casted to the right type, it is normally unnecessary to cast it explicitly, and doing so might hide memory allocation errors. the type of the elements to allocate the number of elements to allocate Allocates @n_structs elements of type @struct_type, initialized to 0's. The returned pointer is cast to a pointer to the given type. If @n_structs is 0 it returns %NULL. Care is taken to avoid overflow when calculating the size of the allocated block. Since the returned pointer is already casted to the right type, it is normally unnecessary to cast it explicitly, and doing so might hide memory allocation errors. the type of the elements to allocate. the number of elements to allocate. Wraps g_alloca() in a more typesafe manner. As mentioned in the documentation for g_alloca(), @n_structs must always be entirely under the control of the program, or you may introduce a denial of service vulnerability. In addition, the multiplication of @struct_type by @n_structs is not checked, so an overflow may lead to a remote code execution vulnerability. Type of memory chunks to be allocated Number of chunks to be allocated Wraps g_alloca0() in a more typesafe manner. the type of the elements to allocate. the number of elements to allocate. Inserts a #GNode as the last child of the given parent. the #GNode to place the new #GNode under the #GNode to insert Inserts a new #GNode as the last child of the given parent. the #GNode to place the new #GNode under the data for the new #GNode Gets the first child of a #GNode. a #GNode Inserts a new #GNode at the given position. the #GNode to place the new #GNode under the position to place the new #GNode at. If position is -1, the new #GNode is inserted as the last child of @parent the data for the new #GNode Inserts a new #GNode after the given sibling. the #GNode to place the new #GNode under the sibling #GNode to place the new #GNode after the data for the new #GNode Inserts a new #GNode before the given sibling. the #GNode to place the new #GNode under the sibling #GNode to place the new #GNode before the data for the new #GNode Gets the next sibling of a #GNode. a #GNode Inserts a new #GNode as the first child of the given parent. the #GNode to place the new #GNode under the data for the new #GNode Gets the previous sibling of a #GNode. a #GNode Converts a 32-bit integer value from network to host byte order. a 32-bit integer value in network byte order Converts a 16-bit integer value from network to host byte order. a 16-bit integer value in network byte order Set the pointer at the specified location to %NULL. the memory address of the pointer. Prompts the user with `[E]xit, [H]alt, show [S]tack trace or [P]roceed`. This function is intended to be used for debugging use only. The following example shows how it can be used together with the g_log() functions. |[<!-- language="C" --> #include <glib.h> static void log_handler (const gchar *log_domain, GLogLevelFlags log_level, const gchar *message, gpointer user_data) { g_log_default_handler (log_domain, log_level, message, user_data); g_on_error_query (MY_PROGRAM_NAME); } int main (int argc, char *argv[]) { g_log_set_handler (MY_LOG_DOMAIN, G_LOG_LEVEL_WARNING | G_LOG_LEVEL_ERROR | G_LOG_LEVEL_CRITICAL, log_handler, NULL); ... ]| If "[E]xit" is selected, the application terminates with a call to _exit(0). If "[S]tack" trace is selected, g_on_error_stack_trace() is called. This invokes gdb, which attaches to the current process and shows a stack trace. The prompt is then shown again. If "[P]roceed" is selected, the function returns. This function may cause different actions on non-UNIX platforms. On Windows consider using the `G_DEBUGGER` environment variable (see [Running GLib Applications](running.html)) and calling g_on_error_stack_trace() instead. the program name, needed by gdb for the "[S]tack trace" option. If @prg_name is %NULL, g_get_prgname() is called to get the program name (which will work correctly if gdk_init() or gtk_init() has been called) Invokes gdb, which attaches to the current process and shows a stack trace. Called by g_on_error_query() when the "[S]tack trace" option is selected. You can get the current process's program name with g_get_prgname(), assuming that you have called gtk_init() or gdk_init(). This function may cause different actions on non-UNIX platforms. When running on Windows, this function is *not* called by g_on_error_query(). If called directly, it will raise an exception, which will crash the program. If the `G_DEBUGGER` environment variable is set, a debugger will be invoked to attach and handle that exception (see [Running GLib Applications](running.html)). the program name, needed by gdb for the "[S]tack trace" option, or `NULL` to use a default string The first call to this routine by a process with a given #GOnce struct calls @func with the given argument. Thereafter, subsequent calls to g_once() with the same #GOnce struct do not call @func again, but return the stored result of the first call. On return from g_once(), the status of @once will be %G_ONCE_STATUS_READY. For example, a mutex or a thread-specific data key must be created exactly once. In a threaded environment, calling g_once() ensures that the initialization is serialized across multiple threads. Calling g_once() recursively on the same #GOnce struct in @func will lead to a deadlock. |[<!-- language="C" --> gpointer get_debug_flags (void) { static GOnce my_once = G_ONCE_INIT; g_once (&my_once, parse_debug_flags, NULL); return my_once.retval; } ]| a #GOnce structure the #GThreadFunc function associated to @once. This function is called only once, regardless of the number of times it and its associated #GOnce struct are passed to g_once(). data to be passed to @func Function to be called when starting a critical initialization section. The argument @location must point to a static 0-initialized variable that will be set to a value other than 0 at the end of the initialization section. In combination with g_once_init_leave() and the unique address @value_location, it can be ensured that an initialization section will be executed only once during a program's life time, and that concurrent threads are blocked until initialization completed. To be used in constructs like this: |[<!-- language="C" --> static gsize initialization_value = 0; if (g_once_init_enter (&initialization_value)) { gsize setup_value = 42; // initialization code here g_once_init_leave (&initialization_value, setup_value); } // use initialization_value here ]| While @location has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. %TRUE if the initialization section should be entered, %FALSE and blocks otherwise location of a static initializable variable containing 0 This functions behaves in the same way as g_once_init_enter(), but can can be used to initialize pointers (or #guintptr) instead of #gsize. |[<!-- language="C" --> static MyStruct *interesting_struct = NULL; if (g_once_init_enter_pointer (&interesting_struct)) { MyStruct *setup_value = allocate_my_struct (); // initialization code here g_once_init_leave_pointer (&interesting_struct, g_steal_pointer (&setup_value)); } // use interesting_struct here ]| %TRUE if the initialization section should be entered, %FALSE and blocks otherwise location of a static initializable variable containing `NULL` Counterpart to g_once_init_enter(). Expects a location of a static 0-initialized initialization variable, and an initialization value other than 0. Sets the variable to the initialization value, and releases concurrent threads blocking in g_once_init_enter() on this initialization variable. While @location has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. location of a static initializable variable containing 0 new non-0 value for `*value_location` Counterpart to g_once_init_enter_pointer(). Expects a location of a static `NULL`-initialized initialization variable, and an initialization value other than `NULL`. Sets the variable to the initialization value, and releases concurrent threads blocking in g_once_init_enter_pointer() on this initialization variable. This functions behaves in the same way as g_once_init_leave(), but can be used to initialize pointers (or #guintptr) instead of #gsize. location of a static initializable variable containing `NULL` new non-`NULL` value for `*location` A wrapper for the POSIX open() function. The open() function is used to convert a pathname into a file descriptor. On POSIX systems file descriptors are implemented by the operating system. On Windows, it's the C library that implements open() and file descriptors. The actual Win32 API for opening files is quite different, see MSDN documentation for CreateFile(). The Win32 API uses file handles, which are more randomish integers, not small integers like file descriptors. Because file descriptors are specific to the C library on Windows, the file descriptor returned by this function makes sense only to functions in the same C library. Thus if the GLib-using code uses a different C library than GLib does, the file descriptor returned by this function cannot be passed to C library functions like write() or read(). See your C library manual for more details about open(). a new file descriptor, or -1 if an error occurred. The return value can be used exactly like the return value from open(). a pathname in the GLib file name encoding (UTF-8 on Windows) as in open() as in open() Parses a string containing debugging options into a %guint containing bit flags. This is used within GDK and GTK to parse the debug options passed on the command line or through environment variables. If @string is equal to "all", all flags are set. Any flags specified along with "all" in @string are inverted; thus, "all,foo,bar" or "foo,bar,all" sets all flags except those corresponding to "foo" and "bar". If @string is equal to "help", all the available keys in @keys are printed out to standard error. the combined set of bit flags. a list of debug options separated by colons, spaces, or commas, or %NULL. pointer to an array of #GDebugKey which associate strings with bit flags. the number of #GDebugKeys in the array. Compares two path buffers for equality and returns `TRUE` if they are equal. The paths inside the path buffers are not going to be normalized, so `X/Y/Z/A/..`, `X/./Y/Z` and `X/Y/Z` are not going to be considered equal. This function can be passed to g_hash_table_new() as the `key_equal_func` parameter. `TRUE` if the two path buffers are equal, and `FALSE` otherwise a path buffer to compare a path buffer to compare Gets the last component of the filename. If @file_name ends with a directory separator it gets the component before the last slash. If @file_name consists only of directory separators (and on Windows, possibly a drive letter), a single separator is returned. If @file_name is empty, it gets ".". a newly allocated string containing the last component of the filename the name of the file Gets the directory components of a file name. For example, the directory component of `/usr/bin/test` is `/usr/bin`. The directory component of `/` is `/`. If the file name has no directory components "." is returned. The returned string should be freed when no longer needed. the directory components of the file the name of the file Returns %TRUE if the given @file_name is an absolute file name. Note that this is a somewhat vague concept on Windows. On POSIX systems, an absolute file name is well-defined. It always starts from the single root directory. For example "/usr/local". On Windows, the concepts of current drive and drive-specific current directory introduce vagueness. This function interprets as an absolute file name one that either begins with a directory separator such as "\Users\tml" or begins with the root on a drive, for example "C:\Windows". The first case also includes UNC paths such as "\\\\myserver\docs\foo". In all cases, either slashes or backslashes are accepted. Note that a file name relative to the current drive root does not truly specify a file uniquely over time and across processes, as the current drive is a per-process value and can be changed. File names relative the current directory on some specific drive, such as "D:foo/bar", are not interpreted as absolute by this function, but they obviously are not relative to the normal current directory as returned by getcwd() or g_get_current_dir() either. Such paths should be avoided, or need to be handled using Windows-specific code. %TRUE if @file_name is absolute a file name Returns a pointer into @file_name after the root component, i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name is not an absolute path it returns %NULL. a pointer into @file_name after the root component a file name Matches a string against a compiled pattern. Passing the correct length of the string given is mandatory. The reversed string can be omitted by passing `NULL`, this is more efficient if the reversed version of the string to be matched is not at hand, as `g_pattern_match()` will only construct it if the compiled pattern requires reverse matches. Note that, if the user code will (possibly) match a string against a multitude of patterns containing wildcards, chances are high that some patterns will require a reversed string. In this case, it’s more efficient to provide the reversed string to avoid multiple constructions thereof in the various calls to `g_pattern_match()`. Note also that the reverse of a UTF-8 encoded string can in general not be obtained by [func@GLib.strreverse]. This works only if the string does not contain any multibyte characters. GLib offers the [func@GLib.utf8_strreverse] function to reverse UTF-8 encoded strings. Use [method@GLib.PatternSpec.match] instead %TRUE if @string matches @pspec a #GPatternSpec the length of @string (in bytes, i.e. `strlen()`, not [func@GLib.utf8_strlen]) the UTF-8 encoded string to match the reverse of @string Matches a string against a pattern given as a string. If this function is to be called in a loop, it’s more efficient to compile the pattern once with [ctor@GLib.PatternSpec.new] and call [method@GLib.PatternSpec.match_string] repeatedly. %TRUE if @string matches @pspec the UTF-8 encoded pattern the UTF-8 encoded string to match Matches a string against a compiled pattern. If the string is to be matched against more than one pattern, consider using [method@GLib.PatternSpec.match] instead while supplying the reversed string. Use [method@GLib.PatternSpec.match_string] instead %TRUE if @string matches @pspec a #GPatternSpec the UTF-8 encoded string to match This is equivalent to g_bit_lock, but working on pointers (or other pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of the pointer. While @address has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. a pointer to a #gpointer-sized value a bit value between 0 and 31 This is equivalent to g_bit_lock, but working on pointers (or other pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of the pointer. a pointer to a #gpointer-sized value a bit value between 0 and 31 returns the set pointer atomically. This is the value after setting the lock, it thus always has the lock bit set, while previously @address had the lockbit unset. You may also use g_pointer_bit_lock_mask_ptr() to clear the lock bit. This mangles @ptr as g_pointer_bit_lock() and g_pointer_bit_unlock() do. the mangled pointer. the pointer to mask the bit to set/clear. If set to `G_MAXUINT`, the lockbit is taken from @preserve_ptr or @ptr (depending on @preserve_mask). whether to set (lock) the bit or unset (unlock). This has no effect, if @lock_bit is set to `G_MAXUINT`. if non-zero, a bit-mask for @preserve_ptr. The @preserve_mask bits from @preserve_ptr are set in the result. Note that the @lock_bit bit will be always set according to @set, regardless of @preserve_mask and @preserve_ptr (unless @lock_bit is `G_MAXUINT`). if @preserve_mask is non-zero, the bits from this pointer are set in the result. This is equivalent to g_bit_trylock(), but working on pointers (or other pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of the pointer. While @address has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. %TRUE if the lock was acquired a pointer to a #gpointer-sized value a bit value between 0 and 31 This is equivalent to g_bit_unlock, but working on pointers (or other pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of the pointer. While @address has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. a pointer to a #gpointer-sized value a bit value between 0 and 31 This is equivalent to g_pointer_bit_unlock() and atomically setting the pointer value. Note that the lock bit will be cleared from the pointer. If the unlocked pointer that was set is not identical to @ptr, an assertion fails. In other words, @ptr must have @lock_bit unset. This also means, you usually can only use this on the lowest bits. a pointer to a #gpointer-sized value a bit value between 0 and 31 the new pointer value to set if non-zero, those bits of the current pointer in @address are preserved. Note that the @lock_bit bit will be always unset regardless of @ptr, @preserve_mask and the currently set value in @address. Polls @fds, as with the poll() system call, but portably. (On systems that don't have poll(), it is emulated using select().) This is used internally by #GMainContext, but it can be called directly if you need to block until a file descriptor is ready, but don't want to run the full main loop. Each element of @fds is a #GPollFD describing a single file descriptor to poll. The @fd field indicates the file descriptor, and the @events field indicates the events to poll for. On return, the @revents fields will be filled with the events that actually occurred. On POSIX systems, the file descriptors in @fds can be any sort of file descriptor, but the situation is much more complicated on Windows. If you need to use g_poll() in code that has to run on Windows, the easiest solution is to construct all of your #GPollFDs with g_io_channel_win32_make_pollfd(). the number of entries in @fds whose @revents fields were filled in, or 0 if the operation timed out, or -1 on error or if the call was interrupted. file descriptors to poll the number of file descriptors in @fds amount of time to wait, in milliseconds, or -1 to wait forever Formats a string according to @format and prefix it to an existing error message. If @err is %NULL (ie: no error variable) then do nothing. If `*err` is %NULL (ie: an error variable is present but there is no error condition) then also do nothing. a return location for a #GError printf()-style format string arguments to @format Prefixes @prefix to an existing error message. If @err or `*err` is %NULL (i.e.: no error variable) then do nothing. a return location for a #GError, or %NULL string to prefix @err with Outputs a formatted message via the print handler. The default print handler outputs the encoded message to `stdout`, without appending a trailing new-line character. Typically, @format should end with its own new-line character. This function should not be used from within libraries for debugging messages, since it may be redirected by applications to special purpose message windows or even files. Instead, libraries should use [func@GLib.log], [func@GLib.log_structured], or the convenience macros [func@GLib.message], [func@GLib.warning] and [func@GLib.error]. the message format. See the `printf()` documentation the parameters to insert into the format string Outputs a formatted message via the error message handler. The default handler outputs the encoded message to `stderr`, without appending a trailing new-line character. Typically, @format should end with its own new-line character. This function should not be used from within libraries. Instead [func@GLib.log] or [func@GLib.log_structured] should be used, or the convenience macros [func@GLib.message], [func@GLib.warning] and [func@GLib.error]. the message format. See the `printf()` documentation the parameters to insert into the format string An implementation of the standard `printf()` function which supports positional parameters, as specified in the Single Unix Specification. As with the standard `printf()`, this does not automatically append a trailing new-line character to the message, so typically @format should end with its own new-line character. `glib/gprintf.h` must be explicitly included in order to use this function. the number of bytes printed a standard `printf()` format string, but notice [string precision pitfalls](string-utils.html#string-precision-pitfalls) the arguments to insert in the output Calculates the maximum space needed to store the output of the `sprintf()` function. If @format or @args are invalid, `0` is returned. This could happen if, for example, @format contains an `%lc` or `%ls` placeholder and @args contains a wide character which cannot be represented in multibyte encoding. `0` can also be returned legitimately if, for example, @format is `%s` and @args is an empty string. The caller is responsible for differentiating these two return cases if necessary. It is recommended to not use `%lc` or `%ls` placeholders in any case, as their behaviour is locale-dependent. the maximum space needed to store the formatted string, or `0` on error the format string. See the `printf()` documentation the parameters to be inserted into the format string Creates a new #GPrivate. dynamic allocation of #GPrivate is a bad idea. Use static storage and G_PRIVATE_INIT() instead. a newly allocated #GPrivate (which can never be destroyed) a #GDestroyNotify If @dest is %NULL, free @src; otherwise, moves @src into `*dest`. The error variable @dest points to must be %NULL. @src must be non-%NULL. Note that @src is no longer valid after this call. If you want to keep using the same GError*, you need to set it to %NULL after calling this function on it. error return location error to move into the return location If @dest is %NULL, free @src; otherwise, moves @src into `*dest`. `*dest` must be %NULL. After the move, add a prefix as with g_prefix_error(). error return location error to move into the return location printf()-style format string arguments to @format Checks whether @needle exists in @haystack. If the element is found, true is returned and the element’s index is returned in @index_ (if non-`NULL`). Otherwise, false is returned and @index_ is undefined. If @needle exists multiple times in @haystack, the index of the first instance is returned. This does pointer comparisons only. If you want to use more complex equality checks, such as string comparisons, use [func@GLib.PtrArray.find_with_equal_func]. true if @needle is one of the elements of @haystack; false otherwise the pointer array to be searched the pointer to look for the return location for the index of the element, if found Checks whether @needle exists in @haystack, using the given @equal_func. If the element is found, true is returned and the element’s index is returned in @index_ (if non-`NULL`). Otherwise, false is returned and @index_ is undefined. If @needle exists multiple times in @haystack, the index of the first instance is returned. @equal_func is called with the element from the array as its first parameter, and @needle as its second parameter. If @equal_func is `NULL`, pointer equality is used. true if @needle is one of the elements of @haystack; false otherwise the pointer array to be searched the pointer to look for the function to call for each element, which should return true when the desired element is found; or `NULL` to use pointer equality the return location for the index of the element, if found Returns the pointer at the given index of the pointer array. This does not perform bounds checking on the given @index_, so you are responsible for checking it against the array length. a pointer array the index of the pointer to return Creates a new `GPtrArray`, copying @len pointers from @data, and setting the array’s reference count to 1. This avoids having to manually add each element one by one. If @copy_func is provided, then it is used to copy each element before adding them to the new array. If it is `NULL` then the pointers are copied directly. It also sets @element_free_func for freeing each element when the array is destroyed either via [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is called with @free_segment set to true or when removing elements. Do not use it if @len is greater than [`G_MAXUINT`](types.html#guint). `GPtrArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new `GPtrArray` an array of pointers the number of pointers in @data a copy function used to copy every element in the array the user data passed to @copy_func a function to free elements on @array destruction Creates a new `GPtrArray` copying the pointers from @data after having computed the length of it and with a reference count of 1. This avoids having to manually add each element one by one. If @copy_func is provided, then it is used to copy the data in the new array. It also sets @element_free_func for freeing each element when the array is destroyed either via [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is called with @free_segment set to true or when removing elements. Do not use it if the @data has more than [`G_MAXUINT`](types.html#guint) elements. `GPtrArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new `GPtrArray` an array of pointers, `NULL` terminated a copy function used to copy every element in the array the user data passed to @copy_func a function to free elements on @array destruction Creates a new `GPtrArray` with @data as pointers, @len as length and a reference count of 1. This avoids having to copy such data manually. After this call, @data belongs to the `GPtrArray` and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with [func@GLib.free]. It also sets @element_free_func for freeing each element when the array is destroyed either via [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is called with @free_segment set to true or when removing elements. Do not use it if @len is greater than [`G_MAXUINT`](types.html#guint). `GPtrArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new `GPtrArray` an array of pointers the number of pointers in @data a function to free elements on @array destruction Creates a new `GPtrArray` with @data as pointers, computing the length of it and setting the reference count to 1. This avoids having to copy such data manually. After this call, @data belongs to the `GPtrArray` and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with [func@GLib.free]. The length is calculated by iterating through @data until the first `NULL` element is found. It also sets @element_free_func for freeing each element when the array is destroyed either via [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is called with @free_segment set to true or when removing elements. Do not use it if the @data length is greater than [`G_MAXUINT`](types.html#guint). `GPtrArray` stores the length of its data in `guint`, which may be shorter than `gsize`. The new `GPtrArray` an array of pointers, `NULL` terminated a function to free elements on @array destruction This is just like the standard C [`qsort()`](man:qsort(3)) function, but the comparison routine accepts a user data argument (like [`qsort_r()`](man:qsort_r(3))). Unlike `qsort()`, this is guaranteed to be a stable sort (since GLib 2.32). `total_elems` is too small to represent larger arrays; use [func@GLib.sort_array] instead start of array to sort elements in the array size of each element function to compare elements data to pass to @compare_func Gets the #GQuark identifying the given (static) string. If the string does not currently have an associated #GQuark, a new #GQuark is created, linked to the given string. Note that this function is identical to g_quark_from_string() except that if a new #GQuark is created the string itself is used rather than a copy. This saves memory, but can only be used if the string will continue to exist until the program terminates. It can be used with statically allocated strings in the main program, but not with statically allocated memory in dynamically loaded modules, if you expect to ever unload the module again (e.g. do not use this function in GTK theme engines). This function must not be used before library constructors have finished running. In particular, this means it cannot be used to initialize global variables in C++. the #GQuark identifying the string, or 0 if @string is %NULL a string Gets the #GQuark identifying the given string. If the string does not currently have an associated #GQuark, a new #GQuark is created, using a copy of the string. This function must not be used before library constructors have finished running. In particular, this means it cannot be used to initialize global variables in C++. the #GQuark identifying the string, or 0 if @string is %NULL a string Gets the string associated with the given #GQuark. the string associated with the #GQuark a #GQuark. Gets the #GQuark associated with the given string, or 0 if string is %NULL or it has no associated #GQuark. If you want the GQuark to be created if it doesn't already exist, use g_quark_from_string() or g_quark_from_static_string(). This function must not be used before library constructors have finished running. the #GQuark associated with the string, or 0 if @string is %NULL or there is no #GQuark associated with it a string Returns a random #gboolean from @rand_. This corresponds to an unbiased coin toss. a #GRand Returns a random #gboolean. This corresponds to an unbiased coin toss. Returns a random #gdouble equally distributed over the range [0..1). a random number Returns a random #gdouble equally distributed over the range [@begin..@end). a random number lower closed bound of the interval upper open bound of the interval Return a random #guint32 equally distributed over the range [0..2^32-1]. a random number Returns a random #gint32 equally distributed over the range [@begin..@end-1]. a random number lower closed bound of the interval upper open bound of the interval Sets the seed for the global random number generator, which is used by the g_random_* functions, to @seed. a value to reinitialize the global random number generator Acquires a reference on the data pointed by @mem_block. a pointer to the data, with its reference count increased a pointer to reference counted data Allocates @block_size bytes of memory, and adds reference counting semantics to it. The data will be freed when its reference count drops to zero. The allocated data is guaranteed to be suitably aligned for any built-in type. a pointer to the allocated memory the size of the allocation, must be greater than 0 Allocates @block_size bytes of memory, and adds reference counting semantics to it. The contents of the returned data is set to zero. The data will be freed when its reference count drops to zero. The allocated data is guaranteed to be suitably aligned for any built-in type. a pointer to the allocated memory the size of the allocation, must be greater than 0 Allocates a new block of data with reference counting semantics, and copies @block_size bytes of @mem_block into it. a pointer to the allocated memory the number of bytes to copy, must be greater than 0 the memory to copy Retrieves the size of the reference counted data pointed by @mem_block. the size of the data, in bytes a pointer to reference counted data A convenience macro to allocate reference counted data with the size of the given @type. This macro calls g_rc_box_alloc() with `sizeof (@type)` and casts the returned pointer to a pointer of the given @type, avoiding a type cast in the source code. the type to allocate, typically a structure name A convenience macro to allocate reference counted data with the size of the given @type, and set its contents to zero. This macro calls g_rc_box_alloc0() with `sizeof (@type)` and casts the returned pointer to a pointer of the given @type, avoiding a type cast in the source code. the type to allocate, typically a structure name Releases a reference on the data pointed by @mem_block. If the reference was the last one, it will free the resources allocated for @mem_block. a pointer to reference counted data Releases a reference on the data pointed by @mem_block. If the reference was the last one, it will call @clear_func to clear the contents of @mem_block, and then will free the resources allocated for @mem_block. a pointer to reference counted data a function to call when clearing the data Reallocates the memory pointed to by @mem, so that it now has space for @n_bytes bytes of memory. It returns the new address of the memory, which may have been moved. @mem may be %NULL, in which case it's considered to have zero-length. @n_bytes may be 0, in which case %NULL will be returned and @mem will be freed unless it is %NULL. If the allocation fails (because the system is out of memory), the program is terminated. the new address of the allocated memory the memory to reallocate new size of the memory in bytes This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication. If the allocation fails (because the system is out of memory), the program is terminated. the new address of the allocated memory the memory to reallocate the number of blocks to allocate the size of each block in bytes Compares the current value of @rc with @val. %TRUE if the reference count is the same as the given value the address of a reference count variable the value to compare Decreases the reference count. If %TRUE is returned, the reference count reached 0. After this point, @rc is an undefined state and must be reinitialized with g_ref_count_init() to be used again. %TRUE if the reference count reached 0, and %FALSE otherwise the address of a reference count variable Increases the reference count. the address of a reference count variable Initializes a reference count variable to 1. the address of a reference count variable Acquires a reference on a string. the given string, with its reference count increased a reference counted string Compares two ref-counted strings for byte-by-byte equality. It can be passed to [func@GLib.HashTable.new] as the key equality function, and behaves exactly the same as [func@GLib.str_equal] (or `strcmp()`), but can return slightly faster as it can check the string lengths before checking all the bytes. `TRUE` if the strings are equal, otherwise `FALSE` a reference counted string a reference counted string Retrieves the length of @str. the length of the given string, in bytes a reference counted string Creates a new reference counted string and copies the contents of @str into it. the newly created reference counted string a NUL-terminated string Creates a new reference counted string and copies the content of @str into it. If you call this function multiple times with the same @str, or with the same contents of @str, it will return a new reference, instead of creating a new string. the newly created reference counted string, or a new reference to an existing string a NUL-terminated string Creates a new reference counted string and copies the contents of @str into it, up to @len bytes. Since this function does not stop at nul bytes, it is the caller's responsibility to ensure that @str has at least @len addressable bytes. the newly created reference counted string a string length of @str to use, or -1 if @str is nul-terminated Releases a reference on a string; if it was the last reference, the resources allocated by the string are freed as well. a reference counted string Checks whether @replacement is a valid replacement string (see g_regex_replace()), i.e. that all escape sequences in it are valid. If @has_references is not %NULL then @replacement is checked for pattern references. For instance, replacement text 'foo\n' does not contain references and may be evaluated without information about actual match, but '\0\1' (whole match followed by first subpattern) requires valid #GMatchInfo object. whether @replacement is a valid replacement string the replacement string location to store information about references in @replacement or %NULL Escapes the nul characters in @string to "\x00". It can be used to compile a regex with embedded nul characters. For completeness, @length can be -1 for a nul-terminated string. In this case the output string will be of course equal to @string. a newly-allocated escaped string the string to escape the length of @string Escapes the special characters used for regular expressions in @string, for instance "a.b*c" becomes "a\.b\*c". This function is useful to dynamically generate regular expressions. @string can contain nul characters that are replaced with "\0", in this case remember to specify the correct length of @string in @length. a newly-allocated escaped string the string to escape the length of @string, in bytes, or -1 if @string is nul-terminated Scans for a match in @string for @pattern. This function is equivalent to g_regex_match() but it does not require to compile the pattern with g_regex_new(), avoiding some lines of code when you need just to do a match without extracting substrings, capture counts, and so on. If this function is to be called on the same @pattern more than once, it's more efficient to compile the pattern once with g_regex_new() and then use g_regex_match(). %TRUE if the string matched, %FALSE otherwise the regular expression the string to scan for matches compile options for the regular expression, or 0 match options, or 0 Breaks the string on the pattern, and returns an array of the tokens. If the pattern contains capturing parentheses, then the text for each of the substrings will also be returned. If the pattern does not match anywhere in the string, then the whole string is returned as the first token. This function is equivalent to g_regex_split() but it does not require to compile the pattern with g_regex_new(), avoiding some lines of code when you need just to do a split without extracting substrings, capture counts, and so on. If this function is to be called on the same @pattern more than once, it's more efficient to compile the pattern once with g_regex_new() and then use g_regex_split(). As a special case, the result of splitting the empty string "" is an empty vector, not a vector containing a single string. The reason for this special case is that being able to represent an empty vector is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you'll need to check for the empty string before calling this function. A pattern that can match empty strings splits @string into separate characters wherever it matches the empty string between characters. For example splitting "ab c" using as a separator "\s*", you will get "a", "b" and "c". a %NULL-terminated array of strings. Free it using g_strfreev() the regular expression the string to scan for matches compile options for the regular expression, or 0 match options, or 0 Resets the cache used for g_get_user_special_dir(), so that the latest on-disk version is used. Call this only if you just changed the data on disk yourself. Due to thread safety issues this may cause leaking of strings that were previously returned from g_get_user_special_dir() that can't be freed. We ensure to only leak the data for the directories that actually changed value though. A wrapper for the POSIX remove() function. The remove() function deletes a name from the filesystem. See your C library manual for more details about how remove() works on your system. On Unix, remove() removes also directories, as it calls unlink() for files and rmdir() for directories. On Windows, although remove() in the C library only works for files, this function tries first remove() and then if that fails rmdir(), and thus works for both files and directories. Note however, that on Windows, it is in general not possible to remove a file that is open to some process, or mapped into memory. If this function fails on Windows you can't infer too much from the errno value. rmdir() is tried regardless of what caused remove() to fail. Any errno value set by remove() will be overwritten by that set by rmdir(). 0 if the file was successfully removed, -1 if an error occurred a pathname in the GLib file name encoding (UTF-8 on Windows) A wrapper for the POSIX rename() function. The rename() function renames a file, moving it between directories if required. See your C library manual for more details about how rename() works on your system. It is not possible in general on Windows to rename a file that is open to some process. 0 if the renaming succeeded, -1 if an error occurred a pathname in the GLib file name encoding (UTF-8 on Windows) a pathname in the GLib file name encoding Reallocates the memory pointed to by @mem, so that it now has space for @n_structs elements of type @struct_type. It returns the new address of the memory, which may have been moved. Care is taken to avoid overflow when calculating the size of the allocated block. the type of the elements to allocate the currently allocated memory the number of elements to allocate Internal function used to print messages from the public [func@GLib.return_if_fail] and [func@GLib.return_val_if_fail] macros. log domain function containing the assertion expression which failed A wrapper for the POSIX rmdir() function. The rmdir() function deletes a directory from the filesystem. See your C library manual for more details about how rmdir() works on your system. 0 if the directory was successfully removed, -1 if an error occurred a pathname in the GLib file name encoding (UTF-8 on Windows) Adds a symbol to the default scope. Use g_scanner_scope_add_symbol() instead. a #GScanner the symbol to add the value of the symbol Calls a function for each symbol in the default scope. Use g_scanner_scope_foreach_symbol() instead. a #GScanner the function to call with each symbol data to pass to the function There is no reason to use this macro, since it does nothing. This macro does nothing. a #GScanner Removes a symbol from the default scope. Use g_scanner_scope_remove_symbol() instead. a #GScanner the symbol to remove There is no reason to use this macro, since it does nothing. This macro does nothing. a #GScanner Calls @func for each item in the range (@begin, @end) passing @user_data to the function. @func must not modify the sequence itself. a #GSequenceIter a #GSequenceIter a #GFunc user data passed to @func Returns the data that @iter points to. the data that @iter points to a #GSequenceIter Inserts a new item just before the item pointed to by @iter. an iterator pointing to the new item a #GSequenceIter the data for the new item Moves the item pointed to by @src to the position indicated by @dest. After calling this function @dest will point to the position immediately after @src. It is allowed for @src and @dest to point into different sequences. a #GSequenceIter pointing to the item to move a #GSequenceIter pointing to the position to which the item is moved Inserts the (@begin, @end) range at the destination pointed to by @dest. The @begin and @end iters must point into the same sequence. It is allowed for @dest to point to a different sequence than the one pointed into by @begin and @end. If @dest is %NULL, the range indicated by @begin and @end is removed from the sequence. If @dest points to a place within the (@begin, @end) range, the range does not move. a #GSequenceIter a #GSequenceIter a #GSequenceIter Finds an iterator somewhere in the range (@begin, @end). This iterator will be close to the middle of the range, but is not guaranteed to be exactly in the middle. The @begin and @end iterators must both point to the same sequence and @begin must come before or be equal to @end in the sequence. a #GSequenceIter pointing somewhere in the (@begin, @end) range a #GSequenceIter a #GSequenceIter Removes the item pointed to by @iter. It is an error to pass the end iterator to this function. If the sequence has a data destroy function associated with it, this function is called on the data for the removed item. a #GSequenceIter Removes all items in the (@begin, @end) range. If the sequence has a data destroy function associated with it, this function is called on the data for the removed items. a #GSequenceIter a #GSequenceIter Changes the data for the item pointed to by @iter to be @data. If the sequence has a data destroy function associated with it, that function is called on the existing data that @iter pointed to. a #GSequenceIter new data for the item Moves the data pointed to by @iter to a new position as indicated by @cmp_func. This function should be called for items in a sequence already sorted according to @cmp_func whenever some aspect of an item changes so that @cmp_func may return different values for that item. @cmp_func is called with two items of the @seq, and @cmp_data. It should return 0 if the items are equal, a negative value if the first item comes before the second, and a positive value if the second item comes before the first. A #GSequenceIter the function used to compare items in the sequence user data passed to @cmp_func. Like g_sequence_sort_changed(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function. @iter_cmp is called with two iterators pointing into the #GSequence that @iter points into. It should return 0 if the iterators are equal, a negative value if the first iterator comes before the second, and a positive value if the second iterator comes before the first. a #GSequenceIter the function used to compare iterators in the sequence user data passed to @cmp_func Swaps the items pointed to by @a and @b. It is allowed for @a and @b to point into difference sequences. a #GSequenceIter a #GSequenceIter Sets a human-readable name for the application. This name should be localized if possible, and is intended for display to the user. Contrast with g_set_prgname(), which sets a non-localized name. g_set_prgname() will be called automatically by gtk_init(), but g_set_application_name() will not. Note that for thread safety reasons, this function can only be called once. The application name will be used in contexts such as error messages, or when displaying an application's name in the task list. localized name of the application Does nothing if @err is %NULL; if @err is non-%NULL, then `*err` must be %NULL. A new #GError is created and assigned to `*err`. a return location for a #GError error domain error code printf()-style format args for @format Does nothing if @err is %NULL; if @err is non-%NULL, then `*err` must be %NULL. A new #GError is created and assigned to `*err`. Unlike g_set_error(), @message is not a printf()-style format string. Use this function if @message contains text you don't have control over, that could include printf() escape sequences. a return location for a #GError error domain error code error message Sets the name of the program. This name should not be localized, in contrast to g_set_application_name(). If you are using #GApplication the program name is set in g_application_run(). In case of GDK or GTK it is set in gdk_init(), which is called by gtk_init() and the #GtkApplication::startup handler. By default, the program name is found by taking the last component of @argv[0]. Since GLib 2.72, this function can be called multiple times and is fully thread safe. Prior to GLib 2.72, this function could only be called once per process. See the [GTK documentation](https://docs.gtk.org/gtk4/migrating-3to4.html#set-a-proper-application-id) for requirements on integrating g_set_prgname() with GTK applications. the name of the program. Sets the print handler to @func, or resets it to the default GLib handler if `NULL`. Any messages passed to [func@GLib.print] will be output via the new handler. The default handler outputs the encoded message to `stdout`. By providing your own handler you can redirect the output, to a GTK widget or a log file for example. Since 2.76 this functions always returns a valid [type@GLib.PrintFunc], and never returns `NULL`. If no custom print handler was set, it will return the GLib default print handler and that can be re-used to decorate its output and/or to write to `stderr` in all platforms. Before GLib 2.76, this was `NULL`. the old print handler the new print handler or `NULL` to reset to the default Sets the handler for printing error messages to @func, or resets it to the default GLib handler if `NULL`. Any messages passed to [func@GLib.printerr] will be output via the new handler. The default handler outputs the encoded message to `stderr`. By providing your own handler you can redirect the output, to a GTK widget or a log file for example. Since 2.76 this functions always returns a valid [type@GLib.PrintFunc], and never returns `NULL`. If no custom error print handler was set, it will return the GLib default error print handler and that can be re-used to decorate its output and/or to write to `stderr` in all platforms. Before GLib 2.76, this was `NULL`. the old error message handler he new error message handler or `NULL` to reset to the default Updates a pointer to a string to a copy of @new_str and returns whether the string was changed. If @new_str matches the previous string, this function is a no-op. If @new_str is different, a copy of it will be assigned to @str_pointer and the previous string pointed to by @str_pointer will be freed with [func@GLib.free]. @str_pointer must not be `NULL`, but can point to a `NULL` value. One convenient usage of this function is in implementing property settings: ```C void foo_set_bar (Foo *foo, const char *new_bar) { g_return_if_fail (IS_FOO (foo)); if (g_set_str (&foo->bar, new_bar)) g_object_notify (foo, "bar"); } ``` true if the value of @str_pointer changed, false otherwise a pointer to either a string or `NULL` a string to assign to @str_pointer Sets an environment variable. On UNIX, both the variable's name and value can be arbitrary byte strings, except that the variable's name cannot contain '='. On Windows, they should be in UTF-8. Note that on some systems, when variables are overwritten, the memory used for the previous variables and its value isn't reclaimed. You should be mindful of the fact that environment variable handling in UNIX is not thread-safe, and your program may crash if one thread calls g_setenv() while another thread is calling getenv(). (And note that many functions, such as gettext(), call getenv() internally.) This function is only safe to use at the very start of your program, before creating any other threads (or creating objects that create worker threads of their own). If you need to set up the environment for a child process, you can use g_get_environ() to get an environment array, modify that with g_environ_setenv() and g_environ_unsetenv(), and then pass that array directly to execvpe(), g_spawn_async(), or the like. %FALSE if the environment variable couldn't be set. the environment variable to set, must not contain '='. the value for to set the variable to. whether to change the variable if it already exists. Parses a command line into an argument vector, in much the same way the shell would, but without many of the expansions the shell would perform (variable expansion, globs, operators, filename expansion, etc. are not supported). The results are defined to be the same as those you would get from a UNIX98 `/bin/sh`, as long as the input contains none of the unsupported shell expansions. If the input does contain such expansions, they are passed through literally. Possible errors are those from the %G_SHELL_ERROR domain. In particular, if @command_line is an empty string (or a string containing only whitespace), %G_SHELL_ERROR_EMPTY_STRING will be returned. It’s guaranteed that @argvp will be a non-empty array if this function returns successfully. Free the returned vector with g_strfreev(). %TRUE on success, %FALSE if error set command line to parse return location for number of args return location for array of args Quotes a string so that the shell (/bin/sh) will interpret the quoted string to mean @unquoted_string. If you pass a filename to the shell, for example, you should first quote it with this function. The return value must be freed with g_free(). The quoting style used is undefined (single or double quotes may be used). quoted string a literal string Unquotes a string as the shell (/bin/sh) would. This function only handles quotes; if a string contains file globs, arithmetic operators, variables, backticks, redirections, or other special-to-the-shell features, the result will be different from the result a real shell would produce (the variables, backticks, etc. will be passed through literally instead of being expanded). This function is guaranteed to succeed if applied to the result of g_shell_quote(). If it fails, it returns %NULL and sets the error. The @quoted_string need not actually contain quoted or escaped text; g_shell_unquote() simply goes through the string and unquotes/unescapes anything that the shell would. Both single and double quotes are handled, as are escapes including escaped newlines. The return value must be freed with g_free(). Possible errors are in the %G_SHELL_ERROR domain. Shell quoting rules are a bit strange. Single quotes preserve the literal string exactly. escape sequences are not allowed; not even `\'` - if you want a `'` in the quoted text, you have to do something like `'foo'\''bar'`. Double quotes allow `$`, ```, `"`, `\`, and newline to be escaped with backslash. Otherwise double quotes preserve things literally. an unquoted string shell-quoted string Performs a checked addition of @a and @b, storing the result in @dest. If the operation is successful, %TRUE is returned. If the operation overflows then the state of @dest is undefined and %FALSE is returned. a pointer to the #gsize destination the #gsize left operand the #gsize right operand Performs a checked multiplication of @a and @b, storing the result in @dest. If the operation is successful, %TRUE is returned. If the operation overflows then the state of @dest is undefined and %FALSE is returned. a pointer to the #gsize destination the #gsize left operand the #gsize right operand Allocates a block of memory from the libc allocator. The block address handed out can be expected to be aligned to at least `1 * sizeof (void*)`. Since GLib 2.76 this always uses the system malloc() implementation internally. a pointer to the allocated memory block, which will be %NULL if and only if @mem_size is 0 the number of bytes to allocate Allocates a block of memory via g_slice_alloc() and initializes the returned memory to 0. Since GLib 2.76 this always uses the system malloc() implementation internally. a pointer to the allocated block, which will be %NULL if and only if @mem_size is 0 the number of bytes to allocate Allocates a block of memory from the slice allocator and copies @block_size bytes into it from @mem_block. @mem_block must be non-%NULL if @block_size is non-zero. Since GLib 2.76 this always uses the system malloc() implementation internally. a pointer to the allocated memory block, which will be %NULL if and only if @mem_size is 0 the number of bytes to allocate the memory to copy A convenience macro to duplicate a block of memory using the slice allocator. It calls g_slice_copy() with `sizeof (@type)` and casts the returned pointer to a pointer of the given type, avoiding a type cast in the source code. This can never return %NULL. Since GLib 2.76 this always uses the system malloc() implementation internally. the type to duplicate, typically a structure name the memory to copy into the allocated block A convenience macro to free a block of memory that has been allocated from the slice allocator. It calls g_slice_free1() using `sizeof (type)` as the block size. Note that the exact release behaviour can be changed with the [`G_DEBUG=gc-friendly`](running.html#environment-variables) environment variable. If @mem is %NULL, this macro does nothing. Since GLib 2.76 this always uses the system free() implementation internally. the type of the block to free, typically a structure name a pointer to the block to free Frees a block of memory. The memory must have been allocated via g_slice_alloc() or g_slice_alloc0() and the @block_size has to match the size specified upon allocation. Note that the exact release behaviour can be changed with the [`G_DEBUG=gc-friendly`](running.html#environment-variables) environment variable. If @mem_block is %NULL, this function does nothing. Since GLib 2.76 this always uses the system free_sized() implementation internally. the size of the block a pointer to the block to free Frees a linked list of memory blocks of structure type @type. The memory blocks must be equal-sized, allocated via g_slice_alloc() or g_slice_alloc0() and linked together by a @next pointer (similar to #GSList). The name of the @next field in @type is passed as third argument. Note that the exact release behaviour can be changed with the [`G_DEBUG=gc-friendly`](running.html#environment-variables) environment variable. If @mem_chain is %NULL, this function does nothing. Since GLib 2.76 this always uses the system free() implementation internally. the type of the @mem_chain blocks a pointer to the first block of the chain the field name of the next pointer in @type Frees a linked list of memory blocks of structure type @type. The memory blocks must be equal-sized, allocated via g_slice_alloc() or g_slice_alloc0() and linked together by a @next pointer (similar to #GSList). The offset of the @next field in each block is passed as third argument. Note that the exact release behaviour can be changed with the [`G_DEBUG=gc-friendly`](running.html#environment-variables) environment variable. If @mem_chain is %NULL, this function does nothing. Since GLib 2.76 this always uses the system free_sized() implementation internally. the size of the blocks a pointer to the first block of the chain the offset of the @next field in the blocks A convenience macro to allocate a block of memory from the slice allocator. It calls g_slice_alloc() with `sizeof (@type)` and casts the returned pointer to a pointer of the given type, avoiding a type cast in the source code. This can never return %NULL as the minimum allocation size from `sizeof (@type)` is 1 byte. Since GLib 2.76 this always uses the system malloc() implementation internally. the type to allocate, typically a structure name A convenience macro to allocate a block of memory from the slice allocator and set the memory to 0. It calls g_slice_alloc0() with `sizeof (@type)` and casts the returned pointer to a pointer of the given type, avoiding a type cast in the source code. This can never return %NULL as the minimum allocation size from `sizeof (@type)` is 1 byte. Since GLib 2.76 this always uses the system malloc() implementation internally. the type to allocate, typically a structure name A convenience macro to get the next element in a #GSList. Note that it is considered perfectly acceptable to access @slist->next directly. an element in a #GSList. A safer form of the standard sprintf() function. The output is guaranteed to not exceed @n characters (including the terminating nul character), so it is easy to ensure that a buffer overflow cannot occur. See also [func@GLib.strdup_printf]. In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be nul-terminated. In versions prior to 1.3.12, this function returns the length of the output string. The return value of g_snprintf() conforms to the snprintf() function as standardized in ISO C99. Note that this is different from traditional `snprintf()`, which returns the length of the output string. The format string may contain positional parameters, as specified in the Single Unix Specification. the number of bytes which would be produced if the buffer was large enough the buffer to hold the output the maximum number of bytes to produce (including the terminating nul character) a standard `printf()` format string, but notice [string precision pitfalls](string-utils.html#string-precision-pitfalls) the arguments to insert in the output This is just like the standard C [`qsort()`](man:qsort(3)) function, but the comparison routine accepts a user data argument (like [`qsort_r()`](man:qsort_r(3))). Unlike `qsort()`, this is guaranteed to be a stable sort. start of array to sort number of elements in the array size of each element function to compare elements data to pass to @compare_func Removes the source with the given ID from the default main context. You must use [method@GLib.Source.destroy] for sources added to a non-default main context. The ID of a [struct@GLib.Source] is given by [method@GLib.Source.get_id], or will be returned by the functions [method@GLib.Source.attach], [func@GLib.idle_add], [func@GLib.idle_add_full], [func@GLib.timeout_add], [func@GLib.timeout_add_full], [func@GLib.child_watch_add], [func@GLib.child_watch_add_full], [func@GLib.io_add_watch], and [func@GLib.io_add_watch_full]. It is a programmer error to attempt to remove a non-existent source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source. true if the source was found and removed, false otherwise the ID of the source to remove. Removes a source from the default main loop context given the source functions and user data. If multiple sources exist with the same source functions and user data, only one will be destroyed. true if a source was found and removed, false otherwise the @source_funcs passed to [ctor@GLib.Source.new] the user data for the callback Removes a source from the default main loop context given the user data for the callback. If multiple sources exist with the same user data, only one will be destroyed. true if a source was found and removed, false otherwise the user_data for the callback Sets the name of a source using its ID. This is a convenience utility to set source names from the return value of [func@GLib.idle_add], [func@GLib.timeout_add], etc. It is a programmer error to attempt to set the name of a non-existent source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source. a source ID debug name for the source Gets the smallest prime number from a built-in array of primes which is larger than @num. This is used within GLib to calculate the optimum size of a #GHashTable. The built-in array of primes ranges from 11 to 13845163 such that each prime is approximately 1.5-2 times the previous prime. the smallest prime number from a built-in array of primes which is larger than @num a #guint Executes a child program asynchronously. See g_spawn_async_with_pipes_and_fds() for a full description; this function simply calls the g_spawn_async_with_pipes() without any pipes, which in turn calls g_spawn_async_with_pipes_and_fds(). You should call g_spawn_close_pid() on the returned child process reference when you don't need it any more. If you are writing a GTK application, and the program you are spawning is a graphical application too, then to ensure that the spawned program opens its windows on the right screen, you may want to use #GdkAppLaunchContext, #GAppLaunchContext, or set the %DISPLAY environment variable. Note that the returned @child_pid on Windows is a handle to the child process and not its identifier. Process handles and process identifiers are different concepts on Windows. %TRUE on success, %FALSE if error is set child's current working directory, or %NULL to inherit parent's child's argument vector child's environment, or %NULL to inherit parent's flags from #GSpawnFlags function to run in the child just before `exec()` user data for @child_setup return location for child process reference, or %NULL Executes a child program asynchronously. Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, so no FD assignments are used. %TRUE on success, %FALSE if an error was set child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding child's argument vector, in the GLib file name encoding; it must be non-empty and %NULL-terminated child's environment, or %NULL to inherit parent's, in the GLib file name encoding flags from #GSpawnFlags function to run in the child just before `exec()` user data for @child_setup return location for child process ID, or %NULL file descriptor to use for child's stdin, or `-1` file descriptor to use for child's stdout, or `-1` file descriptor to use for child's stderr, or `-1` Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, so no FD assignments are used. %TRUE on success, %FALSE if an error was set child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding child's argument vector, in the GLib file name encoding; it must be non-empty and %NULL-terminated child's environment, or %NULL to inherit parent's, in the GLib file name encoding flags from #GSpawnFlags function to run in the child just before `exec()` user data for @child_setup return location for child process ID, or %NULL return location for file descriptor to write to child's stdin, or %NULL return location for file descriptor to read child's stdout, or %NULL return location for file descriptor to read child's stderr, or %NULL Executes a child program asynchronously (your program will not block waiting for the child to exit). The child program is specified by the only argument that must be provided, @argv. @argv should be a %NULL-terminated array of strings, to be passed as the argument vector for the child. The first string in @argv is of course the name of the program to execute. By default, the name of the program must be a full path. If @flags contains the %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is used to search for the executable. If @flags contains the %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from @envp is used to search for the executable. If both the %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags are set, the `PATH` variable from @envp takes precedence over the environment variable. If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not used, then the program will be run from the current directory (or @working_directory, if specified); this might be unexpected or even dangerous in some cases when the current directory is world-writable. On Windows, note that all the string or string vector arguments to this function and the other `g_spawn*()` functions are in UTF-8, the GLib file name encoding. Unicode characters that are not part of the system codepage passed in these arguments will be correctly available in the spawned program only if it uses wide character API to retrieve its command line. For C programs built with Microsoft's tools it is enough to make the program have a `wmain()` instead of `main()`. `wmain()` has a wide character argument vector as parameter. At least currently, mingw doesn't support `wmain()`, so if you use mingw to develop the spawned program, it should call g_win32_get_command_line() to get arguments in UTF-8. On Windows the low-level child process creation API `CreateProcess()` doesn't use argument vectors, but a command line. The C runtime library's `spawn*()` family of functions (which g_spawn_async_with_pipes() eventually calls) paste the argument vector elements together into a command line, and the C runtime startup code does a corresponding reconstruction of an argument vector from the command line, to be passed to `main()`. Complications arise when you have argument vector elements that contain spaces or double quotes. The `spawn*()` functions don't do any quoting or escaping, but on the other hand the startup code does do unquoting and unescaping in order to enable receiving arguments with embedded spaces or double quotes. To work around this asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on argument vector elements that need it before calling the C runtime `spawn()` function. The returned @child_pid on Windows is a handle to the child process, not its identifier. Process handles and process identifiers are different concepts on Windows. @envp is a %NULL-terminated array of strings, where each string has the form `KEY=VALUE`. This will become the child's environment. If @envp is %NULL, the child inherits its parent's environment. @flags should be the bitwise OR of any flags you want to affect the function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the child will not automatically be reaped; you must use a child watch (g_child_watch_add()) to be notified about the death of the child process, otherwise it will stay around as a zombie process until this process exits. Eventually you must call g_spawn_close_pid() on the @child_pid, in order to free resources which may be associated with the child process. (On Unix, using a child watch is equivalent to calling waitpid() or handling the `SIGCHLD` signal manually. On Windows, calling g_spawn_close_pid() is equivalent to calling `CloseHandle()` on the process handle returned in @child_pid). See g_child_watch_add(). Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that other open file descriptors will be inherited by the child; otherwise all descriptors except stdin/stdout/stderr will be closed before calling `exec()` in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an absolute path, it will be looked for in the `PATH` environment variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an absolute path, it will be looked for in the `PATH` variable from @envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP are used, the value from @envp takes precedence over the environment. %G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's standard input (by default, the child's standard input is attached to `/dev/null`). %G_SPAWN_STDIN_FROM_DEV_NULL explicitly imposes the default behavior. Both flags cannot be enabled at the same time and, in both cases, the @stdin_pipe_out argument is ignored. %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output will be discarded (by default, it goes to the same location as the parent's standard output). %G_SPAWN_CHILD_INHERITS_STDOUT explicitly imposes the default behavior. Both flags cannot be enabled at the same time and, in both cases, the @stdout_pipe_out argument is ignored. %G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error will be discarded (by default, it goes to the same location as the parent's standard error). %G_SPAWN_CHILD_INHERITS_STDERR explicitly imposes the default behavior. Both flags cannot be enabled at the same time and, in both cases, the @stderr_pipe_out argument is ignored. It is valid to pass the same FD in multiple parameters (e.g. you can pass a single FD for both @stdout_fd and @stderr_fd, and include it in @source_fds too). @source_fds and @target_fds allow zero or more FDs from this process to be remapped to different FDs in the spawned process. If @n_fds is greater than zero, @source_fds and @target_fds must both be non-%NULL and the same length. Each FD in @source_fds is remapped to the FD number at the same index in @target_fds. The source and target FD may be equal to simply propagate an FD to the spawned process. FD remappings are processed after standard FDs, so any target FDs which equal @stdin_fd, @stdout_fd or @stderr_fd will overwrite them in the spawned process. @source_fds is supported on Windows since 2.72. %G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is the file to execute, while the remaining elements are the actual argument vector to pass to the file. Normally g_spawn_async_with_pipes() uses @argv[0] as the file to execute, and passes all of @argv to the child. @child_setup and @user_data are a function and user data. On POSIX platforms, the function is called in the child after GLib has performed all the setup it plans to perform (including creating pipes, closing file descriptors, etc.) but before calling `exec()`. That is, @child_setup is called just before calling `exec()` in the child. Obviously actions taken in this function will only affect the child, not the parent. On Windows, there is no separate `fork()` and `exec()` functionality. Child processes are created and run with a single API call, `CreateProcess()`. There is no sensible thing @child_setup could be used for on Windows so it is ignored and not called. If non-%NULL, @child_pid will on Unix be filled with the child's process ID. You can use the process ID to send signals to the child, or to use g_child_watch_add() (or `waitpid()`) if you specified the %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be filled with a handle to the child process only if you specified the %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child process using the Win32 API, for example wait for its termination with the `WaitFor*()` functions, or examine its exit code with `GetExitCodeProcess()`. You should close the handle with `CloseHandle()` or g_spawn_close_pid() when you no longer need it. If non-%NULL, the @stdin_pipe_out, @stdout_pipe_out, @stderr_pipe_out locations will be filled with file descriptors for writing to the child's standard input or reading from its standard output or standard error. The caller of g_spawn_async_with_pipes() must close these file descriptors when they are no longer in use. If these parameters are %NULL, the corresponding pipe won't be created. If @stdin_pipe_out is %NULL, the child's standard input is attached to `/dev/null` unless %G_SPAWN_CHILD_INHERITS_STDIN is set. If @stderr_pipe_out is NULL, the child's standard error goes to the same location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL is set. If @stdout_pipe_out is NULL, the child's standard output goes to the same location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL is set. @error can be %NULL to ignore errors, or non-%NULL to report errors. If an error is set, the function returns %FALSE. Errors are reported even if they occur in the child (for example if the executable in `@argv[0]` is not found). Typically the `message` field of returned errors should be displayed to users. Possible errors are those from the %G_SPAWN_ERROR domain. If an error occurs, @child_pid, @stdin_pipe_out, @stdout_pipe_out, and @stderr_pipe_out will not be filled with valid values. If @child_pid is not %NULL and an error does not occur then the returned process reference must be closed using g_spawn_close_pid(). On modern UNIX platforms, GLib can use an efficient process launching codepath driven internally by `posix_spawn()`. This has the advantage of avoiding the fork-time performance costs of cloning the parent process address space, and avoiding associated memory overcommit checks that are not relevant in the context of immediately executing a distinct process. This optimized codepath will be used provided that the following conditions are met: 1. %G_SPAWN_DO_NOT_REAP_CHILD is set 2. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN is set 3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set 4. @working_directory is %NULL 5. @child_setup is %NULL 6. The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath. If you are writing a GTK application, and the program you are spawning is a graphical application too, then to ensure that the spawned program opens its windows on the right screen, you may want to use #GdkAppLaunchContext, #GAppLaunchContext, or set the `DISPLAY` environment variable. %TRUE on success, %FALSE if an error was set child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding child's argument vector, in the GLib file name encoding; it must be non-empty and %NULL-terminated child's environment, or %NULL to inherit parent's, in the GLib file name encoding flags from #GSpawnFlags function to run in the child just before `exec()` user data for @child_setup file descriptor to use for child's stdin, or `-1` file descriptor to use for child's stdout, or `-1` file descriptor to use for child's stderr, or `-1` array of FDs from the parent process to make available in the child process array of FDs to remap @source_fds to in the child process number of FDs in @source_fds and @target_fds return location for child process ID, or %NULL return location for file descriptor to write to child's stdin, or %NULL return location for file descriptor to read child's stdout, or %NULL return location for file descriptor to read child's stderr, or %NULL An old name for g_spawn_check_wait_status(), deprecated because its name is misleading. Despite the name of the function, @wait_status must be the wait status as returned by g_spawn_sync(), g_subprocess_get_status(), `waitpid()`, etc. On Unix platforms, it is incorrect for it to be the exit status as passed to `exit()` or returned by g_subprocess_get_exit_status() or `WEXITSTATUS()`. Use g_spawn_check_wait_status() instead, and check whether your code is conflating wait and exit statuses. %TRUE if child exited successfully, %FALSE otherwise (and @error will be set) A status as returned from g_spawn_sync() Set @error if @wait_status indicates the child exited abnormally (e.g. with a nonzero exit code, or via a fatal signal). The g_spawn_sync() and g_child_watch_add() family of APIs return the status of subprocesses encoded in a platform-specific way. On Unix, this is guaranteed to be in the same format waitpid() returns, and on Windows it is guaranteed to be the result of GetExitCodeProcess(). Prior to the introduction of this function in GLib 2.34, interpreting @wait_status required use of platform-specific APIs, which is problematic for software using GLib as a cross-platform layer. Additionally, many programs simply want to determine whether or not the child exited successfully, and either propagate a #GError or print a message to standard error. In that common case, this function can be used. Note that the error message in @error will contain human-readable information about the wait status. The @domain and @code of @error have special semantics in the case where the process has an "exit code", as opposed to being killed by a signal. On Unix, this happens if WIFEXITED() would be true of @wait_status. On Windows, it is always the case. The special semantics are that the actual exit code will be the code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR. This allows you to differentiate between different exit codes. If the process was terminated by some means other than an exit status (for example if it was killed by a signal), the domain will be %G_SPAWN_ERROR and the code will be %G_SPAWN_ERROR_FAILED. This function just offers convenience; you can of course also check the available platform via a macro such as %G_OS_UNIX, and use WIFEXITED() and WEXITSTATUS() on @wait_status directly. Do not attempt to scan or parse the error message string; it may be translated and/or change in future versions of GLib. Prior to version 2.70, g_spawn_check_exit_status() provides the same functionality, although under a misleading name. %TRUE if child exited successfully, %FALSE otherwise (and @error will be set) A platform-specific wait status as returned from g_spawn_sync() On some platforms, notably Windows, the #GPid type represents a resource which must be closed to prevent resource leaking. g_spawn_close_pid() is provided for this purpose. It should be used on all platforms, even though it doesn't do anything under UNIX. The process reference to close A simple version of g_spawn_async() that parses a command line with g_shell_parse_argv() and passes it to g_spawn_async(). Runs a command line in the background. Unlike g_spawn_async(), the %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note that %G_SPAWN_SEARCH_PATH can have security implications, so consider using g_spawn_async() directly if appropriate. Possible errors are those from g_shell_parse_argv() and g_spawn_async(). The same concerns on Windows apply as for g_spawn_command_line_sync(). %TRUE on success, %FALSE if error is set a command line A simple version of g_spawn_sync() with little-used parameters removed, taking a command line instead of an argument vector. See g_spawn_sync() for full details. The @command_line argument will be parsed by g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag is enabled. Note that %G_SPAWN_SEARCH_PATH can have security implications, so consider using g_spawn_sync() directly if appropriate. Possible errors are those from g_spawn_sync() and those from g_shell_parse_argv(). If @wait_status is non-%NULL, the platform-specific status of the child is stored there; see the documentation of g_spawn_check_wait_status() for how to use and interpret this. On Unix platforms, note that it is usually not equal to the integer passed to `exit()` or returned from `main()`. On Windows, please note the implications of g_shell_parse_argv() parsing @command_line. Parsing is done according to Unix shell rules, not Windows command interpreter rules. Space is a separator, and backslashes are special. Thus you cannot simply pass a @command_line containing canonical Windows paths, like "c:\\program files\\app\\app.exe", as the backslashes will be eaten, and the space will act as a separator. You need to enclose such paths with single quotes, like "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'". %TRUE on success, %FALSE if an error was set a command line return location for child output return location for child errors return location for child wait status, as returned by waitpid() Executes a child synchronously (waits for the child to exit before returning). All output from the child is stored in @standard_output and @standard_error, if those parameters are non-%NULL. Note that you must set the %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when passing %NULL for @standard_output and @standard_error. If @wait_status is non-%NULL, the platform-specific status of the child is stored there; see the documentation of g_spawn_check_wait_status() for how to use and interpret this. On Unix platforms, note that it is usually not equal to the integer passed to `exit()` or returned from `main()`. Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in @flags, and on POSIX platforms, the same restrictions as for g_child_watch_source_new() apply. If an error occurs, no data is returned in @standard_output, @standard_error, or @wait_status. This function calls g_spawn_async_with_pipes() internally; see that function for full details on the other parameters and details on how these functions work on Windows. %TRUE on success, %FALSE if an error was set child's current working directory, or %NULL to inherit parent's child's argument vector, which must be non-empty and %NULL-terminated child's environment, or %NULL to inherit parent's flags from #GSpawnFlags function to run in the child just before `exec()` user data for @child_setup return location for child output, or %NULL return location for child error messages, or %NULL return location for child wait status, as returned by waitpid(), or %NULL An implementation of the standard `sprintf()` function which supports positional parameters, as specified in the Single Unix Specification. Note that it is usually better to use [func@GLib.snprintf], to avoid the risk of buffer overflow. `glib/gprintf.h` must be explicitly included in order to use this function. See also [func@GLib.strdup_printf]. the number of bytes printed A pointer to a memory buffer to contain the resulting string. It is up to the caller to ensure that the allocated buffer is large enough to hold the formatted result. a standard `printf()` format string, but notice [string precision pitfalls](string-utils.html#string-precision-pitfalls) the arguments to insert in the output A wrapper for the POSIX stat() function. The stat() function returns information about a file. On Windows the stat() function in the C library checks only the FAT-style READONLY attribute and does not look at the ACL at all. Thus on Windows the protection bits in the @st_mode field are a fabrication of little use. On Windows the Microsoft C libraries have several variants of the stat struct and stat() function with names like _stat(), _stat32(), _stat32i64() and _stat64i32(). The one used here is for 32-bit code the one with 32-bit size and time fields, specifically called _stat32(). In Microsoft's compiler, by default struct stat means one with 64-bit time fields while in MinGW struct stat is the legacy one with 32-bit fields. To hopefully clear up this messs, the gstdio.h header defines a type #GStatBuf which is the appropriate struct type depending on the platform and/or compiler being used. On POSIX it is just struct stat, but note that even on POSIX platforms, stat() might be a macro. See your C library manual for more details about stat(). 0 if the information was successfully retrieved, -1 if an error occurred a pathname in the GLib file name encoding (UTF-8 on Windows) a pointer to a stat struct, which will be filled with the file information Works like g_mutex_lock(), but for a #GStaticMutex. Use g_mutex_lock() a #GStaticMutex. Works like g_mutex_trylock(), but for a #GStaticMutex. Use g_mutex_trylock() a #GStaticMutex. Works like g_mutex_unlock(), but for a #GStaticMutex. Use g_mutex_unlock() a #GStaticMutex. Sets @fd_ptr to `-1`, returning the value that was there before. Conceptually, this transfers the ownership of the file descriptor from the referenced variable to the caller of the function (i.e. ‘steals’ the reference). This is very similar to [func@GLib.steal_pointer], but for file descriptors. On POSIX platforms, this function is async-signal safe (see [`signal(7)`](man:signal(7)) and [`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a signal handler or a #GSpawnChildSetupFunc. This function preserves the value of `errno`. the value that @fd_ptr previously had A pointer to a file descriptor Sets @handle_pointer to `0`, returning the value that was there before. Conceptually, this transfers the ownership of the handle ID from the referenced variable to the ‘caller’ of the macro (ie: ‘steals’ the handle ID). This can be very useful to make ownership transfer explicit, or to prevent a handle from being released multiple times. For example: ```c void maybe_unsubscribe_signal (ContextStruct *data) { if (some_complex_logic (data)) { g_dbus_connection_signal_unsubscribe (data->connection, g_steal_handle_id (&data->subscription_id)); // now data->subscription_id isn’t a dangling handle } } ``` While [func@GLib.clear_handle_id] can be used in many of the same situations as `g_steal_handle_id()`, this is one situation where it cannot be used, as there is no way to pass the `GDBusConnection` to a [type@GLib.ClearHandleFunc]. a pointer to a handle ID Sets @pp to %NULL, returning the value that was there before. Conceptually, this transfers the ownership of the pointer from the referenced variable to the "caller" of the macro (ie: "steals" the reference). The return value will be properly typed, according to the type of @pp. This can be very useful when combined with g_autoptr() to prevent the return value of a function from being automatically freed. Consider the following example (which only works on GCC and clang): |[ GObject * create_object (void) { g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL); if (early_error_case) return NULL; return g_steal_pointer (&obj); } ]| It can also be used in similar ways for 'out' parameters and is particularly useful for dealing with optional out parameters: |[ gboolean get_object (GObject **obj_out) { g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL); if (early_error_case) return FALSE; if (obj_out) *obj_out = g_steal_pointer (&obj); return TRUE; } ]| In the above example, the object will be automatically freed in the early error case and also in the case that %NULL was given for @obj_out. a pointer to a pointer Copies a nul-terminated string into the destination buffer, including the trailing nul byte, and returns a pointer to the trailing nul byte in `dest`. The return value is useful for concatenating multiple strings without having to repeatedly scan for the end. a pointer to the trailing nul byte in `dest` destination buffer source string Compares two strings for byte-by-byte equality and returns %TRUE if they are equal. It can be passed to g_hash_table_new() as the @key_equal_func parameter, when using non-%NULL strings as keys in a #GHashTable. This function is typically used for hash table comparisons, but can be used for general purpose comparisons of non-%NULL strings. For a %NULL-safe string comparison function, see g_strcmp0(). %TRUE if the two keys match a key a key to compare with @v1 Looks whether the string @str begins with @prefix. true if @str begins with @prefix, false otherwise a string to look in the prefix to look for Looks whether a string ends with @suffix. true if @str ends with @suffix, false otherwise a string to look in the suffix to look for Converts a string to a hash value. This function implements the widely used "djb" hash apparently posted by Daniel Bernstein to comp.lang.c some time ago. The 32 bit unsigned hash value starts at 5381 and for each byte 'c' in the string, is updated: `hash = hash * 33 + c`. This function uses the signed value of each byte. It can be passed to g_hash_table_new() as the @hash_func parameter, when using non-%NULL strings as keys in a #GHashTable. Note that this function may not be a perfect fit for all use cases. For example, it produces some hash collisions with strings as short as 2. a hash value corresponding to the key a string key Determines if a string is pure ASCII. A string is pure ASCII if it contains no bytes with the high bit set. true if @str is ASCII a string Checks if a search conducted for @search_term should match @potential_hit. This function calls [func@GLib.str_tokenize_and_fold] on both @search_term and @potential_hit. ASCII alternates are never taken for @search_term but will be taken for @potential_hit according to the value of @accept_alternates. A hit occurs when each folded token in @search_term is a prefix of a folded token from @potential_hit. Depending on how you're performing the search, it will typically be faster to call `g_str_tokenize_and_fold()` on each string in your corpus and build an index on the returned folded tokens, then call `g_str_tokenize_and_fold()` on the search term and perform lookups into that index. As some examples, searching for ‘fred’ would match the potential hit ‘Smith, Fred’ and also ‘Frédéric’. Searching for ‘Fréd’ would match ‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of accent matching). Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix). true if @potential_hit is a hit the search term from the user the text that may be a hit if true, ASCII alternates are accepted Transliterate @str to plain ASCII. For best results, @str should be in composed normalised form. This function performs a reasonably good set of character replacements. The particular set of replacements that is done may change by version or even by runtime environment. If the source language of @str is known, it can used to improve the accuracy of the translation by passing it as @from_locale. It should be a valid POSIX locale string (of the form `language[_territory][.codeset][@modifier]`). If @from_locale is %NULL then the current locale is used. If you want to do translation for no specific locale, and you want it to be done independently of the currently locale, specify `"C"` for @from_locale. a string in plain ASCII a string, in UTF-8 the source locale, if known Tokenizes @string and performs folding on each token. A token is a non-empty sequence of alphanumeric characters in the source string, separated by non-alphanumeric characters. An "alphanumeric" character for this purpose is one that matches [func@GLib.unichar_isalnum] or [func@GLib.unichar_ismark]. Each token is then (Unicode) normalised and case-folded. If @ascii_alternates is non-`NULL` and some of the returned tokens contain non-ASCII characters, ASCII alternatives will be generated. The number of ASCII alternatives that are generated and the method for doing so is unspecified, but @translit_locale (if specified) may improve the transliteration if the language of the source string is known. the folded tokens a string to tokenize the language code (like 'de' or 'en_GB') from which @string originates a return location for ASCII alternates For each character in @string, if the character is not in @valid_chars, replaces the character with @substitutor. Modifies @string in place, and return @string itself, not a copy. The return value is to allow nesting such as: ```C g_ascii_strup (g_strcanon (str, "abc", '?')) ``` In order to modify a copy, you may use [func@GLib.strdup]: ```C reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); … g_free (reformatted); ``` the modified @string a nul-terminated array of bytes bytes permitted in @string replacement character for disallowed bytes A case-insensitive string comparison, corresponding to the standard `strcasecmp()` function on platforms which support it. See [func@GLib.strncasecmp] for a discussion of why this function is deprecated and how to replace it. 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2 string to compare with @s2 string to compare with @s1 Removes trailing whitespace from a string. This function doesn't allocate or reallocate any memory; it modifies @string in place. Therefore, it cannot be used on statically allocated strings. The pointer to @string is returned to allow the nesting of functions. Also see [func@GLib.strchug] and [func@GLib.strstrip]. the modified @string a string to remove the trailing whitespace from Removes leading whitespace from a string, by moving the rest of the characters forward. This function doesn't allocate or reallocate any memory; it modifies @string in place. Therefore, it cannot be used on statically allocated strings. The pointer to @string is returned to allow the nesting of functions. Also see [func@GLib.strchomp] and [func@GLib.strstrip]. the modified @string a string to remove the leading whitespace from Compares @str1 and @str2 like `strcmp()`. Handles `NULL` gracefully by sorting it before non-`NULL` strings. Comparing two `NULL` pointers returns 0. an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2 a string another string Makes a copy of a string replacing C string-style escape sequences with their one byte equivalent: - `\b` → [U+0008 Backspace](https://en.wikipedia.org/wiki/Backspace) - `\f` → [U+000C Form Feed](https://en.wikipedia.org/wiki/Form_feed) - `\n` → [U+000A Line Feed](https://en.wikipedia.org/wiki/Newline) - `\r` → [U+000D Carriage Return](https://en.wikipedia.org/wiki/Carriage_return) - `\t` → [U+0009 Horizontal Tabulation](https://en.wikipedia.org/wiki/Tab_character) - `\v` → [U+000B Vertical Tabulation](https://en.wikipedia.org/wiki/Vertical_Tab) - `\` followed by one to three octal digits → the numeric value (mod 256) - `\` followed by any other character → the character as is. For example, `\\` will turn into a backslash (`\`) and `\"` into a double quote (`"`). [func@GLib.strescape] does the reverse conversion. a newly-allocated copy of @source with all escaped character compressed a string to compress Concatenates all of the given strings into one long string. The variable argument list must end with `NULL`. If you forget the `NULL`, `g_strconcat()` will start appending random memory junk to your string. Note that this function is usually not the right function to use to assemble a translated message from pieces, since proper translation often requires the pieces to be reordered. a newly-allocated string containing all the string arguments the first string to add, which must not be `NULL` a `NULL`-terminated list of strings to append to the string Converts any delimiter characters in @string to @new_delimiter. Any characters in @string which are found in @delimiters are changed to the @new_delimiter character. Modifies @string in place, and returns @string itself, not a copy. The return value is to allow nesting such as: ```C g_ascii_strup (g_strdelimit (str, "abc", '?')) ``` In order to modify a copy, you may use [func@GLib.strdup]: ```C reformatted = g_strdelimit (g_strdup (const_str), "abc", '?'); … g_free (reformatted); ``` the modified @string the string to convert a string containing the current delimiters, or `NULL` to use the standard delimiters defined in [const@GLib.STR_DELIMITERS] the new delimiter character Converts a string to lower case. This function is totally broken for the reasons discussed in the [func@GLib.strncasecmp] docs — use [func@GLib.ascii_strdown] or [func@GLib.utf8_strdown] instead. the string the string to convert Duplicates a string. If @str is `NULL` it returns `NULL`. a newly-allocated copy of @str the string to duplicate Similar to the standard C `sprintf()` function but safer, since it calculates the maximum space required and allocates memory to hold the result. The returned string is guaranteed to be non-NULL, unless @format contains `%lc` or `%ls` conversions, which can fail if no multibyte representation is available for the given character. a newly-allocated string holding the result a standard `printf()` format string, but notice [string precision pitfalls](string-utils.html#string-precision-pitfalls) the parameters to insert into the format string Similar to the standard C `vsprintf()` function but safer, since it calculates the maximum space required and allocates memory to hold the result. The returned string is guaranteed to be non-NULL, unless @format contains `%lc` or `%ls` conversions, which can fail if no multibyte representation is available for the given character. See also [func@GLib.vasprintf], which offers the same functionality, but additionally returns the length of the allocated string. a newly-allocated string holding the result a standard `printf()` format string, but notice [string precision pitfalls](string-utils.html#string-precision-pitfalls) the list of parameters to insert into the format string Copies an array of strings. The copy is a deep copy; each string is also copied. If called on a `NULL` value, `g_strdupv()` simply returns `NULL`. a newly-allocated array of strings. Use [func@GLib.strfreev] to free it. an array of strings to copy Returns a string corresponding to the given error code, e.g. "no such process". Unlike `strerror()`, this always returns a string in UTF-8 encoding, and the pointer is guaranteed to remain valid for the lifetime of the process. If the error code is unknown, it returns a string like “Unknown error <code\>”. Note that the string may be translated according to the current locale. The value of `errno` will not be changed by this function. However, it may be changed by intermediate function calls, so you should save its value as soon as the call returns: ```C int saved_errno; ret = read (blah); saved_errno = errno; g_strerror (saved_errno); ``` the string describing the error code the system error number. See the standard C `errno` documentation It replaces the following special characters in the string @source with their corresponding C escape sequence: | Symbol | Escape | |-----------------------------------------------------------------------------|--------| | [U+0008 Backspace](https://en.wikipedia.org/wiki/Backspace) | `\b` | | [U+000C Form Feed](https://en.wikipedia.org/wiki/Form_feed) | `\f` | | [U+000A Line Feed](https://en.wikipedia.org/wiki/Newline) | `\n` | | [U+000D Carriage Return](https://en.wikipedia.org/wiki/Carriage_return) | `\r` | | [U+0009 Horizontal Tabulation](https://en.wikipedia.org/wiki/Tab_character) | `\t` | | [U+000B Vertical Tabulation](https://en.wikipedia.org/wiki/Vertical_Tab) | `\v` | It also inserts a backslash (`\`) before any backslash or a double quote (`"`). Additionally all characters in the range 0x01-0x1F (everything below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are replaced with a backslash followed by their octal representation. Characters supplied in @exceptions are not escaped. [func@GLib.strcompress] does the reverse conversion. a newly-allocated copy of @source with special characters escaped a string to escape a string of characters not to escape in @source Frees an array of strings, as well as each string it contains. If @str_array is `NULL`, this function simply returns. an array of strings to free An auxiliary function for gettext() support (see Q_()). @msgval, unless @msgval is identical to @msgid and contains a '|' character, in which case a pointer to the substring of msgid after the first '|' character is returned. a string another string Joins a number of strings together to form one long string, with the optional @separator inserted between each of them. a newly-allocated string containing all of the strings joined together, with @separator between them a string to insert between each of the strings a `NULL`-terminated list of strings to join Joins an array of strings together to form one long string, with the optional @separator inserted between each of them. If @str_array has no items, the return value will be an empty string. If @str_array contains a single item, @separator will not appear in the resulting string. a newly-allocated string containing all of the strings joined together, with @separator between them a string to insert between each of the strings an array of strings to join Portability wrapper that calls `strlcat()` on systems which have it, and emulates it otherwise. Appends nul-terminated @src string to @dest, guaranteeing nul-termination for @dest. The total size of @dest won't exceed @dest_size. At most @dest_size - 1 characters will be copied. Unlike `strncat()`, @dest_size is the full size of dest, not the space left over. This function does not allocate memory. It always nul-terminates (unless @dest_size == 0 or there were no nul characters in the @dest_size characters of dest to start with). Caveat: this is supposedly a more secure alternative to `strcat()` or `strncat()`, but for real security [func@GLib.strconcat] is harder to mess up. size of attempted result, which is `MIN (dest_size, strlen (original dest)) + strlen (src)`, so if @retval >= @dest_size, truncation occurred destination buffer, already containing one nul-terminated string source buffer length of @dest buffer in bytes (not length of existing string inside @dest) Portability wrapper that calls `strlcpy()` on systems which have it, and emulates `strlcpy()` otherwise. Copies @src to @dest; @dest is guaranteed to be nul-terminated; @src must be nul-terminated; @dest_size is the buffer size, not the number of bytes to copy. At most @dest_size - 1 characters will be copied. Always nul-terminates (unless @dest_size is 0). This function does not allocate memory. Unlike `strncpy()`, this function doesn't pad @dest (so it's often faster). It returns the size of the attempted result, `strlen (src)`, so if @retval >= @dest_size, truncation occurred. Caveat: `strlcpy()` is supposedly more secure than `strcpy()` or `strncpy()`, but if you really want to avoid screwups, [func@GLib.strdup] is an even better idea. length of @src destination buffer source buffer length of @dest in bytes A case-insensitive string comparison, corresponding to the standard `strncasecmp()` function on platforms which support it. It is similar to [func@GLib.strcasecmp] except it only compares the first @n characters of the strings. The problem with `g_strncasecmp()` is that it does the comparison by calling `toupper()`/`tolower()`. These functions are locale-specific and operate on single bytes. However, it is impossible to handle things correctly from an internationalization standpoint by operating on bytes, since characters may be multibyte. Thus `g_strncasecmp()` is broken if your string is guaranteed to be ASCII, since it is locale-sensitive, and it's broken if your string is localized, since it doesn't work on many encodings at all, including UTF-8, EUC-JP, etc. There are therefore two replacement techniques: [func@GLib.ascii_strncasecmp], which only works on ASCII and is not locale-sensitive, and [func@GLib.utf8_casefold] followed by `strcmp()` on the resulting strings, which is good for case-insensitive sorting of UTF-8. 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2 string to compare with @s2 string to compare with @s1 the maximum number of characters to compare Duplicates the first @n bytes of a string, returning a newly-allocated buffer @n + 1 bytes long which will always be nul-terminated. If @str is less than @n bytes long the buffer is padded with nuls. If @str is `NULL` it returns `NULL`. To copy a number of characters from a UTF-8 encoded string, use [func@GLib.utf8_strncpy] instead. a newly-allocated buffer containing the first @n bytes of @str the string to duplicate the maximum number of bytes to copy from @str Creates a new string @length bytes long filled with @fill_char. a newly-allocated string filled with @fill_char the length of the new string the byte to fill the string with Reverses all of the bytes in a string. For example, `g_strreverse ("abcdef")` will result in "fedcba". Note that `g_strreverse()` doesn't work on UTF-8 strings containing multibyte characters. For that purpose, use [func@GLib.utf8_strreverse]. the @string, reversed in place the string to reverse Searches the string @haystack for the last occurrence of the string @needle. The fact that this function returns `gchar *` rather than `const gchar *` is a historical artifact. a pointer to the found occurrence, or `NULL` if not found a string to search in the string to search for Searches the string @haystack for the last occurrence of the string @needle, limiting the length of the search to @haystack_len. The fact that this function returns `gchar *` rather than `const gchar *` is a historical artifact. a pointer to the found occurrence, or `NULL` if not found a string to search in the maximum length of @haystack in bytes. A length of `-1` can be used to mean "search the entire string", like [func@GLib.strrstr] the string to search for Returns a string describing the given signal, e.g. "Segmentation fault". If the signal is unknown, it returns “unknown signal (<signum\>)”. You should use this function in preference to `strsignal()`, because it returns a string in UTF-8 encoding, and since not all platforms support the `strsignal()` function. the string describing the signal the signal number. See the `signal` documentation Splits a string into a maximum of @max_tokens pieces, using the given @delimiter. If @max_tokens is reached, the remainder of @string is appended to the last token. As an example, the result of `g_strsplit (":a:bc::d:", ":", -1)` is an array containing the six strings "", "a", "bc", "", "d" and "". As a special case, the result of splitting the empty string "" is an empty array, not an array containing a single string. The reason for this special case is that being able to represent an empty array is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you'll need to check for the empty string before calling `g_strsplit()`. a newly-allocated array of strings, freed with [func@GLib.strfreev] a string to split a string which specifies the places at which to split the string. The delimiter is not included in any of the resulting strings, unless @max_tokens is reached. the maximum number of pieces to split @string into If this is less than 1, the string is split completely Splits @string into a number of tokens not containing any of the bytes in @delimiters. A token is the (possibly empty) longest string that does not contain any of the bytes in @delimiters. Note that separators will only be single bytes from @delimiters. If @max_tokens is reached, the remainder is appended to the last token. For example, the result of `g_strsplit_set ("abc:def/ghi", ":/", -1)` is an array containing the three strings `"abc"`, `"def"`, and `"ghi"`. The result of `g_strsplit_set (":def/ghi:/x", ":/", -1)` is an array containing the five strings `""`, `"def"`, `"ghi"`, `""`, `"x"`. As a special case, the result of splitting the empty string `""` is an empty array, not an array containing a single string. The reason for this special case is that being able to represent an empty array is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you'll need to check for the empty string before calling `g_strsplit_set()`. Note that this function works on bytes not characters, so it can't be used to delimit UTF-8 strings for anything but ASCII characters. a newly-allocated array of strings. Use [func@GLib.strfreev] to free it. a string to split a nul-terminated byte array containing bytes that are used to split the string; can be empty (just a nul byte), which will result in no string splitting the maximum number of tokens to split @string into. If this is less than 1, the string is split completely Searches the string @haystack for the first occurrence of the string @needle, limiting the length of the search to @haystack_len or a nul terminator byte (whichever is reached first). A length of `-1` can be used to mean “search the entire string”, like `strstr()`. The fact that this function returns `gchar *` rather than `const gchar *` is a historical artifact. a pointer to the found occurrence, or `NULL` if not found a string to search in the maximum length of @haystack in bytes, or `-1` to search it entirely the string to search for Removes leading and trailing whitespace from a string. See [func@GLib.strchomp] and [func@GLib.strchug]. a string to remove the leading and trailing whitespace from Converts a string to a floating point value. It calls the standard `strtod()` function to handle the conversion, but if the string is not completely converted it attempts the conversion again with [func@GLib.ascii_strtod], and returns the best match. This function should seldom be used. The normal situation when reading numbers not for human consumption is to use [func@GLib.ascii_strtod]. Only when you know that you must expect both locale formatted and C formatted numbers should you use this. Make sure that you don't pass strings such as comma separated lists of values, since the commas may be interpreted as a decimal point in some locales, causing unexpected results. the converted value the string to convert to a numeric value if non-`NULL`, it returns the character after the last character used in the conversion Converts a string to upper case. This function is totally broken for the reasons discussed in the [func@GLib.strncasecmp] docs — use [func@GLib.ascii_strup] or [func@GLib.utf8_strup] instead. the string the string to convert Checks if an array of strings contains the string @str according to [func@GLib.str_equal]. @strv must not be `NULL`. true if @str is an element of @strv an array of strings to search in the string to search for Checks if two arrays of strings contain exactly the same elements in exactly the same order. Elements are compared using [func@GLib.str_equal]. To match independently of order, sort the arrays first (using [func@GLib.qsort_with_data] or similar). Two empty arrays are considered equal. Neither @strv1 nor @strv2 may be `NULL`. true if @strv1 and @strv2 are equal an array of strings to compare to @strv2 an array of strings to compare to @strv1 Returns the length of an array of strings. @str_array must not be `NULL`. length of @str_array an array of strings Hooks up a new test case at @testpath. This function is similar to [func@GLib.test_add_func]. A fixture data structure with setup and teardown functions may be provided, similar to [func@GLib.test_create_case]. `g_test_add()` is implemented as a macro, so that the @fsetup, @ftest and @fteardown callbacks can expect a @Fixture pointer as their first argument in a type safe manner. They otherwise have type `GTestFixtureFunc`. the test path for a new test case the type of a fixture data structure data argument for the test functions the function to set up the fixture data the actual test function the function to tear down the fixture data Creates a new test case. This function is similar to [func@GLib.test_create_case]. However the test is assumed to use no fixture, and test suites are automatically created on the fly and added to the root fixture, based on the /-separated portions of @testpath. The @test_data argument will be passed as first argument to @test_func. If @testpath includes the component "subprocess" anywhere in it, the test will be skipped by default, and only run if explicitly required via the `-p` command-line option or [func@GLib.test_trap_subprocess]. No component of @testpath may start with a dot (`.`) if the [const@GLib.TEST_OPTION_ISOLATE_DIRS] option is being used; and it is recommended to do so even if it isn’t. a /-separated name for the test data for the @test_func the test function to invoke for this test Creates a new test case. In contrast to [func@GLib.test_add_data_func], this function is freeing @test_data after the test run is complete. a /-separated name for the test data for @test_func the test function to invoke for this test #GDestroyNotify for @test_data Creates a new test case. This function is similar to [func@GLib.test_create_case]. However the test is assumed to use no fixture, and test suites are automatically created on the fly and added to the root fixture, based on the /-separated portions of @testpath. If @testpath includes the component "subprocess" anywhere in it, the test will be skipped by default, and only run if explicitly required via the `-p` command-line option or [func@GLib.test_trap_subprocess]. No component of @testpath may start with a dot (`.`) if the [const@GLib.TEST_OPTION_ISOLATE_DIRS] option is being used; and it is recommended to do so even if it isn’t. a /-separated name for the test the test function to invoke for this test Asserts that all messages previously indicated via [func@GLib.test_expect_message] have been seen and suppressed. This API may only be used with the old logging API ([func@GLib.log] without `G_LOG_USE_STRUCTURED` defined). It will not work with the structured logging API. See [Testing for Messages](logging.html#testing-for-messages). If messages at [flags@GLib.LogLevelFlags.LEVEL_DEBUG] are emitted, but not explicitly expected via [func@GLib.test_expect_message] then they will be ignored. Adds a message to test reports that associates a bug URI with a test case. Bug URIs are constructed from a base URI set with [func@GLib.test_bug_base] and @bug_uri_snippet. If [func@GLib.test_bug_base] has not been called, it is assumed to be the empty string, so a full URI can be provided to [func@GLib.test_bug] instead. See also [func@GLib.test_summary]. Since GLib 2.70, the base URI is not prepended to @bug_uri_snippet if it is already a valid URI. Bug specific bug tracker URI or URI portion. Specifies the base URI for bug reports. The base URI is used to construct bug report messages for [func@GLib.test_message] when [func@GLib.test_bug] is called. Calling this function outside of a test case sets the default base URI for all test cases. Calling it from within a test case changes the base URI for the scope of the test case only. Bug URIs are constructed by appending a bug specific URI portion to @uri_pattern, or by replacing the special string `%s` within @uri_pattern if that is present. If [func@GLib.test_bug_base] is not called, bug URIs are formed solely from the value provided by [func@GLib.test_bug]. the base pattern for bug URIs Creates the pathname to a data file that is required for a test. This function is conceptually similar to [func@GLib.build_filename] except that the first argument has been replaced with a [enum@GLib.TestFileType] argument. The data file should either have been distributed with the module containing the test ([enum@GLib.TestFileType.dist] or built as part of the buildcsystem of that module ([enum@GLib.TestFileType.built]). In order for this function to work in srcdir != builddir situations, the `G_TEST_SRCDIR` and `G_TEST_BUILDDIR` environment variables need to have been defined. As of 2.38, this is done by the glib.mk that is included in GLib. Please ensure that your copy is up to date before using this function. In case neither variable is set, this function will fall back to using the dirname portion of `argv[0]`, possibly removing ".libs". This allows for casual running of tests directly from the commandline in the srcdir == builddir case and should also support running of installed tests, assuming the data files have been installed in the same relative path as the test binary. the path of the file, to be freed using [func@GLib.free] the type of file (built vs. distributed) the first segment of the pathname `NULL`-terminated additional path segments Creates a new [struct@GLib.TestCase]. This API is fairly low level, and calling [func@GLib.test_add] or [func@GLib.test_add_func] is preferable. When this test is executed, a fixture structure of size @data_size will be automatically allocated and filled with zeros. Then @data_setup is called to initialize the fixture. After fixture setup, the actual test function @data_test is called. Once the test run completes, the fixture structure is torn down by calling @data_teardown and after that the memory is automatically released by the test framework. Splitting up a test run into fixture setup, test function and fixture teardown is most useful if the same fixture type is used for multiple tests. In this cases, [func@GLib.test_create_case] will be called with the same type of fixture (the @data_size argument), but varying @test_name and @data_test arguments. a newly allocated test case the name for the test case the size of the fixture data structure test data argument for the test functions the function to set up the fixture data the actual test function the function to teardown the fixture data Creates a new test suite with the name @suite_name. a newly allocated test suite a name for the suite Attempts to disable system crash reporting infrastructure. This function should be called before exercising code paths that are expected or intended to crash, to avoid wasting resources in system-wide crash collection infrastructure such as systemd-coredump or abrt. Indicates that a message with the given @log_domain and @log_level, with text matching @pattern, is expected to be logged. When this message is logged, it will not be printed, and the test case will not abort. This API may only be used with the old logging API ([func@GLib.log] without `G_LOG_USE_STRUCTURED` defined). It will not work with the structured logging API. See [Testing for Messages](logging.html#testing-for-messages). Use [func@GLib.test_assert_expected_messages] to assert that all previously-expected messages have been seen and suppressed. You can call this multiple times in a row, if multiple messages are expected as a result of a single call. (The messages must appear in the same order as the calls to [func@GLib.test_expect_message].) For example: ```c // g_main_context_push_thread_default() should fail if the // context is already owned by another thread. g_test_expect_message (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, "assertion*acquired_context*failed"); g_main_context_push_thread_default (bad_context); g_test_assert_expected_messages (); ``` Note that you cannot use this to test [func@GLib.error] messages, since [func@GLib.error] intentionally never returns even if the program doesn’t abort; use [func@GLib.test_trap_subprocess] in this case. If messages at [flags@GLib.LogLevelFlags.LEVEL_DEBUG] are emitted, but not explicitly expected via [func@GLib.test_expect_message] then they will be ignored. the log domain of the message the log level of the message a glob-style pattern (see [type@GLib.PatternSpec]) Indicates that a test failed. This function can be called multiple times from the same test. You can use this function if your test failed in a recoverable way. Do not use this function if the failure of a test could cause other tests to malfunction. Calling this function will not stop the test from running, you need to return from the test function yourself. So you can produce additional diagnostic messages or even continue running the test. If not called from inside a test, this function does nothing. Note that unlike [func@GLib.test_skip] and [func@GLib.test_incomplete], this function does not log a message alongside the test failure. If details of the test failure are available, either log them with [func@GLib.test_message] before [func@GLib.test_fail], or use [func@GLib.test_fail_printf] instead. Indicates that a test failed and records a message. Also see [func@GLib.test_fail]. The message is formatted as if by [func@GLib.strdup_printf]. the format string printf-like arguments to @format Returns whether a test has already failed. This will be the case when [func@GLib.test_fail], [func@GLib.test_incomplete] or [func@GLib.test_skip] have been called, but also if an assertion has failed. This can be useful to return early from a test if continuing after a failed assertion might be harmful. The return value of this function is only meaningful if it is called from inside a test function. true if the test has failed Gets the pathname of the directory containing test files of the type specified by @file_type. This is approximately the same as calling `g_test_build_filename(".")`, but you don't need to free the return value. the path of the directory, owned by GLib the type of file (built vs. distributed) Gets the pathname to a data file that is required for a test. This is the same as [func@GLib.test_build_filename] with two differences. The first difference is that you must only use this function from within a testcase function. The second difference is that you need not free the return value — it will be automatically freed when the testcase finishes running. It is safe to use this function from a thread inside of a testcase but you must ensure that all such uses occur before the main testcase function returns (ie: it is best to ensure that all threads have been joined). the path, automatically freed at the end of the testcase the type of file (built vs. distributed) the first segment of the pathname `NULL`-terminated additional path segments Gets the test path for the test currently being run. In essence, it will be the same string passed as the first argument to e.g. [func@GLib.test_add] when the test was added. This function returns a valid string only within a test function. Note that this is a test path, not a file system path. the test path for the test currently being run Gets the toplevel test suite for the test path API. the toplevel test suite Indicates that a test failed because of some incomplete functionality. This function can be called multiple times from the same test. Calling this function will not stop the test from running, you need to return from the test function yourself. So you can produce additional diagnostic messages or even continue running the test. If not called from inside a test, this function does nothing. explanation Indicates that a test failed because of some incomplete functionality. Equivalent to [func@GLib.test_incomplete], but the explanation is formatted as if by [func@GLib.strdup_printf]. the format string printf-like arguments to @format Initializes the GLib testing framework. This includes seeding the test random number generator, setting the program name, and parsing test-related commandline args. This should be called before calling any other `g_test_*()` functions. The following arguments are understood: - `-l`: List test cases available in a test executable. - `--seed=SEED`: Provide a random seed to reproduce test runs using random numbers. - `--verbose`: Run tests verbosely. - `-q`, `--quiet`: Run tests quietly. - `-p PATH`: Execute all tests matching the given path. - `-s PATH`: Skip all tests matching the given path. This can also be used to force a test to run that would otherwise be skipped (ie, a test whose name contains "/subprocess"). - `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes: `perf`: Performance tests, may take long and report results (off by default). `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage (off by default). `quick`: Quick tests, should run really quickly and give good coverage (the default). `undefined`: Tests for undefined behaviour, may provoke programming errors under [func@GLib.test_trap_subprocess] or [func@GLib.test_expect_message] to check that appropriate assertions or warnings are given (the default). `no-undefined`: Avoid tests for undefined behaviour. - `--debug-log`: Debug test logging output. Any parsed arguments are removed from @argv, and @argc is adjust accordingly. The following options are supported: - `G_TEST_OPTION_NO_PRGNAME`: Causes g_test_init() to not call [func@GLib.set_prgname]. Since. 2.84 - `G_TEST_OPTION_ISOLATE_DIRS`: Creates a unique temporary directory for each unit test and sets XDG directories to point there for the duration of the unit test. See [const@GLib.TEST_OPTION_ISOLATE_DIRS]. - `G_TEST_OPTION_NONFATAL_ASSERTIONS`: This has the same effect as [func@GLib.test_set_nonfatal_assertions]. Since 2.84 Since 2.58, if tests are compiled with `G_DISABLE_ASSERT` defined, `g_test_init()` will print an error and exit. This is to prevent no-op tests from being executed, as [func@GLib.assert] is commonly (erroneously) used in unit tests, and is a no-op when compiled with `G_DISABLE_ASSERT`. Ensure your tests are compiled without `G_DISABLE_ASSERT` defined. address of the @argc parameter of `main()` address of the @argv parameter of `main()` `NULL`-terminated list of special options Returns true if [func@GLib.test_init] has been called. Installs a non-error fatal log handler which can be used to decide whether log messages which are counted as fatal abort the program. The use case here is that you are running a test case that depends on particular libraries or circumstances and cannot prevent certain known critical or warning messages. So you install a handler that compares the domain and message to precisely not abort in such a case. Note that the handler is reset at the beginning of any test case, so you have to set it inside each test function which needs the special behavior. This handler has no effect on g_error messages. This handler also has no effect on structured log messages (using [func@GLib.log_structured] or [func@GLib.log_structured_array]). To change the fatal behaviour for specific log messages, programs must install a custom log writer function using [func@GLib.log_set_writer_func].See [Using Structured Logging](logging.html#using-structured-logging). the log handler function. data passed to the log handler. Reports the result of a performance or measurement test. The test should generally strive to maximize the reported quantities (larger values are better than smaller ones), this and @maximized_quantity can determine sorting order for test result reports. the reported value the format string of the report message printf-like arguments to @format Adds a message to the test report. the format string printf-like arguments to @format Reports the result of a performance or measurement test. The test should generally strive to minimize the reported quantities (smaller values are better than larger ones), this and @minimized_quantity can determine sorting order for test result reports. the reported value the format string of the report message printf-like arguments to @format Returns true if tests are run in performance mode. By default, tests are run in quick mode. In tests that use [func@GLib.test_init], the option `-m perf` enables performance tests, while `-m quick` disables them. Enqueues a callback @destroy_func to be executed during the next test case teardown phase. This is most useful to auto destroy allocated test resources at the end of a test run. Resources are released in reverse queue order, that means enqueueing callback `A` before callback `B` will cause `B()` to be called before `A()` during teardown. destroy callback for teardown phase destroy callback data Enqueues a pointer to be released with [func@GLib.free] during the next teardown phase. This is equivalent to calling [func@GLib.test_queue_destroy] with a destroy callback of [func@GLib.free]. the pointer to be stored Enqueue an object to be released with g_object_unref() during the next teardown phase. This is equivalent to calling [func@GLib.test_queue_destroy] with a destroy callback of g_object_unref(). the object to unref Returns true if tests are run in quick mode. Tests are always run in slow mode or in fast mode; there is no "medium speed". By default, tests are run in quick mode. In tests that use [func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough` can be used to change this. Returns true if tests are run in quiet mode. In tests that use [func@GLib.test_init], the option `-q` or `--quiet` enables this, while `--verbose` disables it. The default is neither verbose nor quiet. Get a reproducible random bit (0 or 1). See [func@GLib.test_rand_int] for details on test case random numbers. Gets a reproducible random floating point number. See [func@GLib.test_rand_int] for details on test case random numbers. a random number from the seeded random number generator Gets a reproducible random floating point number out of a specified range. See [func@GLib.test_rand_int] for details on test case random numbers. a number with @range_start <= number < @range_end the minimum value returned by this function the minimum value not returned by this function Gets a reproducible random integer number. The random numbers generated by the g_test_rand_*() family of functions change with every new test program start, unless the --seed option is given when starting test programs. For individual test cases however, the random number generator is reseeded, to avoid dependencies between tests and to make --seed effective for all test cases. a random number from the seeded random number generator Gets a reproducible random integer number out of a specified range. See [func@GLib.test_rand_int] for details on test case random numbers. a number with @begin <= number < @end the minimum value returned by this function the smallest value not to be returned by this function Runs all tests under the toplevel suite. The toplevel suite can be retrieved with [func@GLib.test_get_root]. Similar to [func@GLib.test_run_suite], the test cases to be run are filtered according to test path arguments (`-p testpath` and `-s testpath`) as parsed by [func@GLib.test_init]. [func@GLib.test_run_suite] or [func@GLib.test_run] may only be called once in a program. In general, the tests and sub-suites within each suite are run in the order in which they are defined. However, note that prior to GLib 2.36, there was a bug in the `g_test_add_*` functions which caused them to create multiple suites with the same name, meaning that if you created tests "/foo/simple", "/bar/simple", and "/foo/using-bar" in that order, they would get run in that order (since [func@GLib.test_run] would run the first "/foo" suite, then the "/bar" suite, then the second "/foo" suite). As of 2.36, this bug is fixed, and adding the tests in that order would result in a running order of "/foo/simple", "/foo/using-bar", "/bar/simple". If this new ordering is sub-optimal (because it puts more-complicated tests before simpler ones, making it harder to figure out exactly what has failed), you can fix it by changing the test paths to group tests by suite in a way that will result in the desired running order. Eg, "/simple/foo", "/simple/bar", "/complex/foo-using-bar". However, you should never make the actual result of a test depend on the order that tests are run in. If you need to ensure that some particular code runs before or after a given test case, use [func@GLib.test_add], which lets you specify setup and teardown functions. If all tests are skipped or marked as incomplete (expected failures), this function will return 0 if producing TAP output, or 77 (treated as "skip test" by Automake) otherwise. 0 on success, 1 on failure (assuming it returns at all), 0 or 77 if all tests were skipped or marked as incomplete Executes the tests within @suite and all nested test suites. The test suites to be executed are filtered according to test path arguments (`-p testpath` and `-s testpath`) as parsed by [func@GLib.test_init]. See the [func@GLib.test_run] documentation for more information on the order that tests are run in. [func@GLib.test_run_suite] or [func@GLib.test_run] may only be called once in a program. 0 on success a test suite Changes the behaviour of the various assertion macros. The `g_assert_*()` macros, `g_test_assert_expected_messages()` and the various `g_test_trap_assert_*()` macros are changed to not abort to program. Instead, they will call [func@GLib.test_fail] and continue. (This also changes the behavior of [func@GLib.test_fail] so that it will not cause the test program to abort after completing the failed test.) Note that the [func@GLib.assert_not_reached] and [func@GLib.assert] macros are not affected by this. This function can only be called after [func@GLib.test_init]. Indicates that a test was skipped. Calling this function will not stop the test from running, you need to return from the test function yourself. So you can produce additional diagnostic messages or even continue running the test. If not called from inside a test, this function does nothing. explanation Indicates that a test was skipped. Equivalent to [func@GLib.test_skip], but the explanation is formatted as if by [func@GLib.strdup_printf]. the format string printf-like arguments to @format Returns true if tests are run in slow mode. Tests are always run in slow mode or in fast mode; there is no "medium speed". By default, tests are run in quick mode. In tests that use [func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough` can be used to change this. Returns true if the test program is running under [func@GLib.test_trap_subprocess]. true if the test program is running under [func@GLib.test_trap_subprocess] Sets the summary for a test. This may be included in test report output, and is useful documentation for anyone reading the source code or modifying a test in future. It must be a single line, and it should summarise what the test checks, and how. This should be called at the top of a test function. For example: ```c static void test_array_sort (void) { g_test_summary ("Test my_array_sort() sorts the array correctly and stably, " "including testing zero length and one-element arrays."); // ... } ``` See also [func@GLib.test_bug]. summary of the test purpose Returns true if tests are run in thorough mode. Thorough mode is equivalent to slow mode. By default, tests are run in quick mode. In tests that use [func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough` can be used to change this. Gets the number of seconds since the last start of the timer with [func@GLib.test_timer_start]. the time since the last start of the timer in seconds Reports the last result of [func@GLib.test_timer_elapsed]. the last result of [func@GLib.test_timer_elapsed] Starts a timing test. Call [func@GLib.test_timer_elapsed] when the task is supposed to be done. Call this function again to restart the timer. Assert that the last test subprocess failed. See [func@GLib.test_trap_subprocess]. This is sometimes used to test situations that are formally considered to be undefined behaviour, like inputs that fail a [func@GLib.return_if_fail] check. In these situations you should skip the entire test, including the call to [func@GLib.test_trap_subprocess], unless [func@GLib.test_undefined] returns true to indicate that undefined behaviour may be tested. Assert that the last test subprocess passed. See [func@GLib.test_trap_subprocess]. Assert that the stderr output of the last test subprocess matches @serrpattern. See [func@GLib.test_trap_subprocess]. This is sometimes used to test situations that are formally considered to be undefined behaviour, like code that hits a [func@GLib.assert] or [func@GLib.error]. In these situations you should skip the entire test, including the call to [func@GLib.test_trap_subprocess], unless [func@GLib.test_undefined] returns true to indicate that undefined behaviour may be tested. a string that follows glob-style [pattern][struct@PatternSpec] rules Assert that the stderr output of the last test subprocess does not match @serrpattern. See [func@GLib.test_trap_subprocess]. a string that follows glob-style [pattern][struct@PatternSpec] rules Assert that the stdout output of the last test subprocess matches @soutpattern. See [func@GLib.test_trap_subprocess]. a string that follows glob-style [pattern][struct@PatternSpec] rules Assert that the stdout output of the last test subprocess does not match @soutpattern. See [func@GLib.test_trap_subprocess]. a string that follows glob-style [pattern][struct@PatternSpec] rules Forks the current test program to execute a test case that might not return or that might abort. If @usec_timeout is non-0, the forked test case is aborted and considered failing if its run time exceeds it. The forking behavior can be configured with [flags@GLib.TestTrapFlags] flags. In the following example, the test code forks, the forked child process produces some sample output and exits successfully. The forking parent process then asserts successful child program termination and validates child program outputs. ```c static void test_fork_patterns (void) { if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR)) { g_print ("some stdout text: somagic17 "); g_printerr ("some stderr text: semagic43 "); exit (0); // successful test run } g_test_trap_assert_passed (); g_test_trap_assert_stdout ("*somagic17*"); g_test_trap_assert_stderr ("*semagic43*"); } ``` This function is implemented only on Unix platforms, is not always reliable due to problems inherent in fork-without-exec and doesn't set close-on-exec flag on its file descriptors. Use func@GLib.test_trap_subprocess] instead. true for the forked child and false for the executing parent process. timeout for the forked test in microseconds flags to modify forking behaviour Checks the result of the last [func@GLib.test_trap_subprocess] call. true if the last test subprocess terminated successfully Checks the result of the last [func@GLib.test_trap_subprocess] call. true if the last test subprocess was skipped Checks the result of the last [func@GLib.test_trap_subprocess] call. true if the last test subprocess got killed due to a timeout Respawns the test program to run only @test_path in a subprocess. This is equivalent to calling [func@GLib.test_trap_subprocess_with_envp] with `envp` set to `NULL`. See the documentation for that function for full details. test to run in a subprocess timeout for the subprocess test in microseconds. flags to modify subprocess behaviour Respawns the test program to run only @test_path in a subprocess with a given environment. This can be used for a test case that might not return, or that might abort. If @test_path is `NULL` then the same test is re-run in a subprocess. You can use [func@GLib.test_subprocess] to determine whether the test is in a subprocess or not. @test_path can also be the name of the parent test, followed by "`/subprocess/`" and then a name for the specific subtest (or just ending with "`/subprocess`" if the test only has one child test); tests with names of this form will automatically be skipped in the parent process. If @envp is `NULL`, the parent process’ environment will be inherited. If @usec_timeout is non-0, the test subprocess is aborted and considered failing if its run time exceeds it. The subprocess behavior can be configured with [flags@GLib.TestSubprocessFlags] flags. You can use methods such as [func@GLib.test_trap_assert_passed], [func@GLib.test_trap_assert_failed], and [func@GLib.test_trap_assert_stderr] to check the results of the subprocess. (But note that [func@GLib.test_trap_assert_stdout] and [func@GLib.test_trap_assert_stderr] cannot be used if @test_flags specifies that the child should inherit the parent stdout/stderr.) If your `main ()` needs to behave differently in the subprocess, you can call [func@GLib.test_subprocess] (after calling [func@GLib.test_init]) to see whether you are in a subprocess. Internally, this function tracks the child process using [func@GLib.child_watch_source_new], so your process must not ignore `SIGCHLD`, and must not attempt to watch or wait for the child process via another mechanism. The following example tests that calling `my_object_new(1000000)` will abort with an error message. ```c static void test_create_large_object (void) { if (g_test_subprocess ()) { my_object_new (1000000); return; } // Reruns this same test in a subprocess g_test_trap_subprocess (NULL, 0, G_TEST_SUBPROCESS_DEFAULT); g_test_trap_assert_failed (); g_test_trap_assert_stderr ("*ERROR*too large*"); } static void test_different_username (void) { if (g_test_subprocess ()) { // Code under test goes here g_message ("Username is now simulated as %s", g_getenv ("USER")); return; } // Reruns this same test in a subprocess g_auto(GStrv) envp = g_get_environ (); envp = g_environ_setenv (g_steal_pointer (&envp), "USER", "charlie", TRUE); g_test_trap_subprocess_with_envp (NULL, envp, 0, G_TEST_SUBPROCESS_DEFAULT); g_test_trap_assert_passed (); g_test_trap_assert_stdout ("Username is now simulated as charlie"); } int main (int argc, char **argv) { g_test_init (&argc, &argv, NULL); g_test_add_func ("/myobject/create-large-object", test_create_large_object); g_test_add_func ("/myobject/different-username", test_different_username); return g_test_run (); } ``` test to run in a subprocess environment to run the test in timeout for the subprocess test in microseconds flags to modify subprocess behaviour Returns true if tests may provoke assertions and other formally-undefined behaviour, to verify that appropriate warnings are given. This might, in some cases, be useful to turn this off (e.g. if running tests under valgrind). In tests that use [func@GLib.test_init], the option `-m no-undefined` disables those tests, while `-m undefined` explicitly enables them (normally the default behaviour). Since GLib 2.68, if GLib was compiled with gcc or clang and [AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer) is enabled, the default changes to not exercising undefined behaviour. Returns true if tests are run in verbose mode. In tests that use [func@GLib.test_init], the option `--verbose` enables this, while `-q` or `--quiet` disables it. The default is neither verbose nor quiet. This function creates a new thread. The new thread executes the function @func with the argument @data. If the thread was created successfully, it is returned. @error can be %NULL to ignore errors, or non-%NULL to report errors. The error is set, if and only if the function returns %NULL. This function returns a reference to the created thread only if @joinable is %TRUE. In that case, you must free this reference by calling g_thread_unref() or g_thread_join(). If @joinable is %FALSE then you should probably not touch the return value. Use g_thread_new() instead the new #GThread on success a function to execute in the new thread an argument to supply to the new thread should this thread be joinable? This function creates a new thread. The @bound and @priority arguments are now ignored. Use g_thread_new(). the new #GThread on success. a function to execute in the new thread. an argument to supply to the new thread. a stack size for the new thread. should this thread be joinable? ignored ignored Terminates the current thread. If another thread is waiting for us using g_thread_join() then the waiting thread will be woken up and get @retval as the return value of g_thread_join(). Calling g_thread_exit() with a parameter @retval is equivalent to returning @retval from the function @func, as given to g_thread_new(). You must only call g_thread_exit() from a thread that you created yourself with g_thread_new() or related APIs. You must not call this function from a thread created with another threading library or or from within a #GThreadPool. the return value of this thread Call @thread_func on all #GThreads that have been created with g_thread_create(). Note that threads may decide to exit while @thread_func is running, so without intimate knowledge about the lifetime of foreign threads, @thread_func shouldn't access the GThread* pointer passed in as first argument. However, @thread_func will not be called for threads which are known to have exited already. Due to thread lifetime checks, this function has an execution complexity which is quadratic in the number of existing threads. There aren't many things you can do with a #GThread, except comparing it with one that was returned from g_thread_create(). There are better ways to find out if your thread is still alive. function to call for all #GThread structures second argument to @thread_func Indicates if g_thread_init() has been called. %TRUE if threads have been initialized. If you use GLib from more than one thread, you must initialize the thread system by calling g_thread_init(). Since version 2.24, calling g_thread_init() multiple times is allowed, but nothing happens except for the first call. Since version 2.32, GLib does not support custom thread implementations anymore and the @vtable parameter is ignored and you should pass %NULL. ::: note g_thread_init() must not be called directly or indirectly in a callback from GLib. Also no mutexes may be currently locked while calling g_thread_init(). ::: note To use g_thread_init() in your program, you have to link with the libraries that the command `pkg-config --libs gthread-2.0` outputs. This is not the case for all the other thread-related functions of GLib. Those can be used without having to link with the thread libraries. This function is no longer necessary. The GLib threading system is automatically initialized at the start of your program. a function table of type #GThreadFunctions, that provides the entry points to the thread system to be used. Since 2.32, this parameter is ignored and should always be %NULL This function will return the maximum @interval that a thread will wait in the thread pool for new tasks before being stopped. If this function returns 0, threads waiting in the thread pool for new work are not stopped. the maximum @interval (milliseconds) to wait for new tasks in the thread pool before stopping the thread Returns the maximal allowed number of unused threads. the maximal number of unused threads Returns the number of currently unused threads. the number of currently unused threads This function will set the maximum @interval that a thread waiting in the pool for new tasks can be idle for before being stopped. This function is similar to calling g_thread_pool_stop_unused_threads() on a regular timeout, except this is done on a per thread basis. By setting @interval to 0, idle threads will not be stopped. The default value is 15000 (15 seconds). the maximum @interval (in milliseconds) a thread can be idle Sets the maximal number of unused threads to @max_threads. If @max_threads is -1, no limit is imposed on the number of unused threads. The default value is 8 since GLib 2.84. Previously the default value was 2. maximal number of unused threads Stops all currently unused threads. This does not change the maximal number of unused threads. This function can be used to regularly stop all unused threads e.g. from g_timeout_add(). This function returns the #GThread corresponding to the current thread. Note that this function does not increase the reference count of the returned struct. This function will return a #GThread even for threads that were not created by GLib (i.e. those created by other threading APIs). This may be useful for thread identification purposes (i.e. comparisons) but you must not use GLib functions (such as g_thread_join()) on these threads. the #GThread representing the current thread This macro returns %TRUE if the thread system is initialized, and %FALSE if it is not. For language bindings, g_thread_get_initialized() provides the same functionality as a function. Causes the calling thread to voluntarily relinquish the CPU, so that other threads can run. This function is often used as a method to make busy wait less evil. Converts a string containing an ISO 8601 encoded date and time to a #GTimeVal and puts it into @time_. @iso_date must include year, month, day, hours, minutes, and seconds. It can optionally include fractions of a second and a time zone indicator. (In the absence of any time zone indication, the timestamp is assumed to be in local time.) Any leading or trailing space in @iso_date is ignored. This function was deprecated, along with #GTimeVal itself, in GLib 2.62. Equivalent functionality is available using code like: |[ GDateTime *dt = g_date_time_new_from_iso8601 (iso8601_string, NULL); gint64 time_val = g_date_time_to_unix (dt); g_date_time_unref (dt); ]| #GTimeVal is not year-2038-safe. Use g_date_time_new_from_iso8601() instead. %TRUE if the conversion was successful. an ISO 8601 encoded date string a #GTimeVal Sets a function to be called at regular intervals, with the default priority, [const@GLib.PRIORITY_DEFAULT]. The given @function is called repeatedly until it returns [const@GLib.SOURCE_REMOVE], at which point the timeout is automatically destroyed and the function will not be called again. The first call to the function will be at the end of the first @interval. Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to ‘catch up’ time lost in delays). See [main loop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. If you want to have a timer in the ‘seconds’ range and do not care about the exact time of the first call of the timer, use the [func@GLib.timeout_add_seconds] function; this function allows for more optimizations and more efficient system power usage. This internally creates a main loop source using [func@GLib.timeout_source_new] and attaches it to the global [struct@GLib.MainContext] using [method@GLib.Source.attach], so the callback will be invoked in whichever thread is running that main context. You can do these steps manually if you need greater control or to use a custom main context. It is safe to call this function from any thread. The interval given is in terms of monotonic time, not wall clock time. See [func@GLib.get_monotonic_time]. the ID (greater than 0) of the event source the time between calls to the function, in milliseconds function to call data to pass to @function Sets a function to be called at regular intervals, with the given priority. The function is called repeatedly until it returns [const@GLib.SOURCE_REMOVE], at which point the timeout is automatically destroyed and the function will not be called again. The @notify function is called when the timeout is destroyed. The first call to the function will be at the end of the first @interval. Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to ‘catch up’ time lost in delays). See [main loop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. This internally creates a main loop source using [func@GLib.timeout_source_new] and attaches it to the global [struct@GLib.MainContext] using [method@GLib.Source.attach], so the callback will be invoked in whichever thread is running that main context. You can do these steps manually if you need greater control or to use a custom main context. The interval given is in terms of monotonic time, not wall clock time. See [func@GLib.get_monotonic_time]. the ID (greater than 0) of the event source the priority of the timeout source; typically this will be in the range between [const@GLib.PRIORITY_DEFAULT] and [const@GLib.PRIORITY_HIGH] the time between calls to the function, in milliseconds function to call data to pass to @function function to call when the timeout is removed Sets a function to be called after @interval milliseconds have elapsed, with the default priority, [const@GLib.PRIORITY_DEFAULT]. The given @function is called once and then the source will be automatically removed from the main context. This function otherwise behaves like [func@GLib.timeout_add]. the ID (greater than 0) of the event source the time after which the function will be called, in milliseconds function to call data to pass to @function Sets a function to be called at regular intervals with the default priority, [const@GLib.PRIORITY_DEFAULT]. The function is called repeatedly until it returns [const@GLib.SOURCE_REMOVE], at which point the timeout is automatically destroyed and the function will not be called again. This internally creates a main loop source using [func@GLib.timeout_source_new_seconds] and attaches it to the main loop context using [method@GLib.Source.attach]. You can do these steps manually if you need greater control. Also see [func@GLib.timeout_add_seconds_full]. It is safe to call this function from any thread. Note that the first call of the timer may not be precise for timeouts of one second. If you need finer precision and have such a timeout, you may want to use [func@GLib.timeout_add] instead. See [main loop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. The interval given is in terms of monotonic time, not wall clock time. See [func@GLib.get_monotonic_time]. the ID (greater than 0) of the event source the time between calls to the function, in seconds function to call data to pass to @function Sets a function to be called at regular intervals, with @priority. The function is called repeatedly until it returns [const@GLib.SOURCE_REMOVE], at which point the timeout is automatically destroyed and the function will not be called again. Unlike [func@GLib.timeout_add], this function operates at whole second granularity. The initial starting point of the timer is determined by the implementation and the implementation is expected to group multiple timers together so that they fire all at the same time. To allow this grouping, the @interval to the first timer is rounded and can deviate up to one second from the specified interval. Subsequent timer iterations will generally run at the specified interval. Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given @interval See [main loop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. If you want timing more precise than whole seconds, use [func@GLib.timeout_add] instead. The grouping of timers to fire at the same time results in a more power and CPU efficient behavior so if your timer is in multiples of seconds and you don’t require the first timer exactly one second from now, the use of [func@GLib.timeout_add_seconds] is preferred over [func@GLib.timeout_add]. This internally creates a main loop source using [func@GLib.timeout_source_new_seconds] and attaches it to the main loop context using [method@GLib.Source.attach]. You can do these steps manually if you need greater control. It is safe to call this function from any thread. The interval given is in terms of monotonic time, not wall clock time. See [func@GLib.get_monotonic_time]. the ID (greater than 0) of the event source the priority of the timeout source; typically this will be in the range between [const@GLib.PRIORITY_DEFAULT] and [const@GLib.PRIORITY_HIGH] the time between calls to the function, in seconds function to call data to pass to @function function to call when the timeout is removed This function behaves like [func@GLib.timeout_add_once] but with a range in seconds. the ID (greater than 0) of the event source the time after which the function will be called, in seconds function to call data to pass to @function Creates a new timeout source. The source will not initially be associated with any [struct@GLib.MainContext] and must be added to one with [method@GLib.Source.attach] before it will be executed. The interval given is in terms of monotonic time, not wall clock time. See [func@GLib.get_monotonic_time]. the newly-created timeout source the timeout interval in milliseconds Creates a new timeout source. The source will not initially be associated with any [struct@GLib.MainContext] and must be added to one with [method@GLib.Source.attach] before it will be executed. The scheduling granularity/accuracy of this timeout source will be in seconds. The interval given is in terms of monotonic time, not wall clock time. See [func@GLib.get_monotonic_time]. the newly-created timeout source the timeout interval in seconds Returns the height of a #GTrashStack. Note that execution of this function is of O(N) complexity where N denotes the number of items on the stack. #GTrashStack is deprecated without replacement the height of the stack a #GTrashStack Returns the element at the top of a #GTrashStack which may be %NULL. #GTrashStack is deprecated without replacement the element at the top of the stack a #GTrashStack Pops a piece of memory off a #GTrashStack. #GTrashStack is deprecated without replacement the element at the top of the stack a #GTrashStack Pushes a piece of memory onto a #GTrashStack. #GTrashStack is deprecated without replacement a #GTrashStack the piece of memory to push on the stack Attempts to allocate @n_bytes, and returns %NULL on failure. Contrast with g_malloc(), which aborts the program on failure. the allocated memory, or %NULL. number of bytes to allocate. Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on failure. Contrast with g_malloc0(), which aborts the program on failure. the allocated memory, or %NULL number of bytes to allocate This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication. the allocated memory, or %NULL the number of blocks to allocate the size of each block in bytes This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication. the allocated memory, or %NULL. the number of blocks to allocate the size of each block in bytes Attempts to allocate @n_structs elements of type @struct_type, and returns %NULL on failure. Contrast with g_new(), which aborts the program on failure. The returned pointer is cast to a pointer to the given type. The function returns %NULL when @n_structs is 0 of if an overflow occurs. the type of the elements to allocate the number of elements to allocate Attempts to allocate @n_structs elements of type @struct_type, initialized to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts the program on failure. The returned pointer is cast to a pointer to the given type. The function returns %NULL when @n_structs is 0 or if an overflow occurs. the type of the elements to allocate the number of elements to allocate Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL on failure. Contrast with g_realloc(), which aborts the program on failure. If @mem is %NULL, behaves the same as g_try_malloc(). the allocated memory, or %NULL. previously-allocated memory, or %NULL. number of bytes to allocate. This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication. the allocated memory, or %NULL. previously-allocated memory, or %NULL. the number of blocks to allocate the size of each block in bytes Attempts to reallocate the memory pointed to by @mem, so that it now has space for @n_structs elements of type @struct_type, and returns %NULL on failure. Contrast with g_renew(), which aborts the program on failure. It returns the new address of the memory, which may have been moved. The function returns %NULL if an overflow occurs. the type of the elements to allocate the currently allocated memory the number of elements to allocate Convert a string from UCS-4 to UTF-16. A nul character (U+0000) will be added to the result after the converted text. a pointer to a newly allocated UTF-16 string. This value must be freed with [func@GLib.free]. a UCS-4 encoded string the maximum length (number of characters) of @str to use. If @len is negative, then the string is nul-terminated. location to store number of bytes read, or `NULL` to ignore. If an error occurs then the index of the invalid input is stored here. The value stored here will never be negative. location to store number of `gunichar2` written, or `NULL` to ignore. The value stored here does not include the trailing nul, and will never be negative. Convert a string from a 32-bit fixed width representation as UCS-4. to UTF-8. The result will be terminated with a nul byte. a pointer to a newly allocated UTF-8 string. This value must be freed with [func@GLib.free]. a UCS-4 encoded string the maximum length (number of characters) of @str to use. If @len is negative, then the string is nul-terminated. location to store number of characters read, or `NULL` to ignore. If an error occurs then the index of the invalid input is stored here. The value stored here will never be negative. location to store number of bytes written, or `NULL` to ignore. The value stored here does not include the trailing nul, and will never be negative. Performs a checked addition of @a and @b, storing the result in @dest. If the operation is successful, %TRUE is returned. If the operation overflows then the state of @dest is undefined and %FALSE is returned. a pointer to the #guint64 destination the #guint64 left operand the #guint64 right operand Performs a checked multiplication of @a and @b, storing the result in @dest. If the operation is successful, %TRUE is returned. If the operation overflows then the state of @dest is undefined and %FALSE is returned. a pointer to the #guint64 destination the #guint64 left operand the #guint64 right operand Performs a checked addition of @a and @b, storing the result in @dest. If the operation is successful, %TRUE is returned. If the operation overflows then the state of @dest is undefined and %FALSE is returned. a pointer to the #guint destination the #guint left operand the #guint right operand Performs a checked multiplication of @a and @b, storing the result in @dest. If the operation is successful, %TRUE is returned. If the operation overflows then the state of @dest is undefined and %FALSE is returned. a pointer to the #guint destination the #guint left operand the #guint right operand Determines the break type of @c. @c should be a Unicode character (to derive a character from UTF-8 encoded text, use g_utf8_get_char()). The break type is used to find word and line breaks ("text boundaries"), Pango implements the Unicode boundary resolution algorithms and normally you would use a function such as pango_break() instead of caring about break types yourself. the break type of @c a Unicode character Determines the canonical combining class of a Unicode character. the combining class of the character a Unicode character Performs a single composition step of the Unicode canonical composition algorithm. This function includes algorithmic Hangul Jamo composition, but it is not exactly the inverse of g_unichar_decompose(). No composition can have either of @a or @b equal to zero. To be precise, this function composes if and only if there exists a Primary Composite P which is canonically equivalent to the sequence <@a,@b>. See the Unicode Standard for the definition of Primary Composite. If @a and @b do not compose a new character, @ch is set to zero. See [UAX#15](http://unicode.org/reports/tr15/) for details. %TRUE if the characters could be composed a Unicode character a Unicode character return location for the composed character Performs a single decomposition step of the Unicode canonical decomposition algorithm. This function does not include compatibility decompositions. It does, however, include algorithmic Hangul Jamo decomposition, as well as 'singleton' decompositions which replace a character by a single other character. In the case of singletons `*b` will be set to zero. If @ch is not decomposable, `*a` is set to @ch and `*b` is set to zero. Note that the way Unicode decomposition pairs are defined, it is guaranteed that @b would not decompose further, but @a may itself decompose. To get the full canonical decomposition for @ch, one would need to recursively call this function on @a. Or use g_unichar_fully_decompose(). See [UAX#15](http://unicode.org/reports/tr15/) for details. %TRUE if the character could be decomposed a Unicode character return location for the first component of @ch return location for the second component of @ch Determines the numeric value of a character as a decimal digit. If @c is a decimal digit (according to g_unichar_isdigit()), its numeric value. Otherwise, -1. a Unicode character Computes the canonical or compatibility decomposition of a Unicode character. For compatibility decomposition, pass %TRUE for @compat; for canonical decomposition pass %FALSE for @compat. The decomposed sequence is placed in @result. Only up to @result_len characters are written into @result. The length of the full decomposition (irrespective of @result_len) is returned by the function. For canonical decomposition, currently all decompositions are of length at most 4, but this may change in the future (very unlikely though). At any rate, Unicode does guarantee that a buffer of length 18 is always enough for both compatibility and canonical decompositions, so that is the size recommended. This is provided as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH. See [UAX#15](http://unicode.org/reports/tr15/) for details. the length of the full decomposition. a Unicode character. whether perform canonical or compatibility decomposition location to store decomposed result, or %NULL length of @result In Unicode, some characters are "mirrored". This means that their images are mirrored horizontally in text that is laid out from right to left. For instance, "(" would become its mirror image, ")", in right-to-left text. If @ch has the Unicode mirrored property and there is another unicode character that typically has a glyph that is the mirror image of @ch's glyph and @mirrored_ch is set, it puts that character in the address pointed to by @mirrored_ch. Otherwise the original character is put. %TRUE if @ch has a mirrored character, %FALSE otherwise a Unicode character location to store the mirrored character Looks up the #GUnicodeScript for a particular character (as defined by Unicode Standard Annex \#24). No check is made for @ch being a valid Unicode character; if you pass in invalid character, the result is undefined. This function is equivalent to pango_script_for_unichar() and the two are interchangeable. the #GUnicodeScript for the character. a Unicode character Determines whether a character is alphanumeric. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). %TRUE if @c is an alphanumeric character a Unicode character Determines whether a character is alphabetic (i.e. a letter). Given some UTF-8 text, obtain a character value with g_utf8_get_char(). %TRUE if @c is an alphabetic character a Unicode character Determines whether a character is a control character. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). %TRUE if @c is a control character a Unicode character Determines if a given character is assigned in the Unicode standard. %TRUE if the character has an assigned value a Unicode character Determines whether a character is numeric (i.e. a digit). This covers ASCII 0-9 and also digits in other languages/scripts. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). %TRUE if @c is a digit a Unicode character Determines whether a character is printable and not a space (returns %FALSE for control characters, format characters, and spaces). g_unichar_isprint() is similar, but returns %TRUE for spaces. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). %TRUE if @c is printable unless it's a space a Unicode character Determines whether a character is a lowercase letter. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). %TRUE if @c is a lowercase letter a Unicode character Determines whether a character is a mark (non-spacing mark, combining mark, or enclosing mark in Unicode speak). Given some UTF-8 text, obtain a character value with g_utf8_get_char(). Note: in most cases where isalpha characters are allowed, ismark characters should be allowed to as they are essential for writing most European languages as well as many non-Latin scripts. %TRUE if @c is a mark character a Unicode character Determines whether a character is printable. Unlike g_unichar_isgraph(), returns %TRUE for spaces. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). %TRUE if @c is printable a Unicode character Determines whether a character is punctuation or a symbol. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). %TRUE if @c is a punctuation or symbol character a Unicode character Determines whether a character is a space, tab, or line separator (newline, carriage return, etc.). Given some UTF-8 text, obtain a character value with g_utf8_get_char(). (Note: don't use this to do word breaking; you have to use Pango or equivalent to get word breaking right, the algorithm is fairly complex.) %TRUE if @c is a space character a Unicode character Determines if a character is titlecase. Some characters in Unicode which are composites, such as the DZ digraph have three case variants instead of just two. The titlecase form is used at the beginning of a word where only the first letter is capitalized. The titlecase form of the DZ digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z. %TRUE if the character is titlecase a Unicode character Determines if a character is uppercase. %TRUE if @c is an uppercase character a Unicode character Determines if a character is typically rendered in a double-width cell. %TRUE if the character is wide a Unicode character Determines if a character is typically rendered in a double-width cell under legacy East Asian locales. If a character is wide according to g_unichar_iswide(), then it is also reported wide with this function, but the converse is not necessarily true. See the [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/) for details. If a character passes the g_unichar_iswide() test then it will also pass this test, but not the other way around. Note that some characters may pass both this test and g_unichar_iszerowidth(). %TRUE if the character is wide in legacy East Asian locales a Unicode character Determines if a character is a hexadecimal digit. %TRUE if the character is a hexadecimal digit a Unicode character. Determines if a given character typically takes zero width when rendered. The return value is %TRUE for all non-spacing and enclosing marks (e.g., combining accents), format characters, zero-width space, but not U+00AD SOFT HYPHEN. A typical use of this function is with one of g_unichar_iswide() or g_unichar_iswide_cjk() to determine the number of cells a string occupies when displayed on a grid display (terminals). However, note that not all terminals support zero-width rendering of zero-width marks. %TRUE if the character has zero width a Unicode character Converts a single character to UTF-8. number of bytes written, guaranteed to be in the range [1, 6] a Unicode character code output buffer, must have at least 6 bytes of space. If `NULL`, the length will be computed and returned and nothing will be written to @outbuf. Converts a character to lower case. the result of converting @c to lower case. If @c is not an upperlower or titlecase character, or has no lowercase equivalent @c is returned unchanged. a Unicode character. Converts a character to the titlecase. the result of converting @c to titlecase. If @c is not an uppercase or lowercase character, @c is returned unchanged. a Unicode character Converts a character to uppercase. the result of converting @c to uppercase. If @c is not a lowercase or titlecase character, or has no upper case equivalent @c is returned unchanged. a Unicode character Classifies a Unicode character by type. the type of the character. a Unicode character Checks whether @ch is a valid Unicode character. Some possible integer values of @ch will not be valid. U+0000 is considered a valid character, though it’s normally a string terminator. `TRUE` if @ch is a valid Unicode character a Unicode character Determines the numeric value of a character as a hexadecimal digit. If @c is a hex digit (according to g_unichar_isxdigit()), its numeric value. Otherwise, -1. a Unicode character Computes the canonical decomposition of a Unicode character. Use the more flexible g_unichar_fully_decompose() instead. a newly allocated string of Unicode characters. @result_len is set to the resulting length of the string. a Unicode character. location to store the length of the return value. Computes the canonical ordering of a string in-place. This rearranges decomposed characters in the string according to their combining classes. See the Unicode manual for more information. a UCS-4 encoded string. the maximum length of @string to use. Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter codes to scripts. For example, the code for Arabic is 'Arab'. This function accepts four letter codes encoded as a @guint32 in a big-endian fashion. That is, the code expected for Arabic is 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). See [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) for details. the Unicode script for @iso15924, or of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown. a Unicode script Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter codes to scripts. For example, the code for Arabic is 'Arab'. The four letter codes are encoded as a @guint32 by this function in a big-endian fashion. That is, the code returned for Arabic is 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). See [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) for details. the ISO 15924 code for @script, encoded as an integer, of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood. a Unicode script A wrapper for the POSIX unlink() function. The unlink() function deletes a name from the filesystem. If this was the last link to the file and no processes have it opened, the diskspace occupied by the file is freed. See your C library manual for more details about unlink(). Note that on Windows, it is in general not possible to delete files that are open to some process, or mapped into memory. 0 if the name was successfully deleted, -1 if an error occurred a pathname in the GLib file name encoding (UTF-8 on Windows) Removes an environment variable from the environment. Note that on some systems, when variables are overwritten, the memory used for the previous variables and its value isn't reclaimed. You should be mindful of the fact that environment variable handling in UNIX is not thread-safe, and your program may crash if one thread calls g_unsetenv() while another thread is calling getenv(). (And note that many functions, such as gettext(), call getenv() internally.) This function is only safe to use at the very start of your program, before creating any other threads (or creating objects that create worker threads of their own). If you need to set up the environment for a child process, you can use g_get_environ() to get an environment array, modify that with g_environ_setenv() and g_environ_unsetenv(), and then pass that array directly to execvpe(), g_spawn_async(), or the like. the environment variable to remove, must not contain '=' Creates a new #GUri from the given components according to @flags. See also g_uri_build_with_user(), which allows specifying the components of the "userinfo" separately. a new #GUri flags describing how to build the #GUri the URI scheme the userinfo component, or %NULL the host component, or %NULL the port, or `-1` the path component the query component, or %NULL the fragment, or %NULL Creates a new #GUri from the given components according to @flags (%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be coherent with the passed values, in particular use `%`-encoded values with %G_URI_FLAGS_ENCODED. In contrast to g_uri_build(), this allows specifying the components of the ‘userinfo’ field separately. Note that @user must be non-%NULL if either @password or @auth_params is non-%NULL. a new #GUri flags describing how to build the #GUri the URI scheme the user component of the userinfo, or %NULL the password component of the userinfo, or %NULL the auth params of the userinfo, or %NULL the host component, or %NULL the port, or `-1` the path component the query component, or %NULL the fragment, or %NULL Escapes arbitrary data for use in a URI. Normally all characters that are not ‘unreserved’ (i.e. ASCII alphanumerical characters plus dash, dot, underscore and tilde) are escaped. But if you specify characters in @reserved_chars_allowed they are not escaped. This is useful for the ‘reserved’ characters in the URI specification, since those are allowed unescaped in some portions of a URI. Though technically incorrect, this will also allow escaping nul bytes as `%``00`. an escaped version of @unescaped. The returned string should be freed when no longer needed. the unescaped input data. the length of @unescaped a string of reserved characters that are allowed to be used, or %NULL. Escapes a string for use in a URI. Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical characters plus dash, dot, underscore and tilde) are escaped. But if you specify characters in @reserved_chars_allowed they are not escaped. This is useful for the "reserved" characters in the URI specification, since those are allowed unescaped in some portions of a URI. an escaped version of @unescaped. The returned string should be freed when no longer needed. the unescaped input string. a string of reserved characters that are allowed to be used, or %NULL. %TRUE if the result can include UTF-8 characters. Parses @uri_string according to @flags, to determine whether it is a valid [absolute URI](#relative-and-absolute-uris), i.e. it does not need to be resolved relative to another URI using g_uri_parse_relative(). If it’s not a valid URI, an error is returned explaining how it’s invalid. See g_uri_split(), and the definition of #GUriFlags, for more information on the effect of @flags. %TRUE if @uri_string is a valid absolute URI, %FALSE on error. a string containing an absolute URI flags for parsing @uri_string Joins the given components together according to @flags to create an absolute URI string. @path may not be %NULL (though it may be the empty string). When @host is present, @path must either be empty or begin with a slash (`/`) character. When @host is not present, @path cannot begin with two slash characters (`//`). See [RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3). See also g_uri_join_with_user(), which allows specifying the components of the ‘userinfo’ separately. %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set in @flags. an absolute URI string flags describing how to build the URI string the URI scheme, or %NULL the userinfo component, or %NULL the host component, or %NULL the port, or `-1` the path component the query component, or %NULL the fragment, or %NULL Joins the given components together according to @flags to create an absolute URI string. @path may not be %NULL (though it may be the empty string). In contrast to g_uri_join(), this allows specifying the components of the ‘userinfo’ separately. It otherwise behaves the same. %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set in @flags. an absolute URI string flags describing how to build the URI string the URI scheme, or %NULL the user component of the userinfo, or %NULL the password component of the userinfo, or %NULL the auth params of the userinfo, or %NULL the host component, or %NULL the port, or `-1` the path component the query component, or %NULL the fragment, or %NULL Splits an URI list conforming to the text/uri-list mime type defined in RFC 2483 into individual URIs, discarding any comments. The URIs are not validated. a newly allocated %NULL-terminated list of strings holding the individual URIs. The array should be freed with g_strfreev(). an URI list Parses @uri_string according to @flags. If the result is not a valid [absolute URI](#relative-and-absolute-uris), it will be discarded, and an error returned. a new #GUri, or NULL on error. a string representing an absolute URI flags describing how to parse @uri_string Many URI schemes include one or more attribute/value pairs as part of the URI value. This method can be used to parse them into a hash table. When an attribute has multiple occurrences, the last value is the final returned value. If you need to handle repeated attributes differently, use #GUriParamsIter. The @params string is assumed to still be `%`-encoded, but the returned values will be fully decoded. (Thus it is possible that the returned values may contain `=` or @separators, if the value was encoded in the input.) Invalid `%`-encoding is treated as with the %G_URI_FLAGS_PARSE_RELAXED rules for g_uri_parse(). (However, if @params is the path or query string from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED and %G_URI_FLAGS_ENCODED, then you already know that it does not contain any invalid encoding.) %G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init(). If %G_URI_PARAMS_CASE_INSENSITIVE is passed to @flags, attributes will be compared case-insensitively, so a params string `attr=123&Attr=456` will only return a single attribute–value pair, `Attr=456`. Case will be preserved in the returned attributes. If @params cannot be parsed (for example, it contains two @separators characters in a row), then @error is set and %NULL is returned. A hash table of attribute/value pairs, with both names and values fully-decoded; or %NULL on error. a `%`-encoded string containing `attribute=value` parameters the length of @params, or `-1` if it is nul-terminated the separator byte character set between parameters. (usually `&`, but sometimes `;` or both `&;`). Note that this function works on bytes not characters, so it can't be used to delimit UTF-8 strings for anything but ASCII characters. You may pass an empty set, in which case no splitting will occur. flags to modify the way the parameters are handled. Gets the scheme portion of a URI string. [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme as: |[ URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] ]| Common schemes include `file`, `https`, `svn+ssh`, etc. The ‘scheme’ component of the URI, or %NULL on error. The returned string should be freed when no longer needed. a valid URI. Gets the scheme portion of a URI string. [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme as: |[ URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] ]| Common schemes include `file`, `https`, `svn+ssh`, etc. Unlike g_uri_parse_scheme(), the returned scheme is normalized to all-lowercase and does not need to be freed. The ‘scheme’ component of the URI, or %NULL on error. The returned string is normalized to all-lowercase, and interned via g_intern_string(), so it does not need to be freed. a valid URI. Parses @uri_ref according to @flags and, if it is a [relative URI](#relative-and-absolute-uris), resolves it relative to @base_uri_string. If the result is not a valid absolute URI, it will be discarded, and an error returned. (If @base_uri_string is %NULL, this just returns @uri_ref, or %NULL if @uri_ref is invalid or not absolute.) the resolved URI string, or NULL on error. a string representing a base URI a string representing a relative or absolute URI flags describing how to parse @uri_ref Parses @uri_ref (which can be an [absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces. Any component that doesn't appear in @uri_ref will be returned as %NULL (but note that all URIs always have a path component, though it may be the empty string). If @flags contains %G_URI_FLAGS_ENCODED, then `%`-encoded characters in @uri_ref will remain encoded in the output strings. (If not, then all such characters will be decoded.) Note that decoding will only work if the URI components are ASCII or UTF-8, so you will need to use %G_URI_FLAGS_ENCODED if they are not. Note that the %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(), since it always returns only the full userinfo; use g_uri_split_with_user() if you want it split up. %TRUE if @uri_ref parsed successfully, %FALSE on error. a string containing a relative or absolute URI flags for parsing @uri_ref on return, contains the scheme (converted to lowercase), or %NULL on return, contains the userinfo, or %NULL on return, contains the host, or %NULL on return, contains the port, or `-1` on return, contains the path on return, contains the query, or %NULL on return, contains the fragment, or %NULL Parses @uri_string (which must be an [absolute URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces relevant to connecting to a host. See the documentation for g_uri_split() for more details; this is mostly a wrapper around that function with simpler arguments. However, it will return an error if @uri_string is a relative URI, or does not contain a hostname component. %TRUE if @uri_string parsed successfully, %FALSE on error. a string containing an absolute URI flags for parsing @uri_string on return, contains the scheme (converted to lowercase), or %NULL on return, contains the host, or %NULL on return, contains the port, or `-1` Parses @uri_ref (which can be an [absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces. Any component that doesn't appear in @uri_ref will be returned as %NULL (but note that all URIs always have a path component, though it may be the empty string). See g_uri_split(), and the definition of #GUriFlags, for more information on the effect of @flags. Note that @password will only be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and @auth_params will only be parsed out if @flags contains %G_URI_FLAGS_HAS_AUTH_PARAMS. %TRUE if @uri_ref parsed successfully, %FALSE on error. a string containing a relative or absolute URI flags for parsing @uri_ref on return, contains the scheme (converted to lowercase), or %NULL on return, contains the user, or %NULL on return, contains the password, or %NULL on return, contains the auth_params, or %NULL on return, contains the host, or %NULL on return, contains the port, or `-1` on return, contains the path on return, contains the query, or %NULL on return, contains the fragment, or %NULL Unescapes a segment of an escaped string as binary data. Note that in contrast to g_uri_unescape_string(), this does allow nul bytes to appear in the output. If any of the characters in @illegal_characters appears as an escaped character in @escaped_string, then that is an error and %NULL will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. an unescaped version of @escaped_string or %NULL on error (if decoding failed, using %G_URI_ERROR_FAILED error code). The returned #GBytes should be unreffed when no longer needed. A URI-escaped string the length (in bytes) of @escaped_string to escape, or `-1` if it is nul-terminated. a string of illegal characters not to be allowed, or %NULL. Unescapes a segment of an escaped string. If any of the characters in @illegal_characters or the NUL character appears as an escaped character in @escaped_string, then that is an error and %NULL will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. Note: `NUL` byte is not accepted in the output, in contrast to g_uri_unescape_bytes(). an unescaped version of @escaped_string, or %NULL on error. The returned string should be freed when no longer needed. As a special case if %NULL is given for @escaped_string, this function will return %NULL. A string, may be %NULL Pointer to end of @escaped_string, may be %NULL An optional string of illegal characters not to be allowed, may be %NULL Unescapes a whole escaped string. If any of the characters in @illegal_characters or the NUL character appears as an escaped character in @escaped_string, then that is an error and %NULL will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. an unescaped version of @escaped_string. The returned string should be freed when no longer needed. an escaped string to be unescaped. a string of illegal characters not to be allowed, or %NULL. Pauses the current thread for the given number of microseconds. There are 1 million microseconds per second (represented by the %G_USEC_PER_SEC macro). g_usleep() may have limited precision, depending on hardware and operating system; don't rely on the exact length of the sleep. number of microseconds to pause Convert a string from UTF-16 to UCS-4. The result will be nul-terminated. a pointer to a newly allocated UCS-4 string. This value must be freed with [func@GLib.free]. a UTF-16 encoded string the maximum length (number of #gunichar2) of @str to use. If @len is negative, then the string is nul-terminated. location to store number of `gunichar2` read, or `NULL` to ignore. If `NULL`, then [error@GLib.ConvertError.PARTIAL_INPUT] will be returned in case @str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here. The value stored here will never be negative. location to store number of characters written, or `NULL` to ignore. The value stored here does not include the trailing nul, and will never be negative. Convert a string from UTF-16 to UTF-8. The result will be terminated with a nul byte. Note that the input is expected to be already in native endianness, an initial byte-order-mark character is not handled specially. [func@GLib.convert] can be used to convert a byte buffer of UTF-16 data of ambiguous endianness. Further note that this function does not validate the result string; it may (for example) include embedded nul characters. The only validation done by this function is to ensure that the input can be correctly interpreted as UTF-16, i.e. it doesn’t contain unpaired surrogates or partial character sequences. a pointer to a newly allocated UTF-8 string. This value must be freed with [func@GLib.free]. a UTF-16 encoded string the maximum length (number of #gunichar2) of @str to use. If @len is negative, then the string is nul-terminated. location to store number of `gunichar2` read, or `NULL` to ignore. If `NULL`, then [error@GLib.ConvertError.PARTIAL_INPUT] will be returned in case @str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here. The value stored here will never be negative. location to store number of bytes written, or `NULL` to ignore. The value stored here does not include the trailing nul, and will never be negative. Converts a string into a form that is independent of case. The result will not correspond to any particular case, but can be compared for equality or ordered with the results of calling g_utf8_casefold() on other strings. Note that calling g_utf8_casefold() followed by g_utf8_collate() is only an approximation to the correct linguistic case insensitive ordering, though it is a fairly good one. Getting this exactly right would require a more sophisticated collation function that takes case sensitivity into account. GLib does not currently provide such a function. a newly allocated string, that is a case independent form of @str. a UTF-8 encoded string length of @str, in bytes, or -1 if @str is nul-terminated. Compares two strings for ordering using the linguistically correct rules for the [current locale](running.html#locale). When sorting a large number of strings, it will be significantly faster to obtain collation keys with g_utf8_collate_key() and compare the keys with strcmp() when sorting instead of sorting the original strings. If the two strings are not comparable due to being in different collation sequences, the result is undefined. This can happen if the strings are in different language scripts, for example. < 0 if @str1 compares before @str2, 0 if they compare equal, > 0 if @str1 compares after @str2. a UTF-8 encoded string a UTF-8 encoded string Converts a string into a collation key that can be compared with other collation keys produced by the same function using strcmp(). The results of comparing the collation keys of two strings with strcmp() will always be the same as comparing the two original keys with g_utf8_collate(). Note that this function depends on the [current locale](running.html#locale). Note that the returned string is not guaranteed to be in any encoding, especially UTF-8. The returned value is meant to be used only for comparisons. a newly allocated string. The contents of the string are only meant to be used when sorting. This string should be freed with g_free() when you are done with it. a UTF-8 encoded string. length of @str, in bytes, or -1 if @str is nul-terminated. Converts a string into a collation key that can be compared with other collation keys produced by the same function using strcmp(). In order to sort filenames correctly, this function treats the dot '.' as a special case. Most dictionary orderings seem to consider it insignificant, thus producing the ordering "event.c" "eventgenerator.c" "event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we would like to treat numbers intelligently so that "file1" "file10" "file5" is sorted as "file1" "file5" "file10". Note that this function depends on the [current locale](running.html#locale). Note that the returned string is not guaranteed to be in any encoding, especially UTF-8. The returned value is meant to be used only for comparisons. a newly allocated string. The contents of the string are only meant to be used when sorting. This string should be freed with g_free() when you are done with it. a UTF-8 encoded string. length of @str, in bytes, or -1 if @str is nul-terminated. Finds the start of the next UTF-8 character in the string after @p. @p does not have to be at the beginning of a UTF-8 character. No check is made to see if the character found is actually valid other than it starts with an appropriate byte. If @end is `NULL`, the return value will never be `NULL`: if the end of the string is reached, a pointer to the terminating nul byte is returned. If @end is non-`NULL`, the return value will be `NULL` if the end of the string is reached. a pointer to the found character or `NULL` if @end is set and is reached a pointer to a position within a UTF-8 encoded string a pointer to the byte following the end of the string, or `NULL` to indicate that the string is nul-terminated Given a position @p with a UTF-8 encoded string @str, find the start of the previous UTF-8 character starting before @p. Returns `NULL` if no UTF-8 characters are present in @str before @p. @p does not have to be at the beginning of a UTF-8 character. No check is made to see if the character found is actually valid other than it starts with an appropriate byte. a pointer to the found character pointer to the beginning of a UTF-8 encoded string pointer to some position within @str Converts a sequence of bytes encoded as UTF-8 to a Unicode character. If @p does not point to a valid UTF-8 encoded character, results are undefined. If you are not sure that the bytes are complete valid Unicode characters, you should use [func@GLib.utf8_get_char_validated] instead. the resulting character a pointer to Unicode character encoded as UTF-8 Convert a sequence of bytes encoded as UTF-8 to a Unicode character. This function checks for incomplete characters, for invalid characters such as characters that are out of the range of Unicode, and for overlong encodings of valid characters. Note that [func@GLib.utf8_get_char_validated] returns `(gunichar)-2` if @max_len is positive and any of the bytes in the first UTF-8 character sequence are nul. the resulting character. If @p points to a partial sequence at the end of a string that could begin a valid character (or if @max_len is zero), returns `(gunichar)-2`; otherwise, if @p does not point to a valid UTF-8 encoded Unicode character, returns `(gunichar)-1`. a pointer to Unicode character encoded as UTF-8 the maximum number of bytes to read, or `-1` if @p is nul-terminated If the provided string is valid UTF-8, return a copy of it. If not, return a copy in which bytes that could not be interpreted as valid Unicode are replaced with the Unicode replacement character (U+FFFD). For example, this is an appropriate function to use if you have received a string that was incorrectly declared to be UTF-8, and you need a valid UTF-8 version of it that can be logged or displayed to the user, with the assumption that it is close enough to ASCII or UTF-8 to be mostly readable as-is. a valid UTF-8 string whose content resembles @str string to coerce into UTF-8 the maximum length of @str to use, in bytes. If @len is negative, then the string is nul-terminated. Skips to the next character in a UTF-8 string. The string must be valid; this macro is as fast as possible, and has no error-checking. You would use this macro to iterate over a string character by character. The macro returns the start of the next UTF-8 character. Before using this macro, use g_utf8_validate() to validate strings that may contain invalid UTF-8. Pointer to the start of a valid UTF-8 character Converts a string into canonical form, standardizing such issues as whether a character with an accent is represented as a base character and combining accent or as a single precomposed character. The string has to be valid UTF-8, otherwise %NULL is returned. You should generally call g_utf8_normalize() before comparing two Unicode strings. The normalization mode %G_NORMALIZE_DEFAULT only standardizes differences that do not affect the text content, such as the above-mentioned accent representation. %G_NORMALIZE_ALL also standardizes the "compatibility" characters in Unicode, such as SUPERSCRIPT THREE to the standard forms (in this case DIGIT THREE). Formatting information may be lost but for most text operations such characters should be considered the same. %G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_ALL, but returned a result with composed forms rather than a maximally decomposed form. This is often useful if you intend to convert the string to a legacy encoding or pass it to a system with less capable Unicode handling. a newly allocated string, that is the normalized form of @str, or %NULL if @str is not valid UTF-8. a UTF-8 encoded string. length of @str, in bytes, or -1 if @str is nul-terminated. the type of normalization to perform. Converts from an integer character offset to a pointer to a position within the string. Since 2.10, this function allows to pass a negative @offset to step backwards. It is usually worth stepping backwards from the end instead of forwards if @offset is in the last fourth of the string, since moving forward is about 3 times faster than moving backward. Note that this function doesn’t abort when reaching the end of @str. Therefore you should be sure that @offset is within string boundaries before calling that function. Call [func@GLib.utf8_strlen] when unsure. This limitation exists as this function is called frequently during text rendering and therefore has to be as fast as possible. the resulting pointer a UTF-8 encoded string a character offset within @str Converts from a pointer to position within a string to an integer character offset. Since 2.10, this function allows @pos to be before @str, and returns a negative offset in this case. the resulting character offset a UTF-8 encoded string a pointer to a position within @str Finds the previous UTF-8 character in the string before @p. @p does not have to be at the beginning of a UTF-8 character. No check is made to see if the character found is actually valid other than it starts with an appropriate byte. If @p might be the first character of the string, you must use [func@GLib.utf8_find_prev_char] instead. a pointer to the found character a pointer to a position within a UTF-8 encoded string Finds the leftmost occurrence of the given Unicode character in a UTF-8 encoded string, while limiting the search to @len bytes. If @len is `-1`, allow unbounded search. `NULL` if the string does not contain the character, otherwise, a pointer to the start of the leftmost occurrence of the character in the string. a nul-terminated UTF-8 encoded string the maximum length of @p a Unicode character Converts all Unicode characters in the string that have a case to lowercase. The exact manner that this is done depends on the current locale, and may result in the number of characters in the string changing. a newly allocated string, with all characters converted to lowercase. a UTF-8 encoded string length of @str, in bytes, or -1 if @str is nul-terminated. Computes the length of the string in characters, not including the terminating nul character. If the @max’th byte falls in the middle of a character, the last (partial) character is not counted. the length of the string in characters pointer to the start of a UTF-8 encoded string the maximum number of bytes to examine. If @max is less than 0, then the string is assumed to be nul-terminated. If @max is 0, @p will not be examined and may be `NULL`. If @max is greater than 0, up to @max bytes are examined Like the standard C [`strncpy()`](man:strncpy) function, but copies a given number of characters instead of a given number of bytes. The @src string must be valid UTF-8 encoded text. (Use [func@GLib.utf8_validate] on all text before trying to use UTF-8 utility functions with it.) Note you must ensure @dest is at least 4 * @n + 1 to fit the largest possible UTF-8 characters @dest buffer to fill with characters from @src UTF-8 encoded string character count Find the rightmost occurrence of the given Unicode character in a UTF-8 encoded string, while limiting the search to @len bytes. If @len is `-1`, allow unbounded search. `NULL` if the string does not contain the character, otherwise, a pointer to the start of the rightmost occurrence of the character in the string. a nul-terminated UTF-8 encoded string the maximum length of @p a Unicode character Reverses a UTF-8 string. @str must be valid UTF-8 encoded text. (Use [func@GLib.utf8_validate] on all text before trying to use UTF-8 utility functions with it.) This function is intended for programmatic uses of reversed strings. It pays no attention to decomposed characters, combining marks, byte order marks, directional indicators (LRM, LRO, etc) and similar characters which might need special handling when reversing a string for display purposes. Note that unlike [func@GLib.strreverse], this function returns newly-allocated memory, which should be freed with [func@GLib.free] when no longer needed. a newly-allocated string which is the reverse of @str a UTF-8 encoded string the maximum length of @str to use, in bytes. If @len is negative, then the string is nul-terminated. Converts all Unicode characters in the string that have a case to uppercase. The exact manner that this is done depends on the current locale, and may result in the number of characters in the string increasing. (For instance, the German ess-zet will be changed to SS.) a newly allocated string, with all characters converted to uppercase. a UTF-8 encoded string length of @str, in bytes, or -1 if @str is nul-terminated. Copies a substring out of a UTF-8 encoded string. The substring will contain @end_pos - @start_pos characters. Since GLib 2.72, `-1` can be passed to @end_pos to indicate the end of the string. a newly allocated copy of the requested substring. Free with [func@GLib.free] when no longer needed. a UTF-8 encoded string a character offset within @str another character offset within @str, or `-1` to indicate the end of the string Convert a string from UTF-8 to a 32-bit fixed width representation as UCS-4. A trailing nul character (U+0000) will be added to the string after the converted text. a pointer to a newly allocated UCS-4 string. This value must be freed with [func@GLib.free]. a UTF-8 encoded string the maximum length of @str to use, in bytes. If @len is negative, then the string is nul-terminated. location to store number of bytes read, or `NULL` to ignore. If `NULL`, then [error@GLib.ConvertError.PARTIAL_INPUT] will be returned in case @str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here. The value stored here will never be negative. location to store number of characters written, or `NULL` to ignore. The value stored here does not include the trailing nul, and will never be negative. Convert a string from UTF-8 to a 32-bit fixed width representation as UCS-4, assuming valid UTF-8 input. This function is roughly twice as fast as [func@GLib.utf8_to_ucs4] but does no error checking on the input. A trailing nul character (U+0000) will be added to the string after the converted text. a pointer to a newly allocated UCS-4 string. This value must be freed with [func@GLib.free]. a UTF-8 encoded string the maximum length of @str to use, in bytes. If @len is negative, then the string is nul-terminated. location to store the number of characters in the result, or `NULL`. Convert a string from UTF-8 to UTF-16. A nul character (U+0000) will be added to the result after the converted text. a pointer to a newly allocated UTF-16 string. This value must be freed with [func@GLib.free]. a UTF-8 encoded string the maximum length (number of bytes) of @str to use. If @len is negative, then the string is nul-terminated. location to store number of bytes read, or `NULL` to ignore. If `NULL`, then [error@GLib.ConvertError.PARTIAL_INPUT] will be returned in case @str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here. The value stored here will never be negative. location to store number of `gunichar2` written, or `NULL` to ignore. The value stored here does not include the trailing nul, and will never be negative. Cuts off the middle of the string, preserving half of @truncate_length characters at the beginning and half at the end. If @string is already short enough, this returns a copy of @string. If @truncate_length is `0`, an empty string is returned. a newly-allocated copy of @string ellipsized in the middle a nul-terminated UTF-8 encoded string the new size of @string, in characters, including the ellipsis character Validates UTF-8 encoded text. @str is the text to validate; if @str is nul-terminated, then @max_len can be `-1`, otherwise @max_len should be the number of bytes to validate. If @end is non-`NULL`, then the end of the valid range will be stored there. This is the first byte of the first invalid character if some bytes were invalid, or the end of the text being validated otherwise — either the trailing nul byte, or the first byte beyond @max_len (if it’s positive). Note that `g_utf8_validate()` returns `FALSE` if @max_len is positive and any of the @max_len bytes are nul. Returns `TRUE` if all of @str was valid. Many GLib and GTK routines require valid UTF-8 as input; so data read from a file or the network should be checked with `g_utf8_validate()` before doing anything else with it. `TRUE` if the text was valid UTF-8 a pointer to character data max bytes to validate, or `-1` to go until nul return location for end of valid data Validates UTF-8 encoded text. As with [func@GLib.utf8_validate], but @max_len must be set, and hence this function will always return `FALSE` if any of the bytes of @str are nul. `TRUE` if the text was valid UTF-8 a pointer to character data max bytes to validate return location for end of valid data A wrapper for the POSIX utime() function. The utime() function sets the access and modification timestamps of a file. See your C library manual for more details about how utime() works on your system. 0 if the operation was successful, -1 if an error occurred a pathname in the GLib file name encoding (UTF-8 on Windows) a pointer to a struct utimbuf. Parses the string @str and verify if it is a UUID. The function accepts the following syntax: - simple forms (e.g. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`) Note that hyphens are required within the UUID string itself, as per the aforementioned RFC. %TRUE if @str is a valid UUID, %FALSE otherwise. a string representing a UUID Generates a random UUID (RFC 4122 version 4) as a string. It has the same randomness guarantees as #GRand, so must not be used for cryptographic purposes such as key generation, nonces, salts or one-time pads. A string that should be freed with g_free(). Determines if a given string is a valid D-Bus object path. You should ensure that a string is a valid D-Bus object path before passing it to g_variant_new_object_path(). A valid object path starts with `/` followed by zero or more sequences of characters separated by `/` characters. Each sequence must contain only the characters `[A-Z][a-z][0-9]_`. No sequence (including the one following the final `/` character) may be empty. %TRUE if @string is a D-Bus object path a normal C nul-terminated string Determines if a given string is a valid D-Bus type signature. You should ensure that a string is a valid D-Bus type signature before passing it to g_variant_new_signature(). D-Bus type signatures consist of zero or more definite #GVariantType strings in sequence. %TRUE if @string is a D-Bus type signature a normal C nul-terminated string Parses a #GVariant from a text representation. A single #GVariant is parsed from the content of @text. The format is described [here](gvariant-text-format.html). The memory at @limit will never be accessed and the parser behaves as if the character at @limit is the nul terminator. This has the effect of bounding @text. If @endptr is non-%NULL then @text is permitted to contain data following the value that this function parses and @endptr will be updated to point to the first character past the end of the text parsed by this function. If @endptr is %NULL and there is extra data then an error is returned. If @type is non-%NULL then the value will be parsed to have that type. This may result in additional parse errors (in the case that the parsed value doesn't fit the type) but may also result in fewer errors (in the case that the type would have been ambiguous, such as with empty arrays). In the event that the parsing is successful, the resulting #GVariant is returned. It is never floating, and must be freed with [method@GLib.Variant.unref]. In case of any error, %NULL will be returned. If @error is non-%NULL then it will be set to reflect the error that occurred. Officially, the language understood by the parser is “any string produced by [method@GLib.Variant.print]”. This explicitly includes `g_variant_print()`’s annotated types like `int64 -1000`. There may be implementation specific restrictions on deeply nested values, which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is guaranteed to handle nesting up to at least 64 levels. a non-floating reference to a #GVariant, or %NULL a #GVariantType, or %NULL a string containing a GVariant in text form a pointer to the end of @text, or %NULL a location to store the end pointer, or %NULL Pretty-prints a message showing the context of a #GVariant parse error within the string for which parsing was attempted. The resulting string is suitable for output to the console or other monospace media where newlines are treated in the usual way. The message will typically look something like one of the following: |[ unterminated string constant: (1, 2, 3, 'abc ^^^^ ]| or |[ unable to find a common type: [1, 2, 3, 'str'] ^ ^^^^^ ]| The format of the message may change in a future version. @error must have come from a failed attempt to g_variant_parse() and @source_str must be exactly the same string that caused the error. If @source_str was not nul-terminated when you passed it to g_variant_parse() then you must add nul termination before using this function. the printed message a #GError from the #GVariantParseError domain the string that was given to the parser Same as g_variant_error_quark(). Use g_variant_parse_error_quark() instead. Checks if @type_string is a valid [GVariant type string](./struct.VariantType.html#gvariant-type-strings). This call is equivalent to calling [func@GLib.VariantType.string_scan] and confirming that the following character is a nul terminator. true if @type_string is exactly one valid type string Since 2.24 a pointer to any string Scan for a single complete and valid GVariant type string in @string. The memory pointed to by @limit (or bytes beyond it) is never accessed. If a valid type string is found, @endptr is updated to point to the first character past the end of the string that was found and %TRUE is returned. If there is no valid type string starting at @string, or if the type string does not end before @limit then %FALSE is returned. For the simple case of checking if a string is a valid type string, see [func@GLib.VariantType.string_is_valid]. true if a valid type string was found a pointer to any string the end of @string location to store the end pointer An implementation of the GNU `vasprintf()` function which supports positional parameters, as specified in the Single Unix Specification. This function is similar to [func@GLib.vsprintf], except that it allocates a string to hold the output, instead of putting the output in a buffer you allocate in advance. The returned value in @string is guaranteed to be non-`NULL`, unless @format contains `%lc` or `%ls` conversions, which can fail if no multibyte representation is available for the given character. `glib/gprintf.h` must be explicitly included in order to use this function. the number of bytes printed, or -1 on failure the return location for the newly-allocated string, which will be `NULL` if (and only if) this function fails a standard `printf()` format string, but notice [string precision pitfalls](string-utils.html#string-precision-pitfalls) the list of arguments to insert in the output An implementation of the standard `fprintf()` function which supports positional parameters, as specified in the Single Unix Specification. `glib/gprintf.h` must be explicitly included in order to use this function. the number of bytes printed the stream to write to a standard `printf()` format string, but notice [string precision pitfalls](string-utils.html#string-precision-pitfalls) the list of arguments to insert in the output An implementation of the standard `vprintf()` function which supports positional parameters, as specified in the Single Unix Specification. `glib/gprintf.h` must be explicitly included in order to use this function. the number of bytes printed a standard `printf()` format string, but notice [string precision pitfalls](string-utils.html#string-precision-pitfalls) the list of arguments to insert in the output A safer form of the standard `vsprintf()` function. The output is guaranteed to not exceed @n characters (including the terminating nul character), so it is easy to ensure that a buffer overflow cannot occur. See also [func@GLib.strdup_vprintf]. In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be nul-terminated. In versions prior to 1.3.12, this function returns the length of the output string. The return value of `g_vsnprintf()` conforms to the `vsnprintf()` function as standardized in ISO C99. Note that this is different from traditional `vsnprintf()`, which returns the length of the output string. The format string may contain positional parameters, as specified in the Single Unix Specification. the number of bytes which would be produced if the buffer was large enough the buffer to hold the output the maximum number of bytes to produce (including the terminating nul character) a standard `printf()` format string, but notice [string precision pitfalls](string-utils.html#string-precision-pitfalls) the list of arguments to insert in the output An implementation of the standard `vsprintf()` function which supports positional parameters, as specified in the Single Unix Specification. `glib/gprintf.h` must be explicitly included in order to use this function. the number of bytes printed the buffer to hold the output a standard `printf()` format string, but notice [string precision pitfalls](string-utils.html#string-precision-pitfalls) the list of arguments to insert in the output Logs a warning if the expression is not true. Unlike g_return_if_fail(), the expression is always evaluated, even if checks and assertions are disabled. the expression to check Logs a warning. Internal function used to print messages from the public [func@GLib.warn_if_reached] and [func@GLib.warn_if_fail] macros. log domain file containing the warning line number of the warning function containing the warning expression which failed A convenience function/macro to log a warning message. The message should typically *not* be translated to the user’s language. This is not intended for end user error reporting. Use of [type@GLib.Error] is preferred for that instead, as it allows calling functions to perform actions conditional on the type of error. Warning messages are intended to be used in the event of unexpected external conditions (system misconfiguration, missing files, other trusted programs violating protocol, invalid contents in trusted files, etc.) If attempting to deal with programmer errors (for example, incorrect function parameters) then you should use [flags@GLib.LogLevelFlags.LEVEL_CRITICAL] instead. [func@GLib.warn_if_reached] and func@GLib.warn_if_fail] log at [flags@GLib.LogLevelFlags.LEVEL_WARNING]. You can make warnings fatal at runtime by setting the `G_DEBUG` environment variable (see [Running GLib Applications](running.html)): ``` G_DEBUG=fatal-warnings gdb ./my-program ``` Any unrelated failures can be skipped over in [gdb](https://www.gnu.org/software/gdb/) using the `continue` command. If [func@GLib.log_default_handler] is used as the log handler function, a newline character will automatically be appended to @..., and need not be entered manually. If structured logging is enabled, this will use [func@GLib.log_structured]; otherwise it will use [func@GLib.log]. See [Using Structured Logging](logging.html#using-structured-logging). format string, followed by parameters to insert into the format string (as with `printf()`) Logs a warning only once. g_warning_once() calls g_warning() with the passed message the first time the statement is executed; subsequent times it is a no-op. Note! On platforms where the compiler doesn't support variadic macros, the warning is printed each time instead of only once. format string, followed by parameters to insert into the format string (as with printf()) soup3-0.9.0/gir-files/GLibUnix-2.0.gir000064400000000000000000000626341046102023000152600ustar 00000000000000 The type of functions to be called when a UNIX fd watch source triggers. %FALSE if the source should be removed the fd that triggered the event the IO conditions reported on @fd user data passed to g_unix_fd_add() A Unix pipe. The advantage of this type over `int[2]` is that it can be closed automatically when it goes out of scope, using `g_auto(GUnixPipe)`, on compilers that support that feature. A pair of file descriptors, each negative if closed or not yet opened. The file descriptor with index %G_UNIX_PIPE_END_READ is readable. The file descriptor with index %G_UNIX_PIPE_END_WRITE is writable. Close both ends of the pipe, unless they have already been closed or stolen. Any errors are ignored: use g_unix_pipe_close() or g_clear_fd() if error-handling is required. This function is async-signal safe if @error is %NULL and each member of @fds are either negative or a valid open file descriptor. As a result, it is safe to call this function or use `g_auto(GUnixPipe)` (on compilers that support it) in a signal handler or a #GSpawnChildSetupFunc, as long as those conditions are ensured to be true. See [`signal(7)`](man:signal(7)) and [`signal-safety(7)`](man:signal-safety(7)) for more details. This function preserves the value of `errno`. a #GUnixPipe Close one of the ends of the pipe and set the relevant member of @fds to `-1` before returning, equivalent to g_clear_fd(). Like g_close(), if closing the file descriptor fails, the error is stored in both %errno and @error. If this function succeeds, %errno is undefined. This function is async-signal safe if @error is %NULL and the relevant member of @fds is either negative or a valid open file descriptor. This makes it safe to call from a signal handler or a #GSpawnChildSetupFunc under those conditions. See [`signal(7)`](man:signal(7)) and [`signal-safety(7)`](man:signal-safety(7)) for more details. To close both file descriptors and ignore any errors, use g_unix_pipe_clear() instead. %TRUE on success A pair of file descriptors One of the ends of the pipe Return one of the ends of the pipe. It remains owned by @self. This function is async-signal safe (see [`signal(7)`](man:signal(7)) and [`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a signal handler or a #GSpawnChildSetupFunc. This function preserves the value of `errno`. a non-negative file descriptor owned by @self, which must not be closed by the caller, or a negative number if the corresponding end of the pipe was already closed or stolen A pair of file descriptors One of the ends of the pipe Open a pipe. This is the same as g_unix_open_pipe(), but uses the #GUnixPipe data structure. %TRUE on success A pair of file descriptors Flags to pass to g_unix_open_pipe(), typically `O_CLOEXEC` Return one of the ends of the pipe. It becomes owned by the caller, and the file descriptor in the data structure is set to `-1`, similar to g_steal_fd(). This function is async-signal safe (see [`signal(7)`](man:signal(7)) and [`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a signal handler or a #GSpawnChildSetupFunc. This function preserves the value of `errno`. a non-negative file descriptor, which becomes owned by the caller and must be closed by the caller if required, or a negative number if the corresponding end of the pipe was already closed or stolen A pair of file descriptors One of the ends of the pipe Mnemonic constants for the ends of a Unix pipe. The readable file descriptor 0 The writable file descriptor 1 Close every file descriptor equal to or greater than @lowfd. Typically @lowfd will be 3, to leave standard input, standard output and standard error open. This is the same as Linux `close_range (lowfd, ~0U, 0)`, but portable to other OSs and to older versions of Linux. Equivalently, it is the same as BSD `closefrom (lowfd)`, but portable, and async-signal-safe on all OSs. This function is async-signal safe, making it safe to call from a signal handler or a [callback@GLib.SpawnChildSetupFunc], as long as @lowfd is non-negative. See [`signal(7)`](man:signal(7)) and [`signal-safety(7)`](man:signal-safety(7)) for more details. 0 on success, -1 with errno set on error Minimum fd to close, which must be non-negative Sets a function to be called when the IO condition, as specified by @condition becomes true for @fd. @function will be called when the specified IO condition becomes %TRUE. The function is expected to clear whatever event caused the IO condition to become true and return %TRUE in order to be notified when it happens again. If @function returns %FALSE then the watch will be cancelled. The return value of this function can be passed to g_source_remove() to cancel the watch at any time that it exists. The source will never close the fd -- you must do it yourself. the ID (greater than 0) of the event source a file descriptor IO conditions to watch for on @fd a #GUnixFDSourceFunc data to pass to @function Sets a function to be called when the IO condition, as specified by @condition becomes true for @fd. This is the same as g_unix_fd_add(), except that it allows you to specify a non-default priority and a provide a #GDestroyNotify for @user_data. the ID (greater than 0) of the event source the priority of the source a file descriptor IO conditions to watch for on @fd a #GUnixFDSourceFunc data to pass to @function function to call when the idle is removed, or %NULL Queries the file path for the given FD opened by the current process. The file path, or `NULL` on error The file descriptor to query. Creates a #GSource to watch for a particular I/O condition on a file descriptor. The source will never close the @fd — you must do it yourself. Any callback attached to the returned #GSource must have type #GUnixFDSourceFunc. the newly created #GSource a file descriptor I/O conditions to watch for on @fd Mark every file descriptor equal to or greater than @lowfd to be closed at the next `execve()` or similar, as if via the `FD_CLOEXEC` flag. Typically @lowfd will be 3, to leave standard input, standard output and standard error open after exec. This is the same as Linux `close_range (lowfd, ~0U, CLOSE_RANGE_CLOEXEC)`, but portable to other OSs and to older versions of Linux. This function is async-signal safe, making it safe to call from a signal handler or a [callback@GLib.SpawnChildSetupFunc], as long as @lowfd is non-negative. See [`signal(7)`](man:signal(7)) and [`signal-safety(7)`](man:signal-safety(7)) for more details. 0 on success, -1 with errno set on error Minimum fd to act on, which must be non-negative Get the `passwd` file entry for the given @user_name using `getpwnam_r()`. This can fail if the given @user_name doesn’t exist. The returned `struct passwd` has been allocated using g_malloc() and should be freed using g_free(). The strings referenced by the returned struct are included in the same allocation, so are valid until the `struct passwd` is freed. This function is safe to call from multiple threads concurrently. You will need to include `pwd.h` to get the definition of `struct passwd`. passwd entry, or %NULL on error; free the returned value with g_free() the username to get the passwd file entry for Similar to the UNIX pipe() call, but on modern systems like Linux uses the pipe2() system call, which atomically creates a pipe with the configured flags. As of GLib 2.78, the supported flags are `O_CLOEXEC`/`FD_CLOEXEC` (see below) and `O_NONBLOCK`. Prior to GLib 2.78, only `FD_CLOEXEC` was supported — if you wanted to configure `O_NONBLOCK` then that had to be done separately with `fcntl()`. Since GLib 2.80, the constants %G_UNIX_PIPE_END_READ and %G_UNIX_PIPE_END_WRITE can be used as mnemonic indexes in @fds. It is a programmer error to call this function with unsupported flags, and a critical warning will be raised. As of GLib 2.78, it is preferred to pass `O_CLOEXEC` in, rather than `FD_CLOEXEC`, as that matches the underlying `pipe()` API more closely. Prior to 2.78, only `FD_CLOEXEC` was supported. Support for `FD_CLOEXEC` may be deprecated and removed in future. %TRUE on success, %FALSE if not (and errno will be set). Array of two integers Bitfield of file descriptor flags, as for fcntl() Control the non-blocking state of the given file descriptor, according to @nonblock. On most systems this uses %O_NONBLOCK, but on some older ones may use %O_NDELAY. %TRUE if successful A file descriptor If %TRUE, set the descriptor to be non-blocking A convenience function for g_unix_signal_source_new(), which attaches to the default #GMainContext. You can remove the watch using g_source_remove(). An ID (greater than 0) for the event source Signal number Callback Data for @handler A convenience function for g_unix_signal_source_new(), which attaches to the default #GMainContext. You can remove the watch using g_source_remove(). An ID (greater than 0) for the event source the priority of the signal source. Typically this will be in the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. Signal number Callback Data for @handler #GDestroyNotify for @handler Create a #GSource that will be dispatched upon delivery of the UNIX signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`, `SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2` were added. In GLib 2.54, `SIGWINCH` was added. Note that unlike the UNIX default, all sources which have created a watch will be dispatched, regardless of which underlying thread invoked g_unix_signal_source_new(). For example, an effective use of this function is to handle `SIGTERM` cleanly; flushing any outstanding files, and then calling g_main_loop_quit(). It is not safe to do any of this from a regular UNIX signal handler; such a handler may be invoked while malloc() or another library function is running, causing reentrancy issues if the handler attempts to use those functions. None of the GLib/GObject API is safe against this kind of reentrancy. The interaction of this source when combined with native UNIX functions like sigprocmask() is not defined. The source will not initially be associated with any #GMainContext and must be added to one with g_source_attach() before it will be executed. A newly created #GSource A signal number soup3-0.9.0/gir-files/GLibWin32-2.0.gir000064400000000000000000000152551046102023000152340ustar 00000000000000 Type of Windows edition to check for at run-time. The running system can be a workstation or a server edition of Windows. The type of the running system is therefore not checked. The running system is a workstation edition of Windows, such as Windows 7 Professional. The running system is a server edition of Windows, such as Windows Server 2008 R2. Releases the referenced COM object, and clears its pointer to `NULL`. The @com_obj pointer must not be `NULL`. If @com_obj references a `NULL` COM object, this function is a no-op. This is equivalent to `g_clear_object()` for dealing with Windows COM objects. Pointer to COM object pointer to release and clear soup3-0.9.0/gir-files/GModule-2.0.gir000064400000000000000000001366261046102023000151360ustar 00000000000000 The #GModule struct is an opaque data structure to represent a [dynamically-loaded module](modules.html#dynamic-loading-of-modules). It should only be accessed via the following functions. To ensure correct lock ordering, these functions must not be called from global constructors (for example, those using GCC’s `__attribute__((constructor))` attribute). Closes a module. %TRUE on success a #GModule to close Ensures that a module will never be unloaded. Any future g_module_close() calls on the module will be ignored. a #GModule to make permanently resident Returns the filename that the module was opened with. If @module refers to the application itself, "main" is returned. the filename of the module a #GModule Gets a symbol pointer from a module, such as one exported by %G_MODULE_EXPORT. Note that a valid symbol can be %NULL. %TRUE on success a #GModule the name of the symbol to find returns the pointer to the symbol value A portable way to build the filename of a module. The platform-specific prefix and suffix are added to the filename, if needed, and the result is added to the directory, using the correct separator character. The directory should specify the directory where the module can be found. It can be %NULL or an empty string to indicate that the module is in a standard platform-specific directory, though this is not recommended since the wrong module may be found. For example, calling g_module_build_path() on a Linux system with a @directory of `/lib` and a @module_name of "mylibrary" will return `/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the directory it will return `\Windows\mylibrary.dll`. Use g_module_open() instead with @module_name as the basename of the file_name argument. See %G_MODULE_SUFFIX for why. the complete path of the module, including the standard library prefix and suffix. This should be freed when no longer needed the directory where the module is. This can be %NULL or the empty string to indicate that the standard platform-specific directories will be used, though that is not recommended the name of the module Gets a string describing the last module error. a string describing the last module error A thin wrapper function around g_module_open_full() a #GModule on success, or %NULL on failure the name or path to the file containing the module, or %NULL to obtain a #GModule representing the main program itself the flags used for opening the module. This can be the logical OR of any of the #GModuleFlags. Opens a module. If the module has already been opened, its reference count is incremented. If not, the module is searched using @file_name. Since 2.76, the search order/behavior is as follows: 1. If @file_name exists as a regular file, it is used as-is; else 2. If @file_name doesn't have the correct suffix and/or prefix for the platform, then possible suffixes and prefixes will be added to the basename till a file is found and whatever is found will be used; else 3. If @file_name doesn't have the ".la"-suffix, ".la" is appended. Either way, if a matching .la file exists (and is a libtool archive) the libtool archive is parsed to find the actual file name, and that is used. If, at the end of all this, we have a file path that we can access on disk, it is opened as a module. If not, @file_name is attempted to be opened as a module verbatim in the hopes that the system implementation will somehow be able to access it. If that is not possible, %NULL is returned. Note that this behaviour was different prior to 2.76, but there is some overlap in functionality. If backwards compatibility is an issue, kindly consult earlier #GModule documentation for the prior search order/behavior of @file_name. a #GModule on success, or %NULL on failure the name or path to the file containing the module, or %NULL to obtain a #GModule representing the main program itself the flags used for opening the module. This can be the logical OR of any of the #GModuleFlags Checks if modules are supported on the current platform. %TRUE if modules are supported Specifies the type of the module initialization function. If a module contains a function named g_module_check_init() it is called automatically when the module is loaded. It is passed the #GModule structure and should return %NULL on success or a string describing the initialization error. %NULL on success, or a string describing the initialization error the #GModule corresponding to the module which has just been loaded Errors returned by g_module_open_full(). there was an error loading or opening a module file a module returned an error from its `g_module_check_init()` function Flags passed to g_module_open(). Note that these flags are not supported on all platforms. specifies that symbols are only resolved when needed. The default action is to bind all symbols when the module is loaded. specifies that symbols in the module should not be added to the global name space. The default action on most platforms is to place symbols in the module in the global name space, which may cause conflicts with existing symbols. mask for all flags. Specifies the type of the module function called when it is unloaded. If a module contains a function named g_module_unload() it is called automatically when the module is unloaded. It is passed the #GModule structure. the #GModule about to be unloaded A portable way to build the filename of a module. The platform-specific prefix and suffix are added to the filename, if needed, and the result is added to the directory, using the correct separator character. The directory should specify the directory where the module can be found. It can be %NULL or an empty string to indicate that the module is in a standard platform-specific directory, though this is not recommended since the wrong module may be found. For example, calling g_module_build_path() on a Linux system with a @directory of `/lib` and a @module_name of "mylibrary" will return `/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the directory it will return `\Windows\mylibrary.dll`. Use g_module_open() instead with @module_name as the basename of the file_name argument. See %G_MODULE_SUFFIX for why. the complete path of the module, including the standard library prefix and suffix. This should be freed when no longer needed the directory where the module is. This can be %NULL or the empty string to indicate that the standard platform-specific directories will be used, though that is not recommended the name of the module Gets a string describing the last module error. a string describing the last module error Checks if modules are supported on the current platform. %TRUE if modules are supported soup3-0.9.0/gir-files/GObject-2.0.gir000064400000000000000000035577341046102023000151310ustar 00000000000000 This is the signature of marshaller functions, required to marshall arrays of parameter values to signal emissions into C language callback invocations. It is merely an alias to #GClosureMarshal since the #GClosure mechanism takes over responsibility of actual function invocation for the signal system. This is the signature of va_list marshaller functions, an optional marshaller that can be used in some situations to avoid marshalling the signal argument into GValues. A numerical value which represents the unique identifier of a registered type. A convenience macro to ease adding private data to instances of a new type in the @_C_ section of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). For instance: |[<!-- language="C" --> typedef struct _MyObject MyObject; typedef struct _MyObjectClass MyObjectClass; typedef struct { gint foo; gint bar; } MyObjectPrivate; G_DEFINE_TYPE_WITH_CODE (MyObject, my_object, G_TYPE_OBJECT, G_ADD_PRIVATE (MyObject)) ]| Will add `MyObjectPrivate` as the private data to any instance of the `MyObject` type. `G_DEFINE_TYPE_*` macros will automatically create a private function based on the arguments to this macro, which can be used to safely retrieve the private data from an instance of the type; for instance: |[<!-- language="C" --> gint my_object_get_foo (MyObject *obj) { MyObjectPrivate *priv = my_object_get_instance_private (obj); g_return_val_if_fail (MY_IS_OBJECT (obj), 0); return priv->foo; } void my_object_set_bar (MyObject *obj, gint bar) { MyObjectPrivate *priv = my_object_get_instance_private (obj); g_return_if_fail (MY_IS_OBJECT (obj)); if (priv->bar != bar) priv->bar = bar; } ]| Since GLib 2.72, the returned `MyObjectPrivate` pointer is guaranteed to be aligned to at least the alignment of the largest basic GLib type (typically this is #guint64 or #gdouble). If you need larger alignment for an element in the struct, you should allocate it on the heap (aligned), or arrange for your `MyObjectPrivate` struct to be appropriately padded. Note that this macro can only be used together with the `G_DEFINE_TYPE_*` macros, since it depends on variable names from those macros. Also note that private structs added with these macros must have a struct name of the form `TypeNamePrivate`. It is safe to call the `_get_instance_private` function on %NULL or invalid objects since it's only adding an offset to the instance pointer. In that case the returned pointer must not be dereferenced. the name of the type in CamelCase A convenience macro to ease adding private data to instances of a new dynamic type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_ADD_PRIVATE() for details, it is similar but for static types. Note that this macro can only be used together with the G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable names from that macro. the name of the type in CamelCase A callback function used by the type system to finalize those portions of a derived types class structure that were setup from the corresponding GBaseInitFunc() function. Class finalization basically works the inverse way in which class initialization is performed. See GClassInitFunc() for a discussion of the class initialization process. The #GTypeClass structure to finalize A callback function used by the type system to do base initialization of the class structures of derived types. This function is called as part of the initialization process of all derived classes and should reallocate or reset all dynamic class members copied over from the parent class. For example, class members (such as strings) that are not sufficiently handled by a plain memory copy of the parent class into the derived class have to be altered. See GClassInitFunc() for a discussion of the class initialization process. The #GTypeClass structure to initialize `GObject` instance (or source) and another property on another `GObject` instance (or target). Whenever the source property changes, the same value is applied to the target property; for instance, the following binding: ```c g_object_bind_property (object1, "property-a", object2, "property-b", G_BINDING_DEFAULT); ``` will cause the property named "property-b" of @object2 to be updated every time [method@GObject.set] or the specific accessor changes the value of the property "property-a" of @object1. It is possible to create a bidirectional binding between two properties of two `GObject` instances, so that if either property changes, the other is updated as well, for instance: ```c g_object_bind_property (object1, "property-a", object2, "property-b", G_BINDING_BIDIRECTIONAL); ``` will keep the two properties in sync. It is also possible to set a custom transformation function (in both directions, in case of a bidirectional binding) to apply a custom transformation from the source value to the target value before applying it; for instance, the following binding: ```c g_object_bind_property_full (adjustment1, "value", adjustment2, "value", G_BINDING_BIDIRECTIONAL, celsius_to_fahrenheit, fahrenheit_to_celsius, NULL, NULL); ``` will keep the "value" property of the two adjustments in sync; the @celsius_to_fahrenheit function will be called whenever the "value" property of @adjustment1 changes and will transform the current value of the property before applying it to the "value" property of @adjustment2. Vice versa, the @fahrenheit_to_celsius function will be called whenever the "value" property of @adjustment2 changes, and will transform the current value of the property before applying it to the "value" property of @adjustment1. Note that #GBinding does not resolve cycles by itself; a cycle like ``` object1:propertyA -> object2:propertyB object2:propertyB -> object3:propertyC object3:propertyC -> object1:propertyA ``` might lead to an infinite loop. The loop, in this particular case, can be avoided if the objects emit the `GObject::notify` signal only if the value has effectively been changed. A binding is implemented using the `GObject::notify` signal, so it is susceptible to all the various ways of blocking a signal emission, like [func@GObject.signal_stop_emission] or [func@GObject.signal_handler_block]. A binding will be severed, and the resources it allocates freed, whenever either one of the `GObject` instances it refers to are finalized, or when the #GBinding instance loses its last reference. Bindings for languages with garbage collection can use [method@GObject.Binding.unbind] to explicitly release a binding between the source and target properties, instead of relying on the last reference on the binding, source, and target instances to drop. Retrieves the #GObject instance used as the source of the binding. A #GBinding can outlive the source #GObject as the binding does not hold a strong reference to the source. If the source is destroyed before the binding then this function will return %NULL. the source #GObject, or %NULL if the source does not exist any more. a #GBinding Retrieves the #GObject instance used as the target of the binding. A #GBinding can outlive the target #GObject as the binding does not hold a strong reference to the target. If the target is destroyed before the binding then this function will return %NULL. the target #GObject, or %NULL if the target does not exist any more. a #GBinding Retrieves the flags passed when constructing the #GBinding. the #GBindingFlags used by the #GBinding a #GBinding Retrieves the #GObject instance used as the source of the binding. A #GBinding can outlive the source #GObject as the binding does not hold a strong reference to the source. If the source is destroyed before the binding then this function will return %NULL. Use g_binding_dup_source() if the source or binding are used from different threads as otherwise the pointer returned from this function might become invalid if the source is finalized from another thread in the meantime. Use g_binding_dup_source() for a safer version of this function. the source #GObject, or %NULL if the source does not exist any more. a #GBinding Retrieves the name of the property of #GBinding:source used as the source of the binding. the name of the source property a #GBinding Retrieves the #GObject instance used as the target of the binding. A #GBinding can outlive the target #GObject as the binding does not hold a strong reference to the target. If the target is destroyed before the binding then this function will return %NULL. Use g_binding_dup_target() if the target or binding are used from different threads as otherwise the pointer returned from this function might become invalid if the target is finalized from another thread in the meantime. Use g_binding_dup_target() for a safer version of this function. the target #GObject, or %NULL if the target does not exist any more. a #GBinding Retrieves the name of the property of #GBinding:target used as the target of the binding. the name of the target property a #GBinding Explicitly releases the binding between the source and the target property expressed by @binding. This function will release the reference that is being held on the @binding instance if the binding is still bound; if you want to hold on to the #GBinding instance after calling g_binding_unbind(), you will need to hold a reference to it. Note however that this function does not take ownership of @binding, it only unrefs the reference that was initially created by g_object_bind_property() and is owned by the binding. a #GBinding Flags to be used to control the #GBinding The #GObject that should be used as the source of the binding The name of the property of #GBinding:source that should be used as the source of the binding. This should be in [canonical form][canonical-parameter-names] to get the best performance. The #GObject that should be used as the target of the binding The name of the property of #GBinding:target that should be used as the target of the binding. This should be in [canonical form][canonical-parameter-names] to get the best performance. Flags to be passed to g_object_bind_property() or g_object_bind_property_full(). This enumeration can be extended at later date. The default binding; if the source property changes, the target property is updated with its value. Bidirectional binding; if either the property of the source or the property of the target changes, the other is updated. Synchronize the values of the source and target properties when creating the binding; the direction of the synchronization is always from the source to the target. If the two properties being bound are booleans, setting one to %TRUE will result in the other being set to %FALSE and vice versa. This flag will only work for boolean properties, and cannot be used when passing custom transformation functions to g_object_bind_property_full(). `GBindingGroup` can be used to bind multiple properties from an object collectively. Use the various methods to bind properties from a single source object to multiple destination objects. Properties can be bound bidirectionally and are connected when the source object is set with [method@GObject.BindingGroup.set_source]. Creates a new #GBindingGroup. a new #GBindingGroup Creates a binding between @source_property on the source object and @target_property on @target. Whenever the @source_property is changed the @target_property is updated using the same value. The binding flag %G_BINDING_SYNC_CREATE is automatically specified. See g_object_bind_property() for more information. the #GBindingGroup the property on the source to bind the target #GObject the property on @target to bind the flags used to create the #GBinding Creates a binding between @source_property on the source object and @target_property on @target, allowing you to set the transformation functions to be used by the binding. The binding flag %G_BINDING_SYNC_CREATE is automatically specified. See g_object_bind_property_full() for more information. the #GBindingGroup the property on the source to bind the target #GObject the property on @target to bind the flags used to create the #GBinding the transformation function from the source object to the @target, or %NULL to use the default the transformation function from the @target to the source object, or %NULL to use the default custom data to be passed to the transformation functions, or %NULL function to be called when disposing the binding, to free the resources used by the transformation functions Creates a binding between @source_property on the source object and @target_property on @target, allowing you to set the transformation functions to be used by the binding. The binding flag %G_BINDING_SYNC_CREATE is automatically specified. This function is the language bindings friendly version of g_binding_group_bind_property_full(), using #GClosures instead of function pointers. See g_object_bind_property_with_closures() for more information. the #GBindingGroup the property on the source to bind the target #GObject the property on @target to bind the flags used to create the #GBinding a #GClosure wrapping the transformation function from the source object to the @target, or %NULL to use the default a #GClosure wrapping the transformation function from the @target to the source object, or %NULL to use the default Gets the source object used for binding properties. a #GObject or %NULL. the #GBindingGroup Sets @source as the source object used for creating property bindings. If there is already a source object all bindings from it will be removed. Note that all properties that have been bound must exist on @source. the #GBindingGroup the source #GObject, or %NULL to clear it The source object used for binding properties. A function to be called to transform @from_value to @to_value. If this is the @transform_to function of a binding, then @from_value is the @source_property on the @source object, and @to_value is the @target_property on the @target object. If this is the @transform_from function of a %G_BINDING_BIDIRECTIONAL binding, then those roles are reversed. %TRUE if the transformation was successful, and %FALSE otherwise a #GBinding the #GValue containing the value to transform the #GValue in which to store the transformed value data passed to the transform function This function is provided by the user and should produce a copy of the passed in boxed structure. The newly created copy of the boxed structure. The boxed structure to be copied. This function is provided by the user and should free the boxed structure passed. The boxed structure to be freed. Cast a function pointer to a #GCallback. a function pointer. Checks whether the user data of the #GCClosure should be passed as the first parameter to the callback. See g_cclosure_new_swap(). a #GCClosure A #GCClosure is a specialization of #GClosure for C function callbacks. the #GClosure the callback function A #GClosureMarshal function for use with signals with handlers that take two boxed pointers as arguments and return a boolean. If you have such a signal, you will probably also need to use an accumulator, such as g_signal_accumulator_true_handled(). A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__BOXED_BOXED(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with handlers that take a flags type as an argument and return a boolean. If you have such a signal, you will probably also need to use an accumulator, such as g_signal_accumulator_true_handled(). A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__FLAGS(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with handlers that take a #GObject and a pointer and produce a string. It is highly unlikely that your signal handler fits this description. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_STRING__OBJECT_POINTER(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with a single boolean argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOOLEAN(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with a single argument which is any boxed pointer type. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOXED(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with a single character argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__CHAR(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with one double-precision floating point argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__DOUBLE(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with a single argument with an enumerated type. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ENUM(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with a single argument with a flags types. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLAGS(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with one single-precision floating point argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLOAT(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with a single integer argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__INT(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with with a single long integer argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__LONG(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with a single #GObject argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__OBJECT(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with a single argument of type #GParamSpec. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__PARAM(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with a single raw pointer argument type. If it is possible, it is better to use one of the more specific functions such as g_cclosure_marshal_VOID__OBJECT() or g_cclosure_marshal_VOID__OBJECT(). A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__POINTER(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with a single string argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__STRING(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with a single unsigned character argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UCHAR(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with with a single unsigned integer argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with an unsigned int and a pointer as arguments. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT_POINTER(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with a single unsigned long integer argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ULONG(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with a single #GVariant argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VARIANT(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A #GClosureMarshal function for use with signals with no arguments. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VOID(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A generic marshaller function implemented via [libffi](http://sourceware.org/libffi/). Normally this function is not passed explicitly to g_signal_new(), but used automatically by GLib when specifying a %NULL marshaller. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A generic #GVaClosureMarshal function implemented via [libffi](http://sourceware.org/libffi/). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args_list. Creates a new closure which invokes @callback_func with @user_data as the last parameter. @destroy_data will be called as a finalize notifier on the #GClosure. a floating reference to a new #GCClosure the function to invoke user data to pass to @callback_func destroy notify to be called when @user_data is no longer used A variant of g_cclosure_new() which uses @object as @user_data and calls g_object_watch_closure() on @object and the created closure. This function is useful when you have a callback closely associated with a #GObject, and want the callback to no longer run after the object is is freed. a new #GCClosure the function to invoke a #GObject pointer to pass to @callback_func A variant of g_cclosure_new_swap() which uses @object as @user_data and calls g_object_watch_closure() on @object and the created closure. This function is useful when you have a callback closely associated with a #GObject, and want the callback to no longer run after the object is is freed. a new #GCClosure the function to invoke a #GObject pointer to pass to @callback_func Creates a new closure which invokes @callback_func with @user_data as the first parameter. @destroy_data will be called as a finalize notifier on the #GClosure. a floating reference to a new #GCClosure the function to invoke user data to pass to @callback_func destroy notify to be called when @user_data is no longer used Check if the closure still needs a marshaller. See g_closure_set_marshal(). a #GClosure Get the total number of notifiers connected with the closure @cl. The count includes the meta marshaller, the finalize and invalidate notifiers and the marshal guards. Note that each guard counts as two notifiers. See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(), g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards(). a #GClosure The type used for callback functions in structure definitions and function signatures. This doesn't mean that all callback functions must take no parameters and return void. The required signature of a callback function is determined by the context in which is used (e.g. the signal to which it is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. A callback function used by the type system to finalize a class. This function is rarely needed, as dynamically allocated class resources should be handled by GBaseInitFunc() and GBaseFinalizeFunc(). Also, specification of a GClassFinalizeFunc() in the #GTypeInfo structure of a static type is invalid, because classes of static types will never be finalized (they are artificially kept alive when their reference count drops to zero). The #GTypeClass structure to finalize The @class_data member supplied via the #GTypeInfo structure A callback function used by the type system to initialize the class of a specific type. This function should initialize all static class members. The initialization process of a class involves: - Copying common members from the parent class over to the derived class structure. - Zero initialization of the remaining members not copied over from the parent class. - Invocation of the GBaseInitFunc() initializers of all parent types and the class' type. - Invocation of the class' GClassInitFunc() initializer. Since derived classes are partially initialized through a memory copy of the parent class, the general rule is that GBaseInitFunc() and GBaseFinalizeFunc() should take care of necessary reinitialization and release of those class members that were introduced by the type that specified these GBaseInitFunc()/GBaseFinalizeFunc(). GClassInitFunc() should only care about initializing static class members, while dynamic class members (such as allocated strings or reference counted resources) are better handled by a GBaseInitFunc() for this type, so proper initialization of the dynamic class members is performed for class initialization of derived types as well. An example may help to correspond the intend of the different class initializers: |[<!-- language="C" --> typedef struct { GObjectClass parent_class; gint static_integer; gchar *dynamic_string; } TypeAClass; static void type_a_base_class_init (TypeAClass *class) { class->dynamic_string = g_strdup ("some string"); } static void type_a_base_class_finalize (TypeAClass *class) { g_free (class->dynamic_string); } static void type_a_class_init (TypeAClass *class) { class->static_integer = 42; } typedef struct { TypeAClass parent_class; gfloat static_float; GString *dynamic_gstring; } TypeBClass; static void type_b_base_class_init (TypeBClass *class) { class->dynamic_gstring = g_string_new ("some other string"); } static void type_b_base_class_finalize (TypeBClass *class) { g_string_free (class->dynamic_gstring); } static void type_b_class_init (TypeBClass *class) { class->static_float = 3.14159265358979323846; } ]| Initialization of TypeBClass will first cause initialization of TypeAClass (derived classes reference their parent classes, see g_type_class_ref() on this). Initialization of TypeAClass roughly involves zero-initializing its fields, then calling its GBaseInitFunc() type_a_base_class_init() to allocate its dynamic members (dynamic_string), and finally calling its GClassInitFunc() type_a_class_init() to initialize its static members (static_integer). The first step in the initialization process of TypeBClass is then a plain memory copy of the contents of TypeAClass into TypeBClass and zero-initialization of the remaining fields in TypeBClass. The dynamic members of TypeAClass within TypeBClass now need reinitialization which is performed by calling type_a_base_class_init() with an argument of TypeBClass. After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init() is called to allocate the dynamic members of TypeBClass (dynamic_gstring), and finally the GClassInitFunc() of TypeBClass, type_b_class_init(), is called to complete the initialization process with the static members (static_float). Corresponding finalization counter parts to the GBaseInitFunc() functions have to be provided to release allocated resources at class finalization time. The #GTypeClass structure to initialize. The @class_data member supplied via the #GTypeInfo structure. A `GClosure` represents a callback supplied by the programmer. It will generally comprise a function of some kind and a marshaller used to call it. It is the responsibility of the marshaller to convert the arguments for the invocation from #GValues into a suitable form, perform the callback on the converted arguments, and transform the return value back into a #GValue. In the case of C programs, a closure usually just holds a pointer to a function and maybe a data argument, and the marshaller converts between #GValue and native C types. The GObject library provides the #GCClosure type for this purpose. Bindings for other languages need marshallers which convert between #GValues and suitable representations in the runtime of the language in order to use functions written in that language as callbacks. Use g_closure_set_marshal() to set the marshaller on such a custom closure implementation. Within GObject, closures play an important role in the implementation of signals. When a signal is registered, the @c_marshaller argument to g_signal_new() specifies the default C marshaller for any closure which is connected to this signal. GObject provides a number of C marshallers for this purpose, see the g_cclosure_marshal_*() functions. Additional C marshallers can be generated with the [glib-genmarshal][glib-genmarshal] utility. Closures can be explicitly connected to signals with g_signal_connect_closure(), but it usually more convenient to let GObject create a closure automatically by using one of the g_signal_connect_*() functions which take a callback function/user data pair. Using closures has a number of important advantages over a simple callback function/data pointer combination: - Closures allow the callee to get the types of the callback parameters, which means that language bindings don't have to write individual glue for each callback type. - The reference counting of #GClosure makes it easy to handle reentrancy right; if a callback is removed while it is being invoked, the closure and its parameters won't be freed until the invocation finishes. - g_closure_invalidate() and invalidation notifiers allow callbacks to be automatically removed when the objects they point to go away. Indicates whether the closure is currently being invoked with g_closure_invoke() Indicates whether the closure has been invalidated by g_closure_invalidate() A variant of g_closure_new_simple() which stores @object in the @data field of the closure and calls g_object_watch_closure() on @object and the created closure. This function is mainly useful when implementing new types of closures. a newly allocated #GClosure the size of the structure to allocate, must be at least `sizeof (GClosure)` a #GObject pointer to store in the @data field of the newly allocated #GClosure Allocates a struct of the given size and initializes the initial part as a #GClosure. This function is mainly useful when implementing new types of closures: |[<!-- language="C" --> typedef struct _MyClosure MyClosure; struct _MyClosure { GClosure closure; // extra data goes here }; static void my_closure_finalize (gpointer notify_data, GClosure *closure) { MyClosure *my_closure = (MyClosure *)closure; // free extra data here } MyClosure *my_closure_new (gpointer data) { GClosure *closure; MyClosure *my_closure; closure = g_closure_new_simple (sizeof (MyClosure), data); my_closure = (MyClosure *) closure; // initialize extra data here g_closure_add_finalize_notifier (closure, notify_data, my_closure_finalize); return my_closure; } ]| a floating reference to a new #GClosure the size of the structure to allocate, must be at least `sizeof (GClosure)` data to store in the @data field of the newly allocated #GClosure Registers a finalization notifier which will be called when the reference count of @closure goes down to 0. Multiple finalization notifiers on a single closure are invoked in unspecified order. If a single call to g_closure_unref() results in the closure being both invalidated and finalized, then the invalidate notifiers will be run before the finalize notifiers. a #GClosure data to pass to @notify_func the callback function to register Registers an invalidation notifier which will be called when the @closure is invalidated with g_closure_invalidate(). Invalidation notifiers are invoked before finalization notifiers, in an unspecified order. a #GClosure data to pass to @notify_func the callback function to register Adds a pair of notifiers which get invoked before and after the closure callback, respectively. This is typically used to protect the extra arguments for the duration of the callback. See g_object_watch_closure() for an example of marshal guards. a #GClosure data to pass to @pre_marshal_notify a function to call before the closure callback data to pass to @post_marshal_notify a function to call after the closure callback Sets a flag on the closure to indicate that its calling environment has become invalid, and thus causes any future invocations of g_closure_invoke() on this @closure to be ignored. Also, invalidation notifiers installed on the closure will be called at this point. Note that unless you are holding a reference to the closure yourself, the invalidation notifiers may unref the closure and cause it to be destroyed, so if you need to access the closure after calling g_closure_invalidate(), make sure that you've previously called g_closure_ref(). Note that g_closure_invalidate() will also be called when the reference count of a closure drops to zero (unless it has already been invalidated before). #GClosure to invalidate Invokes the closure, i.e. executes the callback represented by the @closure. a #GClosure a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the length of the @param_values array an array of #GValues holding the arguments on which to invoke the callback of @closure a context-dependent invocation hint Increments the reference count on a closure to force it staying alive while the caller holds a pointer to it. The @closure passed in, for convenience #GClosure to increment the reference count on Removes a finalization notifier. Notice that notifiers are automatically removed after they are run. a #GClosure data which was passed to g_closure_add_finalize_notifier() when registering @notify_func the callback function to remove Removes an invalidation notifier. Notice that notifiers are automatically removed after they are run. a #GClosure data which was passed to g_closure_add_invalidate_notifier() when registering @notify_func the callback function to remove Sets the marshaller of @closure. The `marshal_data` of @marshal provides a way for a meta marshaller to provide additional information to the marshaller. For GObject's C predefined marshallers (the `g_cclosure_marshal_*()` functions), what it provides is a callback function to use instead of @closure->callback. See also: g_closure_set_meta_marshal() a #GClosure a #GClosureMarshal function Sets the meta marshaller of @closure. A meta marshaller wraps the @closure's marshal and modifies the way it is called in some fashion. The most common use of this facility is for C callbacks. The same marshallers (generated by [glib-genmarshal][glib-genmarshal]), are used everywhere, but the way that we get the callback function differs. In most cases we want to use the @closure's callback, but in other cases we want to use some different technique to retrieve the callback function. For example, class closures for signals (see g_signal_type_cclosure_new()) retrieve the callback function from a fixed offset in the class structure. The meta marshaller retrieves the right callback and passes it to the marshaller as the @marshal_data argument. a #GClosure context-dependent data to pass to @meta_marshal a #GClosureMarshal function Takes over the initial ownership of a closure. Each closure is initially created in a "floating" state, which means that the initial reference count is not owned by any caller. This function checks to see if the object is still floating, and if so, unsets the floating state and decreases the reference count. If the closure is not floating, g_closure_sink() does nothing. The reason for the existence of the floating state is to prevent cumbersome code sequences like: |[<!-- language="C" --> closure = g_cclosure_new (cb_func, cb_data); g_source_set_closure (source, closure); g_closure_unref (closure); // GObject doesn't really need this ]| Because g_source_set_closure() (and similar functions) take ownership of the initial reference count, if it is unowned, we instead can write: |[<!-- language="C" --> g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); ]| Generally, this function is used together with g_closure_ref(). An example of storing a closure for later notification looks like: |[<!-- language="C" --> static GClosure *notify_closure = NULL; void foo_notify_set_closure (GClosure *closure) { if (notify_closure) g_closure_unref (notify_closure); notify_closure = closure; if (notify_closure) { g_closure_ref (notify_closure); g_closure_sink (notify_closure); } } ]| Because g_closure_sink() may decrement the reference count of a closure (if it hasn't been called on @closure yet) just like g_closure_unref(), g_closure_ref() should be called prior to this function. #GClosure to decrement the initial reference count on, if it's still being held Decrements the reference count of a closure after it was previously incremented by the same caller. If no other callers are using the closure, then the closure will be destroyed and freed. #GClosure to decrement the reference count on The type used for marshaller functions. the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the length of the @param_values array an array of #GValues holding the arguments on which to invoke the callback of @closure the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The type used for the various notification callbacks which can be registered on closures. data specified when registering the notification callback the #GClosure on which the notification is emitted The connection flags are used to specify the behaviour of a signal's connection. Default behaviour (no special flags). Since: 2.74 If set, the handler should be called after the default handler of the signal. Normally, the handler is called before the default handler. If set, the instance and data should be swapped when calling the handler; see g_signal_connect_swapped() for an example. A convenience macro for emitting the usual declarations in the header file for a type which is intended to be subclassed. You might use it in a header as follows: |[<!-- language="C" --> #ifndef _gtk_frobber_h_ #define _gtk_frobber_h_ #define GTK_TYPE_FROBBER gtk_frobber_get_type () GDK_AVAILABLE_IN_3_12 G_DECLARE_DERIVABLE_TYPE (GtkFrobber, gtk_frobber, GTK, FROBBER, GtkWidget) struct _GtkFrobberClass { GtkWidgetClass parent_class; void (* handle_frob) (GtkFrobber *frobber, guint n_frobs); gpointer padding[12]; }; GtkWidget * gtk_frobber_new (void); ... #endif ]| Since the instance structure is public it is often needed to declare a private struct as follow in your C file: |[<!-- language="C" --> typedef struct _GtkFrobberPrivate GtkFrobberPrivate; struct _GtkFrobberPrivate { ... }; G_DEFINE_TYPE_WITH_PRIVATE (GtkFrobber, gtk_frobber, GTK_TYPE_WIDGET) ]| This results in the following things happening: - the usual `gtk_frobber_get_type()` function is declared with a return type of #GType - the `GtkFrobber` struct is created with `GtkWidget` as the first and only item. You are expected to use a private structure from your .c file to store your instance variables. - the `GtkFrobberClass` type is defined as a typedef to `struct _GtkFrobberClass`, which is left undefined. You should do this from the header file directly after you use the macro. - the `GTK_FROBBER()` and `GTK_FROBBER_CLASS()` casts are emitted as `static inline` functions along with the `GTK_IS_FROBBER()` and `GTK_IS_FROBBER_CLASS()` type checking functions and `GTK_FROBBER_GET_CLASS()` function. - g_autoptr() support being added for your type, based on the type of your parent class You can only use this function if your parent type also supports g_autoptr(). Because the type macro (`GTK_TYPE_FROBBER` in the above example) is not a callable, you must continue to manually define this as a macro for yourself. The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro to be used in the usual way with export control and API versioning macros. If you are writing a library, it is important to note that it is possible to convert a type from using G_DECLARE_FINAL_TYPE() to G_DECLARE_DERIVABLE_TYPE() without breaking API or ABI. As a precaution, you should therefore use G_DECLARE_FINAL_TYPE() until you are sure that it makes sense for your class to be subclassed. Once a class structure has been exposed it is not possible to change its size or remove or reorder items without breaking the API and/or ABI. If you want to declare your own class structure, use G_DECLARE_DERIVABLE_TYPE(). If you want to declare a class without exposing the class or instance structures, use G_DECLARE_FINAL_TYPE(). If you must use G_DECLARE_DERIVABLE_TYPE() you should be sure to include some padding at the bottom of your class structure to leave space for the addition of future virtual functions. The name of the new type, in camel case (like `GtkWidget`) The name of the new type in lowercase, with words separated by `_` (like `gtk_widget`) The name of the module, in all caps (like `GTK`) The bare name of the type, in all caps (like `WIDGET`) the name of the parent type, in camel case (like `GtkWidget`) A convenience macro for emitting the usual declarations in the header file for a type which is not (at the present time) intended to be subclassed. You might use it in a header as follows: |[<!-- language="C" --> #ifndef _myapp_window_h_ #define _myapp_window_h_ #include <gtk/gtk.h> #define MY_APP_TYPE_WINDOW my_app_window_get_type () G_DECLARE_FINAL_TYPE (MyAppWindow, my_app_window, MY_APP, WINDOW, GtkWindow) MyAppWindow * my_app_window_new (void); ... #endif ]| And use it as follow in your C file: |[<!-- language="C" --> struct _MyAppWindow { GtkWindow parent; ... }; G_DEFINE_TYPE (MyAppWindow, my_app_window, GTK_TYPE_WINDOW) ]| This results in the following things happening: - the usual `my_app_window_get_type()` function is declared with a return type of #GType - the `MyAppWindow` type is defined as a `typedef` of `struct _MyAppWindow`. The struct itself is not defined and should be defined from the .c file before G_DEFINE_TYPE() is used. - the `MY_APP_WINDOW()` cast is emitted as `static inline` function along with the `MY_APP_IS_WINDOW()` type checking function - the `MyAppWindowClass` type is defined as a struct containing `GtkWindowClass`. This is done for the convenience of the person defining the type and should not be considered to be part of the ABI. In particular, without a firm declaration of the instance structure, it is not possible to subclass the type and therefore the fact that the size of the class structure is exposed is not a concern and it can be freely changed at any point in the future. - g_autoptr() support being added for your type, based on the type of your parent class You can only use this function if your parent type also supports g_autoptr(). Because the type macro (`MY_APP_TYPE_WINDOW` in the above example) is not a callable, you must continue to manually define this as a macro for yourself. The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro to be used in the usual way with export control and API versioning macros. If you want to declare your own class structure, use G_DECLARE_DERIVABLE_TYPE(). If you are writing a library, it is important to note that it is possible to convert a type from using G_DECLARE_FINAL_TYPE() to G_DECLARE_DERIVABLE_TYPE() without breaking API or ABI. As a precaution, you should therefore use G_DECLARE_FINAL_TYPE() until you are sure that it makes sense for your class to be subclassed. Once a class structure has been exposed it is not possible to change its size or remove or reorder items without breaking the API and/or ABI. The name of the new type, in camel case (like `GtkWidget`) The name of the new type in lowercase, with words separated by `_` (like `gtk_widget`) The name of the module, in all caps (like `GTK`) The bare name of the type, in all caps (like `WIDGET`) the name of the parent type, in camel case (like `GtkWidget`) A convenience macro for emitting the usual declarations in the header file for a #GInterface type. You might use it in a header as follows: |[<!-- language="C" --> #ifndef _my_model_h_ #define _my_model_h_ #define MY_TYPE_MODEL my_model_get_type () GDK_AVAILABLE_IN_3_12 G_DECLARE_INTERFACE (MyModel, my_model, MY, MODEL, GObject) struct _MyModelInterface { GTypeInterface g_iface; gpointer (* get_item) (MyModel *model); }; gpointer my_model_get_item (MyModel *model); ... #endif ]| And use it as follow in your C file: |[<!-- language="C" --> G_DEFINE_INTERFACE (MyModel, my_model, G_TYPE_OBJECT); static void my_model_default_init (MyModelInterface *iface) { ... } ]| This results in the following things happening: - the usual `my_model_get_type()` function is declared with a return type of #GType - the `MyModelInterface` type is defined as a typedef to `struct _MyModelInterface`, which is left undefined. You should do this from the header file directly after you use the macro. - the `MY_MODEL()` cast is emitted as `static inline` functions along with the `MY_IS_MODEL()` type checking function and `MY_MODEL_GET_IFACE()` function. - g_autoptr() support being added for your type, based on your prerequisite type. You can only use this function if your prerequisite type also supports g_autoptr(). Because the type macro (`MY_TYPE_MODEL` in the above example) is not a callable, you must continue to manually define this as a macro for yourself. The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro to be used in the usual way with export control and API versioning macros. The name of the new type, in camel case (like `GtkWidget`) The name of the new type in lowercase, with words separated by `_` (like `gtk_widget`) The name of the module, in all caps (like `GTK`) The bare name of the type, in all caps (like `WIDGET`) the name of the prerequisite type, in camel case (like `GtkWidget`) A convenience macro for type implementations. Similar to G_DEFINE_TYPE(), but defines an abstract type. See G_DEFINE_TYPE_EXTENDED() for an example. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by `_`. The #GType of the parent type. A convenience macro for type implementations. Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows you to insert custom code into the `*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by `_`. The #GType of the parent type. Custom code that gets inserted in the `type_name_get_type()` function. Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type. See G_DEFINE_TYPE_EXTENDED() for an example. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by `_`. The #GType of the parent type. A convenience macro for defining a new custom boxed type. Using this macro is the recommended way of defining new custom boxed types, over calling g_boxed_type_register_static() directly. It defines a `type_name_get_type()` function which will return the newly defined #GType, enabling lazy instantiation. You might start by putting declarations in a header as follows: |[<!-- language="C" --> #define MY_TYPE_STRUCT my_struct_get_type () GType my_struct_get_type (void) G_GNUC_CONST; MyStruct * my_struct_new (void); void my_struct_free (MyStruct *self); MyStruct * my_struct_copy (MyStruct *self); ]| And then use this macro and define your implementation in the source file as follows: |[<!-- language="C" --> MyStruct * my_struct_new (void) { // ... your code to allocate a new MyStruct ... } void my_struct_free (MyStruct *self) { // ... your code to free a MyStruct ... } MyStruct * my_struct_copy (MyStruct *self) { // ... your code return a newly allocated copy of a MyStruct ... } G_DEFINE_BOXED_TYPE (MyStruct, my_struct, my_struct_copy, my_struct_free) void foo () { MyStruct *ms; ms = my_struct_new (); // ... your code ... my_struct_free (ms); } ]| The name of the new type, in Camel case The name of the new type, in lowercase, with words separated by `_` the #GBoxedCopyFunc for the new type the #GBoxedFreeFunc for the new type A convenience macro for boxed type implementations. Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the `type_name_get_type()` function, e.g. to register value transformations with g_value_register_transform_func(), for instance: |[<!-- language="C" --> G_DEFINE_BOXED_TYPE_WITH_CODE (GdkRectangle, gdk_rectangle, gdk_rectangle_copy, gdk_rectangle_free, register_rectangle_transform_funcs (g_define_type_id)) ]| Similarly to the `G_DEFINE_TYPE_*` family of macros, the #GType of the newly defined boxed type is exposed in the `g_define_type_id` variable. The name of the new type, in Camel case The name of the new type, in lowercase, with words separated by `_` the #GBoxedCopyFunc for the new type the #GBoxedFreeFunc for the new type Custom code that gets inserted in the `*_get_type()` function A convenience macro for dynamic type implementations, which declares a class initialization function, an instance initialization function (see #GTypeInfo for information about these) and a static variable named `t_n`_parent_class pointing to the parent class. Furthermore, it defines a `*_get_type()` and a static `*_register_type()` functions for use in your `module_init()`. See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. A more general version of G_DEFINE_DYNAMIC_TYPE() which allows to specify #GTypeFlags and custom code. |[<!-- language="C" --> G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, gtk_gadget, GTK_TYPE_THING, 0, G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO, gtk_gadget_gizmo_init)); ]| expands to |[<!-- language="C" --> static void gtk_gadget_init (GtkGadget *self); static void gtk_gadget_class_init (GtkGadgetClass *klass); static void gtk_gadget_class_finalize (GtkGadgetClass *klass); static gpointer gtk_gadget_parent_class = NULL; static GType gtk_gadget_type_id = 0; static void gtk_gadget_class_intern_init (gpointer klass) { gtk_gadget_parent_class = g_type_class_peek_parent (klass); gtk_gadget_class_init ((GtkGadgetClass*) klass); } GType gtk_gadget_get_type (void) { return gtk_gadget_type_id; } static void gtk_gadget_register_type (GTypeModule *type_module) { const GTypeInfo g_define_type_info = { sizeof (GtkGadgetClass), (GBaseInitFunc) NULL, (GBaseFinalizeFunc) NULL, (GClassInitFunc) gtk_gadget_class_intern_init, (GClassFinalizeFunc) gtk_gadget_class_finalize, NULL, // class_data sizeof (GtkGadget), 0, // n_preallocs (GInstanceInitFunc) gtk_gadget_init, NULL // value_table }; gtk_gadget_type_id = g_type_module_register_type (type_module, GTK_TYPE_THING, "GtkGadget", &g_define_type_info, (GTypeFlags) flags); { const GInterfaceInfo g_implement_interface_info = { (GInterfaceInitFunc) gtk_gadget_gizmo_init }; g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); } } ]| The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. #GTypeFlags to pass to g_type_module_register_type() Custom code that gets inserted in the *_get_type() function. A convenience macro for defining enumeration types. This macro will generate a `*_get_type()` function for the given @TypeName, using @type_name as the function prefix. |[<!-- language="C" --> G_DEFINE_ENUM_TYPE (GtkOrientation, gtk_orientation, G_DEFINE_ENUM_VALUE (GTK_ORIENTATION_HORIZONTAL, "horizontal"), G_DEFINE_ENUM_VALUE (GTK_ORIENTATION_VERTICAL, "vertical")) ]| For projects that have multiple enumeration types, or enumeration types with many values, you should consider using glib-mkenums to generate the type function. the enumeration type, in `CamelCase` the enumeration type prefixed, in `snake_case` a list of enumeration values, defined using G_DEFINE_ENUM_VALUE() Defines an enumeration value, and maps it to a "nickname". This macro can only be used with G_DEFINE_ENUM_TYPE() and G_DEFINE_FLAGS_TYPE(). an enumeration value a short string representing the enumeration value A convenience macro for type implementations. Similar to G_DEFINE_TYPE(), but defines a final type. See G_DEFINE_TYPE_EXTENDED() for an example. the name of the new type, in Camel case the name of the new type, in lower case, with words separated by `_` (snake case) the #GType of the parent type A convenience macro for type implementations. Similar to G_DEFINE_TYPE_WITH_CODE(), but defines a final type and allows you to insert custom code into the `*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example. the name of the new type, in Camel case the name of the new type, in lower case, with words separated by `_` (snake case) the #GType of the parent type Custom code that gets inserted in the `type_name_get_type()` function. A convenience macro for type implementations. Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines a final type. See G_DEFINE_TYPE_EXTENDED() for an example. the name of the new type, in Camel case the name of the new type, in lower case, with words separated by `_` (snake case) the #GType of the parent type A convenience macro for defining flag types. This macro will generate a `*_get_type()` function for the given @TypeName, using @type_name as the function prefix. |[<!-- language="C" --> G_DEFINE_FLAGS_TYPE (GSettingsBindFlags, g_settings_bind_flags, G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_DEFAULT, "default"), G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_GET, "get"), G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_SET, "set"), G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_NO_SENSITIVITY, "no-sensitivity"), G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_GET_NO_CHANGES, "get-no-changes"), G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_INVERT_BOOLEAN, "invert-boolean")) ]| For projects that have multiple enumeration types, or enumeration types with many values, you should consider using glib-mkenums to generate the type function. the enumeration type, in `CamelCase` the enumeration type prefixed, in `snake_case` a list of enumeration values, defined using G_DEFINE_ENUM_VALUE() A convenience macro for #GTypeInterface definitions, which declares a default vtable initialization function and defines a `*_get_type()` function. The macro expects the interface initialization function to have the name `t_n ## _default_init`, and the interface structure to have the name `TN ## Interface`. The initialization function has signature `static void t_n ## _default_init (TypeName##Interface *klass);`, rather than the full #GInterfaceInitFunc signature, for brevity and convenience. If you need to use an initialization function with an `iface_data` argument, you must write the #GTypeInterface definitions manually. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by `_`. The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID for no prerequisite type. A convenience macro for #GTypeInterface definitions. Similar to G_DEFINE_INTERFACE(), but allows you to insert custom code into the `*_get_type()` function, e.g. additional interface implementations via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See G_DEFINE_TYPE_EXTENDED() for a similar example using G_DEFINE_TYPE_WITH_CODE(). The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by `_`. The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID for no prerequisite type. Custom code that gets inserted in the `*_get_type()` function. A convenience macro for pointer type implementations, which defines a `type_name_get_type()` function registering the pointer type. The name of the new type, in Camel case The name of the new type, in lowercase, with words separated by `_` A convenience macro for pointer type implementations. Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the `type_name_get_type()` function. The name of the new type, in Camel case The name of the new type, in lowercase, with words separated by `_` Custom code that gets inserted in the `*_get_type()` function A convenience macro for type implementations, which declares a class initialization function, an instance initialization function (see #GTypeInfo for information about these) and a static variable named `t_n_parent_class` pointing to the parent class. Furthermore, it defines a `*_get_type()` function. See G_DEFINE_TYPE_EXTENDED() for an example. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by `_`. The #GType of the parent type. The most general convenience macro for type implementations, on which G_DEFINE_TYPE(), etc are based. |[<!-- language="C" --> G_DEFINE_TYPE_EXTENDED (GtkGadget, gtk_gadget, GTK_TYPE_WIDGET, 0, G_ADD_PRIVATE (GtkGadget) G_IMPLEMENT_INTERFACE (TYPE_GIZMO, gtk_gadget_gizmo_init)); ]| expands to |[<!-- language="C" --> static void gtk_gadget_init (GtkGadget *self); static void gtk_gadget_class_init (GtkGadgetClass *klass); static gpointer gtk_gadget_parent_class = NULL; static gint GtkGadget_private_offset; static void gtk_gadget_class_intern_init (gpointer klass) { gtk_gadget_parent_class = g_type_class_peek_parent (klass); if (GtkGadget_private_offset != 0) g_type_class_adjust_private_offset (klass, &GtkGadget_private_offset); gtk_gadget_class_init ((GtkGadgetClass*) klass); } static inline gpointer gtk_gadget_get_instance_private (GtkGadget *self) { return (G_STRUCT_MEMBER_P (self, GtkGadget_private_offset)); } GType gtk_gadget_get_type (void) { static GType static_g_define_type_id = 0; if (g_once_init_enter_pointer (&static_g_define_type_id)) { GType g_define_type_id = g_type_register_static_simple (GTK_TYPE_WIDGET, g_intern_static_string ("GtkGadget"), sizeof (GtkGadgetClass), (GClassInitFunc) gtk_gadget_class_intern_init, sizeof (GtkGadget), (GInstanceInitFunc) gtk_gadget_init, 0); { GtkGadget_private_offset = g_type_add_instance_private (g_define_type_id, sizeof (GtkGadgetPrivate)); } { const GInterfaceInfo g_implement_interface_info = { (GInterfaceInitFunc) gtk_gadget_gizmo_init }; g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); } g_once_init_leave_pointer (&static_g_define_type_id, g_define_type_id); } return static_g_define_type_id; } ]| The only pieces which have to be manually provided are the definitions of the instance and class structure and the definitions of the instance and class init functions. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by `_`. The #GType of the parent type. #GTypeFlags to pass to g_type_register_static() Custom code that gets inserted in the `*_get_type()` function. A convenience macro for type implementations. Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the `*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example. The name of the new type, in Camel case. The name of the new type in lowercase, with words separated by `_`. The #GType of the parent type. Custom code that gets inserted in the `*_get_type()` function. A convenience macro for type implementations, which declares a class initialization function, an instance initialization function (see #GTypeInfo for information about these), a static variable named `t_n_parent_class` pointing to the parent class, and adds private instance data to the type. Furthermore, it defines a `*_get_type()` function. See G_DEFINE_TYPE_EXTENDED() for an example. Note that private structs added with this macros must have a struct name of the form `TN ## Private`. The private instance data can be retrieved using the automatically generated getter function `t_n_get_instance_private()`. See also: G_ADD_PRIVATE() The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by `_`. The #GType of the parent type. Casts a derived #GEnumClass structure into a #GEnumClass structure. a valid #GEnumClass Get the type identifier from a given #GEnumClass structure. a #GEnumClass Get the static type name from a given #GEnumClass structure. a #GEnumClass The class of an enumeration type holds information about its possible values. the parent class the smallest possible value. the largest possible value. the number of possible values. an array of #GEnumValue structs describing the individual values. A structure which contains a single enum value, its name, and its nickname. the enum value the name of the value the nickname of the value Casts a derived #GFlagsClass structure into a #GFlagsClass structure. a valid #GFlagsClass Get the type identifier from a given #GFlagsClass structure. a #GFlagsClass Get the static type name from a given #GFlagsClass structure. a #GFlagsClass The class of a flags type holds information about its possible values. the parent class a mask covering all possible values. the number of possible values. an array of #GFlagsValue structs describing the individual values. A structure which contains a single flags value, its name, and its nickname. the flags value the name of the value the nickname of the value A convenience macro to ease interface addition in the `_C_` section of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). See G_DEFINE_TYPE_EXTENDED() for an example. Note that this macro can only be used together with the `G_DEFINE_TYPE_*` macros, since it depends on variable names from those macros. The #GType of the interface to add The interface init function, of type #GInterfaceInitFunc A convenience macro to ease interface addition in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. Note that this macro can only be used together with the G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable names from that macro. The #GType of the interface to add The interface init function Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) pointer. Depending on the current debugging level, this function may invoke certain runtime checks to identify invalid casts. Object which is subject to casting. Casts a derived #GInitiallyUnownedClass structure into a #GInitiallyUnownedClass structure. a valid #GInitiallyUnownedClass Get the class structure associated to a #GInitiallyUnowned instance. a #GInitiallyUnowned instance. Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM or derived. a #GEnumClass Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS or derived. a #GFlagsClass Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED. Instance to check for being a %G_TYPE_INITIALLY_UNOWNED. Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type %G_TYPE_INITIALLY_UNOWNED or derived. a #GInitiallyUnownedClass Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. Instance to check for being a %G_TYPE_OBJECT. Checks whether @class "is a" valid #GObjectClass structure of type %G_TYPE_OBJECT or derived. a #GObjectClass Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM or derived. a #GParamSpec Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR. a valid #GParamSpec instance Checks whether @pclass "is a" valid #GParamSpecClass structure of type %G_TYPE_PARAM or derived. a #GParamSpecClass Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE. a #GParamSpec Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE. a #GParamSpec Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY. Use #GArray instead of #GValueArray a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT. a #GParamSpec Checks if @value is a valid and initialized [struct@GObject.Value] structure. a [struct@GObject.Value] structure A type for objects that have an initially floating reference. All the fields in the `GInitiallyUnowned` structure are private to the implementation and should never be accessed directly. The class structure for the GInitiallyUnowned type. the parent class the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the @constructor of the parent class. Overriding @constructor should be rarely needed, e.g. to handle construct properties, or to implement singletons. the generic setter for all properties of this type. Should be overridden for every type with properties. If implementations of @set_property don't emit property change notification explicitly, this will be done implicitly by the type system. However, if the notify signal is emitted explicitly, the type system will not emit it a second time. the generic getter for all properties of this type. Should be overridden for every type with properties. the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class. instance finalization function, should finish the finalization of the instance begun in @dispose and chain up to the @finalize method of the parent class. emits property change notification for a bunch of properties. Overriding @dispatch_properties_changed should be rarely needed. the class closure for the notify signal a #GObject the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation. A callback function used by the type system to initialize a new instance of a type. This function initializes all instance members and allocates any resources required by it. Initialization of a derived instance involves calling all its parent types instance initializers, so the class member of the instance is altered during its initialization to always point to the class that belongs to the type the current initializer was introduced for. The extended members of @instance are guaranteed to have been filled with zeros before this function is called. The instance to initialize The class of the type the instance is created for A callback function used by the type system to finalize an interface. This function should destroy any internal data and release any resources allocated by the corresponding GInterfaceInitFunc() function. The interface structure to finalize The @interface_data supplied via the #GInterfaceInfo structure A structure that provides information to the type system which is used specifically for managing interface types. location of the interface initialization function location of the interface finalization function user-supplied data passed to the interface init/finalize functions A callback function used by the type system to initialize a new interface. This function should initialize all internal data and* allocate any resources required by the interface. The members of @iface_data are guaranteed to have been filled with zeros before this function is called. The interface structure to initialize The @interface_data supplied via the #GInterfaceInfo structure Casts a #GObject or derived pointer into a (GObject*) pointer. Depending on the current debugging level, this function may invoke certain runtime checks to identify invalid casts. Object which is subject to casting. Casts a derived #GObjectClass structure into a #GObjectClass structure. a valid #GObjectClass Return the name of a class structure's type. a valid #GObjectClass Get the type id of a class structure. a valid #GObjectClass Get the class structure associated to a #GObject instance. a #GObject instance. Get the type id of an object. Object to return the type id for. Get the name of an object's type. Object to return the type name for. This macro should be used to emit a standard warning about unexpected properties in set_property() and get_property() implementations. the #GObject on which set_property() or get_property() was called the numeric id of the property the #GParamSpec of the property The base object type. `GObject` is the fundamental type providing the common attributes and methods for all object types in GTK, Pango and other libraries based on GObject. The `GObject` class provides methods for object construction and destruction, property access methods, and signal support. Signals are described in detail [here][gobject-Signals]. For a tutorial on implementing a new `GObject` class, see [How to define and implement a new GObject](tutorial.html#how-to-define-and-implement-a-new-gobject). For a list of naming conventions for GObjects and their methods, see the [GType conventions](concepts.html#conventions). For the high-level concepts behind GObject, read [Instantiatable classed types: Objects](concepts.html#instantiatable-classed-types-objects). Since GLib 2.72, all `GObject`s are guaranteed to be aligned to at least the alignment of the largest basic GLib type (typically this is `guint64` or `gdouble`). If you need larger alignment for an element in a `GObject`, you should allocate it on the heap (aligned), or arrange for your `GObject` to be appropriately padded. This guarantee applies to the `GObject` (or derived) struct, the `GObjectClass` (or derived) struct, and any private data allocated by `G_ADD_PRIVATE()`. Creates a new instance of a #GObject subtype and sets its properties. Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values. Any private data for the object is guaranteed to be initialized with zeros, as per g_type_create_instance(). Note that in C, small integer types in variable argument lists are promoted up to `gint` or `guint` as appropriate, and read back accordingly. `gint` is 32 bits on every platform on which GLib is currently supported. This means that you can use C expressions of type `gint` with g_object_new() and properties of type `gint` or `guint` or smaller. Specifically, you can use integer literals with these property types. When using property types of `gint64` or `guint64`, you must ensure that the value that you provide is 64 bit. This means that you should use a cast or make use of the %G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros. Similarly, `gfloat` is promoted to `gdouble`, so you must ensure that the value you provide is a `gdouble`, even for a property of type `gfloat`. Since GLib 2.72, all #GObjects are guaranteed to be aligned to at least the alignment of the largest basic GLib type (typically this is `guint64` or `gdouble`). If you need larger alignment for an element in a #GObject, you should allocate it on the heap (aligned), or arrange for your #GObject to be appropriately padded. a new instance of @object_type the type id of the #GObject subtype to instantiate the name of the first property the value of the first property, followed optionally by more name/value pairs, followed by %NULL Creates a new instance of a #GObject subtype and sets its properties. Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values. a new instance of @object_type the type id of the #GObject subtype to instantiate the name of the first property the value of the first property, followed optionally by more name/value pairs, followed by %NULL Creates a new instance of a #GObject subtype and sets its properties using the provided arrays. Both arrays must have exactly @n_properties elements, and the names and values correspond by index. Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values. a new instance of @object_type the object type to instantiate the number of properties the names of each property to be set the values of each property to be set Creates a new instance of a #GObject subtype and sets its properties. Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values. Use g_object_new_with_properties() instead. deprecated. See #GParameter for more information. a new instance of @object_type the type id of the #GObject subtype to instantiate the length of the @parameters array an array of #GParameter Find the #GParamSpec with the given name for an interface. Generally, the interface vtable passed in as @g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek(). the #GParamSpec for the property of the interface with the name @property_name, or %NULL if no such property exists. any interface vtable for the interface, or the default vtable for the interface name of a property to look up. Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created #GParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property. This function is meant to be called from the interface's default vtable initialization function (the @class_init member of #GTypeInfo.) It must not be called after after @class_init has been called for any object types implementing this interface. If @pspec is a floating reference, it will be consumed. any interface vtable for the interface, or the default vtable for the interface. the #GParamSpec for the new property Lists the properties of an interface.Generally, the interface vtable passed in as @g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek(). a pointer to an array of pointers to #GParamSpec structures. The paramspecs are owned by GLib, but the array should be freed with g_free() when you are done with it. any interface vtable for the interface, or the default vtable for the interface location to store number of properties returned. the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation. emits property change notification for a bunch of properties. Overriding @dispatch_properties_changed should be rarely needed. the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class. instance finalization function, should finish the finalization of the instance begun in @dispose and chain up to the @finalize method of the parent class. the generic getter for all properties of this type. Should be overridden for every type with properties. Emits a "notify" signal for the property @property_name on @object. When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead. Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called. a #GObject the generic setter for all properties of this type. Should be overridden for every type with properties. If implementations of @set_property don't emit property change notification explicitly, this will be done implicitly by the type system. However, if the notify signal is emitted explicitly, the type system will not emit it a second time. Increases the reference count of the object by one and sets a callback to be called when all other references to the object are dropped, or when this is already the last reference to the object and another reference is established. This functionality is intended for binding @object to a proxy object managed by another memory manager. This is done with two paired references: the strong reference added by g_object_add_toggle_ref() and a reverse reference to the proxy object which is either a strong reference or weak reference. The setup is that when there are no other references to @object, only a weak reference is held in the reverse direction from @object to the proxy object, but when there are other references held to @object, a strong reference is held. The @notify callback is called when the reference from @object to the proxy object should be "toggled" from strong to weak (@is_last_ref true) or weak to strong (@is_last_ref false). Since a (normal) reference must be held to the object before calling g_object_add_toggle_ref(), the initial state of the reverse link is always strong. Multiple toggle references may be added to the same gobject, however if there are multiple toggle references to an object, none of them will ever be notified until all but one are removed. For this reason, you should only ever use a toggle reference if there is important state in the proxy object. Note that if you unref the object on another thread, then @notify might still be invoked after g_object_remove_toggle_ref(), and the object argument might be a dangling pointer. If the object is destroyed on other threads, you must take care of that yourself. A g_object_add_toggle_ref() must be released with g_object_remove_toggle_ref(). a #GObject a function to call when this reference is the last reference to the object, or is no longer the last reference. data to pass to @notify Adds a weak reference from weak_pointer to @object to indicate that the pointer located at @weak_pointer_location is only valid during the lifetime of @object. When the @object is finalized, @weak_pointer will be set to %NULL. Note that as with g_object_weak_ref(), the weak references created by this method are not thread-safe: they cannot safely be used in one thread if the object's last g_object_unref() might happen in another thread. Use #GWeakRef if thread-safety is required. The object that should be weak referenced. The memory address of a pointer. Creates a binding between @source_property on @source and @target_property on @target. Whenever the @source_property is changed the @target_property is updated using the same value. For instance: |[<!-- language="C" --> g_object_bind_property (action, "active", widget, "sensitive", 0); ]| Will result in the "sensitive" property of the widget #GObject instance to be updated with the same value of the "active" property of the action #GObject instance. If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: if @target_property on @target changes then the @source_property on @source will be updated as well. The binding will automatically be removed when either the @source or the @target instances are finalized. To remove the binding without affecting the @source and the @target you can just call g_object_unref() on the returned #GBinding instance. Removing the binding by calling g_object_unref() on it must only be done if the binding, @source and @target are only used from a single thread and it is clear that both @source and @target outlive the binding. Especially it is not safe to rely on this if the binding, @source or @target can be finalized from different threads. Keep another reference to the binding and use g_binding_unbind() instead to be on the safe side. A #GObject can have multiple bindings. the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. the source #GObject the property on @source to bind the target #GObject the property on @target to bind flags to pass to #GBinding Complete version of g_object_bind_property(). Creates a binding between @source_property on @source and @target_property on @target, allowing you to set the transformation functions to be used by the binding. If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: if @target_property on @target changes then the @source_property on @source will be updated as well. The @transform_from function is only used in case of bidirectional bindings, otherwise it will be ignored The binding will automatically be removed when either the @source or the @target instances are finalized. This will release the reference that is being held on the #GBinding instance; if you want to hold on to the #GBinding instance, you will need to hold a reference to it. To remove the binding, call g_binding_unbind(). A #GObject can have multiple bindings. The same @user_data parameter will be used for both @transform_to and @transform_from transformation functions; the @notify function will be called once, when the binding is removed. If you need different data for each transformation function, please use g_object_bind_property_with_closures() instead. the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. the source #GObject the property on @source to bind the target #GObject the property on @target to bind flags to pass to #GBinding the transformation function from the @source to the @target, or %NULL to use the default the transformation function from the @target to the @source, or %NULL to use the default custom data to be passed to the transformation functions, or %NULL a function to call when disposing the binding, to free resources used by the transformation functions, or %NULL if not required Creates a binding between @source_property on @source and @target_property on @target, allowing you to set the transformation functions to be used by the binding. This function is the language bindings friendly version of g_object_bind_property_full(), using #GClosures instead of function pointers. the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. the source #GObject the property on @source to bind the target #GObject the property on @target to bind flags to pass to #GBinding a #GClosure wrapping the transformation function from the @source to the @target, or %NULL to use the default a #GClosure wrapping the transformation function from the @target to the @source, or %NULL to use the default A convenience function to connect multiple signals at once. The signal specs expected by this function have the form `modifier::signal_name`, where `modifier` can be one of the following: - `signal`: equivalent to `g_signal_connect_data (..., NULL, G_CONNECT_DEFAULT)` - `object-signal`, `object_signal`: equivalent to `g_signal_connect_object (..., G_CONNECT_DEFAULT)` - `swapped-signal`, `swapped_signal`: equivalent to `g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)` - `swapped_object_signal`, `swapped-object-signal`: equivalent to `g_signal_connect_object (..., G_CONNECT_SWAPPED)` - `signal_after`, `signal-after`: equivalent to `g_signal_connect_data (..., NULL, G_CONNECT_AFTER)` - `object_signal_after`, `object-signal-after`: equivalent to `g_signal_connect_object (..., G_CONNECT_AFTER)` - `swapped_signal_after`, `swapped-signal-after`: equivalent to `g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER)` - `swapped_object_signal_after`, `swapped-object-signal-after`: equivalent to `g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)` ```c menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW, "type", GTK_WINDOW_POPUP, "child", menu, NULL), "signal::event", gtk_menu_window_event, menu, "signal::size_request", gtk_menu_window_size_request, menu, "signal::destroy", gtk_widget_destroyed, &menu->toplevel, NULL); ``` the object a #GObject the spec for the first signal [type@GObject.Callback] for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by `NULL` A convenience function to disconnect multiple signals at once. The signal specs expected by this function have the form "any_signal", which means to disconnect any signal with matching callback and data, or "any_signal::signal_name", which only disconnects the signal named "signal_name". a #GObject the spec for the first signal #GCallback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by %NULL This is a variant of g_object_get_data() which returns a 'duplicate' of the value. @dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object. If the @key is not set on the object then @dup_func will be called with a %NULL argument. Note that @dup_func is called while user data of @object is locked. This function can be useful to avoid races when multiple threads are using object data on the same key on the same object. the result of calling @dup_func on the value associated with @key on @object, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. the #GObject to store user data on a string, naming the user data pointer function to dup the value passed as user_data to @dup_func This is a variant of g_object_get_qdata() which returns a 'duplicate' of the value. @dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object. If the @quark is not set on the object then @dup_func will be called with a %NULL argument. Note that @dup_func is called while user data of @object is locked. This function can be useful to avoid races when multiple threads are using object data on the same key on the same object. the result of calling @dup_func on the value associated with @quark on @object, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. the #GObject to store user data on a #GQuark, naming the user data pointer function to dup the value passed as user_data to @dup_func This function is intended for #GObject implementations to re-enforce a [floating][floating-ref] object reference. Doing this is seldom required: all #GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink(). a #GObject Increases the freeze count on @object. If the freeze count is non-zero, the emission of "notify" signals on @object is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most one #GObject::notify signal is emitted for each property modified while the object is frozen. This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified. a #GObject Gets properties of an object. In general, a copy is made of the property contents and the caller is responsible for freeing the memory in the appropriate manner for the type, for instance by calling g_free() or g_object_unref(). Here is an example of using g_object_get() to get the contents of three properties: an integer, a string and an object: |[<!-- language="C" --> gint intval; guint64 uint64val; gchar *strval; GObject *objval; g_object_get (my_object, "int-property", &intval, "uint64-property", &uint64val, "str-property", &strval, "obj-property", &objval, NULL); // Do something with intval, uint64val, strval, objval g_free (strval); g_object_unref (objval); ]| a #GObject name of the first property to get return location for the first property, followed optionally by more name/return location pairs, followed by %NULL Gets a named field from the objects table of associations (see g_object_set_data()). the data if found, or %NULL if no such data exists. #GObject containing the associations name of the key for that association Gets a property of an object. The @value can be: - an empty #GValue initialized by %G_VALUE_INIT, which will be automatically initialized with the expected type of the property (since GLib 2.60) - a #GValue initialized with the expected type of the property - a #GValue initialized with a type to which the expected type of the property can be transformed In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling g_value_unset(). Note that g_object_get_property() is really intended for language bindings, g_object_get() is much more convenient for C programming. a #GObject the name of the property to get return location for the property value This function gets back user data pointers stored via g_object_set_qdata(). The user data pointer set, or %NULL The GObject to get a stored user data pointer from A #GQuark, naming the user data pointer Gets properties of an object. In general, a copy is made of the property contents and the caller is responsible for freeing the memory in the appropriate manner for the type, for instance by calling g_free() or g_object_unref(). See g_object_get(). a #GObject name of the first property to get return location for the first property, followed optionally by more name/return location pairs, followed by %NULL Gets @n_properties properties for an @object. Obtained properties will be set to @values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in. a #GObject the number of properties the names of each property to get the values of each property to get Checks whether @object has a [floating][floating-ref] reference. %TRUE if @object has a floating reference a #GObject Emits a "notify" signal for the property @property_name on @object. When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead. Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called. a #GObject the name of a property installed on the class of @object. Emits a "notify" signal for the property specified by @pspec on @object. This function omits the property name lookup, hence it is faster than g_object_notify(). One way to avoid using g_object_notify() from within the class that registered the properties, and using g_object_notify_by_pspec() instead, is to store the GParamSpec used with g_object_class_install_property() inside a static array, e.g.: |[<!-- language="C" --> typedef enum { PROP_FOO = 1, PROP_LAST } MyObjectProperty; static GParamSpec *properties[PROP_LAST]; static void my_object_class_init (MyObjectClass *klass) { properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL, 0, 100, 50, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); g_object_class_install_property (gobject_class, PROP_FOO, properties[PROP_FOO]); } ]| and then notify a change on the "foo" property with: |[<!-- language="C" --> g_object_notify_by_pspec (self, properties[PROP_FOO]); ]| a #GObject the #GParamSpec of a property installed on the class of @object. Increases the reference count of @object. Since GLib 2.56, if `GLIB_VERSION_MAX_ALLOWED` is 2.56 or greater, the type of @object will be propagated to the return type (using the GCC typeof() extension), so any casting the caller needs to do on the return type must be explicit. the same @object a #GObject Increase the reference count of @object, and possibly remove the [floating][floating-ref] reference, if @object has a floating reference. In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one. Since GLib 2.56, the type of @object will be propagated to the return type under the same conditions as for g_object_ref(). @object a #GObject Removes a reference added with g_object_add_toggle_ref(). The reference count of the object is decreased by one. Note that if you unref the object on another thread, then @notify might still be invoked after g_object_remove_toggle_ref(), and the object argument might be a dangling pointer. If the object is destroyed on other threads, you must take care of that yourself. a #GObject a function to call when this reference is the last reference to the object, or is no longer the last reference. data to pass to @notify, or %NULL to match any toggle refs with the @notify argument. Removes a weak reference from @object that was previously added using g_object_add_weak_pointer(). The @weak_pointer_location has to match the one used with g_object_add_weak_pointer(). The object that is weak referenced. The memory address of a pointer. Compares the user data for the key @key on @object with @oldval, and if they are the same, replaces @oldval with @newval. This is like a typical atomic compare-and-exchange operation, for user data on an object. If the previous value was replaced then ownership of the old value (@oldval) is passed to the caller, including the registered destroy notify for it (passed out in @old_destroy). It’s up to the caller to free this as needed, which may or may not include using @old_destroy as sometimes replacement should not destroy the object in the normal way. See g_object_set_data() for guidance on using a small, bounded set of values for @key. %TRUE if the existing value for @key was replaced by @newval, %FALSE otherwise. the #GObject to store user data on a string, naming the user data pointer the old value to compare against the new value a destroy notify for the new value destroy notify for the existing value Compares the user data for the key @quark on @object with @oldval, and if they are the same, replaces @oldval with @newval. This is like a typical atomic compare-and-exchange operation, for user data on an object. If the previous value was replaced then ownership of the old value (@oldval) is passed to the caller, including the registered destroy notify for it (passed out in @old_destroy). It’s up to the caller to free this as needed, which may or may not include using @old_destroy as sometimes replacement should not destroy the object in the normal way. %TRUE if the existing value for @quark was replaced by @newval, %FALSE otherwise. the #GObject to store user data on a #GQuark, naming the user data pointer the old value to compare against the new value a destroy notify for the new value destroy notify for the existing value Releases all references to other objects. This can be used to break reference cycles. This function should only be called from object system implementations. a #GObject Sets properties on an object. The same caveats about passing integer literals as varargs apply as with g_object_new(). In particular, any integer literals set as the values for properties of type #gint64 or #guint64 must be 64 bits wide, using the %G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros. Note that the "notify" signals are queued and only emitted (in reverse order) after all properties have been set. See g_object_freeze_notify(). a #GObject name of the first property to set value for the first property, followed optionally by more name/value pairs, followed by %NULL Each object carries around a table of associations from strings to pointers. This function lets you set an association. If the object already had an association with that name, the old association will be destroyed. Internally, the @key is converted to a #GQuark using g_quark_from_string(). This means a copy of @key is kept permanently (even after @object has been finalized) — so it is recommended to only use a small, bounded set of values for @key in your program, to avoid the #GQuark storage growing unbounded. #GObject containing the associations. name of the key data to associate with that key Like g_object_set_data() except it adds notification for when the association is destroyed, either by setting it to a different value or when the object is destroyed. Note that the @destroy callback is not called if @data is %NULL. #GObject containing the associations name of the key data to associate with that key function to call when the association is destroyed Sets a property on an object. a #GObject the name of the property to set the value This sets an opaque, named pointer on an object. The name is specified through a #GQuark (retrieved e.g. via g_quark_from_static_string()), and the pointer can be gotten back from the @object with g_object_get_qdata() until the @object is finalized. Setting a previously set user data pointer, overrides (frees) the old pointer set, using #NULL as pointer essentially removes the data stored. The GObject to set store a user data pointer A #GQuark, naming the user data pointer An opaque user data pointer This function works like g_object_set_qdata(), but in addition, a void (*destroy) (gpointer) function may be specified which is called with @data as argument when the @object is finalized, or the data is being overwritten by a call to g_object_set_qdata() with the same @quark. The GObject to set store a user data pointer A #GQuark, naming the user data pointer An opaque user data pointer Function to invoke with @data as argument, when @data needs to be freed Sets properties on an object. a #GObject name of the first property to set value for the first property, followed optionally by more name/value pairs, followed by %NULL Sets @n_properties properties for an @object. Properties to be set will be taken from @values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in. a #GObject the number of properties the names of each property to be set the values of each property to be set Remove a specified datum from the object's data associations, without invoking the association's destroy handler. the data if found, or %NULL if no such data exists. #GObject containing the associations name of the key This function gets back user data pointers stored via g_object_set_qdata() and removes the @data from object without invoking its destroy() function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier, for example: |[<!-- language="C" --> void object_add_to_user_list (GObject *object, const gchar *new_string) { // the quark, naming the object data GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); // retrieve the old string list GList *list = g_object_steal_qdata (object, quark_string_list); // prepend new string list = g_list_prepend (list, g_strdup (new_string)); // this changed 'list', so we need to set it again g_object_set_qdata_full (object, quark_string_list, list, free_string_list); } static void free_string_list (gpointer data) { GList *node, *list = data; for (node = list; node; node = node->next) g_free (node->data); g_list_free (list); } ]| Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full(). The user data pointer set, or %NULL The GObject to get a stored user data pointer from A #GQuark, naming the user data pointer If @object is floating, sink it. Otherwise, do nothing. In other words, this function will convert a floating reference (if present) into a full reference. Typically you want to use g_object_ref_sink() in order to automatically do the correct thing with respect to floating or non-floating references, but there is one specific scenario where this function is helpful. The situation where this function is helpful is when creating an API that allows the user to provide a callback function that returns a GObject. We certainly want to allow the user the flexibility to return a non-floating reference from this callback (for the case where the object that is being returned already exists). At the same time, the API style of some popular GObject-based libraries (such as Gtk) make it likely that for newly-created GObject instances, the user can be saved some typing if they are allowed to return a floating reference. Using this function on the return value of the user's callback allows the user to do whichever is more convenient for them. The caller will always receives exactly one full reference to the value: either the one that was returned in the first place, or a floating reference that has been converted to a full reference. This function has an odd interaction when combined with g_object_ref_sink() running at the same time in another thread on the same #GObject instance. If g_object_ref_sink() runs first then the result will be that the floating reference is converted to a hard reference. If g_object_take_ref() runs first then the result will be that the floating reference is converted to a hard reference and an additional reference on top of that one is added. It is best to avoid this situation. @object a #GObject Reverts the effect of a previous call to g_object_freeze_notify(). The freeze count is decreased on @object and when it reaches zero, queued "notify" signals are emitted. Duplicate notifications for each property are squashed so that at most one #GObject::notify signal is emitted for each property, in the reverse order in which they have been queued. It is an error to call this function when the freeze count is zero. a #GObject Decreases the reference count of @object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed). If the pointer to the #GObject may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to %NULL rather than retain a dangling pointer to a potentially invalid #GObject instance. Use g_clear_object() for this. : a #GObject This function essentially limits the life time of the @closure to the life time of the object. That is, when the object is finalized, the @closure is invalidated by calling g_closure_invalidate() on it, in order to prevent invocations of the closure with a finalized (nonexisting) object. Also, g_object_ref() and g_object_unref() are added as marshal guards to the @closure, to ensure that an extra reference count is held on @object during invocation of the @closure. Usually, this function will be called on closures that use this @object as closure data. #GObject restricting lifetime of @closure #GClosure to watch Adds a weak reference callback to an object. Weak references are used for notification when an object is disposed. They are called "weak references" because they allow you to safely hold a pointer to an object without calling g_object_ref() (g_object_ref() adds a strong reference, that is, forces the object to stay alive). Note that the weak references created by this method are not thread-safe: they cannot safely be used in one thread if the object's last g_object_unref() might happen in another thread. Use #GWeakRef if thread-safety is required. #GObject to reference weakly callback to invoke before the object is freed extra data to pass to notify Removes a weak reference callback to an object. #GObject to remove a weak reference from callback to search for data to search for The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al. Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with %G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results in ::notify being emitted, even if the new value is the same as the old. If they did pass %G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call g_object_notify() or g_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed. This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this: |[<!-- language="C" --> g_signal_connect (text_view->buffer, "notify::paste-target-list", G_CALLBACK (gtk_text_view_target_list_notify), text_view) ]| It is important to note that you must use [canonical parameter names][class@GObject.ParamSpec#parameter-names] as detail strings for the notify signal. the #GParamSpec of the property which changed. The class structure for the GObject type. |[<!-- language="C" --> // Example of implementing a singleton using a constructor. static MySingleton *the_singleton = NULL; static GObject* my_singleton_constructor (GType type, guint n_construct_params, GObjectConstructParam *construct_params) { GObject *object; if (!the_singleton) { object = G_OBJECT_CLASS (parent_class)->constructor (type, n_construct_params, construct_params); the_singleton = MY_SINGLETON (object); } else object = g_object_ref (G_OBJECT (the_singleton)); return object; } ]| the parent class the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the @constructor of the parent class. Overriding @constructor should be rarely needed, e.g. to handle construct properties, or to implement singletons. the generic setter for all properties of this type. Should be overridden for every type with properties. If implementations of @set_property don't emit property change notification explicitly, this will be done implicitly by the type system. However, if the notify signal is emitted explicitly, the type system will not emit it a second time. the generic getter for all properties of this type. Should be overridden for every type with properties. the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class. instance finalization function, should finish the finalization of the instance begun in @dispose and chain up to the @finalize method of the parent class. emits property change notification for a bunch of properties. Overriding @dispatch_properties_changed should be rarely needed. the class closure for the notify signal a #GObject the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation. Looks up the #GParamSpec for a property of a class. the #GParamSpec for the property, or %NULL if the class doesn't have a property of that name a #GObjectClass the name of the property to look up Installs new properties from an array of #GParamSpecs. All properties should be installed during the class initializer. It is possible to install properties after that, but doing so is not recommend, and specifically, is not guaranteed to be thread-safe vs. use of properties on the same type on other threads. The property id of each property is the index of each #GParamSpec in the @pspecs array. The property id of 0 is treated specially by #GObject and it should not be used to store a #GParamSpec. This function should be used if you plan to use a static array of #GParamSpecs and g_object_notify_by_pspec(). For instance, this class initialization: |[<!-- language="C" --> typedef enum { PROP_FOO = 1, PROP_BAR, N_PROPERTIES } MyObjectProperty; static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, }; static void my_object_class_init (MyObjectClass *klass) { GObjectClass *gobject_class = G_OBJECT_CLASS (klass); obj_properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL, -1, G_MAXINT, 0, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); obj_properties[PROP_BAR] = g_param_spec_string ("bar", NULL, NULL, NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); gobject_class->set_property = my_object_set_property; gobject_class->get_property = my_object_get_property; g_object_class_install_properties (gobject_class, G_N_ELEMENTS (obj_properties), obj_properties); } ]| allows calling g_object_notify_by_pspec() to notify of property changes: |[<!-- language="C" --> void my_object_set_foo (MyObject *self, gint foo) { if (self->foo != foo) { self->foo = foo; g_object_notify_by_pspec (G_OBJECT (self), obj_properties[PROP_FOO]); } } ]| a #GObjectClass the length of the #GParamSpecs array the #GParamSpecs array defining the new properties Installs a new property. All properties should be installed during the class initializer. It is possible to install properties after that, but doing so is not recommend, and specifically, is not guaranteed to be thread-safe vs. use of properties on the same type on other threads. Note that it is possible to redefine a property in a derived class, by installing a property with the same name. This can be useful at times, e.g. to change the range of allowed values or the default value. a #GObjectClass the id for the new property the #GParamSpec for the new property Get an array of #GParamSpec* for all properties of a class. an array of #GParamSpec* which should be freed after use a #GObjectClass return location for the length of the returned array Registers @property_id as referring to a property with the name @name in a parent class or in an interface implemented by @oclass. This allows this class to "override" a property implementation in a parent class or to provide the implementation of a property from an interface. Internally, overriding is implemented by creating a property of type #GParamSpecOverride; generally operations that query the properties of the object class, such as g_object_class_find_property() or g_object_class_list_properties() will return the overridden property. However, in one case, the @construct_properties argument of the @constructor virtual function, the #GParamSpecOverride is passed instead, so that the @param_id field of the #GParamSpec will be correct. For virtually all uses, this makes no difference. If you need to get the overridden property, you can call g_param_spec_get_redirect_target(). a #GObjectClass the new property ID the name of a property registered in a parent class or in an interface of this class. The GObjectConstructParam struct is an auxiliary structure used to hand #GParamSpec/#GValue pairs to the @constructor of a #GObjectClass. the #GParamSpec of the construct parameter the value to set the parameter to The type of the @finalize function of #GObjectClass. the #GObject being finalized The type of the @get_property function of #GObjectClass. a #GObject the numeric id under which the property was registered with g_object_class_install_property(). a #GValue to return the property value in the #GParamSpec describing the property The type of the @set_property function of #GObjectClass. a #GObject the numeric id under which the property was registered with g_object_class_install_property(). the new value for the property the #GParamSpec describing the property Mask containing the bits of #GParamSpec.flags which are reserved for GLib. Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into a #GParamSpec object. a valid #GParamSpec Cast a #GParamSpec instance into a #GParamSpecBoolean. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecBoxed. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecChar. a valid #GParamSpec instance Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. a valid #GParamSpecClass Cast a #GParamSpec instance into a #GParamSpecDouble. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecEnum. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecFlags. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecFloat. a valid #GParamSpec instance Retrieves the #GParamSpecClass of a #GParamSpec. a valid #GParamSpec Casts a #GParamSpec into a #GParamSpecGType. a #GParamSpec Cast a #GParamSpec instance into a #GParamSpecInt. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecInt64. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecLong. a valid #GParamSpec instance Casts a #GParamSpec instance into a #GParamSpecObject. a valid #GParamSpec instance Casts a #GParamSpec into a #GParamSpecOverride. a #GParamSpec Casts a #GParamSpec instance into a #GParamSpecParam. a valid #GParamSpec instance Casts a #GParamSpec instance into a #GParamSpecPointer. a valid #GParamSpec instance Casts a #GParamSpec instance into a #GParamSpecString. a valid #GParamSpec instance Retrieves the #GType of this @pspec. a valid #GParamSpec Retrieves the #GType name of this @pspec. a valid #GParamSpec Cast a #GParamSpec instance into a #GParamSpecUChar. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecUInt. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecUInt64. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecULong. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecUnichar. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecValueArray. Use #GArray instead of #GValueArray a valid #GParamSpec instance Retrieves the #GType to initialize a #GValue for this parameter. a valid #GParamSpec Casts a #GParamSpec into a #GParamSpecVariant. a #GParamSpec #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. It is recommended to use this for all properties by default, as it allows for internal performance improvements in GObject. It is very rare that a property would have a dynamically constructed name, nickname or blurb. Since 2.13.0 Minimum shift count to be used for user defined flags, to be stored in #GParamSpec.flags. The maximum allowed is 10. Evaluates to the @field_name inside the @inst private data structure for @TypeName. Note that this macro can only be used together with the `G_DEFINE_TYPE_*` and G_ADD_PRIVATE() macros, since it depends on variable names from those macros. the name of the type in CamelCase the instance of @TypeName you wish to access the type of the field in the private data structure the name of the field in the private data structure Evaluates to a pointer to the @field_name inside the @inst private data structure for @TypeName. Note that this macro can only be used together with the `G_DEFINE_TYPE_*` and G_ADD_PRIVATE() macros, since it depends on variable names from those macros. the name of the type in CamelCase the instance of @TypeName you wish to access the name of the field in the private data structure Evaluates to the offset of the @field inside the instance private data structure for @TypeName. Note that this macro can only be used together with the `G_DEFINE_TYPE_*` and G_ADD_PRIVATE() macros, since it depends on variable names from those macros. the name of the type in CamelCase the name of the field in the private data structure Through the #GParamFlags flag values, certain aspects of parameters can be configured. See also: %G_PARAM_STATIC_STRINGS the parameter is readable the parameter is writable alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE the parameter will be set upon object construction. See [vfunc@Object.constructed] for more details the parameter can only be set upon object construction. See [vfunc@Object.constructed] for more details upon parameter conversion (see g_param_value_convert()) strict validation is not required the string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 internal the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8 the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 calls to g_object_set_property() for this property will not automatically result in a "notify" signal being emitted: the implementation must call g_object_notify() themselves in case the property actually changes. Since: 2.42. the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since 2.26 `GParamSpec` encapsulates the metadata required to specify parameters, such as `GObject` properties. ## Parameter names A property name consists of one or more segments consisting of ASCII letters and digits, separated by either the `-` or `_` character. The first character of a property name must be a letter. These are the same rules as for signal naming (see [func@GObject.signal_new]). When creating and looking up a `GParamSpec`, either separator can be used, but they cannot be mixed. Using `-` is considerably more efficient, and is the ‘canonical form’. Using `_` is discouraged. Creates a new #GParamSpec instance. See [canonical parameter names][class@GObject.ParamSpec#parameter-names] for details of the rules for @name. Names which violate these rules lead to undefined behaviour. Beyond the name, #GParamSpecs have two more descriptive strings, the @nick and @blurb, which may be used as a localized label and description. For GTK and related libraries these are considered deprecated and may be omitted, while for other libraries such as GStreamer and its plugins they are essential. When in doubt, follow the conventions used in the surrounding code and supporting libraries. (transfer floating): a newly allocated #GParamSpec instance, which is initially floating the #GType for the property; must be derived from %G_TYPE_PARAM the canonical name of the property the nickname of the property a short description of the property a combination of #GParamFlags Validate a property name for a #GParamSpec. This can be useful for dynamically-generated properties which need to be validated at run-time before actually trying to create them. See [canonical parameter names][class@GObject.ParamSpec#parameter-names] for details of the rules for valid names. %TRUE if @name is a valid property name, %FALSE otherwise. the canonical name of the property The instance finalization function (optional), should chain up to the finalize method of the parent class. Checks if contents of @value comply with the specifications set out by this type, without modifying the value. This vfunc is optional. If it isn't set, GObject will use @value_validate. Since 2.74 Resets a @value to the default value for this type (recommended, the default is g_value_reset()), see g_param_value_set_default(). Ensures that the contents of @value comply with the specifications set out by this type (optional), see g_param_value_validate(). Compares @value1 with @value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp(). Get the short description of a #GParamSpec. the short description of @pspec. a valid #GParamSpec Gets the default value of @pspec as a pointer to a #GValue. The #GValue will remain valid for the life of @pspec. a pointer to a #GValue which must not be modified a #GParamSpec Get the name of a #GParamSpec. The name is always an "interned" string (as per g_intern_string()). This allows for pointer-value comparisons. the name of @pspec. a valid #GParamSpec Gets the GQuark for the name. the GQuark for @pspec->name. a #GParamSpec Get the nickname of a #GParamSpec. the nickname of @pspec. a valid #GParamSpec Gets back user data pointers stored via g_param_spec_set_qdata(). the user data pointer set, or %NULL a valid #GParamSpec a #GQuark, naming the user data pointer If the paramspec redirects operations to another paramspec, returns that paramspec. Redirect is used typically for providing a new implementation of a property in a derived type while preserving all the properties from the parent type. Redirection is established by creating a property of type #GParamSpecOverride. See g_object_class_override_property() for an example of the use of this capability. paramspec to which requests on this paramspec should be redirected, or %NULL if none. a #GParamSpec Increments the reference count of @pspec. the #GParamSpec that was passed into this function a valid #GParamSpec Convenience function to ref and sink a #GParamSpec. the #GParamSpec that was passed into this function a valid #GParamSpec Sets an opaque, named pointer on a #GParamSpec. The name is specified through a #GQuark (retrieved e.g. via g_quark_from_static_string()), and the pointer can be gotten back from the @pspec with g_param_spec_get_qdata(). Setting a previously set user data pointer, overrides (frees) the old pointer set, using %NULL as pointer essentially removes the data stored. the #GParamSpec to set store a user data pointer a #GQuark, naming the user data pointer an opaque user data pointer This function works like g_param_spec_set_qdata(), but in addition, a `void (*destroy) (gpointer)` function may be specified which is called with @data as argument when the @pspec is finalized, or the data is being overwritten by a call to g_param_spec_set_qdata() with the same @quark. the #GParamSpec to set store a user data pointer a #GQuark, naming the user data pointer an opaque user data pointer function to invoke with @data as argument, when @data needs to be freed The initial reference count of a newly created #GParamSpec is 1, even though no one has explicitly called g_param_spec_ref() on it yet. So the initial reference count is flagged as "floating", until someone calls `g_param_spec_ref (pspec); g_param_spec_sink (pspec);` in sequence on it, taking over the initial reference count (thus ending up with a @pspec that has a reference count of 1 still, but is not flagged "floating" anymore). a valid #GParamSpec Gets back user data pointers stored via g_param_spec_set_qdata() and removes the @data from @pspec without invoking its destroy() function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier. the user data pointer set, or %NULL the #GParamSpec to get a stored user data pointer from a #GQuark, naming the user data pointer Decrements the reference count of a @pspec. a valid #GParamSpec private `GTypeInstance` portion name of this parameter: always an interned string `GParamFlags` flags for this parameter the `GValue` type for this parameter `GType` type that uses (introduces) this parameter A #GParamSpec derived structure that contains the meta data for boolean properties. private #GParamSpec portion default value for the property specified A #GParamSpec derived structure that contains the meta data for boxed properties. private #GParamSpec portion A #GParamSpec derived structure that contains the meta data for character properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified The class structure for the GParamSpec type. Normally, GParamSpec classes are filled by g_param_type_register_static(). the parent class the #GValue type for this parameter The instance finalization function (optional), should chain up to the finalize method of the parent class. Resets a @value to the default value for this type (recommended, the default is g_value_reset()), see g_param_value_set_default(). Ensures that the contents of @value comply with the specifications set out by this type (optional), see g_param_value_validate(). Compares @value1 with @value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp(). Checks if contents of @value comply with the specifications set out by this type, without modifying the value. This vfunc is optional. If it isn't set, GObject will use @value_validate. Since 2.74 A #GParamSpec derived structure that contains the meta data for double properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-90. A #GParamSpec derived structure that contains the meta data for enum properties. private #GParamSpec portion the #GEnumClass for the enum default value for the property specified A #GParamSpec derived structure that contains the meta data for flags properties. private #GParamSpec portion the #GFlagsClass for the flags default value for the property specified A #GParamSpec derived structure that contains the meta data for float properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-30. A #GParamSpec derived structure that contains the meta data for #GType properties. private #GParamSpec portion a #GType whose subtypes can occur as values A #GParamSpec derived structure that contains the meta data for integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for 64bit integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for long integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for object properties. private #GParamSpec portion A #GParamSpec derived structure that redirects operations to other types of #GParamSpec. All operations other than getting or setting the value are redirected, including accessing the nick and blurb, validating a value, and so forth. See g_param_spec_get_redirect_target() for retrieving the overridden property. #GParamSpecOverride is used in implementing g_object_class_override_property(), and will not be directly useful unless you are implementing a new base type similar to GObject. A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM properties. private #GParamSpec portion A #GParamSpec derived structure that contains the meta data for pointer properties. private #GParamSpec portion A #GParamSpecPool maintains a collection of #GParamSpecs which can be quickly accessed by owner and name. The implementation of the #GObject property system uses such a pool to store the #GParamSpecs of the properties all object types. Frees the resources allocated by a #GParamSpecPool. a #GParamSpecPool Inserts a #GParamSpec in the pool. a #GParamSpecPool. the #GParamSpec to insert a #GType identifying the owner of @pspec Gets an array of all #GParamSpecs owned by @owner_type in the pool. a newly allocated array containing pointers to all #GParamSpecs owned by @owner_type in the pool a #GParamSpecPool the owner to look for return location for the length of the returned array Gets an #GList of all #GParamSpecs owned by @owner_type in the pool. a #GList of all #GParamSpecs owned by @owner_type in the pool#GParamSpecs. a #GParamSpecPool the owner to look for Looks up a #GParamSpec in the pool. The found #GParamSpec, or %NULL if no matching #GParamSpec was found. a #GParamSpecPool the name to look for the owner to look for If %TRUE, also try to find a #GParamSpec with @param_name owned by an ancestor of @owner_type. Removes a #GParamSpec from the pool. a #GParamSpecPool the #GParamSpec to remove Creates a new #GParamSpecPool. If @type_prefixing is %TRUE, lookups in the newly created pool will allow to specify the owner as a colon-separated prefix of the property name, like "GtkContainer:border-width". This feature is deprecated, so you should always set @type_prefixing to %FALSE. a newly allocated #GParamSpecPool. Whether the pool will support type-prefixed property names. A #GParamSpec derived structure that contains the meta data for string properties. private #GParamSpec portion default value for the property specified a string containing the allowed values for the first byte a string containing the allowed values for the subsequent bytes the replacement byte for bytes which don't match @cset_first or @cset_nth. replace empty string by %NULL replace %NULL strings by an empty string This structure is used to provide the type system with the information required to initialize and destruct (finalize) a parameter's class and instances thereof. The initialized structure is passed to the g_param_type_register_static() The type system will perform a deep copy of this structure, so its memory does not need to be persistent across invocation of g_param_type_register_static(). Size of the instance (object) structure. Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the [slice allocator][glib-Memory-Slices] now. Location of the instance initialization function (optional). The #GType of values conforming to this #GParamSpec The instance finalization function (optional). Resets a @value to the default value for @pspec (recommended, the default is g_value_reset()), see g_param_value_set_default(). Ensures that the contents of @value comply with the specifications set out by @pspec (optional), see g_param_value_validate(). Compares @value1 with @value2 according to @pspec (recommended, the default is memcmp()), see g_param_values_cmp(). A #GParamSpec derived structure that contains the meta data for unsigned character properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for unsigned integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for unsigned long integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties. private #GParamSpec portion default value for the property specified A #GParamSpec derived structure that contains the meta data for #GValueArray properties. private #GParamSpec portion a #GParamSpec describing the elements contained in arrays of this property, may be %NULL if greater than 0, arrays of this property will always have this many elements A #GParamSpec derived structure that contains the meta data for #GVariant properties. When comparing values with g_param_values_cmp(), scalar values with the same type will be compared with g_variant_compare(). Other non-%NULL variants will be checked for equality with g_variant_equal(), and their sort order is otherwise undefined. %NULL is ordered before non-%NULL variants. Two %NULL values compare equal. private #GParamSpec portion a #GVariantType, or %NULL a #GVariant, or %NULL The GParameter struct is an auxiliary structure used to hand parameter name/value pairs to g_object_newv(). This type is not introspectable. the parameter name the parameter value A mask for all #GSignalFlags bits. A mask for all #GSignalMatchType bits. The signal accumulator is a special callback function that can be used to collect return values of the various callbacks that are called during a signal emission. The signal accumulator is specified at signal creation time, if it is left %NULL, no accumulation of callback return values is performed. The return value of signal emissions is then the value returned by the last callback. The accumulator function returns whether the signal emission should be aborted. Returning %TRUE will continue with the signal emission. Returning %FALSE will abort the current emission. Since 2.62, returning %FALSE will skip to the CLEANUP stage. In this case, emission will occur as normal in the CLEANUP stage and the handler's return value will be accumulated. Signal invocation hint, see #GSignalInvocationHint. Accumulator to collect callback return values in, this is the return value of the current signal emission. A #GValue holding the return value of the signal handler. Callback data that was specified when creating the signal. A simple function pointer to get invoked when the signal is emitted. Emission hooks allow you to tie a hook to the signal type, so that it will trap all emissions of that signal, from any object. You may not attach these to signals created with the %G_SIGNAL_NO_HOOKS flag. whether it wants to stay connected. If it returns %FALSE, the signal hook is disconnected (and destroyed). Signal invocation hint, see #GSignalInvocationHint. the number of parameters to the function, including the instance on which the signal was emitted. the instance on which the signal was emitted, followed by the parameters of the emission. user data associated with the hook. The signal flags are used to specify a signal's behaviour. Invoke the object method handler in the first emission stage. Invoke the object method handler in the third emission stage. Invoke the object method handler in the last emission stage. Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted. This signal supports "::detail" appendices to the signal name upon handler connections and emissions. Action signals are signals that may freely be emitted on alive objects from user code via g_signal_emit() and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as object methods which can be called generically by third-party code. No emissions hooks are supported for this signal. Varargs signal emission will always collect the arguments, even if there are no signal handlers connected. The signal is deprecated and will be removed in a future version. A warning will be generated if it is connected while running with `G_ENABLE_DIAGNOSTIC=1`. The signal accumulator was invoked for the first time. This flag is only used in [callback@GObject.SignalAccumulator][accumulator functions] for the `run_type` field of the [struct@GObject.SignalInvocationHint], to mark the first call to the accumulator function for a signal emission. `GSignalGroup` manages a collection of signals on a `GObject`. `GSignalGroup` simplifies the process of connecting many signals to a `GObject` as a group. As such there is no API to disconnect a signal from the group. In particular, this allows you to: - Change the target instance, which automatically causes disconnection of the signals from the old instance and connecting to the new instance. - Block and unblock signals as a group - Ensuring that blocked state transfers across target instances. One place you might want to use such a structure is with `GtkTextView` and `GtkTextBuffer`. Often times, you'll need to connect to many signals on `GtkTextBuffer` from a `GtkTextView` subclass. This allows you to create a signal group during instance construction, simply bind the `GtkTextView:buffer` property to `GSignalGroup:target` and connect all the signals you need. When the `GtkTextView:buffer` property changes all of the signals will be transitioned correctly. Creates a new #GSignalGroup for target instances of @target_type. a new #GSignalGroup the #GType of the target instance. Blocks all signal handlers managed by @self so they will not be called during any signal emissions. Must be unblocked exactly the same number of times it has been blocked to become active again. This blocked state will be kept across changes of the target instance. the #GSignalGroup Connects @c_handler to the signal @detailed_signal on the target instance of @self. You cannot connect a signal handler after #GSignalGroup:target has been set. a #GSignalGroup a string of the form "signal-name::detail" the #GCallback to connect the data to pass to @c_handler calls Connects @c_handler to the signal @detailed_signal on the target instance of @self. The @c_handler will be called after the default handler of the signal. You cannot connect a signal handler after #GSignalGroup:target has been set. a #GSignalGroup a string of the form "signal-name::detail" the #GCallback to connect the data to pass to @c_handler calls Connects @closure to the signal @detailed_signal on #GSignalGroup:target. You cannot connect a signal handler after #GSignalGroup:target has been set. a #GSignalGroup a string of the form `signal-name` with optional `::signal-detail` the closure to connect. whether the handler should be called before or after the default handler of the signal. Connects @c_handler to the signal @detailed_signal on the target instance of @self. You cannot connect a signal handler after #GSignalGroup:target has been set. a #GSignalGroup a string of the form "signal-name::detail" the #GCallback to connect the data to pass to @c_handler calls function to be called when disposing of @self the flags used to create the signal connection Connects @c_handler to the signal @detailed_signal on #GSignalGroup:target. Ensures that the @object stays alive during the call to @c_handler by temporarily adding a reference count. When the @object is destroyed the signal handler will automatically be removed. You cannot connect a signal handler after #GSignalGroup:target has been set. a #GSignalGroup a string of the form `signal-name` with optional `::signal-detail` the #GCallback to connect the #GObject to pass as data to @c_handler calls #GConnectFlags for the signal connection Connects @c_handler to the signal @detailed_signal on the target instance of @self. The instance on which the signal is emitted and @data will be swapped when calling @c_handler. You cannot connect a signal handler after #GSignalGroup:target has been set. a #GSignalGroup a string of the form "signal-name::detail" the #GCallback to connect the data to pass to @c_handler calls Gets the target instance used when connecting signals. The target instance the #GSignalGroup Sets the target instance used when connecting signals. Any signal that has been registered with g_signal_group_connect_object() or similar functions will be connected to this object. If the target instance was previously set, signals will be disconnected from that object prior to connecting to @target. the #GSignalGroup. The target instance used when connecting signals. Unblocks all signal handlers managed by @self so they will be called again during any signal emissions unless it is blocked again. Must be unblocked exactly the same number of times it has been blocked to become active again. the #GSignalGroup The target instance used when connecting signals. The #GType of the target property. This signal is emitted when #GSignalGroup:target is set to a new value other than %NULL. It is similar to #GObject::notify on `target` except it will not emit when #GSignalGroup:target is %NULL and also allows for receiving the #GObject without a data-race. a #GObject containing the new value for #GSignalGroup:target This signal is emitted when the target instance of @self is set to a new #GObject. This signal will only be emitted if the previous target of @self is non-%NULL. The #GSignalInvocationHint structure is used to pass on additional information to callbacks during a signal emission. The signal id of the signal invoking the callback The detail passed on for this emission The stage the signal emission is currently in, this field will contain one of %G_SIGNAL_RUN_FIRST, %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP and %G_SIGNAL_ACCUMULATOR_FIRST_RUN. %G_SIGNAL_ACCUMULATOR_FIRST_RUN is only set for the first run of the accumulator function for a signal emission. The match types specify what g_signal_handlers_block_matched(), g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() match signals by. The signal id must be equal. The signal detail must be equal. The closure must be the same. The C closure callback must be the same. The closure data must be the same. Only unblocked signals may be matched. A structure holding in-depth information for a specific signal. See also: g_signal_query() The signal id of the signal being queried, or 0 if the signal to be queried was unknown. The signal name. The interface/instance type that this signal can be emitted for. The signal flags as passed in to g_signal_new(). The return type for user callbacks. The number of parameters that user callbacks take. The individual parameter types for user callbacks, note that the effective callback signature is: |[<!-- language="C" --> @return_type callback (#gpointer data1, [param_types param_names,] gpointer data2); ]| Set the callback for a source as a #GClosure. If the source is not one of the standard GLib types, the @closure_callback and @closure_marshal fields of the #GSourceFuncs structure must have been filled in with pointers to appropriate functions. the source a #GClosure Sets a dummy callback for @source. The callback will do nothing, and if the source expects a #gboolean return value, it will return %TRUE. (If the source expects any other type of return value, it will return a 0/%NULL value; whatever g_value_init() initializes a #GValue to for that type.) If the source is not one of the standard GLib types, the @closure_callback and @closure_marshal fields of the #GSourceFuncs structure must have been filled in with pointers to appropriate functions. the source Checks that @g_class is a class structure of the type identified by @g_type and issues a warning if this is not the case. Returns @g_class casted to a pointer to @c_type. %NULL is not a valid class structure. This macro should only be used in type implementations. Location of a #GTypeClass structure The type to be returned The corresponding C type of class structure of @g_type Checks if @g_class is a class structure of the type identified by @g_type. If @g_class is %NULL, %FALSE will be returned. This macro should only be used in type implementations. Location of a #GTypeClass structure The type to be checked Checks if @instance is a valid #GTypeInstance structure, otherwise issues a warning and returns %FALSE. %NULL is not a valid #GTypeInstance. This macro should only be used in type implementations. Location of a #GTypeInstance structure Checks that @instance is an instance of the type identified by @g_type and issues a warning if this is not the case. Returns @instance casted to a pointer to @c_type. No warning will be issued if @instance is %NULL, and %NULL will be returned. This macro should only be used in type implementations. Location of a #GTypeInstance structure The type to be returned The corresponding C type of @g_type Checks if @instance is an instance of the fundamental type identified by @g_type. If @instance is %NULL, %FALSE will be returned. This macro should only be used in type implementations. Location of a #GTypeInstance structure. The fundamental type to be checked Checks if @instance is an instance of the type identified by @g_type. If @instance is %NULL, %FALSE will be returned. This macro should only be used in type implementations. Location of a #GTypeInstance structure. The type to be checked Checks if @value has been initialized to hold values of a value type. This macro should only be used in type implementations. a #GValue Checks if @value has been initialized to hold values of type @g_type. This macro should only be used in type implementations. a #GValue The type to be checked Gets the private class structure for a particular type. The private structure must have been registered in the get_type() function with g_type_add_class_private(). This macro should only be used in type implementations. the class of a type deriving from @private_type the type identifying which private data to retrieve The C type for the private structure A bit in the type number that's supposed to be left untouched. Get the type identifier from a given @class structure. This macro should only be used in type implementations. Location of a valid #GTypeClass structure Get the type identifier from a given @instance structure. This macro should only be used in type implementations. Location of a valid #GTypeInstance structure Get the type identifier from a given @interface structure. This macro should only be used in type implementations. Location of a valid #GTypeInterface structure The fundamental type which is the ancestor of @type. Fundamental types are types that serve as ultimate bases for the derived types, thus they are the roots of distinct inheritance hierarchies. A #GType value. An integer constant that represents the number of identifiers reserved for types that are assigned at compile-time. Shift value used in converting numbers to type IDs. Checks if @type has a #GTypeValueTable. A #GType value Get the class structure of a given @instance, casted to a specified ancestor type @g_type of the instance. Note that while calling a GInstanceInitFunc(), the class pointer gets modified, so it might not always return the expected pointer. This macro should only be used in type implementations. Location of the #GTypeInstance structure The #GType of the class to be returned The C type of the class structure Get the interface structure for interface @g_type of a given @instance. This macro should only be used in type implementations. Location of the #GTypeInstance structure The #GType of the interface to be returned The C type of the interface structure Gets the private structure for a particular type. The private structure must have been registered in the class_init function with g_type_class_add_private(). This macro should only be used in type implementations. Use G_ADD_PRIVATE() and the generated `your_type_get_instance_private()` function instead the instance of a type deriving from @private_type the type identifying which private data to retrieve The C type for the private structure Checks if @type is an abstract type. An abstract type cannot be instantiated and is normally used as an abstract base class for derived classes. A #GType value Checks if @type is a classed type. A classed type has an associated #GTypeClass which can be derived to store class-wide virtual function pointers and data for all instances of the type. This allows for subclassing. All #GObjects are classed; none of the scalar fundamental types built into GLib are classed. Interfaces are not classed: while their #GTypeInterface struct could be considered similar to #GTypeClass, and classes can derive interfaces, #GTypeInterface doesn’t allow for subclassing. A #GType value Checks if @type is a deep derivable type. A deep derivable type can be used as the base class of a deep (multi-level) class hierarchy. A #GType value Checks if @type is deprecated. Instantiating a deprecated type will trigger a warning if running with `G_ENABLE_DIAGNOSTIC=1`. a #GType value Checks if @type is a derivable type. A derivable type can be used as the base class of a flat (single-level) class hierarchy. A #GType value Checks if @type is derived (or in object-oriented terminology: inherited) from another type (this holds true for all non-fundamental types). A #GType value Checks whether @type "is a" %G_TYPE_ENUM. a #GType ID. Checks if @type is a final type. A final type cannot be derived any further. a #GType value Checks whether @type "is a" %G_TYPE_FLAGS. a #GType ID. Checks if @type is a fundamental type. A #GType value Checks if @type can be instantiated. Instantiation is the process of creating an instance (object) of this type. A #GType value Checks if @type is an interface type. An interface type provides a pure API, the implementation of which is provided by another type (which is then said to conform to the interface). GLib interfaces are somewhat analogous to Java interfaces and C++ classes containing only pure virtual functions, with the difference that GType interfaces are not derivable (but see g_type_interface_add_prerequisite() for an alternative). A #GType value Check if the passed in type id is a %G_TYPE_OBJECT or derived from it. Type id to check Checks whether @type "is a" %G_TYPE_PARAM. a #GType ID Checks whether the passed in type ID can be used for [method@GObject.Value.init]. That is, this macro checks whether this type provides an implementation of the [struct@GObject.TypeValueTable] functions required to be able to create a [struct@GObject.Value] instance. a type Checks if @type is an abstract value type. An abstract value type introduces a value table, but can't be used for g_value_init() and is normally used as an abstract base type for derived value types. A #GType value Checks if @type is a value type and can be used with g_value_init(). A #GType value Get the type ID for the fundamental type number @x. Use g_type_fundamental_next() instead of this macro to create new fundamental types. the fundamental type number. First fundamental type number to create a new fundamental type id with G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE. Last fundamental type number reserved for BSE. First fundamental type number to create a new fundamental type id with G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. Last fundamental type number reserved for GLib. First available fundamental type number to create new fundamental type id with G_TYPE_MAKE_FUNDAMENTAL(). A callback function used for notification when the state of a toggle reference changes. See also: g_object_add_toggle_ref() Callback data passed to g_object_add_toggle_ref() The object on which g_object_add_toggle_ref() was called. %TRUE if the toggle reference is now the last reference to the object. %FALSE if the toggle reference was the last reference and there are now other references. A union holding one collected value. the field for holding integer values the field for holding long integer values the field for holding 64 bit integer values the field for holding floating point values the field for holding pointers An opaque structure used as the base of all classes. Registers a private structure for an instantiatable type. When an object is allocated, the private structures for the type and all of its parent types are allocated sequentially in the same memory block as the public structures, and are zero-filled. Note that the accumulated size of the private structures of a type and all its parent types cannot exceed 64 KiB. This function should be called in the type's class_init() function. The private structure can be retrieved using the G_TYPE_INSTANCE_GET_PRIVATE() macro. The following example shows attaching a private structure MyObjectPrivate to an object MyObject defined in the standard GObject fashion in the type's class_init() function. Note the use of a structure member "priv" to avoid the overhead of repeatedly calling MY_OBJECT_GET_PRIVATE(). |[<!-- language="C" --> typedef struct _MyObject MyObject; typedef struct _MyObjectPrivate MyObjectPrivate; struct _MyObject { GObject parent; MyObjectPrivate *priv; }; struct _MyObjectPrivate { int some_field; }; static void my_object_class_init (MyObjectClass *klass) { g_type_class_add_private (klass, sizeof (MyObjectPrivate)); } static void my_object_init (MyObject *my_object) { my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object, MY_TYPE_OBJECT, MyObjectPrivate); // my_object->priv->some_field will be automatically initialised to 0 } static int my_object_get_some_field (MyObject *my_object) { MyObjectPrivate *priv; g_return_val_if_fail (MY_IS_OBJECT (my_object), 0); priv = my_object->priv; return priv->some_field; } ]| Use the G_ADD_PRIVATE() macro with the `G_DEFINE_*` family of macros to add instance private data to a type class structure for an instantiatable type size of private structure Gets the offset of the private data for instances of @g_class. This is how many bytes you should add to the instance pointer of a class in order to get the private data for the type represented by @g_class. You can only call this function after you have registered a private data area for @g_class using g_type_class_add_private(). the offset, in bytes a #GTypeClass Retrieves the class structure of the immediate parent type of the class passed in. This is a convenience function often needed in class initializers. Since derived classes hold a reference on their parent classes as long as they are instantiated, the returned class will always exist. This function is essentially equivalent to: g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))) the parent class of @g_class the #GTypeClass structure to retrieve the parent class for Decrements the reference count of the class structure being passed in. Once the last reference count of a class has been released, classes may be finalized by the type system, so further dereferencing of a class pointer after g_type_class_unref() are invalid. Type class reference counting has been removed and type classes now cannot be finalized. This function no longer does anything. a #GTypeClass structure to unref A variant of g_type_class_unref() for use in #GTypeClassCacheFunc implementations. It unreferences a class without consulting the chain of #GTypeClassCacheFuncs, avoiding the recursion which would occur otherwise. Type class reference counting has been removed and type classes now cannot be finalized. This function no longer does anything. a #GTypeClass structure to unref Retrieves the type class of the given @type. This function will create the class on demand if it does not exist already. If you don't want to create the class, use g_type_class_peek() instead. the class structure for the type type ID of a classed type Retrieves the class for a give type. This function is essentially the same as g_type_class_get(), except that the class may have not been instantiated yet. As a consequence, this function may return %NULL if the class of the type passed in does not currently exist (hasn't been referenced before). the #GTypeClass structure for the given type ID or %NULL if the class does not currently exist type ID of a classed type A more efficient version of g_type_class_peek() which works only for static types. the #GTypeClass structure for the given type ID or %NULL if the class does not currently exist or is dynamically loaded type ID of a classed type Increments the reference count of the class structure belonging to @type. This function will demand-create the class if it doesn't exist already. Use g_type_class_get() instead the #GTypeClass structure for the given type ID type ID of a classed type A callback function which is called when the reference count of a class drops to zero. It may use g_type_class_ref() to prevent the class from being freed. You should not call g_type_class_unref() from a #GTypeClassCacheFunc function to prevent infinite recursion, use g_type_class_unref_uncached() instead. The functions have to check the class id passed in to figure whether they actually want to cache the class of this type, since all classes are routed through the same #GTypeClassCacheFunc chain. %TRUE to stop further #GTypeClassCacheFuncs from being called, %FALSE to continue data that was given to the g_type_add_class_cache_func() call The #GTypeClass structure which is unreferenced These flags used to be passed to g_type_init_with_debug_flags() which is now deprecated. If you need to enable debugging features, use the `GOBJECT_DEBUG` environment variable. g_type_init() is now done automatically Print no messages Print messages about object bookkeeping Print messages about signal emissions Keep a count of instances of each type Mask covering all debug flags Bit masks used to check or determine characteristics of a type. No special flags. Since: 2.74 Indicates an abstract type. No instances can be created for an abstract type Indicates an abstract value type, i.e. a type that introduces a value table, but can't be used for g_value_init() Indicates a final type. A final type is a non-derivable leaf node in a deep derivable type hierarchy tree. Since: 2.70 The type is deprecated and may be removed in a future version. A warning will be emitted if it is instantiated while running with `G_ENABLE_DIAGNOSTIC=1`. Since 2.76 Bit masks used to check or determine specific characteristics of a fundamental type. Indicates a classed type Indicates an instantiatable type (implies classed) Indicates a flat derivable type Indicates a deep derivable type (implies derivable) A structure that provides information to the type system which is used specifically for managing fundamental types. #GTypeFundamentalFlags describing the characteristics of the fundamental type This structure is used to provide the type system with the information required to initialize and destruct (finalize) a type's class and its instances. The initialized structure is passed to the g_type_register_static() function (or is copied into the provided #GTypeInfo structure in the g_type_plugin_complete_type_info()). The type system will perform a deep copy of this structure, so its memory does not need to be persistent across invocation of g_type_register_static(). Size of the class structure (required for interface, classed and instantiatable types) Location of the base initialization function (optional) Location of the base finalization function (optional) Location of the class initialization function for classed and instantiatable types. Location of the default vtable initialization function for interface types. (optional) This function is used both to fill in virtual functions in the class or default vtable, and to do type-specific setup such as registering signals and object properties. Location of the class finalization function for classed and instantiatable types. Location of the default vtable finalization function for interface types. (optional) User-supplied data passed to the class init/finalize functions Size of the instance (object) structure (required for instantiatable types only) Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10 this field is ignored. Location of the instance initialization function (optional, for instantiatable types only) A #GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types) An opaque structure used as the base of all type instances. An opaque structure used as the base of all interface types. Returns the corresponding #GTypeInterface structure of the parent type of the instance type to which @g_iface belongs. This is useful when deriving the implementation of an interface from the parent type and then possibly overriding some methods. the corresponding #GTypeInterface structure of the parent type of the instance type to which @g_iface belongs, or %NULL if the parent type doesn't conform to the interface a #GTypeInterface structure Adds @prerequisite_type to the list of prerequisites of @interface_type. This means that any type implementing @interface_type must also implement @prerequisite_type. Prerequisites can be thought of as an alternative to interface derivation (which GType doesn't support). An interface can have at most one instantiatable prerequisite type. #GType value of an interface type #GType value of an interface or instantiatable type Returns the #GTypePlugin structure for the dynamic interface @interface_type which has been added to @instance_type, or %NULL if @interface_type has not been added to @instance_type or does not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). the #GTypePlugin for the dynamic interface @interface_type of @instance_type #GType of an instantiatable type #GType of an interface type Returns the most specific instantiatable prerequisite of an interface type. If the interface type has no instantiatable prerequisite, %G_TYPE_INVALID is returned. See g_type_interface_add_prerequisite() for more information about prerequisites. the instantiatable prerequisite type or %G_TYPE_INVALID if none an interface type Returns the #GTypeInterface structure of an interface to which the passed in class conforms. the #GTypeInterface structure of @iface_type if implemented by @instance_class, %NULL otherwise a #GTypeClass structure an interface ID which this class conforms to Returns the prerequisites of an interfaces type. a newly-allocated zero-terminated array of #GType containing the prerequisites of @interface_type an interface type location to return the number of prerequisites, or %NULL A callback called after an interface vtable is initialized. See g_type_add_interface_check(). data passed to g_type_add_interface_check() the interface that has been initialized `GTypeModule` provides a simple implementation of the `GTypePlugin` interface. The model of `GTypeModule` is a dynamically loaded module which implements some number of types and interface implementations. When the module is loaded, it registers its types and interfaces using [method@GObject.TypeModule.register_type] and [method@GObject.TypeModule.add_interface]. As long as any instances of these types and interface implementations are in use, the module is kept loaded. When the types and interfaces are gone, the module may be unloaded. If the types and interfaces become used again, the module will be reloaded. Note that the last reference cannot be released from within the module code, since that would lead to the caller's code being unloaded before `g_object_unref()` returns to it. Keeping track of whether the module should be loaded or not is done by using a use count - it starts at zero, and whenever it is greater than zero, the module is loaded. The use count is maintained internally by the type system, but also can be explicitly controlled by [method@GObject.TypeModule.use] and [method@GObject.TypeModule.unuse]. Typically, when loading a module for the first type, `g_type_module_use()` will be used to load it so that it can initialize its types. At some later point, when the module no longer needs to be loaded except for the type implementations it contains, `g_type_module_unuse()` is called. `GTypeModule` does not actually provide any implementation of module loading and unloading. To create a particular module type you must derive from `GTypeModule` and implement the load and unload functions in `GTypeModuleClass`. loads the module and registers one or more types using g_type_module_register_type(). unloads the module Registers an additional interface for a type, whose interface lives in the given type plugin. If the interface was already registered for the type in this plugin, nothing will be done. As long as any instances of the type exist, the type plugin will not be unloaded. Since 2.56 if @module is %NULL this will call g_type_add_interface_static() instead. This can be used when making a static build of the module. a #GTypeModule type to which to add the interface. interface type to add type information structure Looks up or registers an enumeration that is implemented with a particular type plugin. If a type with name @type_name was previously registered, the #GType identifier for the type is returned, otherwise the type is newly registered, and the resulting #GType identifier returned. As long as any instances of the type exist, the type plugin will not be unloaded. Since 2.56 if @module is %NULL this will call g_type_register_static() instead. This can be used when making a static build of the module. the new or existing type ID a #GTypeModule name for the type an array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. Looks up or registers a flags type that is implemented with a particular type plugin. If a type with name @type_name was previously registered, the #GType identifier for the type is returned, otherwise the type is newly registered, and the resulting #GType identifier returned. As long as any instances of the type exist, the type plugin will not be unloaded. Since 2.56 if @module is %NULL this will call g_type_register_static() instead. This can be used when making a static build of the module. the new or existing type ID a #GTypeModule name for the type an array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. Looks up or registers a type that is implemented with a particular type plugin. If a type with name @type_name was previously registered, the #GType identifier for the type is returned, otherwise the type is newly registered, and the resulting #GType identifier returned. When reregistering a type (typically because a module is unloaded then reloaded, and reinitialized), @module and @parent_type must be the same as they were previously. As long as any instances of the type exist, the type plugin will not be unloaded. Since 2.56 if @module is %NULL this will call g_type_register_static() instead. This can be used when making a static build of the module. the new or existing type ID a #GTypeModule the type for the parent class name for the type type information structure flags field providing details about the type Sets the name for a #GTypeModule a #GTypeModule. a human-readable name to use in error messages. Decreases the use count of a #GTypeModule by one. If the result is zero, the module will be unloaded. (However, the #GTypeModule will not be freed, and types associated with the #GTypeModule are not unregistered. Once a #GTypeModule is initialized, it must exist forever.) a #GTypeModule Increases the use count of a #GTypeModule by one. If the use count was zero before, the plugin will be loaded. If loading the plugin fails, the use count is reset to its prior value. %FALSE if the plugin needed to be loaded and loading the plugin failed. a #GTypeModule the name of the module In order to implement dynamic loading of types based on #GTypeModule, the @load and @unload functions in #GTypeModuleClass must be implemented. the parent class loads the module and registers one or more types using g_type_module_register_type(). unloads the module An interface that handles the lifecycle of dynamically loaded types. The GObject type system supports dynamic loading of types. It goes as follows: 1. The type is initially introduced (usually upon loading the module the first time, or by your main application that knows what modules introduces what types), like this: ```c new_type_id = g_type_register_dynamic (parent_type_id, "TypeName", new_type_plugin, type_flags); ``` where `new_type_plugin` is an implementation of the `GTypePlugin` interface. 2. The type's implementation is referenced, e.g. through [func@GObject.TypeClass.ref] or through [func@GObject.type_create_instance] (this is being called by [ctor@GObject.Object.new]) or through one of the above done on a type derived from `new_type_id`. 3. This causes the type system to load the type's implementation by calling [method@GObject.TypePlugin.use] and [method@GObject.TypePlugin.complete_type_info] on `new_type_plugin`. 4. At some point the type's implementation isn't required anymore, e.g. after [method@GObject.TypeClass.unref] or [func@GObject.type_free_instance] (called when the reference count of an instance drops to zero). 5. This causes the type system to throw away the information retrieved from [method@GObject.TypePlugin.complete_type_info] and then it calls [method@GObject.TypePlugin.unuse] on `new_type_plugin`. 6. Things may repeat from the second step. So basically, you need to implement a `GTypePlugin` type that carries a use_count, once use_count goes from zero to one, you need to load the implementation to successfully handle the upcoming [method@GObject.TypePlugin.complete_type_info] call. Later, maybe after succeeding use/unuse calls, once use_count drops to zero, you can unload the implementation again. The type system makes sure to call [method@GObject.TypePlugin.use] and [method@GObject.TypePlugin.complete_type_info] again when the type is needed again. [class@GObject.TypeModule] is an implementation of `GTypePlugin` that already implements most of this except for the actual module loading and unloading. It even handles multiple registered types per module. Calls the @complete_interface_info function from the #GTypePluginClass of @plugin. There should be no need to use this function outside of the GObject type system itself. the #GTypePlugin the #GType of an instantiatable type to which the interface is added the #GType of the interface whose info is completed the #GInterfaceInfo to fill in Calls the @complete_type_info function from the #GTypePluginClass of @plugin. There should be no need to use this function outside of the GObject type system itself. a #GTypePlugin the #GType whose info is completed the #GTypeInfo struct to fill in the #GTypeValueTable to fill in Calls the @unuse_plugin function from the #GTypePluginClass of @plugin. There should be no need to use this function outside of the GObject type system itself. a #GTypePlugin Calls the @use_plugin function from the #GTypePluginClass of @plugin. There should be no need to use this function outside of the GObject type system itself. a #GTypePlugin The #GTypePlugin interface is used by the type system in order to handle the lifecycle of dynamically loaded types. Increases the use count of the plugin. Decreases the use count of the plugin. Fills in the #GTypeInfo and #GTypeValueTable structs for the type. The structs are initialized with `memset(s, 0, sizeof (s))` before calling this function. Fills in missing parts of the #GInterfaceInfo for the interface. The structs is initialized with `memset(s, 0, sizeof (s))` before calling this function. The type of the @complete_interface_info function of #GTypePluginClass. the #GTypePlugin the #GType of an instantiatable type to which the interface is added the #GType of the interface whose info is completed the #GInterfaceInfo to fill in The type of the @complete_type_info function of #GTypePluginClass. the #GTypePlugin the #GType whose info is completed the #GTypeInfo struct to fill in the #GTypeValueTable to fill in The type of the @unuse_plugin function of #GTypePluginClass. the #GTypePlugin whose use count should be decreased The type of the @use_plugin function of #GTypePluginClass, which gets called to increase the use count of @plugin. the #GTypePlugin whose use count should be increased A structure holding information for a specific type. See also: g_type_query() the #GType value of the type the name of the type the size of the class structure the size of the instance structure This function is responsible for converting the values collected from a variadic argument list into contents suitable for storage in a #GValue. This function should setup @value similar to #GTypeValueInitFunc; e.g. for a string value that does not allow `NULL` pointers, it needs to either emit an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for #GTypeValueInitFunc it is guaranteed to not contain any old contents that might need freeing. The @n_collect_values argument is the string length of the `collect_format` field of #GTypeValueTable, and `collect_values` is an array of #GTypeCValue with length of @n_collect_values, containing the collected values according to `collect_format`. The @collect_flags argument provided as a hint by the caller. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating that the collected value contents may be considered ‘static’ for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[<!-- language="C" --> if (!collect_values[0].v_pointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the %G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the signal emission code, reference counts should always be incremented for reference counted contents stored in the `value->data` array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for `GTypeValueTable.collect_value()` of `GObject`: |[<!-- language="C" --> GObject *object = G_OBJECT (collect_values[0].v_pointer); g_return_val_if_fail (object != NULL, g_strdup_printf ("Object %p passed as invalid NULL pointer", object)); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types value->data[0].v_pointer = g_object_ref (object); return NULL; ]| The reference count for valid objects is always incremented, regardless of `collect_flags`. For invalid objects, the example returns a newly allocated string without altering `value`. Upon success, `collect_value()` needs to return `NULL`. If, however, an error condition occurred, `collect_value()` should return a newly allocated string containing an error diagnostic. The calling code makes no assumptions about the `value` contents being valid upon error returns, `value` is simply thrown away without further freeing. As such, it is a good idea to not allocate `GValue` contents prior to returning an error; however, `collect_values()` is not obliged to return a correctly setup @value for error returns, simply because any non-`NULL` return is considered a fatal programming error, and further program behaviour is undefined. `NULL` on success, otherwise a newly allocated error string on failure the value to initialize the number of collected values the collected values optional flags Copies the content of a #GValue into another. The @dest_value is a #GValue with zero-filled data section and @src_value is a properly initialized #GValue of same type, or derived type. The purpose of this function is to copy the contents of @src_value into @dest_value in a way, that even after @src_value has been freed, the contents of @dest_value remain valid. String type example: |[<!-- language="C" --> dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]| the value to copy the location of the copy Frees any old contents that might be left in the `value->data` array of the given value. No resources may remain allocated through the #GValue contents after this function returns. E.g. for our above string type: |[<!-- language="C" --> // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]| the value to free Initializes the value contents by setting the fields of the `value->data` array. The data array of the #GValue passed into this function was zero-filled with `memset()`, so no care has to be taken to free any old contents. For example, in the case of a string value that may never be %NULL, the implementation might look like: |[<!-- language="C" --> value->data[0].v_pointer = g_strdup (""); ]| the value to initialize This function is responsible for storing the `value` contents into arguments passed through a variadic argument list which got collected into `collect_values` according to `lcopy_format`. The `n_collect_values` argument equals the string length of `lcopy_format`, and `collect_flags` may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to #GTypeValueCollectFunc, this function is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to #GTypeValueCollectFunc the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[<!-- language="C" --> gchar **string_p = collect_values[0].v_pointer; g_return_val_if_fail (string_p != NULL, g_strdup ("string location passed as NULL")); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of this function for reference-counted types: |[<!-- language="C" --> GObject **object_p = collect_values[0].v_pointer; g_return_val_if_fail (object_p != NULL, g_strdup ("object location passed as NULL")); if (value->data[0].v_pointer == NULL) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]| `NULL` on success, otherwise a newly allocated error string on failure the value to lcopy the number of collected values the collected locations for storage optional flags If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[<!-- language="C" --> return value->data[0].v_pointer; ]| a pointer to the value contents the value to peek - `'i'`: Integers, passed as `collect_values[].v_int` - `'l'`: Longs, passed as `collect_values[].v_long` - `'d'`: Doubles, passed as `collect_values[].v_double` - `'p'`: Pointers, passed as `collect_values[].v_pointer` It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, `'i'` needs to be used, and for collection of floats `'d'`. The #GTypeValueTable provides the functions required by the #GValue implementation, to serve as a container for values of a type. Function to initialize a GValue Function to free a GValue Function to copy a GValue Function to peek the contents of a GValue if they fit into a pointer A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: Function to initialize a GValue from the values collected from variadic arguments Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of `'p'`s to provide lcopy_value() with pointers to storage locations. Function to store the contents of a value into the locations collected from variadic arguments Returns the location of the #GTypeValueTable associated with @type. Note that this function should only be used from source code that implements or has internal knowledge of the implementation of @type. location of the #GTypeValueTable associated with @type or %NULL if there is no #GTypeValueTable associated with @type a #GType Collects a variable argument value from a `va_list`. We have to implement the varargs collection as a macro, because on some systems `va_list` variables cannot be passed by reference. Note: If you are creating the @value argument just before calling this macro, you should use the G_VALUE_COLLECT_INIT() variant and pass the uninitialized #GValue. That variant is faster than G_VALUE_COLLECT(). a #GValue return location. @value is supposed to be initialized according to the value type to be collected the va_list variable; it may be evaluated multiple times flags which are passed on to the collect_value() function of the #GTypeValueTable of @value. a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails The maximal number of #GTypeCValues which can be collected for a single #GValue. Collects a variable argument value from a `va_list`. We have to implement the varargs collection as a macro, because on some systems `va_list` variables cannot be passed by reference. a #GValue return location. @value must contain only 0 bytes. the #GType to use for @value. the va_list variable; it may be evaluated multiple times flags which are passed on to the collect_value() function of the #GTypeValueTable of @value. a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails A variant of G_VALUE_COLLECT_INIT() that provides the #GTypeValueTable to the caller. a #GValue return location. @value must contain only 0 bytes. a #GTypeValueTable pointer that will be set to the value table for @_value_type the #GType to use for @value. the va_list variable; it may be evaluated multiple times flags which are passed on to the collect_value() function of the #GTypeValueTable of @value. a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails Skip an argument of type @_value_type from @var_args. the #GType of the value to skip the va_list variable; it may be evaluated multiple times Checks if @value holds a value of @type. This macro will also check for `value != NULL` and issue a warning if the check fails. a [struct@GObject.Value] structure a [type@GObject.Type] Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN. a valid #GValue structure Checks whether the given #GValue can hold values derived from type %G_TYPE_BOXED. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_CHAR. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE. a valid #GValue structure Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM. a valid #GValue structure Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_INT. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_INT64. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_LONG. a valid #GValue structure Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT. a valid #GValue structure Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_POINTER. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_STRING. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_UINT. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_UINT64. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_ULONG. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT. a valid #GValue structure Flag to indicate that a string in a [struct@GObject.Value] is canonical and will exist for the duration of the process. See [method@GObject.Value.set_interned_string]. This flag should be checked by implementations of [callback@GObject.TypeValueFreeFunc], [callback@GObject.TypeValueCollectFunc] and [callback@GObject.TypeValueLCopyFunc]. Checks whether @value contains a string which is canonical. a valid #GValue structure Stores a value’s value into one or more argument locations from a `va_list`. This is the inverse of G_VALUE_COLLECT(). a #GValue to store into the @var_args; this must be initialized and set the va_list variable; it may be evaluated multiple times flags which are passed on to the lcopy_value() function of the #GTypeValueTable of @value. a #gchar** variable that will be modified to hold a g_new() allocated error message if something fails Flag to indicate that allocated data in a [struct@GObject.Value] shouldn’t be copied. If passed to [func@GObject.VALUE_COLLECT], allocated data won’t be copied but used verbatim. This does not affect ref-counted types like objects. This does not affect usage of [method@GObject.Value.copy]: the data will be copied if it is not ref-counted. This flag should be checked by implementations of [callback@GObject.TypeValueFreeFunc], [callback@GObject.TypeValueCollectFunc] and [callback@GObject.TypeValueLCopyFunc]. Get the type identifier of @value. a [struct@GObject.Value] structure Gets the name of the type of @value. a [struct@GObject.Value] structure This is the signature of va_list marshaller functions, an optional marshaller that can be used in some situations to avoid marshalling the signal argument into GValues. the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. An opaque structure used to hold different types of values. Before it can be used, a `GValue` has to be initialized to a specific type by calling [method@GObject.Value.init] on it. Many types which are stored within a `GValue` need to allocate data on the heap, so [method@GObject.Value.unset] must always be called on a `GValue` to free any such data once you’re finished with the `GValue`, even if the `GValue` itself is stored on the stack. The data within the structure has protected scope: it is accessible only to functions within a [struct@GObject.TypeValueTable] structure, or implementations of the `g_value_*()` API. That is, code which implements new fundamental types. `GValue` users cannot make any assumptions about how data is stored within the 2 element @data union, and the @g_type member should only be accessed through the [func@GObject.VALUE_TYPE] macro and related macros. Copies the value of @src_value into @dest_value. an initialized [struct@GObject.Value] structure an initialized [struct@GObject.Value] structure of the same type as @src_value Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting, the boxed value is duplicated and needs to be later freed with g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), return_value); boxed contents of @value a valid #GValue of %G_TYPE_BOXED derived type Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing its reference count. If the contents of the #GValue are %NULL, then %NULL will be returned. object content of @value, should be unreferenced when no longer needed. a valid #GValue whose type is derived from %G_TYPE_OBJECT Get the contents of a %G_TYPE_PARAM #GValue, increasing its reference count. #GParamSpec content of @value, should be unreferenced when no longer needed. a valid #GValue whose type is derived from %G_TYPE_PARAM Get a copy the contents of a %G_TYPE_STRING #GValue. a newly allocated copy of the string content of @value a valid #GValue of type %G_TYPE_STRING Get the contents of a variant #GValue, increasing its refcount. The returned #GVariant is never floating. variant contents of @value (may be %NULL); should be unreffed using g_variant_unref() when no longer needed a valid #GValue of type %G_TYPE_VARIANT Determines if @value will fit inside the size of a pointer value. This is an internal function introduced mainly for C marshallers. true if @value will fit inside a pointer value; false otherwise an initialized [struct@GObject.Value] structure Get the contents of a %G_TYPE_BOOLEAN #GValue. boolean contents of @value a valid #GValue of type %G_TYPE_BOOLEAN Get the contents of a %G_TYPE_BOXED derived #GValue. boxed contents of @value a valid #GValue of %G_TYPE_BOXED derived type Do not use this function; it is broken on platforms where the %char type is unsigned, such as ARM and PowerPC. See g_value_get_schar(). Get the contents of a %G_TYPE_CHAR #GValue. This function's return type is broken, see g_value_get_schar() character contents of @value a valid #GValue of type %G_TYPE_CHAR Get the contents of a %G_TYPE_DOUBLE #GValue. double contents of @value a valid #GValue of type %G_TYPE_DOUBLE Get the contents of a %G_TYPE_ENUM #GValue. enum contents of @value a valid #GValue whose type is derived from %G_TYPE_ENUM Get the contents of a %G_TYPE_FLAGS #GValue. flags contents of @value a valid #GValue whose type is derived from %G_TYPE_FLAGS Get the contents of a %G_TYPE_FLOAT #GValue. float contents of @value a valid #GValue of type %G_TYPE_FLOAT Get the contents of a %G_TYPE_GTYPE #GValue. the #GType stored in @value a valid #GValue of type %G_TYPE_GTYPE Get the contents of a %G_TYPE_INT #GValue. integer contents of @value a valid #GValue of type %G_TYPE_INT Get the contents of a %G_TYPE_INT64 #GValue. 64bit integer contents of @value a valid #GValue of type %G_TYPE_INT64 Get the contents of a %G_TYPE_LONG #GValue. long integer contents of @value a valid #GValue of type %G_TYPE_LONG Get the contents of a %G_TYPE_OBJECT derived #GValue. object contents of @value a valid #GValue of %G_TYPE_OBJECT derived type Get the contents of a %G_TYPE_PARAM #GValue. #GParamSpec content of @value a valid #GValue whose type is derived from %G_TYPE_PARAM Get the contents of a pointer #GValue. pointer contents of @value a valid #GValue of %G_TYPE_POINTER Get the contents of a %G_TYPE_CHAR #GValue. signed 8 bit integer contents of @value a valid #GValue of type %G_TYPE_CHAR Get the contents of a %G_TYPE_STRING #GValue. string content of @value a valid #GValue of type %G_TYPE_STRING Get the contents of a %G_TYPE_UCHAR #GValue. unsigned character contents of @value a valid #GValue of type %G_TYPE_UCHAR Get the contents of a %G_TYPE_UINT #GValue. unsigned integer contents of @value a valid #GValue of type %G_TYPE_UINT Get the contents of a %G_TYPE_UINT64 #GValue. unsigned 64bit integer contents of @value a valid #GValue of type %G_TYPE_UINT64 Get the contents of a %G_TYPE_ULONG #GValue. unsigned long integer contents of @value a valid #GValue of type %G_TYPE_ULONG Get the contents of a variant #GValue. variant contents of @value (may be %NULL) a valid #GValue of type %G_TYPE_VARIANT Initializes @value to store values of the given @type, and sets its value to the default for @type. This must be called before any other methods on a [struct@GObject.Value], so the value knows what type it’s meant to store. ```c GValue value = G_VALUE_INIT; g_value_init (&value, SOME_G_TYPE); … g_value_unset (&value); ``` the [struct@GObject.Value] structure that has been passed in a zero-filled (cleared) [struct@GObject.Value] structure type the [struct@GObject.Value] should hold values of Initializes and sets @value from an instantiatable type. This calls the [callback@GObject.TypeValueCollectFunc] function for the type the [struct@GObject.Value] contains. Note: The @value will be initialised with the exact type of @instance. If you wish to set the @value’s type to a different [type@GObject.Type] (such as a parent class type), you need to manually call [method@GObject.Value.init] and [method@GObject.Value.set_instance]. a zero-filled (cleared) [struct@GObject.Value] structure the instance Returns the value contents as a pointer. This function asserts that [method@GObject.Value.fits_pointer] returned true for the passed in value. This is an internal function introduced mainly for C marshallers. the value contents as a pointer an initialized [struct@GObject.Value] structure Clears the current value in @value and resets it to the default value (as if the value had just been initialized using [method@GObject.Value.init]). the [struct@GObject.Value] structure that has been passed in an initialized [struct@GObject.Value] structure Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. a valid #GValue of type %G_TYPE_BOOLEAN boolean value to be set Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. a valid #GValue of %G_TYPE_BOXED derived type caller-owned boxed object to be duplicated for the #GValue This is an internal function introduced mainly for C marshallers. Use g_value_take_boxed() instead. a valid #GValue of %G_TYPE_BOXED derived type duplicated unowned boxed value to be set Set the contents of a %G_TYPE_CHAR #GValue to @v_char. This function's input type is broken, see g_value_set_schar() a valid #GValue of type %G_TYPE_CHAR character value to be set Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. a valid #GValue of type %G_TYPE_DOUBLE double value to be set Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. a valid #GValue whose type is derived from %G_TYPE_ENUM enum value to be set Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. a valid #GValue whose type is derived from %G_TYPE_FLAGS flags value to be set Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. a valid #GValue of type %G_TYPE_FLOAT float value to be set Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. a valid #GValue of type %G_TYPE_GTYPE #GType to be set Sets @value from an instantiatable type. This calls the [callback@GObject.TypeValueCollectFunc] function for the type the [struct@GObject.Value] contains. an initialized [struct@GObject.Value] structure the instance Set the contents of a %G_TYPE_INT #GValue to @v_int. a valid #GValue of type %G_TYPE_INT integer value to be set Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. a valid #GValue of type %G_TYPE_INT64 64bit integer value to be set Set the contents of a %G_TYPE_STRING #GValue to @v_string. The string is assumed to be static and interned (canonical, for example from g_intern_string()), and is thus not duplicated when setting the #GValue. a valid #GValue of type %G_TYPE_STRING static string to be set Set the contents of a %G_TYPE_LONG #GValue to @v_long. a valid #GValue of type %G_TYPE_LONG long integer value to be set Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. g_value_set_object() increases the reference count of @v_object (the #GValue holds a reference to @v_object). If you do not wish to increase the reference count of the object (i.e. you wish to pass your current reference to the #GValue because you no longer need it), use g_value_take_object() instead. It is important that your #GValue holds a reference to @v_object (either its own, or one it has taken) to ensure that the object won't be destroyed while the #GValue still exists). a valid #GValue of %G_TYPE_OBJECT derived type object value to be set This is an internal function introduced mainly for C marshallers. Use g_value_take_object() instead. a valid #GValue of %G_TYPE_OBJECT derived type object value to be set Set the contents of a %G_TYPE_PARAM #GValue to @param. a valid #GValue of type %G_TYPE_PARAM the #GParamSpec to be set This is an internal function introduced mainly for C marshallers. Use g_value_take_param() instead. a valid #GValue of type %G_TYPE_PARAM the #GParamSpec to be set Set the contents of a pointer #GValue to @v_pointer. a valid #GValue of %G_TYPE_POINTER pointer value to be set Set the contents of a %G_TYPE_CHAR #GValue to @v_char. a valid #GValue of type %G_TYPE_CHAR signed 8 bit integer to be set Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. The boxed value is assumed to be static, and is thus not duplicated when setting the #GValue. a valid #GValue of %G_TYPE_BOXED derived type static boxed value to be set Set the contents of a %G_TYPE_STRING #GValue to @v_string. The string is assumed to be static, and is thus not duplicated when setting the #GValue. If the the string is a canonical string, using g_value_set_interned_string() is more appropriate. a valid #GValue of type %G_TYPE_STRING static string to be set Set the contents of a %G_TYPE_STRING #GValue to a copy of @v_string. a valid #GValue of type %G_TYPE_STRING caller-owned string to be duplicated for the #GValue This is an internal function introduced mainly for C marshallers. Use g_value_take_string() instead. a valid #GValue of type %G_TYPE_STRING duplicated unowned string to be set Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. a valid #GValue of type %G_TYPE_UCHAR unsigned character value to be set Set the contents of a %G_TYPE_UINT #GValue to @v_uint. a valid #GValue of type %G_TYPE_UINT unsigned integer value to be set Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. a valid #GValue of type %G_TYPE_UINT64 unsigned 64bit integer value to be set Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. a valid #GValue of type %G_TYPE_ULONG unsigned long integer value to be set Set the contents of a variant #GValue to @variant. If the variant is floating, it is consumed. a valid #GValue of type %G_TYPE_VARIANT a #GVariant, or %NULL Steal ownership on contents of a %G_TYPE_STRING #GValue. As a result of this operation the value's contents will be reset to %NULL. The purpose of this call is to provide a way to avoid an extra copy when some object have been serialized into string through #GValue API. NOTE: for safety and compatibility purposes, if #GValue contains static string, or an interned one, this function will return a copy of the string. Otherwise the transfer notation would be ambiguous. string content of @value; Should be freed with g_free() when no longer needed. a valid #GValue of type %G_TYPE_STRING Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed and takes over the ownership of the caller’s reference to @v_boxed; the caller doesn’t have to unref it any more. a valid #GValue of %G_TYPE_BOXED derived type duplicated unowned boxed value to be set Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object and takes over the ownership of the caller’s reference to @v_object; the caller doesn’t have to unref it any more (i.e. the reference count of the object is not increased). If you want the #GValue to hold its own reference to @v_object, use g_value_set_object() instead. a valid #GValue of %G_TYPE_OBJECT derived type object value to be set Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes over the ownership of the caller’s reference to @param; the caller doesn’t have to unref it any more. a valid #GValue of type %G_TYPE_PARAM the #GParamSpec to be set Sets the contents of a %G_TYPE_STRING #GValue to @v_string. a valid #GValue of type %G_TYPE_STRING string to take ownership of Set the contents of a variant #GValue to @variant, and takes over the ownership of the caller's reference to @variant; the caller doesn't have to unref it any more (i.e. the reference count of the variant is not increased). If @variant was floating then its floating reference is converted to a hard reference. If you want the #GValue to hold its own reference to @variant, use g_value_set_variant() instead. This is an internal function introduced mainly for C marshallers. a valid #GValue of type %G_TYPE_VARIANT a #GVariant, or %NULL Tries to cast the contents of @src_value into a type appropriate to store in @dest_value. If a transformation is not possible, @dest_value is not modified. For example, this could transform a `G_TYPE_INT` value into a `G_TYPE_FLOAT` value. Performing transformations between value types might incur precision loss. Especially transformations into strings might reveal seemingly arbitrary results and the format of particular transformations to strings is not guaranteed over time. true on success; false otherwise source value target value Clears the current value in @value (if any) and ‘unsets’ the type. This releases all resources associated with this [struct@GObject.Value]. An unset value is the same as a cleared (zero-filled) [struct@GObject.Value] structure set to `G_VALUE_INIT`. an initialized [struct@GObject.Value] structure Registers a value transformation function for use in [method@GObject.Value.transform]. Any previously registered transformation function for @src_type and @dest_type will be replaced. source type target type a function which transforms values of type @src_type into values of type @dest_type Checks whether a [method@GObject.Value.copy] is able to copy values of type @src_type into values of type @dest_type. true if the copy is possible; false otherwise source type to be copied destination type for copying Checks whether [method@GObject.Value.transform] is able to transform values of type @src_type into values of type @dest_type. Note that for the types to be transformable, they must be compatible or a transformation function must be registered using [func@GObject.Value.register_transform_func]. true if the transformation is possible; false otherwise source type target type A `GValueArray` is a container structure to hold an array of generic values. The prime purpose of a `GValueArray` is for it to be used as an object property that holds an array of values. A `GValueArray` wraps an array of `GValue` elements in order for it to be used as a boxed type through `G_TYPE_VALUE_ARRAY`. `GValueArray` is deprecated in favour of `GArray` since GLib 2.32. It is possible to create a `GArray` that behaves like a `GValueArray` by using the size of `GValue` as the element size, and by setting [method@GObject.Value.unset] as the clear function using [func@GLib.Array.set_clear_func], for instance, the following code: ```c GValueArray *array = g_value_array_new (10); ``` can be replaced by: ```c GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10); g_array_set_clear_func (array, (GDestroyNotify) g_value_unset); ``` Use `GArray` instead, if possible for the given use case, as described above. number of values contained in the array array of values Allocate and initialize a new #GValueArray, optionally preserve space for @n_prealloced elements. New arrays always contain 0 elements, regardless of the value of @n_prealloced. Use #GArray and g_array_sized_new() instead. a newly allocated #GValueArray with 0 values number of values to preallocate space for Insert a copy of @value as last element of @value_array. If @value is %NULL, an uninitialized value is appended. Use #GArray and g_array_append_val() instead. the #GValueArray passed in as @value_array #GValueArray to add an element to #GValue to copy into #GValueArray, or %NULL Construct an exact copy of a #GValueArray by duplicating all its contents. Use #GArray and g_array_ref() instead. Newly allocated copy of #GValueArray #GValueArray to copy Free a #GValueArray including its contents. Use #GArray and g_array_unref() instead. #GValueArray to free Return a pointer to the value at @index_ contained in @value_array. Use g_array_index() instead. pointer to a value at @index_ in @value_array #GValueArray to get a value from index of the value of interest Insert a copy of @value at specified position into @value_array. If @value is %NULL, an uninitialized value is inserted. Use #GArray and g_array_insert_val() instead. the #GValueArray passed in as @value_array #GValueArray to add an element to insertion position, must be <= value_array->;n_values #GValue to copy into #GValueArray, or %NULL Insert a copy of @value as first element of @value_array. If @value is %NULL, an uninitialized value is prepended. Use #GArray and g_array_prepend_val() instead. the #GValueArray passed in as @value_array #GValueArray to add an element to #GValue to copy into #GValueArray, or %NULL Remove the value at position @index_ from @value_array. Use #GArray and g_array_remove_index() instead. the #GValueArray passed in as @value_array #GValueArray to remove an element from position of value to remove, which must be less than @value_array->n_values Sort @value_array using @compare_func to compare the elements according to the semantics of #GCompareFunc. The current implementation uses the same sorting algorithm as standard C qsort() function. Use #GArray and g_array_sort(). the #GValueArray passed in as @value_array #GValueArray to sort function to compare elements Sort @value_array using @compare_func to compare the elements according to the semantics of #GCompareDataFunc. The current implementation uses the same sorting algorithm as standard C qsort() function. Use #GArray and g_array_sort_with_data(). the #GValueArray passed in as @value_array #GValueArray to sort function to compare elements extra data argument provided for @compare_func The type of value transformation functions which can be registered with [func@GObject.Value.register_transform_func]. @dest_value will be initialized to the correct destination type. source value target value A #GWeakNotify function can be added to an object as a callback that gets triggered when the object is finalized. Since the object is already being disposed when the #GWeakNotify is called, there's not much you could do with the object, apart from e.g. using its address as hash-index or the like. In particular, this means it’s invalid to call g_object_ref(), g_weak_ref_init(), g_weak_ref_set(), g_object_add_toggle_ref(), g_object_weak_ref(), g_object_add_weak_pointer() or any function which calls them on the object from this callback. data that was provided when the weak reference was established the object being disposed A structure containing a weak reference to a #GObject. A `GWeakRef` can either be empty (i.e. point to %NULL), or point to an object for as long as at least one "strong" reference to that object exists. Before the object's #GObjectClass.dispose method is called, every #GWeakRef associated with becomes empty (i.e. points to %NULL). Like #GValue, #GWeakRef can be statically allocated, stack- or heap-allocated, or embedded in larger structures. Unlike g_object_weak_ref() and g_object_add_weak_pointer(), this weak reference is thread-safe: converting a weak pointer to a reference is atomic with respect to invalidation of weak pointers to destroyed objects. If the object's #GObjectClass.dispose method results in additional references to the object being held (‘re-referencing’), any #GWeakRefs taken before it was disposed will continue to point to %NULL. Any #GWeakRefs taken during disposal and after re-referencing, or after disposal has returned due to the re-referencing, will continue to point to the object until its refcount goes back to zero, at which point they too will be invalidated. It is invalid to take a #GWeakRef on an object during #GObjectClass.dispose without first having or creating a strong reference to the object. Frees resources associated with a non-statically-allocated #GWeakRef. After this call, the #GWeakRef is left in an undefined state. You should only call this on a #GWeakRef that previously had g_weak_ref_init() called on it. location of a weak reference, which may be empty If @weak_ref is not empty, atomically acquire a strong reference to the object it points to, and return that reference. This function is needed because of the potential race between taking the pointer value and g_object_ref() on it, if the object was losing its last reference at the same time in a different thread. The caller should release the resulting reference in the usual way, by using g_object_unref(). the object pointed to by @weak_ref, or %NULL if it was empty location of a weak reference to a #GObject Initialise a non-statically-allocated #GWeakRef. This function also calls g_weak_ref_set() with @object on the freshly-initialised weak reference. This function should always be matched with a call to g_weak_ref_clear(). It is not necessary to use this function for a #GWeakRef in static storage because it will already be properly initialised. Just use g_weak_ref_set() directly. uninitialized or empty location for a weak reference a #GObject or %NULL Change the object to which @weak_ref points, or set it to %NULL. You must own a strong reference on @object while calling this function. location for a weak reference a #GObject or %NULL Assert that @object is non-%NULL, then release one reference to it with g_object_unref() and assert that it has been finalized (i.e. that there are no more references). If assertions are disabled via `G_DISABLE_ASSERT`, this macro just calls g_object_unref() without any further checks. This macro should only be used in regression tests. an object Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. The newly created copy of the boxed structure. The type of @src_boxed. The boxed structure to be copied. Free the boxed structure @boxed which is of type @boxed_type. The type of @boxed. The boxed structure to be freed. This function creates a new %G_TYPE_BOXED derived type id for a new boxed type with name @name. Boxed type handling functions have to be provided to copy and free opaque boxed structures of this type. For the general case, it is recommended to use G_DEFINE_BOXED_TYPE() instead of calling g_boxed_type_register_static() directly. The macro will create the appropriate `*_get_type()` function for the boxed type. New %G_TYPE_BOXED derived type id for @name. Name of the new boxed type. Boxed structure copy function. Boxed structure free function. A #GClosureMarshal function for use with signals with handlers that take two boxed pointers as arguments and return a boolean. If you have such a signal, you will probably also need to use an accumulator, such as g_signal_accumulator_true_handled(). A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with handlers that take a flags type as an argument and return a boolean. If you have such a signal, you will probably also need to use an accumulator, such as g_signal_accumulator_true_handled(). A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with handlers that take a #GObject and a pointer and produce a string. It is highly unlikely that your signal handler fits this description. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with a single boolean argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with a single argument which is any boxed pointer type. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with a single character argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with one double-precision floating point argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with a single argument with an enumerated type. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with a single argument with a flags types. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with one single-precision floating point argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with a single integer argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with with a single long integer argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with a single #GObject argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with a single argument of type #GParamSpec. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with a single raw pointer argument type. If it is possible, it is better to use one of the more specific functions such as g_cclosure_marshal_VOID__OBJECT() or g_cclosure_marshal_VOID__OBJECT(). A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with a single string argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with a single unsigned character argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with with a single unsigned integer argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with an unsigned int and a pointer as arguments. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with a single unsigned long integer argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with a single #GVariant argument. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A #GClosureMarshal function for use with signals with no arguments. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A generic marshaller function implemented via [libffi](http://sourceware.org/libffi/). Normally this function is not passed explicitly to g_signal_new(), but used automatically by GLib when specifying a %NULL marshaller. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() Creates a new closure which invokes @callback_func with @user_data as the last parameter. @destroy_data will be called as a finalize notifier on the #GClosure. a floating reference to a new #GCClosure the function to invoke user data to pass to @callback_func destroy notify to be called when @user_data is no longer used A variant of g_cclosure_new() which uses @object as @user_data and calls g_object_watch_closure() on @object and the created closure. This function is useful when you have a callback closely associated with a #GObject, and want the callback to no longer run after the object is is freed. a new #GCClosure the function to invoke a #GObject pointer to pass to @callback_func A variant of g_cclosure_new_swap() which uses @object as @user_data and calls g_object_watch_closure() on @object and the created closure. This function is useful when you have a callback closely associated with a #GObject, and want the callback to no longer run after the object is is freed. a new #GCClosure the function to invoke a #GObject pointer to pass to @callback_func Creates a new closure which invokes @callback_func with @user_data as the first parameter. @destroy_data will be called as a finalize notifier on the #GClosure. a floating reference to a new #GCClosure the function to invoke user data to pass to @callback_func destroy notify to be called when @user_data is no longer used Clears a reference to a #GObject. @object_ptr must not be %NULL. If the reference is %NULL then this function does nothing. Otherwise, the reference count of the object is decreased and the pointer is set to %NULL. A macro is also included that allows this function to be used without pointer casts. a pointer to a #GObject reference Disconnects a handler from @instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to. The @handler_id_ptr is then set to zero, which is never a valid handler ID value (see g_signal_connect()). If the handler ID is 0 then this function does nothing. There is also a macro version of this function so that the code will be inlined. A pointer to a handler ID (of type #gulong) of the handler to be disconnected. The instance to remove the signal handler from. This pointer may be %NULL or invalid, if the handler ID is zero. Clears a weak reference to a #GObject. @weak_pointer_location must not be %NULL. If the weak reference is %NULL then this function does nothing. Otherwise, the weak reference to the object is removed for that location and the pointer is set to %NULL. A macro is also included that allows this function to be used without pointer casts. The function itself is static inline, so its address may vary between compilation units. The memory address of a pointer This function is meant to be called from the `complete_type_info` function of a #GTypePlugin implementation, as in the following example: |[<!-- language="C" --> static void my_enum_complete_type_info (GTypePlugin *plugin, GType g_type, GTypeInfo *info, GTypeValueTable *value_table) { static const GEnumValue values[] = { { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" }, { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" }, { 0, NULL, NULL } }; g_enum_complete_type_info (type, info, values); } ]| the type identifier of the type being completed the #GTypeInfo struct to be filled in An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. Returns the #GEnumValue for a value. the #GEnumValue for @value, or %NULL if @value is not a member of the enumeration a #GEnumClass the value to look up Looks up a #GEnumValue by name. the #GEnumValue with name @name, or %NULL if the enumeration doesn't have a member with that name a #GEnumClass the name to look up Looks up a #GEnumValue by nickname. the #GEnumValue with nickname @nick, or %NULL if the enumeration doesn't have a member with that nickname a #GEnumClass the nickname to look up Registers a new static enumeration type with the name @name. It is normally more convenient to let [glib-mkenums][glib-mkenums], generate a my_enum_get_type() function from a usual C enumeration definition than to write one yourself using g_enum_register_static(). The new type identifier. A nul-terminated string used as the name of the new type. An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. Pretty-prints @value in the form of the enum’s name. This is intended to be used for debugging purposes. The format of the output may change in the future. a newly-allocated text string the type identifier of a #GEnumClass type the value This function is meant to be called from the complete_type_info() function of a #GTypePlugin implementation, see the example for g_enum_complete_type_info() above. the type identifier of the type being completed the #GTypeInfo struct to be filled in An array of #GFlagsValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. Returns the first #GFlagsValue which is set in @value. the first #GFlagsValue which is set in @value, or %NULL if none is set a #GFlagsClass the value Looks up a #GFlagsValue by name. the #GFlagsValue with name @name, or %NULL if there is no flag with that name a #GFlagsClass the name to look up Looks up a #GFlagsValue by nickname. the #GFlagsValue with nickname @nick, or %NULL if there is no flag with that nickname a #GFlagsClass the nickname to look up Registers a new static flags type with the name @name. It is normally more convenient to let [glib-mkenums][glib-mkenums] generate a my_flags_get_type() function from a usual C enumeration definition than to write one yourself using g_flags_register_static(). The new type identifier. A nul-terminated string used as the name of the new type. An array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. Pretty-prints @value in the form of the flag names separated by ` | ` and sorted. Any extra bits will be shown at the end as a hexadecimal number. This is intended to be used for debugging purposes. The format of the output may change in the future. a newly-allocated text string the type identifier of a #GFlagsClass type the value Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN property. In many cases, it may be more appropriate to use an enum with g_param_spec_enum(), both to improve code clarity by using explicitly named values, and to allow for more values to be added in future without breaking API. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED derived property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified %G_TYPE_BOXED derived type of this property flags for the property specified Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified a #GType derived from %G_TYPE_ENUM default value for the property specified flags for the property specified Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified a #GType derived from %G_TYPE_FLAGS default value for the property specified flags for the property specified Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecGType instance specifying a %G_TYPE_GTYPE property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified a #GType whose subtypes are allowed as values of the property (use %G_TYPE_NONE for any type) flags for the property specified Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT derived property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified %G_TYPE_OBJECT derived type of this property flags for the property specified Creates a new property of type #GParamSpecOverride. This is used to direct operations to another paramspec, and will not be directly useful unless you are implementing a new base type similar to GObject. the newly created #GParamSpec the name of the property. The property that is being overridden Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified a #GType derived from %G_TYPE_PARAM flags for the property specified Creates a new #GParamSpecPointer instance specifying a pointer property. Where possible, it is better to use g_param_spec_object() or g_param_spec_boxed() to expose memory management information. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified flags for the property specified Creates a new #GParamSpecString instance. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT property. #GValue structures for this property can be accessed with g_value_set_uint() and g_value_get_uint(). See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecValueArray instance specifying a %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a %G_TYPE_BOXED type, as such, #GValue structures for this property can be accessed with g_value_set_boxed() and g_value_get_boxed(). See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified a #GParamSpec describing the elements contained in arrays of this property, may be %NULL flags for the property specified Creates a new #GParamSpecVariant instance specifying a #GVariant property. If @default_value is floating, it is consumed. See g_param_spec_internal() for details on property names. the newly created #GParamSpec canonical name of the property specified nick name for the property specified description of the property specified a #GVariantType a #GVariant of type @type to use as the default value, or %NULL flags for the property specified Registers @name as the name of a new static type derived from %G_TYPE_PARAM. The type system uses the information contained in the #GParamSpecTypeInfo structure pointed to by @info to manage the #GParamSpec type and its instances. The new type identifier. 0-terminated string used as the name of the new #GParamSpec type. The #GParamSpecTypeInfo for this #GParamSpec type. Transforms @src_value into @dest_value if possible, and then validates @dest_value, in order for it to conform to @pspec. If @strict_validation is %TRUE this function will only succeed if the transformed @dest_value complied to @pspec without modifications. See also g_value_type_transformable(), g_value_transform() and g_param_value_validate(). %TRUE if transformation and validation were successful, %FALSE otherwise and @dest_value is left untouched. a valid #GParamSpec source #GValue destination #GValue of correct type for @pspec %TRUE requires @dest_value to conform to @pspec without modifications Checks whether @value contains the default value as specified in @pspec. whether @value contains the canonical default for this @pspec a valid #GParamSpec a #GValue of correct type for @pspec Return whether the contents of @value comply with the specifications set out by @pspec. whether the contents of @value comply with the specifications set out by @pspec. a valid #GParamSpec a #GValue of correct type for @pspec Sets @value to its default value as specified in @pspec. a valid #GParamSpec a #GValue of correct type for @pspec; since 2.64, you can also pass an empty #GValue, initialized with %G_VALUE_INIT Ensures that the contents of @value comply with the specifications set out by @pspec. For example, a #GParamSpecInt might require that integers stored in @value may not be smaller than -42 and not be greater than +42. If @value contains an integer outside of this range, it is modified accordingly, so the resulting value will fit into the range -42 .. +42. whether modifying @value was necessary to ensure validity a valid #GParamSpec a #GValue of correct type for @pspec Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, if @value1 is found to be less than, equal to or greater than @value2, respectively. -1, 0 or +1, for a less than, equal to or greater than result a valid #GParamSpec a #GValue of correct type for @pspec a #GValue of correct type for @pspec Creates a new %G_TYPE_POINTER derived type id for a new pointer type with name @name. a new %G_TYPE_POINTER derived type id for @name. the name of the new pointer type. Updates a #GObject pointer to refer to @new_object. It increments the reference count of @new_object (if non-%NULL), decrements the reference count of the current value of @object_ptr (if non-%NULL), and assigns @new_object to @object_ptr. The assignment is not atomic. @object_ptr must not be %NULL, but can point to a %NULL value. A macro is also included that allows this function to be used without pointer casts. The function itself is static inline, so its address may vary between compilation units. One convenient usage of this function is in implementing property setters: |[ void foo_set_bar (Foo *foo, Bar *new_bar) { g_return_if_fail (IS_FOO (foo)); g_return_if_fail (new_bar == NULL || IS_BAR (new_bar)); if (g_set_object (&foo->bar, new_bar)) g_object_notify (foo, "bar"); } ]| a pointer to a #GObject reference a pointer to the new #GObject to assign to @object_ptr, or %NULL to clear the pointer Updates a pointer to weakly refer to @new_object. It assigns @new_object to @weak_pointer_location and ensures that @weak_pointer_location will automatically be set to %NULL if @new_object gets destroyed. The assignment is not atomic. The weak reference is not thread-safe, see g_object_add_weak_pointer() for details. The @weak_pointer_location argument must not be %NULL. A macro is also included that allows this function to be used without pointer casts. The function itself is static inline, so its address may vary between compilation units. One convenient usage of this function is in implementing property setters: |[ void foo_set_bar (Foo *foo, Bar *new_bar) { g_return_if_fail (IS_FOO (foo)); g_return_if_fail (new_bar == NULL || IS_BAR (new_bar)); if (g_set_weak_pointer (&foo->bar, new_bar)) g_object_notify (foo, "bar"); } ]| the memory address of a pointer a pointer to the new #GObject to assign to it, or %NULL to clear the pointer A predefined #GSignalAccumulator for signals intended to be used as a hook for application code to provide a particular value. Usually only one such value is desired and multiple handlers for the same signal don't make much sense (except for the case of the default handler defined in the class structure, in which case you will usually want the signal connection to override the class handler). This accumulator will use the return value from the first signal handler that is run as the return value for the signal and not run any further handlers (ie: the first handler "wins"). standard #GSignalAccumulator result standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter A predefined #GSignalAccumulator for signals that return a boolean values. The behavior that this accumulator gives is that a return of %TRUE stops the signal emission: no further callbacks will be invoked, while a return of %FALSE allows the emission to continue. The idea here is that a %TRUE return indicates that the callback handled the signal, and no further handling is needed. standard #GSignalAccumulator result standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter Adds an emission hook for a signal, which will get called for any emission of that signal, independent of the instance. This is possible only for signals which don't have %G_SIGNAL_NO_HOOKS flag set. the hook id, for later use with g_signal_remove_emission_hook(). the signal identifier, as returned by g_signal_lookup(). the detail on which to call the hook. a #GSignalEmissionHook function. user data for @hook_func. a #GDestroyNotify for @hook_data. Calls the original class closure of a signal. This function should only be called from an overridden class closure; see g_signal_override_class_closure() and g_signal_override_class_handler(). the argument list of the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. Location for the return value. Calls the original class closure of a signal. This function should only be called from an overridden class closure; see g_signal_override_class_closure() and g_signal_override_class_handler(). the instance the signal is being emitted on. parameters to be passed to the parent class closure, followed by a location for the return value. If the return type of the signal is %G_TYPE_NONE, the return value location can be omitted. Connects a [type@GObject.Callback] function to a signal for a particular object. The handler will be called synchronously, before the default handler of the signal. [func@GObject.signal_emit] will not return control until all handlers are called. See [memory management of signal handlers](signals.html#memory-management-of-signal-handlers) for details on how to handle the return value and memory management of @data. This function cannot fail. If the given signal name doesn’t exist, a critical warning is emitted. No validation is performed on the ‘detail’ string when specified in @detailed_signal, other than a non-empty check. Refer to the [signals documentation](signals.html) for more details. the instance to connect to. a string of the form "signal-name::detail". the #GCallback to connect. data to pass to @c_handler calls. Connects a #GCallback function to a signal for a particular object. The handler will be called synchronously, after the default handler of the signal. This function cannot fail. If the given signal name doesn’t exist, a critical warning is emitted. No validation is performed on the ‘detail’ string when specified in @detailed_signal, other than a non-empty check. Refer to the [signals documentation](signals.html) for more details. the instance to connect to. a string of the form "signal-name::detail". the #GCallback to connect. data to pass to @c_handler calls. Connects a closure to a signal for a particular object. If @closure is a floating reference (see g_closure_sink()), this function takes ownership of @closure. This function cannot fail. If the given signal name doesn’t exist, a critical warning is emitted. No validation is performed on the ‘detail’ string when specified in @detailed_signal, other than a non-empty check. Refer to the [signals documentation](signals.html) for more details. the handler ID (always greater than 0) the instance to connect to. a string of the form "signal-name::detail". the closure to connect. whether the handler should be called before or after the default handler of the signal. Connects a closure to a signal for a particular object. If @closure is a floating reference (see g_closure_sink()), this function takes ownership of @closure. This function cannot fail. If the given signal name doesn’t exist, a critical warning is emitted. No validation is performed on the ‘detail’ string when specified in @detailed_signal, other than a non-empty check. Refer to the [signals documentation](signals.html) for more details. the handler ID (always greater than 0) the instance to connect to. the id of the signal. the detail. the closure to connect. whether the handler should be called before or after the default handler of the signal. Connects a #GCallback function to a signal for a particular object. Similar to g_signal_connect(), but allows to provide a #GClosureNotify for the data which will be called when the signal handler is disconnected and no longer used. Specify @connect_flags if you need `..._after()` or `..._swapped()` variants of this function. This function cannot fail. If the given signal name doesn’t exist, a critical warning is emitted. No validation is performed on the ‘detail’ string when specified in @detailed_signal, other than a non-empty check. Refer to the [signals documentation](signals.html) for more details. the handler ID (always greater than 0) the instance to connect to. a string of the form "signal-name::detail". the #GCallback to connect. data to pass to @c_handler calls. a #GClosureNotify for @data. a combination of #GConnectFlags. This is similar to g_signal_connect_data(), but uses a closure which ensures that the @gobject stays alive during the call to @c_handler by temporarily adding a reference count to @gobject. When the @gobject is destroyed the signal handler will be automatically disconnected. Note that this is not currently threadsafe (ie: emitting a signal while @gobject is being destroyed in another thread is not safe). This function cannot fail. If the given signal name doesn’t exist, a critical warning is emitted. No validation is performed on the "detail" string when specified in @detailed_signal, other than a non-empty check. Refer to the [signals documentation](signals.html) for more details. the handler id. the instance to connect to. a string of the form "signal-name::detail". the #GCallback to connect. the object to pass as data to @c_handler. a combination of #GConnectFlags. Connects a #GCallback function to a signal for a particular object. The instance on which the signal is emitted and @data will be swapped when calling the handler. This is useful when calling pre-existing functions to operate purely on the @data, rather than the @instance: swapping the parameters avoids the need to write a wrapper function. For example, this allows the shorter code: |[<!-- language="C" --> g_signal_connect_swapped (button, "clicked", (GCallback) gtk_widget_hide, other_widget); ]| Rather than the cumbersome: |[<!-- language="C" --> static void button_clicked_cb (GtkButton *button, GtkWidget *other_widget) { gtk_widget_hide (other_widget); } ... g_signal_connect (button, "clicked", (GCallback) button_clicked_cb, other_widget); ]| This function cannot fail. If the given signal name doesn’t exist, a critical warning is emitted. No validation is performed on the ‘detail’ string when specified in @detailed_signal, other than a non-empty check. Refer to the [signals documentation](signals.html) for more details. the instance to connect to. a string of the form "signal-name::detail". the #GCallback to connect. data to pass to @c_handler calls. Emits a signal. Signal emission is done synchronously. The method will only return control after all handlers are called or signal emission was stopped. Note that g_signal_emit() resets the return value to the default if no handlers are connected, in contrast to g_signal_emitv(). the instance the signal is being emitted on. the signal id the detail parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is %G_TYPE_NONE, the return value location can be omitted. Emits a signal. Signal emission is done synchronously. The method will only return control after all handlers are called or signal emission was stopped. Note that g_signal_emit_by_name() resets the return value to the default if no handlers are connected, in contrast to g_signal_emitv(). the instance the signal is being emitted on. a string of the form "signal-name::detail". parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is %G_TYPE_NONE, the return value location can be omitted. The number of parameters to pass to this function is defined when creating the signal. Emits a signal. Signal emission is done synchronously. The method will only return control after all handlers are called or signal emission was stopped. Note that g_signal_emit_valist() resets the return value to the default if no handlers are connected, in contrast to g_signal_emitv(). the instance the signal is being emitted on. the signal id the detail a list of parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is %G_TYPE_NONE, the return value location can be omitted. Emits a signal. Signal emission is done synchronously. The method will only return control after all handlers are called or signal emission was stopped. Note that g_signal_emitv() doesn't change @return_value if no handlers are connected, in contrast to g_signal_emit() and g_signal_emit_valist(). argument list for the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. the signal id the detail Location to store the return value of the signal emission. This must be provided if the specified signal returns a value, but may be ignored otherwise. Returns the invocation hint of the innermost signal emission of instance. the invocation hint of the innermost signal emission, or %NULL if not found. the instance to query Blocks a handler of an instance so it will not be called during any signal emissions unless it is unblocked again. Thus "blocking" a signal handler means to temporarily deactivate it, a signal handler has to be unblocked exactly the same amount of times it has been blocked before to become active again. The @handler_id has to be a valid signal handler id, connected to a signal of @instance. The instance to block the signal handler of. Handler id of the handler to be blocked. Disconnects a handler from an instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to. The @handler_id becomes invalid and may be reused. The @handler_id has to be a valid signal handler id, connected to a signal of @instance. The instance to remove the signal handler from. Handler id of the handler to be disconnected. Finds the first signal handler that matches certain selection criteria. The criteria mask is passed as an OR-ed combination of #GSignalMatchType flags, and the criteria values are passed as arguments. The match @mask has to be non-0 for successful matches. If no handler was found, 0 is returned. A valid non-0 signal handler id for a successful match. The instance owning the signal handler to be found. Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handler has to match. Signal the handler has to be connected to. Signal detail the handler has to be connected to. The closure the handler will invoke. The C closure callback of the handler (useless for non-C closures). The closure data of the handler's closure. Returns whether @handler_id is the ID of a handler connected to @instance. whether @handler_id identifies a handler connected to @instance. The instance where a signal handler is sought. the handler ID. Undoes the effect of a previous g_signal_handler_block() call. A blocked handler is skipped during signal emissions and will not be invoked, unblocking it (for exactly the amount of times it has been blocked before) reverts its "blocked" state, so the handler will be recognized by the signal system and is called upon future or currently ongoing signal emissions (since the order in which handlers are called during signal emissions is deterministic, whether the unblocked handler in question is called as part of a currently ongoing emission depends on how far that emission has proceeded yet). The @handler_id has to be a valid id of a signal handler that is connected to a signal of @instance and is currently blocked. The instance to unblock the signal handler of. Handler id of the handler to be unblocked. Blocks all handlers on an instance that match @func and @data. The instance to block handlers from. The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. Blocks all handlers on an instance that match a certain selection criteria. The criteria mask is passed as a combination of #GSignalMatchType flags, and the criteria values are passed as arguments. A handler must match on all flags set in @mask to be blocked (i.e. the match is conjunctive). Passing at least one of the %G_SIGNAL_MATCH_ID, %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. If no handlers were found, 0 is returned, the number of blocked handlers otherwise. Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78. The number of handlers that matched. The instance to block handlers from. Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. Signal the handlers have to be connected to. Signal detail the handlers have to be connected to. The closure the handlers will invoke. The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. Destroy all signal handlers of a type instance. This function is an implementation detail of the #GObject dispose implementation, and should not be used outside of the type system. The instance whose signal handlers are destroyed Disconnects all handlers on an instance that match @data. The instance to remove handlers from the closure data of the handlers' closures Disconnects all handlers on an instance that match @func and @data. The instance to remove handlers from. The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. Disconnects all handlers on an instance that match a certain selection criteria. The criteria mask is passed as a combination of #GSignalMatchType flags, and the criteria values are passed as arguments. A handler must match on all flags set in @mask to be disconnected (i.e. the match is conjunctive). Passing at least one of the %G_SIGNAL_MATCH_ID, %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. If no handlers were found, 0 is returned, the number of disconnected handlers otherwise. Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78. The number of handlers that matched. The instance to remove handlers from. Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. Signal the handlers have to be connected to. Signal detail the handlers have to be connected to. The closure the handlers will invoke. The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. Unblocks all handlers on an instance that match @func and @data. The instance to unblock handlers from. The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. Unblocks all handlers on an instance that match a certain selection criteria. The criteria mask is passed as a combination of #GSignalMatchType flags, and the criteria values are passed as arguments. A handler must match on all flags set in @mask to be unblocked (i.e. the match is conjunctive). Passing at least one of the %G_SIGNAL_MATCH_ID, %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. If no handlers were found, 0 is returned, the number of unblocked handlers otherwise. The match criteria should not apply to any handlers that are not currently blocked. Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78. The number of handlers that matched. The instance to unblock handlers from. Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. Signal the handlers have to be connected to. Signal detail the handlers have to be connected to. The closure the handlers will invoke. The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. Returns whether there are any handlers connected to @instance for the given signal id and detail. If @detail is 0 then it will only match handlers that were connected without detail. If @detail is non-zero then it will match handlers connected both without detail and with the given detail. This is consistent with how a signal emitted with @detail would be delivered to those handlers. Since 2.46 this also checks for a non-default class closure being installed, as this is basically always what you want. One example of when you might use this is when the arguments to the signal are difficult to compute. A class implementor may opt to not emit the signal if no one is attached anyway, thus saving the cost of building the arguments. %TRUE if a handler is connected to the signal, %FALSE otherwise. the object whose signal handlers are sought. the signal id. the detail. whether blocked handlers should count as match. Validate a signal name. This can be useful for dynamically-generated signals which need to be validated at run-time before actually trying to create them. See [func@GObject.signal_new] for details of the rules for valid names. The rules for signal names are the same as those for property names. %TRUE if @name is a valid signal name, %FALSE otherwise. the canonical name of the signal Lists the signals by id that a certain instance or interface type created. Further information about the signals can be acquired through g_signal_query(). Newly allocated array of signal IDs. Instance or interface type. Location to store the number of signal ids for @itype. Given the name of the signal and the type of object it connects to, gets the signal's identifying integer. Emitting the signal by number is somewhat faster than using the name each time. Also tries the ancestors of the given type. The type class passed as @itype must already have been instantiated (for example, using g_type_class_ref()) for this function to work, as signals are always installed during class initialization. See g_signal_new() for details on allowed signal names. the signal's identifying number, or 0 if no signal was found. the signal's name. the type that the signal operates on. Given the signal's identifier, finds its name. Two different signals may have the same name, if they have differing types. the signal name, or %NULL if the signal number was invalid. the signal's identifying number. Creates a new signal. (This is usually done in the class initializer.) A signal name consists of segments consisting of ASCII letters and digits, separated by either the `-` or `_` character. The first character of a signal name must be a letter. Names which violate these rules lead to undefined behaviour. These are the same rules as for property naming (see g_param_spec_internal()). When registering a signal and looking up a signal, either separator can be used, but they cannot be mixed. Using `-` is considerably more efficient. Using `_` is discouraged. If 0 is used for @class_offset subclasses cannot override the class handler in their class_init method by doing super_class->signal_handler = my_signal_handler. Instead they will have to use g_signal_override_class_handler(). If @c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as the marshaller for this signal. In some simple cases, g_signal_new() will use a more optimized c_marshaller and va_marshaller for the signal instead of g_cclosure_marshal_generic(). If @c_marshaller is non-%NULL, you need to also specify a va_marshaller using g_signal_set_va_marshaller() or the generic va_marshaller will be used. the signal id the name for the signal the type this signal pertains to. It will also pertain to types which are derived from this type. a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. The offset of the function pointer in the class structure for this type. Used to invoke a class method generically. Pass 0 to not associate a class method slot with this signal. the accumulator for this signal; may be %NULL. user data for the @accumulator. the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. the type of return value, or %G_TYPE_NONE for a signal without a return value. the number of parameter types to follow. a list of types, one for each parameter. Creates a new signal. (This is usually done in the class initializer.) This is a variant of g_signal_new() that takes a C callback instead of a class offset for the signal's class handler. This function doesn't need a function pointer exposed in the class structure of an object definition, instead the function pointer is passed directly and can be overridden by derived classes with g_signal_override_class_closure() or g_signal_override_class_handler() and chained to with g_signal_chain_from_overridden() or g_signal_chain_from_overridden_handler(). See g_signal_new() for information about signal names. If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as the marshaller for this signal. the signal id the name for the signal the type this signal pertains to. It will also pertain to types which are derived from this type. a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. a #GCallback which acts as class implementation of this signal. Used to invoke a class method generically. Pass %NULL to not associate a class method with this signal. the accumulator for this signal; may be %NULL. user data for the @accumulator. the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. the type of return value, or %G_TYPE_NONE for a signal without a return value. the number of parameter types to follow. a list of types, one for each parameter. Creates a new signal. (This is usually done in the class initializer.) See g_signal_new() for details on allowed signal names. If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as the marshaller for this signal. the signal id the name for the signal the type this signal pertains to. It will also pertain to types which are derived from this type. a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. The closure to invoke on signal emission; may be %NULL. the accumulator for this signal; may be %NULL. user data for the @accumulator. the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. the type of return value, or %G_TYPE_NONE for a signal without a return value. the number of parameter types in @args. va_list of #GType, one for each parameter. Creates a new signal. (This is usually done in the class initializer.) See g_signal_new() for details on allowed signal names. If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as the marshaller for this signal. the signal id the name for the signal the type this signal pertains to. It will also pertain to types which are derived from this type a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST The closure to invoke on signal emission; may be %NULL the accumulator for this signal; may be %NULL user data for the @accumulator the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL the type of return value, or %G_TYPE_NONE for a signal without a return value the length of @param_types an array of types, one for each parameter (may be %NULL if @n_params is zero) Overrides the class closure (i.e. the default handler) for the given signal for emissions on instances of @instance_type. @instance_type must be derived from the type to which the signal belongs. See g_signal_chain_from_overridden() and g_signal_chain_from_overridden_handler() for how to chain up to the parent class closure from inside the overridden one. the signal id the instance type on which to override the class closure for the signal. the closure. Overrides the class closure (i.e. the default handler) for the given signal for emissions on instances of @instance_type with callback @class_handler. @instance_type must be derived from the type to which the signal belongs. See g_signal_chain_from_overridden() and g_signal_chain_from_overridden_handler() for how to chain up to the parent class closure from inside the overridden one. the name for the signal the instance type on which to override the class handler for the signal. the handler. Internal function to parse a signal name into its @signal_id and @detail quark. Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. a string of the form "signal-name::detail". The interface/instance type that introduced "signal-name". Location to store the signal id. Location to store the detail quark. %TRUE forces creation of a #GQuark for the detail. Queries the signal system for in-depth information about a specific signal. This function will fill in a user-provided structure to hold signal-specific information. If an invalid signal id is passed in, the @signal_id member of the #GSignalQuery is 0. All members filled into the #GSignalQuery structure should be considered constant and have to be left untouched. The signal id of the signal to query information for. A user provided structure that is filled in with constant values upon success. Deletes an emission hook. the id of the signal the id of the emission hook, as returned by g_signal_add_emission_hook() Change the #GSignalCVaMarshaller used for a given signal. This is a specialised form of the marshaller that can often be used for the common case of a single connected signal handler and avoids the overhead of #GValue. Its use is optional. the signal id the instance type on which to set the marshaller. the marshaller to set. Stops a signal's current emission. This will prevent the default method from running, if the signal was %G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" flag). Prints a warning if used on a signal which isn't being emitted. the object whose signal handlers you wish to stop. the signal identifier, as returned by g_signal_lookup(). the detail which the signal was emitted with. Stops a signal's current emission. This is just like g_signal_stop_emission() except it will look up the signal id for you. the object whose signal handlers you wish to stop. a string of the form "signal-name::detail". Creates a new closure which invokes the function found at the offset @struct_offset in the class structure of the interface or classed type identified by @itype. a floating reference to a new #GCClosure the #GType identifier of an interface or classed type the offset of the member function of @itype's class structure which is to be invoked by the new closure Set the callback for a source as a #GClosure. If the source is not one of the standard GLib types, the @closure_callback and @closure_marshal fields of the #GSourceFuncs structure must have been filled in with pointers to appropriate functions. the source a #GClosure Sets a dummy callback for @source. The callback will do nothing, and if the source expects a #gboolean return value, it will return %TRUE. (If the source expects any other type of return value, it will return a 0/%NULL value; whatever g_value_init() initializes a #GValue to for that type.) If the source is not one of the standard GLib types, the @closure_callback and @closure_marshal fields of the #GSourceFuncs structure must have been filled in with pointers to appropriate functions. the source Return a newly allocated string, which describes the contents of a #GValue. The main purpose of this function is to describe #GValue contents for debugging output, the way in which the contents are described may change between different GLib versions. Newly allocated string. #GValue which contents are to be described. Adds a #GTypeClassCacheFunc to be called before the reference count of a class goes from one to zero. This can be used to prevent premature class destruction. All installed #GTypeClassCacheFunc functions will be chained until one of them returns %TRUE. The functions have to check the class id passed in to figure whether they actually want to cache the class of this type, since all classes are routed through the same #GTypeClassCacheFunc chain. data to be passed to @cache_func a #GTypeClassCacheFunc Registers a private class structure for a classed type; when the class is allocated, the private structures for the class and all of its parent types are allocated sequentially in the same memory block as the public structures, and are zero-filled. This function should be called in the type's get_type() function after the type is registered. The private structure can be retrieved using the G_TYPE_CLASS_GET_PRIVATE() macro. GType of a classed type size of private structure Adds a function to be called after an interface vtable is initialized for any class (i.e. after the @interface_init member of #GInterfaceInfo has been called). This function is useful when you want to check an invariant that depends on the interfaces of a class. For instance, the implementation of #GObject uses this facility to check that an object implements all of the properties that are defined on its interfaces. data to pass to @check_func function to be called after each interface is initialized Adds @interface_type to the dynamic @instance_type. The information contained in the #GTypePlugin structure pointed to by @plugin is used to manage the relationship. #GType value of an instantiatable type #GType value of an interface type #GTypePlugin structure to retrieve the #GInterfaceInfo from Adds @interface_type to the static @instance_type. The information contained in the #GInterfaceInfo structure pointed to by @info is used to manage the relationship. #GType value of an instantiatable type #GType value of an interface type #GInterfaceInfo structure for this (@instance_type, @interface_type) combination Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE() macro. %TRUE if @instance is valid, %FALSE otherwise a valid #GTypeInstance structure Return a newly allocated and 0-terminated array of type IDs, listing the child types of @type. Newly allocated and 0-terminated array of child types, free with g_free() the parent type location to store the length of the returned array, or %NULL Retrieves the type class of the given @type. This function will create the class on demand if it does not exist already. If you don't want to create the class, use g_type_class_peek() instead. the class structure for the type type ID of a classed type Retrieves the class for a give type. This function is essentially the same as g_type_class_get(), except that the class may have not been instantiated yet. As a consequence, this function may return %NULL if the class of the type passed in does not currently exist (hasn't been referenced before). the #GTypeClass structure for the given type ID or %NULL if the class does not currently exist type ID of a classed type A more efficient version of g_type_class_peek() which works only for static types. the #GTypeClass structure for the given type ID or %NULL if the class does not currently exist or is dynamically loaded type ID of a classed type Increments the reference count of the class structure belonging to @type. This function will demand-create the class if it doesn't exist already. Use g_type_class_get() instead the #GTypeClass structure for the given type ID type ID of a classed type Creates and initializes an instance of @type if @type is valid and can be instantiated. The type system only performs basic allocation and structure setups for instances: actual instance creation should happen through functions supplied by the type's fundamental type implementation. So use of g_type_create_instance() is reserved for implementers of fundamental types only. E.g. instances of the #GObject hierarchy should be created via g_object_new() and never directly through g_type_create_instance() which doesn't handle things like singleton objects or object construction. The extended members of the returned instance are guaranteed to be filled with zeros. Note: Do not use this function, unless you're implementing a fundamental type. Also language bindings should not use this function, but g_object_new() instead. an allocated and initialized instance, subject to further treatment by the fundamental type implementation an instantiatable type to create an instance for Returns the default interface vtable for the given @g_type. If the type is not currently in use, then the default vtable for the type will be created and initialized by calling the base interface init and default vtable init functions for the type (the @base_init and @class_init members of #GTypeInfo). If you don't want to create the interface vtable, you should use g_type_default_interface_peek() instead. Calling g_type_default_interface_get() is useful when you want to make sure that signals and properties for an interface have been installed. the default vtable for the interface. an interface type If the interface type @g_type is currently in use, returns its default interface vtable. the default vtable for the interface, or %NULL if the type is not currently in use an interface type Increments the reference count for the interface type @g_type, and returns the default interface vtable for the type. If the type is not currently in use, then the default vtable for the type will be created and initialized by calling the base interface init and default vtable init functions for the type (the @base_init and @class_init members of #GTypeInfo). Calling g_type_default_interface_ref() is useful when you want to make sure that signals and properties for an interface have been installed. Use g_type_default_interface_get() instead the default vtable for the interface; call g_type_default_interface_unref() when you are done using the interface. an interface type Decrements the reference count for the type corresponding to the interface default vtable @g_iface. If the type is dynamic, then when no one is using the interface and all references have been released, the finalize function for the interface's default vtable (the @class_finalize member of #GTypeInfo) will be called. Interface reference counting has been removed and interface types now cannot be finalized. This function no longer does anything. the default vtable structure for an interface, as returned by g_type_default_interface_ref() Returns the length of the ancestry of the passed in type. This includes the type itself, so that e.g. a fundamental type has depth 1. the depth of @type a #GType Ensures that the indicated @type has been registered with the type system, and its _class_init() method has been run. In theory, simply calling the type's _get_type() method (or using the corresponding macro) is supposed take care of this. However, _get_type() methods are often marked %G_GNUC_CONST for performance reasons, even though this is technically incorrect (since %G_GNUC_CONST requires that the function not have side effects, which _get_type() methods do on the first call). As a result, if you write a bare call to a _get_type() macro, it may get optimized out by the compiler. Using g_type_ensure() guarantees that the type's _get_type() method is called. a #GType Frees an instance of a type, returning it to the instance pool for the type, if there is one. Like g_type_create_instance(), this function is reserved for implementors of fundamental types. an instance of a type Look up the type ID from a given type name, returning 0 if no type has been registered under this name (this is the preferred method to find out by name whether a specific type has been registered yet). corresponding type ID or 0 type name to look up Internal function, used to extract the fundamental type ID portion. Use G_TYPE_FUNDAMENTAL() instead. fundamental type ID valid type ID Returns the next free fundamental type id which can be used to register a new fundamental type with g_type_register_fundamental(). The returned type ID represents the highest currently registered fundamental type identifier. the next available fundamental type ID to be registered, or 0 if the type system ran out of fundamental type IDs Returns the number of instances allocated of the particular type; this is only available if GLib is built with debugging support and the `instance-count` debug flag is set (by setting the `GOBJECT_DEBUG` variable to include `instance-count`). the number of instances allocated of the given type; if instance counts are not available, returns 0. a #GType Returns the #GTypePlugin structure for @type. the corresponding plugin if @type is a dynamic type, %NULL otherwise #GType to retrieve the plugin for Obtains data which has previously been attached to @type with g_type_set_qdata(). Note that this does not take subtyping into account; data attached to one type with g_type_set_qdata() cannot be retrieved from a subtype using g_type_get_qdata(). the data, or %NULL if no data was found a #GType a #GQuark id to identify the data Returns an opaque serial number that represents the state of the set of registered types. Any time a type is registered this serial changes, which means you can cache information based on type lookups (such as g_type_from_name()) and know if the cache is still valid at a later time by comparing the current serial with the one at the type lookup. An unsigned int, representing the state of type registrations This function used to initialise the type system. Since GLib 2.36, the type system is initialised automatically and this function does nothing. the type system is now initialised automatically This function used to initialise the type system with debugging flags. Since GLib 2.36, the type system is initialised automatically and this function does nothing. If you need to enable debugging features, use the `GOBJECT_DEBUG` environment variable. the type system is now initialised automatically bitwise combination of #GTypeDebugFlags values for debugging purposes Adds @prerequisite_type to the list of prerequisites of @interface_type. This means that any type implementing @interface_type must also implement @prerequisite_type. Prerequisites can be thought of as an alternative to interface derivation (which GType doesn't support). An interface can have at most one instantiatable prerequisite type. #GType value of an interface type #GType value of an interface or instantiatable type Returns the #GTypePlugin structure for the dynamic interface @interface_type which has been added to @instance_type, or %NULL if @interface_type has not been added to @instance_type or does not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). the #GTypePlugin for the dynamic interface @interface_type of @instance_type #GType of an instantiatable type #GType of an interface type Returns the most specific instantiatable prerequisite of an interface type. If the interface type has no instantiatable prerequisite, %G_TYPE_INVALID is returned. See g_type_interface_add_prerequisite() for more information about prerequisites. the instantiatable prerequisite type or %G_TYPE_INVALID if none an interface type Returns the #GTypeInterface structure of an interface to which the passed in class conforms. the #GTypeInterface structure of @iface_type if implemented by @instance_class, %NULL otherwise a #GTypeClass structure an interface ID which this class conforms to Returns the prerequisites of an interfaces type. a newly-allocated zero-terminated array of #GType containing the prerequisites of @interface_type an interface type location to return the number of prerequisites, or %NULL Return a newly allocated and 0-terminated array of type IDs, listing the interface types that @type conforms to. Newly allocated and 0-terminated array of interface types, free with g_free() the type to list interface types for location to store the length of the returned array, or %NULL If @is_a_type is a derivable type, check whether @type is a descendant of @is_a_type. If @is_a_type is an interface, check whether @type conforms to it. %TRUE if @type is a @is_a_type type to check ancestry for possible ancestor of @type or interface that @type could conform to Get the unique name that is assigned to a type ID. Note that this function (like all other GType API) cannot cope with invalid type IDs. %G_TYPE_INVALID may be passed to this function, as may be any other validly registered type ID, but randomized type IDs should not be passed in and will most likely lead to a crash. static type name or %NULL type to return name for Given a @leaf_type and a @root_type which is contained in its ancestry, return the type that @root_type is the immediate parent of. In other words, this function determines the type that is derived directly from @root_type which is also a base class of @leaf_type. Given a root type and a leaf type, this function can be used to determine the types and order in which the leaf type is descended from the root type. immediate child of @root_type and ancestor of @leaf_type descendant of @root_type and the type to be returned immediate parent of the returned type Return the direct parent type of the passed in type. If the passed in type has no parent, i.e. is a fundamental type, 0 is returned. the parent type the derived type Get the corresponding quark of the type IDs name. the type names quark or 0 type to return quark of type name for Queries the type system for information about a specific type. This function will fill in a user-provided structure to hold type-specific information. If an invalid #GType is passed in, the @type member of the #GTypeQuery is 0. All members filled into the #GTypeQuery structure should be considered constant and have to be left untouched. Since GLib 2.78, this function allows queries on dynamic types. Previously it only supported static types. #GType of a static, classed type a user provided structure that is filled in with constant values upon success Registers @type_name as the name of a new dynamic type derived from @parent_type. The type system uses the information contained in the #GTypePlugin structure pointed to by @plugin to manage the type and its instances (if not abstract). The value of @flags determines the nature (e.g. abstract or not) of the type. the new type identifier or %G_TYPE_INVALID if registration failed type from which this type will be derived 0-terminated string used as the name of the new type #GTypePlugin structure to retrieve the #GTypeInfo from bitwise combination of #GTypeFlags values Registers @type_id as the predefined identifier and @type_name as the name of a fundamental type. If @type_id is already registered, or a type named @type_name is already registered, the behaviour is undefined. The type system uses the information contained in the #GTypeInfo structure pointed to by @info and the #GTypeFundamentalInfo structure pointed to by @finfo to manage the type and its instances. The value of @flags determines additional characteristics of the fundamental type. the predefined type identifier a predefined type identifier 0-terminated string used as the name of the new type #GTypeInfo structure for this type #GTypeFundamentalInfo structure for this type bitwise combination of #GTypeFlags values Registers @type_name as the name of a new static type derived from @parent_type. The type system uses the information contained in the #GTypeInfo structure pointed to by @info to manage the type and its instances (if not abstract). The value of @flags determines the nature (e.g. abstract or not) of the type. the new type identifier type from which this type will be derived 0-terminated string used as the name of the new type #GTypeInfo structure for this type bitwise combination of #GTypeFlags values Registers @type_name as the name of a new static type derived from @parent_type. The value of @flags determines the nature (e.g. abstract or not) of the type. It works by filling a #GTypeInfo struct and calling g_type_register_static(). the new type identifier type from which this type will be derived 0-terminated string used as the name of the new type size of the class structure (see #GTypeInfo) location of the class initialization function (see #GTypeInfo) size of the instance structure (see #GTypeInfo) location of the instance initialization function (see #GTypeInfo) bitwise combination of #GTypeFlags values Removes a previously installed #GTypeClassCacheFunc. The cache maintained by @cache_func has to be empty when calling g_type_remove_class_cache_func() to avoid leaks. data that was given when adding @cache_func a #GTypeClassCacheFunc Removes an interface check function added with g_type_add_interface_check(). callback data passed to g_type_add_interface_check() callback function passed to g_type_add_interface_check() Attaches arbitrary data to a type. a #GType a #GQuark id to identify the data the data Returns the location of the #GTypeValueTable associated with @type. Note that this function should only be used from source code that implements or has internal knowledge of the implementation of @type. location of the #GTypeValueTable associated with @type or %NULL if there is no #GTypeValueTable associated with @type a #GType Registers a value transformation function for use in [method@GObject.Value.transform]. Any previously registered transformation function for @src_type and @dest_type will be replaced. source type target type a function which transforms values of type @src_type into values of type @dest_type Checks whether a [method@GObject.Value.copy] is able to copy values of type @src_type into values of type @dest_type. true if the copy is possible; false otherwise source type to be copied destination type for copying Checks whether [method@GObject.Value.transform] is able to transform values of type @src_type into values of type @dest_type. Note that for the types to be transformable, they must be compatible or a transformation function must be registered using [func@GObject.Value.register_transform_func]. true if the transformation is possible; false otherwise source type target type soup3-0.9.0/gir-files/Gdk-3.0.gir000064400000000000000000046120701046102023000143040ustar 00000000000000 Used to represent native events (XEvents for the X11 backend, MSGs for Win32). Converts a #GdkAtom into a pointer type. a #GdkAtom. Positioning hints for aligning a window relative to a rectangle. These hints determine how the window should be positioned in the case that the window would fall off-screen if placed in its ideal position. For example, %GDK_ANCHOR_FLIP_X will replace %GDK_GRAVITY_NORTH_WEST with %GDK_GRAVITY_NORTH_EAST and vice versa if the window extends beyond the left or right edges of the monitor. If %GDK_ANCHOR_SLIDE_X is set, the window can be shifted horizontally to fit on-screen. If %GDK_ANCHOR_RESIZE_X is set, the window can be shrunken horizontally to fit. In general, when multiple flags are set, flipping should take precedence over sliding, which should take precedence over resizing. allow flipping anchors horizontally allow flipping anchors vertically allow sliding window horizontally allow sliding window vertically allow resizing window horizontally allow resizing window vertically allow flipping anchors on both axes allow sliding window on both axes allow resizing window on both axes GdkAppLaunchContext is an implementation of #GAppLaunchContext that handles launching an application in a graphical context. It provides startup notification and allows to launch applications on a specific screen or workspace. ## Launching an application |[<!-- language="C" --> GdkAppLaunchContext *context; context = gdk_display_get_app_launch_context (display); gdk_app_launch_context_set_screen (screen); gdk_app_launch_context_set_timestamp (event->time); if (!g_app_info_launch_default_for_uri ("http://www.gtk.org", context, &error)) g_warning ("Launching failed: %s\n", error->message); g_object_unref (context); ]| Creates a new #GdkAppLaunchContext. Use gdk_display_get_app_launch_context() instead a new #GdkAppLaunchContext Sets the workspace on which applications will be launched when using this context when running under a window manager that supports multiple workspaces, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec). When the workspace is not specified or @desktop is set to -1, it is up to the window manager to pick one, typically it will be the current workspace. a #GdkAppLaunchContext the number of a workspace, or -1 Sets the display on which applications will be launched when using this context. See also gdk_app_launch_context_set_screen(). Use gdk_display_get_app_launch_context() instead a #GdkAppLaunchContext a #GdkDisplay Sets the icon for applications that are launched with this context. Window Managers can use this information when displaying startup notification. See also gdk_app_launch_context_set_icon_name(). a #GdkAppLaunchContext a #GIcon, or %NULL Sets the icon for applications that are launched with this context. The @icon_name will be interpreted in the same way as the Icon field in desktop files. See also gdk_app_launch_context_set_icon(). If both @icon and @icon_name are set, the @icon_name takes priority. If neither @icon or @icon_name is set, the icon is taken from either the file that is passed to launched application or from the #GAppInfo for the launched application itself. a #GdkAppLaunchContext an icon name, or %NULL Sets the screen on which applications will be launched when using this context. See also gdk_app_launch_context_set_display(). Note that, typically, a #GdkScreen represents a logical screen, not a physical monitor. If both @screen and @display are set, the @screen takes priority. If neither @screen or @display are set, the default screen and display are used. a #GdkAppLaunchContext a #GdkScreen Sets the timestamp of @context. The timestamp should ideally be taken from the event that triggered the launch. Window managers can use this information to avoid moving the focus to the newly launched application when the user is busy typing in another window. This is also known as 'focus stealing prevention'. a #GdkAppLaunchContext a timestamp An opaque type representing a string as an index into a table of strings on the X server. Determines the string corresponding to an atom. a newly-allocated string containing the string corresponding to @atom. When you are done with the return value, you should free it using g_free(). a #GdkAtom. Finds or creates an atom corresponding to a given string. the atom corresponding to @atom_name. a string. if %TRUE, GDK is allowed to not create a new atom, but just return %GDK_NONE if the requested atom doesn’t already exists. Currently, the flag is ignored, since checking the existance of an atom is as expensive as creating it. Finds or creates an atom corresponding to a given string. Note that this function is identical to gdk_atom_intern() except that if a new #GdkAtom is created the string itself is used rather than a copy. This saves memory, but can only be used if the string will always exist. It can be used with statically allocated strings in the main program, but not with statically allocated memory in dynamically loaded modules, if you expect to ever unload the module again (e.g. do not use this function in GTK+ theme engines). the atom corresponding to @atom_name a static string Flags describing the current capabilities of a device/tool. X axis is present Y axis is present Pressure axis is present X tilt axis is present Y tilt axis is present Wheel axis is present Distance axis is present Z-axis rotation is present Slider axis is present An enumeration describing the way in which a device axis (valuator) maps onto the predefined valuator types that GTK+ understands. Note that the X and Y axes are not really needed; pointer devices report their location via the x/y members of events regardless. Whether X and Y are present as axes depends on the GDK backend. the axis is ignored. the axis is used as the x axis. the axis is used as the y axis. the axis is used for pressure information. the axis is used for x tilt information. the axis is used for y tilt information. the axis is used for wheel information. the axis is used for pen/tablet distance information. (Since: 3.22) the axis is used for pen rotation information. (Since: 3.22) the axis is used for pen slider information. (Since: 3.22) a constant equal to the numerically highest axis value. The middle button. The primary button. This is typically the left mouse button, or the right button in a left-handed setup. The secondary button. This is typically the right mouse button, or the left button in a left-handed setup. A set of values describing the possible byte-orders for storing pixel values in memory. The values are stored with the least-significant byte first. For instance, the 32-bit value 0xffeecc would be stored in memory as 0xcc, 0xee, 0xff, 0x00. The values are stored with the most-significant byte first. For instance, the 32-bit value 0xffeecc would be stored in memory as 0x00, 0xff, 0xee, 0xcc. Represents the current time, and can be used anywhere a time is expected. A #GdkColor is used to describe a color, similar to the XColor struct used in the X11 drawing API. Use #GdkRGBA For allocated colors, the pixel value used to draw this color on the screen. Not used anymore. The red component of the color. This is a value between 0 and 65535, with 65535 indicating full intensity The green component of the color The blue component of the color Makes a copy of a #GdkColor. The result must be freed using gdk_color_free(). Use #GdkRGBA a copy of @color a #GdkColor Compares two colors. Use #GdkRGBA %TRUE if the two colors compare equal a #GdkColor another #GdkColor Frees a #GdkColor created with gdk_color_copy(). Use #GdkRGBA a #GdkColor A hash function suitable for using for a hash table that stores #GdkColors. Use #GdkRGBA The hash function applied to @color a #GdkColor Returns a textual specification of @color in the hexadecimal form “\#rrrrggggbbbb” where “r”, “g” and “b” are hex digits representing the red, green and blue components respectively. The returned string can be parsed by gdk_color_parse(). Use #GdkRGBA a newly-allocated text string a #GdkColor Parses a textual specification of a color and fill in the @red, @green, and @blue fields of a #GdkColor. The string can either one of a large set of standard names (taken from the X11 `rgb.txt` file), or it can be a hexadecimal value in the form “\#rgb” “\#rrggbb”, “\#rrrgggbbb” or “\#rrrrggggbbbb” where “r”, “g” and “b” are hex digits of the red, green, and blue components of the color, respectively. (White in the four forms is “\#fff”, “\#ffffff”, “\#fffffffff” and “\#ffffffffffff”). Use #GdkRGBA %TRUE if the parsing succeeded the string specifying the color the #GdkColor to fill in Specifies the crossing mode for #GdkEventCrossing. crossing because of pointer motion. crossing because a grab is activated. crossing because a grab is deactivated. crossing because a GTK+ grab is activated. crossing because a GTK+ grab is deactivated. crossing because a GTK+ widget changed state (e.g. sensitivity). crossing because a touch sequence has begun, this event is synthetic as the pointer might have not left the window. crossing because a touch sequence has ended, this event is synthetic as the pointer might have not left the window. crossing because of a device switch (i.e. a mouse taking control of the pointer after a touch device), this event is synthetic as the pointer didn’t leave the window. A #GdkCursor represents a cursor. Its contents are private. Creates a new cursor from the set of builtin cursors for the default display. See gdk_cursor_new_for_display(). To make the cursor invisible, use %GDK_BLANK_CURSOR. Use gdk_cursor_new_for_display() instead. a new #GdkCursor cursor to create Creates a new cursor from the set of builtin cursors. a new #GdkCursor, or %NULL on failure the #GdkDisplay for which the cursor will be created cursor to create Creates a new cursor by looking up @name in the current cursor theme. A recommended set of cursor names that will work across different platforms can be found in the CSS specification: - "none" - ![](default_cursor.png) "default" - ![](help_cursor.png) "help" - ![](pointer_cursor.png) "pointer" - ![](context_menu_cursor.png) "context-menu" - ![](progress_cursor.png) "progress" - ![](wait_cursor.png) "wait" - ![](cell_cursor.png) "cell" - ![](crosshair_cursor.png) "crosshair" - ![](text_cursor.png) "text" - ![](vertical_text_cursor.png) "vertical-text" - ![](alias_cursor.png) "alias" - ![](copy_cursor.png) "copy" - ![](no_drop_cursor.png) "no-drop" - ![](move_cursor.png) "move" - ![](not_allowed_cursor.png) "not-allowed" - ![](grab_cursor.png) "grab" - ![](grabbing_cursor.png) "grabbing" - ![](all_scroll_cursor.png) "all-scroll" - ![](col_resize_cursor.png) "col-resize" - ![](row_resize_cursor.png) "row-resize" - ![](n_resize_cursor.png) "n-resize" - ![](e_resize_cursor.png) "e-resize" - ![](s_resize_cursor.png) "s-resize" - ![](w_resize_cursor.png) "w-resize" - ![](ne_resize_cursor.png) "ne-resize" - ![](nw_resize_cursor.png) "nw-resize" - ![](sw_resize_cursor.png) "sw-resize" - ![](se_resize_cursor.png) "se-resize" - ![](ew_resize_cursor.png) "ew-resize" - ![](ns_resize_cursor.png) "ns-resize" - ![](nesw_resize_cursor.png) "nesw-resize" - ![](nwse_resize_cursor.png) "nwse-resize" - ![](zoom_in_cursor.png) "zoom-in" - ![](zoom_out_cursor.png) "zoom-out" Additionally, the following cursor names are supported, which are not in the CSS specification: - ![](dnd_ask_cursor.png) "dnd-ask" - ![](all_resize_cursor.png) "all-resize" a new #GdkCursor, or %NULL if there is no cursor with the given name the #GdkDisplay for which the cursor will be created the name of the cursor Creates a new cursor from a pixbuf. Not all GDK backends support RGBA cursors. If they are not supported, a monochrome approximation will be displayed. The functions gdk_display_supports_cursor_alpha() and gdk_display_supports_cursor_color() can be used to determine whether RGBA cursors are supported; gdk_display_get_default_cursor_size() and gdk_display_get_maximal_cursor_size() give information about cursor sizes. If @x or @y are `-1`, the pixbuf must have options named “x_hot” and “y_hot”, resp., containing integer values between `0` and the width resp. height of the pixbuf. (Since: 3.0) On the X backend, support for RGBA cursors requires a sufficently new version of the X Render extension. a new #GdkCursor. the #GdkDisplay for which the cursor will be created the #GdkPixbuf containing the cursor image the horizontal offset of the “hotspot” of the cursor. the vertical offset of the “hotspot” of the cursor. Creates a new cursor from a cairo image surface. Not all GDK backends support RGBA cursors. If they are not supported, a monochrome approximation will be displayed. The functions gdk_display_supports_cursor_alpha() and gdk_display_supports_cursor_color() can be used to determine whether RGBA cursors are supported; gdk_display_get_default_cursor_size() and gdk_display_get_maximal_cursor_size() give information about cursor sizes. On the X backend, support for RGBA cursors requires a sufficently new version of the X Render extension. a new #GdkCursor. the #GdkDisplay for which the cursor will be created the cairo image surface containing the cursor pixel data the horizontal offset of the “hotspot” of the cursor the vertical offset of the “hotspot” of the cursor Returns the cursor type for this cursor. a #GdkCursorType a #GdkCursor Returns the display on which the #GdkCursor is defined. the #GdkDisplay associated to @cursor a #GdkCursor. Returns a #GdkPixbuf with the image used to display the cursor. Note that depending on the capabilities of the windowing system and on the cursor, GDK may not be able to obtain the image data. In this case, %NULL is returned. a #GdkPixbuf representing @cursor, or %NULL a #GdkCursor Returns a cairo image surface with the image used to display the cursor. Note that depending on the capabilities of the windowing system and on the cursor, GDK may not be able to obtain the image data. In this case, %NULL is returned. a #cairo_surface_t representing @cursor, or %NULL a #GdkCursor Location to store the hotspot x position, or %NULL Location to store the hotspot y position, or %NULL Adds a reference to @cursor. Use g_object_ref() instead Same @cursor that was passed in a #GdkCursor Removes a reference from @cursor, deallocating the cursor if no references remain. Use g_object_unref() instead a #GdkCursor Predefined cursors. Note that these IDs are directly taken from the X cursor font, and many of these cursors are either not useful, or are not available on other platforms. The recommended way to create cursors is to use gdk_cursor_new_from_name(). ![](X_cursor.png) ![](arrow.png) ![](based_arrow_down.png) ![](based_arrow_up.png) ![](boat.png) ![](bogosity.png) ![](bottom_left_corner.png) ![](bottom_right_corner.png) ![](bottom_side.png) ![](bottom_tee.png) ![](box_spiral.png) ![](center_ptr.png) ![](circle.png) ![](clock.png) ![](coffee_mug.png) ![](cross.png) ![](cross_reverse.png) ![](crosshair.png) ![](diamond_cross.png) ![](dot.png) ![](dotbox.png) ![](double_arrow.png) ![](draft_large.png) ![](draft_small.png) ![](draped_box.png) ![](exchange.png) ![](fleur.png) ![](gobbler.png) ![](gumby.png) ![](hand1.png) ![](hand2.png) ![](heart.png) ![](icon.png) ![](iron_cross.png) ![](left_ptr.png) ![](left_side.png) ![](left_tee.png) ![](leftbutton.png) ![](ll_angle.png) ![](lr_angle.png) ![](man.png) ![](middlebutton.png) ![](mouse.png) ![](pencil.png) ![](pirate.png) ![](plus.png) ![](question_arrow.png) ![](right_ptr.png) ![](right_side.png) ![](right_tee.png) ![](rightbutton.png) ![](rtl_logo.png) ![](sailboat.png) ![](sb_down_arrow.png) ![](sb_h_double_arrow.png) ![](sb_left_arrow.png) ![](sb_right_arrow.png) ![](sb_up_arrow.png) ![](sb_v_double_arrow.png) ![](shuttle.png) ![](sizing.png) ![](spider.png) ![](spraycan.png) ![](star.png) ![](target.png) ![](tcross.png) ![](top_left_arrow.png) ![](top_left_corner.png) ![](top_right_corner.png) ![](top_side.png) ![](top_tee.png) ![](trek.png) ![](ul_angle.png) ![](umbrella.png) ![](ur_angle.png) ![](watch.png) ![](xterm.png) last cursor type Blank cursor. Since 2.16 type of cursors constructed with gdk_cursor_new_from_pixbuf() The #GdkDevice object represents a single input device, such as a keyboard, a mouse, a touchpad, etc. See the #GdkDeviceManager documentation for more information about the various kinds of master and slave devices, and their relationships. Frees an array of #GdkTimeCoord that was returned by gdk_device_get_history(). an array of #GdkTimeCoord. the length of the array. Determines information about the current keyboard grab. This is not public API and must not be used by applications. The symbol was never meant to be used outside of GTK+ %TRUE if this application currently has the keyboard grabbed. the display for which to get the grab information device to get the grab information from location to store current grab window location to store boolean indicating whether the @owner_events flag to gdk_keyboard_grab() or gdk_pointer_grab() was %TRUE. Returns the associated device to @device, if @device is of type %GDK_DEVICE_TYPE_MASTER, it will return the paired pointer or keyboard. If @device is of type %GDK_DEVICE_TYPE_SLAVE, it will return the master device to which @device is attached to. If @device is of type %GDK_DEVICE_TYPE_FLOATING, %NULL will be returned, as there is no associated device. The associated device, or %NULL a #GdkDevice Returns the axes currently available on the device. a #GdkDevice Interprets an array of double as axis values for a given device, and locates the value in the array for a given axis use. %TRUE if the given axis use was found, otherwise %FALSE a #GdkDevice pointer to an array of axes the use to look for location to store the found value. Returns the axis use for @index_. a #GdkAxisUse specifying how the axis is used. a pointer #GdkDevice. the index of the axis. Interprets an array of double as axis values for a given device, and locates the value in the array for a given axis label, as returned by gdk_device_list_axes() %TRUE if the given axis use was found, otherwise %FALSE. a pointer #GdkDevice. pointer to an array of axes #GdkAtom with the axis label. location to store the found value. Returns the device type for @device. the #GdkDeviceType for @device. a #GdkDevice Returns the #GdkDisplay to which @device pertains. a #GdkDisplay. This memory is owned by GTK+, and must not be freed or unreffed. a #GdkDevice Determines whether the pointer follows device motion. This is not meaningful for keyboard devices, which don't have a pointer. %TRUE if the pointer follows device motion a #GdkDevice Obtains the motion history for a pointer device; given a starting and ending timestamp, return all events in the motion history for the device in the given range of time. Some windowing systems do not support motion history, in which case, %FALSE will be returned. (This is not distinguishable from the case where motion history is supported and no events were found.) Note that there is also gdk_window_set_event_compression() to get more motion events delivered directly, independent of the windowing system. %TRUE if the windowing system supports motion history and at least one event was found. a #GdkDevice the window with respect to which which the event coordinates will be reported starting timestamp for range of events to return ending timestamp for the range of events to return location to store a newly-allocated array of #GdkTimeCoord, or %NULL location to store the length of @events, or %NULL If @index_ has a valid keyval, this function will return %TRUE and fill in @keyval and @modifiers with the keyval settings. %TRUE if keyval is set for @index. a #GdkDevice. the index of the macro button to get. return value for the keyval. return value for modifiers. Gets information about which window the given pointer device is in, based on events that have been received so far from the display server. If another application has a pointer grab, or this application has a grab with owner_events = %FALSE, %NULL may be returned even if the pointer is physically over one of this application's windows. the last window the device a #GdkDevice, with a source other than %GDK_SOURCE_KEYBOARD Determines the mode of the device. a #GdkInputSource a #GdkDevice Returns the number of axes the device currently has. the number of axes. a pointer #GdkDevice Returns the number of keys the device currently has. the number of keys. a #GdkDevice Determines the name of the device. a name a #GdkDevice Gets the current location of @device. As a slave device coordinates are those of its master pointer, This function may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE, unless there is an ongoing grab on them, see gdk_device_grab(). pointer device to query status about. location to store the #GdkScreen the @device is on, or %NULL. location to store root window X coordinate of @device, or %NULL. location to store root window Y coordinate of @device, or %NULL. Gets the current location of @device in double precision. As a slave device's coordinates are those of its master pointer, this function may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE, unless there is an ongoing grab on them. See gdk_device_grab(). pointer device to query status about. location to store the #GdkScreen the @device is on, or %NULL. location to store root window X coordinate of @device, or %NULL. location to store root window Y coordinate of @device, or %NULL. Returns the product ID of this device, or %NULL if this information couldn't be obtained. This ID is retrieved from the device, and is thus constant for it. See gdk_device_get_vendor_id() for more information. the product ID, or %NULL a slave #GdkDevice Returns the #GdkSeat the device belongs to. A #GdkSeat. This memory is owned by GTK+ and must not be freed. A #GdkDevice Determines the type of the device. a #GdkInputSource a #GdkDevice Gets the current state of a pointer device relative to @window. As a slave device’s coordinates are those of its master pointer, this function may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE, unless there is an ongoing grab on them. See gdk_device_grab(). a #GdkDevice. a #GdkWindow. an array of doubles to store the values of the axes of @device in, or %NULL. location to store the modifiers, or %NULL. Returns the vendor ID of this device, or %NULL if this information couldn't be obtained. This ID is retrieved from the device, and is thus constant for it. This function, together with gdk_device_get_product_id(), can be used to eg. compose #GSettings paths to store settings for this device. |[<!-- language="C" --> static GSettings * get_device_settings (GdkDevice *device) { const gchar *vendor, *product; GSettings *settings; GdkDevice *device; gchar *path; vendor = gdk_device_get_vendor_id (device); product = gdk_device_get_product_id (device); path = g_strdup_printf ("/org/example/app/devices/%s:%s/", vendor, product); settings = g_settings_new_with_path (DEVICE_SCHEMA, path); g_free (path); return settings; } ]| the vendor ID, or %NULL a slave #GdkDevice Obtains the window underneath @device, returning the location of the device in @win_x and @win_y. Returns %NULL if the window tree under @device is not known to GDK (for example, belongs to another application). As a slave device coordinates are those of its master pointer, This function may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE, unless there is an ongoing grab on them, see gdk_device_grab(). the #GdkWindow under the device position, or %NULL. pointer #GdkDevice to query info to. return location for the X coordinate of the device location, relative to the window origin, or %NULL. return location for the Y coordinate of the device location, relative to the window origin, or %NULL. Obtains the window underneath @device, returning the location of the device in @win_x and @win_y in double precision. Returns %NULL if the window tree under @device is not known to GDK (for example, belongs to another application). As a slave device coordinates are those of its master pointer, This function may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE, unless there is an ongoing grab on them, see gdk_device_grab(). the #GdkWindow under the device position, or %NULL. pointer #GdkDevice to query info to. return location for the X coordinate of the device location, relative to the window origin, or %NULL. return location for the Y coordinate of the device location, relative to the window origin, or %NULL. Grabs the device so that all events coming from this device are passed to this application until the device is ungrabbed with gdk_device_ungrab(), or the window becomes unviewable. This overrides any previous grab on the device by this client. Note that @device and @window need to be on the same display. Device grabs are used for operations which need complete control over the given device events (either pointer or keyboard). For example in GTK+ this is used for Drag and Drop operations, popup menus and such. Note that if the event mask of an X window has selected both button press and button release events, then a button press event will cause an automatic pointer grab until the button is released. X does this automatically since most applications expect to receive button press and release events in pairs. It is equivalent to a pointer grab on the window with @owner_events set to %TRUE. If you set up anything at the time you take the grab that needs to be cleaned up when the grab ends, you should handle the #GdkEventGrabBroken events that are emitted when the grab ends unvoluntarily. Use gdk_seat_grab() instead. %GDK_GRAB_SUCCESS if the grab was successful. a #GdkDevice. To get the device you can use gtk_get_current_event_device() or gdk_event_get_device() if the grab is in reaction to an event. Also, you can use gdk_device_manager_get_client_pointer() but only in code that isn’t triggered by a #GdkEvent and there aren’t other means to get a meaningful #GdkDevice to operate on. the #GdkWindow which will own the grab (the grab window) specifies the grab ownership. if %FALSE then all device events are reported with respect to @window and are only reported if selected by @event_mask. If %TRUE then pointer events for this application are reported as normal, but pointer events outside this application are reported with respect to @window and only if selected by @event_mask. In either mode, unreported events are discarded. specifies the event mask, which is used in accordance with @owner_events. the cursor to display while the grab is active if the device is a pointer. If this is %NULL then the normal cursors are used for @window and its descendants, and the cursor for @window is used elsewhere. the timestamp of the event which led to this pointer grab. This usually comes from the #GdkEvent struct, though %GDK_CURRENT_TIME can be used if the time isn’t known. Returns a #GList of #GdkAtoms, containing the labels for the axes that @device currently has. A #GList of #GdkAtoms, free with g_list_free(). a pointer #GdkDevice If the device if of type %GDK_DEVICE_TYPE_MASTER, it will return the list of slave devices attached to it, otherwise it will return %NULL the list of slave devices, or %NULL. The list must be freed with g_list_free(), the contents of the list are owned by GTK+ and should not be freed. a #GdkDevice Specifies how an axis of a device is used. a pointer #GdkDevice the index of the axis specifies how the axis is used Specifies the X key event to generate when a macro button of a device is pressed. a #GdkDevice the index of the macro button to set the keyval to generate the modifiers to set Sets a the mode of an input device. The mode controls if the device is active and whether the device’s range is mapped to the entire screen or to a single window. Note: This is only meaningful for floating devices, master devices (and slaves connected to these) drive the pointer cursor, which is not limited by the input mode. %TRUE if the mode was successfully changed. a #GdkDevice. the input mode. Release any grab on @device. Use gdk_seat_ungrab() instead. a #GdkDevice a timestap (e.g. %GDK_CURRENT_TIME). Warps @device in @display to the point @x,@y on the screen @screen, unless the device is confined to a window by a grab, in which case it will be moved as far as allowed by the grab. Warping the pointer creates events as if the user had moved the mouse instantaneously to the destination. Note that the pointer should normally be under the control of the user. This function was added to cover some rare use cases like keyboard navigation support for the color picker in the #GtkColorSelectionDialog. the device to warp. the screen to warp @device to. the X coordinate of the destination. the Y coordinate of the destination. Associated pointer or keyboard with this device, if any. Devices of type #GDK_DEVICE_TYPE_MASTER always come in keyboard/pointer pairs. Other device types will have a %NULL associated device. The axes currently available for this device. The #GdkDeviceManager the #GdkDevice pertains to. The #GdkDisplay the #GdkDevice pertains to. Whether the device is represented by a cursor on the screen. Devices of type %GDK_DEVICE_TYPE_MASTER will have %TRUE here. Source type for the device. Number of axes in the device. The device name. The maximal number of concurrent touches on a touch device. Will be 0 if the device is not a touch device or if the number of touches is unknown. Product ID of this device, see gdk_device_get_product_id(). #GdkSeat of this device. Device role in the device manager. Vendor ID of this device, see gdk_device_get_vendor_id(). The ::changed signal is emitted either when the #GdkDevice has changed the number of either axes or keys. For example In X this will normally happen when the slave device routing events through the master device changes (for example, user switches from the USB mouse to a tablet), in that case the master device will change to reflect the new slave device axes and keys. The ::tool-changed signal is emitted on pen/eraser #GdkDevices whenever tools enter or leave proximity. The new current tool In addition to a single pointer and keyboard for user interface input, GDK contains support for a variety of input devices, including graphics tablets, touchscreens and multiple pointers/keyboards interacting simultaneously with the user interface. Such input devices often have additional features, such as sub-pixel positioning information and additional device-dependent information. In order to query the device hierarchy and be aware of changes in the device hierarchy (such as virtual devices being created or removed, or physical devices being plugged or unplugged), GDK provides #GdkDeviceManager. By default, and if the platform supports it, GDK is aware of multiple keyboard/pointer pairs and multitouch devices. This behavior can be changed by calling gdk_disable_multidevice() before gdk_display_open(). There should rarely be a need to do that though, since GDK defaults to a compatibility mode in which it will emit just one enter/leave event pair for all devices on a window. To enable per-device enter/leave events and other multi-pointer interaction features, gdk_window_set_support_multidevice() must be called on #GdkWindows (or gtk_widget_set_support_multidevice() on widgets). window. See the gdk_window_set_support_multidevice() documentation for more information. On X11, multi-device support is implemented through XInput 2. Unless gdk_disable_multidevice() is called, the XInput 2 #GdkDeviceManager implementation will be used as the input source. Otherwise either the core or XInput 1 implementations will be used. For simple applications that don’t have any special interest in input devices, the so-called “client pointer” provides a reasonable approximation to a simple setup with a single pointer and keyboard. The device that has been set as the client pointer can be accessed via gdk_device_manager_get_client_pointer(). Conceptually, in multidevice mode there are 2 device types. Virtual devices (or master devices) are represented by the pointer cursors and keyboard foci that are seen on the screen. Physical devices (or slave devices) represent the hardware that is controlling the virtual devices, and thus have no visible cursor on the screen. Virtual devices are always paired, so there is a keyboard device for every pointer device. Associations between devices may be inspected through gdk_device_get_associated_device(). There may be several virtual devices, and several physical devices could be controlling each of these virtual devices. Physical devices may also be “floating”, which means they are not attached to any virtual device. # Master and slave devices |[ carlos@sacarino:~$ xinput list ⎡ Virtual core pointer id=2 [master pointer (3)] ⎜ ↳ Virtual core XTEST pointer id=4 [slave pointer (2)] ⎜ ↳ Wacom ISDv4 E6 Pen stylus id=10 [slave pointer (2)] ⎜ ↳ Wacom ISDv4 E6 Finger touch id=11 [slave pointer (2)] ⎜ ↳ SynPS/2 Synaptics TouchPad id=13 [slave pointer (2)] ⎜ ↳ TPPS/2 IBM TrackPoint id=14 [slave pointer (2)] ⎜ ↳ Wacom ISDv4 E6 Pen eraser id=16 [slave pointer (2)] ⎣ Virtual core keyboard id=3 [master keyboard (2)] ↳ Virtual core XTEST keyboard id=5 [slave keyboard (3)] ↳ Power Button id=6 [slave keyboard (3)] ↳ Video Bus id=7 [slave keyboard (3)] ↳ Sleep Button id=8 [slave keyboard (3)] ↳ Integrated Camera id=9 [slave keyboard (3)] ↳ AT Translated Set 2 keyboard id=12 [slave keyboard (3)] ↳ ThinkPad Extra Buttons id=15 [slave keyboard (3)] ]| By default, GDK will automatically listen for events coming from all master devices, setting the #GdkDevice for all events coming from input devices. Events containing device information are #GDK_MOTION_NOTIFY, #GDK_BUTTON_PRESS, #GDK_2BUTTON_PRESS, #GDK_3BUTTON_PRESS, #GDK_BUTTON_RELEASE, #GDK_SCROLL, #GDK_KEY_PRESS, #GDK_KEY_RELEASE, #GDK_ENTER_NOTIFY, #GDK_LEAVE_NOTIFY, #GDK_FOCUS_CHANGE, #GDK_PROXIMITY_IN, #GDK_PROXIMITY_OUT, #GDK_DRAG_ENTER, #GDK_DRAG_LEAVE, #GDK_DRAG_MOTION, #GDK_DRAG_STATUS, #GDK_DROP_START, #GDK_DROP_FINISHED and #GDK_GRAB_BROKEN. When dealing with an event on a master device, it is possible to get the source (slave) device that the event originated from via gdk_event_get_source_device(). On a standard session, all physical devices are connected by default to the "Virtual Core Pointer/Keyboard" master devices, hence routing all events through these. This behavior is only modified by device grabs, where the slave device is temporarily detached for as long as the grab is held, and more permanently by user modifications to the device hierarchy. On certain application specific setups, it may make sense to detach a physical device from its master pointer, and mapping it to an specific window. This can be achieved by the combination of gdk_device_grab() and gdk_device_set_mode(). In order to listen for events coming from devices other than a virtual device, gdk_window_set_device_events() must be called. Generally, this function can be used to modify the event mask for any given device. Input devices may also provide additional information besides X/Y. For example, graphics tablets may also provide pressure and X/Y tilt information. This information is device-dependent, and may be queried through gdk_device_get_axis(). In multidevice mode, virtual devices will change axes in order to always represent the physical device that is routing events through it. Whenever the physical device changes, the #GdkDevice:n-axes property will be notified, and gdk_device_list_axes() will return the new device axes. Devices may also have associated “keys” or macro buttons. Such keys can be globally set to map into normal X keyboard events. The mapping is set using gdk_device_set_key(). In GTK+ 3.20, a new #GdkSeat object has been introduced that supersedes #GdkDeviceManager and should be preferred in newly written code. Returns the client pointer, that is, the master pointer that acts as the core pointer for this application. In X11, window managers may change this depending on the interaction pattern under the presence of several pointers. You should use this function seldomly, only in code that isn’t triggered by a #GdkEvent and there aren’t other means to get a meaningful #GdkDevice to operate on. Use gdk_seat_get_pointer() instead. The client pointer. This memory is owned by GDK and must not be freed or unreferenced. a #GdkDeviceManager Gets the #GdkDisplay associated to @device_manager. the #GdkDisplay to which @device_manager is associated to, or %NULL. This memory is owned by GDK and must not be freed or unreferenced. a #GdkDeviceManager Returns the list of devices of type @type currently attached to @device_manager. , use gdk_seat_get_pointer(), gdk_seat_get_keyboard() and gdk_seat_get_slaves() instead. a list of #GdkDevices. The returned list must be freed with g_list_free (). The list elements are owned by GTK+ and must not be freed or unreffed. a #GdkDeviceManager device type to get. The ::device-added signal is emitted either when a new master pointer is created, or when a slave (Hardware) input device is plugged in. the newly added #GdkDevice. The ::device-changed signal is emitted whenever a device has changed in the hierarchy, either slave devices being disconnected from their master device or connected to another one, or master devices being added or removed a slave device. If a slave device is detached from all master devices (gdk_device_get_associated_device() returns %NULL), its #GdkDeviceType will change to %GDK_DEVICE_TYPE_FLOATING, if it's attached, it will change to %GDK_DEVICE_TYPE_SLAVE. the #GdkDevice that changed. The ::device-removed signal is emitted either when a master pointer is removed, or when a slave (Hardware) input device is unplugged. the just removed #GdkDevice. #GdkDevicePad is an interface implemented by devices of type %GDK_SOURCE_TABLET_PAD, it allows querying the features provided by the pad device. Tablet pads may contain one or more groups, each containing a subset of the buttons/rings/strips available. gdk_device_pad_get_n_groups() can be used to obtain the number of groups, gdk_device_pad_get_n_features() and gdk_device_pad_get_feature_group() can be combined to find out the number of buttons/rings/strips the device has, and how are they grouped. Each of those groups have different modes, which may be used to map each individual pad feature to multiple actions. Only one mode is effective (current) for each given group, different groups may have different current modes. The number of available modes in a group can be found out through gdk_device_pad_get_group_n_modes(), and the current mode for a given group will be notified through the #GdkEventPadGroupMode event. Returns the group the given @feature and @idx belong to, or -1 if feature/index do not exist in @pad. The group number of the queried pad feature. a #GdkDevicePad the feature type to get the group from the index of the feature to get the group from Returns the number of modes that @group may have. The number of modes available in @group. a #GdkDevicePad group to get the number of available modes from Returns the number of features a tablet pad has. The amount of elements of type @feature that this pad has. a #GdkDevicePad a pad feature Returns the number of groups this pad device has. Pads have at least one group. A pad group is a subcollection of buttons/strip/rings that is affected collectively by a same current mode. The number of button/ring/strip groups in the pad. a #GdkDevicePad A pad feature. a button a ring-shaped interactive area a straight interactive area Gets the hardware ID of this tool, or 0 if it's not known. When non-zero, the identificator is unique for the given tool model, meaning that two identical tools will share the same @hardware_id, but will have different serial numbers (see gdk_device_tool_get_serial()). This is a more concrete (and device specific) method to identify a #GdkDeviceTool than gdk_device_tool_get_tool_type(), as a tablet may support multiple devices with the same #GdkDeviceToolType, but having different hardware identificators. The hardware identificator of this tool. a #GdkDeviceTool Gets the serial of this tool, this value can be used to identify a physical tool (eg. a tablet pen) across program executions. The serial ID for this tool a #GdkDeviceTool Gets the #GdkDeviceToolType of the tool. The physical type for this tool. This can be used to figure out what sort of pen is being used, such as an airbrush or a pencil. a #GdkDeviceTool Indicates the specific type of tool being used being a tablet. Such as an airbrush, pencil, etc. Tool is of an unknown type. Tool is a standard tablet stylus. Tool is standard tablet eraser. Tool is a brush stylus. Tool is a pencil stylus. Tool is an airbrush stylus. Tool is a mouse. Tool is a lens cursor. Indicates the device type. See [above][GdkDeviceManager.description] for more information about the meaning of these device types. Device is a master (or virtual) device. There will be an associated focus indicator on the screen. Device is a slave (or physical) device. Device is a physical device, currently not attached to any virtual device. #GdkDisplay objects purpose are two fold: - To manage and provide information about input devices (pointers and keyboards) - To manage and provide information about the available #GdkScreens GdkDisplay objects are the GDK representation of an X Display, which can be described as a workstation consisting of a keyboard, a pointing device (such as a mouse) and one or more screens. It is used to open and keep track of various GdkScreen objects currently instantiated by the application. It is also used to access the keyboard(s) and mouse pointer(s) of the display. Most of the input device handling has been factored out into the separate #GdkDeviceManager object. Every display has a device manager, which you can obtain using gdk_display_get_device_manager(). Gets the default #GdkDisplay. This is a convenience function for: `gdk_display_manager_get_default_display (gdk_display_manager_get ())`. a #GdkDisplay, or %NULL if there is no default display. Opens a display. a #GdkDisplay, or %NULL if the display could not be opened the name of the display to open Opens the default display specified by command line arguments or environment variables, sets it as the default display, and returns it. gdk_parse_args() must have been called first. If the default display has previously been set, simply returns that. An internal function that should not be used by applications. This symbol was never meant to be used outside of GTK+ the default display, if it could be opened, otherwise %NULL. Emits a short beep on @display a #GdkDisplay Closes the connection to the windowing system for the given display, and cleans up associated resources. a #GdkDisplay Returns %TRUE if there is an ongoing grab on @device for @display. %TRUE if there is a grab in effect for @device. a #GdkDisplay a #GdkDevice Flushes any requests queued for the windowing system; this happens automatically when the main loop blocks waiting for new events, but if your application is drawing without returning control to the main loop, you may need to call this function explicitly. A common case where this function needs to be called is when an application is executing drawing commands from a thread other than the thread where the main loop is running. This is most useful for X11. On windowing systems where requests are handled synchronously, this function will do nothing. a #GdkDisplay Returns a #GdkAppLaunchContext suitable for launching applications on the given display. a new #GdkAppLaunchContext for @display. Free with g_object_unref() when done a #GdkDisplay Returns the default size to use for cursors on @display. the default cursor size. a #GdkDisplay Returns the default group leader window for all toplevel windows on @display. This window is implicitly created by GDK. See gdk_window_set_group(). The default group leader window for @display a #GdkDisplay Get the default #GdkScreen for @display. the default #GdkScreen object for @display a #GdkDisplay Returns the default #GdkSeat for this display. the default seat. a #GdkDisplay Returns the #GdkDeviceManager associated to @display. Use gdk_display_get_default_seat() and #GdkSeat operations. A #GdkDeviceManager, or %NULL. This memory is owned by GDK and must not be freed or unreferenced. a #GdkDisplay. Gets the next #GdkEvent to be processed for @display, fetching events from the windowing system if necessary. the next #GdkEvent to be processed, or %NULL if no events are pending. The returned #GdkEvent should be freed with gdk_event_free(). a #GdkDisplay Gets the maximal size to use for cursors on @display. a #GdkDisplay the return location for the maximal cursor width the return location for the maximal cursor height Gets a monitor associated with this display. the #GdkMonitor, or %NULL if @monitor_num is not a valid monitor number a #GdkDisplay number of the monitor Gets the monitor in which the point (@x, @y) is located, or a nearby monitor if the point is not in any monitor. the monitor containing the point a #GdkDisplay the x coordinate of the point the y coordinate of the point Gets the monitor in which the largest area of @window resides, or a monitor close to @window if it is outside of all monitors. the monitor with the largest overlap with @window a #GdkDisplay a #GdkWindow Gets the number of monitors that belong to @display. The returned number is valid until the next emission of the #GdkDisplay::monitor-added or #GdkDisplay::monitor-removed signal. the number of monitors a #GdkDisplay Gets the number of screen managed by the @display. The number of screens is always 1. number of screens. a #GdkDisplay Gets the name of the display. a string representing the display name. This string is owned by GDK and should not be modified or freed. a #GdkDisplay Gets the current location of the pointer and the current modifier mask for a given display. Use gdk_device_get_position() instead. a #GdkDisplay location to store the screen that the cursor is on, or %NULL. location to store root window X coordinate of pointer, or %NULL. location to store root window Y coordinate of pointer, or %NULL. location to store current modifier mask, or %NULL Gets the primary monitor for the display. The primary monitor is considered the monitor where the “main desktop” lives. While normal application windows typically allow the window manager to place the windows, specialized desktop applications such as panels should place themselves on the primary monitor. the primary monitor, or %NULL if no primary monitor is configured by the user a #GdkDisplay Returns a screen object for one of the screens of the display. There is only one screen; use gdk_display_get_default_screen() to get it. the #GdkScreen object a #GdkDisplay the screen number Obtains the window underneath the mouse pointer, returning the location of the pointer in that window in @win_x, @win_y for @screen. Returns %NULL if the window under the mouse pointer is not known to GDK (for example, belongs to another application). Use gdk_device_get_window_at_position() instead. the window under the mouse pointer, or %NULL a #GdkDisplay return location for x coordinate of the pointer location relative to the window origin, or %NULL return location for y coordinate of the pointer location relative & to the window origin, or %NULL Returns whether the display has events that are waiting to be processed. %TRUE if there are events ready to be processed. a #GdkDisplay Finds out if the display has been closed. %TRUE if the display is closed. a #GdkDisplay Release any keyboard grab Use gdk_device_ungrab(), together with gdk_device_grab() instead. a #GdkDisplay. a timestap (e.g #GDK_CURRENT_TIME). Returns the list of available input devices attached to @display. The list is statically allocated and should not be freed. Use gdk_device_manager_list_devices() instead. a list of #GdkDevice a #GdkDisplay Returns the list of seats known to @display. the list of seats known to the #GdkDisplay a #GdkDisplay Indicates to the GUI environment that the application has finished loading, using a given identifier. GTK+ will call this function automatically for #GtkWindow with custom startup-notification identifier unless gtk_window_set_auto_startup_notification() is called to disable that feature. a #GdkDisplay a startup-notification identifier, for which notification process should be completed Gets a copy of the first #GdkEvent in the @display’s event queue, without removing the event from the queue. (Note that this function will not get more events from the windowing system. It only checks the events that have already been moved to the GDK event queue.) a copy of the first #GdkEvent on the event queue, or %NULL if no events are in the queue. The returned #GdkEvent should be freed with gdk_event_free(). a #GdkDisplay Test if the pointer is grabbed. Use gdk_display_device_is_grabbed() instead. %TRUE if an active X pointer grab is in effect a #GdkDisplay Release any pointer grab. Use gdk_device_ungrab(), together with gdk_device_grab() instead. a #GdkDisplay. a timestap (e.g. %GDK_CURRENT_TIME). Appends a copy of the given event onto the front of the event queue for @display. a #GdkDisplay a #GdkEvent. Request #GdkEventOwnerChange events for ownership changes of the selection named by the given atom. whether #GdkEventOwnerChange events will be sent. a #GdkDisplay the #GdkAtom naming the selection for which ownership change notification is requested Sets the double click distance (two clicks within this distance count as a double click and result in a #GDK_2BUTTON_PRESS event). See also gdk_display_set_double_click_time(). Applications should not set this, it is a global user-configured setting. a #GdkDisplay distance in pixels Sets the double click time (two clicks within this time interval count as a double click and result in a #GDK_2BUTTON_PRESS event). Applications should not set this, it is a global user-configured setting. a #GdkDisplay double click time in milliseconds (thousandths of a second) Issues a request to the clipboard manager to store the clipboard data. On X11, this is a special program that works according to the [FreeDesktop Clipboard Specification](http://www.freedesktop.org/Standards/clipboard-manager-spec). a #GdkDisplay a #GdkWindow belonging to the clipboard owner a timestamp an array of targets that should be saved, or %NULL if all available targets should be saved. length of the @targets array Returns whether the speicifed display supports clipboard persistance; i.e. if it’s possible to store the clipboard data after an application has quit. On X11 this checks if a clipboard daemon is running. %TRUE if the display supports clipboard persistance. a #GdkDisplay Returns %TRUE if gdk_window_set_composited() can be used to redirect drawing on the window using compositing. Currently this only works on X11 with XComposite and XDamage extensions available. Compositing is an outdated technology that only ever worked on X11. %TRUE if windows may be composited. a #GdkDisplay Returns %TRUE if cursors can use an 8bit alpha channel on @display. Otherwise, cursors are restricted to bilevel alpha (i.e. a mask). whether cursors can have alpha channels. a #GdkDisplay Returns %TRUE if multicolored cursors are supported on @display. Otherwise, cursors have only a forground and a background color. whether cursors can have multiple colors. a #GdkDisplay Returns %TRUE if gdk_window_input_shape_combine_mask() can be used to modify the input shape of windows on @display. %TRUE if windows with modified input shape are supported a #GdkDisplay Returns whether #GdkEventOwnerChange events will be sent when the owner of a selection changes. whether #GdkEventOwnerChange events will be sent. a #GdkDisplay Returns %TRUE if gdk_window_shape_combine_mask() can be used to create shaped windows on @display. %TRUE if shaped windows are supported a #GdkDisplay Flushes any requests queued for the windowing system and waits until all requests have been handled. This is often used for making sure that the display is synchronized with the current state of the program. Calling gdk_display_sync() before gdk_error_trap_pop() makes sure that any errors generated from earlier requests are handled before the error trap is removed. This is most useful for X11. On windowing systems where requests are handled synchronously, this function will do nothing. a #GdkDisplay Warps the pointer of @display to the point @x,@y on the screen @screen, unless the pointer is confined to a window by a grab, in which case it will be moved as far as allowed by the grab. Warping the pointer creates events as if the user had moved the mouse instantaneously to the destination. Note that the pointer should normally be under the control of the user. This function was added to cover some rare use cases like keyboard navigation support for the color picker in the #GtkColorSelectionDialog. Use gdk_device_warp() instead. a #GdkDisplay the screen of @display to warp the pointer to the x coordinate of the destination the y coordinate of the destination The ::closed signal is emitted when the connection to the windowing system for @display is closed. %TRUE if the display was closed due to an error The ::monitor-added signal is emitted whenever a monitor is added. the monitor that was just added The ::monitor-removed signal is emitted whenever a monitor is removed. the monitor that was just removed The ::opened signal is emitted when the connection to the windowing system for @display is opened. The ::seat-added signal is emitted whenever a new seat is made known to the windowing system. the seat that was just added The ::seat-removed signal is emitted whenever a seat is removed by the windowing system. the seat that was just removed The purpose of the #GdkDisplayManager singleton object is to offer notification when displays appear or disappear or the default display changes. You can use gdk_display_manager_get() to obtain the #GdkDisplayManager singleton, but that should be rarely necessary. Typically, initializing GTK+ opens a display that you can work with without ever accessing the #GdkDisplayManager. The GDK library can be built with support for multiple backends. The #GdkDisplayManager object determines which backend is used at runtime. When writing backend-specific code that is supposed to work with multiple GDK backends, you have to consider both compile time and runtime. At compile time, use the #GDK_WINDOWING_X11, #GDK_WINDOWING_WIN32 macros, etc. to find out which backends are present in the GDK library you are building your application against. At runtime, use type-check macros like GDK_IS_X11_DISPLAY() to find out which backend is in use: ## Backend-specific code ## {#backend-specific} |[<!-- language="C" --> #ifdef GDK_WINDOWING_X11 if (GDK_IS_X11_DISPLAY (display)) { // make X11-specific calls here } else #endif #ifdef GDK_WINDOWING_QUARTZ if (GDK_IS_QUARTZ_DISPLAY (display)) { // make Quartz-specific calls here } else #endif g_error ("Unsupported GDK backend"); ]| Gets the singleton #GdkDisplayManager object. When called for the first time, this function consults the `GDK_BACKEND` environment variable to find out which of the supported GDK backends to use (in case GDK has been compiled with multiple backends). Applications can use gdk_set_allowed_backends() to limit what backends can be used. The global #GdkDisplayManager singleton; gdk_parse_args(), gdk_init(), or gdk_init_check() must have been called first. Gets the default #GdkDisplay. a #GdkDisplay, or %NULL if there is no default display. a #GdkDisplayManager List all currently open displays. a newly allocated #GSList of #GdkDisplay objects. Free with g_slist_free() when you are done with it. a #GdkDisplayManager Opens a display. a #GdkDisplay, or %NULL if the display could not be opened a #GdkDisplayManager the name of the display to open Sets @display as the default display. a #GdkDisplayManager a #GdkDisplay The ::display-opened signal is emitted when a display is opened. the opened display Used in #GdkDragContext to indicate what the destination should do with the dropped data. Means nothing, and should not be used. Copy the data. Move the data, i.e. first copy it, then delete it from the source using the DELETE target of the X selection protocol. Add a link to the data. Note that this is only useful if source and destination agree on what it means. Special action which tells the source that the destination will do something that the source doesn’t understand. Ask the user what to do with the data. Used in #GdkDragContext to the reason of a cancelled DND operation. There is no suitable drop target. Drag cancelled by the user Unspecified error. Determines the bitmask of actions proposed by the source if gdk_drag_context_get_suggested_action() returns %GDK_ACTION_ASK. the #GdkDragAction flags a #GdkDragContext Returns the destination window for the DND operation. a #GdkWindow a #GdkDragContext Returns the #GdkDevice associated to the drag context. The #GdkDevice associated to @context. a #GdkDragContext Returns the window on which the drag icon should be rendered during the drag operation. Note that the window may not be available until the drag operation has begun. GDK will move the window in accordance with the ongoing drag operation. The window is owned by @context and will be destroyed when the drag operation is over. the drag window, or %NULL a #GdkDragContext Returns the drag protocol that is used by this context. the drag protocol a #GdkDragContext Determines the action chosen by the drag destination. a #GdkDragAction value a #GdkDragContext Returns the #GdkWindow where the DND operation started. a #GdkWindow a #GdkDragContext Determines the suggested drag action of the context. a #GdkDragAction value a #GdkDragContext Retrieves the list of targets of the context. a #GList of targets a #GdkDragContext Requests the drag and drop operation to be managed by @context. When a drag and drop operation becomes managed, the #GdkDragContext will internally handle all input and source-side #GdkEventDND events as required by the windowing system. Once the drag and drop operation is managed, the drag context will emit the following signals: - The #GdkDragContext::action-changed signal whenever the final action to be performed by the drag and drop operation changes. - The #GdkDragContext::drop-performed signal after the user performs the drag and drop gesture (typically by releasing the mouse button). - The #GdkDragContext::dnd-finished signal after the drag and drop operation concludes (after all #GdkSelection transfers happen). - The #GdkDragContext::cancel signal if the drag and drop operation is finished but doesn't happen over an accepting destination, or is cancelled through other means. #TRUE if the drag and drop operation is managed. a #GdkDragContext Window to use for IPC messaging/events the actions supported by the drag source Associates a #GdkDevice to @context, so all Drag and Drop events for @context are emitted as if they came from this device. a #GdkDragContext a #GdkDevice Sets the position of the drag window that will be kept under the cursor hotspot. Initially, the hotspot is at the top left corner of the drag window. a #GdkDragContext x coordinate of the drag window hotspot y coordinate of the drag window hotspot A new action is being chosen for the drag and drop operation. This signal will only be emitted if the #GdkDragContext manages the drag and drop operation. See gdk_drag_context_manage_dnd() for more information. The action currently chosen The drag and drop operation was cancelled. This signal will only be emitted if the #GdkDragContext manages the drag and drop operation. See gdk_drag_context_manage_dnd() for more information. The reason the context was cancelled The drag and drop operation was finished, the drag destination finished reading all data. The drag source can now free all miscellaneous data. This signal will only be emitted if the #GdkDragContext manages the drag and drop operation. See gdk_drag_context_manage_dnd() for more information. The drag and drop operation was performed on an accepting client. This signal will only be emitted if the #GdkDragContext manages the drag and drop operation. See gdk_drag_context_manage_dnd() for more information. the time at which the drop happened. Used in #GdkDragContext to indicate the protocol according to which DND is done. no protocol. The Motif DND protocol. No longer supported The Xdnd protocol. An extension to the Xdnd protocol for unclaimed root window drops. The simple WM_DROPFILES protocol. The complex OLE2 DND protocol (not implemented). Intra-application DND. Wayland DND protocol. #GdkDrawingContext is an object that represents the current drawing state of a #GdkWindow. It's possible to use a #GdkDrawingContext to draw on a #GdkWindow via rendering API like Cairo or OpenGL. A #GdkDrawingContext can only be created by calling gdk_window_begin_draw_frame() and will be valid until a call to gdk_window_end_draw_frame(). #GdkDrawingContext is available since GDK 3.22 Retrieves a Cairo context to be used to draw on the #GdkWindow that created the #GdkDrawingContext. The returned context is guaranteed to be valid as long as the #GdkDrawingContext is valid, that is between a call to gdk_window_begin_draw_frame() and gdk_window_end_draw_frame(). a Cairo context to be used to draw the contents of the #GdkWindow. The context is owned by the #GdkDrawingContext and should not be destroyed Retrieves a copy of the clip region used when creating the @context. a Cairo region a #GdkDrawingContext Retrieves the window that created the drawing @context. a #GdkWindow a #GdkDrawingContext Checks whether the given #GdkDrawingContext is valid. %TRUE if the context is valid a #GdkDrawingContext The clip region applied to the drawing context. The #GdkWindow that created the drawing context. Use this macro as the return value for continuing the propagation of an event handler. Use this macro as the return value for stopping the propagation of an event handler. A #GdkEvent contains a union of all of the event types, and allows access to the data fields in a number of ways. The event type is always the first field in all of the event types, and can always be accessed with the following code, no matter what type of event it is: |[<!-- language="C" --> GdkEvent *event; GdkEventType type; type = event->type; ]| To access other fields of the event, the pointer to the event can be cast to the appropriate event type, or the union member name can be used. For example if the event type is %GDK_BUTTON_PRESS then the x coordinate of the button press can be accessed with: |[<!-- language="C" --> GdkEvent *event; gdouble x; x = ((GdkEventButton*)event)->x; ]| or: |[<!-- language="C" --> GdkEvent *event; gdouble x; x = event->button.x; ]| the #GdkEventType a #GdkEventAny a #GdkEventExpose a #GdkEventVisibility a #GdkEventMotion a #GdkEventButton a #GdkEventTouch a #GdkEventScroll a #GdkEventKey a #GdkEventCrossing a #GdkEventFocus a #GdkEventConfigure a #GdkEventProperty a #GdkEventSelection a #GdkEventOwnerChange a #GdkEventProximity a #GdkEventDND a #GdkEventWindowState a #GdkEventSetting a #GdkEventGrabBroken a #GdkEventTouchpadSwipe a #GdkEventTouchpadPinch a #GdkEventPadButton a #GdkEventPadAxis a #GdkEventPadGroupMode Creates a new event of the given type. All fields are set to 0. a newly-allocated #GdkEvent. The returned #GdkEvent should be freed with gdk_event_free(). a #GdkEventType If both events contain X/Y information, this function will return %TRUE and return in @angle the relative angle from @event1 to @event2. The rotation direction for positive angles is from the positive X axis towards the positive Y axis. %TRUE if the angle could be calculated. first #GdkEvent second #GdkEvent return location for the relative angle between both events If both events contain X/Y information, the center of both coordinates will be returned in @x and @y. %TRUE if the center could be calculated. first #GdkEvent second #GdkEvent return location for the X coordinate of the center return location for the Y coordinate of the center If both events have X/Y information, the distance between both coordinates (as in a straight line going from @event1 to @event2) will be returned. %TRUE if the distance could be calculated. first #GdkEvent second #GdkEvent return location for the distance Copies a #GdkEvent, copying or incrementing the reference count of the resources associated with it (e.g. #GdkWindow’s and strings). a copy of @event. The returned #GdkEvent should be freed with gdk_event_free(). a #GdkEvent Frees a #GdkEvent, freeing or decrementing any resources associated with it. Note that this function should only be called with events returned from functions such as gdk_event_peek(), gdk_event_get(), gdk_event_copy() and gdk_event_new(). a #GdkEvent. Extract the axis value for a particular axis use from an event structure. %TRUE if the specified axis was found, otherwise %FALSE a #GdkEvent the axis use to look for location to store the value found Extract the button number from an event. %TRUE if the event delivered a button number a #GdkEvent location to store mouse button number Extracts the click count from an event. %TRUE if the event delivered a click count a #GdkEvent location to store click count Extract the event window relative x/y coordinates from an event. %TRUE if the event delivered event window coordinates a #GdkEvent location to put event window x coordinate location to put event window y coordinate If the event contains a “device” field, this function will return it, else it will return %NULL. a #GdkDevice, or %NULL. a #GdkEvent. If the event was generated by a device that supports different tools (eg. a tablet), this function will return a #GdkDeviceTool representing the tool that caused the event. Otherwise, %NULL will be returned. Note: the #GdkDeviceTool<!-- -->s will be constant during the application lifetime, if settings must be stored persistently across runs, see gdk_device_tool_get_serial() The current device tool, or %NULL a #GdkEvent If @event if of type %GDK_TOUCH_BEGIN, %GDK_TOUCH_UPDATE, %GDK_TOUCH_END or %GDK_TOUCH_CANCEL, returns the #GdkEventSequence to which the event belongs. Otherwise, return %NULL. the event sequence that the event belongs to a #GdkEvent Retrieves the type of the event. a #GdkEventType a #GdkEvent Extracts the hardware keycode from an event. Also see gdk_event_get_scancode(). %TRUE if the event delivered a hardware keycode a #GdkEvent location to store the keycode Extracts the keyval from an event. %TRUE if the event delivered a key symbol a #GdkEvent location to store the keyval #event: a #GdkEvent Returns whether this event is an 'emulated' pointer event (typically from a touch event), as opposed to a real one. %TRUE if this event is emulated Extract the root window relative x/y coordinates from an event. %TRUE if the event delivered root window coordinates a #GdkEvent location to put root window x coordinate location to put root window y coordinate Gets the keyboard low-level scancode of a key event. This is usually hardware_keycode. On Windows this is the high word of WM_KEY{DOWN,UP} lParam which contains the scancode and some extended flags. The associated keyboard scancode or 0 a #GdkEvent Returns the screen for the event. The screen is typically the screen for `event->any.window`, but for events such as mouse events, it is the screen where the pointer was when the event occurs - that is, the screen which has the root window to which `event->motion.x_root` and `event->motion.y_root` are relative. the screen for the event a #GdkEvent Retrieves the scroll deltas from a #GdkEvent See also: gdk_event_get_scroll_direction() %TRUE if the event contains smooth scroll information and %FALSE otherwise a #GdkEvent return location for X delta return location for Y delta Extracts the scroll direction from an event. If @event is not of type %GDK_SCROLL, the contents of @direction are undefined. If you wish to handle both discrete and smooth scrolling, you should check the return value of this function, or of gdk_event_get_scroll_deltas(); for instance: |[<!-- language="C" --> GdkScrollDirection direction; double vscroll_factor = 0.0; double x_scroll, y_scroll; if (gdk_event_get_scroll_direction (event, &direction)) { // Handle discrete scrolling with a known constant delta; const double delta = 12.0; switch (direction) { case GDK_SCROLL_UP: vscroll_factor = -delta; break; case GDK_SCROLL_DOWN: vscroll_factor = delta; break; default: // no scrolling break; } } else if (gdk_event_get_scroll_deltas (event, &x_scroll, &y_scroll)) { // Handle smooth scrolling directly vscroll_factor = y_scroll; } ]| %TRUE if the event delivered a scroll direction and %FALSE otherwise a #GdkEvent location to store the scroll direction Returns the #GdkSeat this event was generated for. The #GdkSeat of this event a #GdkEvent This function returns the hardware (slave) #GdkDevice that has triggered the event, falling back to the virtual (master) device (as in gdk_event_get_device()) if the event wasn’t caused by interaction with a hardware device. This may happen for example in synthesized crossing events after a #GdkWindow updates its geometry or a grab is acquired/released. If the event does not contain a device field, this function will return %NULL. a #GdkDevice, or %NULL. a #GdkEvent If the event contains a “state” field, puts that field in @state. Otherwise stores an empty state (0). Returns %TRUE if there was a state field in the event. @event may be %NULL, in which case it’s treated as if the event had no state field. %TRUE if there was a state field in the event a #GdkEvent or %NULL return location for state Returns the time stamp from @event, if there is one; otherwise returns #GDK_CURRENT_TIME. If @event is %NULL, returns #GDK_CURRENT_TIME. time stamp field from @event a #GdkEvent Extracts the #GdkWindow associated with an event. The #GdkWindow associated with the event a #GdkEvent Check whether a scroll event is a stop scroll event. Scroll sequences with smooth scroll information may provide a stop scroll event once the interaction with the device finishes, e.g. by lifting a finger. This stop scroll event is the signal that a widget may trigger kinetic scrolling based on the current velocity. Stop scroll events always have a a delta of 0/0. %TRUE if the event is a scroll stop event a #GdkEvent Appends a copy of the given event onto the front of the event queue for event->any.window’s display, or the default event queue if event->any.window is %NULL. See gdk_display_put_event(). a #GdkEvent. Sets the device for @event to @device. The event must have been allocated by GTK+, for instance, by gdk_event_copy(). a #GdkEvent a #GdkDevice Sets the device tool for this event, should be rarely used. a #GdkEvent tool to set on the event, or %NULL Sets the screen for @event to @screen. The event must have been allocated by GTK+, for instance, by gdk_event_copy(). a #GdkEvent a #GdkScreen Sets the slave device for @event to @device. The event must have been allocated by GTK+, for instance by gdk_event_copy(). a #GdkEvent a #GdkDevice This function returns whether a #GdkEventButton should trigger a context menu, according to platform conventions. The right mouse button always triggers context menus. Additionally, if gdk_keymap_get_modifier_mask() returns a non-0 mask for %GDK_MODIFIER_INTENT_CONTEXT_MENU, then the left mouse button will also trigger a context menu if this modifier is pressed. This function should always be used instead of simply checking for event->button == %GDK_BUTTON_SECONDARY. %TRUE if the event should trigger a context menu. a #GdkEvent, currently only button events are meaningful values Checks all open displays for a #GdkEvent to process,to be processed on, fetching events from the windowing system if necessary. See gdk_display_get_event(). the next #GdkEvent to be processed, or %NULL if no events are pending. The returned #GdkEvent should be freed with gdk_event_free(). Sets the function to call to handle all events from GDK. Note that GTK+ uses this to install its own event handler, so it is usually not useful for GTK+ applications. (Although an application can call this function then call gtk_main_do_event() to pass events to GTK+.) the function to call to handle events from GDK. user data to pass to the function. the function to call when the handler function is removed, i.e. when gdk_event_handler_set() is called with another event handler. If there is an event waiting in the event queue of some open display, returns a copy of it. See gdk_display_peek_event(). a copy of the first #GdkEvent on some event queue, or %NULL if no events are in any queues. The returned #GdkEvent should be freed with gdk_event_free(). Request more motion notifies if @event is a motion notify hint event. This function should be used instead of gdk_window_get_pointer() to request further motion notifies, because it also works for extension events where motion notifies are provided for devices other than the core pointer. Coordinate extraction, processing and requesting more motion events from a %GDK_MOTION_NOTIFY event usually works like this: |[<!-- language="C" --> { // motion_event handler x = motion_event->x; y = motion_event->y; // handle (x,y) motion gdk_event_request_motions (motion_event); // handles is_hint events } ]| a valid #GdkEvent Contains the fields which are common to all event structs. Any event pointer can safely be cast to a pointer to a #GdkEventAny to access these fields. the type of the event. the window which received the event. %TRUE if the event was sent explicitly. Used for button press and button release events. The @type field will be one of %GDK_BUTTON_PRESS, %GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS or %GDK_BUTTON_RELEASE, Double and triple-clicks result in a sequence of events being received. For double-clicks the order of events will be: - %GDK_BUTTON_PRESS - %GDK_BUTTON_RELEASE - %GDK_BUTTON_PRESS - %GDK_2BUTTON_PRESS - %GDK_BUTTON_RELEASE Note that the first click is received just like a normal button press, while the second click results in a %GDK_2BUTTON_PRESS being received just after the %GDK_BUTTON_PRESS. Triple-clicks are very similar to double-clicks, except that %GDK_3BUTTON_PRESS is inserted after the third click. The order of the events is: - %GDK_BUTTON_PRESS - %GDK_BUTTON_RELEASE - %GDK_BUTTON_PRESS - %GDK_2BUTTON_PRESS - %GDK_BUTTON_RELEASE - %GDK_BUTTON_PRESS - %GDK_3BUTTON_PRESS - %GDK_BUTTON_RELEASE For a double click to occur, the second button press must occur within 1/4 of a second of the first. For a triple click to occur, the third button press must also occur within 1/2 second of the first button press. the type of the event (%GDK_BUTTON_PRESS, %GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS or %GDK_BUTTON_RELEASE). the window which received the event. %TRUE if the event was sent explicitly. the time of the event in milliseconds. the x coordinate of the pointer relative to the window. the y coordinate of the pointer relative to the window. @x, @y translated to the axes of @device, or %NULL if @device is the mouse. a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt) and the pointer buttons. See #GdkModifierType. the button which was pressed or released, numbered from 1 to 5. Normally button 1 is the left mouse button, 2 is the middle button, and 3 is the right button. On 2-button mice, the middle button can often be simulated by pressing both mouse buttons together. the master device that the event originated from. Use gdk_event_get_source_device() to get the slave device. the x coordinate of the pointer relative to the root of the screen. the y coordinate of the pointer relative to the root of the screen. Generated when a window size or position has changed. the type of the event (%GDK_CONFIGURE). the window which received the event. %TRUE if the event was sent explicitly. the new x coordinate of the window, relative to its parent. the new y coordinate of the window, relative to its parent. the new width of the window. the new height of the window. Generated when the pointer enters or leaves a window. the type of the event (%GDK_ENTER_NOTIFY or %GDK_LEAVE_NOTIFY). the window which received the event. %TRUE if the event was sent explicitly. the window that was entered or left. the time of the event in milliseconds. the x coordinate of the pointer relative to the window. the y coordinate of the pointer relative to the window. the x coordinate of the pointer relative to the root of the screen. the y coordinate of the pointer relative to the root of the screen. the crossing mode (%GDK_CROSSING_NORMAL, %GDK_CROSSING_GRAB, %GDK_CROSSING_UNGRAB, %GDK_CROSSING_GTK_GRAB, %GDK_CROSSING_GTK_UNGRAB or %GDK_CROSSING_STATE_CHANGED). %GDK_CROSSING_GTK_GRAB, %GDK_CROSSING_GTK_UNGRAB, and %GDK_CROSSING_STATE_CHANGED were added in 2.14 and are always synthesized, never native. the kind of crossing that happened (%GDK_NOTIFY_INFERIOR, %GDK_NOTIFY_ANCESTOR, %GDK_NOTIFY_VIRTUAL, %GDK_NOTIFY_NONLINEAR or %GDK_NOTIFY_NONLINEAR_VIRTUAL). %TRUE if @window is the focus window or an inferior. a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt) and the pointer buttons. See #GdkModifierType. Generated during DND operations. the type of the event (%GDK_DRAG_ENTER, %GDK_DRAG_LEAVE, %GDK_DRAG_MOTION, %GDK_DRAG_STATUS, %GDK_DROP_START or %GDK_DROP_FINISHED). the window which received the event. %TRUE if the event was sent explicitly. the #GdkDragContext for the current DND operation. the time of the event in milliseconds. the x coordinate of the pointer relative to the root of the screen, only set for %GDK_DRAG_MOTION and %GDK_DROP_START. the y coordinate of the pointer relative to the root of the screen, only set for %GDK_DRAG_MOTION and %GDK_DROP_START. Generated when all or part of a window becomes visible and needs to be redrawn. the type of the event (%GDK_EXPOSE or %GDK_DAMAGE). the window which received the event. %TRUE if the event was sent explicitly. bounding box of @region. the region that needs to be redrawn. the number of contiguous %GDK_EXPOSE events following this one. The only use for this is “exposure compression”, i.e. handling all contiguous %GDK_EXPOSE events in one go, though GDK performs some exposure compression so this is not normally needed. Describes a change of keyboard focus. the type of the event (%GDK_FOCUS_CHANGE). the window which received the event. %TRUE if the event was sent explicitly. %TRUE if the window has gained the keyboard focus, %FALSE if it has lost the focus. Specifies the type of function passed to gdk_event_handler_set() to handle all GDK events. the #GdkEvent to process. user data set when the event handler was installed with gdk_event_handler_set(). Generated when a pointer or keyboard grab is broken. On X11, this happens when the grab window becomes unviewable (i.e. it or one of its ancestors is unmapped), or if the same application grabs the pointer or keyboard again. Note that implicit grabs (which are initiated by button presses) can also cause #GdkEventGrabBroken events. the type of the event (%GDK_GRAB_BROKEN) the window which received the event, i.e. the window that previously owned the grab %TRUE if the event was sent explicitly. %TRUE if a keyboard grab was broken, %FALSE if a pointer grab was broken %TRUE if the broken grab was implicit If this event is caused by another grab in the same application, @grab_window contains the new grab window. Otherwise @grab_window is %NULL. Describes a key press or key release event. the type of the event (%GDK_KEY_PRESS or %GDK_KEY_RELEASE). the window which received the event. %TRUE if the event was sent explicitly. the time of the event in milliseconds. a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt) and the pointer buttons. See #GdkModifierType. the key that was pressed or released. See the `gdk/gdkkeysyms.h` header file for a complete list of GDK key codes. the length of @string. a string containing an approximation of the text that would result from this keypress. The only correct way to handle text input of text is using input methods (see #GtkIMContext), so this field is deprecated and should never be used. (gdk_unicode_to_keyval() provides a non-deprecated way of getting an approximate translation for a key.) The string is encoded in the encoding of the current locale (Note: this for backwards compatibility: strings in GTK+ and GDK are typically in UTF-8.) and NUL-terminated. In some cases, the translation of the key code will be a single NUL byte, in which case looking at @length is necessary to distinguish it from the an empty translation. the raw code of the key that was pressed or released. the keyboard group. a flag that indicates if @hardware_keycode is mapped to a modifier. Since 2.10 A set of bit-flags to indicate which events a window is to receive. Most of these masks map onto one or more of the #GdkEventType event types above. See the [input handling overview][chap-input-handling] for details of [event masks][event-masks] and [event propagation][event-propagation]. %GDK_POINTER_MOTION_HINT_MASK is deprecated. It is a special mask to reduce the number of %GDK_MOTION_NOTIFY events received. When using %GDK_POINTER_MOTION_HINT_MASK, fewer %GDK_MOTION_NOTIFY events will be sent, some of which are marked as a hint (the is_hint member is %TRUE). To receive more motion events after a motion hint event, the application needs to asks for more, by calling gdk_event_request_motions(). Since GTK 3.8, motion events are already compressed by default, independent of this mechanism. This compression can be disabled with gdk_window_set_event_compression(). See the documentation of that function for details. If %GDK_TOUCH_MASK is enabled, the window will receive touch events from touch-enabled devices. Those will come as sequences of #GdkEventTouch with type %GDK_TOUCH_UPDATE, enclosed by two events with type %GDK_TOUCH_BEGIN and %GDK_TOUCH_END (or %GDK_TOUCH_CANCEL). gdk_event_get_event_sequence() returns the event sequence for these events, so different sequences may be distinguished. receive expose events receive all pointer motion events deprecated. see the explanation above receive pointer motion events while any button is pressed receive pointer motion events while 1 button is pressed receive pointer motion events while 2 button is pressed receive pointer motion events while 3 button is pressed receive button press events receive button release events receive key press events receive key release events receive window enter events receive window leave events receive focus change events receive events about window configuration change receive property change events receive visibility change events receive proximity in events receive proximity out events receive events about window configuration changes of child windows receive scroll events receive touch events. Since 3.4 receive smooth scrolling events. Since 3.4 receive touchpad gesture events. Since 3.18 receive tablet pad events. Since 3.22 the combination of all the above event masks. Generated when the pointer moves. the type of the event. the window which received the event. %TRUE if the event was sent explicitly. the time of the event in milliseconds. the x coordinate of the pointer relative to the window. the y coordinate of the pointer relative to the window. @x, @y translated to the axes of @device, or %NULL if @device is the mouse. a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt) and the pointer buttons. See #GdkModifierType. set to 1 if this event is just a hint, see the %GDK_POINTER_MOTION_HINT_MASK value of #GdkEventMask. the master device that the event originated from. Use gdk_event_get_source_device() to get the slave device. the x coordinate of the pointer relative to the root of the screen. the y coordinate of the pointer relative to the root of the screen. Generated when the owner of a selection changes. On X11, this information is only available if the X server supports the XFIXES extension. the type of the event (%GDK_OWNER_CHANGE). the window which received the event %TRUE if the event was sent explicitly. the new owner of the selection, or %NULL if there is none the reason for the ownership change as a #GdkOwnerChange value the atom identifying the selection the timestamp of the event the time at which the selection ownership was taken over Generated during %GDK_SOURCE_TABLET_PAD interaction with tactile sensors. the type of the event (%GDK_PAD_RING or %GDK_PAD_STRIP). the window which received the event. %TRUE if the event was sent explicitly. the time of the event in milliseconds. the pad group the ring/strip belongs to. A %GDK_SOURCE_TABLET_PAD device may have one or more groups containing a set of buttons/rings/strips each. number of strip/ring that was interacted. This number is 0-indexed. The current mode of @group. Different groups in a %GDK_SOURCE_TABLET_PAD device may have different current modes. The current value for the given axis. Generated during %GDK_SOURCE_TABLET_PAD button presses and releases. the type of the event (%GDK_PAD_BUTTON_PRESS or %GDK_PAD_BUTTON_RELEASE). the window which received the event. %TRUE if the event was sent explicitly. the time of the event in milliseconds. the pad group the button belongs to. A %GDK_SOURCE_TABLET_PAD device may have one or more groups containing a set of buttons/rings/strips each. The pad button that was pressed. The current mode of @group. Different groups in a %GDK_SOURCE_TABLET_PAD device may have different current modes. Generated during %GDK_SOURCE_TABLET_PAD mode switches in a group. the type of the event (%GDK_PAD_GROUP_MODE). the window which received the event. %TRUE if the event was sent explicitly. the time of the event in milliseconds. the pad group that is switching mode. A %GDK_SOURCE_TABLET_PAD device may have one or more groups containing a set of buttons/rings/strips each. The new mode of @group. Different groups in a %GDK_SOURCE_TABLET_PAD device may have different current modes. Describes a property change on a window. the type of the event (%GDK_PROPERTY_NOTIFY). the window which received the event. %TRUE if the event was sent explicitly. the property that was changed. the time of the event in milliseconds. whether the property was changed (%GDK_PROPERTY_NEW_VALUE) or deleted (%GDK_PROPERTY_DELETE). Proximity events are generated when using GDK’s wrapper for the XInput extension. The XInput extension is an add-on for standard X that allows you to use nonstandard devices such as graphics tablets. A proximity event indicates that the stylus has moved in or out of contact with the tablet, or perhaps that the user’s finger has moved in or out of contact with a touch screen. This event type will be used pretty rarely. It only is important for XInput aware programs that are drawing their own cursor. the type of the event (%GDK_PROXIMITY_IN or %GDK_PROXIMITY_OUT). the window which received the event. %TRUE if the event was sent explicitly. the time of the event in milliseconds. the master device that the event originated from. Use gdk_event_get_source_device() to get the slave device. Generated from button presses for the buttons 4 to 7. Wheel mice are usually configured to generate button press events for buttons 4 and 5 when the wheel is turned. Some GDK backends can also generate “smooth” scroll events, which can be recognized by the %GDK_SCROLL_SMOOTH scroll direction. For these, the scroll deltas can be obtained with gdk_event_get_scroll_deltas(). the type of the event (%GDK_SCROLL). the window which received the event. %TRUE if the event was sent explicitly. the time of the event in milliseconds. the x coordinate of the pointer relative to the window. the y coordinate of the pointer relative to the window. a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt) and the pointer buttons. See #GdkModifierType. the direction to scroll to (one of %GDK_SCROLL_UP, %GDK_SCROLL_DOWN, %GDK_SCROLL_LEFT, %GDK_SCROLL_RIGHT or %GDK_SCROLL_SMOOTH). the master device that the event originated from. Use gdk_event_get_source_device() to get the slave device. the x coordinate of the pointer relative to the root of the screen. the y coordinate of the pointer relative to the root of the screen. the x coordinate of the scroll delta the y coordinate of the scroll delta Generated when a selection is requested or ownership of a selection is taken over by another client application. the type of the event (%GDK_SELECTION_CLEAR, %GDK_SELECTION_NOTIFY or %GDK_SELECTION_REQUEST). the window which received the event. %TRUE if the event was sent explicitly. the selection. the target to which the selection should be converted. the property in which to place the result of the conversion. the time of the event in milliseconds. the window on which to place @property or %NULL if none. Generated when a setting is modified. the type of the event (%GDK_SETTING). the window which received the event. %TRUE if the event was sent explicitly. what happened to the setting (%GDK_SETTING_ACTION_NEW, %GDK_SETTING_ACTION_CHANGED or %GDK_SETTING_ACTION_DELETED). the name of the setting. Used for touch events. @type field will be one of %GDK_TOUCH_BEGIN, %GDK_TOUCH_UPDATE, %GDK_TOUCH_END or %GDK_TOUCH_CANCEL. Touch events are grouped into sequences by means of the @sequence field, which can also be obtained with gdk_event_get_event_sequence(). Each sequence begins with a %GDK_TOUCH_BEGIN event, followed by any number of %GDK_TOUCH_UPDATE events, and ends with a %GDK_TOUCH_END (or %GDK_TOUCH_CANCEL) event. With multitouch devices, there may be several active sequences at the same time. the type of the event (%GDK_TOUCH_BEGIN, %GDK_TOUCH_UPDATE, %GDK_TOUCH_END, %GDK_TOUCH_CANCEL) the window which received the event %TRUE if the event was sent explicitly. the time of the event in milliseconds. the x coordinate of the pointer relative to the window the y coordinate of the pointer relative to the window @x, @y translated to the axes of @device, or %NULL if @device is the mouse a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt) and the pointer buttons. See #GdkModifierType the event sequence that the event belongs to whether the event should be used for emulating pointer event the master device that the event originated from. Use gdk_event_get_source_device() to get the slave device. the x coordinate of the pointer relative to the root of the screen the y coordinate of the pointer relative to the root of the screen Generated during touchpad swipe gestures. the type of the event (%GDK_TOUCHPAD_PINCH) the window which received the event %TRUE if the event was sent explicitly the current phase of the gesture The number of fingers triggering the pinch the time of the event in milliseconds The X coordinate of the pointer The Y coordinate of the pointer Movement delta in the X axis of the swipe focal point Movement delta in the Y axis of the swipe focal point The angle change in radians, negative angles denote counter-clockwise movements The current scale, relative to that at the time of the corresponding %GDK_TOUCHPAD_GESTURE_PHASE_BEGIN event The X coordinate of the pointer, relative to the root of the screen. The Y coordinate of the pointer, relative to the root of the screen. a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt) and the pointer buttons. See #GdkModifierType. Generated during touchpad swipe gestures. the type of the event (%GDK_TOUCHPAD_SWIPE) the window which received the event %TRUE if the event was sent explicitly the current phase of the gesture The number of fingers triggering the swipe the time of the event in milliseconds The X coordinate of the pointer The Y coordinate of the pointer Movement delta in the X axis of the swipe focal point Movement delta in the Y axis of the swipe focal point The X coordinate of the pointer, relative to the root of the screen. The Y coordinate of the pointer, relative to the root of the screen. a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt) and the pointer buttons. See #GdkModifierType. Specifies the type of the event. Do not confuse these events with the signals that GTK+ widgets emit. Although many of these events result in corresponding signals being emitted, the events are often transformed or filtered along the way. In some language bindings, the values %GDK_2BUTTON_PRESS and %GDK_3BUTTON_PRESS would translate into something syntactically invalid (eg `Gdk.EventType.2ButtonPress`, where a symbol is not allowed to start with a number). In that case, the aliases %GDK_DOUBLE_BUTTON_PRESS and %GDK_TRIPLE_BUTTON_PRESS can be used instead. a special code to indicate a null event. the window manager has requested that the toplevel window be hidden or destroyed, usually when the user clicks on a special icon in the title bar. the window has been destroyed. all or part of the window has become visible and needs to be redrawn. the pointer (usually a mouse) has moved. a mouse button has been pressed. a mouse button has been double-clicked (clicked twice within a short period of time). Note that each click also generates a %GDK_BUTTON_PRESS event. alias for %GDK_2BUTTON_PRESS, added in 3.6. a mouse button has been clicked 3 times in a short period of time. Note that each click also generates a %GDK_BUTTON_PRESS event. alias for %GDK_3BUTTON_PRESS, added in 3.6. a mouse button has been released. a key has been pressed. a key has been released. the pointer has entered the window. the pointer has left the window. the keyboard focus has entered or left the window. the size, position or stacking order of the window has changed. Note that GTK+ discards these events for %GDK_WINDOW_CHILD windows. the window has been mapped. the window has been unmapped. a property on the window has been changed or deleted. the application has lost ownership of a selection. another application has requested a selection. a selection has been received. an input device has moved into contact with a sensing surface (e.g. a touchscreen or graphics tablet). an input device has moved out of contact with a sensing surface. the mouse has entered the window while a drag is in progress. the mouse has left the window while a drag is in progress. the mouse has moved in the window while a drag is in progress. the status of the drag operation initiated by the window has changed. a drop operation onto the window has started. the drop operation initiated by the window has completed. a message has been received from another application. the window visibility status has changed. the scroll wheel was turned the state of a window has changed. See #GdkWindowState for the possible window states a setting has been modified. the owner of a selection has changed. This event type was added in 2.6 a pointer or keyboard grab was broken. This event type was added in 2.8. the content of the window has been changed. This event type was added in 2.14. A new touch event sequence has just started. This event type was added in 3.4. A touch event sequence has been updated. This event type was added in 3.4. A touch event sequence has finished. This event type was added in 3.4. A touch event sequence has been canceled. This event type was added in 3.4. A touchpad swipe gesture event, the current state is determined by its phase field. This event type was added in 3.18. A touchpad pinch gesture event, the current state is determined by its phase field. This event type was added in 3.18. A tablet pad button press event. This event type was added in 3.22. A tablet pad button release event. This event type was added in 3.22. A tablet pad axis event from a "ring". This event type was added in 3.22. A tablet pad axis event from a "strip". This event type was added in 3.22. A tablet pad group mode change. This event type was added in 3.22. marks the end of the GdkEventType enumeration. Added in 2.18 Generated when the window visibility status has changed. Modern composited windowing systems with pervasive transparency make it impossible to track the visibility of a window reliably, so this event can not be guaranteed to provide useful information. the type of the event (%GDK_VISIBILITY_NOTIFY). the window which received the event. %TRUE if the event was sent explicitly. the new visibility state (%GDK_VISIBILITY_FULLY_OBSCURED, %GDK_VISIBILITY_PARTIAL or %GDK_VISIBILITY_UNOBSCURED). Generated when the state of a toplevel window changes. the type of the event (%GDK_WINDOW_STATE). the window which received the event. %TRUE if the event was sent explicitly. mask specifying what flags have changed. the new window state, a combination of #GdkWindowState bits. Specifies the type of function used to filter native events before they are converted to GDK events. When a filter is called, @event is unpopulated, except for `event->window`. The filter may translate the native event to a GDK event and store the result in @event, or handle it without translation. If the filter translates the event and processing should continue, it should return %GDK_FILTER_TRANSLATE. a #GdkFilterReturn value. the native event to filter. the GDK event to which the X event will be translated. user data set when the filter was installed. Specifies the result of applying a #GdkFilterFunc to a native event. event not handled, continue processing. native event translated into a GDK event and stored in the `event` structure that was passed in. event handled, terminate processing. A #GdkFrameClock tells the application when to update and repaint a window. This may be synced to the vertical refresh rate of the monitor, for example. Even when the frame clock uses a simple timer rather than a hardware-based vertical sync, the frame clock helps because it ensures everything paints at the same time (reducing the total number of frames). The frame clock can also automatically stop painting when it knows the frames will not be visible, or scale back animation framerates. #GdkFrameClock is designed to be compatible with an OpenGL-based implementation or with mozRequestAnimationFrame in Firefox, for example. A frame clock is idle until someone requests a frame with gdk_frame_clock_request_phase(). At some later point that makes sense for the synchronization being implemented, the clock will process a frame and emit signals for each phase that has been requested. (See the signals of the #GdkFrameClock class for documentation of the phases. %GDK_FRAME_CLOCK_PHASE_UPDATE and the #GdkFrameClock::update signal are most interesting for application writers, and are used to update the animations, using the frame time given by gdk_frame_clock_get_frame_time(). The frame time is reported in microseconds and generally in the same timescale as g_get_monotonic_time(), however, it is not the same as g_get_monotonic_time(). The frame time does not advance during the time a frame is being painted, and outside of a frame, an attempt is made so that all calls to gdk_frame_clock_get_frame_time() that are called at a “similar” time get the same value. This means that if different animations are timed by looking at the difference in time between an initial value from gdk_frame_clock_get_frame_time() and the value inside the #GdkFrameClock::update signal of the clock, they will stay exactly synchronized. Starts updates for an animation. Until a matching call to gdk_frame_clock_end_updating() is made, the frame clock will continually request a new frame with the %GDK_FRAME_CLOCK_PHASE_UPDATE phase. This function may be called multiple times and frames will be requested until gdk_frame_clock_end_updating() is called the same number of times. a #GdkFrameClock Stops updates for an animation. See the documentation for gdk_frame_clock_begin_updating(). a #GdkFrameClock Gets the frame timings for the current frame. the #GdkFrameTimings for the frame currently being processed, or even no frame is being processed, for the previous frame. Before any frames have been processed, returns %NULL. a #GdkFrameClock A #GdkFrameClock maintains a 64-bit counter that increments for each frame drawn. inside frame processing, the value of the frame counter for the current frame. Outside of frame processing, the frame counter for the last frame. a #GdkFrameClock Gets the time that should currently be used for animations. Inside the processing of a frame, it’s the time used to compute the animation position of everything in a frame. Outside of a frame, it's the time of the conceptual “previous frame,” which may be either the actual previous frame time, or if that’s too old, an updated time. a timestamp in microseconds, in the timescale of of g_get_monotonic_time(). a #GdkFrameClock #GdkFrameClock internally keeps a history of #GdkFrameTimings objects for recent frames that can be retrieved with gdk_frame_clock_get_timings(). The set of stored frames is the set from the counter values given by gdk_frame_clock_get_history_start() and gdk_frame_clock_get_frame_counter(), inclusive. the frame counter value for the oldest frame that is available in the internal frame history of the #GdkFrameClock. a #GdkFrameClock Using the frame history stored in the frame clock, finds the last known presentation time and refresh interval, and assuming that presentation times are separated by the refresh interval, predicts a presentation time that is a multiple of the refresh interval after the last presentation time, and later than @base_time. a #GdkFrameClock base time for determining a presentaton time a location to store the determined refresh interval, or %NULL. A default refresh interval of 1/60th of a second will be stored if no history is present. a location to store the next candidate presentation time after the given base time. 0 will be will be stored if no history is present. Retrieves a #GdkFrameTimings object holding timing information for the current frame or a recent frame. The #GdkFrameTimings object may not yet be complete: see gdk_frame_timings_get_complete(). the #GdkFrameTimings object for the specified frame, or %NULL if it is not available. See gdk_frame_clock_get_history_start(). a #GdkFrameClock the frame counter value identifying the frame to be received. Asks the frame clock to run a particular phase. The signal corresponding the requested phase will be emitted the next time the frame clock processes. Multiple calls to gdk_frame_clock_request_phase() will be combined together and only one frame processed. If you are displaying animated content and want to continually request the %GDK_FRAME_CLOCK_PHASE_UPDATE phase for a period of time, you should use gdk_frame_clock_begin_updating() instead, since this allows GTK+ to adjust system parameters to get maximally smooth animations. a #GdkFrameClock the phase that is requested This signal ends processing of the frame. Applications should generally not handle this signal. This signal begins processing of the frame. Applications should generally not handle this signal. This signal is used to flush pending motion events that are being batched up and compressed together. Applications should not handle this signal. This signal is emitted as the second step of toolkit and application processing of the frame. Any work to update sizes and positions of application elements should be performed. GTK+ normally handles this internally. This signal is emitted as the third step of toolkit and application processing of the frame. The frame is repainted. GDK normally handles this internally and produces expose events, which are turned into GTK+ #GtkWidget::draw signals. This signal is emitted after processing of the frame is finished, and is handled internally by GTK+ to resume normal event processing. Applications should not handle this signal. This signal is emitted as the first step of toolkit and application processing of the frame. Animations should be updated using gdk_frame_clock_get_frame_time(). Applications can connect directly to this signal, or use gtk_widget_add_tick_callback() as a more convenient interface. #GdkFrameClockPhase is used to represent the different paint clock phases that can be requested. The elements of the enumeration correspond to the signals of #GdkFrameClock. no phase corresponds to GdkFrameClock::flush-events. Should not be handled by applications. corresponds to GdkFrameClock::before-paint. Should not be handled by applications. corresponds to GdkFrameClock::update. corresponds to GdkFrameClock::layout. corresponds to GdkFrameClock::paint. corresponds to GdkFrameClock::resume-events. Should not be handled by applications. corresponds to GdkFrameClock::after-paint. Should not be handled by applications. A #GdkFrameTimings object holds timing information for a single frame of the application’s displays. To retrieve #GdkFrameTimings objects, use gdk_frame_clock_get_timings() or gdk_frame_clock_get_current_timings(). The information in #GdkFrameTimings is useful for precise synchronization of video with the event or audio streams, and for measuring quality metrics for the application’s display, such as latency and jitter. The timing information in a #GdkFrameTimings is filled in incrementally as the frame as drawn and passed off to the window system for processing and display to the user. The accessor functions for #GdkFrameTimings can return 0 to indicate an unavailable value for two reasons: either because the information is not yet available, or because it isn't available at all. Once gdk_frame_timings_get_complete() returns %TRUE for a frame, you can be certain that no further values will become available and be stored in the #GdkFrameTimings. %TRUE if all information that will be available for the frame has been filled in. a #GdkFrameTimings Gets the frame counter value of the #GdkFrameClock when this this frame was drawn. the frame counter value for this frame a #GdkFrameTimings Returns the frame time for the frame. This is the time value that is typically used to time animations for the frame. See gdk_frame_clock_get_frame_time(). the frame time for the frame, in the timescale of g_get_monotonic_time() A #GdkFrameTimings Gets the predicted time at which this frame will be displayed. Although no predicted time may be available, if one is available, it will be available while the frame is being generated, in contrast to gdk_frame_timings_get_presentation_time(), which is only available after the frame has been presented. In general, if you are simply animating, you should use gdk_frame_clock_get_frame_time() rather than this function, but this function is useful for applications that want exact control over latency. For example, a movie player may want this information for Audio/Video synchronization. The predicted time at which the frame will be presented, in the timescale of g_get_monotonic_time(), or 0 if no predicted presentation time is available. a #GdkFrameTimings Reurns the presentation time. This is the time at which the frame became visible to the user. the time the frame was displayed to the user, in the timescale of g_get_monotonic_time(), or 0 if no presentation time is available. See gdk_frame_timings_get_complete() a #GdkFrameTimings Gets the natural interval between presentation times for the display that this frame was displayed on. Frame presentation usually happens during the “vertical blanking interval”. the refresh interval of the display, in microseconds, or 0 if the refresh interval is not available. See gdk_frame_timings_get_complete(). a #GdkFrameTimings Increases the reference count of @timings. @timings a #GdkFrameTimings Decreases the reference count of @timings. If @timings is no longer referenced, it will be freed. a #GdkFrameTimings Indicates which monitor (in a multi-head setup) a window should span over when in fullscreen mode. Fullscreen on current monitor only. Span across all monitors when fullscreen. #GdkGLContext is an object representing the platform-specific OpenGL drawing context. #GdkGLContexts are created for a #GdkWindow using gdk_window_create_gl_context(), and the context will match the #GdkVisual of the window. A #GdkGLContext is not tied to any particular normal framebuffer. For instance, it cannot draw to the #GdkWindow back buffer. The GDK repaint system is in full control of the painting to that. Instead, you can create render buffers or textures and use gdk_cairo_draw_from_gl() in the draw function of your widget to draw them. Then GDK will handle the integration of your rendering with that of other widgets. Support for #GdkGLContext is platform-specific, context creation can fail, returning %NULL context. A #GdkGLContext has to be made "current" in order to start using it, otherwise any OpenGL call will be ignored. ## Creating a new OpenGL context ## In order to create a new #GdkGLContext instance you need a #GdkWindow, which you typically get during the realize call of a widget. A #GdkGLContext is not realized until either gdk_gl_context_make_current(), or until it is realized using gdk_gl_context_realize(). It is possible to specify details of the GL context like the OpenGL version to be used, or whether the GL context should have extra state validation enabled after calling gdk_window_create_gl_context() by calling gdk_gl_context_realize(). If the realization fails you have the option to change the settings of the #GdkGLContext and try again. ## Using a GdkGLContext ## You will need to make the #GdkGLContext the current context before issuing OpenGL calls; the system sends OpenGL commands to whichever context is current. It is possible to have multiple contexts, so you always need to ensure that the one which you want to draw with is the current one before issuing commands: |[<!-- language="C" --> gdk_gl_context_make_current (context); ]| You can now perform your drawing using OpenGL commands. You can check which #GdkGLContext is the current one by using gdk_gl_context_get_current(); you can also unset any #GdkGLContext that is currently set by calling gdk_gl_context_clear_current(). Clears the current #GdkGLContext. Any OpenGL call after this function returns will be ignored until gdk_gl_context_make_current() is called. Retrieves the current #GdkGLContext. the current #GdkGLContext, or %NULL Retrieves the value set using gdk_gl_context_set_debug_enabled(). %TRUE if debugging is enabled a #GdkGLContext Retrieves the #GdkDisplay the @context is created for a #GdkDisplay or %NULL a #GdkGLContext Retrieves the value set using gdk_gl_context_set_forward_compatible(). %TRUE if the context should be forward compatible a #GdkGLContext Retrieves the major and minor version requested by calling gdk_gl_context_set_required_version(). a #GdkGLContext return location for the major version to request return location for the minor version to request Retrieves the #GdkGLContext that this @context share data with. a #GdkGLContext or %NULL a #GdkGLContext Checks whether the @context is using an OpenGL or OpenGL ES profile. %TRUE if the #GdkGLContext is using an OpenGL ES profile a #GdkGLContext Retrieves the OpenGL version of the @context. The @context must be realized prior to calling this function. a #GdkGLContext return location for the major version return location for the minor version Retrieves the #GdkWindow used by the @context. a #GdkWindow or %NULL a #GdkGLContext Whether the #GdkGLContext is in legacy mode or not. The #GdkGLContext must be realized before calling this function. When realizing a GL context, GDK will try to use the OpenGL 3.2 core profile; this profile removes all the OpenGL API that was deprecated prior to the 3.2 version of the specification. If the realization is successful, this function will return %FALSE. If the underlying OpenGL implementation does not support core profiles, GDK will fall back to a pre-3.2 compatibility profile, and this function will return %TRUE. You can use the value returned by this function to decide which kind of OpenGL API to use, or whether to do extension discovery, or what kind of shader programs to load. %TRUE if the GL context is in legacy mode a #GdkGLContext Makes the @context the current one. a #GdkGLContext Realizes the given #GdkGLContext. It is safe to call this function on a realized #GdkGLContext. %TRUE if the context is realized a #GdkGLContext Sets whether the #GdkGLContext should perform extra validations and run time checking. This is useful during development, but has additional overhead. The #GdkGLContext must not be realized or made current prior to calling this function. a #GdkGLContext whether to enable debugging in the context Sets whether the #GdkGLContext should be forward compatible. Forward compatibile contexts must not support OpenGL functionality that has been marked as deprecated in the requested version; non-forward compatible contexts, on the other hand, must support both deprecated and non deprecated functionality. The #GdkGLContext must not be realized or made current prior to calling this function. a #GdkGLContext whether the context should be forward compatible Sets the major and minor version of OpenGL to request. Setting @major and @minor to zero will use the default values. The #GdkGLContext must not be realized or made current prior to calling this function. a #GdkGLContext the major version to request the minor version to request Requests that GDK create a OpenGL ES context instead of an OpenGL one, if the platform and windowing system allows it. The @context must not have been realized. By default, GDK will attempt to automatically detect whether the underlying GL implementation is OpenGL or OpenGL ES once the @context is realized. You should check the return value of gdk_gl_context_get_use_es() after calling gdk_gl_context_realize() to decide whether to use the OpenGL or OpenGL ES API, extensions, or shaders. a #GdkGLContext: whether the context should use OpenGL ES instead of OpenGL, or -1 to allow auto-detection The #GdkDisplay used to create the #GdkGLContext. The #GdkGLContext that this context is sharing data with, or %NULL The #GdkWindow the gl context is bound to. Error enumeration for #GdkGLContext. OpenGL support is not available The requested visual format is not supported The requested profile is not supported The #GdkGeometry struct gives the window manager information about a window’s geometry constraints. Normally you would set these on the GTK+ level using gtk_window_set_geometry_hints(). #GtkWindow then sets the hints on the #GdkWindow it creates. gdk_window_set_geometry_hints() expects the hints to be fully valid already and simply passes them to the window manager; in contrast, gtk_window_set_geometry_hints() performs some interpretation. For example, #GtkWindow will apply the hints to the geometry widget instead of the toplevel window, if you set a geometry widget. Also, the @min_width/@min_height/@max_width/@max_height fields may be set to -1, and #GtkWindow will substitute the size request of the window or geometry widget. If the minimum size hint is not provided, #GtkWindow will use its requisition as the minimum size. If the minimum size is provided and a geometry widget is set, #GtkWindow will take the minimum size as the minimum size of the geometry widget rather than the entire window. The base size is treated similarly. The canonical use-case for gtk_window_set_geometry_hints() is to get a terminal widget to resize properly. Here, the terminal text area should be the geometry widget; #GtkWindow will then automatically set the base size to the size of other widgets in the terminal window, such as the menubar and scrollbar. Then, the @width_inc and @height_inc fields should be set to the size of one character in the terminal. Finally, the base size should be set to the size of one character. The net effect is that the minimum size of the terminal will have a 1x1 character terminal area, and only terminal sizes on the “character grid” will be allowed. Here’s an example of how the terminal example would be implemented, assuming a terminal area widget called “terminal” and a toplevel window “toplevel”: |[<!-- language="C" --> GdkGeometry hints; hints.base_width = terminal->char_width; hints.base_height = terminal->char_height; hints.min_width = terminal->char_width; hints.min_height = terminal->char_height; hints.width_inc = terminal->char_width; hints.height_inc = terminal->char_height; gtk_window_set_geometry_hints (GTK_WINDOW (toplevel), GTK_WIDGET (terminal), &hints, GDK_HINT_RESIZE_INC | GDK_HINT_MIN_SIZE | GDK_HINT_BASE_SIZE); ]| The other useful fields are the @min_aspect and @max_aspect fields; these contain a width/height ratio as a floating point number. If a geometry widget is set, the aspect applies to the geometry widget rather than the entire window. The most common use of these hints is probably to set @min_aspect and @max_aspect to the same value, thus forcing the window to keep a constant aspect ratio. minimum width of window (or -1 to use requisition, with #GtkWindow only) minimum height of window (or -1 to use requisition, with #GtkWindow only) maximum width of window (or -1 to use requisition, with #GtkWindow only) maximum height of window (or -1 to use requisition, with #GtkWindow only) allowed window widths are @base_width + @width_inc * N where N is any integer (-1 allowed with #GtkWindow) allowed window widths are @base_height + @height_inc * N where N is any integer (-1 allowed with #GtkWindow) width resize increment height resize increment minimum width/height ratio maximum width/height ratio window gravity, see gtk_window_set_gravity() Defines how device grabs interact with other devices. All other devices’ events are allowed. Other devices’ events are blocked for the grab window. Other devices’ events are blocked for the whole application. Returned by gdk_device_grab(), gdk_pointer_grab() and gdk_keyboard_grab() to indicate success or the reason for the failure of the grab attempt. the resource was successfully grabbed. the resource is actively grabbed by another client. the resource was grabbed more recently than the specified time. the grab window or the @confine_to window are not viewable. the resource is frozen by an active grab of another client. the grab failed for some other reason. Since 3.16 Defines the reference point of a window and the meaning of coordinates passed to gtk_window_move(). See gtk_window_move() and the "implementation notes" section of the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification for more details. the reference point is at the top left corner. the reference point is in the middle of the top edge. the reference point is at the top right corner. the reference point is at the middle of the left edge. the reference point is at the center of the window. the reference point is at the middle of the right edge. the reference point is at the lower left corner. the reference point is at the middle of the lower edge. the reference point is at the lower right corner. the reference point is at the top left corner of the window itself, ignoring window manager decorations. An enumeration that describes the mode of an input device. the device is disabled and will not report any events. the device is enabled. The device’s coordinate space maps to the entire screen. the device is enabled. The device’s coordinate space is mapped to a single window. The manner in which this window is chosen is undefined, but it will typically be the same way in which the focus window for key events is determined. An enumeration describing the type of an input device in general terms. the device is a mouse. (This will be reported for the core pointer, even if it is something else, such as a trackball.) the device is a stylus of a graphics tablet or similar device. the device is an eraser. Typically, this would be the other end of a stylus on a graphics tablet. the device is a graphics tablet “puck” or similar device. the device is a keyboard. the device is a direct-input touch device, such as a touchscreen or tablet. This device type has been added in 3.4. the device is an indirect touch device, such as a touchpad. This device type has been added in 3.4. the device is a trackpoint. This device type has been added in 3.22 the device is a "pad", a collection of buttons, rings and strips found in drawing tablets. This device type has been added in 3.22. A #GdkKeymap defines the translation from keyboard state (including a hardware key, a modifier mask, and active keyboard group) to a keyval. This translation has two phases. The first phase is to determine the effective keyboard group and level for the keyboard state; the second phase is to look up the keycode/group/level triplet in the keymap and see what keyval it corresponds to. Returns the #GdkKeymap attached to the default display. Use gdk_keymap_get_for_display() instead the #GdkKeymap attached to the default display. Returns the #GdkKeymap attached to @display. the #GdkKeymap attached to @display. the #GdkDisplay. Maps the non-virtual modifiers (i.e Mod2, Mod3, ...) which are set in @state to the virtual modifiers (i.e. Super, Hyper and Meta) and set the corresponding bits in @state. GDK already does this before delivering key events, but for compatibility reasons, it only sets the first virtual modifier it finds, whereas this function sets all matching virtual modifiers. This function is useful when matching key events against accelerators. a #GdkKeymap pointer to the modifier mask to change Returns whether the Caps Lock modifer is locked. %TRUE if Caps Lock is on a #GdkKeymap Returns the direction of effective layout of the keymap. %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL if it can determine the direction. %PANGO_DIRECTION_NEUTRAL otherwise. a #GdkKeymap Returns the keyvals bound to @hardware_keycode. The Nth #GdkKeymapKey in @keys is bound to the Nth keyval in @keyvals. Free the returned arrays with g_free(). When a keycode is pressed by the user, the keyval from this list of entries is selected by considering the effective keyboard group and level. See gdk_keymap_translate_keyboard_state(). %TRUE if there were any entries a #GdkKeymap a keycode return location for array of #GdkKeymapKey, or %NULL return location for array of keyvals, or %NULL length of @keys and @keyvals Obtains a list of keycode/group/level combinations that will generate @keyval. Groups and levels are two kinds of keyboard mode; in general, the level determines whether the top or bottom symbol on a key is used, and the group determines whether the left or right symbol is used. On US keyboards, the shift key changes the keyboard level, and there are no groups. A group switch key might convert a keyboard between Hebrew to English modes, for example. #GdkEventKey contains a %group field that indicates the active keyboard group. The level is computed from the modifier mask. The returned array should be freed with g_free(). %TRUE if keys were found and returned a #GdkKeymap a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc. return location for an array of #GdkKeymapKey return location for number of elements in returned array Returns the modifier mask the @keymap’s windowing system backend uses for a particular purpose. Note that this function always returns real hardware modifiers, not virtual ones (e.g. it will return #GDK_MOD1_MASK rather than #GDK_META_MASK if the backend maps MOD1 to META), so there are use cases where the return value of this function has to be transformed by gdk_keymap_add_virtual_modifiers() in order to contain the expected result. the modifier mask used for @intent. a #GdkKeymap the use case for the modifier mask Returns the current modifier state. the current modifier state. a #GdkKeymap Returns whether the Num Lock modifer is locked. %TRUE if Num Lock is on a #GdkKeymap Returns whether the Scroll Lock modifer is locked. %TRUE if Scroll Lock is on a #GdkKeymap Determines if keyboard layouts for both right-to-left and left-to-right languages are in use. %TRUE if there are layouts in both directions, %FALSE otherwise a #GdkKeymap Looks up the keyval mapped to a keycode/group/level triplet. If no keyval is bound to @key, returns 0. For normal user input, you want to use gdk_keymap_translate_keyboard_state() instead of this function, since the effective group/level may not be the same as the current keyboard state. a keyval, or 0 if none was mapped to the given @key a #GdkKeymap a #GdkKeymapKey with keycode, group, and level initialized Maps the virtual modifiers (i.e. Super, Hyper and Meta) which are set in @state to their non-virtual counterparts (i.e. Mod2, Mod3,...) and set the corresponding bits in @state. This function is useful when matching key events against accelerators. %FALSE if two virtual modifiers were mapped to the same non-virtual modifier. Note that %FALSE is also returned if a virtual modifier is mapped to a non-virtual modifier that was already set in @state. a #GdkKeymap pointer to the modifier state to map Translates the contents of a #GdkEventKey into a keyval, effective group, and level. Modifiers that affected the translation and are thus unavailable for application use are returned in @consumed_modifiers. See [Groups][key-group-explanation] for an explanation of groups and levels. The @effective_group is the group that was actually used for the translation; some keys such as Enter are not affected by the active keyboard group. The @level is derived from @state. For convenience, #GdkEventKey already contains the translated keyval, so this function isn’t as useful as you might think. @consumed_modifiers gives modifiers that should be masked outfrom @state when comparing this key press to a hot key. For instance, on a US keyboard, the `plus` symbol is shifted, so when comparing a key press to a `<Control>plus` accelerator `<Shift>` should be masked out. |[<!-- language="C" --> // We want to ignore irrelevant modifiers like ScrollLock #define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK) gdk_keymap_translate_keyboard_state (keymap, event->hardware_keycode, event->state, event->group, &keyval, NULL, NULL, &consumed); if (keyval == GDK_PLUS && (event->state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK) // Control was pressed ]| An older interpretation @consumed_modifiers was that it contained all modifiers that might affect the translation of the key; this allowed accelerators to be stored with irrelevant consumed modifiers, by doing: |[<!-- language="C" --> // XXX Don’t do this XXX if (keyval == accel_keyval && (event->state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed)) // Accelerator was pressed ]| However, this did not work if multi-modifier combinations were used in the keymap, since, for instance, `<Control>` would be masked out even if only `<Control><Alt>` was used in the keymap. To support this usage as well as well as possible, all single modifier combinations that could affect the key for any combination of modifiers will be returned in @consumed_modifiers; multi-modifier combinations are returned only when actually found in @state. When you store accelerators, you should always store them with consumed modifiers removed. Store `<Control>plus`, not `<Control><Shift>plus`, %TRUE if there was a keyval bound to the keycode/state/group a #GdkKeymap a keycode a modifier state active keyboard group return location for keyval, or %NULL return location for effective group, or %NULL return location for level, or %NULL return location for modifiers that were used to determine the group or level, or %NULL The ::direction-changed signal gets emitted when the direction of the keymap changes. The ::keys-changed signal is emitted when the mapping represented by @keymap changes. The ::state-changed signal is emitted when the state of the keyboard changes, e.g when Caps Lock is turned on or off. See gdk_keymap_get_caps_lock_state(). A #GdkKeymapKey is a hardware key that can be mapped to a keyval. the hardware keycode. This is an identifying number for a physical key. indicates movement in a horizontal direction. Usually groups are used for two different languages. In group 0, a key might have two English characters, and in group 1 it might have two Hebrew characters. The Hebrew characters will be printed on the key next to the English characters. indicates which symbol on the key will be used, in a vertical direction. So on a standard US keyboard, the key with the number “1” on it also has the exclamation point ("!") character on it. The level indicates whether to use the “1” or the “!” symbol. The letter keys are considered to have a lowercase letter at level 0, and an uppercase letter at level 1, though only the uppercase letter is printed. This enum is used with gdk_keymap_get_modifier_mask() in order to determine what modifiers the currently used windowing system backend uses for particular purposes. For example, on X11/Windows, the Control key is used for invoking menu shortcuts (accelerators), whereas on Apple computers it’s the Command key (which correspond to %GDK_CONTROL_MASK and %GDK_MOD2_MASK, respectively). the primary modifier used to invoke menu accelerators. the modifier used to invoke context menus. Note that mouse button 3 always triggers context menus. When this modifier is not 0, it additionally triggers context menus when used with mouse button 1. the modifier used to extend selections using `modifier`-click or `modifier`-cursor-key the modifier used to modify selections, which in most cases means toggling the clicked item into or out of the selection. when any of these modifiers is pressed, the key event cannot produce a symbol directly. This is meant to be used for input methods, and for use cases like typeahead search. the modifier that switches between keyboard groups (AltGr on X11/Windows and Option/Alt on OS X). The set of modifier masks accepted as modifiers in accelerators. Needed because Command is mapped to MOD2 on OSX, which is widely used, but on X11 MOD2 is NumLock and using that for a mod key is problematic at best. Ref: https://bugzilla.gnome.org/show_bug.cgi?id=736125. A set of bit-flags to indicate the state of modifier keys and mouse buttons in various event types. Typical modifier keys are Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock or ShiftLock. Like the X Window System, GDK supports 8 modifier keys and 5 mouse buttons. Since 2.10, GDK recognizes which of the Meta, Super or Hyper keys are mapped to Mod2 - Mod5, and indicates this by setting %GDK_SUPER_MASK, %GDK_HYPER_MASK or %GDK_META_MASK in the state field of key events. Note that GDK may add internal values to events which include reserved values such as %GDK_MODIFIER_RESERVED_13_MASK. Your code should preserve and ignore them. You can use %GDK_MODIFIER_MASK to remove all reserved values. Also note that the GDK X backend interprets button press events for button 4-7 as scroll events, so %GDK_BUTTON4_MASK and %GDK_BUTTON5_MASK will never be set. the Shift key. a Lock key (depending on the modifier mapping of the X server this may either be CapsLock or ShiftLock). the Control key. the fourth modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier, but normally it is the Alt key). the fifth modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier). the sixth modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier). the seventh modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier). the eighth modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier). the first mouse button. the second mouse button. the third mouse button. the fourth mouse button. the fifth mouse button. A reserved bit flag; do not use in your own code A reserved bit flag; do not use in your own code A reserved bit flag; do not use in your own code A reserved bit flag; do not use in your own code A reserved bit flag; do not use in your own code A reserved bit flag; do not use in your own code A reserved bit flag; do not use in your own code A reserved bit flag; do not use in your own code A reserved bit flag; do not use in your own code A reserved bit flag; do not use in your own code A reserved bit flag; do not use in your own code A reserved bit flag; do not use in your own code A reserved bit flag; do not use in your own code the Super modifier. Since 2.10 the Hyper modifier. Since 2.10 the Meta modifier. Since 2.10 A reserved bit flag; do not use in your own code not used in GDK itself. GTK+ uses it to differentiate between (keyval, modifiers) pairs from key press and release events. a mask covering all modifier types. GdkMonitor objects represent the individual outputs that are associated with a #GdkDisplay. GdkDisplay has APIs to enumerate monitors with gdk_display_get_n_monitors() and gdk_display_get_monitor(), and to find particular monitors with gdk_display_get_primary_monitor() or gdk_display_get_monitor_at_window(). GdkMonitor was introduced in GTK+ 3.22 and supersedes earlier APIs in GdkScreen to obtain monitor-related information. Gets the display that this monitor belongs to. the display a #GdkMonitor Retrieves the size and position of an individual monitor within the display coordinate space. The returned geometry is in ”application pixels”, not in ”device pixels” (see gdk_monitor_get_scale_factor()). a #GdkMonitor a #GdkRectangle to be filled with the monitor geometry Gets the height in millimeters of the monitor. the physical height of the monitor a #GdkMonitor Gets the name or PNP ID of the monitor's manufacturer, if available. Note that this value might also vary depending on actual display backend. PNP ID registry is located at https://uefi.org/pnp_id_list the name of the manufacturer, or %NULL a #GdkMonitor Gets the a string identifying the monitor model, if available. the monitor model, or %NULL a #GdkMonitor Gets the refresh rate of the monitor, if available. The value is in milli-Hertz, so a refresh rate of 60Hz is returned as 60000. the refresh rate in milli-Hertz, or 0 a #GdkMonitor Gets the internal scale factor that maps from monitor coordinates to the actual device pixels. On traditional systems this is 1, but on very high density outputs this can be a higher value (often 2). This can be used if you want to create pixel based data for a particular monitor, but most of the time you’re drawing to a window where it is better to use gdk_window_get_scale_factor() instead. the scale factor a #GdkMonitor Gets information about the layout of red, green and blue primaries for each pixel in this monitor, if available. the subpixel layout a #GdkMonitor Gets the width in millimeters of the monitor. the physical width of the monitor a #GdkMonitor Retrieves the size and position of the “work area” on a monitor within the display coordinate space. The returned geometry is in ”application pixels”, not in ”device pixels” (see gdk_monitor_get_scale_factor()). The work area should be considered when positioning menus and similar popups, to avoid placing them below panels, docks or other desktop components. Note that not all backends may have a concept of workarea. This function will return the monitor geometry if a workarea is not available, or does not apply. a #GdkMonitor a #GdkRectangle to be filled with the monitor workarea Gets whether this monitor should be considered primary (see gdk_display_get_primary_monitor()). %TRUE if @monitor is primary a #GdkMonitor Specifies the kind of crossing for #GdkEventCrossing. See the X11 protocol specification of LeaveNotify for full details of crossing event generation. the window is entered from an ancestor or left towards an ancestor. the pointer moves between an ancestor and an inferior of the window. the window is entered from an inferior or left towards an inferior. the window is entered from or left towards a window which is neither an ancestor nor an inferior. the pointer moves between two windows which are not ancestors of each other and the window is part of the ancestor chain between one of these windows and their least common ancestor. an unknown type of enter/leave event occurred. Specifies why a selection ownership was changed. some other app claimed the ownership the window was destroyed the client was closed A special value, indicating that the background for a window should be inherited from the parent window. Extracts a #GdkAtom from a pointer. The #GdkAtom must have been stored in the pointer with GDK_ATOM_TO_POINTER(). a pointer containing a #GdkAtom. This is the priority that the idle handler processing window updates is given in the [GLib Main Loop][glib-The-Main-Event-Loop]. Defines the x and y coordinates of a point. the x coordinate of the point. the y coordinate of the point. Describes how existing data is combined with new data when using gdk_property_change(). the new data replaces the existing data. the new data is prepended to the existing data. the new data is appended to the existing data. Specifies the type of a property change for a #GdkEventProperty. the property value was changed. the property was deleted. A #GdkRGBA is used to represent a (possibly translucent) color, in a way that is compatible with cairo’s notion of color. The intensity of the red channel from 0.0 to 1.0 inclusive The intensity of the green channel from 0.0 to 1.0 inclusive The intensity of the blue channel from 0.0 to 1.0 inclusive The opacity of the color from 0.0 for completely translucent to 1.0 for opaque Makes a copy of a #GdkRGBA. The result must be freed through gdk_rgba_free(). A newly allocated #GdkRGBA, with the same contents as @rgba a #GdkRGBA Compares two RGBA colors. %TRUE if the two colors compare equal a #GdkRGBA pointer another #GdkRGBA pointer Frees a #GdkRGBA created with gdk_rgba_copy() a #GdkRGBA A hash function suitable for using for a hash table that stores #GdkRGBAs. The hash value for @p a #GdkRGBA pointer Parses a textual representation of a color, filling in the @red, @green, @blue and @alpha fields of the @rgba #GdkRGBA. The string can be either one of: - A standard name (Taken from the X11 rgb.txt file). - A hexadecimal value in the form “\#rgb”, “\#rrggbb”, “\#rrrgggbbb” or ”\#rrrrggggbbbb” - A RGB color in the form “rgb(r,g,b)” (In this case the color will have full opacity) - A RGBA color in the form “rgba(r,g,b,a)” Where “r”, “g”, “b” and “a” are respectively the red, green, blue and alpha color values. In the last two cases, “r”, “g”, and “b” are either integers in the range 0 to 255 or percentage values in the range 0% to 100%, and a is a floating point value in the range 0 to 1. %TRUE if the parsing succeeded the #GdkRGBA to fill in the string specifying the color Returns a textual specification of @rgba in the form `rgb(r,g,b)` or `rgba(r g,b,a)`, where “r”, “g”, “b” and “a” represent the red, green, blue and alpha values respectively. “r”, “g”, and “b” are represented as integers in the range 0 to 255, and “a” is represented as a floating point value in the range 0 to 1. These string forms are string forms that are supported by the CSS3 colors module, and can be parsed by gdk_rgba_parse(). Note that this string representation may lose some precision, since “r”, “g” and “b” are represented as 8-bit integers. If this is a concern, you should use a different representation. A newly allocated text string a #GdkRGBA Defines the position and size of a rectangle. It is identical to #cairo_rectangle_int_t. Checks if the two given rectangles are equal. %TRUE if the rectangles are equal. a #GdkRectangle a #GdkRectangle Calculates the intersection of two rectangles. It is allowed for @dest to be the same as either @src1 or @src2. If the rectangles do not intersect, @dest’s width and height is set to 0 and its x and y values are undefined. If you are only interested in whether the rectangles intersect, but not in the intersecting area itself, pass %NULL for @dest. %TRUE if the rectangles intersect. a #GdkRectangle a #GdkRectangle return location for the intersection of @src1 and @src2, or %NULL Calculates the union of two rectangles. The union of rectangles @src1 and @src2 is the smallest rectangle which includes both @src1 and @src2 within it. It is allowed for @dest to be the same as either @src1 or @src2. Note that this function does not ignore 'empty' rectangles (ie. with zero width or height). a #GdkRectangle a #GdkRectangle return location for the union of @src1 and @src2 #GdkScreen objects are the GDK representation of the screen on which windows can be displayed and on which the pointer moves. X originally identified screens with physical screens, but nowadays it is more common to have a single #GdkScreen which combines several physical monitors (see gdk_screen_get_n_monitors()). GdkScreen is used throughout GDK and GTK+ to specify which screen the top level windows are to be displayed on. it is also used to query the screen specification and default settings such as the default visual (gdk_screen_get_system_visual()), the dimensions of the physical monitors (gdk_screen_get_monitor_geometry()), etc. Gets the default screen for the default display. (See gdk_display_get_default ()). a #GdkScreen, or %NULL if there is no default display. Gets the height of the default screen in pixels. The returned size is in ”application pixels”, not in ”device pixels” (see gdk_screen_get_monitor_scale_factor()). Use per-monitor information the height of the default screen in pixels. Returns the height of the default screen in millimeters. Note that on many X servers this value will not be correct. Use per-monitor information the height of the default screen in millimeters, though it is not always correct. Gets the width of the default screen in pixels. The returned size is in ”application pixels”, not in ”device pixels” (see gdk_screen_get_monitor_scale_factor()). Use per-monitor information the width of the default screen in pixels. Returns the width of the default screen in millimeters. Note that on many X servers this value will not be correct. Use per-monitor information the width of the default screen in millimeters, though it is not always correct. Returns the screen’s currently active window. On X11, this is done by inspecting the _NET_ACTIVE_WINDOW property on the root window, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec). If there is no currently currently active window, or the window manager does not support the _NET_ACTIVE_WINDOW hint, this function returns %NULL. On other platforms, this function may return %NULL, depending on whether it is implementable on that platform. The returned window should be unrefed using g_object_unref() when no longer needed. the currently active window, or %NULL. a #GdkScreen Gets the display to which the @screen belongs. the display to which @screen belongs a #GdkScreen Gets any options previously set with gdk_screen_set_font_options(). the current font options, or %NULL if no default font options have been set. a #GdkScreen Gets the height of @screen in pixels. The returned size is in ”application pixels”, not in ”device pixels” (see gdk_screen_get_monitor_scale_factor()). Use per-monitor information instead the height of @screen in pixels. a #GdkScreen Returns the height of @screen in millimeters. Note that this value is somewhat ill-defined when the screen has multiple monitors of different resolution. It is recommended to use the monitor dimensions instead. Use per-monitor information instead the heigth of @screen in millimeters. a #GdkScreen Returns the monitor number in which the point (@x,@y) is located. Use gdk_display_get_monitor_at_point() instead the monitor number in which the point (@x,@y) lies, or a monitor close to (@x,@y) if the point is not in any monitor. a #GdkScreen. the x coordinate in the virtual screen. the y coordinate in the virtual screen. Returns the number of the monitor in which the largest area of the bounding rectangle of @window resides. Use gdk_display_get_monitor_at_window() instead the monitor number in which most of @window is located, or if @window does not intersect any monitors, a monitor, close to @window. a #GdkScreen. a #GdkWindow Retrieves the #GdkRectangle representing the size and position of the individual monitor within the entire screen area. The returned geometry is in ”application pixels”, not in ”device pixels” (see gdk_screen_get_monitor_scale_factor()). Monitor numbers start at 0. To obtain the number of monitors of @screen, use gdk_screen_get_n_monitors(). Note that the size of the entire screen area can be retrieved via gdk_screen_get_width() and gdk_screen_get_height(). Use gdk_monitor_get_geometry() instead a #GdkScreen the monitor number a #GdkRectangle to be filled with the monitor geometry Gets the height in millimeters of the specified monitor. Use gdk_monitor_get_height_mm() instead the height of the monitor, or -1 if not available a #GdkScreen number of the monitor, between 0 and gdk_screen_get_n_monitors (screen) Returns the output name of the specified monitor. Usually something like VGA, DVI, or TV, not the actual product name of the display device. Use gdk_monitor_get_model() instead a newly-allocated string containing the name of the monitor, or %NULL if the name cannot be determined a #GdkScreen number of the monitor, between 0 and gdk_screen_get_n_monitors (screen) Returns the internal scale factor that maps from monitor coordinates to the actual device pixels. On traditional systems this is 1, but on very high density outputs this can be a higher value (often 2). This can be used if you want to create pixel based data for a particular monitor, but most of the time you’re drawing to a window where it is better to use gdk_window_get_scale_factor() instead. Use gdk_monitor_get_scale_factor() instead the scale factor screen to get scale factor for number of the monitor, between 0 and gdk_screen_get_n_monitors (screen) Gets the width in millimeters of the specified monitor, if available. Use gdk_monitor_get_width_mm() instead the width of the monitor, or -1 if not available a #GdkScreen number of the monitor, between 0 and gdk_screen_get_n_monitors (screen) Retrieves the #GdkRectangle representing the size and position of the “work area” on a monitor within the entire screen area. The returned geometry is in ”application pixels”, not in ”device pixels” (see gdk_screen_get_monitor_scale_factor()). The work area should be considered when positioning menus and similar popups, to avoid placing them below panels, docks or other desktop components. Note that not all backends may have a concept of workarea. This function will return the monitor geometry if a workarea is not available, or does not apply. Monitor numbers start at 0. To obtain the number of monitors of @screen, use gdk_screen_get_n_monitors(). Use gdk_monitor_get_workarea() instead a #GdkScreen the monitor number a #GdkRectangle to be filled with the monitor workarea Returns the number of monitors which @screen consists of. Use gdk_display_get_n_monitors() instead number of monitors which @screen consists of a #GdkScreen Gets the index of @screen among the screens in the display to which it belongs. (See gdk_screen_get_display()) the index a #GdkScreen Gets the primary monitor for @screen. The primary monitor is considered the monitor where the “main desktop” lives. While normal application windows typically allow the window manager to place the windows, specialized desktop applications such as panels should place themselves on the primary monitor. If no primary monitor is configured by the user, the return value will be 0, defaulting to the first monitor. Use gdk_display_get_primary_monitor() instead An integer index for the primary monitor, or 0 if none is configured. a #GdkScreen. Gets the resolution for font handling on the screen; see gdk_screen_set_resolution() for full details. the current resolution, or -1 if no resolution has been set. a #GdkScreen Gets a visual to use for creating windows with an alpha channel. The windowing system on which GTK+ is running may not support this capability, in which case %NULL will be returned. Even if a non-%NULL value is returned, its possible that the window’s alpha channel won’t be honored when displaying the window on the screen: in particular, for X an appropriate windowing manager and compositing manager must be running to provide appropriate display. This functionality is not implemented in the Windows backend. For setting an overall opacity for a top-level window, see gdk_window_set_opacity(). a visual to use for windows with an alpha channel or %NULL if the capability is not available. a #GdkScreen Gets the root window of @screen. the root window a #GdkScreen Retrieves a desktop-wide setting such as double-click time for the #GdkScreen @screen. FIXME needs a list of valid settings here, or a link to more information. %TRUE if the setting existed and a value was stored in @value, %FALSE otherwise. the #GdkScreen where the setting is located the name of the setting location to store the value of the setting Get the system’s default visual for @screen. This is the visual for the root window of the display. The return value should not be freed. the system visual a #GdkScreen. Obtains a list of all toplevel windows known to GDK on the screen @screen. A toplevel window is a child of the root window (see gdk_get_default_root_window()). The returned list should be freed with g_list_free(), but its elements need not be freed. list of toplevel windows, free with g_list_free() The #GdkScreen where the toplevels are located. Gets the width of @screen in pixels. The returned size is in ”application pixels”, not in ”device pixels” (see gdk_screen_get_monitor_scale_factor()). Use per-monitor information instead the width of @screen in pixels. a #GdkScreen Gets the width of @screen in millimeters. Note that this value is somewhat ill-defined when the screen has multiple monitors of different resolution. It is recommended to use the monitor dimensions instead. Use per-monitor information instead the width of @screen in millimeters. a #GdkScreen Returns a #GList of #GdkWindows representing the current window stack. On X11, this is done by inspecting the _NET_CLIENT_LIST_STACKING property on the root window, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec). If the window manager does not support the _NET_CLIENT_LIST_STACKING hint, this function returns %NULL. On other platforms, this function may return %NULL, depending on whether it is implementable on that platform. The returned list is newly allocated and owns references to the windows it contains, so it should be freed using g_list_free() and its windows unrefed using g_object_unref() when no longer needed. a list of #GdkWindows for the current window stack, or %NULL. a #GdkScreen Returns whether windows with an RGBA visual can reasonably be expected to have their alpha channel drawn correctly on the screen. On X11 this function returns whether a compositing manager is compositing @screen. Whether windows with RGBA visuals can reasonably be expected to have their alpha channels drawn correctly on the screen. a #GdkScreen Lists the available visuals for the specified @screen. A visual describes a hardware image data format. For example, a visual might support 24-bit color, or 8-bit color, and might expect pixels to be in a certain format. Call g_list_free() on the return value when you’re finished with it. a list of visuals; the list must be freed, but not its contents the relevant #GdkScreen. Determines the name to pass to gdk_display_open() to get a #GdkDisplay with this screen as the default screen. a newly allocated string, free with g_free() a #GdkScreen Sets the default font options for the screen. These options will be set on any #PangoContext’s newly created with gdk_pango_context_get_for_screen(). Changing the default set of font options does not affect contexts that have already been created. a #GdkScreen a #cairo_font_options_t, or %NULL to unset any previously set default font options. Sets the resolution for font handling on the screen. This is a scale factor between points specified in a #PangoFontDescription and cairo units. The default value is 96, meaning that a 10 point font will be 13 units high. (10 * 96. / 72. = 13.3). a #GdkScreen the resolution in “dots per inch”. (Physical inches aren’t actually involved; the terminology is conventional.) The ::composited-changed signal is emitted when the composited status of the screen changes The ::monitors-changed signal is emitted when the number, size or position of the monitors attached to the screen change. Only for X11 and OS X for now. A future implementation for Win32 may be a possibility. The ::size-changed signal is emitted when the pixel width or height of a screen changes. Specifies the direction for #GdkEventScroll. the window is scrolled up. the window is scrolled down. the window is scrolled to the left. the window is scrolled to the right. the scrolling is determined by the delta values in #GdkEventScroll. See gdk_event_get_scroll_deltas(). Since: 3.4 The #GdkSeat object represents a collection of input devices that belong to a user. Returns the capabilities this #GdkSeat currently has. the seat capabilities a #GdkSeat Returns the #GdkDisplay this seat belongs to. a #GdkDisplay. This object is owned by GTK+ and must not be freed. a #GdkSeat Returns the master device that routes keyboard events. a master #GdkDevice with keyboard capabilities. This object is owned by GTK+ and must not be freed. a #GdkSeat Returns the master device that routes pointer events. a master #GdkDevice with pointer capabilities. This object is owned by GTK+ and must not be freed. a #GdkSeat Returns the slave devices that match the given capabilities. A list of #GdkDevices. The list must be freed with g_list_free(), the elements are owned by GDK and must not be freed. a #GdkSeat capabilities to get devices for Grabs the seat so that all events corresponding to the given @capabilities are passed to this application until the seat is ungrabbed with gdk_seat_ungrab(), or the window becomes hidden. This overrides any previous grab on the seat by this client. As a rule of thumb, if a grab is desired over %GDK_SEAT_CAPABILITY_POINTER, all other "pointing" capabilities (eg. %GDK_SEAT_CAPABILITY_TOUCH) should be grabbed too, so the user is able to interact with all of those while the grab holds, you should thus use %GDK_SEAT_CAPABILITY_ALL_POINTING most commonly. Grabs are used for operations which need complete control over the events corresponding to the given capabilities. For example in GTK+ this is used for Drag and Drop operations, popup menus and such. Note that if the event mask of a #GdkWindow has selected both button press and button release events, or touch begin and touch end, then a press event will cause an automatic grab until the button is released, equivalent to a grab on the window with @owner_events set to %TRUE. This is done because most applications expect to receive paired press and release events. If you set up anything at the time you take the grab that needs to be cleaned up when the grab ends, you should handle the #GdkEventGrabBroken events that are emitted when the grab ends unvoluntarily. %GDK_GRAB_SUCCESS if the grab was successful. a #GdkSeat the #GdkWindow which will own the grab capabilities that will be grabbed if %FALSE then all device events are reported with respect to @window and are only reported if selected by @event_mask. If %TRUE then pointer events for this application are reported as normal, but pointer events outside this application are reported with respect to @window and only if selected by @event_mask. In either mode, unreported events are discarded. the cursor to display while the grab is active. If this is %NULL then the normal cursors are used for @window and its descendants, and the cursor for @window is used elsewhere. the event that is triggering the grab, or %NULL if none is available. function to prepare the window to be grabbed, it can be %NULL if @window is visible before this call. user data to pass to @prepare_func Releases a grab added through gdk_seat_grab(). a #GdkSeat #GdkDisplay of this seat. The ::device-added signal is emitted when a new input device is related to this seat. the newly added #GdkDevice. The ::device-removed signal is emitted when an input device is removed (e.g. unplugged). the just removed #GdkDevice. The ::tool-added signal is emitted whenever a new tool is made known to the seat. The tool may later be assigned to a device (i.e. on proximity with a tablet). The device will emit the #GdkDevice::tool-changed signal accordingly. A same tool may be used by several devices. the new #GdkDeviceTool known to the seat This signal is emitted whenever a tool is no longer known to this @seat. the just removed #GdkDeviceTool Flags describing the seat capabilities. No input capabilities The seat has a pointer (e.g. mouse) The seat has touchscreen(s) attached The seat has drawing tablet(s) attached The seat has keyboard(s) attached The union of all pointing capabilities The union of all capabilities Type of the callback used to set up @window so it can be grabbed. A typical action would be ensuring the window is visible, although there's room for other initialization actions. the #GdkSeat being grabbed the #GdkWindow being grabbed user data passed in gdk_seat_grab() Specifies the kind of modification applied to a setting in a #GdkEventSetting. a setting was added. a setting was changed. a setting was deleted. This enumeration describes how the red, green and blue components of physical pixels on an output device are laid out. The layout is not known Not organized in this way The layout is horizontal, the order is RGB The layout is horizontal, the order is BGR The layout is vertical, the order is RGB The layout is vertical, the order is BGR This macro marks the beginning of a critical section in which GDK and GTK+ functions can be called safely and without causing race conditions. Only one thread at a time can be in such a critial section. The macro expands to a no-op if #G_THREADS_ENABLED has not been defined. Typically gdk_threads_enter() should be used instead of this macro. Use g_main_context_invoke(), g_idle_add() and related functions if you need to schedule GTK+ calls from other threads. This macro marks the end of a critical section begun with #GDK_THREADS_ENTER. Deprecated in 3.6. A #GdkTimeCoord stores a single event in a motion history. The timestamp for this event. the values of the device’s axes. Specifies the current state of a touchpad gesture. All gestures are guaranteed to begin with an event with phase %GDK_TOUCHPAD_GESTURE_PHASE_BEGIN, followed by 0 or several events with phase %GDK_TOUCHPAD_GESTURE_PHASE_UPDATE. A finished gesture may have 2 possible outcomes, an event with phase %GDK_TOUCHPAD_GESTURE_PHASE_END will be emitted when the gesture is considered successful, this should be used as the hint to perform any permanent changes. Cancelled gestures may be so for a variety of reasons, due to hardware or the compositor, or due to the gesture recognition layers hinting the gesture did not finish resolutely (eg. a 3rd finger being added during a pinch gesture). In these cases, the last event will report the phase %GDK_TOUCHPAD_GESTURE_PHASE_CANCEL, this should be used as a hint to undo any visible/permanent changes that were done throughout the progress of the gesture. See also #GdkEventTouchpadSwipe and #GdkEventTouchpadPinch. The gesture has begun. The gesture has been updated. The gesture was finished, changes should be permanently applied. The gesture was cancelled, all changes should be undone. Specifies the visiblity status of a window for a #GdkEventVisibility. the window is completely visible. the window is partially visible. the window is not visible at all. A #GdkVisual contains information about a particular visual. Get the visual with the most available colors for the default GDK screen. The return value should not be freed. Visual selection should be done using gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual() best visual Get the best available depth for the default GDK screen. “Best” means “largest,” i.e. 32 preferred over 24 preferred over 8 bits per pixel. Visual selection should be done using gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual() best available depth Return the best available visual type for the default GDK screen. Visual selection should be done using gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual() best visual type Combines gdk_visual_get_best_with_depth() and gdk_visual_get_best_with_type(). Visual selection should be done using gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual() best visual with both @depth and @visual_type, or %NULL if none a bit depth a visual type Get the best visual with depth @depth for the default GDK screen. Color visuals and visuals with mutable colormaps are preferred over grayscale or fixed-colormap visuals. The return value should not be freed. %NULL may be returned if no visual supports @depth. Visual selection should be done using gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual() best visual for the given depth a bit depth Get the best visual of the given @visual_type for the default GDK screen. Visuals with higher color depths are considered better. The return value should not be freed. %NULL may be returned if no visual has type @visual_type. Visual selection should be done using gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual() best visual of the given type a visual type Get the system’s default visual for the default GDK screen. This is the visual for the root window of the display. The return value should not be freed. Use gdk_screen_get_system_visual (gdk_screen_get_default ()). system visual Returns the number of significant bits per red, green and blue value. Not all GDK backend provide a meaningful value for this function. Use gdk_visual_get_red_pixel_details() and its variants to learn about the pixel layout of TrueColor and DirectColor visuals The number of significant bits per color value for @visual. a #GdkVisual Obtains values that are needed to calculate blue pixel values in TrueColor and DirectColor. The “mask” is the significant bits within the pixel. The “shift” is the number of bits left we must shift a primary for it to be in position (according to the "mask"). Finally, "precision" refers to how much precision the pixel value contains for a particular primary. a #GdkVisual A pointer to a #guint32 to be filled in, or %NULL A pointer to a #gint to be filled in, or %NULL A pointer to a #gint to be filled in, or %NULL Returns the byte order of this visual. The information returned by this function is only relevant when working with XImages, and not all backends return meaningful information for this. This information is not useful A #GdkByteOrder stating the byte order of @visual. A #GdkVisual. Returns the size of a colormap for this visual. You have to use platform-specific APIs to manipulate colormaps. This information is not useful, since GDK does not provide APIs to operate on colormaps. The size of a colormap that is suitable for @visual. A #GdkVisual. Returns the bit depth of this visual. The bit depth of this visual. A #GdkVisual. Obtains values that are needed to calculate green pixel values in TrueColor and DirectColor. The “mask” is the significant bits within the pixel. The “shift” is the number of bits left we must shift a primary for it to be in position (according to the "mask"). Finally, "precision" refers to how much precision the pixel value contains for a particular primary. a #GdkVisual A pointer to a #guint32 to be filled in, or %NULL A pointer to a #gint to be filled in, or %NULL A pointer to a #gint to be filled in, or %NULL Obtains values that are needed to calculate red pixel values in TrueColor and DirectColor. The “mask” is the significant bits within the pixel. The “shift” is the number of bits left we must shift a primary for it to be in position (according to the "mask"). Finally, "precision" refers to how much precision the pixel value contains for a particular primary. A #GdkVisual A pointer to a #guint32 to be filled in, or %NULL A pointer to a #gint to be filled in, or %NULL A pointer to a #gint to be filled in, or %NULL Gets the screen to which this visual belongs the screen to which this visual belongs. a #GdkVisual Returns the type of visual this is (PseudoColor, TrueColor, etc). A #GdkVisualType stating the type of @visual. A #GdkVisual. A set of values that describe the manner in which the pixel values for a visual are converted into RGB values for display. Each pixel value indexes a grayscale value directly. Each pixel is an index into a color map that maps pixel values into grayscale values. The color map can be changed by an application. Each pixel value is an index into a predefined, unmodifiable color map that maps pixel values into RGB values. Each pixel is an index into a color map that maps pixel values into rgb values. The color map can be changed by an application. Each pixel value directly contains red, green, and blue components. Use gdk_visual_get_red_pixel_details(), etc, to obtain information about how the components are assembled into a pixel value. Each pixel value contains red, green, and blue components as for %GDK_VISUAL_TRUE_COLOR, but the components are mapped via a color table into the final output table instead of being converted directly. These are hints originally defined by the Motif toolkit. The window manager can use them when determining how to decorate the window. The hint must be set before mapping the window. all decorations should be applied. a frame should be drawn around the window. the frame should have resize handles. a titlebar should be placed above the window. a button for opening a menu should be included. a minimize button should be included. a maximize button should be included. These are hints originally defined by the Motif toolkit. The window manager can use them when determining the functions to offer for the window. The hint must be set before mapping the window. all functions should be offered. the window should be resizable. the window should be movable. the window should be minimizable. the window should be maximizable. the window should be closable. Creates a new #GdkWindow using the attributes from @attributes. See #GdkWindowAttr and #GdkWindowAttributesType for more details. Note: to use this on displays other than the default display, @parent must be specified. the new #GdkWindow a #GdkWindow, or %NULL to create the window as a child of the default root window for the default display. attributes of the new window mask indicating which fields in @attributes are valid Obtains the window underneath the mouse pointer, returning the location of that window in @win_x, @win_y. Returns %NULL if the window under the mouse pointer is not known to GDK (if the window belongs to another application and a #GdkWindow hasn’t been created for it with gdk_window_foreign_new()) NOTE: For multihead-aware widgets or applications use gdk_display_get_window_at_pointer() instead. Use gdk_device_get_window_at_position() instead. window under the mouse pointer return location for origin of the window under the pointer return location for origin of the window under the pointer Constrains a desired width and height according to a set of geometry hints (such as minimum and maximum size). a #GdkGeometry structure a mask indicating what portions of @geometry are set desired width of window desired height of the window location to store resulting width location to store resulting height Calls gdk_window_process_updates() for all windows (see #GdkWindow) in the application. With update debugging enabled, calls to gdk_window_invalidate_region() clear the invalidated region of the screen to a noticeable color, and GDK pauses for a short time before sending exposes to windows during gdk_window_process_updates(). The net effect is that you can see the invalid region for each window and watch redraws as they occur. This allows you to diagnose inefficiencies in your application. In essence, because the GDK rendering model prevents all flicker, if you are redrawing the same region 400 times you may never notice, aside from noticing a speed problem. Enabling update debugging causes GTK to flicker slowly and noticeably, so you can see exactly what’s being redrawn when, in what order. The --gtk-debug=updates command line option passed to GTK+ programs enables this debug option at application startup time. That's usually more useful than calling gdk_window_set_debug_updates() yourself, though you might want to use this function to enable updates sometime after application startup time. %TRUE to turn on update debugging Adds an event filter to @window, allowing you to intercept events before they reach GDK. This is a low-level operation and makes it easy to break GDK and/or GTK+, so you have to know what you're doing. Pass %NULL for @window to get all events for all windows, instead of events for a specific window. If you are interested in X GenericEvents, bear in mind that XGetEventData() has been already called on the event, and XFreeEventData() must not be called within @function. a #GdkWindow filter callback data to pass to filter callback Emits a short beep associated to @window in the appropriate display, if supported. Otherwise, emits a short beep on the display just as gdk_display_beep(). a toplevel #GdkWindow Indicates that you are beginning the process of redrawing @region on @window, and provides you with a #GdkDrawingContext. If @window is a top level #GdkWindow, backed by a native window implementation, a backing store (offscreen buffer) large enough to contain @region will be created. The backing store will be initialized with the background color or background surface for @window. Then, all drawing operations performed on @window will be diverted to the backing store. When you call gdk_window_end_frame(), the contents of the backing store will be copied to @window, making it visible on screen. Only the part of @window contained in @region will be modified; that is, drawing operations are clipped to @region. The net result of all this is to remove flicker, because the user sees the finished product appear all at once when you call gdk_window_end_draw_frame(). If you draw to @window directly without calling gdk_window_begin_draw_frame(), the user may see flicker as individual drawing operations are performed in sequence. When using GTK+, the widget system automatically places calls to gdk_window_begin_draw_frame() and gdk_window_end_draw_frame() around emissions of the `GtkWidget::draw` signal. That is, if you’re drawing the contents of the widget yourself, you can assume that the widget has a cleared background, is already set as the clip region, and already has a backing store. Therefore in most cases, application code in GTK does not need to call gdk_window_begin_draw_frame() explicitly. a #GdkDrawingContext context that should be used to draw the contents of the window; the returned context is owned by GDK. a #GdkWindow a Cairo region Begins a window move operation (for a toplevel window). This function assumes that the drag is controlled by the client pointer device, use gdk_window_begin_move_drag_for_device() to begin a drag with a different device. a toplevel #GdkWindow the button being used to drag, or 0 for a keyboard-initiated drag root window X coordinate of mouse click that began the drag root window Y coordinate of mouse click that began the drag timestamp of mouse click that began the drag Begins a window move operation (for a toplevel window). You might use this function to implement a “window move grip,” for example. The function works best with window managers that support the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) but has a fallback implementation for other window managers. a toplevel #GdkWindow the device used for the operation the button being used to drag, or 0 for a keyboard-initiated drag root window X coordinate of mouse click that began the drag root window Y coordinate of mouse click that began the drag timestamp of mouse click that began the drag A convenience wrapper around gdk_window_begin_paint_region() which creates a rectangular region for you. See gdk_window_begin_paint_region() for details. Use gdk_window_begin_draw_frame() instead a #GdkWindow rectangle you intend to draw to Indicates that you are beginning the process of redrawing @region. A backing store (offscreen buffer) large enough to contain @region will be created. The backing store will be initialized with the background color or background surface for @window. Then, all drawing operations performed on @window will be diverted to the backing store. When you call gdk_window_end_paint(), the backing store will be copied to @window, making it visible onscreen. Only the part of @window contained in @region will be modified; that is, drawing operations are clipped to @region. The net result of all this is to remove flicker, because the user sees the finished product appear all at once when you call gdk_window_end_paint(). If you draw to @window directly without calling gdk_window_begin_paint_region(), the user may see flicker as individual drawing operations are performed in sequence. The clipping and background-initializing features of gdk_window_begin_paint_region() are conveniences for the programmer, so you can avoid doing that work yourself. When using GTK+, the widget system automatically places calls to gdk_window_begin_paint_region() and gdk_window_end_paint() around emissions of the expose_event signal. That is, if you’re writing an expose event handler, you can assume that the exposed area in #GdkEventExpose has already been cleared to the window background, is already set as the clip region, and already has a backing store. Therefore in most cases, application code need not call gdk_window_begin_paint_region(). (You can disable the automatic calls around expose events on a widget-by-widget basis by calling gtk_widget_set_double_buffered().) If you call this function multiple times before calling the matching gdk_window_end_paint(), the backing stores are pushed onto a stack. gdk_window_end_paint() copies the topmost backing store onscreen, subtracts the topmost region from all other regions in the stack, and pops the stack. All drawing operations affect only the topmost backing store in the stack. One matching call to gdk_window_end_paint() is required for each call to gdk_window_begin_paint_region(). Use gdk_window_begin_draw_frame() instead a #GdkWindow region you intend to draw to Begins a window resize operation (for a toplevel window). This function assumes that the drag is controlled by the client pointer device, use gdk_window_begin_resize_drag_for_device() to begin a drag with a different device. a toplevel #GdkWindow the edge or corner from which the drag is started the button being used to drag, or 0 for a keyboard-initiated drag root window X coordinate of mouse click that began the drag root window Y coordinate of mouse click that began the drag timestamp of mouse click that began the drag (use gdk_event_get_time()) Begins a window resize operation (for a toplevel window). You might use this function to implement a “window resize grip,” for example; in fact #GtkStatusbar uses it. The function works best with window managers that support the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) but has a fallback implementation for other window managers. a toplevel #GdkWindow the edge or corner from which the drag is started the device used for the operation the button being used to drag, or 0 for a keyboard-initiated drag root window X coordinate of mouse click that began the drag root window Y coordinate of mouse click that began the drag timestamp of mouse click that began the drag (use gdk_event_get_time()) Does nothing, present only for compatiblity. this function is no longer needed a toplevel #GdkWindow Transforms window coordinates from a parent window to a child window, where the parent window is the normal parent as returned by gdk_window_get_parent() for normal windows, and the window's embedder as returned by gdk_offscreen_window_get_embedder() for offscreen windows. For normal windows, calling this function is equivalent to subtracting the return values of gdk_window_get_position() from the parent coordinates. For offscreen windows however (which can be arbitrarily transformed), this function calls the GdkWindow::from-embedder: signal to translate the coordinates. You should always use this function when writing generic code that walks down a window hierarchy. See also: gdk_window_coords_to_parent() a child window X coordinate in parent’s coordinate system Y coordinate in parent’s coordinate system return location for X coordinate in child’s coordinate system return location for Y coordinate in child’s coordinate system Transforms window coordinates from a child window to its parent window, where the parent window is the normal parent as returned by gdk_window_get_parent() for normal windows, and the window's embedder as returned by gdk_offscreen_window_get_embedder() for offscreen windows. For normal windows, calling this function is equivalent to adding the return values of gdk_window_get_position() to the child coordinates. For offscreen windows however (which can be arbitrarily transformed), this function calls the GdkWindow::to-embedder: signal to translate the coordinates. You should always use this function when writing generic code that walks up a window hierarchy. See also: gdk_window_coords_from_parent() a child window X coordinate in child’s coordinate system Y coordinate in child’s coordinate system return location for X coordinate in parent’s coordinate system, or %NULL return location for Y coordinate in parent’s coordinate system, or %NULL Creates a new #GdkGLContext matching the framebuffer format to the visual of the #GdkWindow. The context is disconnected from any particular window or surface. If the creation of the #GdkGLContext failed, @error will be set. Before using the returned #GdkGLContext, you will need to call gdk_gl_context_make_current() or gdk_gl_context_realize(). the newly created #GdkGLContext, or %NULL on error a #GdkWindow Create a new image surface that is efficient to draw on the given @window. Initially the surface contents are all 0 (transparent if contents have transparency, black otherwise.) The @width and @height of the new surface are not affected by the scaling factor of the @window, or by the @scale argument; they are the size of the surface in device pixels. If you wish to create an image surface capable of holding the contents of @window you can use: |[<!-- language="C" --> int scale = gdk_window_get_scale_factor (window); int width = gdk_window_get_width (window) * scale; int height = gdk_window_get_height (window) * scale; // format is set elsewhere cairo_surface_t *surface = gdk_window_create_similar_image_surface (window, format, width, height, scale); ]| Note that unlike cairo_surface_create_similar_image(), the new surface's device scale is set to @scale, or to the scale factor of @window if @scale is 0. a pointer to the newly allocated surface. The caller owns the surface and should call cairo_surface_destroy() when done with it. This function always returns a valid pointer, but it will return a pointer to a “nil” surface if @other is already in an error state or any other error occurs. window to make new surface similar to, or %NULL if none the format for the new surface width of the new surface height of the new surface the scale of the new surface, or 0 to use same as @window Create a new surface that is as compatible as possible with the given @window. For example the new surface will have the same fallback resolution and font options as @window. Generally, the new surface will also use the same backend as @window, unless that is not possible for some reason. The type of the returned surface may be examined with cairo_surface_get_type(). Initially the surface contents are all 0 (transparent if contents have transparency, black otherwise.) a pointer to the newly allocated surface. The caller owns the surface and should call cairo_surface_destroy() when done with it. This function always returns a valid pointer, but it will return a pointer to a “nil” surface if @other is already in an error state or any other error occurs. window to make new surface similar to the content for the new surface width of the new surface height of the new surface Attempt to deiconify (unminimize) @window. On X11 the window manager may choose to ignore the request to deiconify. When using GTK+, use gtk_window_deiconify() instead of the #GdkWindow variant. Or better yet, you probably want to use gtk_window_present_with_time(), which raises the window, focuses it, unminimizes it, and puts it on the current desktop. a toplevel #GdkWindow Destroys the window system resources associated with @window and decrements @window's reference count. The window system resources for all children of @window are also destroyed, but the children’s reference counts are not decremented. Note that a window will not be destroyed automatically when its reference count reaches zero. You must call this function yourself before that happens. a #GdkWindow Does nothing, present only for compatiblity. this function is no longer needed a toplevel #GdkWindow Indicates that the drawing of the contents of @window started with gdk_window_begin_frame() has been completed. This function will take care of destroying the #GdkDrawingContext. It is an error to call this function without a matching gdk_window_begin_frame() first. a #GdkWindow the #GdkDrawingContext created by gdk_window_begin_draw_frame() Indicates that the backing store created by the most recent call to gdk_window_begin_paint_region() should be copied onscreen and deleted, leaving the next-most-recent backing store or no backing store at all as the active paint region. See gdk_window_begin_paint_region() for full details. It is an error to call this function without a matching gdk_window_begin_paint_region() first. a #GdkWindow Tries to ensure that there is a window-system native window for this GdkWindow. This may fail in some situations, returning %FALSE. Offscreen window and children of them can never have native windows. Some backends may not support native child windows. %TRUE if the window has a native window, %FALSE otherwise a #GdkWindow This function does nothing. a #GdkWindow Sets keyboard focus to @window. In most cases, gtk_window_present_with_time() should be used on a #GtkWindow, rather than calling this function. a #GdkWindow timestamp of the event triggering the window focus Temporarily freezes a window and all its descendants such that it won't receive expose events. The window will begin receiving expose events again when gdk_window_thaw_toplevel_updates_libgtk_only() is called. If gdk_window_freeze_toplevel_updates_libgtk_only() has been called more than once, gdk_window_thaw_toplevel_updates_libgtk_only() must be called an equal number of times to begin processing exposes. This function is not part of the GDK public API and is only for use by GTK+. This symbol was never meant to be used outside of GTK+ a #GdkWindow Temporarily freezes a window such that it won’t receive expose events. The window will begin receiving expose events again when gdk_window_thaw_updates() is called. If gdk_window_freeze_updates() has been called more than once, gdk_window_thaw_updates() must be called an equal number of times to begin processing exposes. a #GdkWindow Moves the window into fullscreen mode. This means the window covers the entire screen and is above any panels or task bars. If the window was already fullscreen, then this function does nothing. On X11, asks the window manager to put @window in a fullscreen state, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “fullscreen”; so you can’t rely on the fullscreenification actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. a toplevel #GdkWindow Moves the window into fullscreen mode on the given monitor. This means the window covers the entire screen and is above any panels or task bars. If the window was already fullscreen, then this function does nothing. UNRELEASED a toplevel #GdkWindow Which monitor to display fullscreen on. This function informs GDK that the geometry of an embedded offscreen window has changed. This is necessary for GDK to keep track of which offscreen window the pointer is in. an embedded offscreen #GdkWindow Determines whether or not the desktop environment shuld be hinted that the window does not want to receive input focus. whether or not the window should receive input focus. a toplevel #GdkWindow. Gets the pattern used to clear the background on @window. Don't use this function The pattern to use for the background or %NULL if there is no background. a window Gets the list of children of @window known to GDK. This function only returns children created via GDK, so for example it’s useless when used with the root window; it only returns windows an application created itself. The returned list must be freed, but the elements in the list need not be. list of child windows inside @window a #GdkWindow Gets the list of children of @window known to GDK with a particular @user_data set on it. The returned list must be freed, but the elements in the list need not be. The list is returned in (relative) stacking order, i.e. the lowest window is first. list of child windows inside @window a #GdkWindow user data to look for Computes the region of a window that potentially can be written to by drawing primitives. This region may not take into account other factors such as if the window is obscured by other windows, but no area outside of this region will be affected by drawing primitives. a #cairo_region_t. This must be freed with cairo_region_destroy() when you are done. a #GdkWindow Determines whether @window is composited. See gdk_window_set_composited(). Compositing is an outdated technology that only ever worked on X11. %TRUE if the window is composited. a #GdkWindow Retrieves a #GdkCursor pointer for the cursor currently set on the specified #GdkWindow, or %NULL. If the return value is %NULL then there is no custom cursor set on the specified window, and it is using the cursor for its parent window. a #GdkCursor, or %NULL. The returned object is owned by the #GdkWindow and should not be unreferenced directly. Use gdk_window_set_cursor() to unset the cursor of the window a #GdkWindow Returns the decorations set on the GdkWindow with gdk_window_set_decorations(). %TRUE if the window has decorations set, %FALSE otherwise. The toplevel #GdkWindow to get the decorations from The window decorations will be written here Retrieves a #GdkCursor pointer for the @device currently set on the specified #GdkWindow, or %NULL. If the return value is %NULL then there is no custom cursor set on the specified window, and it is using the cursor for its parent window. a #GdkCursor, or %NULL. The returned object is owned by the #GdkWindow and should not be unreferenced directly. Use gdk_window_set_cursor() to unset the cursor of the window a #GdkWindow. a master, pointer #GdkDevice. Returns the event mask for @window corresponding to an specific device. device event mask for @window a #GdkWindow. a #GdkDevice. Obtains the current device position and modifier state. The position is given in coordinates relative to the upper left corner of @window. Use gdk_window_get_device_position_double() if you need subpixel precision. The window underneath @device (as with gdk_device_get_window_at_position()), or %NULL if the window is not known to GDK. a #GdkWindow. pointer #GdkDevice to query to. return location for the X coordinate of @device, or %NULL. return location for the Y coordinate of @device, or %NULL. return location for the modifier mask, or %NULL. Obtains the current device position in doubles and modifier state. The position is given in coordinates relative to the upper left corner of @window. The window underneath @device (as with gdk_device_get_window_at_position()), or %NULL if the window is not known to GDK. a #GdkWindow. pointer #GdkDevice to query to. return location for the X coordinate of @device, or %NULL. return location for the Y coordinate of @device, or %NULL. return location for the modifier mask, or %NULL. Gets the #GdkDisplay associated with a #GdkWindow. the #GdkDisplay associated with @window a #GdkWindow Finds out the DND protocol supported by a window. the supported DND protocol. the destination window location of the window where the drop should happen. This may be @window or a proxy window, or %NULL if @window does not support Drag and Drop. Obtains the parent of @window, as known to GDK. Works like gdk_window_get_parent() for normal windows, but returns the window’s embedder for offscreen windows. See also: gdk_offscreen_window_get_embedder() effective parent of @window a #GdkWindow Gets the toplevel window that’s an ancestor of @window. Works like gdk_window_get_toplevel(), but treats an offscreen window's embedder as its parent, using gdk_window_get_effective_parent(). See also: gdk_offscreen_window_get_embedder() the effective toplevel window containing @window a #GdkWindow Get the current event compression setting for this window. %TRUE if motion events will be compressed a #GdkWindow Gets the event mask for @window for all master input devices. See gdk_window_set_events(). event mask for @window a #GdkWindow Determines whether or not the desktop environment should be hinted that the window does not want to receive input focus when it is mapped. whether or not the window wants to receive input focus when it is mapped. a toplevel #GdkWindow. Gets the frame clock for the window. The frame clock for a window never changes unless the window is reparented to a new toplevel window. the frame clock window to get frame clock for Obtains the bounding box of the window, including window manager titlebar/borders if any. The frame position is given in root window coordinates. To get the position of the window itself (rather than the frame) in root window coordinates, use gdk_window_get_origin(). a toplevel #GdkWindow rectangle to fill with bounding box of the window frame Obtains the #GdkFullscreenMode of the @window. The #GdkFullscreenMode applied to the window when fullscreen. a toplevel #GdkWindow Any of the return location arguments to this function may be %NULL, if you aren’t interested in getting the value of that field. The X and Y coordinates returned are relative to the parent window of @window, which for toplevels usually means relative to the window decorations (titlebar, etc.) rather than relative to the root window (screen-size background window). On the X11 platform, the geometry is obtained from the X server, so reflects the latest position of @window; this may be out-of-sync with the position of @window delivered in the most-recently-processed #GdkEventConfigure. gdk_window_get_position() in contrast gets the position from the most recent configure event. Note: If @window is not a toplevel, it is much better to call gdk_window_get_position(), gdk_window_get_width() and gdk_window_get_height() instead, because it avoids the roundtrip to the X server and because these functions support the full 32-bit coordinate space, whereas gdk_window_get_geometry() is restricted to the 16-bit coordinates of X11. a #GdkWindow return location for X coordinate of window (relative to its parent) return location for Y coordinate of window (relative to its parent) return location for width of window return location for height of window Returns the group leader window for @window. See gdk_window_set_group(). the group leader window for @window a toplevel #GdkWindow Returns the height of the given @window. On the X11 platform the returned size is the size reported in the most-recently-processed configure event, rather than the current size on the X server. The height of @window a #GdkWindow Determines whether or not the window manager is hinted that @window has modal behaviour. whether or not the window has the modal hint set. A toplevel #GdkWindow. Obtains the position of a window in root window coordinates. (Compare with gdk_window_get_position() and gdk_window_get_geometry() which return the position of a window relative to its parent window.) not meaningful, ignore a #GdkWindow return location for X coordinate return location for Y coordinate Obtains the parent of @window, as known to GDK. Does not query the X server; thus this returns the parent as passed to gdk_window_new(), not the actual parent. This should never matter unless you’re using Xlib calls mixed with GDK calls on the X11 platform. It may also matter for toplevel windows, because the window manager may choose to reparent them. Note that you should use gdk_window_get_effective_parent() when writing generic code that walks up a window hierarchy, because gdk_window_get_parent() will most likely not do what you expect if there are offscreen windows in the hierarchy. parent of @window a #GdkWindow Returns whether input to the window is passed through to the window below. See gdk_window_set_pass_through() for details a #GdkWindow Obtains the current pointer position and modifier state. The position is given in coordinates relative to the upper left corner of @window. Use gdk_window_get_device_position() instead. the window containing the pointer (as with gdk_window_at_pointer()), or %NULL if the window containing the pointer isn’t known to GDK a #GdkWindow return location for X coordinate of pointer or %NULL to not return the X coordinate return location for Y coordinate of pointer or %NULL to not return the Y coordinate return location for modifier mask or %NULL to not return the modifier mask Obtains the position of the window as reported in the most-recently-processed #GdkEventConfigure. Contrast with gdk_window_get_geometry() which queries the X server for the current window position, regardless of which events have been received or processed. The position coordinates are relative to the window’s parent window. a #GdkWindow X coordinate of window Y coordinate of window Obtains the position of a window position in root window coordinates. This is similar to gdk_window_get_origin() but allows you to pass in any position in the window, not just the origin. a #GdkWindow X coordinate in window Y coordinate in window return location for X coordinate return location for Y coordinate Obtains the top-left corner of the window manager frame in root window coordinates. a toplevel #GdkWindow return location for X position of window frame return location for Y position of window frame Returns the internal scale factor that maps from window coordiantes to the actual device pixels. On traditional systems this is 1, but on very high density outputs this can be a higher value (often 2). A higher value means that drawing is automatically scaled up to a higher resolution, so any code doing drawing will automatically look nicer. However, if you are supplying pixel-based data the scale value can be used to determine whether to use a pixel resource with higher resolution data. The scale of a window may change during runtime, if this happens a configure event will be sent to the toplevel window. the scale factor window to get scale factor for Gets the #GdkScreen associated with a #GdkWindow. the #GdkScreen associated with @window a #GdkWindow Returns the event mask for @window corresponding to the device class specified by @source. source event mask for @window a #GdkWindow a #GdkInputSource to define the source class. Gets the bitwise OR of the currently active window state flags, from the #GdkWindowState enumeration. window state bitfield a #GdkWindow Returns %TRUE if the window is aware of the existence of multiple devices. %TRUE if the window handles multidevice features. a #GdkWindow. Gets the toplevel window that’s an ancestor of @window. Any window type but %GDK_WINDOW_CHILD is considered a toplevel window, as is a %GDK_WINDOW_CHILD window that has a root window as parent. Note that you should use gdk_window_get_effective_toplevel() when you want to get to a window’s toplevel as seen on screen, because gdk_window_get_toplevel() will most likely not do what you expect if there are offscreen windows in the hierarchy. the toplevel window containing @window a #GdkWindow This function returns the type hint set for a window. The type hint set for @window A toplevel #GdkWindow Transfers ownership of the update area from @window to the caller of the function. That is, after calling this function, @window will no longer have an invalid/dirty region; the update area is removed from @window and handed to you. If a window has no update area, gdk_window_get_update_area() returns %NULL. You are responsible for calling cairo_region_destroy() on the returned region if it’s non-%NULL. the update area for @window a #GdkWindow Retrieves the user data for @window, which is normally the widget that @window belongs to. See gdk_window_set_user_data(). a #GdkWindow return location for user data Computes the region of the @window that is potentially visible. This does not necessarily take into account if the window is obscured by other windows, but no area outside of this region is visible. a #cairo_region_t. This must be freed with cairo_region_destroy() when you are done. a #GdkWindow Gets the #GdkVisual describing the pixel format of @window. a #GdkVisual a #GdkWindow Returns the width of the given @window. On the X11 platform the returned size is the size reported in the most-recently-processed configure event, rather than the current size on the X server. The width of @window a #GdkWindow Gets the type of the window. See #GdkWindowType. type of window a #GdkWindow Checks whether the window has a native window or not. Note that you can use gdk_window_ensure_native() if a native window is needed. %TRUE if the @window has a native window, %FALSE otherwise. a #GdkWindow For toplevel windows, withdraws them, so they will no longer be known to the window manager; for all windows, unmaps them, so they won’t be displayed. Normally done automatically as part of gtk_widget_hide(). a #GdkWindow Asks to iconify (minimize) @window. The window manager may choose to ignore the request, but normally will honor it. Using gtk_window_iconify() is preferred, if you have a #GtkWindow widget. This function only makes sense when @window is a toplevel window. a toplevel #GdkWindow Like gdk_window_shape_combine_region(), but the shape applies only to event handling. Mouse events which happen while the pointer position corresponds to an unset bit in the mask will be passed on the window below @window. An input shape is typically used with RGBA windows. The alpha channel of the window defines which pixels are invisible and allows for nicely antialiased borders, and the input shape controls where the window is “clickable”. On the X11 platform, this requires version 1.1 of the shape extension. On the Win32 platform, this functionality is not present and the function does nothing. a #GdkWindow region of window to be non-transparent X position of @shape_region in @window coordinates Y position of @shape_region in @window coordinates Adds @region to the update area for @window. The update area is the region that needs to be redrawn, or “dirty region.” The call gdk_window_process_updates() sends one or more expose events to the window, which together cover the entire update area. An application would normally redraw the contents of @window in response to those expose events. GDK will call gdk_window_process_all_updates() on your behalf whenever your program returns to the main loop and becomes idle, so normally there’s no need to do that manually, you just need to invalidate regions that you know should be redrawn. The @child_func parameter controls whether the region of each child window that intersects @region will also be invalidated. Only children for which @child_func returns #TRUE will have the area invalidated. a #GdkWindow a #cairo_region_t function to use to decide if to recurse to a child, %NULL means never recurse. data passed to @child_func A convenience wrapper around gdk_window_invalidate_region() which invalidates a rectangular region. See gdk_window_invalidate_region() for details. a #GdkWindow rectangle to invalidate or %NULL to invalidate the whole window whether to also invalidate child windows Adds @region to the update area for @window. The update area is the region that needs to be redrawn, or “dirty region.” The call gdk_window_process_updates() sends one or more expose events to the window, which together cover the entire update area. An application would normally redraw the contents of @window in response to those expose events. GDK will call gdk_window_process_all_updates() on your behalf whenever your program returns to the main loop and becomes idle, so normally there’s no need to do that manually, you just need to invalidate regions that you know should be redrawn. The @invalidate_children parameter controls whether the region of each child window that intersects @region will also be invalidated. If %FALSE, then the update area for child windows will remain unaffected. See gdk_window_invalidate_maybe_recurse if you need fine grained control over which children are invalidated. a #GdkWindow a #cairo_region_t %TRUE to also invalidate child windows Check to see if a window is destroyed.. %TRUE if the window is destroyed a #GdkWindow Determines whether or not the window is an input only window. %TRUE if @window is input only a toplevel #GdkWindow Determines whether or not the window is shaped. %TRUE if @window is shaped a toplevel #GdkWindow Check if the window and all ancestors of the window are mapped. (This is not necessarily "viewable" in the X sense, since we only check as far as we have GDK window parents, not to the root window.) %TRUE if the window is viewable a #GdkWindow Checks whether the window has been mapped (with gdk_window_show() or gdk_window_show_unraised()). %TRUE if the window is mapped a #GdkWindow Lowers @window to the bottom of the Z-order (stacking order), so that other windows with the same parent window appear above @window. This is true whether or not the other windows are visible. If @window is a toplevel, the window manager may choose to deny the request to move the window in the Z-order, gdk_window_lower() only requests the restack, does not guarantee it. Note that gdk_window_show() raises the window again, so don’t call this function before gdk_window_show(). (Try gdk_window_show_unraised().) a #GdkWindow If you call this during a paint (e.g. between gdk_window_begin_paint_region() and gdk_window_end_paint() then GDK will mark the current clip region of the window as being drawn. This is required when mixing GL rendering via gdk_cairo_draw_from_gl() and cairo rendering, as otherwise GDK has no way of knowing when something paints over the GL-drawn regions. This is typically called automatically by GTK+ and you don't need to care about this. a #GdkWindow a #cairo_t Maximizes the window. If the window was already maximized, then this function does nothing. On X11, asks the window manager to maximize @window, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “maximized”; so you can’t rely on the maximization actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. On Windows, reliably maximizes the window. a toplevel #GdkWindow Merges the input shape masks for any child windows into the input shape mask for @window. i.e. the union of all input masks for @window and its children will become the new input mask for @window. See gdk_window_input_shape_combine_region(). This function is distinct from gdk_window_set_child_input_shapes() because it includes @window’s input shape mask in the set of shapes to be merged. a #GdkWindow Merges the shape masks for any child windows into the shape mask for @window. i.e. the union of all masks for @window and its children will become the new mask for @window. See gdk_window_shape_combine_region(). This function is distinct from gdk_window_set_child_shapes() because it includes @window’s shape mask in the set of shapes to be merged. a #GdkWindow Repositions a window relative to its parent window. For toplevel windows, window managers may ignore or modify the move; you should probably use gtk_window_move() on a #GtkWindow widget anyway, instead of using GDK functions. For child windows, the move will reliably succeed. If you’re also planning to resize the window, use gdk_window_move_resize() to both move and resize simultaneously, for a nicer visual effect. a #GdkWindow X coordinate relative to window’s parent Y coordinate relative to window’s parent Move the part of @window indicated by @region by @dy pixels in the Y direction and @dx pixels in the X direction. The portions of @region that not covered by the new position of @region are invalidated. Child windows are not moved. a #GdkWindow The #cairo_region_t to move Amount to move in the X direction Amount to move in the Y direction Equivalent to calling gdk_window_move() and gdk_window_resize(), except that both operations are performed at once, avoiding strange visual effects. (i.e. the user may be able to see the window first move, then resize, if you don’t use gdk_window_move_resize().) a #GdkWindow new X position relative to window’s parent new Y position relative to window’s parent new width new height Moves @window to @rect, aligning their anchor points. @rect is relative to the top-left corner of the window that @window is transient for. @rect_anchor and @window_anchor determine anchor points on @rect and @window to pin together. @rect's anchor point can optionally be offset by @rect_anchor_dx and @rect_anchor_dy, which is equivalent to offsetting the position of @window. @anchor_hints determines how @window will be moved if the anchor points cause it to move off-screen. For example, %GDK_ANCHOR_FLIP_X will replace %GDK_GRAVITY_NORTH_WEST with %GDK_GRAVITY_NORTH_EAST and vice versa if @window extends beyond the left or right edges of the monitor. Connect to the #GdkWindow::moved-to-rect signal to find out how it was actually positioned. the #GdkWindow to move the destination #GdkRectangle to align @window with the point on @rect to align with @window's anchor point the point on @window to align with @rect's anchor point positioning hints to use when limited on space horizontal offset to shift @window, i.e. @rect's anchor point vertical offset to shift @window, i.e. @rect's anchor point Like gdk_window_get_children(), but does not copy the list of children, so the list does not need to be freed. a reference to the list of child windows in @window a #GdkWindow Sends one or more expose events to @window. The areas in each expose event will cover the entire update area for the window (see gdk_window_invalidate_region() for details). Normally GDK calls gdk_window_process_all_updates() on your behalf, so there’s no need to call this function unless you want to force expose events to be delivered immediately and synchronously (vs. the usual case, where GDK delivers them in an idle handler). Occasionally this is useful to produce nicer scrolling behavior, for example. a #GdkWindow whether to also process updates for child windows Raises @window to the top of the Z-order (stacking order), so that other windows with the same parent window appear below @window. This is true whether or not the windows are visible. If @window is a toplevel, the window manager may choose to deny the request to move the window in the Z-order, gdk_window_raise() only requests the restack, does not guarantee it. a #GdkWindow Registers a window as a potential drop destination. a #GdkWindow. Remove a filter previously added with gdk_window_add_filter(). a #GdkWindow previously-added filter function user data for previously-added filter function Reparents @window into the given @new_parent. The window being reparented will be unmapped as a side effect. a #GdkWindow new parent to move @window into X location inside the new parent Y location inside the new parent Resizes @window; for toplevel windows, asks the window manager to resize the window. The window manager may not allow the resize. When using GTK+, use gtk_window_resize() instead of this low-level GDK function. Windows may not be resized below 1x1. If you’re also planning to move the window, use gdk_window_move_resize() to both move and resize simultaneously, for a nicer visual effect. a #GdkWindow new width of the window new height of the window Changes the position of @window in the Z-order (stacking order), so that it is above @sibling (if @above is %TRUE) or below @sibling (if @above is %FALSE). If @sibling is %NULL, then this either raises (if @above is %TRUE) or lowers the window. If @window is a toplevel, the window manager may choose to deny the request to move the window in the Z-order, gdk_window_restack() only requests the restack, does not guarantee it. a #GdkWindow a #GdkWindow that is a sibling of @window, or %NULL a boolean Scroll the contents of @window, both pixels and children, by the given amount. @window itself does not move. Portions of the window that the scroll operation brings in from offscreen areas are invalidated. The invalidated region may be bigger than what would strictly be necessary. For X11, a minimum area will be invalidated if the window has no subwindows, or if the edges of the window’s parent do not extend beyond the edges of the window. In other cases, a multi-step process is used to scroll the window which may produce temporary visual artifacts and unnecessary invalidations. a #GdkWindow Amount to scroll in the X direction Amount to scroll in the Y direction Setting @accept_focus to %FALSE hints the desktop environment that the window doesn’t want to receive input focus. On X, it is the responsibility of the window manager to interpret this hint. ICCCM-compliant window manager usually respect it. a toplevel #GdkWindow %TRUE if the window should receive input focus Sets the background color of @window. However, when using GTK+, influence the background of a widget using a style class or CSS — if you’re an application — or with gtk_style_context_set_background() — if you're implementing a custom widget. Don't use this function a #GdkWindow a #GdkColor Sets the background of @window. A background of %NULL means that the window won't have any background. On the X11 backend it's also possible to inherit the background from the parent window using gdk_x11_get_parent_relative_pattern(). The windowing system will normally fill a window with its background when the window is obscured then exposed. Don't use this function a #GdkWindow a pattern to use, or %NULL Sets the background color of @window. See also gdk_window_set_background_pattern(). Don't use this function a #GdkWindow a #GdkRGBA color Sets the input shape mask of @window to the union of input shape masks for all children of @window, ignoring the input shape mask of @window itself. Contrast with gdk_window_merge_child_input_shapes() which includes the input shape mask of @window in the masks to be merged. a #GdkWindow Sets the shape mask of @window to the union of shape masks for all children of @window, ignoring the shape mask of @window itself. Contrast with gdk_window_merge_child_shapes() which includes the shape mask of @window in the masks to be merged. a #GdkWindow Sets a #GdkWindow as composited, or unsets it. Composited windows do not automatically have their contents drawn to the screen. Drawing is redirected to an offscreen buffer and an expose event is emitted on the parent of the composited window. It is the responsibility of the parent’s expose handler to manually merge the off-screen content onto the screen in whatever way it sees fit. It only makes sense for child windows to be composited; see gdk_window_set_opacity() if you need translucent toplevel windows. An additional effect of this call is that the area of this window is no longer clipped from regions marked for invalidation on its parent. Draws done on the parent window are also no longer clipped by the child. This call is only supported on some systems (currently, only X11 with new enough Xcomposite and Xdamage extensions). You must call gdk_display_supports_composite() to check if setting a window as composited is supported before attempting to do so. Compositing is an outdated technology that only ever worked on X11. a #GdkWindow %TRUE to set the window as composited Sets the default mouse pointer for a #GdkWindow. Note that @cursor must be for the same display as @window. Use gdk_cursor_new_for_display() or gdk_cursor_new_from_pixbuf() to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. Passing %NULL for the @cursor argument to gdk_window_set_cursor() means that @window will use the cursor of its parent window. Most windows should use this default. a #GdkWindow a cursor “Decorations” are the features the window manager adds to a toplevel #GdkWindow. This function sets the traditional Motif window manager hints that tell the window manager which decorations you would like your window to have. Usually you should use gtk_window_set_decorated() on a #GtkWindow instead of using the GDK function directly. The @decorations argument is the logical OR of the fields in the #GdkWMDecoration enumeration. If #GDK_DECOR_ALL is included in the mask, the other bits indicate which decorations should be turned off. If #GDK_DECOR_ALL is not included, then the other bits indicate which decorations should be turned on. Most window managers honor a decorations hint of 0 to disable all decorations, but very few honor all possible combinations of bits. a toplevel #GdkWindow decoration hint mask Sets a specific #GdkCursor for a given device when it gets inside @window. Use gdk_cursor_new_for_display() or gdk_cursor_new_from_pixbuf() to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. Passing %NULL for the @cursor argument to gdk_window_set_cursor() means that @window will use the cursor of its parent window. Most windows should use this default. a #GdkWindow a master, pointer #GdkDevice a #GdkCursor Sets the event mask for a given device (Normally a floating device, not attached to any visible pointer) to @window. For example, an event mask including #GDK_BUTTON_PRESS_MASK means the window should report button press events. The event mask is the bitwise OR of values from the #GdkEventMask enumeration. See the [input handling overview][event-masks] for details. a #GdkWindow #GdkDevice to enable events for. event mask for @window Determines whether or not extra unprocessed motion events in the event queue can be discarded. If %TRUE only the most recent event will be delivered. Some types of applications, e.g. paint programs, need to see all motion events and will benefit from turning off event compression. By default, event compression is enabled. a #GdkWindow %TRUE if motion events should be compressed The event mask for a window determines which events will be reported for that window from all master input devices. For example, an event mask including #GDK_BUTTON_PRESS_MASK means the window should report button press events. The event mask is the bitwise OR of values from the #GdkEventMask enumeration. See the [input handling overview][event-masks] for details. a #GdkWindow event mask for @window Setting @focus_on_map to %FALSE hints the desktop environment that the window doesn’t want to receive input focus when it is mapped. focus_on_map should be turned off for windows that aren’t triggered interactively (such as popups from network activity). On X, it is the responsibility of the window manager to interpret this hint. Window managers following the freedesktop.org window manager extension specification should respect it. a toplevel #GdkWindow %TRUE if the window should receive input focus when mapped Specifies whether the @window should span over all monitors (in a multi-head setup) or only the current monitor when in fullscreen mode. The @mode argument is from the #GdkFullscreenMode enumeration. If #GDK_FULLSCREEN_ON_ALL_MONITORS is specified, the fullscreen @window will span over all monitors from the #GdkScreen. On X11, searches through the list of monitors from the #GdkScreen the ones which delimit the 4 edges of the entire #GdkScreen and will ask the window manager to span the @window over these monitors. If the XINERAMA extension is not available or not usable, this function has no effect. Not all window managers support this, so you can’t rely on the fullscreen window to span over the multiple monitors when #GDK_FULLSCREEN_ON_ALL_MONITORS is specified. a toplevel #GdkWindow fullscreen mode Sets hints about the window management functions to make available via buttons on the window frame. On the X backend, this function sets the traditional Motif window manager hint for this purpose. However, few window managers do anything reliable or interesting with this hint. Many ignore it entirely. The @functions argument is the logical OR of values from the #GdkWMFunction enumeration. If the bitmask includes #GDK_FUNC_ALL, then the other bits indicate which functions to disable; if it doesn’t include #GDK_FUNC_ALL, it indicates which functions to enable. a toplevel #GdkWindow bitmask of operations to allow on @window Sets the geometry hints for @window. Hints flagged in @geom_mask are set, hints not flagged in @geom_mask are unset. To unset all hints, use a @geom_mask of 0 and a @geometry of %NULL. This function provides hints to the windowing system about acceptable sizes for a toplevel window. The purpose of this is to constrain user resizing, but the windowing system will typically (but is not required to) also constrain the current size of the window to the provided values and constrain programatic resizing via gdk_window_resize() or gdk_window_move_resize(). Note that on X11, this effect has no effect on windows of type %GDK_WINDOW_TEMP or windows where override redirect has been turned on via gdk_window_set_override_redirect() since these windows are not resizable by the user. Since you can’t count on the windowing system doing the constraints for programmatic resizes, you should generally call gdk_window_constrain_size() yourself to determine appropriate sizes. a toplevel #GdkWindow geometry hints bitmask indicating fields of @geometry to pay attention to Sets the group leader window for @window. By default, GDK sets the group leader for all toplevel windows to a global window implicitly created by GDK. With this function you can override this default. The group leader window allows the window manager to distinguish all windows that belong to a single application. It may for example allow users to minimize/unminimize all windows belonging to an application at once. You should only set a non-default group window if your application pretends to be multiple applications. a toplevel #GdkWindow group leader window, or %NULL to restore the default group leader window Sets a list of icons for the window. One of these will be used to represent the window when it has been iconified. The icon is usually shown in an icon box or some sort of task bar. Which icon size is shown depends on the window manager. The window manager can scale the icon but setting several size icons can give better image quality since the window manager may only need to scale the icon by a small amount or not at all. Note that some platforms don't support window icons. The #GdkWindow toplevel window to set the icon of. A list of pixbufs, of different sizes. Windows may have a name used while minimized, distinct from the name they display in their titlebar. Most of the time this is a bad idea from a user interface standpoint. But you can set such a name with this function, if you like. After calling this with a non-%NULL @name, calls to gdk_window_set_title() will not update the icon title. Using %NULL for @name unsets the icon title; further calls to gdk_window_set_title() will again update the icon title as well. Note that some platforms don't support window icons. a toplevel #GdkWindow name of window while iconified (minimized) Registers an invalidate handler for a specific window. This will get called whenever a region in the window or its children is invalidated. This can be used to record the invalidated region, which is useful if you are keeping an offscreen copy of some region and want to keep it up to date. You can also modify the invalidated region in case you’re doing some effect where e.g. a child widget appears in multiple places. a #GdkWindow a #GdkWindowInvalidateHandlerFunc callback function Set if @window must be kept above other windows. If the window was already above, then this function does nothing. On X11, asks the window manager to keep @window above, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “keep above”; so you can’t rely on the window being kept above. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. a toplevel #GdkWindow whether to keep @window above other windows Set if @window must be kept below other windows. If the window was already below, then this function does nothing. On X11, asks the window manager to keep @window below, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “keep below”; so you can’t rely on the window being kept below. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. a toplevel #GdkWindow whether to keep @window below other windows The application can use this hint to tell the window manager that a certain window has modal behaviour. The window manager can use this information to handle modal windows in a special way. You should only use this on windows for which you have previously called gdk_window_set_transient_for() A toplevel #GdkWindow %TRUE if the window is modal, %FALSE otherwise. Set @window to render as partially transparent, with opacity 0 being fully transparent and 1 fully opaque. (Values of the opacity parameter are clamped to the [0,1] range.) For toplevel windows this depends on support from the windowing system that may not always be there. For instance, On X11, this works only on X screens with a compositing manager running. On Wayland, there is no per-window opacity value that the compositor would apply. Instead, use `gdk_window_set_opaque_region (window, NULL)` to tell the compositor that the entire window is (potentially) non-opaque, and draw your content with alpha, or use gtk_widget_set_opacity() to set an overall opacity for your widgets. For child windows this function only works for non-native windows. For setting up per-pixel alpha topelevels, see gdk_screen_get_rgba_visual(), and for non-toplevels, see gdk_window_set_composited(). Support for non-toplevel windows was added in 3.8. a top-level or non-native #GdkWindow opacity For optimisation purposes, compositing window managers may like to not draw obscured regions of windows, or turn off blending during for these regions. With RGB windows with no transparency, this is just the shape of the window, but with ARGB32 windows, the compositor does not know what regions of the window are transparent or not. This function only works for toplevel windows. GTK+ will update this property automatically if the @window background is opaque, as we know where the opaque regions are. If your window background is not opaque, please update this property in your #GtkWidget::style-updated handler. a top-level or non-native #GdkWindow a region, or %NULL An override redirect window is not under the control of the window manager. This means it won’t have a titlebar, won’t be minimizable, etc. - it will be entirely under the control of the application. The window manager can’t see the override redirect window at all. Override redirect should only be used for short-lived temporary windows, such as popup menus. #GtkMenu uses an override redirect window in its implementation, for example. a toplevel #GdkWindow %TRUE if window should be override redirect Sets whether input to the window is passed through to the window below. The default value of this is %FALSE, which means that pointer events that happen inside the window are send first to the window, but if the event is not selected by the event mask then the event is sent to the parent window, and so on up the hierarchy. If @pass_through is %TRUE then such pointer events happen as if the window wasn't there at all, and thus will be sent first to any windows below @window. This is useful if the window is used in a transparent fashion. In the terminology of the web this would be called "pointer-events: none". Note that a window with @pass_through %TRUE can still have a subwindow without pass through, so you can get events on a subset of a window. And in that cases you would get the in-between related events such as the pointer enter/leave events on its way to the destination window. a #GdkWindow a boolean When using GTK+, typically you should use gtk_window_set_role() instead of this low-level function. The window manager and session manager use a window’s role to distinguish it from other kinds of window in the same application. When an application is restarted after being saved in a previous session, all windows with the same title and role are treated as interchangeable. So if you have two windows with the same title that should be distinguished for session management purposes, you should set the role on those windows. It doesn’t matter what string you use for the role, as long as you have a different role for each non-interchangeable kind of window. a toplevel #GdkWindow a string indicating its role Newer GTK+ windows using client-side decorations use extra geometry around their frames for effects like shadows and invisible borders. Window managers that want to maximize windows or snap to edges need to know where the extents of the actual frame lie, so that users don’t feel like windows are snapping against random invisible edges. Note that this property is automatically updated by GTK+, so this function should only be used by applications which do not use GTK+ to create toplevel windows. a #GdkWindow The left extent The right extent The top extent The bottom extent Toggles whether a window should appear in a pager (workspace switcher, or other desktop utility program that displays a small thumbnail representation of the windows on the desktop). If a window’s semantic type as specified with gdk_window_set_type_hint() already fully describes the window, this function should not be called in addition, instead you should allow the window to be treated according to standard policy for its semantic type. a toplevel #GdkWindow %TRUE to skip the pager Toggles whether a window should appear in a task list or window list. If a window’s semantic type as specified with gdk_window_set_type_hint() already fully describes the window, this function should not be called in addition, instead you should allow the window to be treated according to standard policy for its semantic type. a toplevel #GdkWindow %TRUE to skip the taskbar Sets the event mask for any floating device (i.e. not attached to any visible pointer) that has the source defined as @source. This event mask will be applied both to currently existing, newly added devices after this call, and devices being attached/detached. a #GdkWindow a #GdkInputSource to define the source class. event mask for @window When using GTK+, typically you should use gtk_window_set_startup_id() instead of this low-level function. a toplevel #GdkWindow a string with startup-notification identifier Used to set the bit gravity of the given window to static, and flag it so all children get static subwindow gravity. This is used if you are implementing scary features that involve deep knowledge of the windowing system. Don’t worry about it. static gravities haven't worked on anything but X11 for a long time. %FALSE a #GdkWindow %TRUE to turn on static gravity This function will enable multidevice features in @window. Multidevice aware windows will need to handle properly multiple, per device enter/leave events, device grabs and grab ownerships. a #GdkWindow. %TRUE to enable multidevice support in @window. Sets the title of a toplevel window, to be displayed in the titlebar. If you haven’t explicitly set the icon name for the window (using gdk_window_set_icon_name()), the icon name will be set to @title as well. @title must be in UTF-8 encoding (as with all user-readable strings in GDK/GTK+). @title may not be %NULL. a toplevel #GdkWindow title of @window Indicates to the window manager that @window is a transient dialog associated with the application window @parent. This allows the window manager to do things like center @window on @parent and keep @window above @parent. See gtk_window_set_transient_for() if you’re using #GtkWindow or #GtkDialog. a toplevel #GdkWindow another toplevel #GdkWindow The application can use this call to provide a hint to the window manager about the functionality of a window. The window manager can use this information when determining the decoration and behaviour of the window. The hint must be set before the window is mapped. A toplevel #GdkWindow A hint of the function this window will have Toggles whether a window needs the user's urgent attention. a toplevel #GdkWindow %TRUE if the window is urgent For most purposes this function is deprecated in favor of g_object_set_data(). However, for historical reasons GTK+ stores the #GtkWidget that owns a #GdkWindow as user data on the #GdkWindow. So, custom widget implementations should use this function for that. If GTK+ receives an event for a #GdkWindow, and the user data for the window is non-%NULL, GTK+ will assume the user data is a #GtkWidget, and forward the event to that widget. a #GdkWindow user data Makes pixels in @window outside @shape_region be transparent, so that the window may be nonrectangular. If @shape_region is %NULL, the shape will be unset, so the whole window will be opaque again. @offset_x and @offset_y are ignored if @shape_region is %NULL. On the X11 platform, this uses an X server extension which is widely available on most common platforms, but not available on very old X servers, and occasionally the implementation will be buggy. On servers without the shape extension, this function will do nothing. This function works on both toplevel and child windows. a #GdkWindow region of window to be non-transparent X position of @shape_region in @window coordinates Y position of @shape_region in @window coordinates Like gdk_window_show_unraised(), but also raises the window to the top of the window stack (moves the window to the front of the Z-order). This function maps a window so it’s visible onscreen. Its opposite is gdk_window_hide(). When implementing a #GtkWidget, you should call this function on the widget's #GdkWindow as part of the “map” method. a #GdkWindow Shows a #GdkWindow onscreen, but does not modify its stacking order. In contrast, gdk_window_show() will raise the window to the top of the window stack. On the X11 platform, in Xlib terms, this function calls XMapWindow() (it also updates some internal GDK state, which means that you can’t really use XMapWindow() directly on a GDK window). a #GdkWindow Asks the windowing system to show the window menu. The window menu is the menu shown when right-clicking the titlebar on traditional windows managed by the window manager. This is useful for windows using client-side decorations, activating it with a right-click on the window decorations. %TRUE if the window menu was shown and %FALSE otherwise. a #GdkWindow a #GdkEvent to show the menu for “Pins” a window such that it’s on all workspaces and does not scroll with viewports, for window managers that have scrollable viewports. (When using #GtkWindow, gtk_window_stick() may be more useful.) On the X11 platform, this function depends on window manager support, so may have no effect with many window managers. However, GDK will do the best it can to convince the window manager to stick the window. For window managers that don’t support this operation, there’s nothing you can do to force it to happen. a toplevel #GdkWindow Thaws a window frozen with gdk_window_freeze_toplevel_updates_libgtk_only(). This function is not part of the GDK public API and is only for use by GTK+. This symbol was never meant to be used outside of GTK+ a #GdkWindow Thaws a window frozen with gdk_window_freeze_updates(). a #GdkWindow Moves the window out of fullscreen mode. If the window was not fullscreen, does nothing. On X11, asks the window manager to move @window out of the fullscreen state, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “fullscreen”; so you can’t rely on the unfullscreenification actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. a toplevel #GdkWindow Unmaximizes the window. If the window wasn’t maximized, then this function does nothing. On X11, asks the window manager to unmaximize @window, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “maximized”; so you can’t rely on the unmaximization actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. On Windows, reliably unmaximizes the window. a toplevel #GdkWindow Reverse operation for gdk_window_stick(); see gdk_window_stick(), and gtk_window_unstick(). a toplevel #GdkWindow Withdraws a window (unmaps it and asks the window manager to forget about it). This function is not really useful as gdk_window_hide() automatically withdraws toplevel windows before hiding them. a toplevel #GdkWindow The mouse pointer for a #GdkWindow. See gdk_window_set_cursor() and gdk_window_get_cursor() for details. The ::create-surface signal is emitted when an offscreen window needs its surface (re)created, which happens either when the window is first drawn to, or when the window is being resized. The first signal handler that returns a non-%NULL surface will stop any further signal emission, and its surface will be used. Note that it is not possible to access the window's previous surface from within any callback of this signal. Calling gdk_offscreen_window_get_surface() will lead to a crash. the newly created #cairo_surface_t for the offscreen window the width of the offscreen surface to create the height of the offscreen surface to create The ::from-embedder signal is emitted to translate coordinates in the embedder of an offscreen window to the offscreen window. See also #GdkWindow::to-embedder. x coordinate in the embedder window y coordinate in the embedder window return location for the x coordinate in the offscreen window return location for the y coordinate in the offscreen window Emitted when the position of @window is finalized after being moved to a destination rectangle. @window might be flipped over the destination rectangle in order to keep it on-screen, in which case @flipped_x and @flipped_y will be set to %TRUE accordingly. @flipped_rect is the ideal position of @window after any possible flipping, but before any possible sliding. @final_rect is @flipped_rect, but possibly translated in the case that flipping is still ineffective in keeping @window on-screen. the position of @window after any possible flipping or %NULL if the backend can't obtain it the final position of @window or %NULL if the backend can't obtain it %TRUE if the anchors were flipped horizontally %TRUE if the anchors were flipped vertically The ::pick-embedded-child signal is emitted to find an embedded child at the given position. the #GdkWindow of the embedded child at @x, @y, or %NULL x coordinate in the window y coordinate in the window The ::to-embedder signal is emitted to translate coordinates in an offscreen window to its embedder. See also #GdkWindow::from-embedder. x coordinate in the offscreen window y coordinate in the offscreen window return location for the x coordinate in the embedder window return location for the y coordinate in the embedder window Attributes to use for a newly-created window. title of the window (for toplevel windows) event mask (see gdk_window_set_events()) X coordinate relative to parent window (see gdk_window_move()) Y coordinate relative to parent window (see gdk_window_move()) width of window height of window #GDK_INPUT_OUTPUT (normal window) or #GDK_INPUT_ONLY (invisible window that receives events) #GdkVisual for window type of window cursor for the window (see gdk_window_set_cursor()) don’t use (see gtk_window_set_wmclass()) don’t use (see gtk_window_set_wmclass()) %TRUE to bypass the window manager a hint of the function of the window Used to indicate which fields in the #GdkWindowAttr struct should be honored. For example, if you filled in the “cursor” and “x” fields of #GdkWindowAttr, pass “@GDK_WA_X | @GDK_WA_CURSOR” to gdk_window_new(). Fields in #GdkWindowAttr not covered by a bit in this enum are required; for example, the @width/@height, @wclass, and @window_type fields are required, they have no corresponding flag in #GdkWindowAttributesType. Honor the title field Honor the X coordinate field Honor the Y coordinate field Honor the cursor field Honor the visual field Honor the wmclass_class and wmclass_name fields Honor the override_redirect field Honor the type_hint field A function of this type is passed to gdk_window_invalidate_maybe_recurse(). It gets called for each child of the window to determine whether to recursively invalidate it or now. %TRUE to invalidate @window recursively a #GdkWindow user data Determines a window edge or corner. the top left corner. the top edge. the top right corner. the left edge. the right edge. the lower left corner. the lower edge. the lower right corner. Used to indicate which fields of a #GdkGeometry struct should be paid attention to. Also, the presence/absence of @GDK_HINT_POS, @GDK_HINT_USER_POS, and @GDK_HINT_USER_SIZE is significant, though they don't directly refer to #GdkGeometry fields. @GDK_HINT_USER_POS will be set automatically by #GtkWindow if you call gtk_window_move(). @GDK_HINT_USER_POS and @GDK_HINT_USER_SIZE should be set if the user specified a size/position using a --geometry command-line argument; gtk_window_parse_geometry() automatically sets these flags. indicates that the program has positioned the window min size fields are set max size fields are set base size fields are set aspect ratio fields are set resize increment fields are set window gravity field is set indicates that the window’s position was explicitly set by the user indicates that the window’s size was explicitly set by the user Whenever some area of the window is invalidated (directly in the window or in a child window) this gets called with @region in the coordinate space of @window. You can use @region to just keep track of the dirty region, or you can actually change @region in case you are doing display tricks like showing a child in multiple places. a #GdkWindow a #cairo_region_t Specifies the state of a toplevel window. the window is not shown. the window is minimized. the window is maximized. the window is sticky. the window is maximized without decorations. the window is kept above other windows. the window is kept below other windows. the window is presented as focused (with active decorations). the window is in a tiled state, Since 3.10. Since 3.22.23, this is deprecated in favor of per-edge information. whether the top edge is tiled, Since 3.22.23 whether the top edge is resizable, Since 3.22.23 whether the right edge is tiled, Since 3.22.23 whether the right edge is resizable, Since 3.22.23 whether the bottom edge is tiled, Since 3.22.23 whether the bottom edge is resizable, Since 3.22.23 whether the left edge is tiled, Since 3.22.23 whether the left edge is resizable, Since 3.22.23 Describes the kind of window. root window; this window has no parent, covers the entire screen, and is created by the window system toplevel window (used to implement #GtkWindow) child window (used to implement e.g. #GtkEntry) override redirect temporary window (used to implement #GtkMenu) foreign window (see gdk_window_foreign_new()) offscreen window (see [Offscreen Windows][OFFSCREEN-WINDOWS]). Since 2.18 subsurface-based window; This window is visually tied to a toplevel, and is moved/stacked with it. Currently this window type is only implemented in Wayland. Since 3.14 These are hints for the window manager that indicate what type of function the window has. The window manager can use this when determining decoration and behaviour of the window. The hint must be set before mapping the window. See the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification for more details about window types. Normal toplevel window. Dialog window. Window used to implement a menu; GTK+ uses this hint only for torn-off menus, see #GtkTearoffMenuItem. Window used to implement toolbars. Window used to display a splash screen during application startup. Utility windows which are not detached toolbars or dialogs. Used for creating dock or panel windows. Used for creating the desktop background window. A menu that belongs to a menubar. A menu that does not belong to a menubar, e.g. a context menu. A tooltip. A notification - typically a “bubble” that belongs to a status icon. A popup from a combo box. A window that is used to implement a DND cursor. @GDK_INPUT_OUTPUT windows are the standard kind of window you might expect. Such windows receive events and are also displayed on screen. @GDK_INPUT_ONLY windows are invisible; they are usually placed above other windows in order to trap or filter the events. You can’t draw on @GDK_INPUT_ONLY windows. window for graphics and events window for events only Appends gdk option entries to the passed in option group. This is not public API and must not be used by applications. This symbol was never meant to be used outside of GTK+ An option group. Finds or creates an atom corresponding to a given string. the atom corresponding to @atom_name. a string. if %TRUE, GDK is allowed to not create a new atom, but just return %GDK_NONE if the requested atom doesn’t already exists. Currently, the flag is ignored, since checking the existance of an atom is as expensive as creating it. Finds or creates an atom corresponding to a given string. Note that this function is identical to gdk_atom_intern() except that if a new #GdkAtom is created the string itself is used rather than a copy. This saves memory, but can only be used if the string will always exist. It can be used with statically allocated strings in the main program, but not with statically allocated memory in dynamically loaded modules, if you expect to ever unload the module again (e.g. do not use this function in GTK+ theme engines). the atom corresponding to @atom_name a static string Emits a short beep on the default display. Creates a Cairo context for drawing to @window. Note that calling cairo_reset_clip() on the resulting #cairo_t will produce undefined results, so avoid it at all costs. Typically, this function is used to draw on a #GdkWindow out of the paint cycle of the toolkit; this should be avoided, as it breaks various assumptions and optimizations. If you are drawing on a native #GdkWindow in response to a %GDK_EXPOSE event you should use gdk_window_begin_draw_frame() and gdk_drawing_context_get_cairo_context() instead. GTK will automatically do this for you when drawing a widget. Use gdk_window_begin_draw_frame() and gdk_drawing_context_get_cairo_context() instead A newly created Cairo context. Free with cairo_destroy() when you are done drawing. a #GdkWindow This is the main way to draw GL content in GTK+. It takes a render buffer ID (@source_type == #GL_RENDERBUFFER) or a texture id (@source_type == #GL_TEXTURE) and draws it onto @cr with an OVER operation, respecting the current clip. The top left corner of the rectangle specified by @x, @y, @width and @height will be drawn at the current (0,0) position of the cairo_t. This will work for *all* cairo_t, as long as @window is realized, but the fallback implementation that reads back the pixels from the buffer may be used in the general case. In the case of direct drawing to a window with no special effects applied to @cr it will however use a more efficient approach. For #GL_RENDERBUFFER the code will always fall back to software for buffers with alpha components, so make sure you use #GL_TEXTURE if using alpha. Calling this may change the current GL context. a cairo context The window we're rendering for (not necessarily into) The GL ID of the source buffer The type of the @source The scale-factor that the @source buffer is allocated for The source x position in @source to start copying from in GL coordinates The source y position in @source to start copying from in GL coordinates The width of the region to draw The height of the region to draw This is a convenience function around cairo_clip_extents(). It rounds the clip extents to integer coordinates and returns a boolean indicating if a clip area exists. %TRUE if a clip rectangle exists, %FALSE if all of @cr is clipped and all drawing can be skipped a cairo context return location for the clip, or %NULL Retrieves the #GdkDrawingContext that created the Cairo context @cr. a #GdkDrawingContext, if any is set a Cairo context [Cairo](http://cairographics.org) is a graphics library that supports vector graphics and image compositing that can be used with GDK. GTK+ does all of its drawing using cairo. GDK does not wrap the cairo API, instead it allows to create cairo contexts which can be used to draw on #GdkWindows. Additional functions allow use #GdkRectangles with cairo and to use #GdkColors, #GdkRGBAs, #GdkPixbufs and #GdkWindows as sources for drawing operations. Adds the given rectangle to the current path of @cr. a cairo context a #GdkRectangle Adds the given region to the current path of @cr. a cairo context a #cairo_region_t Creates region that describes covers the area where the given @surface is more than 50% opaque. This function takes into account device offsets that might be set with cairo_surface_set_device_offset(). A #cairo_region_t; must be freed with cairo_region_destroy() a cairo surface Sets the specified #GdkColor as the source color of @cr. Use gdk_cairo_set_source_rgba() instead a cairo context a #GdkColor Sets the given pixbuf as the source pattern for @cr. The pattern has an extend mode of %CAIRO_EXTEND_NONE and is aligned so that the origin of @pixbuf is @pixbuf_x, @pixbuf_y. a cairo context a #GdkPixbuf X coordinate of location to place upper left corner of @pixbuf Y coordinate of location to place upper left corner of @pixbuf Sets the specified #GdkRGBA as the source color of @cr. a cairo context a #GdkRGBA Sets the given window as the source pattern for @cr. The pattern has an extend mode of %CAIRO_EXTEND_NONE and is aligned so that the origin of @window is @x, @y. The window contains all its subwindows when rendering. Note that the contents of @window are undefined outside of the visible part of @window, so use this function with care. a cairo context a #GdkWindow X coordinate of location to place upper left corner of @window Y coordinate of location to place upper left corner of @window Creates an image surface with the same contents as the pixbuf. a new cairo surface, must be freed with cairo_surface_destroy() a #GdkPixbuf the scale of the new surface, or 0 to use same as @window The window this will be drawn to, or %NULL Parses a textual specification of a color and fill in the @red, @green, and @blue fields of a #GdkColor. The string can either one of a large set of standard names (taken from the X11 `rgb.txt` file), or it can be a hexadecimal value in the form “\#rgb” “\#rrggbb”, “\#rrrgggbbb” or “\#rrrrggggbbbb” where “r”, “g” and “b” are hex digits of the red, green, and blue components of the color, respectively. (White in the four forms is “\#fff”, “\#ffffff”, “\#fffffffff” and “\#ffffffffffff”). Use #GdkRGBA %TRUE if the parsing succeeded the string specifying the color the #GdkColor to fill in A #GdkColor represents a color. When working with cairo, it is often more convenient to use a #GdkRGBA instead, and #GdkColor has been deprecated in favor of #GdkRGBA. These functions are used to create and destroy cursors. There is a number of standard cursors, but it is also possible to construct new cursors from pixbufs. There may be limitations as to what kinds of cursors can be constructed on a given display, see gdk_display_supports_cursor_alpha(), gdk_display_supports_cursor_color(), gdk_display_get_default_cursor_size() and gdk_display_get_maximal_cursor_size(). Cursors by themselves are not very interesting, they must be be bound to a window for users to see them. This is done with gdk_window_set_cursor() or by setting the cursor member of the #GdkWindowAttr passed to gdk_window_new(). Disables multidevice support in GDK. This call must happen prior to gdk_display_open(), gtk_init(), gtk_init_with_args() or gtk_init_check() in order to take effect. Most common GTK+ applications won’t ever need to call this. Only applications that do mixed GDK/Xlib calls could want to disable multidevice support if such Xlib code deals with input devices in any way and doesn’t observe the presence of XInput 2. These functions provide a low level interface for drag and drop. The X backend of GDK supports both the Xdnd and Motif drag and drop protocols transparently, the Win32 backend supports the WM_DROPFILES protocol. GTK+ provides a higher level abstraction based on top of these functions, and so they are not normally needed in GTK+ applications. See the [Drag and Drop][gtk3-Drag-and-Drop] section of the GTK+ documentation for more information. Aborts a drag without dropping. This function is called by the drag source. This function does not need to be called in managed drag and drop operations. See gdk_drag_context_manage_dnd() for more information. a #GdkDragContext the timestamp for this operation Starts a drag and creates a new drag context for it. This function assumes that the drag is controlled by the client pointer device, use gdk_drag_begin_for_device() to begin a drag with a different device. This function is called by the drag source. a newly created #GdkDragContext the source window for this drag. the offered targets, as list of #GdkAtoms Starts a drag and creates a new drag context for it. This function is called by the drag source. a newly created #GdkDragContext the source window for this drag the device that controls this drag the offered targets, as list of #GdkAtoms Starts a drag and creates a new drag context for it. This function is called by the drag source. a newly created #GdkDragContext the source window for this drag the device that controls this drag the offered targets, as list of #GdkAtoms the x coordinate where the drag nominally started the y coordinate where the drag nominally started Drops on the current destination. This function is called by the drag source. This function does not need to be called in managed drag and drop operations. See gdk_drag_context_manage_dnd() for more information. a #GdkDragContext the timestamp for this operation Inform GDK if the drop ended successfully. Passing %FALSE for @success may trigger a drag cancellation animation. This function is called by the drag source, and should be the last call before dropping the reference to the @context. The #GdkDragContext will only take the first gdk_drag_drop_done() call as effective, if this function is called multiple times, all subsequent calls will be ignored. a #GdkDragContext whether the drag was ultimatively successful Returns whether the dropped data has been successfully transferred. This function is intended to be used while handling a %GDK_DROP_FINISHED event, its return value is meaningless at other times. %TRUE if the drop was successful. a #GdkDragContext Finds the destination window and DND protocol to use at the given pointer position. This function is called by the drag source to obtain the @dest_window and @protocol parameters for gdk_drag_motion(). a #GdkDragContext a window which may be at the pointer position, but should be ignored, since it is put up by the drag source as an icon the screen where the destination window is sought the x position of the pointer in root coordinates the y position of the pointer in root coordinates location to store the destination window in location to store the DND protocol in Returns the selection atom for the current source window. the selection atom, or %GDK_NONE a #GdkDragContext. Updates the drag context when the pointer moves or the set of actions changes. This function is called by the drag source. This function does not need to be called in managed drag and drop operations. See gdk_drag_context_manage_dnd() for more information. a #GdkDragContext the new destination window, obtained by gdk_drag_find_window() the DND protocol in use, obtained by gdk_drag_find_window() the x position of the pointer in root coordinates the y position of the pointer in root coordinates the suggested action the possible actions the timestamp for this operation Selects one of the actions offered by the drag source. This function is called by the drag destination in response to gdk_drag_motion() called by the drag source. a #GdkDragContext the selected action which will be taken when a drop happens, or 0 to indicate that a drop will not be accepted the timestamp for this operation Ends the drag operation after a drop. This function is called by the drag destination. a #GdkDragContext %TRUE if the data was successfully received the timestamp for this operation Accepts or rejects a drop. This function is called by the drag destination in response to a drop initiated by the drag source. a #GdkDragContext %TRUE if the drop is accepted the timestamp for this operation Removes an error trap pushed with gdk_error_trap_push(). May block until an error has been definitively received or not received from the X server. gdk_error_trap_pop_ignored() is preferred if you don’t need to know whether an error occurred, because it never has to block. If you don't need the return value of gdk_error_trap_pop(), use gdk_error_trap_pop_ignored(). Prior to GDK 3.0, this function would not automatically sync for you, so you had to gdk_flush() if your last call to Xlib was not a blocking round trip. X error code or 0 on success Removes an error trap pushed with gdk_error_trap_push(), but without bothering to wait and see whether an error occurred. If an error arrives later asynchronously that was triggered while the trap was pushed, that error will be ignored. This function allows X errors to be trapped instead of the normal behavior of exiting the application. It should only be used if it is not possible to avoid the X error in any other way. Errors are ignored on all #GdkDisplay currently known to the #GdkDisplayManager. If you don’t care which error happens and just want to ignore everything, pop with gdk_error_trap_pop_ignored(). If you need the error code, use gdk_error_trap_pop() which may have to block and wait for the error to arrive from the X server. This API exists on all platforms but only does anything on X. You can use gdk_x11_display_error_trap_push() to ignore errors on only a single display. ## Trapping an X error |[<!-- language="C" --> gdk_error_trap_push (); // ... Call the X function which may cause an error here ... if (gdk_error_trap_pop ()) { // ... Handle the error here ... } ]| Checks all open displays for a #GdkEvent to process,to be processed on, fetching events from the windowing system if necessary. See gdk_display_get_event(). the next #GdkEvent to be processed, or %NULL if no events are pending. The returned #GdkEvent should be freed with gdk_event_free(). Sets the function to call to handle all events from GDK. Note that GTK+ uses this to install its own event handler, so it is usually not useful for GTK+ applications. (Although an application can call this function then call gtk_main_do_event() to pass events to GTK+.) the function to call to handle events from GDK. user data to pass to the function. the function to call when the handler function is removed, i.e. when gdk_event_handler_set() is called with another event handler. If there is an event waiting in the event queue of some open display, returns a copy of it. See gdk_display_peek_event(). a copy of the first #GdkEvent on some event queue, or %NULL if no events are in any queues. The returned #GdkEvent should be freed with gdk_event_free(). Request more motion notifies if @event is a motion notify hint event. This function should be used instead of gdk_window_get_pointer() to request further motion notifies, because it also works for extension events where motion notifies are provided for devices other than the core pointer. Coordinate extraction, processing and requesting more motion events from a %GDK_MOTION_NOTIFY event usually works like this: |[<!-- language="C" --> { // motion_event handler x = motion_event->x; y = motion_event->y; // handle (x,y) motion gdk_event_request_motions (motion_event); // handles is_hint events } ]| a valid #GdkEvent The event structures contain data specific to each type of event in GDK. > A common mistake is to forget to set the event mask of a widget so that > the required events are received. See gtk_widget_set_events(). This section describes functions dealing with events from the window system. In GTK+ applications the events are handled automatically in gtk_main_do_event() and passed on to the appropriate widgets, so these functions are rarely needed. Though some of the fields in the [Event Structures][gdk3-Event-Structures] are useful. If both events contain X/Y information, this function will return %TRUE and return in @angle the relative angle from @event1 to @event2. The rotation direction for positive angles is from the positive X axis towards the positive Y axis. %TRUE if the angle could be calculated. first #GdkEvent second #GdkEvent return location for the relative angle between both events If both events contain X/Y information, the center of both coordinates will be returned in @x and @y. %TRUE if the center could be calculated. first #GdkEvent second #GdkEvent return location for the X coordinate of the center return location for the Y coordinate of the center If both events have X/Y information, the distance between both coordinates (as in a straight line going from @event1 to @event2) will be returned. %TRUE if the distance could be calculated. first #GdkEvent second #GdkEvent return location for the distance Checks if any events are ready to be processed for any display. %TRUE if any events are pending. Flushes the output buffers of all display connections and waits until all requests have been processed. This is rarely needed by applications. The functions in this section are intended to be used in test programs. They allow to simulate some user input. This section describes the GDK initialization functions and miscellaneous utility functions, as well as deprecation facilities. The GDK and GTK+ headers annotate deprecated APIs in a way that produces compiler warnings if these deprecated APIs are used. The warnings can be turned off by defining the macro %GDK_DISABLE_DEPRECATION_WARNINGS before including the glib.h header. GDK and GTK+ also provide support for building applications against defined subsets of deprecated or new APIs. Define the macro %GDK_VERSION_MIN_REQUIRED to specify up to what version you want to receive warnings about deprecated APIs. Define the macro %GDK_VERSION_MAX_ALLOWED to specify the newest version whose API you want to use. Obtains the root window (parent all other windows are inside) for the default display and screen. the default root window Gets the name of the display, which usually comes from the `DISPLAY` environment variable or the `--display` command line option. Call gdk_display_get_name (gdk_display_get_default ())) instead. the name of the display. Gets the display name specified in the command line arguments passed to gdk_init() or gdk_parse_args(), if any. the display name, if specified explicitly, otherwise %NULL this string is owned by GTK+ and must not be modified or freed. Gets the program class. Unless the program class has explicitly been set with gdk_set_program_class() or with the `--class` commandline option, the default value is the program name (determined with g_get_prgname()) with the first character converted to uppercase. the program class. Gets whether event debugging output is enabled. %TRUE if event debugging output is enabled. Initializes the GDK library and connects to the windowing system. If initialization fails, a warning message is output and the application terminates with a call to `exit(1)`. Any arguments used by GDK are removed from the array and @argc and @argv are updated accordingly. GTK+ initializes GDK in gtk_init() and so this function is not usually needed by GTK+ applications. the number of command line arguments. the array of command line arguments. Initializes the GDK library and connects to the windowing system, returning %TRUE on success. Any arguments used by GDK are removed from the array and @argc and @argv are updated accordingly. GTK+ initializes GDK in gtk_init() and so this function is not usually needed by GTK+ applications. %TRUE if initialization succeeded. the number of command line arguments. the array of command line arguments. Grabs the keyboard so that all events are passed to this application until the keyboard is ungrabbed with gdk_keyboard_ungrab(). This overrides any previous keyboard grab by this client. If you set up anything at the time you take the grab that needs to be cleaned up when the grab ends, you should handle the #GdkEventGrabBroken events that are emitted when the grab ends unvoluntarily. Use gdk_device_grab() instead. %GDK_GRAB_SUCCESS if the grab was successful. the #GdkWindow which will own the grab (the grab window). if %FALSE then all keyboard events are reported with respect to @window. If %TRUE then keyboard events for this application are reported as normal, but keyboard events outside this application are reported with respect to @window. Both key press and key release events are always reported, independant of the event mask set by the application. a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is available. Ungrabs the keyboard on the default display, if it is grabbed by this application. Use gdk_device_ungrab(), together with gdk_device_grab() instead. a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is available. Key values are the codes which are sent whenever a key is pressed or released. They appear in the #GdkEventKey.keyval field of the #GdkEventKey structure, which is passed to signal handlers for the #GtkWidget::key-press-event and #GtkWidget::key-release-event signals. The complete list of key values can be found in the `gdk/gdkkeysyms.h` header file. Key values are regularly updated from the upstream X.org X11 implementation, so new values are added regularly. They will be prefixed with GDK_KEY_ rather than XF86XK_ or XK_ (for older symbols). Key values can be converted into a string representation using gdk_keyval_name(). The reverse function, converting a string to a key value, is provided by gdk_keyval_from_name(). The case of key values can be determined using gdk_keyval_is_upper() and gdk_keyval_is_lower(). Key values can be converted to upper or lower case using gdk_keyval_to_upper() and gdk_keyval_to_lower(). When it makes sense, key values can be converted to and from Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval(). # Groups # {#key-group-explanation} One #GdkKeymap object exists for each user display. gdk_keymap_get_default() returns the #GdkKeymap for the default display; to obtain keymaps for other displays, use gdk_keymap_get_for_display(). A keymap is a mapping from #GdkKeymapKey to key values. You can think of a #GdkKeymapKey as a representation of a symbol printed on a physical keyboard key. That is, it contains three pieces of information. First, it contains the hardware keycode; this is an identifying number for a physical key. Second, it contains the “level” of the key. The level indicates which symbol on the key will be used, in a vertical direction. So on a standard US keyboard, the key with the number “1“ on it also has the exclamation point (”!”) character on it. The level indicates whether to use the “1” or the “!” symbol. The letter keys are considered to have a lowercase letter at level 0, and an uppercase letter at level 1, though only the uppercase letter is printed. Third, the #GdkKeymapKey contains a group; groups are not used on standard US keyboards, but are used in many other countries. On a keyboard with groups, there can be 3 or 4 symbols printed on a single key. The group indicates movement in a horizontal direction. Usually groups are used for two different languages. In group 0, a key might have two English characters, and in group 1 it might have two Hebrew characters. The Hebrew characters will be printed on the key next to the English characters. In order to use a keymap to interpret a key event, it’s necessary to first convert the keyboard state into an effective group and level. This is done via a set of rules that varies widely according to type of keyboard and user configuration. The function gdk_keymap_translate_keyboard_state() accepts a keyboard state -- consisting of hardware keycode pressed, active modifiers, and active group -- applies the appropriate rules, and returns the group/level to be used to index the keymap, along with the modifiers which did not affect the group and level. i.e. it returns “unconsumed modifiers.” The keyboard group may differ from the effective group used for keymap lookups because some keys don't have multiple groups - e.g. the Enter key is always in group 0 regardless of keyboard state. Note that gdk_keymap_translate_keyboard_state() also returns the keyval, i.e. it goes ahead and performs the keymap lookup in addition to telling you which effective group/level values were used for the lookup. #GdkEventKey already contains this keyval, however, so you don’t normally need to call gdk_keymap_translate_keyboard_state() just to get the keyval. Obtains the upper- and lower-case versions of the keyval @symbol. Examples of keyvals are #GDK_KEY_a, #GDK_KEY_Enter, #GDK_KEY_F1, etc. a keyval return location for lowercase version of @symbol return location for uppercase version of @symbol Converts a key name to a key value. The names are the same as those in the `gdk/gdkkeysyms.h` header file but without the leading “GDK_KEY_”. the corresponding key value, or %GDK_KEY_VoidSymbol if the key name is not a valid key a key name Returns %TRUE if the given key value is in lower case. %TRUE if @keyval is in lower case, or if @keyval is not subject to case conversion. a key value. Returns %TRUE if the given key value is in upper case. %TRUE if @keyval is in upper case, or if @keyval is not subject to case conversion. a key value. Converts a key value into a symbolic name. The names are the same as those in the `gdk/gdkkeysyms.h` header file but without the leading “GDK_KEY_”. a string containing the name of the key, or %NULL if @keyval is not a valid key. The string should not be modified. a key value Converts a key value to lower case, if applicable. the lower case form of @keyval, or @keyval itself if it is already in lower case or it is not subject to case conversion. a key value. Convert from a GDK key symbol to the corresponding ISO10646 (Unicode) character. the corresponding unicode character, or 0 if there is no corresponding character. a GDK key symbol Converts a key value to upper case, if applicable. the upper case form of @keyval, or @keyval itself if it is already in upper case or it is not subject to case conversion. a key value. Lists the available visuals for the default screen. (See gdk_screen_list_visuals()) A visual describes a hardware image data format. For example, a visual might support 24-bit color, or 8-bit color, and might expect pixels to be in a certain format. Call g_list_free() on the return value when you’re finished with it. Use gdk_screen_list_visuals (gdk_screen_get_default ()). a list of visuals; the list must be freed, but not its contents Indicates to the GUI environment that the application has finished loading. If the applications opens windows, this function is normally called after opening the application’s initial set of windows. GTK+ will call this function automatically after opening the first #GtkWindow unless gtk_window_set_auto_startup_notification() is called to disable that feature. Indicates to the GUI environment that the application has finished loading, using a given identifier. GTK+ will call this function automatically for #GtkWindow with custom startup-notification identifier unless gtk_window_set_auto_startup_notification() is called to disable that feature. a startup-notification identifier, for which notification process should be completed Gets the window that @window is embedded in. the embedding #GdkWindow, or %NULL if @window is not an mbedded offscreen window a #GdkWindow Gets the offscreen surface that an offscreen window renders into. If you need to keep this around over window resizes, you need to add a reference to it. The offscreen surface, or %NULL if not offscreen a #GdkWindow Sets @window to be embedded in @embedder. To fully embed an offscreen window, in addition to calling this function, it is also necessary to handle the #GdkWindow::pick-embedded-child signal on the @embedder and the #GdkWindow::to-embedder and #GdkWindow::from-embedder signals on @window. a #GdkWindow the #GdkWindow that @window gets embedded in Creates a #PangoContext for the default GDK screen. The context must be freed when you’re finished with it. When using GTK+, normally you should use gtk_widget_get_pango_context() instead of this function, to get the appropriate context for the widget you intend to render text onto. The newly created context will have the default font options (see #cairo_font_options_t) for the default screen; if these options change it will not be updated. Using gtk_widget_get_pango_context() is more convenient if you want to keep a context around and track changes to the screen’s font rendering settings. a new #PangoContext for the default display Creates a #PangoContext for @display. The context must be freed when you’re finished with it. When using GTK+, normally you should use gtk_widget_get_pango_context() instead of this function, to get the appropriate context for the widget you intend to render text onto. The newly created context will have the default font options (see #cairo_font_options_t) for the display; if these options change it will not be updated. Using gtk_widget_get_pango_context() is more convenient if you want to keep a context around and track changes to the font rendering settings. a new #PangoContext for @display the #GdkDisplay for which the context is to be created Creates a #PangoContext for @screen. The context must be freed when you’re finished with it. When using GTK+, normally you should use gtk_widget_get_pango_context() instead of this function, to get the appropriate context for the widget you intend to render text onto. The newly created context will have the default font options (see #cairo_font_options_t) for the screen; if these options change it will not be updated. Using gtk_widget_get_pango_context() is more convenient if you want to keep a context around and track changes to the screen’s font rendering settings. a new #PangoContext for @screen the #GdkScreen for which the context is to be created. Pango is the text layout system used by GDK and GTK+. The functions and types in this section are used to obtain clip regions for #PangoLayouts, and to get #PangoContexts that can be used with GDK. Creating a #PangoLayout object is the first step in rendering text, and requires getting a handle to a #PangoContext. For GTK+ programs, you’ll usually want to use gtk_widget_get_pango_context(), or gtk_widget_create_pango_layout(), rather than using the lowlevel gdk_pango_context_get_for_screen(). Once you have a #PangoLayout, you can set the text and attributes of it with Pango functions like pango_layout_set_text() and get its size with pango_layout_get_size(). (Note that Pango uses a fixed point system internally, so converting between Pango units and pixels using [PANGO_SCALE][PANGO-SCALE-CAPS] or the PANGO_PIXELS() macro.) Rendering a Pango layout is done most simply with pango_cairo_show_layout(); you can also draw pieces of the layout with pango_cairo_show_layout_line(). ## Draw transformed text with Pango and cairo ## {#rotated-example} |[<!-- language="C" --> #define RADIUS 100 #define N_WORDS 10 #define FONT "Sans Bold 18" PangoContext *context; PangoLayout *layout; PangoFontDescription *desc; double radius; int width, height; int i; // Set up a transformation matrix so that the user space coordinates for // where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS] // We first center, then change the scale width = gdk_window_get_width (window); height = gdk_window_get_height (window); radius = MIN (width, height) / 2.; cairo_translate (cr, radius + (width - 2 * radius) / 2, radius + (height - 2 * radius) / 2); cairo_scale (cr, radius / RADIUS, radius / RADIUS); // Create a PangoLayout, set the font and text context = gdk_pango_context_get_for_screen (screen); layout = pango_layout_new (context); pango_layout_set_text (layout, "Text", -1); desc = pango_font_description_from_string (FONT); pango_layout_set_font_description (layout, desc); pango_font_description_free (desc); // Draw the layout N_WORDS times in a circle for (i = 0; i < N_WORDS; i++) { double red, green, blue; double angle = 2 * G_PI * i / n_words; cairo_save (cr); // Gradient from red at angle == 60 to blue at angle == 300 red = (1 + cos (angle - 60)) / 2; green = 0; blue = 1 - red; cairo_set_source_rgb (cr, red, green, blue); cairo_rotate (cr, angle); // Inform Pango to re-layout the text with the new transformation matrix pango_cairo_update_layout (cr, layout); pango_layout_get_size (layout, &width, &height); cairo_move_to (cr, - width / 2 / PANGO_SCALE, - DEFAULT_TEXT_RADIUS); pango_cairo_show_layout (cr, layout); cairo_restore (cr); } g_object_unref (layout); g_object_unref (context); ]| ## Output of the [example][rotated-example] above. ![](rotated-text.png) Obtains a clip region which contains the areas where the given ranges of text would be drawn. @x_origin and @y_origin are the top left point to center the layout. @index_ranges should contain ranges of bytes in the layout’s text. Note that the regions returned correspond to logical extents of the text ranges, not ink extents. So the drawn layout may in fact touch areas out of the clip region. The clip region is mainly useful for highlightling parts of text, such as when text is selected. a clip region containing the given ranges a #PangoLayout X pixel where you intend to draw the layout with this clip Y pixel where you intend to draw the layout with this clip array of byte indexes into the layout, where even members of array are start indexes and odd elements are end indexes number of ranges in @index_ranges, i.e. half the size of @index_ranges Obtains a clip region which contains the areas where the given ranges of text would be drawn. @x_origin and @y_origin are the top left position of the layout. @index_ranges should contain ranges of bytes in the layout’s text. The clip region will include space to the left or right of the line (to the layout bounding box) if you have indexes above or below the indexes contained inside the line. This is to draw the selection all the way to the side of the layout. However, the clip region is in line coordinates, not layout coordinates. Note that the regions returned correspond to logical extents of the text ranges, not ink extents. So the drawn line may in fact touch areas out of the clip region. The clip region is mainly useful for highlightling parts of text, such as when text is selected. a clip region containing the given ranges a #PangoLayoutLine X pixel where you intend to draw the layout line with this clip baseline pixel where you intend to draw the layout line with this clip array of byte indexes into the layout, where even members of array are start indexes and odd elements are end indexes number of ranges in @index_ranges, i.e. half the size of @index_ranges Parse command line arguments, and store for future use by calls to gdk_display_open(). Any arguments used by GDK are removed from the array and @argc and @argv are updated accordingly. You shouldn’t call this function explicitly if you are using gtk_init(), gtk_init_check(), gdk_init(), or gdk_init_check(). the number of command line arguments. the array of command line arguments. Transfers image data from a #cairo_surface_t and converts it to an RGB(A) representation inside a #GdkPixbuf. This allows you to efficiently read individual pixels from cairo surfaces. For #GdkWindows, use gdk_pixbuf_get_from_window() instead. This function will create an RGB pixbuf with 8 bits per channel. The pixbuf will contain an alpha channel if the @surface contains one. A newly-created pixbuf with a reference count of 1, or %NULL on error surface to copy from Source X coordinate within @surface Source Y coordinate within @surface Width in pixels of region to get Height in pixels of region to get Transfers image data from a #GdkWindow and converts it to an RGB(A) representation inside a #GdkPixbuf. In other words, copies image data from a server-side drawable to a client-side RGB(A) buffer. This allows you to efficiently read individual pixels on the client side. This function will create an RGB pixbuf with 8 bits per channel with the size specified by the @width and @height arguments scaled by the scale factor of @window. The pixbuf will contain an alpha channel if the @window contains one. If the window is off the screen, then there is no image data in the obscured/offscreen regions to be placed in the pixbuf. The contents of portions of the pixbuf corresponding to the offscreen region are undefined. If the window you’re obtaining data from is partially obscured by other windows, then the contents of the pixbuf areas corresponding to the obscured regions are undefined. If the window is not mapped (typically because it’s iconified/minimized or not on the current workspace), then %NULL will be returned. If memory can’t be allocated for the return value, %NULL will be returned instead. In short, there are several ways this function can fail, and if it fails it returns %NULL; so check the return value. You should rarely, if ever, need to call this function. A newly-created pixbuf with a reference count of 1, or %NULL on error Source window Source X coordinate within @window Source Y coordinate within @window Width in pixels of region to get Height in pixels of region to get Pixbufs are client-side images. For details on how to create and manipulate pixbufs, see the #GdkPixbuf API documentation. The functions described here allow to obtain pixbufs from #GdkWindows and cairo surfaces. Grabs the pointer (usually a mouse) so that all events are passed to this application until the pointer is ungrabbed with gdk_pointer_ungrab(), or the grab window becomes unviewable. This overrides any previous pointer grab by this client. Pointer grabs are used for operations which need complete control over mouse events, even if the mouse leaves the application. For example in GTK+ it is used for Drag and Drop, for dragging the handle in the #GtkHPaned and #GtkVPaned widgets. Note that if the event mask of an X window has selected both button press and button release events, then a button press event will cause an automatic pointer grab until the button is released. X does this automatically since most applications expect to receive button press and release events in pairs. It is equivalent to a pointer grab on the window with @owner_events set to %TRUE. If you set up anything at the time you take the grab that needs to be cleaned up when the grab ends, you should handle the #GdkEventGrabBroken events that are emitted when the grab ends unvoluntarily. Use gdk_device_grab() instead. %GDK_GRAB_SUCCESS if the grab was successful. the #GdkWindow which will own the grab (the grab window). if %FALSE then all pointer events are reported with respect to @window and are only reported if selected by @event_mask. If %TRUE then pointer events for this application are reported as normal, but pointer events outside this application are reported with respect to @window and only if selected by @event_mask. In either mode, unreported events are discarded. specifies the event mask, which is used in accordance with @owner_events. Note that only pointer events (i.e. button and motion events) may be selected. If non-%NULL, the pointer will be confined to this window during the grab. If the pointer is outside @confine_to, it will automatically be moved to the closest edge of @confine_to and enter and leave events will be generated as necessary. the cursor to display while the grab is active. If this is %NULL then the normal cursors are used for @window and its descendants, and the cursor for @window is used for all other windows. the timestamp of the event which led to this pointer grab. This usually comes from a #GdkEventButton struct, though %GDK_CURRENT_TIME can be used if the time isn’t known. Returns %TRUE if the pointer on the default display is currently grabbed by this application. Note that this does not take the inmplicit pointer grab on button presses into account. Use gdk_display_device_is_grabbed() instead. %TRUE if the pointer is currently grabbed by this application. Ungrabs the pointer on the default display, if it is grabbed by this application. Use gdk_device_ungrab(), together with gdk_device_grab() instead. a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is available. Prepare for parsing command line arguments for GDK. This is not public API and should not be used in application code. This symbol was never meant to be used outside of GTK+ Each window under X can have any number of associated “properties” attached to it. Properties are arbitrary chunks of data identified by “atom”s. (An “atom” is a numeric index into a string table on the X server. They are used to transfer strings efficiently between clients without having to transfer the entire string.) A property has an associated type, which is also identified using an atom. A property has an associated “format”, an integer describing how many bits are in each unit of data inside the property. It must be 8, 16, or 32. When data is transferred between the server and client, if they are of different endianesses it will be byteswapped as necessary according to the format of the property. Note that on the client side, properties of format 32 will be stored with one unit per long, even if a long integer has more than 32 bits on the platform. (This decision was apparently made for Xlib to maintain compatibility with programs that assumed longs were 32 bits, at the expense of programs that knew better.) The functions in this section are used to add, remove and change properties on windows, to convert atoms to and from strings and to manipulate some types of data commonly stored in X window properties. Changes the contents of a property on a window. a #GdkWindow the property to change the new type for the property. If @mode is %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this must match the existing type or an error will occur. the new format for the property. If @mode is %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this must match the existing format or an error will occur. a value describing how the new data is to be combined with the current data. the data (a `guchar *` `gushort *`, or `gulong *`, depending on @format), cast to a `guchar *`. the number of elements of size determined by the format, contained in @data. Deletes a property from a window. a #GdkWindow the property to delete Retrieves a portion of the contents of a property. If the property does not exist, then the function returns %FALSE, and %GDK_NONE will be stored in @actual_property_type. The XGetWindowProperty() function that gdk_property_get() uses has a very confusing and complicated set of semantics. Unfortunately, gdk_property_get() makes the situation worse instead of better (the semantics should be considered undefined), and also prints warnings to stderr in cases where it should return a useful error to the program. You are advised to use XGetWindowProperty() directly until a replacement function for gdk_property_get() is provided. %TRUE if data was successfully received and stored in @data, otherwise %FALSE. a #GdkWindow the property to retrieve the desired property type, or %GDK_NONE, if any type of data is acceptable. If this does not match the actual type, then @actual_format and @actual_length will be filled in, a warning will be printed to stderr and no data will be returned. the offset into the property at which to begin retrieving data, in 4 byte units. the length of the data to retrieve in bytes. Data is considered to be retrieved in 4 byte chunks, so @length will be rounded up to the next highest 4 byte boundary (so be careful not to pass a value that might overflow when rounded up). if %TRUE, delete the property after retrieving the data. location to store the actual type of the property. location to store the actual return format of the data; either 8, 16 or 32 bits. location to store the length of the retrieved data, in bytes. Data returned in the 32 bit format is stored in a long variable, so the actual number of 32 bit elements should be be calculated via @actual_length / sizeof(glong) to ensure portability to 64 bit systems. location to store a pointer to the data. The retrieved data should be freed with g_free() when you are finished using it. This function returns the available bit depths for the default screen. It’s equivalent to listing the visuals (gdk_list_visuals()) and then looking at the depth field in each visual, removing duplicates. The array returned by this function should not be freed. Visual selection should be done using gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual() return location for available depths return location for number of available depths This function returns the available visual types for the default screen. It’s equivalent to listing the visuals (gdk_list_visuals()) and then looking at the type field in each visual, removing duplicates. The array returned by this function should not be freed. Visual selection should be done using gdk_screen_get_system_visual() and gdk_screen_get_rgba_visual() return location for the available visual types return location for the number of available visual types GDK provides the #GdkPoint and #GdkRectangle data types for representing pixels and sets of pixels on the screen. Together with Cairo’s #cairo_region_t data type, they make up the central types for representing graphical data. A #GdkPoint represents an x and y coordinate of a point. A #GdkRectangle represents the position and size of a rectangle. The intersection of two rectangles can be computed with gdk_rectangle_intersect(). To find the union of two rectangles use gdk_rectangle_union(). #cairo_region_t is usually used for managing clipping of graphical operations. #GdkRGBA is a convenient way to pass rgba colors around. It’s based on cairo’s way to deal with colors and mirrors its behavior. All values are in the range from 0.0 to 1.0 inclusive. So the color (0.0, 0.0, 0.0, 0.0) represents transparent black and (1.0, 1.0, 1.0, 1.0) is opaque white. Other values will be clamped to this range when drawing. Retrieves the contents of a selection in a given form. a #GdkWindow. an atom identifying the selection to get the contents of. the form in which to retrieve the selection. the timestamp to use when retrieving the selection. The selection owner may refuse the request if it did not own the selection at the time indicated by the timestamp. Determines the owner of the given selection. if there is a selection owner for this window, and it is a window known to the current process, the #GdkWindow that owns the selection, otherwise %NULL. Note that the return value may be owned by a different process if a foreign window was previously created for that window, but a new foreign window will never be created by this call. an atom indentifying a selection. Determine the owner of the given selection. Note that the return value may be owned by a different process if a foreign window was previously created for that window, but a new foreign window will never be created by this call. if there is a selection owner for this window, and it is a window known to the current process, the #GdkWindow that owns the selection, otherwise %NULL. a #GdkDisplay an atom indentifying a selection Sets the owner of the given selection. %TRUE if the selection owner was successfully changed to @owner, otherwise %FALSE. a #GdkWindow or %NULL to indicate that the the owner for the given should be unset. an atom identifying a selection. timestamp to use when setting the selection. If this is older than the timestamp given last time the owner was set for the given selection, the request will be ignored. if %TRUE, and the new owner is different from the current owner, the current owner will be sent a SelectionClear event. Sets the #GdkWindow @owner as the current owner of the selection @selection. %TRUE if the selection owner was successfully changed to owner, otherwise %FALSE. the #GdkDisplay a #GdkWindow or %NULL to indicate that the owner for the given should be unset an atom identifying a selection timestamp to use when setting the selection If this is older than the timestamp given last time the owner was set for the given selection, the request will be ignored if %TRUE, and the new owner is different from the current owner, the current owner will be sent a SelectionClear event Retrieves selection data that was stored by the selection data in response to a call to gdk_selection_convert(). This function will not be used by applications, who should use the #GtkClipboard API instead. the length of the retrieved data. the window on which the data is stored location to store a pointer to the retrieved data. If the retrieval failed, %NULL we be stored here, otherwise, it will be non-%NULL and the returned data should be freed with g_free() when you are finished using it. The length of the allocated memory is one more than the length of the returned data, and the final byte will always be zero, to ensure nul-termination of strings location to store the type of the property location to store the format of the property Sends a response to SelectionRequest event. window to which to deliver response. selection that was requested. target that was selected. property in which the selection owner stored the data, or %GDK_NONE to indicate that the request was rejected. timestamp. Send a response to SelectionRequest event. the #GdkDisplay where @requestor is realized window to which to deliver response selection that was requested target that was selected property in which the selection owner stored the data, or %GDK_NONE to indicate that the request was rejected timestamp GDK’s selection functions, based on the [X selection mechanism]( https://www.x.org/releases/X11R7.6/doc/xorg-docs/specs/ICCCM/icccm.html), provide a way to transfer arbitrary chunks of data between programs. A “selection” is a essentially a named clipboard, identified by a string interned as a #GdkAtom. By claiming ownership of a selection, an application indicates that it will be responsible for supplying its contents. The most common selections are `PRIMARY` and `CLIPBOARD`. The contents of a selection can be represented in a number of formats, called “targets”. Each target is identified by an atom. A list of all possible targets supported by the selection owner can be retrieved by requesting the special target `TARGETS`. When a selection is retrieved, the data is accompanied by a type (an atom), and a format (an integer, representing the number of bits per item). See [Properties and Atoms][gdk3-Properties-and-Atoms] for more information. The functions in this section only contain the lowlevel parts of the selection protocol. A considerably more complicated implementation is needed on top of this. GTK+ contains such an implementation in the functions in `gtkselection.h` and programmers should use those functions instead of the ones presented here. If you plan to implement selection handling directly on top of the functions here, you should refer to the [X Inter-Client Communication Conventions Manual (ICCCM)]( https://www.x.org/releases/X11R7.6/doc/xorg-docs/specs/ICCCM/icccm.html). Note that although much of the selection API design is based on that of X, it will work on other GDK backends too. Sets a list of backends that GDK should try to use. This can be be useful if your application does not work with certain GDK backends. By default, GDK tries all included backends. For example, |[<!-- language="C" --> gdk_set_allowed_backends ("wayland,quartz,*"); ]| instructs GDK to try the Wayland backend first, followed by the Quartz backend, and then all others. If the `GDK_BACKEND` environment variable is set, it determines what backends are tried in what order, while still respecting the set of allowed backends that are specified by this function. The possible backend names are x11, win32, quartz, broadway, wayland. You can also include a * in the list to try all remaining backends. This call must happen prior to gdk_display_open(), gtk_init(), gtk_init_with_args() or gtk_init_check() in order to take effect. a comma-separated list of backends Set the double click time for the default display. See gdk_display_set_double_click_time(). See also gdk_display_set_double_click_distance(). Applications should not set this, it is a global user-configured setting. double click time in milliseconds (thousandths of a second) Sets the program class. The X11 backend uses the program class to set the class name part of the `WM_CLASS` property on toplevel windows; see the ICCCM. The program class can still be overridden with the --class command line option. a string. Sets whether a trace of received events is output. Note that GTK+ must be compiled with debugging (that is, configured using the `--enable-debug` option) to use this option. %TRUE to output event debugging information. Obtains a desktop-wide setting, such as the double-click time, for the default screen. See gdk_screen_get_setting(). %TRUE if the setting existed and a value was stored in @value, %FALSE otherwise. the name of the setting. location to store the value of the setting. Retrieves a pixel from @window to force the windowing system to carry out any pending rendering commands. This function is intended to be used to synchronize with rendering pipelines, to benchmark windowing system rendering operations. a mapped #GdkWindow This function is intended to be used in GTK+ test programs. It will warp the mouse pointer to the given (@x,@y) coordinates within @window and simulate a button press or release event. Because the mouse pointer needs to be warped to the target location, use of this function outside of test programs that run in their own virtual windowing system (e.g. Xvfb) is not recommended. Also, gdk_test_simulate_button() is a fairly low level function, for most testing purposes, gtk_test_widget_click() is the right function to call which will generate a button press event followed by its accompanying button release event. whether all actions necessary for a button event simulation were carried out successfully a #GdkWindow to simulate a button event for x coordinate within @window for the button event y coordinate within @window for the button event Number of the pointer button for the event, usually 1, 2 or 3 Keyboard modifiers the event is setup with either %GDK_BUTTON_PRESS or %GDK_BUTTON_RELEASE This function is intended to be used in GTK+ test programs. If (@x,@y) are > (-1,-1), it will warp the mouse pointer to the given (@x,@y) coordinates within @window and simulate a key press or release event. When the mouse pointer is warped to the target location, use of this function outside of test programs that run in their own virtual windowing system (e.g. Xvfb) is not recommended. If (@x,@y) are passed as (-1,-1), the mouse pointer will not be warped and @window origin will be used as mouse pointer location for the event. Also, gdk_test_simulate_key() is a fairly low level function, for most testing purposes, gtk_test_widget_send_key() is the right function to call which will generate a key press event followed by its accompanying key release event. whether all actions necessary for a key event simulation were carried out successfully a #GdkWindow to simulate a key event for x coordinate within @window for the key event y coordinate within @window for the key event A GDK keyboard value Keyboard modifiers the event is setup with either %GDK_KEY_PRESS or %GDK_KEY_RELEASE Converts a text property in the given encoding to a list of UTF-8 strings. the number of strings in the resulting list a #GdkDisplay an atom representing the encoding of the text the format of the property the text to convert the length of @text, in bytes location to store the list of strings or %NULL. The list should be freed with g_strfreev(). For thread safety, GDK relies on the thread primitives in GLib, and on the thread-safe GLib main loop. GLib is completely thread safe (all global data is automatically locked), but individual data structure instances are not automatically locked for performance reasons. So e.g. you must coordinate accesses to the same #GHashTable from multiple threads. GTK+, however, is not thread safe. You should only use GTK+ and GDK from the thread gtk_init() and gtk_main() were called on. This is usually referred to as the “main thread”. Signals on GTK+ and GDK types, as well as non-signal callbacks, are emitted in the main thread. You can schedule work in the main thread safely from other threads by using gdk_threads_add_idle() and gdk_threads_add_timeout(): |[<!-- language="C" --> static void worker_thread (void) { ExpensiveData *expensive_data = do_expensive_computation (); gdk_threads_add_idle (got_value, expensive_data); } static gboolean got_value (gpointer user_data) { ExpensiveData *expensive_data = user_data; my_app->expensive_data = expensive_data; gtk_button_set_sensitive (my_app->button, TRUE); gtk_button_set_label (my_app->button, expensive_data->result_label); return G_SOURCE_REMOVE; } ]| You should use gdk_threads_add_idle() and gdk_threads_add_timeout() instead of g_idle_add() and g_timeout_add() since libraries not under your control might be using the deprecated GDK locking mechanism. If you are sure that none of the code in your application and libraries use the deprecated gdk_threads_enter() or gdk_threads_leave() methods, then you can safely use g_idle_add() and g_timeout_add(). For more information on this "worker thread" pattern, you should also look at #GTask, which gives you high-level tools to perform expensive tasks from worker threads, and will handle thread management for you. A wrapper for the common usage of gdk_threads_add_idle_full() assigning the default priority, #G_PRIORITY_DEFAULT_IDLE. See gdk_threads_add_idle_full(). the ID (greater than 0) of the event source. function to call data to pass to @function Adds a function to be called whenever there are no higher priority events pending. If the function returns %FALSE it is automatically removed from the list of event sources and will not be called again. This variant of g_idle_add_full() calls @function with the GDK lock held. It can be thought of a MT-safe version for GTK+ widgets for the following use case, where you have to worry about idle_callback() running in thread A and accessing @self after it has been finalized in thread B: |[<!-- language="C" --> static gboolean idle_callback (gpointer data) { // gdk_threads_enter(); would be needed for g_idle_add() SomeWidget *self = data; // do stuff with self self->idle_id = 0; // gdk_threads_leave(); would be needed for g_idle_add() return FALSE; } static void some_widget_do_stuff_later (SomeWidget *self) { self->idle_id = gdk_threads_add_idle (idle_callback, self) // using g_idle_add() here would require thread protection in the callback } static void some_widget_finalize (GObject *object) { SomeWidget *self = SOME_WIDGET (object); if (self->idle_id) g_source_remove (self->idle_id); G_OBJECT_CLASS (parent_class)->finalize (object); } ]| the ID (greater than 0) of the event source. the priority of the idle source. Typically this will be in the range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE function to call data to pass to @function function to call when the idle is removed, or %NULL A wrapper for the common usage of gdk_threads_add_timeout_full() assigning the default priority, #G_PRIORITY_DEFAULT. See gdk_threads_add_timeout_full(). the ID (greater than 0) of the event source. the time between calls to the function, in milliseconds (1/1000ths of a second) function to call data to pass to @function Sets a function to be called at regular intervals holding the GDK lock, with the given priority. The function is called repeatedly until it returns %FALSE, at which point the timeout is automatically destroyed and the function will not be called again. The @notify function is called when the timeout is destroyed. The first call to the function will be at the end of the first @interval. Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to “catch up” time lost in delays). This variant of g_timeout_add_full() can be thought of a MT-safe version for GTK+ widgets for the following use case: |[<!-- language="C" --> static gboolean timeout_callback (gpointer data) { SomeWidget *self = data; // do stuff with self self->timeout_id = 0; return G_SOURCE_REMOVE; } static void some_widget_do_stuff_later (SomeWidget *self) { self->timeout_id = g_timeout_add (timeout_callback, self) } static void some_widget_finalize (GObject *object) { SomeWidget *self = SOME_WIDGET (object); if (self->timeout_id) g_source_remove (self->timeout_id); G_OBJECT_CLASS (parent_class)->finalize (object); } ]| the ID (greater than 0) of the event source. the priority of the timeout source. Typically this will be in the range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. the time between calls to the function, in milliseconds (1/1000ths of a second) function to call data to pass to @function function to call when the timeout is removed, or %NULL A wrapper for the common usage of gdk_threads_add_timeout_seconds_full() assigning the default priority, #G_PRIORITY_DEFAULT. For details, see gdk_threads_add_timeout_full(). the ID (greater than 0) of the event source. the time between calls to the function, in seconds function to call data to pass to @function A variant of gdk_threads_add_timeout_full() with second-granularity. See g_timeout_add_seconds_full() for a discussion of why it is a good idea to use this function if you don’t need finer granularity. the ID (greater than 0) of the event source. the priority of the timeout source. Typically this will be in the range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. the time between calls to the function, in seconds function to call data to pass to @function function to call when the timeout is removed, or %NULL This function marks the beginning of a critical section in which GDK and GTK+ functions can be called safely and without causing race conditions. Only one thread at a time can be in such a critial section. All GDK and GTK+ calls should be made from the main thread Initializes GDK so that it can be used from multiple threads in conjunction with gdk_threads_enter() and gdk_threads_leave(). This call must be made before any use of the main loop from GTK+; to be safe, call it before gtk_init(). All GDK and GTK+ calls should be made from the main thread Leaves a critical region begun with gdk_threads_enter(). All GDK and GTK+ calls should be made from the main thread Allows the application to replace the standard method that GDK uses to protect its data structures. Normally, GDK creates a single #GMutex that is locked by gdk_threads_enter(), and released by gdk_threads_leave(); using this function an application provides, instead, a function @enter_fn that is called by gdk_threads_enter() and a function @leave_fn that is called by gdk_threads_leave(). The functions must provide at least same locking functionality as the default implementation, but can also do extra application specific processing. As an example, consider an application that has its own recursive lock that when held, holds the GTK+ lock as well. When GTK+ unlocks the GTK+ lock when entering a recursive main loop, the application must temporarily release its lock as well. Most threaded GTK+ apps won’t need to use this method. This method must be called before gdk_threads_init(), and cannot be called multiple times. All GDK and GTK+ calls should be made from the main thread function called to guard GDK function called to release the guard Convert from a ISO10646 character to a key symbol. the corresponding GDK key symbol, if one exists. or, if there is no corresponding symbol, wc | 0x01000000 a ISO10646 encoded character Converts an UTF-8 string into the best possible representation as a STRING. The representation of characters not in STRING is not specified; it may be as pseudo-escape sequences \x{ABCD}, or it may be in some other form of approximation. the newly-allocated string, or %NULL if the conversion failed. (It should not fail for any properly formed UTF-8 string unless system limits like memory or file descriptors are exceeded.) a UTF-8 string A #GdkVisual describes a particular video hardware display format. It includes information about the number of bits used for each color, the way the bits are translated into an RGB value for display, and the way the bits are stored in memory. For example, a piece of display hardware might support 24-bit color, 16-bit color, or 8-bit color; meaning 24/16/8-bit pixel sizes. For a given pixel size, pixels can be in different formats; for example the “red” element of an RGB pixel may be in the top 8 bits of the pixel, or may be in the lower 4 bits. There are several standard visuals. The visual returned by gdk_screen_get_system_visual() is the system’s default visual, and the visual returned by gdk_screen_get_rgba_visual() should be used for creating windows with an alpha channel. A number of functions are provided for determining the “best” available visual. For the purposes of making this determination, higher bit depths are considered better, and for visuals of the same bit depth, %GDK_VISUAL_PSEUDO_COLOR is preferred at 8bpp, otherwise, the visual types are ranked in the order of(highest to lowest) %GDK_VISUAL_DIRECT_COLOR, %GDK_VISUAL_TRUE_COLOR, %GDK_VISUAL_PSEUDO_COLOR, %GDK_VISUAL_STATIC_COLOR, %GDK_VISUAL_GRAYSCALE, then %GDK_VISUAL_STATIC_GRAY. A #GdkWindow is a (usually) rectangular region on the screen. It’s a low-level object, used to implement high-level objects such as #GtkWidget and #GtkWindow on the GTK+ level. A #GtkWindow is a toplevel window, the thing a user might think of as a “window” with a titlebar and so on; a #GtkWindow may contain many #GdkWindows. For example, each #GtkButton has a #GdkWindow associated with it. # Composited Windows # {#COMPOSITED-WINDOWS} Normally, the windowing system takes care of rendering the contents of a child window onto its parent window. This mechanism can be intercepted by calling gdk_window_set_composited() on the child window. For a “composited” window it is the responsibility of the application to render the window contents at the right spot. # Offscreen Windows # {#OFFSCREEN-WINDOWS} Offscreen windows are more general than composited windows, since they allow not only to modify the rendering of the child window onto its parent, but also to apply coordinate transformations. To integrate an offscreen window into a window hierarchy, one has to call gdk_offscreen_window_set_embedder() and handle a number of signals. The #GdkWindow::pick-embedded-child signal on the embedder window is used to select an offscreen child at given coordinates, and the #GdkWindow::to-embedder and #GdkWindow::from-embedder signals on the offscreen window are used to translate coordinates between the embedder and the offscreen window. For rendering an offscreen window onto its embedder, the contents of the offscreen window are available as a surface, via gdk_offscreen_window_get_surface(). soup3-0.9.0/gir-files/Gdk-4.0.gir000064400000000000000000043112271046102023000143050ustar 00000000000000 Defines all possible DND actions. This can be used in [method@Gdk.Drop.status] messages when any drop can be accepted or a more specific drop method is not yet known. Positioning hints for aligning a surface relative to a rectangle. These hints determine how the surface should be positioned in the case that the surface would fall off-screen if placed in its ideal position. For example, %GDK_ANCHOR_FLIP_X will replace %GDK_GRAVITY_NORTH_WEST with %GDK_GRAVITY_NORTH_EAST and vice versa if the surface extends beyond the left or right edges of the monitor. If %GDK_ANCHOR_SLIDE_X is set, the surface can be shifted horizontally to fit on-screen. If %GDK_ANCHOR_RESIZE_X is set, the surface can be shrunken horizontally to fit. In general, when multiple flags are set, flipping should take precedence over sliding, which should take precedence over resizing. allow flipping anchors horizontally allow flipping anchors vertically allow sliding surface horizontally allow sliding surface vertically allow resizing surface horizontally allow resizing surface vertically allow flipping anchors on both axes allow sliding surface on both axes allow resizing surface on both axes Handles launching an application in a graphical context. It is an implementation of `GAppLaunchContext` that provides startup notification and allows to launch applications on a specific workspace. ## Launching an application ```c GdkAppLaunchContext *context; context = gdk_display_get_app_launch_context (display); gdk_app_launch_context_set_timestamp (gdk_event_get_time (event)); if (!g_app_info_launch_default_for_uri ("http://www.gtk.org", context, &error)) g_warning ("Launching failed: %s\n", error->message); g_object_unref (context); ``` Gets the `GdkDisplay` that @context is for. the display of @context a `GdkAppLaunchContext` Sets the workspace on which applications will be launched. This only works when running under a window manager that supports multiple workspaces, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec). Specifically this sets the `_NET_WM_DESKTOP` property described in that spec. This only works when using the X11 backend. When the workspace is not specified or @desktop is set to -1, it is up to the window manager to pick one, typically it will be the current workspace. a `GdkAppLaunchContext` the number of a workspace, or -1 Sets the icon for applications that are launched with this context. Window Managers can use this information when displaying startup notification. See also [method@Gdk.AppLaunchContext.set_icon_name]. a `GdkAppLaunchContext` a `GIcon` Sets the icon for applications that are launched with this context. The @icon_name will be interpreted in the same way as the Icon field in desktop files. See also [method@Gdk.AppLaunchContext.set_icon]. If both @icon and @icon_name are set, the @icon_name takes priority. If neither @icon or @icon_name is set, the icon is taken from either the file that is passed to launched application or from the `GAppInfo` for the launched application itself. a `GdkAppLaunchContext` an icon name Sets the timestamp of @context. The timestamp should ideally be taken from the event that triggered the launch. Window managers can use this information to avoid moving the focus to the newly launched application when the user is busy typing in another window. This is also known as 'focus stealing prevention'. a `GdkAppLaunchContext` a timestamp The display that the `GdkAppLaunchContext` is on. Flags describing the current capabilities of a device/tool. X axis is present Y axis is present Scroll X delta axis is present Scroll Y delta axis is present Pressure axis is present X tilt axis is present Y tilt axis is present Wheel axis is present Distance axis is present Z-axis rotation is present Slider axis is present Defines how device axes are interpreted by GTK. Note that the X and Y axes are not really needed; pointer devices report their location via the x/y members of events regardless. Whether X and Y are present as axes depends on the GDK backend. the axis is ignored. the axis is used as the x axis. the axis is used as the y axis. the axis is used as the scroll x delta the axis is used as the scroll y delta the axis is used for pressure information. the axis is used for x tilt information. the axis is used for y tilt information. the axis is used for wheel information. the axis is used for pen/tablet distance information the axis is used for pen rotation information the axis is used for pen slider information a constant equal to the numerically highest axis value. The middle button. The primary button. This is typically the left mouse button, or the right button in a left-handed setup. The secondary button. This is typically the right mouse button, or the left button in a left-handed setup. An event related to a button on a pointer device. Extract the button number from a button event. the button of @event a button event Represents the current time, and can be used anywhere a time is expected. Represents the platform-specific draw context. `GdkCairoContext`s are created for a surface using [method@Gdk.Surface.create_cairo_context], and the context can then be used to draw on that surface. Retrieves a Cairo context to be used to draw on the `GdkSurface` of @context. A call to [method@Gdk.DrawContext.begin_frame] with this @context must have been done or this function will return %NULL. The returned context is guaranteed to be valid until [method@Gdk.DrawContext.end_frame] is called. Drawing content with Cairo should be done via Cairo rendernodes, not by using renderers. a Cairo context to draw on `GdkSurface a `GdkCairoContext` that is currently drawing Contains the parameters that define a colorstate with cicp parameters. Cicp parameters are specified in the ITU-T H.273 [specification](https://www.itu.int/rec/T-REC-H.273/en). See the documentation of individual properties for supported values. The 'unspecified' value (2) is not treated in any special way, and must be replaced by a different value before creating a color state. `GdkCicpParams` can be used as a builder object to construct a color state from Cicp data with [method@Gdk.CicpParams.build_color_state]. The function will return an error if the given parameters are not supported. You can obtain a `GdkCicpParams` object from a color state with [method@Gdk.ColorState.create_cicp_params]. This can be used to create a variant of a color state, by changing just one of the cicp parameters, or just to obtain information about the color state. Creates a new `GdkCicpParams` object. The initial values of the properties are the values for "undefined" and need to be set before a color state object can be built. a new `GdkCicpParams` Creates a new `GdkColorState` object for the cicp parameters in @self. Note that this may fail if the cicp parameters in @self are not supported by GTK. In that case, `NULL` is returned, and @error is set with an error message that can be presented to the user. A newly allocated `GdkColorState` a `GdkCicpParams` Returns the value of the color-primaries property of @self. the color-primaries value a `GdkCicpParams` Gets the matrix-coefficients property of @self. the matrix-coefficients value a `GdkCicpParams` Gets the range property of @self. the range value a `GdkCicpParams` Gets the transfer-function property of @self. the transfer-function value a `GdkCicpParams` Sets the color-primaries property of @self. a `GdkCicpParams` the new color primaries value @self a `GdkCicpParams` Sets the matrix-coefficients property of @self. the new matrix-coefficients value Sets the range property of @self a `GdkCipParams` the range value Sets the transfer-function property of @self. a `GdkCicpParams` the new transfer-function value The color primaries to use. Supported values: - 1: BT.709 / sRGB - 2: unspecified - 5: PAL - 6,7: BT.601 / NTSC - 9: BT.2020 - 12: Display P3 The matrix coefficients (for YUV to RGB conversion). Supported values: - 0: RGB - 1: BT.709 - 2: unspecified - 5,6: BT.601 - 9: BT.2020 Whether the data is using the full range of values. The range of the data. The transfer function to use. Supported values: - 1,6,14,15: BT.709, BT.601, BT.2020 - 2: unspecified - 4: gamma 2.2 - 5: gamma 2.8 - 8: linear - 13: sRGB - 16: BT.2100 PQ - 18: BT.2100 HLG The values of this enumeration describe whether image data uses the full range of 8-bit values. In digital broadcasting, it is common to reserve the lowest and highest values. Typically the allowed values for the narrow range are 16-235 for Y and 16-240 for u,v (when dealing with YUV data). The values use the range of 16-235 (for Y) and 16-240 for u and v. The values use the full range. Represents data shared between applications or inside an application. To get a `GdkClipboard` object, use [method@Gdk.Display.get_clipboard] or [method@Gdk.Display.get_primary_clipboard]. You can find out about the data that is currently available in a clipboard using [method@Gdk.Clipboard.get_formats]. To make text or image data available in a clipboard, use [method@Gdk.Clipboard.set_text] or [method@Gdk.Clipboard.set_texture]. For other data, you can use [method@Gdk.Clipboard.set_content], which takes a [class@Gdk.ContentProvider] object. To read textual or image data from a clipboard, use [method@Gdk.Clipboard.read_text_async] or [method@Gdk.Clipboard.read_texture_async]. For other data, use [method@Gdk.Clipboard.read_async], which provides a `GInputStream` object. Returns the `GdkContentProvider` currently set on @clipboard. If the @clipboard is empty or its contents are not owned by the current process, %NULL will be returned. The content of a clipboard if the clipboard does not maintain any content a `GdkClipboard` Gets the `GdkDisplay` that the clipboard was created for. a `GdkDisplay` a `GdkClipboard` Gets the formats that the clipboard can provide its current contents in. The formats of the clipboard a `GdkClipboard` Returns if the clipboard is local. A clipboard is considered local if it was last claimed by the running application. Note that [method@Gdk.Clipboard.get_content] may return %NULL even on a local clipboard. In this case the clipboard is empty. %TRUE if the clipboard is local a `GdkClipboard` Asynchronously requests an input stream to read the @clipboard's contents from. The clipboard will choose the most suitable mime type from the given list to fulfill the request, preferring the ones listed first. a `GdkClipboard` a %NULL-terminated array of mime types to choose from the I/O priority of the request optional `GCancellable` object callback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous clipboard read. See [method@Gdk.Clipboard.read_async]. a `GInputStream` a `GdkClipboard` a `GAsyncResult` location to store the chosen mime type Asynchronously request the @clipboard contents converted to a string. This is a simple wrapper around [method@Gdk.Clipboard.read_value_async]. Use that function or [method@Gdk.Clipboard.read_async] directly if you need more control over the operation. a `GdkClipboard` optional `GCancellable` object callback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous clipboard read. See [method@Gdk.Clipboard.read_text_async]. a new string a `GdkClipboard` a `GAsyncResult` Asynchronously request the @clipboard contents converted to a `GdkPixbuf`. This is a simple wrapper around [method@Gdk.Clipboard.read_value_async]. Use that function or [method@Gdk.Clipboard.read_async] directly if you need more control over the operation. a `GdkClipboard` optional `GCancellable` object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous clipboard read. See [method@Gdk.Clipboard.read_texture_async]. a new `GdkTexture` a `GdkClipboard` a `GAsyncResult` Asynchronously request the @clipboard contents converted to the given @type. For local clipboard contents that are available in the given `GType`, the value will be copied directly. Otherwise, GDK will try to use [func@content_deserialize_async] to convert the clipboard's data. a `GdkClipboard` a `GType` to read the I/O priority of the request optional `GCancellable` object callback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous clipboard read. See [method@Gdk.Clipboard.read_value_async]. a `GValue` containing the result. a `GdkClipboard` a `GAsyncResult` Sets the clipboard to contain the value collected from the given varargs. Values should be passed the same way they are passed to other value collecting APIs, such as [method@GObject.Object.set] or [func@GObject.signal_emit]. ```c gdk_clipboard_set (clipboard, G_TYPE_STRING, "Hello World"); gdk_clipboard_set (clipboard, GDK_TYPE_TEXTURE, some_texture); ``` a `GdkClipboard` type of value to set value contents conforming to @type Sets a new content provider on @clipboard. The clipboard will claim the `GdkDisplay`'s resources and advertise these new contents to other applications. In the rare case of a failure, this function will return %FALSE. The clipboard will then continue reporting its old contents and ignore @provider. If the contents are read by either an external application or the @clipboard's read functions, @clipboard will select the best format to transfer the contents and then request that format from @provider. %TRUE if setting the clipboard succeeded a `GdkClipboard` the new contents of @clipboard or %NULL to clear the clipboard Puts the given @text into the clipboard. a `GdkClipboard` Text to put into the clipboard Puts the given @texture into the clipboard. a `GdkClipboard` a `GdkTexture` to put into the clipboard Sets the clipboard to contain the value collected from the given @args. a `GdkClipboard` type of value to set varargs containing the value of @type Sets the @clipboard to contain the given @value. a `GdkClipboard` a `GValue` to set Asynchronously instructs the @clipboard to store its contents remotely. If the clipboard is not local, this function does nothing but report success. The purpose of this call is to preserve clipboard contents beyond the lifetime of an application, so this function is typically called on exit. Depending on the platform, the functionality may not be available unless a "clipboard manager" is running. This function is called automatically when a [GtkApplication](../gtk4/class.Application.html) is shut down, so you likely don't need to call it. a `GdkClipboard` the I/O priority of the request optional `GCancellable` object callback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous clipboard store. See [method@Gdk.Clipboard.store_async]. %TRUE if storing was successful. a `GdkClipboard` a `GAsyncResult` The `GdkContentProvider` or %NULL if the clipboard is empty or contents are provided otherwise. The `GdkDisplay` that the clipboard belongs to. The possible formats that the clipboard can provide its data in. %TRUE if the contents of the clipboard are owned by this process. Emitted when the clipboard changes ownership. Enumerates the color channels of RGBA values as used in `GdkColor` and OpenGL/Vulkan shaders. Note that this is not the order of pixel values in Cairo and `GdkMemoryFormat` can have many different orders. The red color channel, aka 0 The green color channel, aka 1 The blue color channel, aka 2 The alpha color channel, aka 3 Provides information to interpret colors and pixels in a variety of ways. They are also known as [*color spaces*](https://en.wikipedia.org/wiki/Color_space). Crucially, GTK knows how to convert colors from one color state to another. `GdkColorState` objects are immutable and therefore threadsafe. Create a [class@Gdk.CicpParams] representing the colorstate. It is not guaranteed that every `GdkColorState` can be represented with Cicp parameters. If that is the case, this function returns `NULL`. A new [class@Gdk.CicpParams] a `GdkColorState` Compares two `GdkColorStates` for equality. Note that this function is not guaranteed to be perfect and two objects describing the same color state may compare not equal. However, different color states will never compare equal. %TRUE if the two color states compare equal a `GdkColorState` another `GdkColorStatee` Compares two `GdkColorStates` for equivalence. Two objects that represent the same color state should be equivalent, even though they may not be equal in the sense of [method@Gdk.ColorState.equal]. %TRUE if the two color states are equivalent a `GdkColorState` another `GdkColorStatee` Increase the reference count of @self. the object that was passed in a `GdkColorState` Decrease the reference count of @self. Unless @self is static, it will be freed when the reference count reaches zero. a `GdkColorState` Returns the color state object representing the oklab color space. This is a perceptually uniform color state. the color state object for oklab Returns the color state object representing the oklch color space. This is the polar variant of oklab, in which the hue is encoded as a polar coordinate. the color state object for oklch Returns the color state object representing the linear rec2100 color space. This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and a linear transfer function. It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/8/0/1. See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-linear) for details about this colorstate. the color state object for linearized rec2100 Returns the color state object representing the rec2100-pq color space. This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and the transfer function defined by SMPTE ST 2084 and BT.2100-2. It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/16/0/1. See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-pq) for details about this colorstate. the color state object for rec2100-pq Returns the color state object representing the sRGB color space. This color state uses the primaries defined by BT.709-6 and the transfer function defined by IEC 61966-2-1. It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/13/0/1. See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB) for details about this colorstate. the color state object for sRGB Returns the color state object representing the linearized sRGB color space. This color state uses the primaries defined by BT.709-6 and a linear transfer function. It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/8/0/1. See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB-linear) for details about this colorstate. the color state object for linearized sRGB The type of a function that can be registered with gdk_content_register_deserializer(). When the function gets called to operate on content, it can call functions on the @deserializer object to obtain the mime type, input stream, user data, etc. for its operation. a `GdkContentDeserializer` Deserializes content received via inter-application data transfers. The `GdkContentDeserializer` transforms serialized content that is identified by a mime type into an object identified by a GType. GTK provides serializers and deserializers for common data types such as text, colors, images or file lists. To register your own deserialization functions, use [func@content_register_deserializer]. Also see [class@Gdk.ContentSerializer]. Gets the cancellable for the current operation. This is the `GCancellable` that was passed to [func@Gdk.content_deserialize_async]. the cancellable for the current operation a `GdkContentDeserializer` Gets the `GType` to create an instance of. the `GType` for the current operation a `GdkContentDeserializer` Gets the input stream for the current operation. This is the stream that was passed to [func@Gdk.content_deserialize_async]. the input stream for the current operation a `GdkContentDeserializer` Gets the mime type to deserialize from. the mime type for the current operation a `GdkContentDeserializer` Gets the I/O priority for the current operation. This is the priority that was passed to [func@Gdk.content_deserialize_async]. the I/O priority for the current operation a `GdkContentDeserializer` Gets the data that was associated with the current operation. See [method@Gdk.ContentDeserializer.set_task_data]. the task data for @deserializer a `GdkContentDeserializer` Gets the user data that was passed when the deserializer was registered. the user data for this deserializer a `GdkContentDeserializer` Gets the `GValue` to store the deserialized object in. the `GValue` for the current operation a `GdkContentDeserializer` Indicate that the deserialization has ended with an error. This function consumes @error. a `GdkContentDeserializer` a `GError` Indicate that the deserialization has been successfully completed. a `GdkContentDeserializer` Associate data with the current deserialization operation. a `GdkContentDeserializer` data to associate with this operation destroy notify for @data Used to advertise and negotiate the format of content. You will encounter `GdkContentFormats` when interacting with objects controlling operations that pass data between different widgets, window or application, like [class@Gdk.Drag], [class@Gdk.Drop], [class@Gdk.Clipboard] or [class@Gdk.ContentProvider]. GDK supports content in 2 forms: `GType` and mime type. Using `GTypes` is meant only for in-process content transfers. Mime types are meant to be used for data passing both in-process and out-of-process. The details of how data is passed is described in the documentation of the actual implementations. To transform between the two forms, [class@Gdk.ContentSerializer] and [class@Gdk.ContentDeserializer] are used. A `GdkContentFormats` describes a set of possible formats content can be exchanged in. It is assumed that this set is ordered. `GTypes` are more important than mime types. Order between different `GTypes` or mime types is the order they were added in, most important first. Functions that care about order, such as [method@Gdk.ContentFormats.union], will describe in their documentation how they interpret that order, though in general the order of the first argument is considered the primary order of the result, followed by the order of further arguments. For debugging purposes, the function [method@Gdk.ContentFormats.to_string] exists. It will print a comma-separated list of formats from most important to least important. `GdkContentFormats` is an immutable struct. After creation, you cannot change the types it represents. Instead, new `GdkContentFormats` have to be created. The [struct@Gdk.ContentFormatsBuilder] structure is meant to help in this endeavor. Creates a new `GdkContentFormats` from an array of mime types. The mime types must be valid and different from each other or the behavior of the return value is undefined. If you cannot guarantee this, use [struct@Gdk.ContentFormatsBuilder] instead. the new `GdkContentFormats`. Pointer to an array of mime types number of entries in @mime_types. Creates a new `GdkContentFormats` for a given `GType`. a new `GdkContentFormats` a `GType` Checks if a given `GType` is part of the given @formats. %TRUE if the `GType` was found a `GdkContentFormats` the `GType` to search for Checks if a given mime type is part of the given @formats. %TRUE if the mime_type was found a `GdkContentFormats` the mime type to search for Gets the `GType`s included in @formats. Note that @formats may not contain any `GType`s, in particular when they are empty. In that case %NULL will be returned. %G_TYPE_INVALID-terminated array of types included in @formats a `GdkContentFormats` optional pointer to take the number of `GType`s contained in the return value Gets the mime types included in @formats. Note that @formats may not contain any mime types, in particular when they are empty. In that case %NULL will be returned. %NULL-terminated array of interned strings of mime types included in @formats a `GdkContentFormats` optional pointer to take the number of mime types contained in the return value Returns whether the content formats contain any formats. true if @formats contains no mime types and no GTypes content formats Checks if @first and @second have any matching formats. %TRUE if a matching format was found. the primary `GdkContentFormats` to intersect the `GdkContentFormats` to intersect with Finds the first `GType` from @first that is also contained in @second. If no matching `GType` is found, %G_TYPE_INVALID is returned. The first common `GType` or %G_TYPE_INVALID if none. the primary `GdkContentFormats` to intersect the `GdkContentFormats` to intersect with Finds the first mime type from @first that is also contained in @second. If no matching mime type is found, %NULL is returned. The first common mime type or %NULL if none the primary `GdkContentFormats` to intersect the `GdkContentFormats` to intersect with Prints the given @formats into a string for human consumption. The result of this function can later be parsed with [func@Gdk.ContentFormats.parse]. a `GdkContentFormats` a `GString` to print into Increases the reference count of a `GdkContentFormats` by one. the passed in `GdkContentFormats`. a `GdkContentFormats` Prints the given @formats into a human-readable string. The resulting string can be parsed with [func@Gdk.ContentFormats.parse]. This is a small wrapper around [method@Gdk.ContentFormats.print] to help when debugging. a new string a `GdkContentFormats` Append all missing types from @second to @first, in the order they had in @second. a new `GdkContentFormats` the `GdkContentFormats` to merge into the `GdkContentFormats` to merge from Add GTypes for mime types in @formats for which deserializers are registered. a new `GdkContentFormats` a `GdkContentFormats` Add mime types for GTypes in @formats for which deserializers are registered. a new `GdkContentFormats` a `GdkContentFormats` Add GTypes for the mime types in @formats for which serializers are registered. a new `GdkContentFormats` a `GdkContentFormats` Add mime types for GTypes in @formats for which serializers are registered. a new `GdkContentFormats` a `GdkContentFormats` Decreases the reference count of a `GdkContentFormats` by one. If the resulting reference count is zero, frees the formats. a `GdkContentFormats` Parses the given @string into `GdkContentFormats` and returns the formats. Strings printed via [method@Gdk.ContentFormats.to_string] can be read in again successfully using this function. If @string does not describe valid content formats, %NULL is returned. the content formats if @string is valid the string to parse Creates `GdkContentFormats` objects. Create a new `GdkContentFormatsBuilder` object. The resulting builder would create an empty `GdkContentFormats`. Use addition functions to add types to it. a new `GdkContentFormatsBuilder` Appends all formats from @formats to @builder, skipping those that already exist. a `GdkContentFormatsBuilder` the formats to add Appends @type to @builder if it has not already been added. a `GdkContentFormats`Builder a `GType` Appends @mime_type to @builder if it has not already been added. a `GdkContentFormatsBuilder` a mime type Creates a new `GdkContentFormats` from the current state of the given @builder, and frees the @builder instance. the newly created `GdkContentFormats` with all the formats added to @builder a `GdkContentFormatsBuilder` Acquires a reference on the given @builder. This function is intended primarily for bindings. `GdkContentFormatsBuilder` objects should not be kept around. the given `GdkContentFormatsBuilder` with its reference count increased a `GdkContentFormatsBuilder` Creates a new `GdkContentFormats` from the given @builder. The given `GdkContentFormatsBuilder` is reset once this function returns; you cannot call this function multiple times on the same @builder instance. This function is intended primarily for bindings. C code should use [method@Gdk.ContentFormatsBuilder.free_to_formats]. the newly created `GdkContentFormats` with all the formats added to @builder a `GdkContentFormats`Builder Releases a reference on the given @builder. a `GdkContentFormatsBuilder` Provides content for the clipboard or for drag-and-drop operations in a number of formats. To create a `GdkContentProvider`, use [ctor@Gdk.ContentProvider.new_for_value] or [ctor@Gdk.ContentProvider.new_for_bytes]. GDK knows how to handle common text and image formats out-of-the-box. See [class@Gdk.ContentSerializer] and [class@Gdk.ContentDeserializer] if you want to add support for application-specific data formats. Create a content provider that provides the given @bytes as data for the given @mime_type. a new `GdkContentProvider` the mime type a `GBytes` with the data for @mime_type Create a content provider that provides the given @value. a new `GdkContentProvider` a `GValue` Create a content provider that provides the value of the given @type. The value is provided using G_VALUE_COLLECT(), so the same rules apply as when calling g_object_new() or g_object_set(). a new `GdkContentProvider` Type of value to follow value Creates a content provider that represents all the given @providers. Whenever data needs to be written, the union provider will try the given @providers in the given order and the first one supporting a format will be chosen to provide it. This allows an easy way to support providing data in different formats. For example, an image may be provided by its file and by the image contents with a call such as ```c gdk_content_provider_new_union ((GdkContentProvider *[2]) { gdk_content_provider_new_typed (G_TYPE_FILE, file), gdk_content_provider_new_typed (GDK_TYPE_TEXTURE, texture) }, 2); ``` a new `GdkContentProvider` The `GdkContentProvider`s to present the union of the number of providers Emits the ::content-changed signal. a `GdkContentProvider` Gets the contents of @provider stored in @value. The @value will have been initialized to the `GType` the value should be provided in. This given `GType` does not need to be listed in the formats returned by [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is not supported, this operation can fail and `G_IO_ERROR_NOT_SUPPORTED` will be reported. %TRUE if the value was set successfully. Otherwise @error will be set to describe the failure. a `GdkContentProvider` the `GValue` to fill Gets the formats that the provider can provide its current contents in. The formats of the provider a `GdkContentProvider` Gets the formats that the provider suggests other applications to store the data in. An example of such an application would be a clipboard manager. This can be assumed to be a subset of [method@Gdk.ContentProvider.ref_formats]. The storable formats of the provider a `GdkContentProvider` Asynchronously writes the contents of @provider to @stream in the given @mime_type. The given mime type does not need to be listed in the formats returned by [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is not supported, `G_IO_ERROR_NOT_SUPPORTED` will be reported. The given @stream will not be closed. a `GdkContentProvider` the mime type to provide the data in the `GOutputStream` to write to I/O priority of the request. optional `GCancellable` object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous write operation. See [method@Gdk.ContentProvider.write_mime_type_async]. %TRUE if the operation was completed successfully. Otherwise @error will be set to describe the failure. a `GdkContentProvider` a `GAsyncResult` Emits the ::content-changed signal. a `GdkContentProvider` Gets the contents of @provider stored in @value. The @value will have been initialized to the `GType` the value should be provided in. This given `GType` does not need to be listed in the formats returned by [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is not supported, this operation can fail and `G_IO_ERROR_NOT_SUPPORTED` will be reported. %TRUE if the value was set successfully. Otherwise @error will be set to describe the failure. a `GdkContentProvider` the `GValue` to fill Gets the formats that the provider can provide its current contents in. The formats of the provider a `GdkContentProvider` Gets the formats that the provider suggests other applications to store the data in. An example of such an application would be a clipboard manager. This can be assumed to be a subset of [method@Gdk.ContentProvider.ref_formats]. The storable formats of the provider a `GdkContentProvider` Asynchronously writes the contents of @provider to @stream in the given @mime_type. The given mime type does not need to be listed in the formats returned by [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is not supported, `G_IO_ERROR_NOT_SUPPORTED` will be reported. The given @stream will not be closed. a `GdkContentProvider` the mime type to provide the data in the `GOutputStream` to write to I/O priority of the request. optional `GCancellable` object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous write operation. See [method@Gdk.ContentProvider.write_mime_type_async]. %TRUE if the operation was completed successfully. Otherwise @error will be set to describe the failure. a `GdkContentProvider` a `GAsyncResult` The possible formats that the provider can provide its data in. The subset of formats that clipboard managers should store this provider's data in. Emitted whenever the content provided by this provider has changed. Class structure for `GdkContentProvider`. Signal class closure for `GdkContentProvider::content-changed` a `GdkContentProvider` The formats of the provider a `GdkContentProvider` The storable formats of the provider a `GdkContentProvider` a `GdkContentProvider` the mime type to provide the data in the `GOutputStream` to write to I/O priority of the request. optional `GCancellable` object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function %TRUE if the operation was completed successfully. Otherwise @error will be set to describe the failure. a `GdkContentProvider` a `GAsyncResult` %TRUE if the value was set successfully. Otherwise @error will be set to describe the failure. a `GdkContentProvider` the `GValue` to fill The type of a function that can be registered with gdk_content_register_serializer(). When the function gets called to operate on content, it can call functions on the @serializer object to obtain the mime type, output stream, user data, etc. for its operation. a `GdkContentSerializer` Serializes content for inter-application data transfers. The `GdkContentSerializer` transforms an object that is identified by a GType into a serialized form (i.e. a byte stream) that is identified by a mime type. GTK provides serializers and deserializers for common data types such as text, colors, images or file lists. To register your own serialization functions, use [func@Gdk.content_register_serializer]. Also see [class@Gdk.ContentDeserializer]. Gets the cancellable for the current operation. This is the `GCancellable` that was passed to [func@content_serialize_async]. the cancellable for the current operation a `GdkContentSerializer` Gets the `GType` to of the object to serialize. the `GType` for the current operation a `GdkContentSerializer` Gets the mime type to serialize to. the mime type for the current operation a `GdkContentSerializer` Gets the output stream for the current operation. This is the stream that was passed to [func@content_serialize_async]. the output stream for the current operation a `GdkContentSerializer` Gets the I/O priority for the current operation. This is the priority that was passed to [func@content_serialize_async]. the I/O priority for the current operation a `GdkContentSerializer` Gets the data that was associated with the current operation. See [method@Gdk.ContentSerializer.set_task_data]. the task data for @serializer a `GdkContentSerializer` Gets the user data that was passed when the serializer was registered. the user data for this serializer a `GdkContentSerializer` Gets the `GValue` to read the object to serialize from. the `GValue` for the current operation a `GdkContentSerializer` Indicate that the serialization has ended with an error. This function consumes @error. a `GdkContentSerializer` a `GError` Indicate that the serialization has been successfully completed. a `GdkContentSerializer` Associate data with the current serialization operation. a `GdkContentSerializer` data to associate with this operation destroy notify for @data An event caused by a pointing device moving between surfaces. Extracts the notify detail from a crossing event. the notify detail of @event a crossing event Checks if the @event surface is the focus surface. %TRUE if the surface is the focus surface a crossing event Extracts the crossing mode from a crossing event. the mode of @event a crossing event Specifies the crossing mode for enter and leave events. crossing because of pointer motion. crossing because a grab is activated. crossing because a grab is deactivated. crossing because a GTK grab is activated. crossing because a GTK grab is deactivated. crossing because a GTK widget changed state (e.g. sensitivity). crossing because a touch sequence has begun, this event is synthetic as the pointer might have not left the surface. crossing because a touch sequence has ended, this event is synthetic as the pointer might have not left the surface. crossing because of a device switch (i.e. a mouse taking control of the pointer after a touch device), this event is synthetic as the pointer didn’t leave the surface. Used to create and destroy cursors. Cursors are immutable objects, so once you created them, there is no way to modify them later. You should create a new cursor when you want to change something about it. Cursors by themselves are not very interesting: they must be bound to a window for users to see them. This is done with [method@Gdk.Surface.set_cursor] or [method@Gdk.Surface.set_device_cursor]. Applications will typically use higher-level GTK functions such as [gtk_widget_set_cursor()](../gtk4/method.Widget.set_cursor.html) instead. Cursors are not bound to a given [class@Gdk.Display], so they can be shared. However, the appearance of cursors may vary when used on different platforms. ## Named and texture cursors There are multiple ways to create cursors. The platform's own cursors can be created with [ctor@Gdk.Cursor.new_from_name]. That function lists the commonly available names that are shared with the CSS specification. Other names may be available, depending on the platform in use. On some platforms, what images are used for named cursors may be influenced by the cursor theme. Another option to create a cursor is to use [ctor@Gdk.Cursor.new_from_texture] and provide an image to use for the cursor. To ease work with unsupported cursors, a fallback cursor can be provided. If a [class@Gdk.Surface] cannot use a cursor because of the reasons mentioned above, it will try the fallback cursor. Fallback cursors can themselves have fallback cursors again, so it is possible to provide a chain of progressively easier to support cursors. If none of the provided cursors can be supported, the default cursor will be the ultimate fallback. Creates a new callback-based cursor object. Cursors of this kind produce textures for the cursor image on demand, when the @callback is called. a new `GdkCursor` the `GdkCursorGetTextureCallback` data to pass to @callback destroy notify for @data the `GdkCursor` to fall back to when this one cannot be supported Creates a new cursor by looking up @name in the current cursor theme. A recommended set of cursor names that will work across different platforms can be found in the CSS specification: | | | | | --- | --- | --- | | | "none" | No cursor | | ![](default_cursor.png) | "default" | The default cursor | | ![](help_cursor.png) | "help" | Help is available | | ![](pointer_cursor.png) | "pointer" | Indicates a link or interactive element | | ![](context_menu_cursor.png) |"context-menu" | A context menu is available | | ![](progress_cursor.png) | "progress" | Progress indicator | | ![](wait_cursor.png) | "wait" | Busy cursor | | ![](cell_cursor.png) | "cell" | Cell(s) may be selected | | ![](crosshair_cursor.png) | "crosshair" | Simple crosshair | | ![](text_cursor.png) | "text" | Text may be selected | | ![](vertical_text_cursor.png) | "vertical-text" | Vertical text may be selected | | ![](alias_cursor.png) | "alias" | DND: Something will be linked | | ![](copy_cursor.png) | "copy" | DND: Something will be copied | | ![](move_cursor.png) | "move" | DND: Something will be moved | | ![](dnd_ask_cursor.png) | "dnd-ask" | DND: User can choose action to be carried out | | ![](no_drop_cursor.png) | "no-drop" | DND: Can't drop here | | ![](not_allowed_cursor.png) | "not-allowed" | DND: Action will not be carried out | | ![](grab_cursor.png) | "grab" | DND: Something can be grabbed | | ![](grabbing_cursor.png) | "grabbing" | DND: Something is being grabbed | | ![](n_resize_cursor.png) | "n-resize" | Resizing: Move north border | | ![](e_resize_cursor.png) | "e-resize" | Resizing: Move east border | | ![](s_resize_cursor.png) | "s-resize" | Resizing: Move south border | | ![](w_resize_cursor.png) | "w-resize" | Resizing: Move west border | | ![](ne_resize_cursor.png) | "ne-resize" | Resizing: Move north-east corner | | ![](nw_resize_cursor.png) | "nw-resize" | Resizing: Move north-west corner | | ![](sw_resize_cursor.png) | "sw-resize" | Resizing: Move south-west corner | | ![](se_resize_cursor.png) | "se-resize" | Resizing: Move south-east corner | | ![](col_resize_cursor.png) | "col-resize" | Resizing: Move an item or border horizontally | | ![](row_resize_cursor.png) | "row-resize" | Resizing: Move an item or border vertically | | ![](ew_resize_cursor.png) | "ew-resize" | Moving: Something can be moved horizontally | | ![](ns_resize_cursor.png) | "ns-resize" | Moving: Something can be moved vertically | | ![](nesw_resize_cursor.png) | "nesw-resize" | Moving: Something can be moved diagonally, north-east to south-west | | ![](nwse_resize_cursor.png) | "nwse-resize" | Moving: something can be moved diagonally, north-west to south-east | | ![](all_resize_cursor.png) | "all-resize" | Moving: Something can be moved in any direction | | ![](all_scroll_cursor.png) | "all-scroll" | Can scroll in any direction | | ![](zoom_in_cursor.png) | "zoom-in" | Zoom in | | ![](zoom_out_cursor.png) | "zoom-out" | Zoom out | a new `GdkCursor`, or %NULL if there is no cursor with the given name the name of the cursor %NULL or the `GdkCursor` to fall back to when this one cannot be supported Creates a new cursor from a `GdkTexture`. a new `GdkCursor` the texture providing the pixel data the horizontal offset of the “hotspot” of the cursor the vertical offset of the “hotspot” of the cursor the `GdkCursor` to fall back to when this one cannot be supported Returns the fallback for this @cursor. The fallback will be used if this cursor is not available on a given `GdkDisplay`. For named cursors, this can happen when using nonstandard names or when using an incomplete cursor theme. For textured cursors, this can happen when the texture is too large or when the `GdkDisplay` it is used on does not support textured cursors. the fallback of the cursor or %NULL to use the default cursor as fallback a `GdkCursor` Returns the horizontal offset of the hotspot. The hotspot indicates the pixel that will be directly above the cursor. Note that named cursors may have a nonzero hotspot, but this function will only return the hotspot position for cursors created with [ctor@Gdk.Cursor.new_from_texture]. the horizontal offset of the hotspot or 0 for named cursors a `GdkCursor` Returns the vertical offset of the hotspot. The hotspot indicates the pixel that will be directly above the cursor. Note that named cursors may have a nonzero hotspot, but this function will only return the hotspot position for cursors created with [ctor@Gdk.Cursor.new_from_texture]. the vertical offset of the hotspot or 0 for named cursors a `GdkCursor` Returns the name of the cursor. If the cursor is not a named cursor, %NULL will be returned. the name of the cursor or %NULL if it is not a named cursor a `GdkCursor` Returns the texture for the cursor. If the cursor is a named cursor, %NULL will be returned. the texture for cursor or %NULL if it is a named cursor a `GdkCursor` Cursor to fall back to if this cursor cannot be displayed. X position of the cursor hotspot in the cursor image. Y position of the cursor hotspot in the cursor image. Name of this this cursor. The name will be %NULL if the cursor was created from a texture. The texture displayed by this cursor. The texture will be %NULL if the cursor was created from a name. The type of callback used by a dynamic `GdkCursor` to generate a texture for the cursor image at the given @cursor_size and @scale. The actual cursor size in application pixels may be different from @cursor_size x @cursor_size, and will be returned in @width, @height. The returned texture should have a size that corresponds to the actual cursor size, in device pixels (i.e. application pixels, multiplied by @scale). This function may fail and return `NULL`, in which case the fallback cursor will be used. the cursor image, or `NULL` if none could be produced. the `GdkCursor` the nominal cursor size, in application pixels the device scale return location for the actual cursor width, in application pixels return location for the actual cursor height, in application pixels return location for the hotspot X position, in application pixels return location for the hotspot Y position, in application pixels User data for the callback An event related to drag and drop operations. Gets the `GdkDrop` object from a DND event. the drop a DND event An event related to closing a top-level surface. Represents an input device, such as a keyboard, mouse or touchpad. See the [class@Gdk.Seat] documentation for more information about the various kinds of devices, and their relationships. Retrieves the index of the active layout of the keyboard. If there is no valid active layout for the `GdkDevice`, this function will return -1; This is only relevant for keyboard devices. The layout index of the active layout or -1. a `GdkDevice` Retrieves whether the Caps Lock modifier of the keyboard is locked. This is only relevant for keyboard devices. %TRUE if Caps Lock is on for @device a `GdkDevice` Retrieves the current tool for @device. the `GdkDeviceTool` a `GdkDevice` Returns the direction of effective layout of the keyboard. This is only relevant for keyboard devices. The direction of a layout is the direction of the majority of its symbols. See [func@Pango.unichar_direction]. %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL if it can determine the direction. %PANGO_DIRECTION_NEUTRAL otherwise a `GdkDevice` Returns the `GdkDisplay` to which @device pertains. a `GdkDisplay` a `GdkDevice` Determines whether the pointer follows device motion. This is not meaningful for keyboard devices, which don't have a pointer. %TRUE if the pointer follows device motion a `GdkDevice` Retrieves the names of the layouts of the keyboard. This is only relevant for keyboard devices. %NULL-terminated array of strings of layouts, a `GdkDevice` Retrieves the current modifier state of the keyboard. This is only relevant for keyboard devices. the current modifier state a `GdkDevice` The name of the device, suitable for showing in a user interface. a name a GdkDevice` Retrieves whether the Num Lock modifier of the keyboard is locked. This is only relevant for keyboard devices. %TRUE if Num Lock is on for @device a ``GdkDevice` Retrieves the number of touch points associated to @device. the number of touch points a `GdkDevice` Returns the product ID of this device. This ID is retrieved from the device, and does not change. See [method@Gdk.Device.get_vendor_id] for more information. the product ID a physical `GdkDevice` Retrieves whether the Scroll Lock modifier of the keyboard is locked. This is only relevant for keyboard devices. %TRUE if Scroll Lock is on for @device a `GdkDevice` Returns the `GdkSeat` the device belongs to. a `GdkSeat` A `GdkDevice` Determines the type of the device. a `GdkInputSource` a `GdkDevice` Obtains the surface underneath @device, returning the location of the device in @win_x and @win_y. Returns %NULL if the surface tree under @device is not known to GDK (for example, belongs to another application). the `GdkSurface` under the device position pointer `GdkDevice` to query info to return location for the X coordinate of the device location relative to the surface origin return location for the Y coordinate of the device location relative to the surface origin Returns the timestamp of the last activity for this device. In practice, this means the timestamp of the last event that was received from the OS for this device. (GTK may occasionally produce events for a device that are not received from the OS, and will not update the timestamp). the timestamp of the last activity for this device a `GdkDevice` Returns the vendor ID of this device. This ID is retrieved from the device, and does not change. This function, together with [method@Gdk.Device.get_product_id], can be used to eg. compose `GSettings` paths to store settings for this device. ```c static GSettings * get_device_settings (GdkDevice *device) { const char *vendor, *product; GSettings *settings; GdkDevice *device; char *path; vendor = gdk_device_get_vendor_id (device); product = gdk_device_get_product_id (device); path = g_strdup_printf ("/org/example/app/devices/%s:%s/", vendor, product); settings = g_settings_new_with_path (DEVICE_SCHEMA, path); g_free (path); return settings; } ``` the vendor ID a physical `GdkDevice` Determines if layouts for both right-to-left and left-to-right languages are in use on the keyboard. This is only relevant for keyboard devices. %TRUE if there are layouts with both directions, %FALSE otherwise a `GdkDevice` The index of the keyboard active layout of a `GdkDevice`. Will be -1 if there is no valid active layout. This is only relevant for keyboard devices. Whether Caps Lock is on. This is only relevant for keyboard devices. The direction of the current layout. This is only relevant for keyboard devices. The `GdkDisplay` the `GdkDevice` pertains to. Whether the device has both right-to-left and left-to-right layouts. This is only relevant for keyboard devices. Whether the device is represented by a cursor on the screen. The names of the keyboard layouts of a `GdkDevice`. This is only relevant for keyboard devices. The current modifier state of the device. This is only relevant for keyboard devices. Number of axes in the device. The device name. Whether Num Lock is on. This is only relevant for keyboard devices. The maximal number of concurrent touches on a touch device. Will be 0 if the device is not a touch device or if the number of touches is unknown. Product ID of this device. See [method@Gdk.Device.get_product_id]. Whether Scroll Lock is on. This is only relevant for keyboard devices. `GdkSeat` of this device. Source type for the device. The `GdkDeviceTool` that is currently used with this device. Vendor ID of this device. See [method@Gdk.Device.get_vendor_id]. Emitted either when the number of either axes or keys changes. On X11 this will normally happen when the physical device routing events through the logical device changes (for example, user switches from the USB mouse to a tablet); in that case the logical device will change to reflect the axes and keys on the new physical device. Emitted on pen/eraser devices whenever tools enter or leave proximity. The new current tool An interface for tablet pad devices. It allows querying the features provided by the pad device. Tablet pads may contain one or more groups, each containing a subset of the buttons/rings/strips available. [method@Gdk.DevicePad.get_n_groups] can be used to obtain the number of groups, [method@Gdk.DevicePad.get_n_features] and [method@Gdk.DevicePad.get_feature_group] can be combined to find out the number of buttons/rings/strips the device has, and how are they grouped. Each of those groups have different modes, which may be used to map each individual pad feature to multiple actions. Only one mode is effective (current) for each given group, different groups may have different current modes. The number of available modes in a group can be found out through [method@Gdk.DevicePad.get_group_n_modes], and the current mode for a given group will be notified through events of type `GDK_PAD_GROUP_MODE`. Returns the group the given @feature and @idx belong to. f the feature or index do not exist in @pad, -1 is returned. The group number of the queried pad feature. a `GdkDevicePad` the feature type to get the group from the index of the feature to get the group from Returns the number of modes that @group may have. The number of modes available in @group. a `GdkDevicePad` group to get the number of available modes from Returns the number of features a tablet pad has. The amount of elements of type @feature that this pad has. a `GdkDevicePad` a pad feature Returns the number of groups this pad device has. Pads have at least one group. A pad group is a subcollection of buttons/strip/rings that is affected collectively by a same current mode. The number of button/ring/strip groups in the pad. a `GdkDevicePad` A pad feature. a button a ring-shaped interactive area a straight interactive area A physical tool associated to a `GdkDevice`. Gets the axes of the tool. the axes of @tool a `GdkDeviceTool` Gets the hardware ID of this tool, or 0 if it's not known. When non-zero, the identifier is unique for the given tool model, meaning that two identical tools will share the same @hardware_id, but will have different serial numbers (see [method@Gdk.DeviceTool.get_serial]). This is a more concrete (and device specific) method to identify a `GdkDeviceTool` than [method@Gdk.DeviceTool.get_tool_type], as a tablet may support multiple devices with the same `GdkDeviceToolType`, but different hardware identifiers. The hardware identifier of this tool. a `GdkDeviceTool` Gets the serial number of this tool. This value can be used to identify a physical tool (eg. a tablet pen) across program executions. The serial ID for this tool a `GdkDeviceTool` Gets the `GdkDeviceToolType` of the tool. The physical type for this tool. This can be used to figure out what sort of pen is being used, such as an airbrush or a pencil. a `GdkDeviceTool` The axes of the tool. The hardware ID of the tool. The serial number of the tool. The type of the tool. Indicates the specific type of tool being used being a tablet. Such as an airbrush, pencil, etc. Tool is of an unknown type. Tool is a standard tablet stylus. Tool is standard tablet eraser. Tool is a brush stylus. Tool is a pencil stylus. Tool is an airbrush stylus. Tool is a mouse. Tool is a lens cursor. A representation of a workstation. Their purpose are two-fold: - To manage and provide information about input devices (pointers, keyboards, etc) - To manage and provide information about output devices (monitors, projectors, etc) Most of the input device handling has been factored out into separate [class@Gdk.Seat] objects. Every display has a one or more seats, which can be accessed with [method@Gdk.Display.get_default_seat] and [method@Gdk.Display.list_seats]. Output devices are represented by [class@Gdk.Monitor] objects, which can be accessed with [method@Gdk.Display.get_monitor_at_surface] and similar APIs. Gets the default `GdkDisplay`. This is a convenience function for: gdk_display_manager_get_default_display (gdk_display_manager_get ()) a `GdkDisplay`, or %NULL if there is no default display Opens a display. If opening the display fails, `NULL` is returned. a `GdkDisplay` the name of the display to open Emits a short beep on @display a `GdkDisplay` Closes the connection to the windowing system for the given display. This cleans up associated resources. a `GdkDisplay` Creates a new `GdkGLContext` for the `GdkDisplay`. The context is disconnected from any particular surface or surface and cannot be used to draw to any surface. It can only be used to draw to non-surface framebuffers like textures. If the creation of the `GdkGLContext` failed, @error will be set. Before using the returned `GdkGLContext`, you will need to call [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize]. the newly created `GdkGLContext` a `GdkDisplay` Returns %TRUE if there is an ongoing grab on @device for @display. %TRUE if there is a grab in effect for @device. a `GdkDisplay` a `GdkDevice` Flushes any requests queued for the windowing system. This happens automatically when the main loop blocks waiting for new events, but if your application is drawing without returning control to the main loop, you may need to call this function explicitly. A common case where this function needs to be called is when an application is executing drawing commands from a thread other than the thread where the main loop is running. This is most useful for X11. On windowing systems where requests are handled synchronously, this function will do nothing. a `GdkDisplay` Returns a `GdkAppLaunchContext` suitable for launching applications on the given display. a new `GdkAppLaunchContext` for @display a `GdkDisplay` Gets the clipboard used for copy/paste operations. the display's clipboard a `GdkDisplay` Returns the default `GdkSeat` for this display. Note that a display may not have a seat. In this case, this function will return %NULL. the default seat. a `GdkDisplay` Returns the dma-buf formats that are supported on this display. GTK may use OpenGL or Vulkan to support some formats. Calling this function will then initialize them if they aren't yet. The formats returned by this function can be used for negotiating buffer formats with producers such as v4l, pipewire or GStreamer. To learn more about dma-bufs, see [class@Gdk.DmabufTextureBuilder]. This function is threadsafe. It can be called from any thread. a `GdkDmabufFormats` object a `GdkDisplay` Gets the monitor in which the largest area of @surface resides. the monitor with the largest overlap with @surface a `GdkDisplay` a `GdkSurface` Gets the list of monitors associated with this display. Subsequent calls to this function will always return the same list for the same display. You can listen to the GListModel::items-changed signal on this list to monitor changes to the monitor of this display. a `GListModel` of `GdkMonitor` a `GdkDisplay` Gets the name of the display. a string representing the display name. This string is owned by GDK and should not be modified or freed. a `GdkDisplay` Gets the clipboard used for the primary selection. On backends where the primary clipboard is not supported natively, GDK emulates this clipboard locally. the primary clipboard a `GdkDisplay` Retrieves a desktop-wide setting such as double-click time for the @display. %TRUE if the setting existed and a value was stored in @value, %FALSE otherwise a `GdkDisplay` the name of the setting location to store the value of the setting Gets the startup notification ID for a Wayland display, or %NULL if no ID has been defined. the startup notification ID for @display a `GdkDisplay` Finds out if the display has been closed. %TRUE if the display is closed. a `GdkDisplay` Returns whether surfaces can reasonably be expected to have their alpha channel drawn correctly on the screen. Check [method@Gdk.Display.is_rgba] for whether the display supports an alpha channel. On X11 this function returns whether a compositing manager is compositing on @display. On modern displays, this value is always %TRUE. Whether surfaces with RGBA visuals can reasonably be expected to have their alpha channels drawn correctly on the screen. a `GdkDisplay` Returns whether surfaces on this @display are created with an alpha channel. Even if a %TRUE is returned, it is possible that the surface’s alpha channel won’t be honored when displaying the surface on the screen: in particular, for X an appropriate windowing manager and compositing manager must be running to provide appropriate display. Use [method@Gdk.Display.is_composited] to check if that is the case. On modern displays, this value is always %TRUE. %TRUE if surfaces are created with an alpha channel or %FALSE if the display does not support this functionality. a `GdkDisplay` Returns the list of seats known to @display. the list of seats known to the `GdkDisplay` a `GdkDisplay` Returns the keyvals bound to @keycode. The Nth `GdkKeymapKey` in @keys is bound to the Nth keyval in @keyvals. When a keycode is pressed by the user, the keyval from this list of entries is selected by considering the effective keyboard group and level. Free the returned arrays with g_free(). %TRUE if there were any entries a `GdkDisplay` a keycode return location for array of `GdkKeymapKey` return location for array of keyvals length of @keys and @keyvals Obtains a list of keycode/group/level combinations that will generate @keyval. Groups and levels are two kinds of keyboard mode; in general, the level determines whether the top or bottom symbol on a key is used, and the group determines whether the left or right symbol is used. On US keyboards, the shift key changes the keyboard level, and there are no groups. A group switch key might convert a keyboard between Hebrew to English modes, for example. `GdkEventKey` contains a %group field that indicates the active keyboard group. The level is computed from the modifier mask. The returned array should be freed with g_free(). %TRUE if keys were found and returned a `GdkDisplay` a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc. return location for an array of `GdkKeymapKey` return location for number of elements in returned array Indicates to the GUI environment that the application has finished loading, using a given identifier. GTK will call this function automatically for [GtkWindow](../gtk4/class.Window.html) with custom startup-notification identifier unless [gtk_window_set_auto_startup_notification()](../gtk4/method.Window.set_auto_startup_notification.html) is called to disable that feature. Using [method@Gdk.Toplevel.set_startup_id] is sufficient a `GdkDisplay` a startup-notification identifier, for which notification process should be completed Checks that OpenGL is available for @self and ensures that it is properly initialized. When this fails, an @error will be set describing the error and this function returns %FALSE. Note that even if this function succeeds, creating a `GdkGLContext` may still fail. This function is idempotent. Calling it multiple times will just return the same value or error. You never need to call this function, GDK will call it automatically as needed. But you can use it as a check when setting up code that might make use of OpenGL. %TRUE if the display supports OpenGL a `GdkDisplay` Adds the given event to the event queue for @display. This function is only useful in very special situations and should not be used by applications. a `GdkDisplay` a `GdkEvent` Returns %TRUE if the display supports input shapes. This means that [method@Gdk.Surface.set_input_region] can be used to modify the input shape of surfaces on @display. On modern displays, this value is always %TRUE. %TRUE if surfaces with modified input shape are supported a `GdkDisplay` Returns whether it's possible for a surface to draw outside of the window area. If %TRUE is returned the application decides if it wants to draw shadows. If %FALSE is returned, the compositor decides if it wants to draw shadows. %TRUE if surfaces can draw shadows or %FALSE if the display does not support this functionality. a `GdkDisplay` Flushes any requests queued for the windowing system and waits until all requests have been handled. This is often used for making sure that the display is synchronized with the current state of the program. Calling [method@Gdk.Display.sync] before [method@GdkX11.Display.error_trap_pop] makes sure that any errors generated from earlier requests are handled before the error trap is removed. This is most useful for X11. On windowing systems where requests are handled synchronously, this function will do nothing. a `GdkDisplay` Translates the contents of a `GdkEventKey` into a keyval, effective group, and level. Modifiers that affected the translation and are thus unavailable for application use are returned in @consumed_modifiers. The @effective_group is the group that was actually used for the translation; some keys such as Enter are not affected by the active keyboard group. The @level is derived from @state. @consumed_modifiers gives modifiers that should be masked out from @state when comparing this key press to a keyboard shortcut. For instance, on a US keyboard, the `plus` symbol is shifted, so when comparing a key press to a `<Control>plus` accelerator `<Shift>` should be masked out. This function should rarely be needed, since `GdkEventKey` already contains the translated keyval. It is exported for the benefit of virtualized test environments. %TRUE if there was a keyval bound to keycode/state/group. a `GdkDisplay` a keycode a modifier state active keyboard group return location for keyval return location for effective group return location for level return location for modifiers that were used to determine the group or level %TRUE if the display properly composites the alpha channel. The dma-buf formats that are supported on this display %TRUE if the display supports input shapes. %TRUE if the display supports an alpha channel. %TRUE if the display supports extensible frames. Emitted when the connection to the windowing system for @display is closed. %TRUE if the display was closed due to an error Emitted when the connection to the windowing system for @display is opened. Emitted whenever a new seat is made known to the windowing system. the seat that was just added Emitted whenever a seat is removed by the windowing system. the seat that was just removed Emitted whenever a setting changes its value. the name of the setting that changed Offers notification when displays appear or disappear. `GdkDisplayManager` is a singleton object. You can use [func@Gdk.DisplayManager.get] to obtain the `GdkDisplayManager` singleton, but that should be rarely necessary. Typically, initializing GTK opens a display that you can work with without ever accessing the `GdkDisplayManager`. The GDK library can be built with support for multiple backends. The `GdkDisplayManager` object determines which backend is used at runtime. In the rare case that you need to influence which of the backends is being used, you can use [func@Gdk.set_allowed_backends]. Note that you need to call this function before initializing GTK. ## Backend-specific code When writing backend-specific code that is supposed to work with multiple GDK backends, you have to consider both compile time and runtime. At compile time, use the `GDK_WINDOWING_X11`, `GDK_WINDOWING_WIN32` macros, etc. to find out which backends are present in the GDK library you are building your application against. At runtime, use type-check macros like GDK_IS_X11_DISPLAY() to find out which backend is in use: ```c #ifdef GDK_WINDOWING_X11 if (GDK_IS_X11_DISPLAY (display)) { // make X11-specific calls here } else #endif #ifdef GDK_WINDOWING_MACOS if (GDK_IS_MACOS_DISPLAY (display)) { // make Quartz-specific calls here } else #endif g_error ("Unsupported GDK backend"); ``` Gets the singleton `GdkDisplayManager` object. When called for the first time, this function consults the `GDK_BACKEND` environment variable to find out which of the supported GDK backends to use (in case GDK has been compiled with multiple backends). Applications can use [func@set_allowed_backends] to limit what backends will be used. The global `GdkDisplayManager` singleton Gets the default `GdkDisplay`. a `GdkDisplay` a `GdkDisplayManager` List all currently open displays. a newly allocated `GSList` of `GdkDisplay` objects a `GdkDisplayManager` Opens a display. a `GdkDisplay`, or %NULL if the display could not be opened a `GdkDisplayManager` the name of the display to open Sets @display as the default display. a `GdkDisplayManager` a `GdkDisplay` The default display. Emitted when a display is opened. the opened display Error enumeration for `GdkDmabufTexture`. Dmabuf support is not available, because the OS is not Linux, or it was explicitly disabled at compile- or runtime The requested format is not supported GTK failed to create the resource for other reasons Registers an error quark for [class@Gdk.DmabufTexture] errors. the error quark Provides information about supported DMA buffer formats. You can query whether a given format is supported with [method@Gdk.DmabufFormats.contains] and you can iterate over the list of all supported formats with [method@Gdk.DmabufFormats.get_n_formats] and [method@Gdk.DmabufFormats.get_format]. The list of supported formats is sorted by preference, with the best formats coming first. The list may contains (format, modifier) pairs where the modifier is `DMA_FORMAT_MOD_INVALID`, indicating that **_implicit modifiers_** may be used with this format. See [class@Gdk.DmabufTextureBuilder] for more information about DMA buffers. Note that DMA buffers only exist on Linux. Returns whether a given format is contained in @formats. `TRUE` if the format specified by the arguments is part of @formats a `GdkDmabufFormats` a format code a format modifier Returns whether @formats1 and @formats2 contain the same dmabuf formats, in the same order. `TRUE` if @formats1 and @formats2 are equal a `GdkDmabufFormats` another `GdkDmabufFormats` Gets the fourcc code and modifier for a format that is contained in @formats. a `GdkDmabufFormats` the index of the format to return return location for the format code return location for the format modifier Returns the number of formats that the @formats object contains. Note that DMA buffers are a Linux concept, so on other platforms, [method@Gdk.DmabufFormats.get_n_formats] will always return zero. the number of formats a `GdkDmabufFormats` Increases the reference count of @formats. the passed-in object a `GdkDmabufFormats` Decreases the reference count of @formats. When the reference count reaches zero, the object is freed. a `GdkDmabufFormats` A `GdkTexture` representing a DMA buffer. To create a `GdkDmabufTexture`, use the auxiliary [class@Gdk.DmabufTextureBuilder] object. Dma-buf textures can only be created on Linux. Constructs [class@Gdk.Texture] objects from DMA buffers. DMA buffers are commonly called **_dma-bufs_**. DMA buffers are a feature of the Linux kernel to enable efficient buffer and memory sharing between hardware such as codecs, GPUs, displays, cameras and the kernel drivers controlling them. For example, a decoder may want its output to be directly shared with the display server for rendering without a copy. Any device driver which participates in DMA buffer sharing, can do so as either the exporter or importer of buffers (or both). The memory that is shared via DMA buffers is usually stored in non-system memory (maybe in device's local memory or something else not directly accessible by the CPU), and accessing this memory from the CPU may have higher-than-usual overhead. In particular for graphics data, it is not uncommon that data consists of multiple separate blocks of memory, for example one block for each of the red, green and blue channels. These blocks are called **_planes_**. DMA buffers can have up to four planes. Even if the memory is a single block, the data can be organized in multiple planes, by specifying offsets from the beginning of the data. DMA buffers are exposed to user-space as file descriptors allowing to pass them between processes. If a DMA buffer has multiple planes, there is one file descriptor per plane. The format of the data (for graphics data, essentially its colorspace) is described by a 32-bit integer. These format identifiers are defined in the header file `drm_fourcc.h` and commonly referred to as **_fourcc_** values, since they are identified by 4 ASCII characters. Additionally, each DMA buffer has a **_modifier_**, which is a 64-bit integer that describes driver-specific details of the memory layout, such as tiling or compression. For historical reasons, some producers of dma-bufs don't provide an explicit modifier, but instead return `DMA_FORMAT_MOD_INVALID` to indicate that their modifier is **_implicit_**. GTK tries to accommodate this situation by accepting `DMA_FORMAT_MOD_INVALID` as modifier. The operation of `GdkDmabufTextureBuilder` is quite simple: Create a texture builder, set all the necessary properties, and then call [method@Gdk.DmabufTextureBuilder.build] to create the new texture. The required properties for a dma-buf texture are * The width and height in pixels * The `fourcc` code and `modifier` which identify the format and memory layout of the dma-buf * The file descriptor, offset and stride for each of the planes `GdkDmabufTextureBuilder` can be used for quick one-shot construction of textures as well as kept around and reused to construct multiple textures. For further information, see * The Linux kernel [documentation](https://docs.kernel.org/driver-api/dma-buf.html) * The header file [drm_fourcc.h](https://gitlab.freedesktop.org/mesa/drm/-/blob/main/include/drm/drm_fourcc.h) Creates a new texture builder. the new `GdkTextureBuilder` Builds a new `GdkTexture` with the values set up in the builder. It is a programming error to call this function if any mandatory property has not been set. Not all formats defined in the `drm_fourcc.h` header are supported. You can use [method@Gdk.Display.get_dmabuf_formats] to get a list of supported formats. If the format is not supported by GTK, %NULL will be returned and @error will be set. The `destroy` function gets called when the returned texture gets released. It is the responsibility of the caller to keep the file descriptors for the planes open until the created texture is no longer used, and close them afterwards (possibly using the @destroy notify). It is possible to call this function multiple times to create multiple textures, possibly with changing properties in between. a newly built `GdkTexture` or `NULL` if the format is not supported a `GdkDmabufTextureBuilder` destroy function to be called when the texture is released user data to pass to the destroy function Gets the color state previously set via gdk_dmabuf_texture_builder_set_color_state(). the color state a `GdkDmabufTextureBuilder` Returns the display that this texture builder is associated with. the display a `GdkDmabufTextureBuilder Gets the file descriptor for a plane. the file descriptor a `GdkDmabufTextureBuilder` the plane to get the fd for Gets the format previously set via gdk_dmabuf_texture_builder_set_fourcc() or 0 if the format wasn't set. The format is specified as a fourcc code. The format a `GdkDmabufTextureBuilder` Gets the height previously set via gdk_dmabuf_texture_builder_set_height() or 0 if the height wasn't set. The height a `GdkDmabufTextureBuilder` Gets the modifier value. the modifier a `GdkDmabufTextureBuilder` Gets the number of planes. The number of planes a `GdkDmabufTextureBuilder` Gets the offset value for a plane. the offset a `GdkDmabufTextureBuilder` the plane to get the offset for Whether the data is premultiplied. whether the data is premultiplied a `GdkDmabufTextureBuilder` Gets the stride value for a plane. the stride a `GdkDmabufTextureBuilder` the plane to get the stride for Gets the region previously set via gdk_dmabuf_texture_builder_set_update_region() or %NULL if none was set. The region a `GdkDmabufTextureBuilder` Gets the texture previously set via gdk_dmabuf_texture_builder_set_update_texture() or %NULL if none was set. The texture a `GdkDmabufTextureBuilder` Gets the width previously set via gdk_dmabuf_texture_builder_set_width() or 0 if the width wasn't set. The width a `GdkDmabufTextureBuilder` Sets the color state for the texture. By default, the colorstate is `NULL`. In that case, GTK will choose the correct colorstate based on the format. If you don't know what colorstates are, this is probably the right thing. a `GdkDmabufTextureBuilder` a `GdkColorState` or `NULL` to unset the colorstate. Sets the display that this texture builder is associated with. The display is used to determine the supported dma-buf formats. a `GdkDmabufTextureBuilder the display Sets the file descriptor for a plane. a `GdkDmabufTextureBuilder` the plane to set the fd for the file descriptor Sets the format of the texture. The format is specified as a fourcc code. The format must be set before calling [method@Gdk.DmabufTextureBuilder.build]. a `GdkDmabufTextureBuilder` the texture's format or 0 to unset Sets the height of the texture. The height must be set before calling [method@Gdk.DmabufTextureBuilder.build]. a `GdkDmabufTextureBuilder` the texture's height or 0 to unset Sets the modifier. a `GdkDmabufTextureBuilder` the modifier value Sets the number of planes of the texture. a `GdkDmabufTextureBuilder` the number of planes Sets the offset for a plane. a `GdkDmabufTextureBuilder` the plane to set the offset for the offset value Sets whether the data is premultiplied. Unless otherwise specified, all formats including alpha channels are assumed to be premultiplied. a `GdkDmabufTextureBuilder` whether the data is premultiplied Sets the stride for a plane. The stride must be set for all planes before calling [method@Gdk.DmabufTextureBuilder.build]. a `GdkDmabufTextureBuilder` the plane to set the stride for the stride value Sets the region to be updated by this texture. Together with [property@Gdk.DmabufTextureBuilder:update-texture] this describes an update of a previous texture. When rendering animations of large textures, it is possible that consecutive textures are only updating contents in parts of the texture. It is then possible to describe this update via these two properties, so that GTK can avoid rerendering parts that did not change. An example would be a screen recording where only the mouse pointer moves. a `GdkDmabufTextureBuilder` the region to update Sets the texture to be updated by this texture. See [method@Gdk.DmabufTextureBuilder.set_update_region] for an explanation. a `GdkDmabufTextureBuilder` the texture to update Sets the width of the texture. The width must be set before calling [method@Gdk.DmabufTextureBuilder.build]. a `GdkDmabufTextureBuilder` The texture's width or 0 to unset The color state of the texture. The display that this texture will be used on. The format of the texture, as a fourcc value. The height of the texture. The modifier. The number of planes of the texture. Note that you can set properties for other planes, but they will be ignored when constructing the texture. Whether the alpha channel is premultiplied into the others. Only relevant if the format has alpha. The update region for [property@Gdk.DmabufTextureBuilder:update-texture]. The texture [property@Gdk.DmabufTextureBuilder:update-region] is an update for. The width of the texture. Represents the source of an ongoing DND operation. A `GdkDrag` is created when a drag is started, and stays alive for duration of the DND operation. After a drag has been started with [func@Gdk.Drag.begin], the caller gets informed about the status of the ongoing drag operation with signals on the `GdkDrag` object. GTK provides a higher level abstraction based on top of these functions, and so they are not normally needed in GTK applications. See the "Drag and Drop" section of the GTK documentation for more information. Starts a drag and creates a new drag context for it. This function is called by the drag source. After this call, you probably want to set up the drag icon using the surface returned by [method@Gdk.Drag.get_drag_surface]. This function returns a reference to the [class@Gdk.Drag] object, but GTK keeps its own reference as well, as long as the DND operation is going on. Note: if @actions include %GDK_ACTION_MOVE, you need to listen for the [signal@Gdk.Drag::dnd-finished] signal and delete the data at the source if [method@Gdk.Drag.get_selected_action] returns %GDK_ACTION_MOVE. a newly created `GdkDrag` the source surface for this drag the device that controls this drag the offered content the actions supported by this drag the x offset to @device's position where the drag nominally started the y offset to @device's position where the drag nominally started Informs GDK that the drop ended. Passing %FALSE for @success may trigger a drag cancellation animation. This function is called by the drag source, and should be the last call before dropping the reference to the @drag. The `GdkDrag` will only take the first [method@Gdk.Drag.drop_done] call as effective, if this function is called multiple times, all subsequent calls will be ignored. a `GdkDrag` whether the drag was ultimatively successful Determines the bitmask of possible actions proposed by the source. the `GdkDragAction` flags a `GdkDrag` Returns the `GdkContentProvider` associated to the `GdkDrag` object. The `GdkContentProvider` associated to @drag. a `GdkDrag` Returns the `GdkDevice` associated to the `GdkDrag` object. The `GdkDevice` associated to @drag. a `GdkDrag` Gets the `GdkDisplay` that the drag object was created for. a `GdkDisplay` a `GdkDrag` Returns the surface on which the drag icon should be rendered during the drag operation. Note that the surface may not be available until the drag operation has begun. GDK will move the surface in accordance with the ongoing drag operation. The surface is owned by @drag and will be destroyed when the drag operation is over. the drag surface a `GdkDrag` Retrieves the formats supported by this `GdkDrag` object. a `GdkContentFormats` a `GdkDrag` Determines the action chosen by the drag destination. a `GdkDragAction` value a `GdkDrag` Returns the `GdkSurface` where the drag originates. The `GdkSurface` where the drag originates a `GdkDrag` Sets the position of the drag surface that will be kept under the cursor hotspot. Initially, the hotspot is at the top left corner of the drag surface. a `GdkDrag` x coordinate of the drag surface hotspot y coordinate of the drag surface hotspot The possible actions of this drag. The `GdkContentProvider`. The `GdkDevice` that is performing the drag. The `GdkDisplay` that the drag belongs to. The possible formats that the drag can provide its data in. The currently selected action of the drag. The surface where the drag originates. Emitted when the drag operation is cancelled. The reason the drag was cancelled Emitted when the destination side has finished reading all data. The drag object can now free all miscellaneous data. Emitted when the drop operation is performed on an accepting client. Used in `GdkDrop` and `GdkDrag` to indicate the actions that the destination can and should do with the dropped data. No action. Copy the data. Move the data, i.e. first copy it, then delete it from the source using the DELETE target of the X selection protocol. Add a link to the data. Note that this is only useful if source and destination agree on what it means, and is not supported on all platforms. Ask the user what to do with the data. Checks if @action represents a single action or includes multiple actions. When @action is `GDK_ACTION_NONE` - ie no action was given, `TRUE` is returned. %TRUE if exactly one action was given a `GdkDragAction` Used in `GdkDrag` to the reason of a cancelled DND operation. There is no suitable drop target. Drag cancelled by the user Unspecified error. A surface that is used during DND. Present @drag_surface. %FALSE if it failed to be presented, otherwise %TRUE. the `GdkDragSurface` to show the unconstrained drag_surface width to layout the unconstrained drag_surface height to layout Emitted when the size for the surface needs to be computed, when it is present. This signal will normally be emitted during the native surface layout cycle when the surface size needs to be recomputed. It is the responsibility of the drag surface user to handle this signal and compute the desired size of the surface, storing the computed size in the [struct@Gdk.DragSurfaceSize] object that is passed to the signal handler, using [method@Gdk.DragSurfaceSize.set_size]. Failing to set a size so will result in an arbitrary size being used as a result. the size of the drag surface The `GdkDragSurfaceInterface` implementation is private to GDK. Contains information that is useful to compute the size of a drag surface. Sets the size the drag surface prefers to be resized to. a `GdkDragSurfaceSize` the width the height Base class for objects implementing different rendering methods. `GdkDrawContext` is the base object used by contexts implementing different rendering methods, such as [class@Gdk.CairoContext] or [class@Gdk.GLContext]. It provides shared functionality between those contexts. You will always interact with one of those subclasses. A `GdkDrawContext` is always associated with a single toplevel surface. Indicates that you are beginning the process of redrawing @region on the @context's surface. Calling this function begins a drawing operation using @context on the surface that @context was created from. The actual requirements and guarantees for the drawing operation vary for different implementations of drawing, so a [class@Gdk.CairoContext] and a [class@Gdk.GLContext] need to be treated differently. A call to this function is a requirement for drawing and must be followed by a call to [method@Gdk.DrawContext.end_frame], which will complete the drawing operation and ensure the contents become visible on screen. Note that the @region passed to this function is the minimum region that needs to be drawn and depending on implementation, windowing system and hardware in use, it might be necessary to draw a larger region. Drawing implementation must use [method@Gdk.DrawContext.get_frame_region] to query the region that must be drawn. When using GTK, the widget system automatically places calls to gdk_draw_context_begin_frame() and gdk_draw_context_end_frame() via the use of [GskRenderer](../gsk4/class.Renderer.html)s, so application code does not need to call these functions explicitly. Drawing directly to the surface is no longer recommended. Use `GskRenderNode` and `GskRenderer`. the `GdkDrawContext` used to draw the frame. The context must have a surface. minimum region that should be drawn Ends a drawing operation started with gdk_draw_context_begin_frame(). This makes the drawing available on screen. See [method@Gdk.DrawContext.begin_frame] for more details about drawing. When using a [class@Gdk.GLContext], this function may call `glFlush()` implicitly before returning; it is not recommended to call `glFlush()` explicitly before calling this function. Drawing directly to the surface is no longer recommended. Use `GskRenderNode` and `GskRenderer`. a `GdkDrawContext` Retrieves the `GdkDisplay` the @context is created for the `GdkDisplay` a `GdkDrawContext` Retrieves the region that is currently being repainted. After a call to [method@Gdk.DrawContext.begin_frame] this function will return a union of the region passed to that function and the area of the surface that the @context determined needs to be repainted. If @context is not in between calls to [method@Gdk.DrawContext.begin_frame] and [method@Gdk.DrawContext.end_frame], %NULL will be returned. Drawing directly to the surface is no longer recommended. Use `GskRenderNode` and `GskRenderer`. a Cairo region a `GdkDrawContext` Retrieves the surface that @context is bound to. a `GdkSurface` a `GdkDrawContext` Returns %TRUE if @context is in the process of drawing to its surface. This is the case between calls to [method@Gdk.DrawContext.begin_frame] and [method@Gdk.DrawContext.end_frame]. In this situation, drawing commands may be effecting the contents of the @context's surface. Drawing directly to the surface is no longer recommended. Use `GskRenderNode` and `GskRenderer`. %TRUE if the context is between [method@Gdk.DrawContext.begin_frame] and [method@Gdk.DrawContext.end_frame] calls. a `GdkDrawContext` The `GdkDisplay` used to create the `GdkDrawContext`. The `GdkSurface` the context is bound to. Represents the target of an ongoing DND operation. Possible drop sites get informed about the status of the ongoing drag operation with events of type `GDK_DRAG_ENTER`, `GDK_DRAG_LEAVE`, `GDK_DRAG_MOTION` and `GDK_DROP_START`. The `GdkDrop` object can be obtained from these [class@Gdk.Event] types using [method@Gdk.DNDEvent.get_drop]. The actual data transfer is initiated from the target side via an async read, using one of the `GdkDrop` methods for this purpose: [method@Gdk.Drop.read_async] or [method@Gdk.Drop.read_value_async]. GTK provides a higher level abstraction based on top of these functions, and so they are not normally needed in GTK applications. See the "Drag and Drop" section of the GTK documentation for more information. Ends the drag operation after a drop. The @action must be a single action selected from the actions available via [method@Gdk.Drop.get_actions]. a `GdkDrop` the action performed by the destination or `GDK_ACTION_NONE` if the drop failed Returns the possible actions for this `GdkDrop`. If this value contains multiple actions - i.e. [func@Gdk.DragAction.is_unique] returns false for the result - [method@Gdk.Drop.finish] must choose the action to use when accepting the drop. This will only happen if you passed `GDK_ACTION_ASK` as one of the possible actions in [method@Gdk.Drop.status]. `GDK_ACTION_ASK` itself will not be included in the actions returned by this function. This value may change over the lifetime of the [class@Gdk.Drop] both as a response to source side actions as well as to calls to [method@Gdk.Drop.status] or [method@Gdk.Drop.finish]. The source side will not change this value anymore once a drop has started. The possible `GdkDragActions` a `GdkDrop` Returns the `GdkDevice` performing the drop. The `GdkDevice` performing the drop. a `GdkDrop` Gets the `GdkDisplay` that @self was created for. a `GdkDisplay` a `GdkDrop` If this is an in-app drag-and-drop operation, returns the `GdkDrag` that corresponds to this drop. If it is not, `NULL` is returned. the corresponding `GdkDrag` a `GdkDrop` Returns the `GdkContentFormats` that the drop offers the data to be read in. The possible `GdkContentFormats` a `GdkDrop` Returns the `GdkSurface` performing the drop. The `GdkSurface` performing the drop. a `GdkDrop` Asynchronously read the dropped data from a `GdkDrop` in a format that complies with one of the mime types. a `GdkDrop` pointer to an array of mime types the I/O priority for the read operation optional `GCancellable` object a `GAsyncReadyCallback` to call when the request is satisfied the data to pass to @callback Finishes an async drop read operation. Note that you must not use blocking read calls on the returned stream in the GTK thread, since some platforms might require communication with GTK to complete the data transfer. You can use async APIs such as g_input_stream_read_bytes_async(). See [method@Gdk.Drop.read_async]. the `GInputStream` a `GdkDrop` a `GAsyncResult` return location for the used mime type Asynchronously request the drag operation's contents converted to the given @type. For local drag-and-drop operations that are available in the given `GType`, the value will be copied directly. Otherwise, GDK will try to use [func@Gdk.content_deserialize_async] to convert the data. a `GdkDrop` a `GType` to read the I/O priority of the request. optional `GCancellable` object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function Finishes an async drop read. See [method@Gdk.Drop.read_value_async]. a `GValue` containing the result. a `GdkDrop` a `GAsyncResult` Selects all actions that are potentially supported by the destination. When calling this function, do not restrict the passed in actions to the ones provided by [method@Gdk.Drop.get_actions]. Those actions may change in the future, even depending on the actions you provide here. The @preferred action is a hint to the drag-and-drop mechanism about which action to use when multiple actions are possible. This function should be called by drag destinations in response to `GDK_DRAG_ENTER` or `GDK_DRAG_MOTION` events. If the destination does not yet know the exact actions it supports, it should set any possible actions first and then later call this function again. a `GdkDrop` Supported actions of the destination, or `GDK_ACTION_NONE` to indicate that a drop will not be accepted A unique action that's a member of @actions indicating the preferred action The possible actions for this drop The `GdkDevice` performing the drop The `GdkDisplay` that the drop belongs to. The `GdkDrag` that initiated this drop The possible formats that the drop can provide its data in. The `GdkSurface` the drop happens on Use this macro as the return value for continuing the propagation of an event handler. Use this macro as the return value for stopping the propagation of an event handler. Represents windowing system events. In GTK applications the events are handled automatically by toplevel widgets and passed on to the event controllers of appropriate widgets, so using `GdkEvent` and its related API is rarely needed. `GdkEvent` structs are immutable. Returns the relative angle from @event1 to @event2. The relative angle is the angle between the X axis and the line through both events' positions. The rotation direction for positive angles is from the positive X axis towards the positive Y axis. This assumes that both events have X/Y information. If not, this function returns %FALSE. %TRUE if the angle could be calculated. first `GdkEvent` second `GdkEvent` return location for the relative angle between both events Returns the point halfway between the events' positions. This assumes that both events have X/Y information. If not, this function returns %FALSE. %TRUE if the center could be calculated. first `GdkEvent` second `GdkEvent` return location for the X coordinate of the center return location for the Y coordinate of the center Returns the distance between the event locations. This assumes that both events have X/Y information. If not, this function returns %FALSE. %TRUE if the distance could be calculated. first `GdkEvent` second `GdkEvent` return location for the distance Extracts all axis values from an event. To find out which axes are used, use [method@Gdk.DeviceTool.get_axes] on the device tool returned by [method@Gdk.Event.get_device_tool]. %TRUE on success, otherwise %FALSE a `GdkEvent` the array of values for all axes the length of array Extract the axis value for a particular axis use from an event structure. To find out which axes are used, use [method@Gdk.DeviceTool.get_axes] on the device tool returned by [method@Gdk.Event.get_device_tool]. %TRUE if the specified axis was found, otherwise %FALSE a `GdkEvent` the axis use to look for location to store the value found Returns the device of an event. a `GdkDevice` a `GdkEvent`. Returns a `GdkDeviceTool` representing the tool that caused the event. If the was not generated by a device that supports different tools (such as a tablet), this function will return %NULL. Note: the `GdkDeviceTool` will be constant during the application lifetime, if settings must be stored persistently across runs, see [method@Gdk.DeviceTool.get_serial]. The current device tool a `GdkEvent` Retrieves the display associated to the @event. a `GdkDisplay` a `GdkEvent` Returns the event sequence to which the event belongs. Related touch events are connected in a sequence. Other events typically don't have event sequence information. the event sequence that the event belongs to a `GdkEvent` Retrieves the type of the event. a `GdkEvent`Type a `GdkEvent` Retrieves the history of the device that @event is for, as a list of time and coordinates. The history includes positions that are not delivered as separate events to the application because they occurred in the same frame as @event. Note that only motion and scroll events record history, and motion events do it only if one of the mouse buttons is down, or the device has a tool. an array of time and coordinates a motion or scroll event Return location for the length of the returned array Returns the modifier state field of an event. the modifier state of @event a `GdkEvent` Returns whether this event is an 'emulated' pointer event. Emulated pointer events typically originate from a touch events. %TRUE if this event is emulated a `GdkEvent` Extract the event surface relative x/y coordinates from an event. This position is in [surface coordinates](coordinates.html). whether the positions were set a `GdkEvent` location to put event surface x coordinate location to put event surface y coordinate Returns the seat that originated the event. a `GdkSeat`. a `GdkEvent` Extracts the surface associated with an event. The `GdkSurface` associated with the event a `GdkEvent` Returns the timestamp of @event. Not all events have timestamps. In that case, this function returns %GDK_CURRENT_TIME. timestamp field from @event a `GdkEvent` Increase the ref count of @event. @event a `GdkEvent` Returns whether a `GdkEvent` should trigger a context menu, according to platform conventions. The right mouse button typically triggers context menus. On macOS, Control+left mouse button also triggers. This function should always be used instead of simply checking for ```c event->button == GDK_BUTTON_SECONDARY ``` %TRUE if the event should trigger a context menu. a `GdkEvent`, currently only button events are meaningful values Decrease the ref count of @event. If the last reference is dropped, the structure is freed. a `GdkEvent` An opaque type representing a sequence of related events. Specifies the type of the event. the window manager has requested that the toplevel surface be hidden or destroyed, usually when the user clicks on a special icon in the title bar. the pointer (usually a mouse) has moved. a mouse button has been pressed. a mouse button has been released. a key has been pressed. a key has been released. the pointer has entered the surface. the pointer has left the surface. the keyboard focus has entered or left the surface. an input device has moved into contact with a sensing surface (e.g. a touchscreen or graphics tablet). an input device has moved out of contact with a sensing surface. the mouse has entered the surface while a drag is in progress. the mouse has left the surface while a drag is in progress. the mouse has moved in the surface while a drag is in progress. a drop operation onto the surface has started. the scroll wheel was turned a pointer or keyboard grab was broken. A new touch event sequence has just started. A touch event sequence has been updated. A touch event sequence has finished. A touch event sequence has been canceled. A touchpad swipe gesture event, the current state is determined by its phase field. A touchpad pinch gesture event, the current state is determined by its phase field. A tablet pad button press event. A tablet pad button release event. A tablet pad axis event from a "ring". A tablet pad axis event from a "strip". A tablet pad group mode change. A touchpad hold gesture event, the current state is determined by its phase field. A tablet pad axis event from a "dial". marks the end of the GdkEventType enumeration. An opaque type representing a list of files. Creates a new `GdkFileList` for the given array of files. This function is meant to be used by language bindings. the newly create files list the files to add to the list the number of files in the array Creates a new files list container from a singly linked list of `GFile` instances. This function is meant to be used by language bindings the newly created files list a list of files Retrieves the list of files inside a `GdkFileList`. This function is meant for language bindings. the files inside the list the file list An event related to a keyboard focus change. Extracts whether this event is about focus entering or leaving the surface. %TRUE of the focus is entering a focus change event Tells the application when to update and repaint a surface. This may be synced to the vertical refresh rate of the monitor, for example. Even when the frame clock uses a simple timer rather than a hardware-based vertical sync, the frame clock helps because it ensures everything paints at the same time (reducing the total number of frames). The frame clock can also automatically stop painting when it knows the frames will not be visible, or scale back animation framerates. `GdkFrameClock` is designed to be compatible with an OpenGL-based implementation or with mozRequestAnimationFrame in Firefox, for example. A frame clock is idle until someone requests a frame with [method@Gdk.FrameClock.request_phase]. At some later point that makes sense for the synchronization being implemented, the clock will process a frame and emit signals for each phase that has been requested. (See the signals of the `GdkFrameClock` class for documentation of the phases. %GDK_FRAME_CLOCK_PHASE_UPDATE and the [signal@Gdk.FrameClock::update] signal are most interesting for application writers, and are used to update the animations, using the frame time given by [method@Gdk.FrameClock.get_frame_time]. The frame time is reported in microseconds and generally in the same timescale as g_get_monotonic_time(), however, it is not the same as g_get_monotonic_time(). The frame time does not advance during the time a frame is being painted, and outside of a frame, an attempt is made so that all calls to [method@Gdk.FrameClock.get_frame_time] that are called at a “similar” time get the same value. This means that if different animations are timed by looking at the difference in time between an initial value from [method@Gdk.FrameClock.get_frame_time] and the value inside the [signal@Gdk.FrameClock::update] signal of the clock, they will stay exactly synchronized. Starts updates for an animation. Until a matching call to [method@Gdk.FrameClock.end_updating] is made, the frame clock will continually request a new frame with the %GDK_FRAME_CLOCK_PHASE_UPDATE phase. This function may be called multiple times and frames will be requested until gdk_frame_clock_end_updating() is called the same number of times. a `GdkFrameClock` Stops updates for an animation. See the documentation for [method@Gdk.FrameClock.begin_updating]. a `GdkFrameClock` Gets the frame timings for the current frame. the `GdkFrameTimings` for the frame currently being processed, or even no frame is being processed, for the previous frame. Before any frames have been processed, returns %NULL. a `GdkFrameClock` Calculates the current frames-per-second, based on the frame timings of @frame_clock. the current fps, as a `double` a `GdkFrameClock` `GdkFrameClock` maintains a 64-bit counter that increments for each frame drawn. inside frame processing, the value of the frame counter for the current frame. Outside of frame processing, the frame counter for the last frame. a `GdkFrameClock` Gets the time that should currently be used for animations. Inside the processing of a frame, it’s the time used to compute the animation position of everything in a frame. Outside of a frame, it's the time of the conceptual “previous frame,” which may be either the actual previous frame time, or if that’s too old, an updated time. a timestamp in microseconds, in the timescale of of g_get_monotonic_time(). a `GdkFrameClock` Returns the frame counter for the oldest frame available in history. `GdkFrameClock` internally keeps a history of `GdkFrameTimings` objects for recent frames that can be retrieved with [method@Gdk.FrameClock.get_timings]. The set of stored frames is the set from the counter values given by [method@Gdk.FrameClock.get_history_start] and [method@Gdk.FrameClock.get_frame_counter], inclusive. the frame counter value for the oldest frame that is available in the internal frame history of the `GdkFrameClock` a `GdkFrameClock` Predicts a presentation time, based on history. Using the frame history stored in the frame clock, finds the last known presentation time and refresh interval, and assuming that presentation times are separated by the refresh interval, predicts a presentation time that is a multiple of the refresh interval after the last presentation time, and later than @base_time. a `GdkFrameClock` base time for determining a presentaton time a location to store the determined refresh interval, or %NULL. A default refresh interval of 1/60th of a second will be stored if no history is present. a location to store the next candidate presentation time after the given base time. 0 will be will be stored if no history is present. Retrieves a `GdkFrameTimings` object holding timing information for the current frame or a recent frame. The `GdkFrameTimings` object may not yet be complete: see [method@Gdk.FrameTimings.get_complete] and [method@Gdk.FrameClock.get_history_start]. the `GdkFrameTimings` object for the specified frame, or %NULL if it is not available a `GdkFrameClock` the frame counter value identifying the frame to be received Asks the frame clock to run a particular phase. The signal corresponding the requested phase will be emitted the next time the frame clock processes. Multiple calls to gdk_frame_clock_request_phase() will be combined together and only one frame processed. If you are displaying animated content and want to continually request the %GDK_FRAME_CLOCK_PHASE_UPDATE phase for a period of time, you should use [method@Gdk.FrameClock.begin_updating] instead, since this allows GTK to adjust system parameters to get maximally smooth animations. a `GdkFrameClock` the phase that is requested This signal ends processing of the frame. Applications should generally not handle this signal. Begins processing of the frame. Applications should generally not handle this signal. Used to flush pending motion events that are being batched up and compressed together. Applications should not handle this signal. Emitted as the second step of toolkit and application processing of the frame. Any work to update sizes and positions of application elements should be performed. GTK normally handles this internally. Emitted as the third step of toolkit and application processing of the frame. The frame is repainted. GDK normally handles this internally and emits [signal@Gdk.Surface::render] signals which are turned into [GtkWidget::snapshot](../gtk4/signal.Widget.snapshot.html) signals by GTK. Emitted after processing of the frame is finished. This signal is handled internally by GTK to resume normal event processing. Applications should not handle this signal. Emitted as the first step of toolkit and application processing of the frame. Animations should be updated using [method@Gdk.FrameClock.get_frame_time]. Applications can connect directly to this signal, or use [gtk_widget_add_tick_callback()](../gtk4/method.Widget.add_tick_callback.html) as a more convenient interface. Used to represent the different paint clock phases that can be requested. The elements of the enumeration correspond to the signals of `GdkFrameClock`. no phase corresponds to GdkFrameClock::flush-events. Should not be handled by applications. corresponds to GdkFrameClock::before-paint. Should not be handled by applications. corresponds to GdkFrameClock::update. corresponds to GdkFrameClock::layout. Should not be handled by applications. corresponds to GdkFrameClock::paint. corresponds to GdkFrameClock::resume-events. Should not be handled by applications. corresponds to GdkFrameClock::after-paint. Should not be handled by applications. Holds timing information for a single frame of the application’s displays. To retrieve `GdkFrameTimings` objects, use [method@Gdk.FrameClock.get_timings] or [method@Gdk.FrameClock.get_current_timings]. The information in `GdkFrameTimings` is useful for precise synchronization of video with the event or audio streams, and for measuring quality metrics for the application’s display, such as latency and jitter. Returns whether @timings are complete. The timing information in a `GdkFrameTimings` is filled in incrementally as the frame as drawn and passed off to the window system for processing and display to the user. The accessor functions for `GdkFrameTimings` can return 0 to indicate an unavailable value for two reasons: either because the information is not yet available, or because it isn't available at all. Once this function returns %TRUE for a frame, you can be certain that no further values will become available and be stored in the `GdkFrameTimings`. %TRUE if all information that will be available for the frame has been filled in. a `GdkFrameTimings` Gets the frame counter value of the `GdkFrameClock` when this frame was drawn. the frame counter value for this frame a `GdkFrameTimings` Returns the frame time for the frame. This is the time value that is typically used to time animations for the frame. See [method@Gdk.FrameClock.get_frame_time]. the frame time for the frame, in the timescale of g_get_monotonic_time() A `GdkFrameTimings` Gets the predicted time at which this frame will be displayed. Although no predicted time may be available, if one is available, it will be available while the frame is being generated, in contrast to [method@Gdk.FrameTimings.get_presentation_time], which is only available after the frame has been presented. In general, if you are simply animating, you should use [method@Gdk.FrameClock.get_frame_time] rather than this function, but this function is useful for applications that want exact control over latency. For example, a movie player may want this information for Audio/Video synchronization. The predicted time at which the frame will be presented, in the timescale of g_get_monotonic_time(), or 0 if no predicted presentation time is available. a `GdkFrameTimings` Reurns the presentation time. This is the time at which the frame became visible to the user. the time the frame was displayed to the user, in the timescale of g_get_monotonic_time(), or 0 if no presentation time is available. See [method@Gdk.FrameTimings.get_complete] a `GdkFrameTimings` Gets the natural interval between presentation times for the display that this frame was displayed on. Frame presentation usually happens during the “vertical blanking interval”. the refresh interval of the display, in microseconds, or 0 if the refresh interval is not available. See [method@Gdk.FrameTimings.get_complete]. a `GdkFrameTimings` Increases the reference count of @timings. @timings a `GdkFrameTimings` Decreases the reference count of @timings. If @timings is no longer referenced, it will be freed. a `GdkFrameTimings` Indicates which monitor a surface should span over when in fullscreen mode. Fullscreen on current monitor only. Span across all monitors when fullscreen. The list of the different APIs that GdkGLContext can potentially support. The OpenGL API The OpenGL ES API Represents a platform-specific OpenGL draw context. `GdkGLContext`s are created for a surface using [method@Gdk.Surface.create_gl_context], and the context will match the characteristics of the surface. A `GdkGLContext` is not tied to any particular normal framebuffer. For instance, it cannot draw to the surface back buffer. The GDK repaint system is in full control of the painting to that. Instead, you can create render buffers or textures and use [func@cairo_draw_from_gl] in the draw function of your widget to draw them. Then GDK will handle the integration of your rendering with that of other widgets. Support for `GdkGLContext` is platform-specific and context creation can fail, returning %NULL context. A `GdkGLContext` has to be made "current" in order to start using it, otherwise any OpenGL call will be ignored. ## Creating a new OpenGL context In order to create a new `GdkGLContext` instance you need a `GdkSurface`, which you typically get during the realize call of a widget. A `GdkGLContext` is not realized until either [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize] is called. It is possible to specify details of the GL context like the OpenGL version to be used, or whether the GL context should have extra state validation enabled after calling [method@Gdk.Surface.create_gl_context] by calling [method@Gdk.GLContext.realize]. If the realization fails you have the option to change the settings of the `GdkGLContext` and try again. ## Using a GdkGLContext You will need to make the `GdkGLContext` the current context before issuing OpenGL calls; the system sends OpenGL commands to whichever context is current. It is possible to have multiple contexts, so you always need to ensure that the one which you want to draw with is the current one before issuing commands: ```c gdk_gl_context_make_current (context); ``` You can now perform your drawing using OpenGL commands. You can check which `GdkGLContext` is the current one by using [func@Gdk.GLContext.get_current]; you can also unset any `GdkGLContext` that is currently set by calling [func@Gdk.GLContext.clear_current]. Clears the current `GdkGLContext`. Any OpenGL call after this function returns will be ignored until [method@Gdk.GLContext.make_current] is called. Retrieves the current `GdkGLContext`. the current `GdkGLContext` Gets the allowed APIs set via gdk_gl_context_set_allowed_apis(). the allowed APIs a GL context Gets the API currently in use. If the renderer has not been realized yet, 0 is returned. the currently used API a GL context Retrieves whether the context is doing extra validations and runtime checking. See [method@Gdk.GLContext.set_debug_enabled]. %TRUE if debugging is enabled a `GdkGLContext` Retrieves the display the @context is created for a `GdkDisplay` a `GdkGLContext` Retrieves whether the context is forward-compatible. See [method@Gdk.GLContext.set_forward_compatible]. %TRUE if the context should be forward-compatible a `GdkGLContext` Retrieves required OpenGL version set as a requirement for the @context realization. It will not change even if a greater OpenGL version is supported and used after the @context is realized. See [method@Gdk.GLContext.get_version] for the real version in use. See [method@Gdk.GLContext.set_required_version]. a `GdkGLContext` return location for the major version to request return location for the minor version to request Used to retrieves the `GdkGLContext` that this @context share data with. As many contexts can share data now and no single shared context exists anymore, this function has been deprecated and now always returns %NULL. Use [method@Gdk.GLContext.is_shared] to check if contexts can be shared. %NULL a `GdkGLContext` Retrieves the surface used by the @context. a `GdkSurface` a `GdkGLContext` Checks whether the @context is using an OpenGL or OpenGL ES profile. %TRUE if the `GdkGLContext` is using an OpenGL ES profile; %FALSE if other profile is in use of if the @context has not yet been realized. a `GdkGLContext` Retrieves the OpenGL version of the @context. The @context must be realized prior to calling this function. a `GdkGLContext` return location for the major version return location for the minor version Whether the `GdkGLContext` is in legacy mode or not. The `GdkGLContext` must be realized before calling this function. When realizing a GL context, GDK will try to use the OpenGL 3.2 core profile; this profile removes all the OpenGL API that was deprecated prior to the 3.2 version of the specification. If the realization is successful, this function will return %FALSE. If the underlying OpenGL implementation does not support core profiles, GDK will fall back to a pre-3.2 compatibility profile, and this function will return %TRUE. You can use the value returned by this function to decide which kind of OpenGL API to use, or whether to do extension discovery, or what kind of shader programs to load. %TRUE if the GL context is in legacy mode a `GdkGLContext` Checks if the two GL contexts can share resources. When they can, the texture IDs from @other can be used in @self. This is particularly useful when passing `GdkGLTexture` objects between different contexts. Contexts created for the same display with the same properties will always be compatible, even if they are created for different surfaces. For other contexts it depends on the GL backend. Both contexts must be realized for this check to succeed. If either one is not, this function will return %FALSE. %TRUE if the two GL contexts are compatible. a `GdkGLContext` the `GdkGLContext` that should be compatible with @self Makes the @context the current one. a `GdkGLContext` Realizes the given `GdkGLContext`. It is safe to call this function on a realized `GdkGLContext`. %TRUE if the context is realized a `GdkGLContext` Sets the allowed APIs. When gdk_gl_context_realize() is called, only the allowed APIs will be tried. If you set this to 0, realizing will always fail. If you set it on a realized context, the property will not have any effect. It is only relevant during gdk_gl_context_realize(). By default, all APIs are allowed. a GL context the allowed APIs Sets whether the `GdkGLContext` should perform extra validations and runtime checking. This is useful during development, but has additional overhead. The `GdkGLContext` must not be realized or made current prior to calling this function. a `GdkGLContext` whether to enable debugging in the context Sets whether the `GdkGLContext` should be forward-compatible. Forward-compatible contexts must not support OpenGL functionality that has been marked as deprecated in the requested version; non-forward compatible contexts, on the other hand, must support both deprecated and non deprecated functionality. The `GdkGLContext` must not be realized or made current prior to calling this function. a `GdkGLContext` whether the context should be forward-compatible Sets the major and minor version of OpenGL to request. Setting @major and @minor to zero will use the default values. Setting @major and @minor lower than the minimum versions required by GTK will result in the context choosing the minimum version. The @context must not be realized or made current prior to calling this function. a `GdkGLContext` the major version to request the minor version to request Requests that GDK create an OpenGL ES context instead of an OpenGL one. Not all platforms support OpenGL ES. The @context must not have been realized. By default, GDK will attempt to automatically detect whether the underlying GL implementation is OpenGL or OpenGL ES once the @context is realized. You should check the return value of [method@Gdk.GLContext.get_use_es] after calling [method@Gdk.GLContext.realize] to decide whether to use the OpenGL or OpenGL ES API, extensions, or shaders. a `GdkGLContext` whether the context should use OpenGL ES instead of OpenGL, or -1 to allow auto-detection The allowed APIs. The API currently in use. Always %NULL As many contexts can share data now and no single shared context exists anymore, this function has been deprecated and now always returns %NULL. Use [method@Gdk.GLContext.is_shared] to check if contexts can be shared. Error enumeration for `GdkGLContext`. OpenGL support is not available The requested visual format is not supported The requested profile is not supported The shader compilation failed The shader linking failed Registers an error quark for [class@Gdk.GLContext] errors. the error quark A `GdkTexture` representing a GL texture object. Creates a new texture for an existing GL texture. Note that the GL texture must not be modified until @destroy is called, which will happen when the GdkTexture object is finalized, or due to an explicit call of [method@Gdk.GLTexture.release]. [class@Gdk.GLTextureBuilder] supersedes this function and provides extended functionality for creating GL textures. A newly-created `GdkTexture` a `GdkGLContext` the ID of a texture that was created with @context the nominal width of the texture the nominal height of the texture a destroy notify that will be called when the GL resources are released data that gets passed to @destroy Releases the GL resources held by a `GdkGLTexture`. The texture contents are still available via the [method@Gdk.Texture.download] function, after this function has been called. a `GdkTexture` wrapping a GL texture Constructs [class@Gdk.Texture] objects from GL textures. The operation is quite simple: Create a texture builder, set all the necessary properties - keep in mind that the properties [property@Gdk.GLTextureBuilder:context], [property@Gdk.GLTextureBuilder:id], [property@Gdk.GLTextureBuilder:width], and [property@Gdk.GLTextureBuilder:height] are mandatory - and then call [method@Gdk.GLTextureBuilder.build] to create the new texture. `GdkGLTextureBuilder` can be used for quick one-shot construction of textures as well as kept around and reused to construct multiple textures. Creates a new texture builder. the new `GdkTextureBuilder` Builds a new `GdkTexture` with the values set up in the builder. The `destroy` function gets called when the returned texture gets released; either when the texture is finalized or by an explicit call to [method@Gdk.GLTexture.release]. It should release all GL resources associated with the texture, such as the [property@Gdk.GLTextureBuilder:id] and the [property@Gdk.GLTextureBuilder:sync]. Note that it is a programming error to call this function if any mandatory property has not been set. It is possible to call this function multiple times to create multiple textures, possibly with changing properties in between. a newly built `GdkTexture` a `GdkGLTextureBuilder` destroy function to be called when the texture is released user data to pass to the destroy function Gets the color state previously set via gdk_gl_texture_builder_set_color_state(). the color state a `GdkGLTextureBuilder` Gets the context previously set via gdk_gl_texture_builder_set_context() or %NULL if none was set. The context a `GdkGLTextureBuilder` Gets the format previously set via gdk_gl_texture_builder_set_format(). The format a `GdkGLTextureBuilder` Gets whether the texture has a mipmap. Whether the texture has a mipmap a `GdkGLTextureBuilder` Gets the height previously set via gdk_gl_texture_builder_set_height() or 0 if the height wasn't set. The height a `GdkGLTextureBuilder` Gets the texture id previously set via gdk_gl_texture_builder_set_id() or 0 if the id wasn't set. The id a `GdkGLTextureBuilder` Gets the `GLsync` previously set via gdk_gl_texture_builder_set_sync(). the `GLSync` a `GdkGLTextureBuilder` Gets the region previously set via gdk_gl_texture_builder_set_update_region() or %NULL if none was set. The region a `GdkGLTextureBuilder` Gets the texture previously set via gdk_gl_texture_builder_set_update_texture() or %NULL if none was set. The texture a `GdkGLTextureBuilder` Gets the width previously set via gdk_gl_texture_builder_set_width() or 0 if the width wasn't set. The width a `GdkGLTextureBuilder` Sets the color state for the texture. By default, the sRGB colorstate is used. If you don't know what colorstates are, this is probably the right thing. a `GdkGLTextureBuilder` a `GdkColorState` Sets the context to be used for the texture. This is the context that owns the texture. The context must be set before calling [method@Gdk.GLTextureBuilder.build]. a `GdkGLTextureBuilder` The context the texture belongs to or %NULL to unset Sets the format of the texture. The default is `GDK_MEMORY_R8G8B8A8_PREMULTIPLIED`. The format is the preferred format the texture data should be downloaded to. The format must be supported by the GL version of [property@Gdk.GLTextureBuilder:context]. GDK's texture download code assumes that the format corresponds to the storage parameters of the GL texture in an obvious way. For example, a format of `GDK_MEMORY_R16G16B16A16_PREMULTIPLIED` is expected to be stored as `GL_RGBA16` texture, and `GDK_MEMORY_G8A8` is expected to be stored as `GL_RG8` texture. Setting the right format is particularly useful when using high bit depth textures to preserve the bit depth, to set the correct value for unpremultiplied textures and to make sure opaque textures are treated as such. Non-RGBA textures need to have swizzling parameters set up properly to be usable in GSK's shaders. a `GdkGLTextureBuilder` The texture's format Sets whether the texture has a mipmap. This allows the renderer and other users of the generated texture to use a higher quality downscaling. Typically, the `glGenerateMipmap` function is used to generate a mimap. a `GdkGLTextureBuilder` Whether the texture has a mipmap Sets the height of the texture. The height must be set before calling [method@Gdk.GLTextureBuilder.build]. a `GdkGLTextureBuilder` The texture's height or 0 to unset Sets the texture id of the texture. The texture id must remain unmodified until the texture was finalized. See [method@Gdk.GLTextureBuilder.build] for a longer discussion. The id must be set before calling [method@Gdk.GLTextureBuilder.build]. a `GdkGLTextureBuilder` The texture id to be used for creating the texture Sets the GLSync object to use for the texture. GTK will wait on this object before using the created `GdkTexture`. The `destroy` function that is passed to [method@Gdk.GLTextureBuilder.build] is responsible for freeing the sync object when it is no longer needed. The texture builder does not destroy it and it is the callers responsibility to make sure it doesn't leak. a `GdkGLTextureBuilder` the GLSync object Sets the region to be updated by this texture. Together with [property@Gdk.GLTextureBuilder:update-texture] this describes an update of a previous texture. When rendering animations of large textures, it is possible that consecutive textures are only updating contents in parts of the texture. It is then possible to describe this update via these two properties, so that GTK can avoid rerendering parts that did not change. An example would be a screen recording where only the mouse pointer moves. a `GdkGLTextureBuilder` the region to update Sets the texture to be updated by this texture. See [method@Gdk.GLTextureBuilder.set_update_region] for an explanation. a `GdkGLTextureBuilder` the texture to update Sets the width of the texture. The width must be set before calling [method@Gdk.GLTextureBuilder.build]. a `GdkGLTextureBuilder` The texture's width or 0 to unset The color state of the texture. The context owning the texture. The format when downloading the texture. If the texture has a mipmap. The height of the texture. The texture ID to use. An optional `GLSync` object. If this is set, GTK will wait on it before using the texture. The update region for [property@Gdk.GLTextureBuilder:update-texture]. The texture [property@Gdk.GLTextureBuilder:update-region] is an update for. The width of the texture. An event related to a broken windowing system grab. Extracts the grab surface from a grab broken event. the grab surface of @event a grab broken event Checks whether the grab broken event is for an implicit grab. %TRUE if the an implicit grab was broken a grab broken event Defines the reference point of a surface and is used in `GdkPopupLayout`. the reference point is at the top left corner. the reference point is in the middle of the top edge. the reference point is at the top right corner. the reference point is at the middle of the left edge. the reference point is at the center of the surface. the reference point is at the middle of the right edge. the reference point is at the lower left corner. the reference point is at the middle of the lower edge. the reference point is at the lower right corner. the reference point is at the top left corner of the surface itself, ignoring window manager decorations. An enumeration describing the type of an input device in general terms. the device is a mouse. (This will be reported for the core pointer, even if it is something else, such as a trackball.) the device is a stylus of a graphics tablet or similar device. the device is a keyboard. the device is a direct-input touch device, such as a touchscreen or tablet the device is an indirect touch device, such as a touchpad the device is a trackpoint the device is a "pad", a collection of buttons, rings and strips found in drawing tablets An event related to a key-based device. Extracts the consumed modifiers from a key event. the consumed modifiers or @event a key event Extracts the keycode from a key event. the keycode of @event a key event Extracts the keyval from a key event. the keyval of @event a key event Extracts the layout from a key event. the layout of @event a key event Extracts the shift level from a key event. the shift level of @event a key event Gets a keyval and modifier combination that will match the event. See [method@Gdk.KeyEvent.matches]. %TRUE on success a key `GdkEvent` return location for a keyval return location for modifiers Extracts whether the key event is for a modifier key. %TRUE if the @event is for a modifier key a key event Matches a key event against a keyval and modifiers. This is typically used to trigger keyboard shortcuts such as Ctrl-C. Partial matches are possible where the combination matches if the currently active group is ignored. Note that we ignore Caps Lock for matching. a `GdkKeyMatch` value describing whether @event matches a key `GdkEvent` the keyval to match the modifiers to match Describes how well an event matches a given keyval and modifiers. `GdkKeyMatch` values are returned by [method@Gdk.KeyEvent.matches]. The key event does not match The key event matches if keyboard state (specifically, the currently active group) is ignored The key event matches Represents a hardware key that can be mapped to a keyval. the hardware keycode. This is an identifying number for a physical key. indicates movement in a horizontal direction. Usually groups are used for two different languages. In group 0, a key might have two English characters, and in group 1 it might have two Hebrew characters. The Hebrew characters will be printed on the key next to the English characters. indicates which symbol on the key will be used, in a vertical direction. So on a standard US keyboard, the key with the number “1” on it also has the exclamation point ("!") character on it. The level indicates whether to use the “1” or the “!” symbol. The letter keys are considered to have a lowercase letter at level 0, and an uppercase letter at level 1, though only the uppercase letter is printed. A mask covering all entries in `GdkModifierType`. Describes formats that image data can have in memory. It describes formats by listing the contents of the memory passed to it. So `GDK_MEMORY_A8R8G8B8` will be 1 byte (8 bits) of alpha, followed by a byte each of red, green and blue. It is not endian-dependent, so `CAIRO_FORMAT_ARGB32` is represented by different `GdkMemoryFormats` on architectures with different endiannesses. Its naming is modelled after [VkFormat](https://www.khronos.org/registry/vulkan/specs/1.0/html/vkspec.html#VkFormat) for details). 4 bytes; for blue, green, red, alpha. The color values are premultiplied with the alpha value. 4 bytes; for alpha, red, green, blue. The color values are premultiplied with the alpha value. 4 bytes; for red, green, blue, alpha The color values are premultiplied with the alpha value. 4 bytes; for blue, green, red, alpha. 4 bytes; for alpha, red, green, blue. 4 bytes; for red, green, blue, alpha. 4 bytes; for alpha, blue, green, red. 3 bytes; for red, green, blue. The data is opaque. 3 bytes; for blue, green, red. The data is opaque. 3 guint16 values; for red, green, blue. 4 guint16 values; for red, green, blue, alpha. The color values are premultiplied with the alpha value. 4 guint16 values; for red, green, blue, alpha. 3 half-float values; for red, green, blue. The data is opaque. 4 half-float values; for red, green, blue and alpha. The color values are premultiplied with the alpha value. 4 half-float values; for red, green, blue and alpha. 3 float values; for red, green, blue. 4 float values; for red, green, blue and alpha. The color values are premultiplied with the alpha value. 4 float values; for red, green, blue and alpha. 2 bytes; for grayscale, alpha. The color values are premultiplied with the alpha value. 2 bytes; for grayscale, alpha. One byte; for grayscale. The data is opaque. 2 guint16 values; for grayscale, alpha. The color values are premultiplied with the alpha value. 2 guint16 values; for grayscale, alpha. One guint16 value; for grayscale. The data is opaque. One byte; for alpha. One guint16 value; for alpha. One half-float value; for alpha. One float value; for alpha. 4 bytes; for alpha, blue, green, red, The color values are premultiplied with the alpha value. 4 bytes; for blue, green, red, unused. 4 bytes; for unused, red, green, blue. 4 bytes; for red, green, blue, unused. 4 bytes; for unused, blue, green, red. Multiplane format with 2 planes. The first plane contains the first channel, usually containing luma values. The second plane with interleaved chroma values, Cb followed by Cr. Subsampled in both the X and Y direction. Commonly known by the fourcc "NV12". Multiplane format with 2 planes. The first plane contains the first channel, usually containing luma values. The second plane with interleaved chroma values, Cr followed by Cb. Subsampled in both the X and Y direction. Commonly known by the fourcc "NV21". Multiplane format with 2 planes. The first plane contains the first channel, usually containing luma values. The second plane with interleaved chroma values, Cb followed by Cr. Subsampled in the X direction. Commonly known by the fourcc "NV16". Multiplane format with 2 planes. The first plane contains the first channel, usually containing luma values. The second plane with interleaved chroma values, Cr followed by Cb. Subsampled in the X direction. Commonly known by the fourcc "NV61". Multiplane format with 2 planes. The first plane contains the first channel, usually containing luma values. The second plane with interleaved chroma values, Cb followed by Cr. This format is not subsampled. Commonly known by the fourcc "NV24". Multiplane format with 2 planes. The first plane contains the first channel, usually containing luma values. The second plane with interleaved chroma values, Cr followed by Cb. This format is not subsampled. Commonly known by the fourcc "NV42". Multiplane format with 2 planes. Each channel is a 16 bit integer, but only the highest 10 bits are used. The first plane contains the first channel, usually containing luma values. The second plane with interleaved chroma values, Cr followed by Cb. This format is not subsampled. Commonly known by the fourcc "P010". Multiplane format with 2 planes. Each channel is a 16 bit integer, but only the highest 10 bits are used. The first plane contains the first channel, usually containing luma values. The second plane with interleaved chroma values, Cr followed by Cb. This format is not subsampled. Commonly known by the fourcc "P012". Multiplane format with 2 planes. Each channel is a 16 bit integer. The first plane contains the first channel, usually containing luma values. The second plane with interleaved chroma values, Cr followed by Cb. This format is not subsampled. Commonly known by the fourcc "P016". Multiplane format with 3 planes. Each channel is a 8 bit integer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. Subsampled in both the X and Y direction with 4:1 ratio. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. Subsampled in both the X and Y direction with 4:1 ratio. It is mapped into the 1st channel. Commonly known by the fourcc "YUV410". Multiplane format with 3 planes. Each channel is a 8 bit integer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the second chroma chanel. Subsampled in both the X and Y direction with 4:1 ratio. It is mapped into the 1st channel. The third plane usually contains the first chroma channel. Subsampled in both the X and Y direction with 4:1 ratio. It is mapped into the 3rd channel. Commonly known by the fourcc "YVU410". Multiplane format with 3 planes. Each channel is a 8 bit integer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. Subsampled in the X direction with 4:1 ratio. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. Subsampled in the X direction with 4:1 ratio. It is mapped into the 1st channel. Commonly known by the fourcc "YUV411". Multiplane format with 3 planes. Each channel is a 8 bit integer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the second chroma chanel. Subsampled in the X direction with 4:1 ratio. It is mapped into the 1st channel. The third plane usually contains the first chroma channel. Subsampled in the X direction with 4:1 ratio. It is mapped into the 3rd channel. Commonly known by the fourcc "YVU411". Multiplane format with 3 planes. Each channel is a 8 bit integer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. Subsampled in both the X and Y direction. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. Subsampled in both the X and Y direction. It is mapped into the 1st channel. Commonly known by the fourcc "YUV420". Multiplane format with 3 planes. Each channel is a 8 bit integer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the second chroma chanel. Subsampled in both the X and Y direction. It is mapped into the 1st channel. The third plane usually contains the first chroma channel. Subsampled in both the X and Y direction. It is mapped into the 3rd channel. Commonly known by the fourcc "YVU420". Multiplane format with 3 planes. Each channel is a 8 bit integer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. Subsampled in the X direction. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. Subsampled in the X direction. It is mapped into the 1st channel. Commonly known by the fourcc "YUV422". Multiplane format with 3 planes. Each channel is a 8 bit integer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the second chroma chanel. Subsampled in the X direction. It is mapped into the 1st channel. The third plane usually contains the first chroma channel. Subsampled in the X direction. It is mapped into the 3rd channel. Commonly known by the fourcc "YVU422". Multiplane format with 3 planes. Each channel is a 8 bit integer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. It is mapped into the 1st channel. Commonly known by the fourcc "YUV444". Multiplane format with 3 planes. Each channel is a 8 bit integer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the second chroma chanel. Subsampled in the X direction. It is mapped into the 1st channel. The third plane usually contains the first chroma channel. Subsampled in the X direction. It is mapped into the 3rd channel. Commonly known by the fourcc "YVU444". Packed format with subsampled channels. Each channel is a 8 bit integer. The red and blue/chroma channels are subsampled and interleaved with the green/luma channel. Each block contains 2 pixels, so the width must be a multiple of 2. Commonly known by the fourcc "YUYV". Packed format with subsampled channels. Each channel is a 8 bit integer. The red and blue/chroma channels are subsampled and interleaved with the green/luma channel. Each block contains 2 pixels, so the width must be a multiple of 2. Commonly known by the fourcc "YVYU". Packed format with subsampled channels. Each channel is a 8 bit integer. The red and blue/chroma channels are subsampled and interleaved with the green/luma channel. Each block contains 2 pixels, so the width must be a multiple of 2. Commonly known by the fourcc "VYUY". Packed format with subsampled channels. Each channel is a 8 bit integer. The red and blue/chroma channels are subsampled and interleaved with the green/luma channel. Each block contains 2 pixels, so the width must be a multiple of 2. Commonly known by the fourcc "UYVY". Multiplane format with 3 planes. Each channel is a 16 bit integer. Only the 10 lower bits are used. The remaining ones must be set to 0 by the producer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. Subsampled in both the X and Y direction. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. Subsampled in both the X and Y direction. It is mapped into the 1st channel. Commonly known by the fourcc "S010". Multiplane format with 3 planes. Each channel is a 16 bit integer. Only the 10 lower bits are used. The remaining ones must be set to 0 by the producer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. Subsampled in the X direction. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. Subsampled in the X direction. It is mapped into the 1st channel. Commonly known by the fourcc "S210". Multiplane format with 3 planes. Each channel is a 16 bit integer. Only the 10 lower bits are used. The remaining ones must be set to 0 by the producer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. It is mapped into the 1st channel. Commonly known by the fourcc "S410". Multiplane format with 3 planes. Each channel is a 16 bit integer. Only the 12 lower bits are used. The remaining ones must be set to 0 by the producer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. Subsampled in both the X and Y direction. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. Subsampled in both the X and Y direction. It is mapped into the 1st channel. Commonly known by the fourcc "S012". Multiplane format with 3 planes. Each channel is a 16 bit integer. Only the 12 lower bits are used. The remaining ones must be set to 0 by the producer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. Subsampled in the X direction. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. Subsampled in the X direction. It is mapped into the 1st channel. Commonly known by the fourcc "S212". Multiplane format with 3 planes. Each channel is a 16 bit integer. Only the 12 lower bits are used. The remaining ones must be set to 0 by the producer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. It is mapped into the 1st channel. Commonly known by the fourcc "S412". Multiplane format with 3 planes. Each channel is a 16 bit integer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. Subsampled in both the X and Y direction. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. Subsampled in both the X and Y direction. It is mapped into the 1st channel. Commonly known by the fourcc "S016". Multiplane format with 3 planes. Each channel is a 16 bit integer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. Subsampled in the X direction. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. Subsampled in the X direction. It is mapped into the 1st channel. Commonly known by the fourcc "S216". Multiplane format with 3 planes. Each channel is a 16 bit integer. The first plane usually contains the luma channel. It is mapped into the 2nd channel. The second plane usually contains the first chroma chanel. It is mapped into the 3rd channel. The third plane usually contains the second chroma channel. It is mapped into the 1st channel. Commonly known by the fourcc "S416". The number of formats. This value will change as more formats get added, so do not rely on its concrete integer. A `GdkTexture` representing image data in memory. Creates a new texture for a blob of image data. The `GBytes` must contain @stride × @height pixels in the given format. A newly-created `GdkTexture` the width of the texture the height of the texture the format of the data the `GBytes` containing the pixel data rowstride for the data Constructs [class@Gdk.Texture] objects from system memory provided via [struct@GLib.Bytes]. The operation is quite simple: Create a texture builder, set all the necessary properties - keep in mind that the properties [property@Gdk.MemoryTextureBuilder:bytes], [property@Gdk.MemoryTextureBuilder:stride], [property@Gdk.MemoryTextureBuilder:width], and [property@Gdk.MemoryTextureBuilder:height] are mandatory - and then call [method@Gdk.MemoryTextureBuilder.build] to create the new texture. `GdkMemoryTextureBuilder` can be used for quick one-shot construction of textures as well as kept around and reused to construct multiple textures. Creates a new texture builder. the new `GdkTextureBuilder` Builds a new `GdkTexture` with the values set up in the builder. Note that it is a programming error to call this function if any mandatory property has not been set. It is possible to call this function multiple times to create multiple textures, possibly with changing properties in between. a newly built `GdkTexture` a `GdkMemoryTextureBuilder` Gets the bytes previously set via gdk_memory_texture_builder_set_bytes() or %NULL if none was set. The bytes a `GdkMemoryTextureBuilder` Gets the colorstate previously set via gdk_memory_texture_builder_set_color_state(). The colorstate a `GdkMemoryTextureBuilder` Gets the format previously set via gdk_memory_texture_builder_set_format(). The format a `GdkMemoryTextureBuilder` Gets the height previously set via gdk_memory_texture_builder_set_height() or 0 if the height wasn't set. The height a `GdkMemoryTextureBuilder` Gets the offset previously set via gdk_memory_texture_builder_set_offset(). The offset associated to a @plane a `GdkMemoryTextureBuilder` a plane Gets the stride previously set via gdk_memory_texture_builder_set_stride(). the stride a `GdkMemoryTextureBuilder` Gets the stride previously set via gdk_memory_texture_builder_set_stride_for_plane(). The stride associated to a @plane a `GdkMemoryTextureBuilder` a plane Gets the region previously set via gdk_memory_texture_builder_set_update_region() or %NULL if none was set. The update region a `GdkMemoryTextureBuilder` Gets the texture previously set via gdk_memory_texture_builder_set_update_texture() or %NULL if none was set. The update texture a `GdkMemoryTextureBuilder` Gets the width previously set via gdk_memory_texture_builder_set_width() or 0 if the width wasn't set. The width a `GdkMemoryTextureBuilder` Sets the data to be shown but the texture. The bytes must be set before calling [method@Gdk.MemoryTextureBuilder.build]. a `GdkMemoryTextureBuilder` The bytes the texture shows or %NULL to unset Sets the colorstate describing the data. By default, the sRGB colorstate is used. If you don't know what colorstates are, this is probably the right thing. a `GdkMemoryTextureBuilder` The colorstate describing the data Sets the format of the bytes. The default is `GDK_MEMORY_R8G8B8A8_PREMULTIPLIED`. a `GdkMemoryTextureBuilder` The texture's format Sets the height of the texture. The height must be set before calling [method@Gdk.MemoryTextureBuilder.build] and conform to size requirements of the provided format. a `GdkMemoryTextureBuilder` The texture's height or 0 to unset Sets the offset of the texture for @plane. a `GdkMemoryTextureBuilder` a plane the texture's offset for @plane Sets the rowstride of the bytes used. The rowstride must be set before calling [method@Gdk.MemoryTextureBuilder.build]. a `GdkMemoryTextureBuilder` the stride or 0 to unset Sets the stride of the texture for @plane. a `GdkMemoryTextureBuilder` a plane the texture's stride for @plane Sets the region to be updated by this texture. Together with [property@Gdk.MemoryTextureBuilder:update-texture], this describes an update of a previous texture. When rendering animations of large textures, it is possible that consecutive textures are only updating contents in parts of the texture. It is then possible to describe this update via these two properties, so that GTK can avoid rerendering parts that did not change. An example would be a screen recording where only the mouse pointer moves. a `GdkMemoryTextureBuilder` the region to update Sets the texture to be updated by this texture. See [method@Gdk.MemoryTextureBuilder.set_update_region] for an explanation. a `GdkMemoryTextureBuilder` the texture to update Sets the width of the texture. The width must be set before calling [method@Gdk.MemoryTextureBuilder.build] and conform to size requirements of the provided format. a `GdkMemoryTextureBuilder` The texture's width or 0 to unset The bytes holding the data. The colorstate describing the data. The format of the data. The height of the texture. The rowstride of the texture. The rowstride is the number of bytes between the first pixel in a row of image data, and the first pixel in the next row. The update region for [property@Gdk.MemoryTextureBuilder:update-texture]. The texture [property@Gdk.MemoryTextureBuilder:update-region] is an update for. The width of the texture. Flags to indicate the state of modifier keys and mouse buttons in events. Typical modifier keys are Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock or ShiftLock. Note that GDK may add internal values to events which include values outside of this enumeration. Your code should preserve and ignore them. You can use %GDK_MODIFIER_MASK to remove all private values. No modifier. the Shift key. a Lock key (depending on the Windowing System configuration, this may either be <kbd>CapsLock</kbd> or <kbd>ShiftLock</kbd>). the Control key. the fourth modifier key (it depends on the Windowing System configuration which key is interpreted as this modifier, but normally it is the <kbd>Alt</kbd> key). the first mouse button. the second mouse button. the third mouse button. the fourth mouse button. the fifth mouse button. the Super modifier. the Hyper modifier. the Meta modifier. Maps to Command on macOS. Represents the individual outputs that are associated with a `GdkDisplay`. `GdkDisplay` keeps a `GListModel` to enumerate and monitor monitors with [method@Gdk.Display.get_monitors]. You can use [method@Gdk.Display.get_monitor_at_surface] to find a particular monitor. Gets the name of the monitor's connector, if available. These are strings such as "eDP-1", or "HDMI-2". They depend on software and hardware configuration, and should not be relied on as stable identifiers of a specific monitor. the name of the connector a `GdkMonitor` Gets a string describing the monitor, if available. This can be used to identify a monitor in the UI. the monitor description a `GdkMonitor` Gets the display that this monitor belongs to. the display a `GdkMonitor` Retrieves the size and position of the monitor within the display coordinate space. The returned geometry is in ”application pixels”, not in ”device pixels” (see [method@Gdk.Monitor.get_scale]). a `GdkMonitor` a `GdkRectangle` to be filled with the monitor geometry Gets the height in millimeters of the monitor. the physical height of the monitor a `GdkMonitor` Gets the name or PNP ID of the monitor's manufacturer. Note that this value might also vary depending on actual display backend. The PNP ID registry is located at [https://uefi.org/pnp_id_list](https://uefi.org/pnp_id_list). the name of the manufacturer a `GdkMonitor` Gets the string identifying the monitor model, if available. the monitor model a `GdkMonitor` Gets the refresh rate of the monitor, if available. The value is in milli-Hertz, so a refresh rate of 60Hz is returned as 60000. the refresh rate in milli-Hertz, or 0 a `GdkMonitor` Gets the internal scale factor that maps from monitor coordinates to device pixels. This can be used if you want to create pixel based data for a particular monitor, but most of the time you’re drawing to a surface where it is better to use [method@Gdk.Surface.get_scale] instead. the scale a `GdkMonitor` Gets the internal scale factor that maps from monitor coordinates to device pixels. On traditional systems this is 1, but on very high density outputs it can be a higher value (often 2). This can be used if you want to create pixel based data for a particular monitor, but most of the time you’re drawing to a surface where it is better to use [method@Gdk.Surface.get_scale_factor] instead. the scale factor a `GdkMonitor` Gets information about the layout of red, green and blue primaries for pixels. the subpixel layout a `GdkMonitor` Gets the width in millimeters of the monitor. the physical width of the monitor a `GdkMonitor` Returns %TRUE if the @monitor object corresponds to a physical monitor. The @monitor becomes invalid when the physical monitor is unplugged or removed. %TRUE if the object corresponds to a physical monitor a `GdkMonitor` The connector name. A short description of the monitor, meant for display to the user. The `GdkDisplay` of the monitor. The geometry of the monitor. The height of the monitor, in millimeters. The manufacturer name. The model name. The refresh rate, in milli-Hertz. The scale of the monitor. The scale factor. The scale factor is the next larger integer, compared to [property@Gdk.Surface:scale]. The subpixel layout. Whether the object is still valid. The width of the monitor, in millimeters. Emitted when the output represented by @monitor gets disconnected. An event related to a pointer or touch device motion. Specifies the kind of crossing for enter and leave events. See the X11 protocol specification of LeaveNotify for full details of crossing event generation. the surface is entered from an ancestor or left towards an ancestor. the pointer moves between an ancestor and an inferior of the surface. the surface is entered from an inferior or left towards an inferior. the surface is entered from or left towards a surface which is neither an ancestor nor an inferior. the pointer moves between two surfaces which are not ancestors of each other and the surface is part of the ancestor chain between one of these surfaces and their least common ancestor. an unknown type of enter/leave event occurred. This is the priority that the idle handler processing surface updates is given in the main loop. An event related to a pad-based device. Extracts the information from a pad strip or ring event. a pad strip or ring event Return location for the axis index Return location for the axis value Extracts information about the pressed button from a pad event. the button of @event a pad button event Extracts group and mode information from a pad event. a pad event return location for the group return location for the mode An interface for content that can be painted. The content of a `GdkPaintable` can be painted anywhere at any size without requiring any sort of layout. The interface is inspired by similar concepts elsewhere, such as [ClutterContent](https://developer.gnome.org/clutter/stable/ClutterContent.html), [HTML/CSS Paint Sources](https://www.w3.org/TR/css-images-4/#paint-source), or [SVG Paint Servers](https://www.w3.org/TR/SVG2/pservers.html). A `GdkPaintable` can be snapshot at any time and size using [method@Gdk.Paintable.snapshot]. How the paintable interprets that size and if it scales or centers itself into the given rectangle is implementation defined, though if you are implementing a `GdkPaintable` and don't know what to do, it is suggested that you scale your paintable ignoring any potential aspect ratio. The contents that a `GdkPaintable` produces may depend on the [class@Gdk.Snapshot] passed to it. For example, paintables may decide to use more detailed images on higher resolution screens or when OpenGL is available. A `GdkPaintable` will however always produce the same output for the same snapshot. A `GdkPaintable` may change its contents, meaning that it will now produce a different output with the same snapshot. Once that happens, it will call [method@Gdk.Paintable.invalidate_contents] which will emit the [signal@Gdk.Paintable::invalidate-contents] signal. If a paintable is known to never change its contents, it will set the %GDK_PAINTABLE_STATIC_CONTENTS flag. If a consumer cannot deal with changing contents, it may call [method@Gdk.Paintable.get_current_image] which will return a static paintable and use that. A paintable can report an intrinsic (or preferred) size or aspect ratio it wishes to be rendered at, though it doesn't have to. Consumers of the interface can use this information to layout thepaintable appropriately. Just like the contents, the size of a paintable can change. A paintable will indicate this by calling [method@Gdk.Paintable.invalidate_size] which will emit the [signal@Gdk.Paintable::invalidate-size] signal. And just like for contents, if a paintable is known to never change its size, it will set the %GDK_PAINTABLE_STATIC_SIZE flag. Besides API for applications, there are some functions that are only useful for implementing subclasses and should not be used by applications: [method@Gdk.Paintable.invalidate_contents], [method@Gdk.Paintable.invalidate_size], [func@Gdk.Paintable.new_empty]. Returns a paintable that has the given intrinsic size and draws nothing. This is often useful for implementing the [vfunc@Gdk.Paintable.get_current_image] virtual function when the paintable is in an incomplete state (like a [GtkMediaStream](../gtk4/class.MediaStream.html) before receiving the first frame). a `GdkPaintable` The intrinsic width to report. Can be 0 for no width. The intrinsic height to report. Can be 0 for no height. Gets an immutable paintable for the current contents displayed by @paintable. This is useful when you want to retain the current state of an animation, for example to take a screenshot of a running animation. If the @paintable is already immutable, it will return itself. An immutable paintable for the current contents of @paintable a `GdkPaintable` Get flags for the paintable. This is oftentimes useful for optimizations. See [flags@Gdk.PaintableFlags] for the flags and what they mean. The `GdkPaintableFlags` for this paintable a `GdkPaintable` Gets the preferred aspect ratio the @paintable would like to be displayed at. The aspect ratio is the width divided by the height, so a value of 0.5 means that the @paintable prefers to be displayed twice as high as it is wide. Consumers of this interface can use this to preserve aspect ratio when displaying the paintable. This is a purely informational value and does not in any way limit the values that may be passed to [method@Gdk.Paintable.snapshot]. Usually when a @paintable returns nonzero values from [method@Gdk.Paintable.get_intrinsic_width] and [method@Gdk.Paintable.get_intrinsic_height] the aspect ratio should conform to those values, though that is not required. If the @paintable does not have a preferred aspect ratio, it returns 0. Negative values are never returned. the intrinsic aspect ratio of @paintable or 0 if none. a `GdkPaintable` Gets the preferred height the @paintable would like to be displayed at. Consumers of this interface can use this to reserve enough space to draw the paintable. This is a purely informational value and does not in any way limit the values that may be passed to [method@Gdk.Paintable.snapshot]. If the @paintable does not have a preferred height, it returns 0. Negative values are never returned. the intrinsic height of @paintable or 0 if none. a `GdkPaintable` Gets the preferred width the @paintable would like to be displayed at. Consumers of this interface can use this to reserve enough space to draw the paintable. This is a purely informational value and does not in any way limit the values that may be passed to [method@Gdk.Paintable.snapshot]. If the @paintable does not have a preferred width, it returns 0. Negative values are never returned. the intrinsic width of @paintable or 0 if none. a `GdkPaintable` Snapshots the given paintable with the given @width and @height. The paintable is drawn at the current (0,0) offset of the @snapshot. If @width and @height are not larger than zero, this function will do nothing. a `GdkPaintable` a `GdkSnapshot` to snapshot to width to snapshot in height to snapshot in Compute a concrete size for the `GdkPaintable`. Applies the sizing algorithm outlined in the [CSS Image spec](https://drafts.csswg.org/css-images-3/#default-sizing) to the given @paintable. See that link for more details. It is not necessary to call this function when both @specified_width and @specified_height are known, but it is useful to call this function in GtkWidget:measure implementations to compute the other dimension when only one dimension is given. a `GdkPaintable` the width @paintable could be drawn into or 0.0 if unknown the height @paintable could be drawn into or 0.0 if unknown the width @paintable would be drawn into if no other constraints were given the height @paintable would be drawn into if no other constraints were given will be set to the concrete width computed will be set to the concrete height computed Gets an immutable paintable for the current contents displayed by @paintable. This is useful when you want to retain the current state of an animation, for example to take a screenshot of a running animation. If the @paintable is already immutable, it will return itself. An immutable paintable for the current contents of @paintable a `GdkPaintable` Get flags for the paintable. This is oftentimes useful for optimizations. See [flags@Gdk.PaintableFlags] for the flags and what they mean. The `GdkPaintableFlags` for this paintable a `GdkPaintable` Gets the preferred aspect ratio the @paintable would like to be displayed at. The aspect ratio is the width divided by the height, so a value of 0.5 means that the @paintable prefers to be displayed twice as high as it is wide. Consumers of this interface can use this to preserve aspect ratio when displaying the paintable. This is a purely informational value and does not in any way limit the values that may be passed to [method@Gdk.Paintable.snapshot]. Usually when a @paintable returns nonzero values from [method@Gdk.Paintable.get_intrinsic_width] and [method@Gdk.Paintable.get_intrinsic_height] the aspect ratio should conform to those values, though that is not required. If the @paintable does not have a preferred aspect ratio, it returns 0. Negative values are never returned. the intrinsic aspect ratio of @paintable or 0 if none. a `GdkPaintable` Gets the preferred height the @paintable would like to be displayed at. Consumers of this interface can use this to reserve enough space to draw the paintable. This is a purely informational value and does not in any way limit the values that may be passed to [method@Gdk.Paintable.snapshot]. If the @paintable does not have a preferred height, it returns 0. Negative values are never returned. the intrinsic height of @paintable or 0 if none. a `GdkPaintable` Gets the preferred width the @paintable would like to be displayed at. Consumers of this interface can use this to reserve enough space to draw the paintable. This is a purely informational value and does not in any way limit the values that may be passed to [method@Gdk.Paintable.snapshot]. If the @paintable does not have a preferred width, it returns 0. Negative values are never returned. the intrinsic width of @paintable or 0 if none. a `GdkPaintable` Called by implementations of `GdkPaintable` to invalidate their contents. Unless the contents are invalidated, implementations must guarantee that multiple calls of [method@Gdk.Paintable.snapshot] produce the same output. This function will emit the [signal@Gdk.Paintable::invalidate-contents] signal. If a @paintable reports the %GDK_PAINTABLE_STATIC_CONTENTS flag, it must not call this function. a `GdkPaintable` Called by implementations of `GdkPaintable` to invalidate their size. As long as the size is not invalidated, @paintable must return the same values for its intrinsic width, height and aspect ratio. This function will emit the [signal@Gdk.Paintable::invalidate-size] signal. If a @paintable reports the %GDK_PAINTABLE_STATIC_SIZE flag, it must not call this function. a `GdkPaintable` Snapshots the given paintable with the given @width and @height. The paintable is drawn at the current (0,0) offset of the @snapshot. If @width and @height are not larger than zero, this function will do nothing. a `GdkPaintable` a `GdkSnapshot` to snapshot to width to snapshot in height to snapshot in Emitted when the contents of the @paintable change. Examples for such an event would be videos changing to the next frame or the icon theme for an icon changing. Emitted when the intrinsic size of the @paintable changes. This means the values reported by at least one of [method@Gdk.Paintable.get_intrinsic_width], [method@Gdk.Paintable.get_intrinsic_height] or [method@Gdk.Paintable.get_intrinsic_aspect_ratio] has changed. Examples for such an event would be a paintable displaying the contents of a toplevel surface being resized. Flags about a paintable object. Implementations use these for optimizations such as caching. The size is immutable. The [signal@Gdk.Paintable::invalidate-size] signal will never be emitted. The content is immutable. The [signal@Gdk.Paintable::invalidate-contents] signal will never be emitted. The list of functions that can be implemented for the `GdkPaintable` interface. Note that apart from the [vfunc@Gdk.Paintable.snapshot] function, no virtual function of this interface is mandatory to implement, though it is a good idea to implement [vfunc@Gdk.Paintable.get_current_image] for non-static paintables and [vfunc@Gdk.Paintable.get_flags] if the image is not dynamic as the default implementation returns no flags and that will make the implementation likely quite slow. Snapshot the paintable. The given @width and @height are guaranteed to be larger than 0.0. The resulting snapshot must modify only the area in the rectangle from (0,0) to (width, height). This is the only function that must be implemented for this interface. a `GdkPaintable` a `GdkSnapshot` to snapshot to width to snapshot in height to snapshot in return a `GdkPaintable` that does not change over time. This means the `GDK_PAINTABLE_STATIC_SIZE` and `GDK_PAINTABLE_STATIC_CONTENTS` flag are set. An immutable paintable for the current contents of @paintable a `GdkPaintable` Get the flags for this instance. See [flags@Gdk.PaintableFlags] for details. The `GdkPaintableFlags` for this paintable a `GdkPaintable` The preferred width for this object to be snapshot at or 0 if none. This is purely a hint. The object must still be able to render at any size. the intrinsic width of @paintable or 0 if none. a `GdkPaintable` The preferred height for this object to be snapshot at or 0 if none. This is purely a hint. The object must still be able to render at any size. the intrinsic height of @paintable or 0 if none. a `GdkPaintable` The preferred aspect ratio for this object or 0 if none. If both [vfunc@Gdk.Paintable.get_intrinsic_width] and [vfunc@Gdk.Paintable.get_intrinsic_height] return non-zero values, this function should return the aspect ratio computed from those. the intrinsic aspect ratio of @paintable or 0 if none. a `GdkPaintable` A surface that is attached to another surface. The `GdkPopup` is positioned relative to its parent surface. `GdkPopup`s are typically used to implement menus and similar popups. They can be modal, which is indicated by the [property@Gdk.Popup:autohide] property. Returns whether this popup is set to hide on outside clicks. %TRUE if @popup will autohide a `GdkPopup` Returns the parent surface of a popup. the parent surface a `GdkPopup` Obtains the position of the popup relative to its parent. the X coordinate of @popup position a `GdkPopup` Obtains the position of the popup relative to its parent. the Y coordinate of @popup position a `GdkPopup` Gets the current popup rectangle anchor. The value returned may change after calling [method@Gdk.Popup.present], or after the [signal@Gdk.Surface::layout] signal is emitted. the current rectangle anchor value of @popup a `GdkPopup` Gets the current popup surface anchor. The value returned may change after calling [method@Gdk.Popup.present], or after the [signal@Gdk.Surface::layout] signal is emitted. the current surface anchor value of @popup a `GdkPopup` Present @popup after having processed the `GdkPopupLayout` rules. If the popup was previously not showing, it will be shown, otherwise it will change position according to @layout. After calling this function, the result should be handled in response to the [signal@Gdk.Surface::layout] signal being emitted. The resulting popup position can be queried using [method@Gdk.Popup.get_position_x], [method@Gdk.Popup.get_position_y], and the resulting size will be sent as parameters in the layout signal. Use [method@Gdk.Popup.get_rect_anchor] and [method@Gdk.Popup.get_surface_anchor] to get the resulting anchors. Presenting may fail, for example if the @popup is set to autohide and is immediately hidden upon being presented. If presenting failed, the [signal@Gdk.Surface::layout] signal will not me emitted. %FALSE if it failed to be presented, otherwise %TRUE. the `GdkPopup` to show the unconstrained popup width to layout the unconstrained popup height to layout the `GdkPopupLayout` object used to layout Whether to hide on outside clicks. The parent surface. Contains information that is necessary position a [iface@Gdk.Popup] relative to its parent. The positioning requires a negotiation with the windowing system, since it depends on external constraints, such as the position of the parent surface, and the screen dimensions. The basic ingredients are a rectangle on the parent surface, and the anchor on both that rectangle and the popup. The anchors specify a side or corner to place next to each other. ![Popup anchors](popup-anchors.png) For cases where placing the anchors next to each other would make the popup extend offscreen, the layout includes some hints for how to resolve this problem. The hints may suggest to flip the anchor position to the other side, or to 'slide' the popup along a side, or to resize it. ![Flipping popups](popup-flip.png) ![Sliding popups](popup-slide.png) These hints may be combined. Ultimatively, it is up to the windowing system to determine the position and size of the popup. You can learn about the result by calling [method@Gdk.Popup.get_position_x], [method@Gdk.Popup.get_position_y], [method@Gdk.Popup.get_rect_anchor] and [method@Gdk.Popup.get_surface_anchor] after the popup has been presented. This can be used to adjust the rendering. For example, [GtkPopover](../gtk4/class.Popover.html) changes its arrow position accordingly. But you have to be careful avoid changing the size of the popover, or it has to be presented again. Create a popup layout description. Used together with [method@Gdk.Popup.present] to describe how a popup surface should be placed and behave on-screen. @anchor_rect is relative to the top-left corner of the surface's parent. @rect_anchor and @surface_anchor determine anchor points on @anchor_rect and surface to pin together. The position of @anchor_rect's anchor point can optionally be offset using [method@Gdk.PopupLayout.set_offset], which is equivalent to offsetting the position of surface. newly created instance of `GdkPopupLayout` the anchor rectangle to align @surface with the point on @anchor_rect to align with @surface's anchor point the point on @surface to align with @rect's anchor point Makes a copy of @layout. a copy of @layout. a popup layout Check whether @layout and @other has identical layout properties. true if @layout and @other have identical layout properties, otherwise false. a popup layout another popup layout Get the anchor hints. the anchor hints a popup layout Get the anchor rectangle. The anchor rectangle a popup layout Retrieves the offset for the anchor rectangle. a popup layout return location for the delta X coordinate return location for the delta Y coordinate Returns the anchor position on the anchor rectangle. the anchor on the anchor rectangle. a popup layout Obtains the shadow widths of this layout. a popup layout return location for the left shadow width return location for the right shadow width return location for the top shadow width return location for the bottom shadow width Returns the anchor position on the popup surface. the anchor on the popup surface. a popup layout Increases the reference count of @value. the same @layout a popup layout Set new anchor hints. The set @anchor_hints determines how @surface will be moved if the anchor points cause it to move off-screen. For example, `GDK_ANCHOR_FLIP_X` will replace `GDK_GRAVITY_NORTH_WEST` with `GDK_GRAVITY_NORTH_EAST` and vice versa if @surface extends beyond the left or right edges of the monitor. a popup layout the new anchor hints Set the anchor rectangle. a popup layout the new anchor rectangle Offset the position of the anchor rectangle with the given delta. a popup layout x delta to offset the anchor rectangle with y delta to offset the anchor rectangle with Set the anchor on the anchor rectangle. a popup layout the new rect anchor Sets the shadow width of the popup. The shadow width corresponds to the part of the computed surface size that would consist of the shadow margin surrounding the window, would there be any. a popup layout width of the left part of the shadow width of the right part of the shadow height of the top part of the shadow height of the bottom part of the shadow Set the anchor on the popup surface. a popup layout the new popup surface anchor Decreases the reference count of @value. a popup layout An event related to the proximity of a tool to a device. Represents a color, in a way that is compatible with cairo’s notion of color. `GdkRGBA` is a convenient way to pass colors around. It’s based on cairo’s way to deal with colors and mirrors its behavior. All values are in the range from 0.0 to 1.0 inclusive. So the color (0.0, 0.0, 0.0, 0.0) represents transparent black and (1.0, 1.0, 1.0, 1.0) is opaque white. Other values will be clamped to this range when drawing. The intensity of the red channel from 0.0 to 1.0 inclusive The intensity of the green channel from 0.0 to 1.0 inclusive The intensity of the blue channel from 0.0 to 1.0 inclusive The opacity of the color from 0.0 for completely translucent to 1.0 for opaque Makes a copy of a `GdkRGBA`. The result must be freed through [method@Gdk.RGBA.free]. A newly allocated `GdkRGBA`, with the same contents as @rgba a `GdkRGBA` Compares two `GdkRGBA` colors. %TRUE if the two colors compare equal a `GdkRGBA` another `GdkRGBA` Frees a `GdkRGBA`. a `GdkRGBA` A hash function suitable for using for a hash table that stores `GdkRGBA`s. The hash value for @p a `GdkRGBA` Checks if an @rgba value is transparent. That is, drawing with the value would not produce any change. %TRUE if the @rgba is clear a `GdkRGBA` Checks if an @rgba value is opaque. That is, drawing with the value will not retain any results from previous contents. %TRUE if the @rgba is opaque a `GdkRGBA` Parses a textual representation of a color. The string can be either one of: - A standard name (Taken from the CSS specification). - A hexadecimal value in the form “\#rgb”, “\#rrggbb”, “\#rrrgggbbb” or ”\#rrrrggggbbbb” - A hexadecimal value in the form “\#rgba”, “\#rrggbbaa”, or ”\#rrrrggggbbbbaaaa” - A RGB color in the form “rgb(r,g,b)” (In this case the color will have full opacity) - A RGBA color in the form “rgba(r,g,b,a)” - A HSL color in the form “hsl(h,s,l)” - A HSLA color in the form “hsla(h,s,l,a)” Where “r”, “g”, “b” and “a” are respectively the red, green, blue and alpha color values. In the last two cases, “r”, “g”, and “b” are either integers in the range 0 to 255 or percentage values in the range 0% to 100%, and a is a floating point value in the range 0 to 1. The range for “h” is 0 to 360, and “s”, “l” can be either numbers in the range 0 to 100 or percentages. %TRUE if the parsing succeeded the `GdkRGBA` to fill in the string specifying the color Returns a textual specification of @rgba in the form `rgb(r,g,b)` or `rgba(r,g,b,a)`, where “r”, “g”, “b” and “a” represent the red, green, blue and alpha values respectively. “r”, “g”, and “b” are represented as integers in the range 0 to 255, and “a” is represented as a floating point value in the range 0 to 1. These string forms are string forms that are supported by the CSS3 colors module, and can be parsed by [method@Gdk.RGBA.parse]. Note that this string representation may lose some precision, since “r”, “g” and “b” are represented as 8-bit integers. If this is a concern, you should use a different representation. A newly allocated text string a `GdkRGBA` Represents a rectangle. `GdkRectangle` is identical to `cairo_rectangle_t`. Together with Cairo’s `cairo_region_t` data type, these are the central types for representing sets of pixels. The intersection of two rectangles can be computed with [method@Gdk.Rectangle.intersect]; to find the union of two rectangles use [method@Gdk.Rectangle.union]. The `cairo_region_t` type provided by Cairo is usually used for managing non-rectangular clipping of graphical operations. The Graphene library has a number of other data types for regions and volumes in 2D and 3D. the x coordinate of the top left corner the y coordinate of the top left corner the width of the rectangle the height of the rectangle Returns %TRUE if @rect contains the point described by @x and @y. %TRUE if @rect contains the point a `GdkRectangle` X coordinate Y coordinate Checks if the two given rectangles are equal. %TRUE if the rectangles are equal. a `GdkRectangle` a `GdkRectangle` Calculates the intersection of two rectangles. It is allowed for @dest to be the same as either @src1 or @src2. If the rectangles do not intersect, @dest’s width and height is set to 0 and its x and y values are undefined. If you are only interested in whether the rectangles intersect, but not in the intersecting area itself, pass %NULL for @dest. %TRUE if the rectangles intersect. a `GdkRectangle` a `GdkRectangle` return location for the intersection of @src1 and @src2 Calculates the union of two rectangles. The union of rectangles @src1 and @src2 is the smallest rectangle which includes both @src1 and @src2 within it. It is allowed for @dest to be the same as either @src1 or @src2. Note that this function does not ignore 'empty' rectangles (ie. with zero width or height). a `GdkRectangle` a `GdkRectangle` return location for the union of @src1 and @src2 Specifies the direction for scroll events. the surface is scrolled up. the surface is scrolled down. the surface is scrolled to the left. the surface is scrolled to the right. the scrolling is determined by the delta values in scroll events. See gdk_scroll_event_get_deltas() An event related to a scrolling motion. Extracts the scroll deltas of a scroll event. The deltas will be zero unless the scroll direction is %GDK_SCROLL_SMOOTH. For the representation unit of these deltas, see [method@Gdk.ScrollEvent.get_unit]. a scroll event return location for x scroll delta return location for y scroll delta Extracts the direction of a scroll event. the scroll direction of @event a scroll event Extracts the scroll direction relative to the physical motion. the relative scroll direction. a relative scroll direction. Extracts the scroll delta unit of a scroll event. The unit will always be %GDK_SCROLL_UNIT_WHEEL if the scroll direction is not %GDK_SCROLL_SMOOTH. the scroll unit. a scroll event. Check whether a scroll event is a stop scroll event. Scroll sequences with smooth scroll information may provide a stop scroll event once the interaction with the device finishes, e.g. by lifting a finger. This stop scroll event is the signal that a widget may trigger kinetic scrolling based on the current velocity. Stop scroll events always have a delta of 0/0. %TRUE if the event is a scroll stop event a scroll event Used in scroll events, to announce the direction relative to physical motion. Physical motion and event motion are the same Physical motion is inverted relative to event motion Relative motion is unknown on this device or backend Specifies the unit of scroll deltas. When you get %GDK_SCROLL_UNIT_WHEEL, a delta of 1.0 means 1 wheel detent click in the south direction, 2.0 means 2 wheel detent clicks in the south direction... This is the same logic for negative values but in the north direction. If you get %GDK_SCROLL_UNIT_SURFACE, are managing a scrollable view and get a value of 123, you have to scroll 123 surface logical pixels right if it's @delta_x or down if it's @delta_y. This is the same logic for negative values but you have to scroll left instead of right if it's @delta_x and up instead of down if it's @delta_y. 1 surface logical pixel is equal to 1 real screen pixel multiplied by the final scale factor of your graphical interface (the product of the desktop scale factor and eventually a custom scale factor in your app). The delta is in number of wheel clicks. The delta is in surface pixels to scroll directly on screen. Represents a collection of input devices that belong to a user. Returns the capabilities this `GdkSeat` currently has. the seat capabilities a `GdkSeat` Returns the devices that match the given capabilities. A list of `GdkDevices`. The list must be freed with g_list_free(), the elements are owned by GTK and must not be freed. a `GdkSeat` capabilities to get devices for Returns the `GdkDisplay` this seat belongs to. a `GdkDisplay`. This object is owned by GTK and must not be freed. a `GdkSeat` Returns the device that routes keyboard events. a `GdkDevice` with keyboard capabilities. This object is owned by GTK and must not be freed. a `GdkSeat` Returns the device that routes pointer events. a `GdkDevice` with pointer capabilities. This object is owned by GTK and must not be freed. a `GdkSeat` Returns all `GdkDeviceTools` that are known to the application. A list of tools. Free with g_list_free(). a `GdkSeat` `GdkDisplay` of this seat. Emitted when a new input device is related to this seat. the newly added `GdkDevice`. Emitted when an input device is removed (e.g. unplugged). the just removed `GdkDevice`. Emitted whenever a new tool is made known to the seat. The tool may later be assigned to a device (i.e. on proximity with a tablet). The device will emit the [signal@Gdk.Device::tool-changed] signal accordingly. A same tool may be used by several devices. the new `GdkDeviceTool` known to the seat Emitted whenever a tool is no longer known to this @seat. the just removed `GdkDeviceTool` Flags describing the seat capabilities. No input capabilities The seat has a pointer (e.g. mouse) The seat has touchscreen(s) attached The seat has drawing tablet(s) attached The seat has keyboard(s) attached The seat has drawing tablet pad(s) attached The union of all pointing capabilities The union of all capabilities Base type for snapshot operations. The subclass of `GdkSnapshot` used by GTK is [GtkSnapshot](../gtk4/class.Snapshot.html). This enumeration describes how the red, green and blue components of physical pixels on an output device are laid out. The layout is not known Not organized in this way The layout is horizontal, the order is RGB The layout is horizontal, the order is BGR The layout is vertical, the order is RGB The layout is vertical, the order is BGR Represents a rectangular region on the screen. It’s a low-level object, used to implement high-level objects such as [GtkWindow](../gtk4/class.Window.html). The surfaces you see in practice are either [iface@Gdk.Toplevel] or [iface@Gdk.Popup], and those interfaces provide much of the required API to interact with these surfaces. Other, more specialized surface types exist, but you will rarely interact with them directly. Create a new popup surface. The surface will be attached to @parent and can be positioned relative to it using [method@Gdk.Popup.present]. a new `GdkSurface` the parent surface to attach the surface to whether to hide the surface on outside clicks Creates a new toplevel surface. the new `GdkSurface` the display to create the surface on Emits a short beep associated to @surface. If the display of @surface does not support per-surface beeps, emits a short beep on the display just as [method@Gdk.Display.beep]. a toplevel `GdkSurface` Creates a new `GdkCairoContext` for rendering on @surface. Drawing content with Cairo should be done via Cairo rendernodes, not by using the Cairo renderer. the newly created `GdkCairoContext` a `GdkSurface` Creates a new `GdkGLContext` for the `GdkSurface`. The context is disconnected from any particular surface or surface. If the creation of the `GdkGLContext` failed, @error will be set. Before using the returned `GdkGLContext`, you will need to call [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize]. the newly created `GdkGLContext` a `GdkSurface` Create a new Cairo surface that is as compatible as possible with the given @surface. For example the new surface will have the same fallback resolution and font options as @surface. Generally, the new surface will also use the same backend as @surface, unless that is not possible for some reason. The type of the returned surface may be examined with cairo_surface_get_type(). Initially the surface contents are all 0 (transparent if contents have transparency, black otherwise.) This function always returns a valid pointer, but it will return a pointer to a “nil” surface if @other is already in an error state or any other error occurs. Create a suitable cairo image surface yourself a pointer to the newly allocated surface. The caller owns the surface and should call cairo_surface_destroy() when done with it. surface to make new surface similar to the content for the new surface width of the new surface height of the new surface Sets an error and returns %NULL. GTK does not expose any Vulkan internals. This function is a leftover that was accidentally exposed. %NULL a `GdkSurface` Destroys the window system resources associated with @surface and decrements @surface's reference count. The window system resources for all children of @surface are also destroyed, but the children’s reference counts are not decremented. Note that a surface will not be destroyed automatically when its reference count reaches zero. You must call this function yourself before that happens. a `GdkSurface` Retrieves a `GdkCursor` pointer for the cursor currently set on the `GdkSurface`. If the return value is %NULL then there is no custom cursor set on the surface, and it is using the cursor for its parent surface. Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface. a `GdkCursor` a `GdkSurface` Retrieves a `GdkCursor` pointer for the @device currently set on the specified `GdkSurface`. If the return value is %NULL then there is no custom cursor set on the specified surface, and it is using the cursor for its parent surface. Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface. a `GdkCursor` a `GdkSurface` a pointer `GdkDevice` Obtains the current device position and modifier state. The position is given in coordinates relative to the upper left corner of @surface. %TRUE if the device is over the surface a `GdkSurface` pointer `GdkDevice` to query to return location for the X coordinate of @device return location for the Y coordinate of @device return location for the modifier mask Gets the `GdkDisplay` associated with a `GdkSurface`. the `GdkDisplay` associated with @surface a `GdkSurface` Gets the frame clock for the surface. The frame clock for a surface never changes unless the surface is reparented to a new toplevel surface. the frame clock surface to get frame clock for Returns the height of the given @surface. Surface size is reported in ”application pixels”, not ”device pixels” (see [method@Gdk.Surface.get_scale_factor]). The height of @surface a `GdkSurface` Checks whether the surface has been mapped. A surface is mapped with [method@Gdk.Toplevel.present] or [method@Gdk.Popup.present]. %TRUE if the surface is mapped a `GdkSurface` Returns the internal scale that maps from surface coordinates to the actual device pixels. When the scale is bigger than 1, the windowing system prefers to get buffers with a resolution that is bigger than the surface size (e.g. to show the surface on a high-resolution display, or in a magnifier). Compare with [method@Gdk.Surface.get_scale_factor], which returns the next larger integer. The scale may change during the lifetime of the surface. the scale surface to get scale for Returns the internal scale factor that maps from surface coordinates to the actual device pixels. On traditional systems this is 1, but on very high density outputs this can be a higher value (often 2). A higher value means that drawing is automatically scaled up to a higher resolution, so any code doing drawing will automatically look nicer. However, if you are supplying pixel-based data the scale value can be used to determine whether to use a pixel resource with higher resolution data. The scale factor may change during the lifetime of the surface. the scale factor surface to get scale factor for Returns the width of the given @surface. Surface size is reported in ”application pixels”, not ”device pixels” (see [method@Gdk.Surface.get_scale_factor]). The width of @surface a `GdkSurface` Hide the surface. For toplevel surfaces, withdraws them, so they will no longer be known to the window manager; for all surfaces, unmaps them, so they won’t be displayed. Normally done automatically as part of [gtk_widget_hide()](../gtk4/method.Widget.hide.html). a `GdkSurface` Check to see if a surface is destroyed. %TRUE if the surface is destroyed a `GdkSurface` Forces a [signal@Gdk.Surface::render] signal emission for @surface to be scheduled. This function is useful for implementations that track invalid regions on their own. a `GdkSurface` Request a layout phase from the surface's frame clock. See [method@Gdk.FrameClock.request_phase]. a `GdkSurface` Sets the default mouse pointer for a `GdkSurface`. Passing %NULL for the @cursor argument means that @surface will use the cursor of its parent surface. Most surfaces should use this default. Note that @cursor must be for the same display as @surface. Use [ctor@Gdk.Cursor.new_from_name] or [ctor@Gdk.Cursor.new_from_texture] to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. a `GdkSurface` a `GdkCursor` Sets a specific `GdkCursor` for a given device when it gets inside @surface. Passing %NULL for the @cursor argument means that @surface will use the cursor of its parent surface. Most surfaces should use this default. Use [ctor@Gdk.Cursor.new_from_name] or [ctor@Gdk.Cursor.new_from_texture] to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. a `GdkSurface` a pointer `GdkDevice` a `GdkCursor` Apply the region to the surface for the purpose of event handling. Mouse events which happen while the pointer position corresponds to an unset bit in the mask will be passed on the surface below @surface. An input region is typically used with RGBA surfaces. The alpha channel of the surface defines which pixels are invisible and allows for nicely antialiased borders, and the input region controls where the surface is “clickable”. Use [method@Gdk.Display.supports_input_shapes] to find out if a particular backend supports input regions. a `GdkSurface` region of surface to be reactive, or %NULL to make the entire surface reactive Marks a region of the `GdkSurface` as opaque. For optimisation purposes, compositing window managers may like to not draw obscured regions of surfaces, or turn off blending during for these regions. With RGB windows with no transparency, this is just the shape of the window, but with ARGB32 windows, the compositor does not know what regions of the window are transparent or not. This function only works for toplevel surfaces. GTK will update this property automatically if the @surface background is opaque, as we know where the opaque regions are. If your surface background is not opaque, please update this property in your [GtkWidgetClass.css_changed](../gtk4/vfunc.Widget.css_changed.html) handler. GDK can figure out the opaque parts of a window itself by inspecting the contents that are drawn. a top-level `GdkSurface` a region, or %NULL to make the entire surface opaque Translates coordinates between two surfaces. Note that this only works if @to and @from are popups or transient-for to the same toplevel (directly or indirectly). %TRUE if the coordinates were successfully translated the origin surface the target surface coordinates to translate coordinates to translate The mouse pointer for the `GdkSurface`. The `GdkDisplay` connection of the surface. The `GdkFrameClock` of the surface. The height of the surface, in pixels. Whether the surface is mapped. The scale of the surface. The scale factor of the surface. The scale factor is the next larger integer, compared to [property@Gdk.Surface:scale]. The width of the surface in pixels. Emitted when @surface starts being present on the monitor. the monitor Emitted when GDK receives an input event for @surface. %TRUE to indicate that the event has been handled an input event Emitted when the size of @surface is changed, or when relayout should be performed. Surface size is reported in ”application pixels”, not ”device pixels” (see gdk_surface_get_scale_factor()). the current width the current height Emitted when @surface stops being present on the monitor. the monitor Emitted when part of the surface needs to be redrawn. %TRUE to indicate that the signal has been handled the region that needs to be redrawn Determines a surface edge or corner. the top left corner. the top edge. the top right corner. the left edge. the right edge. the lower left corner. the lower edge. the lower right corner. Refers to pixel data in various forms. It is primarily meant for pixel data that will not change over multiple frames, and will be used for a long time. There are various ways to create `GdkTexture` objects from a [class@GdkPixbuf.Pixbuf], or from bytes stored in memory, a file, or a [struct@Gio.Resource]. The ownership of the pixel data is transferred to the `GdkTexture` instance; you can only make a copy of it, via [method@Gdk.Texture.download]. `GdkTexture` is an immutable object: That means you cannot change anything about it other than increasing the reference count via [method@GObject.Object.ref], and consequently, it is a threadsafe object. GDK provides a number of threadsafe texture loading functions: [ctor@Gdk.Texture.new_from_resource], [ctor@Gdk.Texture.new_from_bytes], [ctor@Gdk.Texture.new_from_file], [ctor@Gdk.Texture.new_from_filename], [ctor@Gdk.Texture.new_for_pixbuf]. Note that these are meant for loading icons and resources that are shipped with the toolkit or application. It is recommended that you use a dedicated image loading framework such as [glycin](https://lib.rs/crates/glycin), if you need to load untrusted image data. Creates a new texture object representing the `GdkPixbuf`. This function is threadsafe, so that you can e.g. use GTask and [method@Gio.Task.run_in_thread] to avoid blocking the main thread while loading a big image. Use e.g. libglycin, which can load many image formats into a `GdkTexture` a new `GdkTexture` a `GdkPixbuf` Creates a new texture by loading an image from memory, The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available. If `NULL` is returned, then @error will be set. This function is threadsafe, so that you can e.g. use GTask and [method@Gio.Task.run_in_thread] to avoid blocking the main thread while loading a big image. ::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a `GdkTexture`. A newly-created `GdkTexture` a `GBytes` containing the data to load Creates a new texture by loading an image from a file. The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available. If `NULL` is returned, then @error will be set. This function is threadsafe, so that you can e.g. use GTask and [method@Gio.Task.run_in_thread] to avoid blocking the main thread while loading a big image. ::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a `GdkTexture`. A newly-created `GdkTexture` `GFile` to load Creates a new texture by loading an image from a file. The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available. If `NULL` is returned, then @error will be set. This function is threadsafe, so that you can e.g. use GTask and [method@Gio.Task.run_in_thread] to avoid blocking the main thread while loading a big image. ::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a `GdkTexture`. A newly-created `GdkTexture` the filename to load Creates a new texture by loading an image from a resource. The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available. It is a fatal error if @resource_path does not specify a valid image resource and the program will abort if that happens. If you are unsure about the validity of a resource, use [ctor@Gdk.Texture.new_from_file] to load it. This function is threadsafe, so that you can e.g. use GTask and [method@Gio.Task.run_in_thread] to avoid blocking the main thread while loading a big image. A newly-created `GdkTexture` the path of the resource file Downloads the @texture into local memory. This may be an expensive operation, as the actual texture data may reside on a GPU or on a remote display server. The data format of the downloaded data is equivalent to %CAIRO_FORMAT_ARGB32, so every downloaded pixel requires 4 bytes of memory. Downloading a texture into a Cairo image surface: ```c surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32, gdk_texture_get_width (texture), gdk_texture_get_height (texture)); gdk_texture_download (texture, cairo_image_surface_get_data (surface), cairo_image_surface_get_stride (surface)); cairo_surface_mark_dirty (surface); ``` For more flexible download capabilities, see [struct@Gdk.TextureDownloader]. a `GdkTexture` pointer to enough memory to be filled with the downloaded data of @texture rowstride in bytes Returns the color state associated with the texture. the color state of the `GdkTexture` a `GdkTexture` Gets the memory format most closely associated with the data of the texture. Note that it may not be an exact match for texture data stored on the GPU or with compression. The format can give an indication about the bit depth and opacity of the texture and is useful to determine the best format for downloading the texture. the preferred format for the texture's data a GdkTexture Returns the height of the @texture, in pixels. the height of the `GdkTexture` a `GdkTexture` Returns the width of @texture, in pixels. the width of the `GdkTexture` a `GdkTexture` Store the given @texture to the @filename as a PNG file. This is a utility function intended for debugging and testing. If you want more control over formats, proper error handling or want to store to a [iface@Gio.File] or other location, you might want to use [method@Gdk.Texture.save_to_png_bytes] or look into the libglycin library. %TRUE if saving succeeded, %FALSE on failure. a `GdkTexture` the filename to store to Store the given @texture in memory as a PNG file. Use [ctor@Gdk.Texture.new_from_bytes] to read it back. If you want to serialize a texture, this is a convenient and portable way to do that. If you need more control over the generated image, such as attaching metadata, you should look into an image handling library such as the libglycin library. If you are dealing with high dynamic range float data, you might also want to consider [method@Gdk.Texture.save_to_tiff_bytes] instead. a newly allocated `GBytes` containing PNG data a `GdkTexture` Store the given @texture to the @filename as a TIFF file. GTK will attempt to store data without loss. %TRUE if saving succeeded, %FALSE on failure. a `GdkTexture` the filename to store to Store the given @texture in memory as a TIFF file. Use [ctor@Gdk.Texture.new_from_bytes] to read it back. This function is intended to store a representation of the texture's data that is as accurate as possible. This is particularly relevant when working with high dynamic range images and floating-point texture data. If that is not your concern and you are interested in a smaller size and a more portable format, you might want to use [method@Gdk.Texture.save_to_png_bytes]. a newly allocated `GBytes` containing TIFF data a `GdkTexture` The color state of the texture. The height of the texture, in pixels. The width of the texture, in pixels. Used to download the contents of a [class@Gdk.Texture]. It is intended to be created as a short-term object for a single download, but can be used for multiple downloads of different textures or with different settings. `GdkTextureDownloader` can be used to convert data between different formats. Create a `GdkTexture` for the existing format and then download it in a different format. Creates a new texture downloader for @texture. By default, the downloader will convert the data to the default memory format, and to the sRGB color state. A new texture downloader texture to download Creates a copy of the downloader. This function is meant for language bindings. A copy of the downloader the downloader to copy Downloads the given texture pixels into a `GBytes`. The rowstride will be stored in the stride value. This function will abort if it tries to download a large texture and fails to allocate memory. If you think that may happen, you should handle memory allocation yourself and use [method@Gdk.TextureDownloader.download_into] once allocation succeeded. This function cannot be used with a multiplanar format. Use [method@Gdk.TextureDownloader.download_bytes_with_planes] for that purpose. The downloaded pixels the downloader The stride of the resulting data in bytes Downloads the given texture pixels into a `GBytes`. The offsets and strides of the resulting buffer will be stored in the respective values. If the format does have less than 4 planes, the remaining offsets and strides will be set to `0`. The downloaded pixels the downloader The offsets of the resulting data planes in bytes The stride of the resulting data planes in bytes Downloads the @texture into local memory. This function cannot be used with a multiplanar format. a texture downloader pointer to enough memory to be filled with the downloaded data of the texture rowstride in bytes Frees the given downloader and all its associated resources. texture downloader to free Gets the color state that the data will be downloaded in. The color state of the download a texture downloader Gets the format that the data will be downloaded in. The format of the download a texture downloader Gets the texture that the downloader will download. The texture to download a texture downloader Sets the color state the downloader will convert the data to. By default, the sRGB colorstate returned by [func@ColorState.get_srgb] is used. a texture downloader the color state to use Sets the format the downloader will download. By default, GDK_MEMORY_DEFAULT is set. a texture downloader the format to use Changes the texture the downloader will download. a texture downloader the new texture to download Possible errors that can be returned by `GdkTexture` constructors. Not enough memory to handle this image The image data appears corrupted The image contains features that cannot be loaded The image format is not supported Registers an error quark for [class@Gdk.Texture] errors. the error quark Stores a single event in a motion history. To check whether an axis is present, check whether the corresponding flag from the [flags@Gdk.AxisFlags] enumeration is set in the @flags To access individual axis values, use the values of the values of the [enum@Gdk.AxisUse] enumerations as indices. The timestamp for this event Flags indicating what axes are present, see [flags@Gdk.AxisFlags] axis values, indexed by [enum@Gdk.AxisUse] The kind of title bar gesture to emit with [method@Gdk.Toplevel.titlebar_gesture]. double click gesture right click gesture middle click gesture A freestanding toplevel surface. The `GdkToplevel` interface provides useful APIs for interacting with the windowing system, such as controlling maximization and size of the surface, setting icons and transient parents for dialogs. Begins an interactive move operation. You might use this function to implement draggable titlebars. a `GdkToplevel` the device used for the operation the button being used to drag, or 0 for a keyboard-initiated drag surface X coordinate of mouse click that began the drag surface Y coordinate of mouse click that began the drag timestamp of mouse click that began the drag (use [method@Gdk.Event.get_time]) Begins an interactive resize operation. You might use this function to implement a “window resize grip.” a `GdkToplevel` the edge or corner from which the drag is started the device used for the operation the button being used to drag, or 0 for a keyboard-initiated drag surface X coordinate of mouse click that began the drag surface Y coordinate of mouse click that began the drag timestamp of mouse click that began the drag (use [method@Gdk.Event.get_time]) Sets keyboard focus to @surface. In most cases, [gtk_window_present_with_time()](../gtk4/method.Window.present_with_time.html) should be used on a [GtkWindow](../gtk4/class.Window.html), rather than calling this function. a `GdkToplevel` timestamp of the event triggering the surface focus The capabilities that are available for this toplevel. the capabilities of the `GdkToplevel`. a `GdkToplevel` Returns the gravity that is used when changing the toplevel size programmatically. the gravity a toplevel Gets the bitwise or of the currently active surface state flags, from the `GdkToplevelState` enumeration. surface state bitfield a `GdkToplevel` Requests that the @toplevel inhibit the system shortcuts. This is asking the desktop environment/windowing system to let all keyboard events reach the surface, as long as it is focused, instead of triggering system actions. If granted, the rerouting remains active until the default shortcuts processing is restored with [method@Gdk.Toplevel.restore_system_shortcuts], or the request is revoked by the desktop environment, windowing system or the user. A typical use case for this API is remote desktop or virtual machine viewers which need to inhibit the default system keyboard shortcuts so that the remote session or virtual host gets those instead of the local environment. The windowing system or desktop environment may ask the user to grant or deny the request or even choose to ignore the request entirely. The caller can be notified whenever the request is granted or revoked by listening to the [property@Gdk.Toplevel:shortcuts-inhibited] property. a `GdkToplevel` the `GdkEvent` that is triggering the inhibit request, or %NULL if none is available Asks to lower the @toplevel below other windows. The windowing system may choose to ignore the request. %TRUE if the surface was lowered a `GdkToplevel` Asks to minimize the @toplevel. The windowing system may choose to ignore the request. %TRUE if the surface was minimized a `GdkToplevel` Present @toplevel after having processed the `GdkToplevelLayout` rules. If the toplevel was previously not showing, it will be showed, otherwise it will change layout according to @layout. GDK may emit the [signal@Gdk.Toplevel::compute-size] signal to let the user of this toplevel compute the preferred size of the toplevel surface. Presenting is asynchronous and the specified layout parameters are not guaranteed to be respected. the `GdkToplevel` to show the `GdkToplevelLayout` object used to layout Restore default system keyboard shortcuts which were previously inhibited. This undoes the effect of [method@Gdk.Toplevel.inhibit_system_shortcuts]. a `GdkToplevel` Sets the toplevel to be decorated. Setting @decorated to %FALSE hints the desktop environment that the surface has its own, client-side decorations and does not need to have window decorations added. a `GdkToplevel` %TRUE to request decorations Sets the toplevel to be deletable. Setting @deletable to %TRUE hints the desktop environment that it should offer the user a way to close the surface. a `GdkToplevel` %TRUE to request a delete button Sets the gravity that is used when changing the toplevel size programmatically. a toplevel the new gravity Sets a list of icons for the surface. One of these will be used to represent the surface in iconic form. The icon may be shown in window lists or task bars. Which icon size is shown depends on the window manager. The window manager can scale the icon but setting several size icons can give better image quality. Note that some platforms don't support surface icons. a `GdkToplevel` A list of textures to use as icon, of different sizes Sets the toplevel to be modal. The application can use this hint to tell the window manager that a certain surface has modal behaviour. The window manager can use this information to handle modal surfaces in a special way. You should only use this on surfaces for which you have previously called [method@Gdk.Toplevel.set_transient_for]. a `GdkToplevel` %TRUE if the surface is modal, %FALSE otherwise. Sets the startup notification ID. When using GTK, typically you should use [gtk_window_set_startup_id()](../gtk4/method.Window.set_startup_id.html) instead of this low-level function. a `GdkToplevel` a string with startup-notification identifier Sets the title of a toplevel surface. The title maybe be displayed in the titlebar, in lists of windows, etc. a `GdkToplevel` title of @surface Sets a transient-for parent. Indicates to the window manager that @surface is a transient dialog associated with the application surface @parent. This allows the window manager to do things like center @surface on @parent and keep @surface above @parent. See [gtk_window_set_transient_for()](../gtk4/method.Window.set_transient_for.html) if you’re using [GtkWindow](../gtk4/class.Window.html). a `GdkToplevel` another toplevel `GdkSurface` Asks the windowing system to show the window menu. The window menu is the menu shown when right-clicking the titlebar on traditional windows managed by the window manager. This is useful for windows using client-side decorations, activating it with a right-click on the window decorations. %TRUE if the window menu was shown and %FALSE otherwise. a `GdkToplevel` a `GdkEvent` to show the menu for Returns whether the desktop environment supports tiled window states. %TRUE if the desktop environment supports tiled window states a `GdkToplevel` Performs a title bar gesture. whether the gesture was performed a `GdkToplevel` a `GdkTitlebarGesture` The capabilities that are available for this toplevel. Whether the window manager should add decorations. Whether the window manager should allow to close the surface. The fullscreen mode of the surface. The gravity to use when resizing a surface programmatically. Gravity describes which point of the surface we want to keep fixed (meaning that the surface will grow in the opposite direction). For example, a gravity of `GDK_GRAVITY_NORTH_EAST` means that we want to fix top right corner of the surface. This property is just a hint that may affect the result when negotiating toplevel sizes with the windowing system. It does not affect interactive resizes started with [method@Gdk.Toplevel.begin_resize]. A list of textures to use as icon. Whether the surface is modal. Whether the surface should inhibit keyboard shortcuts. The startup ID of the surface. See [class@Gdk.AppLaunchContext] for more information about startup feedback. The state of the toplevel. The title of the surface. The transient parent of the surface. Emitted when the size for the surface needs to be computed, when it is present. This signal will normally be emitted during or after a call to [method@Gdk.Toplevel.present], depending on the configuration received by the windowing system. It may also be emitted at any other point in time, in response to the windowing system spontaneously changing the configuration of the toplevel surface. It is the responsibility of the toplevel user to handle this signal and compute the desired size of the toplevel, given the information passed via the [struct@Gdk.ToplevelSize] object. Failing to do so will result in an arbitrary size being used as a result. a `GdkToplevelSize` Reflects what features a `GdkToplevel` supports. Whether tiled window states are supported. Whether inhibiting system shortcuts is supported. See [method@Gdk.Toplevel.inhibit_system_shortcuts]. Whether titlebar gestures are supported. See [method@Gdk.Toplevel.titlebar_gesture]. Whether showing the window menu is supported. See [method@Gdk.Toplevel.show_window_menu]. Whether the toplevel can be maximized. Whether the toplevel can be made fullscreen. Whether the toplevel can be minimized. See [method@Gdk.Toplevel.minimize]. Whether the toplevel can be lowered. See [method@Gdk.Toplevel.lower]. Contains information that is necessary to present a sovereign window on screen. The `GdkToplevelLayout` struct is necessary for using [method@Gdk.Toplevel.present]. Toplevel surfaces are sovereign windows that can be presented to the user in various states (maximized, on all workspaces, etc). Create a toplevel layout description. Used together with [method@Gdk.Toplevel.present] to describe how a toplevel surface should be placed and behave on-screen. The size is in ”application pixels”, not ”device pixels” (see [method@Gdk.Surface.get_scale]). newly created instance of `GdkToplevelLayout` Create a new `GdkToplevelLayout` and copy the contents of @layout into it. a copy of @layout. a toplevel layout Check whether @layout and @other has identical layout properties. true if @layout and @other have identical layout properties, otherwise false. a toplevel layout another toplevel layout If the layout specifies whether to the toplevel should go fullscreen, the value pointed to by @fullscreen is set to true if it should go fullscreen, or false, if it should go unfullscreen. whether the @layout specifies the fullscreen state for the toplevel a toplevel layout location to store whether the toplevel should be fullscreen Returns the monitor that the layout is fullscreening the surface on. the monitor on which @layout fullscreens a toplevel layout If the layout specifies whether to the toplevel should go maximized, the value pointed to by @maximized is set to true if it should go maximized, or false, if it should go unmaximized. whether the @layout specifies the maximized state for the toplevel a toplevel layout set to true if the toplevel should be maximized Returns whether the layout should allow the user to resize the surface. true if the layout is resizable a toplevel layout Increases the reference count of @layout. the same @layout a toplevel layout Sets whether the layout should cause the surface to be fullscreen when presented. a toplevel layout true to fullscreen the surface the monitor to fullscreen on Sets whether the layout should cause the surface to be maximized when presented. a toplevel layout true to maximize Sets whether the layout should allow the user to resize the surface after it has been presented. a toplevel layout true to allow resizing Decreases the reference count of @layout. a toplevel layout Contains information that is useful to compute the size of a toplevel. Retrieves the bounds the toplevel is placed within. The bounds represent the largest size a toplevel may have while still being able to fit within some type of boundary. Depending on the backend, this may be equivalent to the dimensions of the work area or the monitor on which the window is being presented on, or something else that limits the way a toplevel can be presented. a `GdkToplevelSize` return location for width return location for height Sets the minimum size of the toplevel. The minimum size corresponds to the limitations the toplevel can be shrunk to, without resulting in incorrect painting. A user of a `GdkToplevel` should calculate these given both the existing size, and the bounds retrieved from the `GdkToplevelSize` object. The minimum size should be within the bounds (see [method@Gdk.ToplevelSize.get_bounds]). a `GdkToplevelSize` the minimum width the minimum height Sets the shadows size of the toplevel. The shadow width corresponds to the part of the computed surface size that would consist of the shadow margin surrounding the window, would there be any. Shadow width should only be set if [method@Gtk.Display.supports_shadow_width] is %TRUE. a `GdkToplevelSize` width of the left part of the shadow width of the right part of the shadow height of the top part of the shadow height of the bottom part of the shadow Sets the size the toplevel prefers to be resized to. The size should be within the bounds (see [method@Gdk.ToplevelSize.get_bounds]). The set size should be considered as a hint, and should not be assumed to be respected by the windowing system, or backend. a `GdkToplevelSize` the width the height Specifies the state of a toplevel surface. On platforms that support information about individual edges, the %GDK_TOPLEVEL_STATE_TILED state will be set whenever any of the individual tiled states is set. On platforms that lack that support, the tiled state will give an indication of tiledness without any of the per-edge states being set. the surface is minimized the surface is maximized the surface is sticky the surface is maximized without decorations the surface is kept above other surfaces the surface is kept below other surfaces the surface is presented as focused (with active decorations) the surface is in a tiled state whether the top edge is tiled whether the top edge is resizable whether the right edge is tiled whether the right edge is resizable whether the bottom edge is tiled whether the bottom edge is resizable whether the left edge is tiled whether the left edge is resizable The surface is not visible to the user. An event related to a touch-based device. Extracts whether a touch event is emulating a pointer event. %TRUE if @event is emulating a touch event An event related to a gesture on a touchpad device. Unlike touchscreens, where the windowing system sends basic sequences of begin, update, end events, and leaves gesture recognition to the clients, touchpad gestures are typically processed by the system, resulting in these events. Extracts delta information from a touchpad event. a touchpad event return location for x return location for y Extracts the touchpad gesture phase from a touchpad event. the gesture phase of @event a touchpad event Extracts the number of fingers from a touchpad event. the number of fingers for @event a touchpad event Extracts the angle delta from a touchpad pinch event. the angle delta of @event a touchpad pinch event Extracts the scale from a touchpad pinch event. the scale of @event a touchpad pinch event Specifies the current state of a touchpad gesture. All gestures are guaranteed to begin with an event with phase %GDK_TOUCHPAD_GESTURE_PHASE_BEGIN, followed by 0 or several events with phase %GDK_TOUCHPAD_GESTURE_PHASE_UPDATE. A finished gesture may have 2 possible outcomes, an event with phase %GDK_TOUCHPAD_GESTURE_PHASE_END will be emitted when the gesture is considered successful, this should be used as the hint to perform any permanent changes. Cancelled gestures may be so for a variety of reasons, due to hardware or the compositor, or due to the gesture recognition layers hinting the gesture did not finish resolutely (eg. a 3rd finger being added during a pinch gesture). In these cases, the last event will report the phase %GDK_TOUCHPAD_GESTURE_PHASE_CANCEL, this should be used as a hint to undo any visible/permanent changes that were done throughout the progress of the gesture. The gesture has begun. The gesture has been updated. The gesture was finished, changes should be permanently applied. The gesture was cancelled, all changes should be undone. Represents the platform-specific Vulkan draw context. `GdkVulkanContext`s are created for a surface using [method@Gdk.Surface.create_vulkan_context], and the context will match the characteristics of the surface. Support for `GdkVulkanContext` is platform-specific and context creation can fail, returning %NULL context. GTK does not expose any Vulkan internals. This struct is a leftover that was accidentally exposed. Emitted when the images managed by this context have changed. Usually this means that the swapchain had to be recreated, for example in response to a change of the surface size. Error enumeration for `GdkVulkanContext`. Vulkan is not supported on this backend or has not been compiled in. Vulkan support is not available on this Surface Registers an error quark for [class@Gdk.VulkanContext] errors. the error quark Draws GL content onto a cairo context. It takes a render buffer ID (@source_type == GL_RENDERBUFFER) or a texture id (@source_type == GL_TEXTURE) and draws it onto @cr with an OVER operation, respecting the current clip. The top left corner of the rectangle specified by @x, @y, @width and @height will be drawn at the current (0,0) position of the `cairo_t`. This will work for *all* `cairo_t`, as long as @surface is realized, but the fallback implementation that reads back the pixels from the buffer may be used in the general case. In the case of direct drawing to a surface with no special effects applied to @cr it will however use a more efficient approach. For GL_RENDERBUFFER the code will always fall back to software for buffers with alpha components, so make sure you use GL_TEXTURE if using alpha. Calling this may change the current GL context. The function is overly complex and produces broken output in various combinations of arguments. If you want to draw with GL textures in GTK, use [ctor@Gdk.GLTexture.new]; if you want to use that texture in Cairo, use [method@Gdk.Texture.download] to download the data into a Cairo image surface. a cairo context The surface we're rendering for (not necessarily into) The GL ID of the source buffer The type of the @source The scale-factor that the @source buffer is allocated for The source x position in @source to start copying from in GL coordinates The source y position in @source to start copying from in GL coordinates The width of the region to draw The height of the region to draw Adds the given rectangle to the current path of @cr. a cairo context a `GdkRectangle` Adds the given region to the current path of @cr. a cairo context a `cairo_region_t` Creates region that covers the area where the given @surface is more than 50% opaque. This function takes into account device offsets that might be set with cairo_surface_set_device_offset(). A `cairo_region_t` a cairo surface Sets the given pixbuf as the source pattern for @cr. The pattern has an extend mode of %CAIRO_EXTEND_NONE and is aligned so that the origin of @pixbuf is @pixbuf_x, @pixbuf_y. Use cairo_set_source_surface() and gdk_texture_download() a cairo context a `GdkPixbuf` X coordinate of location to place upper left corner of @pixbuf Y coordinate of location to place upper left corner of @pixbuf Sets the specified `GdkRGBA` as the source color of @cr. a cairo context a `GdkRGBA` Returns the color state object representing the oklab color space. This is a perceptually uniform color state. the color state object for oklab Returns the color state object representing the oklch color space. This is the polar variant of oklab, in which the hue is encoded as a polar coordinate. the color state object for oklch Returns the color state object representing the linear rec2100 color space. This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and a linear transfer function. It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/8/0/1. See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-linear) for details about this colorstate. the color state object for linearized rec2100 Returns the color state object representing the rec2100-pq color space. This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and the transfer function defined by SMPTE ST 2084 and BT.2100-2. It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/16/0/1. See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-pq) for details about this colorstate. the color state object for rec2100-pq Returns the color state object representing the sRGB color space. This color state uses the primaries defined by BT.709-6 and the transfer function defined by IEC 61966-2-1. It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/13/0/1. See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB) for details about this colorstate. the color state object for sRGB Returns the color state object representing the linearized sRGB color space. This color state uses the primaries defined by BT.709-6 and a linear transfer function. It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/8/0/1. See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB-linear) for details about this colorstate. the color state object for linearized sRGB Reads content from the given input stream and deserialize it, asynchronously. The default I/O priority is `G_PRIORITY_DEFAULT` (i.e. 0), and lower numbers indicate a higher priority. a `GInputStream` to read the serialized content from the mime type to deserialize from the GType to deserialize from the I/O priority of the operation optional `GCancellable` object callback to call when the operation is done data to pass to the callback function Finishes a content deserialization operation. %TRUE if the operation was successful. In this case, @value is set. %FALSE if an error occurred. In this case, @error is set the `GAsyncResult` return location for the result of the operation Parses the given @string into `GdkContentFormats` and returns the formats. Strings printed via [method@Gdk.ContentFormats.to_string] can be read in again successfully using this function. If @string does not describe valid content formats, %NULL is returned. the content formats if @string is valid the string to parse Registers a function to deserialize object of a given type. Since 4.20, when looking up a deserializer to use, GTK will use the last registered deserializer for a given mime type, so applications can override the built-in deserializers. the mime type which the function can deserialize from the type of objects that the function creates the callback data that @deserialize can access destroy notify for @data Registers a function to serialize objects of a given type. Since 4.20, when looking up a serializer to use, GTK will use the last registered serializer for a given mime type, so applications can override the built-in serializers. the type of objects that the function can serialize the mime type to serialize to the callback data that @serialize can access destroy notify for @data Serialize content and write it to the given output stream, asynchronously. The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers indicate a higher priority. a `GOutputStream` to write the serialized content to the mime type to serialize to the content to serialize the I/O priority of the operation optional `GCancellable` object callback to call when the operation is done data to pass to the callback function Finishes a content serialization operation. %TRUE if the operation was successful, %FALSE if an error occurred. In this case, @error is set the `GAsyncResult` Registers an error quark for [class@Gdk.DmabufTexture] errors. the error quark Checks if @action represents a single action or includes multiple actions. When @action is `GDK_ACTION_NONE` - ie no action was given, `TRUE` is returned. %TRUE if exactly one action was given a `GdkDragAction` Returns the relative angle from @event1 to @event2. The relative angle is the angle between the X axis and the line through both events' positions. The rotation direction for positive angles is from the positive X axis towards the positive Y axis. This assumes that both events have X/Y information. If not, this function returns %FALSE. %TRUE if the angle could be calculated. first `GdkEvent` second `GdkEvent` return location for the relative angle between both events Returns the point halfway between the events' positions. This assumes that both events have X/Y information. If not, this function returns %FALSE. %TRUE if the center could be calculated. first `GdkEvent` second `GdkEvent` return location for the X coordinate of the center return location for the Y coordinate of the center Returns the distance between the event locations. This assumes that both events have X/Y information. If not, this function returns %FALSE. %TRUE if the distance could be calculated. first `GdkEvent` second `GdkEvent` return location for the distance Registers an error quark for [class@Gdk.GLContext] errors. the error quark Canonicalizes the given mime type and interns the result. If @string is not a valid mime type, %NULL is returned instead. See RFC 2048 for the syntax if mime types. An interned string for the canonicalized mime type or %NULL if the string wasn't a valid mime type string of a potential mime type Obtains the upper- and lower-case versions of the keyval @symbol. Examples of keyvals are `GDK_KEY_a`, `GDK_KEY_Enter`, `GDK_KEY_F1`, etc. a keyval return location for lowercase version of @symbol return location for uppercase version of @symbol Converts a key name to a key value. The names are the same as those in the `gdk/gdkkeysyms.h` header file but without the leading “GDK_KEY_”. the corresponding key value, or `GDK_KEY_VoidSymbol` if the key name is not a valid key a key name Returns true if the given key value is in lower case. true if @keyval is in lower case, or if @keyval is not subject to case conversion. a key value. Returns true if the given key value is in upper case. true if @keyval is in upper case, or if @keyval is not subject to case conversion. a key value. Converts a key value into a symbolic name. The names are the same as those in the `gdk/gdkkeysyms.h` header file but without the leading “GDK_KEY_”. a string containing the name of the key a key value Converts a key value to lower case, if applicable. the lower case form of @keyval, or @keyval itself if it is already in lower case or it is not subject to case conversion. a key value. Converts from a GDK key symbol to the corresponding Unicode character. Note that the conversion does not take the current locale into consideration, which might be expected for particular keyvals, such as `GDK_KEY_KP_Decimal`. the corresponding unicode character, or 0 if there is no corresponding character. a GDK key symbol Converts a key value to upper case, if applicable. the upper case form of @keyval, or @keyval itself if it is already in upper case or it is not subject to case conversion. a key value. Returns a paintable that has the given intrinsic size and draws nothing. This is often useful for implementing the [vfunc@Gdk.Paintable.get_current_image] virtual function when the paintable is in an incomplete state (like a [GtkMediaStream](../gtk4/class.MediaStream.html) before receiving the first frame). a `GdkPaintable` The intrinsic width to report. Can be 0 for no width. The intrinsic height to report. Can be 0 for no height. Obtains a clip region which contains the areas where the given ranges of text would be drawn. @x_origin and @y_origin are the top left point to center the layout. @index_ranges should contain ranges of bytes in the layout’s text. Note that the regions returned correspond to logical extents of the text ranges, not ink extents. So the drawn layout may in fact touch areas out of the clip region. The clip region is mainly useful for highlightling parts of text, such as when text is selected. a clip region containing the given ranges a `PangoLayout` X pixel where you intend to draw the layout with this clip Y pixel where you intend to draw the layout with this clip array of byte indexes into the layout, where even members of array are start indexes and odd elements are end indexes number of ranges in @index_ranges, i.e. half the size of @index_ranges Obtains a clip region which contains the areas where the given ranges of text would be drawn. @x_origin and @y_origin are the top left position of the layout. @index_ranges should contain ranges of bytes in the layout’s text. The clip region will include space to the left or right of the line (to the layout bounding box) if you have indexes above or below the indexes contained inside the line. This is to draw the selection all the way to the side of the layout. However, the clip region is in line coordinates, not layout coordinates. Note that the regions returned correspond to logical extents of the text ranges, not ink extents. So the drawn line may in fact touch areas out of the clip region. The clip region is mainly useful for highlightling parts of text, such as when text is selected. a clip region containing the given ranges a `PangoLayoutLine` X pixel where you intend to draw the layout line with this clip baseline pixel where you intend to draw the layout line with this clip array of byte indexes into the layout, where even members of array are start indexes and odd elements are end indexes number of ranges in @index_ranges, i.e. half the size of @index_ranges Transfers image data from a `cairo_surface_t` and converts it to a `GdkPixbuf`. This allows you to efficiently read individual pixels from cairo surfaces. This function will create an RGB pixbuf with 8 bits per channel. The pixbuf will contain an alpha channel if the @surface contains one. Use [class@Gdk.Texture] and subclasses instead cairo surfaces and pixbufs A newly-created pixbuf with a reference count of 1 surface to copy from Source X coordinate within @surface Source Y coordinate within @surface Width in pixels of region to get Height in pixels of region to get Creates a new pixbuf from @texture. This should generally not be used in newly written code as later stages will almost certainly convert the pixbuf back into a texture to draw it on screen. Use [class@Gdk.Texture] and subclasses instead cairo surfaces and pixbufs a new `GdkPixbuf` a `GdkTexture` Sets a list of backends that GDK should try to use. This can be useful if your application does not work with certain GDK backends. By default, GDK tries all included backends. For example: ```c gdk_set_allowed_backends ("wayland,macos,*"); ``` instructs GDK to try the Wayland backend first, followed by the MacOs backend, and then all others. If the `GDK_BACKEND` environment variable is set, it determines what backends are tried in what order, while still respecting the set of allowed backends that are specified by this function. The possible backend names are: - `broadway` - `macos` - `wayland`. - `win32` - `x11` You can also include a `*` in the list to try all remaining backends. This call must happen prior to functions that open a display, such as [func@Gdk.Display.open], `gtk_init()`, or `gtk_init_check()` in order to take effect. a comma-separated list of backends Registers an error quark for [class@Gdk.Texture] errors. the error quark Converts from a Unicode character to a key symbol. the corresponding GDK key symbol, if one exists, or, if there is no corresponding symbol, `wc | 0x01000000` a Unicode character Registers an error quark for [class@Gdk.VulkanContext] errors. the error quark soup3-0.9.0/gir-files/GdkMacos-4.0.gir000064400000000000000000000210541046102023000152600ustar 00000000000000 Retrieves the size and position of the “work area” on a monitor within the display coordinate space. The returned geometry is in ”application pixels”, not in ”device pixels” (see [method@Gdk.Monitor.get_scale_factor]). a `GdkMonitor` a `GdkRectangle` to be filled with the monitor geometry Gets the underlying NSWindow used by the surface. The NSWindow's contentView is an implementation detail and may change between releases of GTK. a #NSWindow or %NULL a #GdkMacosSurface The "native" property contains the underlying NSWindow. soup3-0.9.0/gir-files/GdkPixbuf-2.0.gir000064400000000000000000007360211046102023000154600ustar 00000000000000 This enumeration defines the color spaces that are supported by the gdk-pixbuf library. Currently only RGB is supported. Indicates a red/green/blue additive color space. Interpolation modes for scaling functions. The `GDK_INTERP_NEAREST` mode is the fastest scaling method, but has horrible quality when scaling down; `GDK_INTERP_BILINEAR` is the best choice if you aren't sure what to choose, it has a good speed/quality balance. **Note**: Cubic filtering is missing from the list; hyperbolic interpolation is just as fast and results in higher quality. Nearest neighbor sampling; this is the fastest and lowest quality mode. Quality is normally unacceptable when scaling down, but may be OK when scaling up. This is an accurate simulation of the PostScript image operator without any interpolation enabled. Each pixel is rendered as a tiny parallelogram of solid color, the edges of which are implemented with antialiasing. It resembles nearest neighbor for enlargement, and bilinear for reduction. Best quality/speed balance; use this mode by default. Bilinear interpolation. For enlargement, it is equivalent to point-sampling the ideal bilinear-interpolated image. For reduction, it is equivalent to laying down small tiles and integrating over the coverage area. This is the slowest and highest quality reconstruction function. It is derived from the hyperbolic filters in Wolberg's "Digital Image Warping", and is formally defined as the hyperbolic-filter sampling the ideal hyperbolic-filter interpolated image (the filter is designed to be idempotent for 1:1 pixel mapping). **Deprecated**: this interpolation filter is deprecated, as in reality it has a lower quality than the @GDK_INTERP_BILINEAR filter (Since: 2.38) Macro to test the version of GdkPixbuf being compiled against. major version (e.g. 2 for version 2.34.0) minor version (e.g. 34 for version 2.34.0) micro version (e.g. 0 for version 2.34.0) Major version of gdk-pixbuf library, that is the "0" in "0.8.2" for example. Micro version of gdk-pixbuf library, that is the "2" in "0.8.2" for example. Minor version of gdk-pixbuf library, that is the "8" in "0.8.2" for example. Contains the full version of GdkPixbuf as a string. This is the version being compiled against; contrast with `gdk_pixbuf_version`. A pixel buffer. `GdkPixbuf` contains information about an image's pixel data, its color space, bits per sample, width and height, and the rowstride (the number of bytes between the start of one row and the start of the next). ## Creating new `GdkPixbuf` The most basic way to create a pixbuf is to wrap an existing pixel buffer with a [class@GdkPixbuf.Pixbuf] instance. You can use the [`ctor@GdkPixbuf.Pixbuf.new_from_data`] function to do this. Every time you create a new `GdkPixbuf` instance for some data, you will need to specify the destroy notification function that will be called when the data buffer needs to be freed; this will happen when a `GdkPixbuf` is finalized by the reference counting functions. If you have a chunk of static data compiled into your application, you can pass in `NULL` as the destroy notification function so that the data will not be freed. The [`ctor@GdkPixbuf.Pixbuf.new`] constructor function can be used as a convenience to create a pixbuf with an empty buffer; this is equivalent to allocating a data buffer using `malloc()` and then wrapping it with `gdk_pixbuf_new_from_data()`. The `gdk_pixbuf_new()` function will compute an optimal rowstride so that rendering can be performed with an efficient algorithm. You can also copy an existing pixbuf with the [method@Pixbuf.copy] function. This is not the same as just acquiring a reference to the old pixbuf instance: the copy function will actually duplicate the pixel data in memory and create a new [class@Pixbuf] instance for it. ## Reference counting `GdkPixbuf` structures are reference counted. This means that an application can share a single pixbuf among many parts of the code. When a piece of the program needs to use a pixbuf, it should acquire a reference to it by calling `g_object_ref()`; when it no longer needs the pixbuf, it should release the reference it acquired by calling `g_object_unref()`. The resources associated with a `GdkPixbuf` will be freed when its reference count drops to zero. Newly-created `GdkPixbuf` instances start with a reference count of one. ## Image Data Image data in a pixbuf is stored in memory in an uncompressed, packed format. Rows in the image are stored top to bottom, and in each row pixels are stored from left to right. There may be padding at the end of a row. The "rowstride" value of a pixbuf, as returned by [`method@GdkPixbuf.Pixbuf.get_rowstride`], indicates the number of bytes between rows. **NOTE**: If you are copying raw pixbuf data with `memcpy()` note that the last row in the pixbuf may not be as wide as the full rowstride, but rather just as wide as the pixel data needs to be; that is: it is unsafe to do `memcpy (dest, pixels, rowstride * height)` to copy a whole pixbuf. Use [method@GdkPixbuf.Pixbuf.copy] instead, or compute the width in bytes of the last row as: ```c last_row = width * ((n_channels * bits_per_sample + 7) / 8); ``` The same rule applies when iterating over each row of a `GdkPixbuf` pixels array. The following code illustrates a simple `put_pixel()` function for RGB pixbufs with 8 bits per channel with an alpha channel. ```c static void put_pixel (GdkPixbuf *pixbuf, int x, int y, guchar red, guchar green, guchar blue, guchar alpha) { int n_channels = gdk_pixbuf_get_n_channels (pixbuf); // Ensure that the pixbuf is valid g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB); g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8); g_assert (gdk_pixbuf_get_has_alpha (pixbuf)); g_assert (n_channels == 4); int width = gdk_pixbuf_get_width (pixbuf); int height = gdk_pixbuf_get_height (pixbuf); // Ensure that the coordinates are in a valid range g_assert (x >= 0 && x < width); g_assert (y >= 0 && y < height); int rowstride = gdk_pixbuf_get_rowstride (pixbuf); // The pixel buffer in the GdkPixbuf instance guchar *pixels = gdk_pixbuf_get_pixels (pixbuf); // The pixel we wish to modify guchar *p = pixels + y * rowstride + x * n_channels; p[0] = red; p[1] = green; p[2] = blue; p[3] = alpha; } ``` ## Loading images The `GdkPixBuf` class provides a simple mechanism for loading an image from a file in synchronous and asynchronous fashion. For GUI applications, it is recommended to use the asynchronous stream API to avoid blocking the control flow of the application. Additionally, `GdkPixbuf` provides the [class@GdkPixbuf.PixbufLoader`] API for progressive image loading. ## Saving images The `GdkPixbuf` class provides methods for saving image data in a number of file formats. The formatted data can be written to a file or to a memory buffer. `GdkPixbuf` can also call a user-defined callback on the data, which allows to e.g. write the image to a socket or store it in a database. Creates a new `GdkPixbuf` structure and allocates a buffer for it. If the allocation of the buffer failed, this function will return `NULL`. The buffer has an optimal rowstride. Note that the buffer is not cleared; you will have to fill it completely yourself. A newly-created pixel buffer Color space for image Whether the image should have transparency information Number of bits per color sample Width of image in pixels, must be > 0 Height of image in pixels, must be > 0 Creates a new #GdkPixbuf out of in-memory readonly image data. Currently only RGB images with 8 bits per sample are supported. This is the `GBytes` variant of gdk_pixbuf_new_from_data(), useful for language bindings. A newly-created pixbuf Image data in 8-bit/sample packed format inside a #GBytes Colorspace for the image data Whether the data has an opacity channel Number of bits per sample Width of the image in pixels, must be > 0 Height of the image in pixels, must be > 0 Distance in bytes between row starts Creates a new #GdkPixbuf out of in-memory image data. Currently only RGB images with 8 bits per sample are supported. Since you are providing a pre-allocated pixel buffer, you must also specify a way to free that data. This is done with a function of type `GdkPixbufDestroyNotify`. When a pixbuf created with is finalized, your destroy notification function will be called, and it is its responsibility to free the pixel array. See also: [ctor@GdkPixbuf.Pixbuf.new_from_bytes] A newly-created pixbuf Image data in 8-bit/sample packed format Colorspace for the image data Whether the data has an opacity channel Number of bits per sample Width of the image in pixels, must be > 0 Height of the image in pixels, must be > 0 Distance in bytes between row starts Function used to free the data when the pixbuf's reference count drops to zero, or `NULL` if the data should not be freed Closure data to pass to the destroy notification function Creates a new pixbuf by loading an image from a file. The file format is detected automatically. If `NULL` is returned, then @error will be set. Possible errors are: - the file could not be opened - there is no loader for the file's format - there is not enough memory to allocate the image buffer - the image buffer contains invalid data The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`. A newly-created pixbuf Name of file to load, in the GLib file name encoding Creates a new pixbuf by loading an image from a file. The file format is detected automatically. If `NULL` is returned, then @error will be set. Possible errors are: - the file could not be opened - there is no loader for the file's format - there is not enough memory to allocate the image buffer - the image buffer contains invalid data The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`. The image will be scaled to fit in the requested size, optionally preserving the image's aspect ratio. When preserving the aspect ratio, a `width` of -1 will cause the image to be scaled to the exact given height, and a `height` of -1 will cause the image to be scaled to the exact given width. When not preserving aspect ratio, a `width` or `height` of -1 means to not scale the image at all in that dimension. Negative values for `width` and `height` are allowed since 2.8. A newly-created pixbuf Name of file to load, in the GLib file name encoding The width the image should have or -1 to not constrain the width The height the image should have or -1 to not constrain the height `TRUE` to preserve the image's aspect ratio Creates a new pixbuf by loading an image from a file. The file format is detected automatically. If `NULL` is returned, then @error will be set. Possible errors are: - the file could not be opened - there is no loader for the file's format - there is not enough memory to allocate the image buffer - the image buffer contains invalid data The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`. The image will be scaled to fit in the requested size, preserving the image's aspect ratio. Note that the returned pixbuf may be smaller than `width` x `height`, if the aspect ratio requires it. To load and image at the requested size, regardless of aspect ratio, use [ctor@GdkPixbuf.Pixbuf.new_from_file_at_scale]. A newly-created pixbuf Name of file to load, in the GLib file name encoding The width the image should have or -1 to not constrain the width The height the image should have or -1 to not constrain the height Creates a `GdkPixbuf` from a flat representation that is suitable for storing as inline data in a program. This is useful if you want to ship a program with images, but don't want to depend on any external files. GdkPixbuf ships with a program called `gdk-pixbuf-csource`, which allows for conversion of `GdkPixbuf`s into such a inline representation. In almost all cases, you should pass the `--raw` option to `gdk-pixbuf-csource`. A sample invocation would be: ``` gdk-pixbuf-csource --raw --name=myimage_inline myimage.png ``` For the typical case where the inline pixbuf is read-only static data, you don't need to copy the pixel data unless you intend to write to it, so you can pass `FALSE` for `copy_pixels`. If you pass `--rle` to `gdk-pixbuf-csource`, a copy will be made even if `copy_pixels` is `FALSE`, so using this option is generally a bad idea. If you create a pixbuf from const inline data compiled into your program, it's probably safe to ignore errors and disable length checks, since things will always succeed: ```c pixbuf = gdk_pixbuf_new_from_inline (-1, myimage_inline, FALSE, NULL); ``` For non-const inline data, you could get out of memory. For untrusted inline data located at runtime, you could have corrupt inline data in addition. Use `GResource` instead. A newly-created pixbuf Length in bytes of the `data` argument or -1 to disable length checks Byte data containing a serialized `GdkPixdata` structure Whether to copy the pixel data, or use direct pointers `data` for the resulting pixbuf Creates a new pixbuf by loading an image from an resource. The file format is detected automatically. If `NULL` is returned, then @error will be set. A newly-created pixbuf the path of the resource file Creates a new pixbuf by loading an image from an resource. The file format is detected automatically. If `NULL` is returned, then @error will be set. The image will be scaled to fit in the requested size, optionally preserving the image's aspect ratio. When preserving the aspect ratio, a @width of -1 will cause the image to be scaled to the exact given height, and a @height of -1 will cause the image to be scaled to the exact given width. When not preserving aspect ratio, a @width or @height of -1 means to not scale the image at all in that dimension. The stream is not closed. A newly-created pixbuf the path of the resource file The width the image should have or -1 to not constrain the width The height the image should have or -1 to not constrain the height `TRUE` to preserve the image's aspect ratio Creates a new pixbuf by loading an image from an input stream. The file format is detected automatically. If `NULL` is returned, then `error` will be set. The `cancellable` can be used to abort the operation from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and `G_IO_ERROR` domains. The stream is not closed. A newly-created pixbuf a `GInputStream` to load the pixbuf from optional `GCancellable` object, `NULL` to ignore Creates a new pixbuf by loading an image from an input stream. The file format is detected automatically. If `NULL` is returned, then @error will be set. The @cancellable can be used to abort the operation from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and `G_IO_ERROR` domains. The image will be scaled to fit in the requested size, optionally preserving the image's aspect ratio. When preserving the aspect ratio, a `width` of -1 will cause the image to be scaled to the exact given height, and a `height` of -1 will cause the image to be scaled to the exact given width. If both `width` and `height` are given, this function will behave as if the smaller of the two values is passed as -1. When not preserving aspect ratio, a `width` or `height` of -1 means to not scale the image at all in that dimension. The stream is not closed. A newly-created pixbuf a `GInputStream` to load the pixbuf from The width the image should have or -1 to not constrain the width The height the image should have or -1 to not constrain the height `TRUE` to preserve the image's aspect ratio optional `GCancellable` object, `NULL` to ignore Finishes an asynchronous pixbuf creation operation started with gdk_pixbuf_new_from_stream_async(). the newly created pixbuf a `GAsyncResult` Creates a new pixbuf by parsing XPM data in memory. This data is commonly the result of including an XPM file into a program's C source. Use [ctor@GdkPixbuf.Pixbuf.new_from_stream] with a [class@Gio.MemoryInputStream], making sure to handle errors in case the XPM format loader is not available A newly-created pixbuf Pointer to inline XPM data. Calculates the rowstride that an image created with those values would have. This function is useful for front-ends and backends that want to check image values without needing to create a `GdkPixbuf`. the rowstride for the given values, or -1 in case of error. Color space for image Whether the image should have transparency information Number of bits per color sample Width of image in pixels, must be > 0 Height of image in pixels, must be > 0 Parses an image file far enough to determine its format and size. A `GdkPixbufFormat` describing the image format of the file The name of the file to identify. Return location for the width of the image Return location for the height of the image Asynchronously parses an image file far enough to determine its format and size. For more details see gdk_pixbuf_get_file_info(), which is the synchronous version of this function. When the operation is finished, @callback will be called in the main thread. You can then call gdk_pixbuf_get_file_info_finish() to get the result of the operation. The name of the file to identify optional `GCancellable` object, `NULL` to ignore a `GAsyncReadyCallback` to call when the file info is available the data to pass to the callback function Finishes an asynchronous pixbuf parsing operation started with gdk_pixbuf_get_file_info_async(). A `GdkPixbufFormat` describing the image format of the file a `GAsyncResult` Return location for the width of the image, or `NULL` Return location for the height of the image, or `NULL` Obtains the available information about the image formats supported by GdkPixbuf. A list of support image formats. Initalizes the gdk-pixbuf loader modules referenced by the `loaders.cache` file present inside that directory. This is to be used by applications that want to ship certain loaders in a different location from the system ones. This is needed when the OS or runtime ships a minimal number of loaders so as to reduce the potential attack surface of carefully crafted image files, especially for uncommon file types. Applications that require broader image file types coverage, such as image viewers, would be expected to ship the gdk-pixbuf modules in a separate location, bundled with the application in a separate directory from the OS or runtime- provided modules. Path to directory where the `loaders.cache` is installed Creates a new pixbuf by asynchronously loading an image from an input stream. For more details see gdk_pixbuf_new_from_stream(), which is the synchronous version of this function. When the operation is finished, @callback will be called in the main thread. You can then call gdk_pixbuf_new_from_stream_finish() to get the result of the operation. a `GInputStream` from which to load the pixbuf optional `GCancellable` object, `NULL` to ignore a `GAsyncReadyCallback` to call when the pixbuf is loaded the data to pass to the callback function Creates a new pixbuf by asynchronously loading an image from an input stream. For more details see gdk_pixbuf_new_from_stream_at_scale(), which is the synchronous version of this function. When the operation is finished, @callback will be called in the main thread. You can then call gdk_pixbuf_new_from_stream_finish() to get the result of the operation. a `GInputStream` from which to load the pixbuf the width the image should have or -1 to not constrain the width the height the image should have or -1 to not constrain the height `TRUE` to preserve the image's aspect ratio optional `GCancellable` object, `NULL` to ignore a `GAsyncReadyCallback` to call when the pixbuf is loaded the data to pass to the callback function Finishes an asynchronous pixbuf save operation started with gdk_pixbuf_save_to_stream_async(). `TRUE` if the pixbuf was saved successfully, `FALSE` if an error was set. a `GAsyncResult` Takes an existing pixbuf and adds an alpha channel to it. If the existing pixbuf already had an alpha channel, the channel values are copied from the original; otherwise, the alpha channel is initialized to 255 (full opacity). If `substitute_color` is `TRUE`, then the color specified by the (`r`, `g`, `b`) arguments will be assigned zero opacity. That is, if you pass `(255, 255, 255)` for the substitute color, all white pixels will become fully transparent. If `substitute_color` is `FALSE`, then the (`r`, `g`, `b`) arguments will be ignored. A newly-created pixbuf A #GdkPixbuf. Whether to set a color to zero opacity. Red value to substitute. Green value to substitute. Blue value to substitute. Takes an existing pixbuf and checks for the presence of an associated "orientation" option. The orientation option may be provided by the JPEG loader (which reads the exif orientation tag) or the TIFF loader (which reads the TIFF orientation tag, and compensates it for the partial transforms performed by libtiff). If an orientation option/tag is present, the appropriate transform will be performed so that the pixbuf is oriented correctly. A newly-created pixbuf a pixbuf with an orientation option Creates a transformation of the source image @src by scaling by @scale_x and @scale_y then translating by @offset_x and @offset_y. This gives an image in the coordinates of the destination pixbuf. The rectangle (@dest_x, @dest_y, @dest_width, @dest_height) is then alpha blended onto the corresponding rectangle of the original destination image. When the destination rectangle contains parts not in the source image, the data at the edges of the source image is replicated to infinity. ![](composite.png) a #GdkPixbuf the #GdkPixbuf into which to render the results the left coordinate for region to render the top coordinate for region to render the width of the region to render the height of the region to render the offset in the X direction (currently rounded to an integer) the offset in the Y direction (currently rounded to an integer) the scale factor in the X direction the scale factor in the Y direction the interpolation type for the transformation. overall alpha for source image (0..255) Creates a transformation of the source image @src by scaling by @scale_x and @scale_y then translating by @offset_x and @offset_y, then alpha blends the rectangle (@dest_x ,@dest_y, @dest_width, @dest_height) of the resulting image with a checkboard of the colors @color1 and @color2 and renders it onto the destination image. If the source image has no alpha channel, and @overall_alpha is 255, a fast path is used which omits the alpha blending and just performs the scaling. See gdk_pixbuf_composite_color_simple() for a simpler variant of this function suitable for many tasks. a #GdkPixbuf the #GdkPixbuf into which to render the results the left coordinate for region to render the top coordinate for region to render the width of the region to render the height of the region to render the offset in the X direction (currently rounded to an integer) the offset in the Y direction (currently rounded to an integer) the scale factor in the X direction the scale factor in the Y direction the interpolation type for the transformation. overall alpha for source image (0..255) the X offset for the checkboard (origin of checkboard is at -@check_x, -@check_y) the Y offset for the checkboard the size of checks in the checkboard (must be a power of two) the color of check at upper left the color of the other check Creates a new pixbuf by scaling `src` to `dest_width` x `dest_height` and alpha blending the result with a checkboard of colors `color1` and `color2`. the new pixbuf a #GdkPixbuf the width of destination image the height of destination image the interpolation type for the transformation. overall alpha for source image (0..255) the size of checks in the checkboard (must be a power of two) the color of check at upper left the color of the other check Creates a new `GdkPixbuf` with a copy of the information in the specified `pixbuf`. Note that this does not copy the options set on the original `GdkPixbuf`, use gdk_pixbuf_copy_options() for this. A newly-created pixbuf A pixbuf. Copies a rectangular area from `src_pixbuf` to `dest_pixbuf`. Conversion of pixbuf formats is done automatically. If the source rectangle overlaps the destination rectangle on the same pixbuf, it will be overwritten during the copy operation. Therefore, you can not use this function to scroll a pixbuf. Source pixbuf. Source X coordinate within @src_pixbuf. Source Y coordinate within @src_pixbuf. Width of the area to copy. Height of the area to copy. Destination pixbuf. X coordinate within @dest_pixbuf. Y coordinate within @dest_pixbuf. Copies the key/value pair options attached to a `GdkPixbuf` to another `GdkPixbuf`. This is useful to keep original metadata after having manipulated a file. However be careful to remove metadata which you've already applied, such as the "orientation" option after rotating the image. `TRUE` on success. the source pixbuf the destination pixbuf Clears a pixbuf to the given RGBA value, converting the RGBA value into the pixbuf's pixel format. The alpha component will be ignored if the pixbuf doesn't have an alpha channel. a `GdkPixbuf` RGBA pixel to used to clear (`0xffffffff` is opaque white, `0x00000000` transparent black) Flips a pixbuf horizontally or vertically and returns the result in a new pixbuf. the new pixbuf a #GdkPixbuf `TRUE` to flip horizontally, `FALSE` to flip vertically Queries the number of bits per color sample in a pixbuf. Number of bits per color sample. A pixbuf. Returns the length of the pixel data, in bytes. The length of the pixel data. A pixbuf Queries the color space of a pixbuf. Color space. A pixbuf. Queries whether a pixbuf has an alpha channel (opacity information). `TRUE` if it has an alpha channel, `FALSE` otherwise. A pixbuf. Queries the height of a pixbuf. Height in pixels. A pixbuf. Queries the number of channels of a pixbuf. Number of channels. A pixbuf. Looks up @key in the list of options that may have been attached to the @pixbuf when it was loaded, or that may have been attached by another function using gdk_pixbuf_set_option(). For instance, the ANI loader provides "Title" and "Artist" options. The ICO, XBM, and XPM loaders provide "x_hot" and "y_hot" hot-spot options for cursor definitions. The PNG loader provides the tEXt ancillary chunk key/value pairs as options. Since 2.12, the TIFF and JPEG loaders return an "orientation" option string that corresponds to the embedded TIFF/Exif orientation tag (if present). Since 2.32, the TIFF loader sets the "multipage" option string to "yes" when a multi-page TIFF is loaded. Since 2.32 the JPEG and PNG loaders set "x-dpi" and "y-dpi" if the file contains image density information in dots per inch. Since 2.36.6, the JPEG loader sets the "comment" option with the comment EXIF tag. the value associated with `key` a `GdkPixbuf` a nul-terminated string. Returns a `GHashTable` with a list of all the options that may have been attached to the `pixbuf` when it was loaded, or that may have been attached by another function using [method@GdkPixbuf.Pixbuf.set_option]. a #GHashTable of key/values pairs a `GdkPixbuf` Queries a pointer to the pixel data of a pixbuf. This function will cause an implicit copy of the pixbuf data if the pixbuf was created from read-only data. Please see the section on [image data](class.Pixbuf.html#image-data) for information about how the pixel data is stored in memory. A pointer to the pixbuf's pixel data. A pixbuf. Queries a pointer to the pixel data of a pixbuf. This function will cause an implicit copy of the pixbuf data if the pixbuf was created from read-only data. Please see the section on [image data](class.Pixbuf.html#image-data) for information about how the pixel data is stored in memory. A pointer to the pixbuf's pixel data. A pixbuf. The length of the binary data. Queries the rowstride of a pixbuf, which is the number of bytes between the start of a row and the start of the next row. Distance between row starts. A pixbuf. Queries the width of a pixbuf. Width in pixels. A pixbuf. Creates a new pixbuf which represents a sub-region of `src_pixbuf`. The new pixbuf shares its pixels with the original pixbuf, so writing to one affects both. The new pixbuf holds a reference to `src_pixbuf`, so `src_pixbuf` will not be finalized until the new pixbuf is finalized. Note that if `src_pixbuf` is read-only, this function will force it to be mutable. a new pixbuf a `GdkPixbuf` X coord in @src_pixbuf Y coord in @src_pixbuf width of region in @src_pixbuf height of region in @src_pixbuf Provides a #GBytes buffer containing the raw pixel data; the data must not be modified. This function allows skipping the implicit copy that must be made if gdk_pixbuf_get_pixels() is called on a read-only pixbuf. A new reference to a read-only copy of the pixel data. Note that for mutable pixbufs, this function will incur a one-time copy of the pixel data for conversion into the returned #GBytes. A pixbuf Provides a read-only pointer to the raw pixel data. This function allows skipping the implicit copy that must be made if gdk_pixbuf_get_pixels() is called on a read-only pixbuf. a read-only pointer to the raw pixel data A pixbuf Adds a reference to a pixbuf. Use g_object_ref(). The same as the @pixbuf argument. A pixbuf. Removes the key/value pair option attached to a `GdkPixbuf`. `TRUE` if an option was removed, `FALSE` if not. a `GdkPixbuf` a nul-terminated string representing the key to remove. Rotates a pixbuf by a multiple of 90 degrees, and returns the result in a new pixbuf. If `angle` is 0, this function will return a copy of `src`. the new pixbuf a #GdkPixbuf the angle to rotate by Modifies saturation and optionally pixelates `src`, placing the result in `dest`. The `src` and `dest` pixbufs must have the same image format, size, and rowstride. The `src` and `dest` arguments may be the same pixbuf with no ill effects. If `saturation` is 1.0 then saturation is not changed. If it's less than 1.0, saturation is reduced (the image turns toward grayscale); if greater than 1.0, saturation is increased (the image gets more vivid colors). If `pixelate` is `TRUE`, then pixels are faded in a checkerboard pattern to create a pixelated image. source image place to write modified version of @src saturation factor whether to pixelate Saves pixbuf to a file in format @type. By default, "jpeg", "png", "ico" and "bmp" are possible file formats to save in, but more formats may be installed. The list of all writable formats can be determined in the following way: ```c void add_if_writable (GdkPixbufFormat *data, GSList **list) { if (gdk_pixbuf_format_is_writable (data)) *list = g_slist_prepend (*list, data); } GSList *formats = gdk_pixbuf_get_formats (); GSList *writable_formats = NULL; g_slist_foreach (formats, add_if_writable, &writable_formats); g_slist_free (formats); ``` If `error` is set, `FALSE` will be returned. Possible errors include those in the `GDK_PIXBUF_ERROR` domain and those in the `G_FILE_ERROR` domain. The variable argument list should be `NULL`-terminated; if not empty, it should contain pairs of strings that modify the save parameters. For example: ```c gdk_pixbuf_save (pixbuf, handle, "jpeg", &error, "quality", "100", NULL); ``` Currently only few parameters exist. JPEG images can be saved with a "quality" parameter; its value should be in the range `[0, 100]`. JPEG and PNG density can be set by setting the "x-dpi" and "y-dpi" parameters to the appropriate values in dots per inch. Text chunks can be attached to PNG images by specifying parameters of the form "tEXt::key", where key is an ASCII string of length 1-79. The values are UTF-8 encoded strings. The PNG compression level can be specified using the "compression" parameter; it's value is in an integer in the range of `[0, 9]`. ICC color profiles can also be embedded into PNG, JPEG and TIFF images. The "icc-profile" value should be the complete ICC profile encoded into base64. ```c char *contents; gsize length; // icm_path is set elsewhere g_file_get_contents (icm_path, &contents, &length, NULL); char *contents_encode = g_base64_encode ((const guchar *) contents, length); gdk_pixbuf_save (pixbuf, handle, "png", &error, "icc-profile", contents_encode, NULL); ``` TIFF images recognize: 1. a "bits-per-sample" option (integer) which can be either 1 for saving bi-level CCITTFAX4 images, or 8 for saving 8-bits per sample 2. a "compression" option (integer) which can be 1 for no compression, 2 for Huffman, 5 for LZW, 7 for JPEG and 8 for DEFLATE (see the libtiff documentation and tiff.h for all supported codec values) 3. an "icc-profile" option (zero-terminated string) containing a base64 encoded ICC color profile. ICO images can be saved in depth 16, 24, or 32, by using the "depth" parameter. When the ICO saver is given "x_hot" and "y_hot" parameters, it produces a CUR instead of an ICO. `TRUE` on success, and `FALSE` otherwise a `GdkPixbuf`. name of file to save. name of file format. return location for error list of key-value save options, followed by `NULL` Saves pixbuf to a new buffer in format `type`, which is currently "jpeg", "png", "tiff", "ico" or "bmp". This is a convenience function that uses `gdk_pixbuf_save_to_callback()` to do the real work. Note that the buffer is not `NUL`-terminated and may contain embedded `NUL` characters. If @error is set, `FALSE` will be returned and @buffer will be set to `NULL`. Possible errors include those in the `GDK_PIXBUF_ERROR` domain. See `gdk_pixbuf_save()` for more details. whether an error was set a `GdkPixbuf`. location to receive a pointer to the new buffer. location to receive the size of the new buffer. name of file format. return location for error, or `NULL` list of key-value save options Vector version of `gdk_pixbuf_save_to_buffer()`. Saves pixbuf to a new buffer in format @type, which is currently "jpeg", "tiff", "png", "ico" or "bmp". See [method@GdkPixbuf.Pixbuf.save_to_buffer] for more details. whether an error was set a `GdkPixbuf`. location to receive a pointer to the new buffer. location to receive the size of the new buffer. name of file format. name of options to set values for named options Saves pixbuf in format `type` by feeding the produced data to a callback. This function can be used when you want to store the image to something other than a file, such as an in-memory buffer or a socket. If @error is set, `FALSE` will be returned. Possible errors include those in the `GDK_PIXBUF_ERROR` domain and whatever the save function generates. See [method@GdkPixbuf.Pixbuf.save] for more details. whether an error was set a `GdkPixbuf`. a function that is called to save each block of data that the save routine generates. user data to pass to the save function. name of file format. return location for error, or `NULL` list of key-value save options Vector version of `gdk_pixbuf_save_to_callback()`. Saves pixbuf to a callback in format @type, which is currently "jpeg", "png", "tiff", "ico" or "bmp". If @error is set, `FALSE` will be returned. See [method@GdkPixbuf.Pixbuf.save_to_callback] for more details. whether an error was set a `GdkPixbuf` a function that is called to save each block of data that the save routine generates user data to pass to the save function name of file format name of options to set values for named options Saves `pixbuf` to an output stream. Supported file formats are currently "jpeg", "tiff", "png", "ico" or "bmp". See `gdk_pixbuf_save_to_buffer()` for more details. The `cancellable` can be used to abort the operation from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and `G_IO_ERROR` domains. The stream is not closed at the end of this call. `TRUE` if the pixbuf was saved successfully, `FALSE` if an error was set. a `GdkPixbuf` a `GOutputStream` to save the pixbuf to name of file format optional `GCancellable` object, `NULL` to ignore return location for error, or `NULL` list of key-value save options Saves `pixbuf` to an output stream asynchronously. For more details see gdk_pixbuf_save_to_stream(), which is the synchronous version of this function. When the operation is finished, `callback` will be called in the main thread. You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the operation. a `GdkPixbuf` a `GOutputStream` to which to save the pixbuf name of file format optional `GCancellable` object, `NULL` to ignore a `GAsyncReadyCallback` to call when the pixbuf is saved the data to pass to the callback function list of key-value save options Saves `pixbuf` to an output stream. Supported file formats are currently "jpeg", "tiff", "png", "ico" or "bmp". See [method@GdkPixbuf.Pixbuf.save_to_stream] for more details. `TRUE` if the pixbuf was saved successfully, `FALSE` if an error was set. a `GdkPixbuf` a `GOutputStream` to save the pixbuf to name of file format name of options to set values for named options optional `GCancellable` object, `NULL` to ignore Saves `pixbuf` to an output stream asynchronously. For more details see gdk_pixbuf_save_to_streamv(), which is the synchronous version of this function. When the operation is finished, `callback` will be called in the main thread. You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the operation. a `GdkPixbuf` a `GOutputStream` to which to save the pixbuf name of file format name of options to set values for named options optional `GCancellable` object, `NULL` to ignore a `GAsyncReadyCallback` to call when the pixbuf is saved the data to pass to the callback function Vector version of `gdk_pixbuf_save()`. Saves pixbuf to a file in `type`, which is currently "jpeg", "png", "tiff", "ico" or "bmp". If @error is set, `FALSE` will be returned. See [method@GdkPixbuf.Pixbuf.save] for more details. whether an error was set a `GdkPixbuf`. name of file to save. name of file format. name of options to set values for named options Creates a transformation of the source image @src by scaling by @scale_x and @scale_y then translating by @offset_x and @offset_y, then renders the rectangle (@dest_x, @dest_y, @dest_width, @dest_height) of the resulting image onto the destination image replacing the previous contents. Try to use gdk_pixbuf_scale_simple() first; this function is the industrial-strength power tool you can fall back to, if gdk_pixbuf_scale_simple() isn't powerful enough. If the source rectangle overlaps the destination rectangle on the same pixbuf, it will be overwritten during the scaling which results in rendering artifacts. a #GdkPixbuf the #GdkPixbuf into which to render the results the left coordinate for region to render the top coordinate for region to render the width of the region to render the height of the region to render the offset in the X direction (currently rounded to an integer) the offset in the Y direction (currently rounded to an integer) the scale factor in the X direction the scale factor in the Y direction the interpolation type for the transformation. Create a new pixbuf containing a copy of `src` scaled to `dest_width` x `dest_height`. This function leaves `src` unaffected. The `interp_type` should be `GDK_INTERP_NEAREST` if you want maximum speed (but when scaling down `GDK_INTERP_NEAREST` is usually unusably ugly). The default `interp_type` should be `GDK_INTERP_BILINEAR` which offers reasonable quality and speed. You can scale a sub-portion of `src` by creating a sub-pixbuf pointing into `src`; see [method@GdkPixbuf.Pixbuf.new_subpixbuf]. If `dest_width` and `dest_height` are equal to the width and height of `src`, this function will return an unscaled copy of `src`. For more complicated scaling/alpha blending see [method@GdkPixbuf.Pixbuf.scale] and [method@GdkPixbuf.Pixbuf.composite]. the new pixbuf a #GdkPixbuf the width of destination image the height of destination image the interpolation type for the transformation. Attaches a key/value pair as an option to a `GdkPixbuf`. If `key` already exists in the list of options attached to the `pixbuf`, the new value is ignored and `FALSE` is returned. `TRUE` on success a `GdkPixbuf` a nul-terminated string. a nul-terminated string. Removes a reference from a pixbuf. Use g_object_unref(). A pixbuf. The number of bits per sample. Currently only 8 bit per sample are supported. The color space of the pixbuf. Currently, only `GDK_COLORSPACE_RGB` is supported. Whether the pixbuf has an alpha channel. The number of rows of the pixbuf. The number of samples per pixel. Currently, only 3 or 4 samples per pixel are supported. A pointer to the pixel data of the pixbuf. The number of bytes between the start of a row and the start of the next row. This number must (obviously) be at least as large as the width of the pixbuf. The number of columns of the pixbuf. Control the alpha channel for drawables. These values can be passed to gdk_pixbuf_xlib_render_to_drawable_alpha() in gdk-pixbuf-xlib to control how the alpha channel of an image should be handled. This function can create a bilevel clipping mask (black and white) and use it while painting the image. In the future, when the X Window System gets an alpha channel extension, it will be possible to do full alpha compositing onto arbitrary drawables. For now both cases fall back to a bilevel clipping mask. There is no user of GdkPixbufAlphaMode in GdkPixbuf, and the Xlib utility functions have been split out to their own library, gdk-pixbuf-xlib A bilevel clipping mask (black and white) will be created and used to draw the image. Pixels below 0.5 opacity will be considered fully transparent, and all others will be considered fully opaque. For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL. In the future it will do full alpha compositing. An opaque object representing an animation. The GdkPixBuf library provides a simple mechanism to load and represent animations. An animation is conceptually a series of frames to be displayed over time. The animation may not be represented as a series of frames internally; for example, it may be stored as a sprite and instructions for moving the sprite around a background. To display an animation you don't need to understand its representation, however; you just ask `GdkPixbuf` what should be displayed at a given point in time. Use a different image loading library for animatable assets Creates a new animation by loading it from a file. The file format is detected automatically. If the file's format does not support multi-frame images, then an animation with a single frame will be created. Possible errors are in the `GDK_PIXBUF_ERROR` and `G_FILE_ERROR` domains. Use a different image loading library for animatable assets A newly-created animation Name of file to load, in the GLib file name encoding Creates a new pixbuf animation by loading an image from an resource. The file format is detected automatically. If `NULL` is returned, then @error will be set. Use a different image loading library for animatable assets A newly-created animation the path of the resource file Creates a new animation by loading it from an input stream. The file format is detected automatically. If `NULL` is returned, then @error will be set. The @cancellable can be used to abort the operation from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and `G_IO_ERROR` domains. The stream is not closed. Use a different image loading library for animatable assets A newly-created animation a `GInputStream` to load the pixbuf from optional `GCancellable` object Finishes an asynchronous pixbuf animation creation operation started with [func@GdkPixbuf.PixbufAnimation.new_from_stream_async]. Use a different image loading library for animatable assets the newly created animation a #GAsyncResult Creates a new animation by asynchronously loading an image from an input stream. For more details see gdk_pixbuf_new_from_stream(), which is the synchronous version of this function. When the operation is finished, `callback` will be called in the main thread. You can then call gdk_pixbuf_animation_new_from_stream_finish() to get the result of the operation. Use a different image loading library for animatable assets a #GInputStream from which to load the animation optional #GCancellable object a `GAsyncReadyCallback` to call when the pixbuf is loaded the data to pass to the callback function Get an iterator for displaying an animation. The iterator provides the frames that should be displayed at a given time. @start_time would normally come from g_get_current_time(), and marks the beginning of animation playback. After creating an iterator, you should immediately display the pixbuf returned by gdk_pixbuf_animation_iter_get_pixbuf(). Then, you should install a timeout (with g_timeout_add()) or by some other mechanism ensure that you'll update the image after gdk_pixbuf_animation_iter_get_delay_time() milliseconds. Each time the image is updated, you should reinstall the timeout with the new, possibly-changed delay time. As a shortcut, if @start_time is `NULL`, the result of g_get_current_time() will be used automatically. To update the image (i.e. possibly change the result of gdk_pixbuf_animation_iter_get_pixbuf() to a new frame of the animation), call gdk_pixbuf_animation_iter_advance(). If you're using #GdkPixbufLoader, in addition to updating the image after the delay time, you should also update it whenever you receive the area_updated signal and gdk_pixbuf_animation_iter_on_currently_loading_frame() returns `TRUE`. In this case, the frame currently being fed into the loader has received new data, so needs to be refreshed. The delay time for a frame may also be modified after an area_updated signal, for example if the delay time for a frame is encoded in the data after the frame itself. So your timeout should be reinstalled after any area_updated signal. A delay time of -1 is possible, indicating "infinite". Use a different image loading library for animatable assets an iterator to move over the animation a #GdkPixbufAnimation time when the animation starts playing fills @width and @height with the frame size of the animation. Retrieves a static image for the animation. If an animation is really just a plain image (has only one frame), this function returns that image. If the animation is an animation, this function returns a reasonable image to use as a static unanimated image, which might be the first frame, or something more sophisticated depending on the file format. If an animation hasn't loaded any frames yet, this function will return `NULL`. Use a different image loading library for animatable assets unanimated image representing the animation a #GdkPixbufAnimation Checks whether the animation is a static image. If you load a file with gdk_pixbuf_animation_new_from_file() and it turns out to be a plain, unanimated image, then this function will return `TRUE`. Use gdk_pixbuf_animation_get_static_image() to retrieve the image. Use a different image loading library for animatable assets `TRUE` if the "animation" was really just an image a #GdkPixbufAnimation Queries the height of the bounding box of a pixbuf animation. Use a different image loading library for animatable assets Height of the bounding box of the animation. An animation. Get an iterator for displaying an animation. The iterator provides the frames that should be displayed at a given time. @start_time would normally come from g_get_current_time(), and marks the beginning of animation playback. After creating an iterator, you should immediately display the pixbuf returned by gdk_pixbuf_animation_iter_get_pixbuf(). Then, you should install a timeout (with g_timeout_add()) or by some other mechanism ensure that you'll update the image after gdk_pixbuf_animation_iter_get_delay_time() milliseconds. Each time the image is updated, you should reinstall the timeout with the new, possibly-changed delay time. As a shortcut, if @start_time is `NULL`, the result of g_get_current_time() will be used automatically. To update the image (i.e. possibly change the result of gdk_pixbuf_animation_iter_get_pixbuf() to a new frame of the animation), call gdk_pixbuf_animation_iter_advance(). If you're using #GdkPixbufLoader, in addition to updating the image after the delay time, you should also update it whenever you receive the area_updated signal and gdk_pixbuf_animation_iter_on_currently_loading_frame() returns `TRUE`. In this case, the frame currently being fed into the loader has received new data, so needs to be refreshed. The delay time for a frame may also be modified after an area_updated signal, for example if the delay time for a frame is encoded in the data after the frame itself. So your timeout should be reinstalled after any area_updated signal. A delay time of -1 is possible, indicating "infinite". Use a different image loading library for animatable assets an iterator to move over the animation a #GdkPixbufAnimation time when the animation starts playing Retrieves a static image for the animation. If an animation is really just a plain image (has only one frame), this function returns that image. If the animation is an animation, this function returns a reasonable image to use as a static unanimated image, which might be the first frame, or something more sophisticated depending on the file format. If an animation hasn't loaded any frames yet, this function will return `NULL`. Use a different image loading library for animatable assets unanimated image representing the animation a #GdkPixbufAnimation Queries the width of the bounding box of a pixbuf animation. Use a different image loading library for animatable assets Width of the bounding box of the animation. An animation. Checks whether the animation is a static image. If you load a file with gdk_pixbuf_animation_new_from_file() and it turns out to be a plain, unanimated image, then this function will return `TRUE`. Use gdk_pixbuf_animation_get_static_image() to retrieve the image. Use a different image loading library for animatable assets `TRUE` if the "animation" was really just an image a #GdkPixbufAnimation Adds a reference to an animation. Use g_object_ref(). The same as the @animation argument. An animation. Removes a reference from an animation. Use g_object_unref(). An animation. Modules supporting animations must derive a type from #GdkPixbufAnimation, providing suitable implementations of the virtual functions. Use a different image loading library for animatable assets the parent class returns whether the given animation is just a static image. `TRUE` if the "animation" was really just an image a #GdkPixbufAnimation returns a static image representing the given animation. unanimated image representing the animation a #GdkPixbufAnimation fills @width and @height with the frame size of the animation. returns an iterator for the given animation. an iterator to move over the animation a #GdkPixbufAnimation time when the animation starts playing An opaque object representing an iterator which points to a certain position in an animation. Use a different image loading library for animatable assets Possibly advances an animation to a new frame. Chooses the frame based on the start time passed to gdk_pixbuf_animation_get_iter(). @current_time would normally come from g_get_current_time(), and must be greater than or equal to the time passed to gdk_pixbuf_animation_get_iter(), and must increase or remain unchanged each time gdk_pixbuf_animation_iter_get_pixbuf() is called. That is, you can't go backward in time; animations only play forward. As a shortcut, pass `NULL` for the current time and g_get_current_time() will be invoked on your behalf. So you only need to explicitly pass @current_time if you're doing something odd like playing the animation at double speed. If this function returns `FALSE`, there's no need to update the animation display, assuming the display had been rendered prior to advancing; if `TRUE`, you need to call gdk_pixbuf_animation_iter_get_pixbuf() and update the display with the new pixbuf. Use a different image loading library for animatable assets `TRUE` if the image may need updating a #GdkPixbufAnimationIter current time Gets the number of milliseconds the current pixbuf should be displayed, or -1 if the current pixbuf should be displayed forever. The `g_timeout_add()` function conveniently takes a timeout in milliseconds, so you can use a timeout to schedule the next update. Note that some formats, like GIF, might clamp the timeout values in the image file to avoid updates that are just too quick. The minimum timeout for GIF images is currently 20 milliseconds. Use a different image loading library for animatable assets delay time in milliseconds (thousandths of a second) an animation iterator Gets the current pixbuf which should be displayed. The pixbuf might not be the same size as the animation itself (gdk_pixbuf_animation_get_width(), gdk_pixbuf_animation_get_height()). This pixbuf should be displayed for gdk_pixbuf_animation_iter_get_delay_time() milliseconds. The caller of this function does not own a reference to the returned pixbuf; the returned pixbuf will become invalid when the iterator advances to the next frame, which may happen anytime you call gdk_pixbuf_animation_iter_advance(). Copy the pixbuf to keep it (don't just add a reference), as it may get recycled as you advance the iterator. Use a different image loading library for animatable assets the pixbuf to be displayed an animation iterator Used to determine how to respond to the area_updated signal on #GdkPixbufLoader when loading an animation. The `::area_updated` signal is emitted for an area of the frame currently streaming in to the loader. So if you're on the currently loading frame, you will need to redraw the screen for the updated area. Use a different image loading library for animatable assets `TRUE` if the frame we're on is partially loaded, or the last frame a #GdkPixbufAnimationIter Possibly advances an animation to a new frame. Chooses the frame based on the start time passed to gdk_pixbuf_animation_get_iter(). @current_time would normally come from g_get_current_time(), and must be greater than or equal to the time passed to gdk_pixbuf_animation_get_iter(), and must increase or remain unchanged each time gdk_pixbuf_animation_iter_get_pixbuf() is called. That is, you can't go backward in time; animations only play forward. As a shortcut, pass `NULL` for the current time and g_get_current_time() will be invoked on your behalf. So you only need to explicitly pass @current_time if you're doing something odd like playing the animation at double speed. If this function returns `FALSE`, there's no need to update the animation display, assuming the display had been rendered prior to advancing; if `TRUE`, you need to call gdk_pixbuf_animation_iter_get_pixbuf() and update the display with the new pixbuf. Use a different image loading library for animatable assets `TRUE` if the image may need updating a #GdkPixbufAnimationIter current time Gets the number of milliseconds the current pixbuf should be displayed, or -1 if the current pixbuf should be displayed forever. The `g_timeout_add()` function conveniently takes a timeout in milliseconds, so you can use a timeout to schedule the next update. Note that some formats, like GIF, might clamp the timeout values in the image file to avoid updates that are just too quick. The minimum timeout for GIF images is currently 20 milliseconds. Use a different image loading library for animatable assets delay time in milliseconds (thousandths of a second) an animation iterator Gets the current pixbuf which should be displayed. The pixbuf might not be the same size as the animation itself (gdk_pixbuf_animation_get_width(), gdk_pixbuf_animation_get_height()). This pixbuf should be displayed for gdk_pixbuf_animation_iter_get_delay_time() milliseconds. The caller of this function does not own a reference to the returned pixbuf; the returned pixbuf will become invalid when the iterator advances to the next frame, which may happen anytime you call gdk_pixbuf_animation_iter_advance(). Copy the pixbuf to keep it (don't just add a reference), as it may get recycled as you advance the iterator. Use a different image loading library for animatable assets the pixbuf to be displayed an animation iterator Used to determine how to respond to the area_updated signal on #GdkPixbufLoader when loading an animation. The `::area_updated` signal is emitted for an area of the frame currently streaming in to the loader. So if you're on the currently loading frame, you will need to redraw the screen for the updated area. Use a different image loading library for animatable assets `TRUE` if the frame we're on is partially loaded, or the last frame a #GdkPixbufAnimationIter Modules supporting animations must derive a type from #GdkPixbufAnimationIter, providing suitable implementations of the virtual functions. Use a different image loading library for animatable assets the parent class returns the time in milliseconds that the current frame should be shown. delay time in milliseconds (thousandths of a second) an animation iterator returns the current frame. the pixbuf to be displayed an animation iterator returns whether the current frame of @iter is being loaded. `TRUE` if the frame we're on is partially loaded, or the last frame a #GdkPixbufAnimationIter advances the iterator to @current_time, possibly changing the current frame. `TRUE` if the image may need updating a #GdkPixbufAnimationIter current time A function of this type is responsible for freeing the pixel array of a pixbuf. The gdk_pixbuf_new_from_data() function lets you pass in a pre-allocated pixel array so that a pixbuf can be created from it; in this case you will need to pass in a function of type `GdkPixbufDestroyNotify` so that the pixel data can be freed when the pixbuf is finalized. The pixel array of the pixbuf that is being finalized. User closure data. An error code in the `GDK_PIXBUF_ERROR` domain. Many gdk-pixbuf operations can cause errors in this domain, or in the `G_FILE_ERROR` domain. An image file was broken somehow. Not enough memory. A bad option was passed to a pixbuf save module. Unknown image type. Don't know how to perform the given operation on the type of image at hand. Generic failure code, something went wrong. Only part of the animation was loaded. A `GdkPixbufFormat` contains information about the image format accepted by a module. Only modules should access the fields directly, applications should use the `gdk_pixbuf_format_*` family of functions. the name of the image format the signature of the module the message domain for the `description` a description of the image format the MIME types for the image format typical filename extensions for the image format a combination of `GdkPixbufFormatFlags` a boolean determining whether the loader is disabled` a string containing license information, typically set to shorthands like "GPL", "LGPL", etc. Creates a copy of `format`. the newly allocated copy of a `GdkPixbufFormat`. Use gdk_pixbuf_format_free() to free the resources when done a pixbuf format Frees the resources allocated when copying a `GdkPixbufFormat` using gdk_pixbuf_format_copy() a pixbuf format Returns a description of the format. a description of the format. a `GdkPixbufFormat` Returns the filename extensions typically used for files in the given format. an array of filename extensions a `GdkPixbufFormat` Returns information about the license of the image loader for the format. The returned string should be a shorthand for a well known license, e.g. "LGPL", "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license. a string describing the license of the pixbuf format a pixbuf format Returns the mime types supported by the format. an array of mime types a `GdkPixbufFormat` Returns the name of the format. the name of the format. a `GdkPixbufFormat` Returns whether this image format is disabled. See gdk_pixbuf_format_set_disabled(). whether this image format is disabled. a `GdkPixbufFormat` Returns `TRUE` if the save option specified by @option_key is supported when saving a pixbuf using the module implementing @format. See gdk_pixbuf_save() for more information about option keys. `TRUE` if the specified option is supported a pixbuf format the name of an option Returns whether this image format is scalable. If a file is in a scalable format, it is preferable to load it at the desired size, rather than loading it at the default size and scaling the resulting pixbuf to the desired size. whether this image format is scalable. a `GdkPixbufFormat` Returns whether pixbufs can be saved in the given format. whether pixbufs can be saved in the given format. a `GdkPixbufFormat` Disables or enables an image format. If a format is disabled, GdkPixbuf won't use the image loader for this format to load images. Applications can use this to avoid using image loaders with an inappropriate license, see gdk_pixbuf_format_get_license(). a `GdkPixbufFormat` `TRUE` to disable the format @format Flags which allow a module to specify further details about the supported operations. the module can write out images in the format. the image format is scalable the module is threadsafe. gdk-pixbuf ignores modules that are not marked as threadsafe. (Since 2.28). Incremental image loader. `GdkPixbufLoader` provides a way for applications to drive the process of loading an image, by letting them send the image data directly to the loader instead of having the loader read the data from a file. Applications can use this functionality instead of `gdk_pixbuf_new_from_file()` or `gdk_pixbuf_animation_new_from_file()` when they need to parse image data in small chunks. For example, it should be used when reading an image from a (potentially) slow network connection, or when loading an extremely large file. To use `GdkPixbufLoader` to load an image, create a new instance, and call [method@GdkPixbuf.PixbufLoader.write] to send the data to it. When done, [method@GdkPixbuf.PixbufLoader.close] should be called to end the stream and finalize everything. The loader will emit three important signals throughout the process: - [signal@GdkPixbuf.PixbufLoader::size-prepared] will be emitted as soon as the image has enough information to determine the size of the image to be used. If you want to scale the image while loading it, you can call [method@GdkPixbuf.PixbufLoader.set_size] in response to this signal. - [signal@GdkPixbuf.PixbufLoader::area-prepared] will be emitted as soon as the pixbuf of the desired has been allocated. You can obtain the `GdkPixbuf` instance by calling [method@GdkPixbuf.PixbufLoader.get_pixbuf]. If you want to use it, simply acquire a reference to it. You can also call `gdk_pixbuf_loader_get_pixbuf()` later to get the same pixbuf. - [signal@GdkPixbuf.PixbufLoader::area-updated] will be emitted every time a region is updated. This way you can update a partially completed image. Note that you do not know anything about the completeness of an image from the updated area. For example, in an interlaced image you will need to make several passes before the image is done loading. ## Loading an animation Loading an animation is almost as easy as loading an image. Once the first [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been emitted, you can call [method@GdkPixbuf.PixbufLoader.get_animation] to get the [class@GdkPixbuf.PixbufAnimation] instance, and then call and [method@GdkPixbuf.PixbufAnimation.get_iter] to get a [class@GdkPixbuf.PixbufAnimationIter] to retrieve the pixbuf for the desired time stamp. Creates a new pixbuf loader object. A newly-created pixbuf loader. Creates a new pixbuf loader object that always attempts to parse image data as if it were an image of MIME type @mime_type, instead of identifying the type automatically. This function is useful if you want an error if the image isn't the expected MIME type; for loading image formats that can't be reliably identified by looking at the data; or if the user manually forces a specific MIME type. The list of supported mime types depends on what image loaders are installed, but typically "image/png", "image/jpeg", "image/gif", "image/tiff" and "image/x-xpixmap" are among the supported mime types. To obtain the full list of supported mime types, call gdk_pixbuf_format_get_mime_types() on each of the #GdkPixbufFormat structs returned by gdk_pixbuf_get_formats(). A newly-created pixbuf loader. the mime type to be loaded Creates a new pixbuf loader object that always attempts to parse image data as if it were an image of type @image_type, instead of identifying the type automatically. This function is useful if you want an error if the image isn't the expected type; for loading image formats that can't be reliably identified by looking at the data; or if the user manually forces a specific type. The list of supported image formats depends on what image loaders are installed, but typically "png", "jpeg", "gif", "tiff" and "xpm" are among the supported formats. To obtain the full list of supported image formats, call gdk_pixbuf_format_get_name() on each of the #GdkPixbufFormat structs returned by gdk_pixbuf_get_formats(). A newly-created pixbuf loader. name of the image format to be loaded with the image Informs a pixbuf loader that no further writes with gdk_pixbuf_loader_write() will occur, so that it can free its internal loading structures. This function also tries to parse any data that hasn't yet been parsed; if the remaining data is partial or corrupt, an error will be returned. If `FALSE` is returned, `error` will be set to an error from the `GDK_PIXBUF_ERROR` or `G_FILE_ERROR` domains. If you're just cancelling a load rather than expecting it to be finished, passing `NULL` for `error` to ignore it is reasonable. Remember that this function does not release a reference on the loader, so you will need to explicitly release any reference you hold. `TRUE` if all image data written so far was successfully passed out via the update_area signal A pixbuf loader. Queries the #GdkPixbufAnimation that a pixbuf loader is currently creating. In general it only makes sense to call this function after the [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been emitted by the loader. If the loader doesn't have enough bytes yet, and hasn't emitted the `area-prepared` signal, this function will return `NULL`. The animation that the loader is currently loading A pixbuf loader Obtains the available information about the format of the currently loading image file. A #GdkPixbufFormat A pixbuf loader. Queries the #GdkPixbuf that a pixbuf loader is currently creating. In general it only makes sense to call this function after the [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been emitted by the loader; this means that enough data has been read to know the size of the image that will be allocated. If the loader has not received enough data via gdk_pixbuf_loader_write(), then this function returns `NULL`. The returned pixbuf will be the same in all future calls to the loader, so if you want to keep using it, you should acquire a reference to it. Additionally, if the loader is an animation, it will return the "static image" of the animation (see gdk_pixbuf_animation_get_static_image()). The pixbuf that the loader is creating A pixbuf loader. Causes the image to be scaled while it is loaded. The desired image size can be determined relative to the original size of the image by calling gdk_pixbuf_loader_set_size() from a signal handler for the ::size-prepared signal. Attempts to set the desired image size are ignored after the emission of the ::size-prepared signal. A pixbuf loader. The desired width of the image being loaded. The desired height of the image being loaded. Parses the next `count` bytes in the given image buffer. `TRUE` if the write was successful, or `FALSE` if the loader cannot parse the buffer A pixbuf loader. Pointer to image data. Length of the @buf buffer in bytes. Parses the next contents of the given image buffer. `TRUE` if the write was successful, or `FALSE` if the loader cannot parse the buffer A pixbuf loader. The image data as a `GBytes` buffer. This signal is emitted when the pixbuf loader has allocated the pixbuf in the desired size. After this signal is emitted, applications can call gdk_pixbuf_loader_get_pixbuf() to fetch the partially-loaded pixbuf. This signal is emitted when a significant area of the image being loaded has been updated. Normally it means that a complete scanline has been read in, but it could be a different area as well. Applications can use this signal to know when to repaint areas of an image that is being loaded. X offset of upper-left corner of the updated area. Y offset of upper-left corner of the updated area. Width of updated area. Height of updated area. This signal is emitted when gdk_pixbuf_loader_close() is called. It can be used by different parts of an application to receive notification when an image loader is closed by the code that drives it. This signal is emitted when the pixbuf loader has been fed the initial amount of data that is required to figure out the size of the image that it will create. Applications can call gdk_pixbuf_loader_set_size() in response to this signal to set the desired size to which the image should be scaled. the original width of the image the original height of the image A `GdkPixbufModule` contains the necessary functions to load and save images in a certain file format. If `GdkPixbuf` has been compiled with `GModule` support, it can be extended by modules which can load (and perhaps also save) new image and animation formats. ## Implementing modules The `GdkPixbuf` interfaces needed for implementing modules are contained in `gdk-pixbuf-io.h` (and `gdk-pixbuf-animation.h` if the module supports animations). They are not covered by the same stability guarantees as the regular GdkPixbuf API. To underline this fact, they are protected by the `GDK_PIXBUF_ENABLE_BACKEND` pre-processor symbol. Each loadable module must contain a `GdkPixbufModuleFillVtableFunc` function named `fill_vtable`, which will get called when the module is loaded and must set the function pointers of the `GdkPixbufModule`. In order to make format-checking work before actually loading the modules (which may require calling `dlopen` to load image libraries), modules export their signatures (and other information) via the `fill_info` function. An external utility, `gdk-pixbuf-query-loaders`, uses this to create a text file containing a list of all available loaders and their signatures. This file is then read at runtime by `GdkPixbuf` to obtain the list of available loaders and their signatures. Modules may only implement a subset of the functionality available via `GdkPixbufModule`. If a particular functionality is not implemented, the `fill_vtable` function will simply not set the corresponding function pointers of the `GdkPixbufModule` structure. If a module supports incremental loading (i.e. provides `begin_load`, `stop_load` and `load_increment`), it doesn't have to implement `load`, since `GdkPixbuf` can supply a generic `load` implementation wrapping the incremental loading. ## Installing modules Installing a module is a two-step process: - copy the module file(s) to the loader directory (normally `$libdir/gdk-pixbuf-2.0/$version/loaders`, unless overridden by the environment variable `GDK_PIXBUF_MODULEDIR`) - call `gdk-pixbuf-query-loaders` to update the module file (normally `$libdir/gdk-pixbuf-2.0/$version/loaders.cache`, unless overridden by the environment variable `GDK_PIXBUF_MODULE_FILE`) the name of the module, usually the same as the usual file extension for images of this type, eg. "xpm", "jpeg" or "png". the path from which the module is loaded. the loaded `GModule`. a `GdkPixbufFormat` holding information about the module. loads an image from a file. loads an image from data in memory. begins an incremental load. stops an incremental load. continues an incremental load. loads an animation from a file. saves a `GdkPixbuf` to a file. saves a `GdkPixbuf` by calling the given `GdkPixbufSaveFunc`. returns whether a save option key is supported by the module Sets up the image loading state. The image loader is responsible for storing the given function pointers and user data, and call them when needed. The image loader should set up an internal state object, and return it from this function; the state object will then be updated from the [callback@GdkPixbuf.PixbufModuleIncrementLoadFunc] callback, and will be freed by [callback@GdkPixbuf.PixbufModuleStopLoadFunc] callback. the data to be passed to [callback@GdkPixbuf.PixbufModuleIncrementLoadFunc] and [callback@GdkPixbuf.PixbufModuleStopLoadFunc], or `NULL` in case of error the function to be called when the size is known the function to be called when the data has been prepared the function to be called when the data has been updated the data to be passed to the functions Defines the type of the function used to fill a #GdkPixbufFormat structure with information about a module. a #GdkPixbufFormat. Defines the type of the function used to set the vtable of a #GdkPixbufModule when it is loaded. a #GdkPixbufModule. Incrementally loads a buffer into the image data. `TRUE` if the incremental load was successful the state object created by [callback@GdkPixbuf.PixbufModuleBeginLoadFunc] the data to load the length of the data to load Loads a file from a standard C file stream into a new `GdkPixbufAnimation`. In case of error, this function should return `NULL` and set the `error` argument. a newly created `GdkPixbufAnimation` for the contents of the file the file stream from which the image should be loaded Loads a file from a standard C file stream into a new `GdkPixbuf`. In case of error, this function should return `NULL` and set the `error` argument. a newly created `GdkPixbuf` for the contents of the file the file stream from which the image should be loaded Loads XPM data into a new `GdkPixbuf`. a newly created `GdkPixbuf` for the XPM data the XPM data The signature prefix for a module. The signature of a module is a set of prefixes. Prefixes are encoded as pairs of ordinary strings, where the second string, called the mask, if not `NULL`, must be of the same length as the first one and may contain ' ', '!', 'x', 'z', and 'n' to indicate bytes that must be matched, not matched, "don't-care"-bytes, zeros and non-zeros, respectively. Each prefix has an associated integer that describes the relevance of the prefix, with 0 meaning a mismatch and 100 a "perfect match". Starting with gdk-pixbuf 2.8, the first byte of the mask may be '*', indicating an unanchored pattern that matches not only at the beginning, but also in the middle. Versions prior to 2.8 will interpret the '*' like an 'x'. The signature of a module is stored as an array of `GdkPixbufModulePatterns`. The array is terminated by a pattern where the `prefix` is `NULL`. ```c GdkPixbufModulePattern *signature[] = { { "abcdx", " !x z", 100 }, { "bla", NULL, 90 }, { NULL, NULL, 0 } }; ``` In the example above, the signature matches e.g. "auud\0" with relevance 100, and "blau" with relevance 90. the prefix for this pattern mask containing bytes which modify how the prefix is matched against test data relevance of this pattern Defines the type of the function that gets called once the initial setup of @pixbuf is done. #GdkPixbufLoader uses a function of this type to emit the "<link linkend="GdkPixbufLoader-area-prepared">area_prepared</link>" signal. the #GdkPixbuf that is currently being loaded. if an animation is being loaded, the #GdkPixbufAnimation, else %NULL. the loader. Saves a `GdkPixbuf` by calling the provided function. The optional `option_keys` and `option_values` arrays contain the keys and values (in the same order) for attributes to be saved alongside the image data. `TRUE` on success; in case of failure, `FALSE` is returned and the `error` is set the function to call when saving the data to pass to @save_func the `GdkPixbuf` to save an array of option names an array of option values Saves a `GdkPixbuf` into a standard C file stream. The optional `param_keys` and `param_values` arrays contain the keys and values (in the same order) for attributes to be saved alongside the image data. `TRUE` on success; in case of failure, `FALSE` is returned and the `error` is set the file stream into which the image should be saved the image to save parameter keys to save parameter values to save Checks whether the given `option_key` is supported when saving. `TRUE` if the option is supported the option key to check Defines the type of the function that gets called once the size of the loaded image is known. The function is expected to set @width and @height to the desired size to which the image should be scaled. If a module has no efficient way to achieve the desired scaling during the loading of the image, it may either ignore the size request, or only approximate it - gdk-pixbuf will then perform the required scaling on the completely loaded image. If the function sets @width or @height to zero, the module should interpret this as a hint that it will be closed soon and shouldn't allocate further resources. This convention is used to implement gdk_pixbuf_get_file_info() efficiently. pointer to a location containing the current image width pointer to a location containing the current image height the loader. Finalizes the image loading state. This function is called on success and error states. `TRUE` if the loading operation was successful the state object created by [callback@GdkPixbuf.PixbufModuleBeginLoadFunc] Defines the type of the function that gets called every time a region of @pixbuf is updated. #GdkPixbufLoader uses a function of this type to emit the "<link linkend="GdkPixbufLoader-area-updated">area_updated</link>" signal. the #GdkPixbuf that is currently being loaded. the X origin of the updated area. the Y origin of the updated area. the width of the updated area. the height of the updated area. the loader. The possible rotations which can be passed to gdk_pixbuf_rotate_simple(). To make them easier to use, their numerical values are the actual degrees. No rotation. Rotate by 90 degrees. Rotate by 180 degrees. Rotate by 270 degrees. Save functions used by [method@GdkPixbuf.Pixbuf.save_to_callback]. This function is called once for each block of bytes that is "written" by `gdk_pixbuf_save_to_callback()`. If successful it should return `TRUE`; if an error occurs it should set `error` and return `FALSE`, in which case `gdk_pixbuf_save_to_callback()` will fail with the same error. `TRUE` if successful, `FALSE` otherwise bytes to be written. number of bytes in @buf. A location to return an error. user data passed to gdk_pixbuf_save_to_callback(). An opaque struct representing a simple animation. Creates a new, empty animation. Use a different image loading library for animatable assets a newly allocated #GdkPixbufSimpleAnim the width of the animation the height of the animation the speed of the animation, in frames per second Adds a new frame to @animation. The @pixbuf must have the dimensions specified when the animation was constructed. Use a different image loading library for animatable assets a #GdkPixbufSimpleAnim the pixbuf to add Gets whether @animation should loop indefinitely when it reaches the end. Use a different image loading library for animatable assets %TRUE if the animation loops forever, %FALSE otherwise a #GdkPixbufSimpleAnim Sets whether @animation should loop indefinitely when it reaches the end. Use a different image loading library for animatable assets a #GdkPixbufSimpleAnim whether to loop the animation Whether the animation should loop when it reaches the end. Use a different image loading library for animatable assets soup3-0.9.0/gir-files/GdkPixdata-2.0.gir000064400000000000000000000363301046102023000156110ustar 00000000000000 Magic number for #GdkPixdata structures. The length of a #GdkPixdata structure without the @pixel_data pointer. A pixel buffer suitable for serialization and streaming. Using `GdkPixdata`, images can be compiled into an application, making it unnecessary to refer to external image files at runtime. `GdkPixbuf` includes a utility named `gdk-pixbuf-csource`, which can be used to convert image files into `GdkPixdata` structures suitable for inclusion in C sources. To convert the `GdkPixdata` structures back into a `GdkPixbuf`, use `gdk_pixbuf_from_pixdata()`. `GdkPixdata` should not be used any more. `GResource` should be used to save the original compressed images inside the program's binary magic number. A valid `GdkPixdata` structure must have `GDK_PIXBUF_MAGIC_NUMBER` here less than 1 to disable length checks, otherwise `GDK_PIXDATA_HEADER_LENGTH` plus the length of `pixel_data` information about colorspace, sample width and encoding, in a `GdkPixdataType` Distance in bytes between rows Width of the image in pixels Height of the image in pixels `width` x `height` pixels, encoded according to `pixdata_type` and `rowstride` Deserializes (reconstruct) a #GdkPixdata structure from a byte stream. The byte stream consists of a straightforward writeout of the `GdkPixdata` fields in network byte order, plus the `pixel_data` bytes the structure points to. The `pixdata` contents are reconstructed byte by byte and are checked for validity. This function may fail with `GDK_PIXBUF_ERROR_CORRUPT_IMAGE` or `GDK_PIXBUF_ERROR_UNKNOWN_TYPE`. Use `GResource` instead. Upon successful deserialization `TRUE` is returned, `FALSE` otherwise. a #GdkPixdata structure to be filled in. length of the stream used for deserialization. stream of bytes containing a serialized #GdkPixdata structure. Converts a `GdkPixbuf` to a `GdkPixdata`. If `use_rle` is `TRUE`, the pixel data is run-length encoded into newly-allocated memory and a pointer to that memory is returned. Use #GResource instead. If `use_rle` is `TRUE`, a pointer to the newly-allocated memory for the run-length encoded pixel data, otherwise `NULL`. a `GdkPixdata` to fill. the data to fill `pixdata` with. whether to use run-length encoding for the pixel data. Serializes a #GdkPixdata structure into a byte stream. The byte stream consists of a straightforward writeout of the #GdkPixdata fields in network byte order, plus the @pixel_data bytes the structure points to. Use #GResource instead. A newly-allocated string containing the serialized #GdkPixdata structure. a valid #GdkPixdata structure to serialize. location to store the resulting stream length in. Generates C source code suitable for compiling images directly into programs. GdkPixbuf ships with a program called `gdk-pixbuf-csource`, which offers a command line interface to this function. Use #GResource instead. a newly-allocated string buffer containing the C source form of `pixdata`. a `GdkPixdata` to convert to C source used for naming generated data structures or macros the kind of C source to be generated An enumeration which is used by gdk_pixdata_to_csource() to determine the form of C source to be generated. The three values @GDK_PIXDATA_DUMP_PIXDATA_STREAM, @GDK_PIXDATA_DUMP_PIXDATA_STRUCT and @GDK_PIXDATA_DUMP_MACROS are mutually exclusive, as are @GDK_PIXBUF_DUMP_GTYPES and @GDK_PIXBUF_DUMP_CTYPES. The remaining elements are optional flags that can be freely added. Generate pixbuf data stream (a single string containing a serialized #GdkPixdata structure in network byte order). Generate #GdkPixdata structure (needs the #GdkPixdata structure definition from gdk-pixdata.h). Generate <function>*_ROWSTRIDE</function>, <function>*_WIDTH</function>, <function>*_HEIGHT</function>, <function>*_BYTES_PER_PIXEL</function> and <function>*_RLE_PIXEL_DATA</function> or <function>*_PIXEL_DATA</function> macro definitions for the image. Generate GLib data types instead of standard C data types. Generate standard C data types instead of GLib data types. Generate static symbols. Generate const symbols. Provide a <function>*_RUN_LENGTH_DECODE(image_buf, rle_data, size, bpp)</function> macro definition to decode run-length encoded image data. An enumeration containing three sets of flags for a #GdkPixdata struct: one for the used colorspace, one for the width of the samples and one for the encoding of the pixel data. each pixel has red, green and blue samples. each pixel has red, green and blue samples and an alpha value. mask for the colortype flags of the enum. each sample has 8 bits. mask for the sample width flags of the enum. the pixel data is in raw form. the pixel data is run-length encoded. Runs may be up to 127 bytes long; their length is stored in a single byte preceding the pixel data for the run. If a run is constant, its length byte has the high bit set and the pixel data consists of a single pixel which must be repeated. mask for the encoding flags of the enum. Converts a `GdkPixdata` to a `GdkPixbuf`. If `copy_pixels` is `TRUE` or if the pixel data is run-length-encoded, the pixel data is copied into newly-allocated memory; otherwise it is reused. Use `GResource` instead. a new pixbuf a #GdkPixdata to convert into a `GdkPixbuf`. whether to copy raw pixel data; run-length encoded pixel data is always copied. soup3-0.9.0/gir-files/GdkWayland-4.0.gir000064400000000000000000000740561046102023000156270ustar 00000000000000 The Wayland implementation of `GdkDevice`. Beyond the regular [class@Gdk.Device] API, the Wayland implementation provides access to Wayland objects such as the `wl_seat` with [method@GdkWayland.WaylandDevice.get_wl_seat], the `wl_keyboard` with [method@GdkWayland.WaylandDevice.get_wl_keyboard] and the `wl_pointer` with [method@GdkWayland.WaylandDevice.get_wl_pointer]. Returns the `/dev/input/event*` path of this device. For `GdkDevice`s that possibly coalesce multiple hardware devices (eg. mouse, keyboard, touch,...), this function will return %NULL. This is most notably implemented for devices of type %GDK_SOURCE_PEN, %GDK_SOURCE_TABLET_PAD. the `/dev/input/event*` path of this device a `GdkDevice` Returns the Wayland `wl_keyboard` of a `GdkDevice`. a Wayland `wl_keyboard` a `GdkDevice` Returns the Wayland `wl_pointer` of a `GdkDevice`. a Wayland `wl_pointer` a `GdkDevice` Returns the Wayland `wl_seat` of a `GdkDevice`. a Wayland `wl_seat` a `GdkDevice` Returns the `xkb_keymap` of a `GdkDevice`. a `struct xkb_keymap` a `GdkDevice` The Wayland implementation of `GdkDisplay`. Beyond the regular [class@Gdk.Display] API, the Wayland implementation provides access to Wayland objects such as the `wl_display` with [method@GdkWayland.WaylandDisplay.get_wl_display], the `wl_compositor` with [method@GdkWayland.WaylandDisplay.get_wl_compositor]. You can find out what Wayland globals are supported by a display with [method@GdkWayland.WaylandDisplay.query_registry]. Retrieves the EGL display connection object for the given GDK display. the EGL display a Wayland display Gets the startup notification ID for a Wayland display, or `NULL` if no ID has been defined. the startup notification ID for @display a display Returns the Wayland `wl_compositor` of a display. a Wayland `wl_compositor` a display Returns the Wayland `wl_display` of a display. a Wayland `wl_display` a display Returns true if the interface was found in the display `wl_registry.global` handler. true if the global is offered by the compositor a display global interface to query in the registry Sets the cursor theme for the given @display. Use the cursor-related properties of [GtkSettings](../gtk4/class.Settings.html) to set the cursor theme a display the new cursor theme the size to use for cursors Sets the startup notification ID for a display. This is usually taken from the value of the `DESKTOP_STARTUP_ID` environment variable, but in some cases (such as the application not being launched using exec()) it can come from other sources. The startup ID is also what is used to signal that the startup is complete (for example, when opening a window or when calling [method@Gdk.Display.notify_startup_complete]). Use [method@Gdk.Toplevel.set_startup_id] a display the startup notification ID (must be valid utf8) The Wayland implementation of `GdkGLContext`. The Wayland implementation of `GdkMonitor`. Beyond the [class@Gdk.Monitor] API, the Wayland implementation offers access to the Wayland `wl_output` object with [method@GdkWayland.WaylandMonitor.get_wl_output]. Returns the Wayland `wl_output` of a `GdkMonitor`. a Wayland `wl_output` a `GdkMonitor` The Wayland implementation of `GdkPopup`. The Wayland implementation of `GdkSeat`. Beyond the regular [class@Gdk.Seat] API, the Wayland implementation provides access to the Wayland `wl_seat` object with [method@GdkWayland.WaylandSeat.get_wl_seat]. Returns the Wayland `wl_seat` of a `GdkSeat`. a Wayland `wl_seat` a `GdkSeat` The Wayland implementation of `GdkSurface`. Beyond the [class@Gdk.Surface] API, the Wayland implementation offers access to the Wayland `wl_surface` object with [method@GdkWayland.WaylandSurface.get_wl_surface]. Forces next commit. a `GdkSurface` Returns the Wayland `wl_surface` of a `GdkSurface`. a Wayland `wl_surface` a `GdkSurface` The Wayland implementation of `GdkToplevel`. Beyond the [iface@Gdk.Toplevel] API, the Wayland implementation has API to set up cross-process parent-child relationships between surfaces with [method@GdkWayland.WaylandToplevel.export_handle] and [method@GdkWayland.WaylandToplevel.set_transient_for_exported]. Destroy a handle that was obtained with gdk_wayland_toplevel_export_handle(). Note that this API depends on an unstable Wayland protocol, and thus may require changes in the future. the `GdkToplevel` that was exported the handle to drop Asynchronously obtains a handle for a surface that can be passed to other processes. When the handle has been obtained, @callback will be called. It is an error to call this function on a surface that is already exported. When the handle is no longer needed, [method@GdkWayland.WaylandToplevel.unexport_handle] should be called to clean up resources. The main purpose for obtaining a handle is to mark a surface from another surface as transient for this one, see [method@GdkWayland.WaylandToplevel.set_transient_for_exported]. Before 4.12, this API could not safely be used multiple times, since there was no reference counting for handles. Starting with 4.12, every call to this function obtains a new handle, and every call to [method@GdkWayland.WaylandToplevel.drop_exported_handle] drops just the handle that it is given. Note that this API depends on an unstable Wayland protocol, and thus may require changes in the future. %TRUE if the handle has been requested, %FALSE if an error occurred. the `GdkToplevel` to obtain a handle for callback to call with the handle user data for @callback destroy notify for @user_data Sets the application id on a `GdkToplevel`. a `GdkToplevel` the application id for the @toplevel Marks @toplevel as transient for the surface to which the given @parent_handle_str refers. Typically, the handle will originate from a [method@GdkWayland.WaylandToplevel.export_handle] call in another process. Note that this API depends on an unstable Wayland protocol, and thus may require changes in the future. %TRUE if the surface has been marked as transient, %FALSE if an error occurred. the `GdkToplevel` to make as transient an exported handle for a surface Destroys the handle that was obtained with gdk_wayland_toplevel_export_handle(). It is an error to call this function on a surface that does not have a handle. Since 4.12, this function does nothing. Use [method@GdkWayland.WaylandToplevel.drop_exported_handle] instead to drop a handle that was obtained with [method@GdkWayland.WaylandToplevel.export_handle]. Note that this API depends on an unstable Wayland protocol, and thus may require changes in the future. Use [method@GdkWayland.WaylandToplevel.drop_exported_handle] instead, this function does nothing the `GdkToplevel` to unexport Callback that gets called when the handle for a surface has been obtained from the Wayland compositor. This callback is used in [method@GdkWayland.WaylandToplevel.export_handle]. The @handle can be passed to other processes, for the purpose of marking surfaces as transient for out-of-process surfaces. the `GdkToplevel` that is exported the handle user data that was passed to [method@GdkWayland.WaylandToplevel.export_handle] soup3-0.9.0/gir-files/GdkWin32-4.0.gir000064400000000000000000001340031046102023000151170ustar 00000000000000 Error enumeration for GTK's Direct3D 12 integration. D3D12 support is not available, because the OS is not Windows, the Windows version is not recent enough, or it was explicitly disabled at compile- or runtime The requested format is not supported GTK failed to create the resource for other reasons A `GdkTexture` representing a [ID3D12Resource](https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nn-d3d12-id3d12resource). To create a `GdkD3D12Texture`, use the auxiliary [class@Gdk.Win32.D3d12TextureBuilder] object. D3D12 textures can only be created on Windows. `GdkD3D12TextureBuilder` is a builder used to construct [class@Gdk.Texture] objects from [ID3D12Resources](https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nn-d3d12-id3d12resource). The operation of `GdkD3D12TextureBuilder` is quite simple: Create a texture builder, set all the necessary properties, and then call [method@Gdk.D3d12TextureBuilder.build] to create the new texture. Not all `D3D12Resources` can be used. You have to use a texture resource for a `GdkTexture`. GDK will attempt to detect invalid resources and fail to create the texture in that case. `GdkD3D12TextureBuilder` can be used for quick one-shot construction of textures as well as kept around and reused to construct multiple textures. Creates a new texture builder. the new `GdkTextureBuilder` Builds a new `GdkTexture` with the values set up in the builder. It is a programming error to call this function if any mandatory property has not been set. Not all formats defined in the `drm_fourcc.h` header are supported. You can use [method@Gdk.Display.get_d3d12_formats] to get a list of supported formats. If the format is not supported by GTK, %NULL will be returned and @error will be set. The `destroy` function gets called when the returned texture gets released. It is the responsibility of the caller to keep the file descriptors for the planes open until the created texture is no longer used, and close them afterwards (possibly using the @destroy notify). It is possible to call this function multiple times to create multiple textures, possibly with changing properties in between. a newly built `GdkTexture` or `NULL` if the format is not supported a `GdkD3D12TextureBuilder` destroy function to be called when the texture is released user data to pass to the destroy function Gets the color state previously set via gdk_d3d12_texture_builder_set_color_state(). the color state a `GdkD3D12TextureBuilder` Returns the fence that this texture builder is associated with. the fence a `GdkD3D12TextureBuilder` Returns the value that GTK should wait for on the fence before using the resource. the fence wait value a `GdkD3D12TextureBuilder` Whether the data is premultiplied. whether the data is premultiplied a `GdkD3D12TextureBuilder` Returns the resource that this texture builder is associated with. the resource a `GdkD3D12TextureBuilder` Gets the region previously set via gdk_d3d12_texture_builder_set_update_region() or %NULL if none was set. The region a `GdkD3D12TextureBuilder` Gets the texture previously set via gdk_d3d12_texture_builder_set_update_texture() or %NULL if none was set. The texture a `GdkD3D12TextureBuilder` Sets the color state for the texture. By default, the colorstate is `NULL`. In that case, GTK will choose the correct colorstate based on the format. If you don't know what colorstates are, this is probably the right thing. a `GdkD3D12TextureBuilder` a `GdkColorState` or `NULL` to unset the colorstate. Sets the fence that this texture builder is going to construct a texture for. a `GdkD3D12TextureBuilder` the fence Sets the value that GTK should wait on on the given fence before using the resource. When no fence is set, this value has no effect. a `GdkD3D12TextureBuilder` the value to wait on Sets whether the data is premultiplied. Unless otherwise specified, all formats including alpha channels are assumed to be premultiplied. a `GdkD3D12TextureBuilder` whether the data is premultiplied Sets the resource that this texture builder is going to construct a texture for. a `GdkD3D12TextureBuilder` the resource Sets the region to be updated by this texture. Together with [property@Gdk.D3d12TextureBuilder:update-texture] this describes an update of a previous texture. When rendering animations of large textures, it is possible that consecutive textures are only updating contents in parts of the texture. It is then possible to describe this update via these two properties, so that GTK can avoid rerendering parts that did not change. An example would be a screen recording where only the mouse pointer moves. a `GdkD3D12TextureBuilder` the region to update Sets the texture to be updated by this texture. See [method@Gdk.D3d12TextureBuilder.set_update_region] for an explanation. a `GdkD3D12TextureBuilder` the texture to update The color state of the texture. The optional `ID3D12Fence` to wait on before using the resource. The value the fence should wait on Whether the alpha channel is premultiplied into the others. Only relevant if the format has alpha. The `ID3D12Resource` The update region for [property@Gdk.D3d12TextureBuilder:update-texture]. The texture [property@Gdk.D3d12TextureBuilder:update-region] is an update for. Retrieves the version of the WGL implementation. %TRUE if WGL is available a `GdkDisplay` return location for the WGL major version return location for the WGL minor version Adds an event filter to @window, allowing you to intercept messages before they reach GDK. This is a low-level operation and makes it easy to break GDK and/or GTK, so you have to know what you're doing. a `GdkWin32Display` filter callback data to pass to filter callback Retrieves the EGL display connection object for the given GDK display. the EGL display a Win32 display Returns the Win32 HCURSOR wrapper object belonging to a `GdkCursor`, potentially creating the cursor object. Be aware that the returned cursor may not be unique to @cursor. It may for example be shared with its fallback cursor. a GdkWin32HCursor a `GdkDisplay` a `GdkCursor` Remove a filter previously added with gdk_win32_display_add_filter(). A `GdkWin32Display` previously-added filter function user data for previously-added filter function Sets the cursor theme from which the images for cursor should be taken. If the windowing system supports it, existing cursors created with [ctor@Gdk.Cursor.new_from_name] are updated to reflect the theme change. Custom cursors constructed with [ctor@Gdk.Cursor.new_from_texture] will have to be handled by the application (GTK applications can learn about cursor theme changes by listening for change notification for the corresponding `GtkSetting`). a `GdkDisplay` the name of the cursor theme to use, or %NULL to unset a previously set value the cursor size to use, or 0 to keep the previous size Specifies the type of function used to filter Windows messages before they are processed by GDK Win32 backend. The @return_value must be set, if this function returns `GDK_WIN32_MESSAGE_FILTER_REMOVE`, otherwise it is ignored. The event translation and message filtering are orthogonal - if a filter wants a GDK event queued, it should do that itself. a `GdkWin32MessageFilterReturn` value. a location to store the return value for the message user data set when the filter was installed. Specifies the result of applying a `GdkWin32MessageFilterFunc` to a Windows message. event not handled, continue processing. event handled, terminate processing. Retrieves the size and position of the “work area” on a monitor within the display coordinate space. The returned geometry is in ”application pixels”, not in ”device pixels” (see [method@Gdk.Monitor.get_scale_factor]). a `GdkMonitor` a `GdkRectangle` to be filled with the monitor workarea Use gdk_win32_surface_get_handle() instead. the associated @surface HWND handle. a `GdkSurface` Use `GDK_IS_WIN32_SURFACE` instead. %TRUE if the @surface is a win32 implemented surface. a `GdkSurface` the %GdkSurface associated with the given @anid, or %NULL. a %GdkDisplay a HWND window handle Returns the HWND handle belonging to @surface. the associated HWND handle. a native `GdkSurface`. Flashes the specified @surface. a native `GdkSurface`. if %TRUE, flashes both the window and the taskbar button continuously. Registers an error quark for [class@Gdk.Win32.D3d12Texture] errors. the error quark soup3-0.9.0/gir-files/GdkX11-3.0.gir000064400000000000000000002546201046102023000145750ustar 00000000000000 Returns the X cursor belonging to a #GdkCursor. a #GdkCursor. Returns the display of a #GdkCursor. a #GdkCursor. Converts a @gpointer back to an XID that was previously converted using GDK_XID_TO_POINTER(). pointer to extract an XID from Obtains the Xlib window id of the root window of the current screen. Returns the display of a X11 #GdkScreen. a #GdkScreen Returns the index of a X11 #GdkScreen. a #GdkScreen Returns the screen of a X11 #GdkScreen. a #GdkScreen Returns the display of a #GdkWindow. a #GdkWindow. Returns the X window belonging to a #GdkWindow. a #GdkWindow. Returns the X cursor belonging to a #GdkCursor. an Xlib Cursor. a #GdkCursor. Returns the display of a #GdkCursor. an Xlib Display*. a #GdkCursor. Retrieves the version of the GLX implementation. %TRUE if GLX is available a #GdkDisplay return location for the GLX major version return location for the GLX minor version Sends a startup notification message of type @message_type to @display. This is a convenience function for use by code that implements the freedesktop startup notification specification. Applications should not normally need to call it directly. See the [Startup Notification Protocol specification](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt) for definitions of the message types and keys that can be used. a #GdkDisplay startup notification message type ("new", "change", or "remove") a list of key/value pairs (as strings), terminated by a %NULL key. (A %NULL value for a key will cause that key to be skipped in the output.) Pops the error trap pushed by gdk_x11_display_error_trap_push(). Will XSync() if necessary and will always block until the error is known to have occurred or not occurred, so the error code can be returned. If you don’t need to use the return value, gdk_x11_display_error_trap_pop_ignored() would be more efficient. See gdk_error_trap_pop() for the all-displays-at-once equivalent. X error code or 0 on success the display Pops the error trap pushed by gdk_x11_display_error_trap_push(). Does not block to see if an error occurred; merely records the range of requests to ignore errors for, and ignores those errors if they arrive asynchronously. See gdk_error_trap_pop_ignored() for the all-displays-at-once equivalent. the display Begins a range of X requests on @display for which X error events will be ignored. Unignored errors (when no trap is pushed) will abort the application. Use gdk_x11_display_error_trap_pop() or gdk_x11_display_error_trap_pop_ignored()to lift a trap pushed with this function. See also gdk_error_trap_push() to push a trap on all displays. a #GdkDisplay Gets the startup notification ID for a display. the startup notification ID for @display a #GdkDisplay Returns the timestamp of the last user interaction on @display. The timestamp is taken from events caused by user interaction such as key presses or pointer movements. See gdk_x11_window_set_user_time(). the timestamp of the last user interaction a #GdkDisplay Returns the X display of a #GdkDisplay. an X display a #GdkDisplay Call XGrabServer() on @display. To ungrab the display again, use gdk_x11_display_ungrab(). gdk_x11_display_grab()/gdk_x11_display_ungrab() calls can be nested. a #GdkDisplay Sets the cursor theme from which the images for cursor should be taken. If the windowing system supports it, existing cursors created with gdk_cursor_new(), gdk_cursor_new_for_display() and gdk_cursor_new_from_name() are updated to reflect the theme change. Custom cursors constructed with gdk_cursor_new_from_pixbuf() will have to be handled by the application (GTK+ applications can learn about cursor theme changes by listening for change notification for the corresponding #GtkSetting). a #GdkDisplay the name of the cursor theme to use, or %NULL to unset a previously set value the cursor size to use, or 0 to keep the previous size Sets the startup notification ID for a display. This is usually taken from the value of the DESKTOP_STARTUP_ID environment variable, but in some cases (such as the application not being launched using exec()) it can come from other sources. If the ID contains the string "_TIME" then the portion following that string is taken to be the X11 timestamp of the event that triggered the application to be launched and the GDK current event time is set accordingly. The startup ID is also what is used to signal that the startup is complete (for example, when opening a window or when calling gdk_notify_startup_complete()). a #GdkDisplay the startup notification ID (must be valid utf8) Forces a specific window scale for all windows on this display, instead of using the default or user configured scale. This is can be used to disable scaling support by setting @scale to 1, or to programmatically set the window scale. Once the scale is set by this call it will not change in response to later user configuration changes. the display The new scale value Convert a string from the encoding of the current locale into a form suitable for storing in a window property. 0 upon success, non-zero upon failure the #GdkDisplay where the encoding is defined a nul-terminated string location to store the encoding atom (to be used as the type for the property) location to store the format of the property location to store newly allocated data for the property the length of @ctext, in bytes Convert a text string from the encoding as it is stored in a property into an array of strings in the encoding of the current locale. (The elements of the array represent the nul-separated elements of the original text string.) the number of strings stored in list, or 0, if the conversion failed The #GdkDisplay where the encoding is defined an atom representing the encoding. The most common values for this are STRING, or COMPOUND_TEXT. This is value used as the type for the property the format of the property The text data The number of items to transform location to store an array of strings in the encoding of the current locale. This array should be freed using gdk_free_text_list(). Ungrab @display after it has been grabbed with gdk_x11_display_grab(). a #GdkDisplay Converts from UTF-8 to compound text. %TRUE if the conversion succeeded, otherwise %FALSE a #GdkDisplay a UTF-8 string location to store resulting encoding location to store format of the result location to store the data of the result location to store the length of the data stored in @ctext Extracts the group from the state field sent in an X Key event. This is only needed for code processing raw X events, since #GdkEventKey directly includes an is_modifier field. the index of the active keyboard group for the event a #GdkX11Keymap raw state returned from X Determines whether a particular key code represents a key that is a modifier. That is, it’s a key that normally just affects the keyboard state and the behavior of other keys rather than producing a direct effect itself. This is only needed for code processing raw X events, since #GdkEventKey directly includes an is_modifier field. %TRUE if the hardware keycode is a modifier key a #GdkX11Keymap the hardware keycode from a key event Returns the current workspace for @screen when running under a window manager that supports multiple workspaces, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification. the current workspace, or 0 if workspaces are not supported a #GdkScreen Gets the XID of the specified output/monitor. If the X server does not support version 1.2 of the RANDR extension, 0 is returned. the XID of the monitor a #GdkScreen number of the monitor, between 0 and gdk_screen_get_n_monitors (screen) Returns the number of workspaces for @screen when running under a window manager that supports multiple workspaces, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification. the number of workspaces, or 0 if workspaces are not supported a #GdkScreen Returns the index of a #GdkScreen. the position of @screen among the screens of its display a #GdkScreen Returns the name of the window manager for @screen. the name of the window manager screen @screen, or "unknown" if the window manager is unknown. The string is owned by GDK and should not be freed. a #GdkScreen Returns the screen of a #GdkScreen. an Xlib Screen* a #GdkScreen Looks up the #GdkVisual for a particular screen and X Visual ID. the #GdkVisual (owned by the screen object), or %NULL if the visual ID wasn’t found. a #GdkScreen. an X Visual ID. This function is specific to the X11 backend of GDK, and indicates whether the window manager supports a certain hint from the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification. When using this function, keep in mind that the window manager can change over time; so you shouldn’t use this function in a way that impacts persistent application state. A common bug is that your application can start up before the window manager does when the user logs in, and before the window manager starts gdk_x11_screen_supports_net_wm_hint() will return %FALSE for every property. You can monitor the window_manager_changed signal on #GdkScreen to detect a window manager change. %TRUE if the window manager supports @property the relevant #GdkScreen. a property atom. Returns the X visual belonging to a #GdkVisual. an Xlib Visual*. a #GdkVisual. Wraps a native window in a #GdkWindow. The function will try to look up the window using gdk_x11_window_lookup_for_display() first. If it does not find it there, it will create a new window. This may fail if the window has been destroyed. If the window was already known to GDK, a new reference to the existing #GdkWindow is returned. a #GdkWindow wrapper for the native window, or %NULL if the window has been destroyed. The wrapper will be newly created, if one doesn’t exist already. the #GdkDisplay where the window handle comes from. an Xlib Window Looks up the #GdkWindow that wraps the given native window handle. the #GdkWindow wrapper for the native window, or %NULL if there is none. the #GdkDisplay corresponding to the window handle an Xlib Window Gets the number of the workspace @window is on. the current workspace of @window a #GdkWindow Returns the X resource (window) belonging to a #GdkWindow. the ID of @drawable’s X resource. a native #GdkWindow. Moves the window to the correct workspace when running under a window manager that supports multiple workspaces, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification. Will not do anything if the window is already on all workspaces. a #GdkWindow Moves the window to the given workspace when running unde a window manager that supports multiple workspaces, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification. a #GdkWindow the number of the workspace to move the window to This is the same as gdk_window_set_shadow_width() but it only works on GdkX11Window. Use gdk_window_set_shadow_width() instead. a #GdkWindow The left extent The right extent The top extent The bottom extent This function can be used to disable frame synchronization for a window. Normally frame synchronziation will be enabled or disabled based on whether the system has a compositor that supports frame synchronization, but if the window is not directly managed by the window manager, then frame synchronziation may need to be disabled. This is the case for a window embedded via the XEMBED protocol. a native #GdkWindow whether frame-synchronization should be enabled Set a hint for the window manager, requesting that the titlebar should be hidden when the window is maximized. Note that this property is automatically updated by GTK+, so this function should only be used by applications which do not use GTK+ to create toplevel windows. a #GdkWindow whether to hide the titlebar when maximized GTK+ applications can request a dark theme variant. In order to make other applications - namely window managers using GTK+ for themeing - aware of this choice, GTK+ uses this function to export the requested theme variant as _GTK_THEME_VARIANT property on toplevel windows. Note that this property is automatically updated by GTK+, so this function should only be used by applications which do not use GTK+ to create toplevel windows. a #GdkWindow the theme variant to export The application can use this call to update the _NET_WM_USER_TIME property on a toplevel window. This property stores an Xserver time which represents the time of the last user input event received for this window. This property may be used by the window manager to alter the focus, stacking, and/or placement behavior of windows when they are mapped depending on whether the new window was created by a user action or is a "pop-up" window activated by a timer or some other event. Note that this property is automatically updated by GDK, so this function should only be used by applications which handle input events bypassing GDK. A toplevel #GdkWindow An XServer timestamp to which the property should be set This function modifies or removes an arbitrary X11 window property of type UTF8_STRING. If the given @window is not a toplevel window, it is ignored. a #GdkWindow Property name, will be interned as an X atom Property value, or %NULL to delete Converts an XID into a @gpointer. This is useful with data structures that use pointer arguments such as #GHashTable. Use GDK_POINTER_TO_XID() to convert the argument back to an XID. XID to stuff into the pointer Converts from a #GdkAtom to the X atom for the default GDK display with the same string value. the X atom corresponding to @atom. A #GdkAtom Converts from a #GdkAtom to the X atom for a #GdkDisplay with the same string value. The special value %GDK_NONE is converted to %None. the X atom corresponding to @atom, or %None A #GdkDisplay A #GdkAtom, or %GDK_NONE Returns the device ID as seen by XInput2. > If gdk_disable_multidevice() has been called, this function > will respectively return 2/3 for the core pointer and keyboard, > (matching the IDs for the Virtual Core Pointer and Keyboard in > XInput 2), but calling this function on any slave devices (i.e. > those managed via XInput 1.x), will return 0. the XInput2 device ID. a #GdkDevice Returns the #GdkDevice that wraps the given device ID. The #GdkDevice wrapping the device ID, or %NULL if the given ID doesn’t currently represent a device. a #GdkDeviceManager a device ID, as understood by the XInput2 protocol Frees the data returned from gdk_x11_display_string_to_compound_text(). The pointer stored in @ctext from a call to gdk_x11_display_string_to_compound_text(). Frees the array of strings created by gdk_x11_display_text_property_to_text_list(). the value stored in the @list parameter by a call to gdk_x11_display_text_property_to_text_list(). Gets the root window of the default screen (see gdk_x11_get_default_screen()). an Xlib Window. Gets the default GTK+ screen number. returns the screen number specified by the --display command line option or the DISPLAY environment variable when gdk_init() calls XOpenDisplay(). Gets the default GTK+ display. the Xlib Display* for the display specified in the `--display` command line option or the `DISPLAY` environment variable. Used with gdk_window_set_background_pattern() to inherit background from parent window. Useful for imitating transparency when compositing is not available. Otherwise behaves like a transparent pattern. Don't use this function Routine to get the current X server time stamp. the time stamp. a #GdkWindow, used for communication with the server. The window must have GDK_PROPERTY_CHANGE_MASK in its events mask or a hang will result. Returns the X atom for GDK’s default display corresponding to @atom_name. This function caches the result, so if called repeatedly it is much faster than XInternAtom(), which is a round trip to the server each time. a X atom for GDK’s default display. a string Returns the X atom for a #GdkDisplay corresponding to @atom_name. This function caches the result, so if called repeatedly it is much faster than XInternAtom(), which is a round trip to the server each time. a X atom for a #GdkDisplay a #GdkDisplay a string Returns the name of an X atom for GDK’s default display. This function is meant mainly for debugging, so for convenience, unlike XAtomName() and gdk_atom_name(), the result doesn’t need to be freed. Also, this function will never return %NULL, even if @xatom is invalid. name of the X atom; this string is owned by GTK+, so it shouldn’t be modifed or freed. an X atom for GDK’s default display Returns the name of an X atom for its display. This function is meant mainly for debugging, so for convenience, unlike XAtomName() and gdk_atom_name(), the result doesn’t need to be freed. name of the X atom; this string is owned by GDK, so it shouldn’t be modifed or freed. the #GdkDisplay where @xatom is defined an X atom Call gdk_x11_display_grab() on the default display. To ungrab the server again, use gdk_x11_ungrab_server(). gdk_x11_grab_server()/gdk_x11_ungrab_server() calls can be nested. Find the #GdkDisplay corresponding to @xdisplay, if any exists. the #GdkDisplay, if found, otherwise %NULL. a pointer to an X Display Registers interest in receiving extension events with type codes between @event_base and `event_base + n_events - 1`. The registered events must have the window field in the same place as core X events (this is not the case for e.g. XKB extension events). If an event type is registered, events of this type will go through global and window-specific filters (see gdk_window_add_filter()). Unregistered events will only go through global filters. GDK may register the events of some X extensions on its own. This function should only be needed in unusual circumstances, e.g. when filtering XInput extension events on the root window. a #GdkDisplay first event type code to register number of event type codes to register Sets the `SM_CLIENT_ID` property on the application’s leader window so that the window manager can save the application’s state using the X11R6 ICCCM session management protocol. See the X Session Management Library documentation for more information on session management and the Inter-Client Communication Conventions Manual the client id assigned by the session manager when the connection was opened, or %NULL to remove the property. Ungrab the default display after it has been grabbed with gdk_x11_grab_server(). Convert from an X atom for the default display to the corresponding #GdkAtom. the corresponding G#dkAtom. an X atom for the default GDK display Convert from an X atom for a #GdkDisplay to the corresponding #GdkAtom. the corresponding #GdkAtom. A #GdkDisplay an X atom The functions in this section are specific to the GDK X11 backend. To use them, you need to include the `<gdk/gdkx.h>` header and use the X11-specific pkg-config files to build your application (either `gdk-x11-3.0` or `gtk+-x11-3.0`). To make your code compile with other GDK backends, guard backend-specific calls by an ifdef as follows. Since GDK may be built with multiple backends, you should also check for the backend that is in use (e.g. by using the GDK_IS_X11_DISPLAY() macro). |[ #ifdef GDK_WINDOWING_X11 if (GDK_IS_X11_DISPLAY (display)) { // make X11-specific calls here } else #endif #ifdef GDK_WINDOWING_QUARTZ if (GDK_IS_QUARTZ_DISPLAY (display)) { // make Quartz-specific calls here } else #endif g_error ("Unsupported GDK backend"); ]| soup3-0.9.0/gir-files/GdkX11-4.0.gir000064400000000000000000002220021046102023000145630ustar 00000000000000 Returns the display of a `GdkDisplay`. a `GdkDisplay` Converts a @gpointer back to an XID that was previously converted using GDK_XID_TO_POINTER(). pointer to extract an XID from Returns the display of a `GdkSurface`. a `GdkSurface` Returns the X window belonging to a `GdkSurface`. a `GdkSurface` Tries to open a new display to the X server given by @display_name. If opening the display fails, %NULL is returned. The new display name of the X display. See the XOpenDisplay() for details. Sets the program class. The X11 backend uses the program class to set the class name part of the `WM_CLASS` property on toplevel windows; see the ICCCM. a `GdkDisplay` a string Sends a startup notification message of type @message_type to @display. This is a convenience function for use by code that implements the freedesktop startup notification specification. Applications should not normally need to call it directly. See the [Startup Notification Protocol specification](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt) for definitions of the message types and keys that can be used. a `GdkDisplay` startup notification message type ("new", "change", or "remove") a list of key/value pairs (as strings), terminated by a %NULL key. (A %NULL value for a key will cause that key to be skipped in the output.) Pops the error trap pushed by gdk_x11_display_error_trap_push(). Will XSync() if necessary and will always block until the error is known to have occurred or not occurred, so the error code can be returned. If you don’t need to use the return value, gdk_x11_display_error_trap_pop_ignored() would be more efficient. X error code or 0 on success the display Pops the error trap pushed by gdk_x11_display_error_trap_push(). Does not block to see if an error occurred; merely records the range of requests to ignore errors for, and ignores those errors if they arrive asynchronously. the display Begins a range of X requests on @display for which X error events will be ignored. Unignored errors (when no trap is pushed) will abort the application. Use gdk_x11_display_error_trap_pop() or gdk_x11_display_error_trap_pop_ignored()to lift a trap pushed with this function. a `GdkDisplay` Returns the default group leader surface for all toplevel surfaces on @display. This surface is implicitly created by GDK. See gdk_x11_surface_set_group(). The default group leader surface for @display a `GdkDisplay` Retrieves the EGL display connection object for the given GDK display. This function returns `NULL` if GDK is using GLX. the EGL display object an X11 display Retrieves the version of the EGL implementation. %TRUE if EGL is available a `GdkDisplay` return location for the EGL major version return location for the EGL minor version Retrieves the version of the GLX implementation. %TRUE if GLX is available a `GdkDisplay` return location for the GLX major version return location for the GLX minor version Gets the primary monitor for the display. The primary monitor is considered the monitor where the “main desktop” lives. While normal application surfaces typically allow the window manager to place the surfaces, specialized desktop applications such as panels should place themselves on the primary monitor. If no monitor is the designated primary monitor, any monitor (usually the first) may be returned. the primary monitor, or any monitor if no primary monitor is configured by the user a `GdkDisplay` Retrieves the `GdkX11Screen` of the @display. the `GdkX11Screen` a `GdkX11Display` Gets the startup notification ID for a display. the startup notification ID for @display a `GdkDisplay` Returns the timestamp of the last user interaction on @display. The timestamp is taken from events caused by user interaction such as key presses or pointer movements. See gdk_x11_surface_set_user_time(). the timestamp of the last user interaction a `GdkDisplay` Returns the X cursor belonging to a `GdkCursor`, potentially creating the cursor. Be aware that the returned cursor may not be unique to @cursor. It may for example be shared with its fallback cursor. On old X servers that don't support the XCursor extension, all cursors may even fall back to a few default cursors. an Xlib Cursor. a `GdkDisplay` a `GdkCursor` Returns the X display of a `GdkDisplay`. an X display a `GdkDisplay` Returns the root X window used by `GdkDisplay`. an X Window a `GdkDisplay` Returns the X Screen used by `GdkDisplay`. an X Screen a `GdkDisplay` Call XGrabServer() on @display. To ungrab the display again, use gdk_x11_display_ungrab(). gdk_x11_display_grab()/gdk_x11_display_ungrab() calls can be nested. a `GdkDisplay` Sets the cursor theme from which the images for cursor should be taken. If the windowing system supports it, existing cursors created with [ctor@Gdk.Cursor.new_from_name] are updated to reflect the theme change. Custom cursors constructed with [ctor@Gdk.Cursor.new_from_texture] will have to be handled by the application (GTK applications can learn about cursor theme changes by listening for change notification for the corresponding `GtkSetting`). Use the cursor-related properties of [GtkSettings](../gtk4/class.Settings.html) to set the cursor theme a `GdkDisplay` the name of the cursor theme to use, or %NULL to unset a previously set value the cursor size to use, or 0 to keep the previous size Sets the startup notification ID for a display. This is usually taken from the value of the DESKTOP_STARTUP_ID environment variable, but in some cases (such as the application not being launched using exec()) it can come from other sources. If the ID contains the string "_TIME" then the portion following that string is taken to be the X11 timestamp of the event that triggered the application to be launched and the GDK current event time is set accordingly. The startup ID is also what is used to signal that the startup is complete (for example, when opening a window or when calling gdk_display_notify_startup_complete()). Using [method@Gdk.Toplevel.set_startup_id] is sufficient a `GdkDisplay` the startup notification ID (must be valid utf8) Forces a specific window scale for all windows on this display, instead of using the default or user configured scale. This is can be used to disable scaling support by setting @scale to 1, or to programmatically set the window scale. Once the scale is set by this call it will not change in response to later user configuration changes. the display The new scale value Convert a string from the encoding of the current locale into a form suitable for storing in a window property. 0 upon success, non-zero upon failure the `GdkDisplay` where the encoding is defined a nul-terminated string location to store the encoding (to be used as the type for the property) location to store the format of the property location to store newly allocated data for the property the length of @ctext, in bytes Convert a text string from the encoding as it is stored in a property into an array of strings in the encoding of the current locale. (The elements of the array represent the nul-separated elements of the original text string.) the number of strings stored in list, or 0, if the conversion failed The `GdkDisplay` where the encoding is defined a string representing the encoding. The most common values for this are "STRING", or "COMPOUND_TEXT". This is value used as the type for the property the format of the property The text data The number of items to transform location to store an array of strings in the encoding of the current locale. This array should be freed using gdk_x11_free_text_list(). Ungrab @display after it has been grabbed with gdk_x11_display_grab(). a `GdkDisplay` Converts from UTF-8 to compound text. %TRUE if the conversion succeeded, otherwise %FALSE a `GdkDisplay` a UTF-8 string location to store resulting encoding location to store format of the result location to store the data of the result location to store the length of the data stored in @ctext The ::xevent signal is a low level signal that is emitted whenever an XEvent has been received. When handlers to this signal return %TRUE, no other handlers will be invoked. In particular, the default handler for this function is GDK's own event handling mechanism, so by returning %TRUE for an event that GDK expects to translate, you may break GDK and/or GTK+ in interesting ways. You have been warned. If you want this signal handler to queue a `GdkEvent`, you can use gdk_display_put_event(). If you are interested in X GenericEvents, bear in mind that XGetEventData() has been already called on the event, and XFreeEventData() will be called afterwards. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. a pointer to the XEvent to process Returns the XID of the Output corresponding to @monitor. the XID of @monitor a `GdkMonitor` Retrieves the size and position of the “work area” on a monitor within the display coordinate space. The returned geometry is in ”application pixels”, not in ”device pixels” (see [method@Gdk.Monitor.get_scale_factor]). a `GdkMonitor` a `GdkRectangle` to be filled with the monitor workarea Returns the current workspace for @screen when running under a window manager that supports multiple workspaces, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification. the current workspace, or 0 if workspaces are not supported a `GdkX11Screen` Gets the XID of the specified output/monitor. If the X server does not support version 1.2 of the RANDR extension, 0 is returned. the XID of the monitor a `GdkX11Screen` number of the monitor, between 0 and gdk_screen_get_n_monitors (screen) Returns the number of workspaces for @screen when running under a window manager that supports multiple workspaces, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification. the number of workspaces, or 0 if workspaces are not supported a `GdkX11Screen` Returns the index of a `GdkX11Screen`. the position of @screen among the screens of its display a `GdkX11Screen` Returns the name of the window manager for @screen. the name of the window manager screen @screen, or "unknown" if the window manager is unknown. The string is owned by GDK and should not be freed. a `GdkX11Screen` Returns the screen of a `GdkX11Screen`. an Xlib Screen* a `GdkX11Screen` This function is specific to the X11 backend of GDK, and indicates whether the window manager supports a certain hint from the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification. When using this function, keep in mind that the window manager can change over time; so you shouldn’t use this function in a way that impacts persistent application state. A common bug is that your application can start up before the window manager does when the user logs in, and before the window manager starts gdk_x11_screen_supports_net_wm_hint() will return %FALSE for every property. You can monitor the window_manager_changed signal on `GdkX11Screen` to detect a window manager change. %TRUE if the window manager supports @property the relevant `GdkX11Screen`. name of the WM property Looks up the `GdkSurface` that wraps the given native window handle. the `GdkSurface` wrapper for the native window the `GdkDisplay` corresponding to the window handle an Xlib Window Gets the number of the workspace @surface is on. the current workspace of @surface a `GdkSurface` Returns the group this surface belongs to. The group of this surface; The `GdkSurface` Returns the X resource (surface) belonging to a `GdkSurface`. the ID of @drawable’s X resource. a native `GdkSurface`. Moves the surface to the correct workspace when running under a window manager that supports multiple workspaces, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification. Will not do anything if the surface is already on all workspaces. a `GdkSurface` Moves the surface to the given workspace when running unde a window manager that supports multiple workspaces, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification. a `GdkSurface` the number of the workspace to move the surface to This function can be used to disable frame synchronization for a surface. Normally frame synchronziation will be enabled or disabled based on whether the system has a compositor that supports frame synchronization, but if the surface is not directly managed by the window manager, then frame synchronziation may need to be disabled. This is the case for a surface embedded via the XEMBED protocol. a native `GdkSurface` whether frame-synchronization should be enabled Sets the group leader of @surface to be @leader. See the ICCCM for details. a native `GdkSurface` a `GdkSurface` Sets a hint on @surface that pagers should not display it. See the EWMH for details. a `GdkSurface` %TRUE to skip pagers Sets a hint on @surface that taskbars should not display it. See the EWMH for details. a native `GdkSurface` %TRUE to skip taskbars GTK applications can request a dark theme variant. In order to make other applications - namely window managers using GTK for themeing - aware of this choice, GTK uses this function to export the requested theme variant as _GTK_THEME_VARIANT property on toplevel surfaces. Note that this property is automatically updated by GTK, so this function should only be used by applications which do not use GTK to create toplevel surfaces. a `GdkSurface` the theme variant to export Sets a hint on @surface that it needs user attention. See the ICCCM for details. a native `GdkSurface` %TRUE to indicate urgenct attention needed The application can use this call to update the _NET_WM_USER_TIME property on a toplevel surface. This property stores an Xserver time which represents the time of the last user input event received for this surface. This property may be used by the window manager to alter the focus, stacking, and/or placement behavior of surfaces when they are mapped depending on whether the new surface was created by a user action or is a "pop-up" surface activated by a timer or some other event. Note that this property is automatically updated by GDK, so this function should only be used by applications which handle input events bypassing GDK. A toplevel `GdkSurface` An XServer timestamp to which the property should be set This function modifies or removes an arbitrary X11 window property of type UTF8_STRING. If the given @surface is not a toplevel surface, it is ignored. a `GdkSurface` Property name, will be interned as an X atom Property value, or %NULL to delete Converts an XID into a @gpointer. This is useful with data structures that use pointer arguments such as `GHashTable`. Use GDK_POINTER_TO_XID() to convert the argument back to an XID. XID to stuff into the pointer Returns the device ID as seen by XInput2. the XInput2 device ID a `GdkDevice` Returns the `GdkDevice` that wraps the given device ID. The `GdkDevice` wrapping the device ID, or %NULL if the given ID doesn’t currently represent a device. a `GdkDeviceManager` a device ID, as understood by the XInput2 protocol Frees the data returned from gdk_x11_display_string_to_compound_text(). The pointer stored in @ctext from a call to gdk_x11_display_string_to_compound_text(). Frees the array of strings created by gdk_x11_display_text_property_to_text_list(). the value stored in the @list parameter by a call to gdk_x11_display_text_property_to_text_list(). Routine to get the current X server time stamp. the time stamp a `GdkSurface`, used for communication with the server. The surface must have `GDK_PROPERTY_CHANGE_MASK` in its events mask or a hang will result. Returns the X atom for a `GdkDisplay` corresponding to @atom_name. This function caches the result, so if called repeatedly it is much faster than XInternAtom(), which is a round trip to the server each time. a X atom for a `GdkDisplay` a `GdkDisplay` a string Returns the name of an X atom for its display. This function is meant mainly for debugging, so for convenience, unlike XAtomName() and the result doesn’t need to be freed. name of the X atom; this string is owned by GDK, so it shouldn’t be modified or freed. the `GdkDisplay` where @xatom is defined an X atom Find the `GdkDisplay` corresponding to @xdisplay, if any exists. the `GdkDisplay`, if found, otherwise %NULL. a pointer to an X Display Sets the `SM_CLIENT_ID` property on the application’s leader window so that the window manager can save the application’s state using the X11R6 ICCCM session management protocol. See the X Session Management Library documentation for more information on session management and the Inter-Client Communication Conventions Manual the client id assigned by the session manager when the connection was opened, or %NULL to remove the property. soup3-0.9.0/gir-files/Gio-2.0.gir000064400000000000000000215366531046102023000143270ustar 00000000000000 `GAction` represents a single named action. The main interface to an action is that it can be activated with [method@Gio.Action.activate]. This results in the 'activate' signal being emitted. An activation has a `GVariant` parameter (which may be `NULL`). The correct type for the parameter is determined by a static parameter type (which is given at construction time). An action may optionally have a state, in which case the state may be set with [method@Gio.Action.change_state]. This call takes a [type@GLib.Variant]. The correct type for the state is determined by a static state type (which is given at construction time). The state may have a hint associated with it, specifying its valid range. `GAction` is merely the interface to the concept of an action, as described above. Various implementations of actions exist, including [class@Gio.SimpleAction]. In all cases, the implementing class is responsible for storing the name of the action, the parameter type, the enabled state, the optional state type and the state and emitting the appropriate signals when these change. The implementor is responsible for filtering calls to [method@Gio.Action.activate] and [method@Gio.Action.change_state] for type safety and for the state being enabled. Probably the only useful thing to do with a `GAction` is to put it inside of a [class@Gio.SimpleActionGroup]. Checks if @action_name is valid. @action_name is valid if it consists only of alphanumeric characters, plus `-` and `.`. The empty string is not a valid action name. It is an error to call this function with a non-UTF-8 @action_name. @action_name must not be `NULL`. `TRUE` if @action_name is valid a potential action name Parses a detailed action name into its separate name and target components. Detailed action names can have three formats. The first format is used to represent an action name with no target value and consists of just an action name containing no whitespace nor the characters `:`, `(` or `)`. For example: `app.action`. The second format is used to represent an action with a target value that is a non-empty string consisting only of alphanumerics, plus `-` and `.`. In that case, the action name and target value are separated by a double colon (`::`). For example: `app.action::target`. The third format is used to represent an action with any type of target value, including strings. The target value follows the action name, surrounded in parens. For example: `app.action(42)`. The target value is parsed using [func@GLib.Variant.parse]. If a tuple-typed value is desired, it must be specified in the same way, resulting in two sets of parens, for example: `app.action((1,2,3))`. A string target can be specified this way as well: `app.action('target')`. For strings, this third format must be used if target value is empty or contains characters other than alphanumerics, `-` and `.`. If this function returns `TRUE`, a non-`NULL` value is guaranteed to be returned in @action_name (if a pointer is passed in). A `NULL` value may still be returned in @target_value, as the @detailed_name may not contain a target. If returned, the [type@GLib.Variant] in @target_value is guaranteed to not be floating. `TRUE` if successful, else `FALSE` with @error set a detailed action name the action name the target value, or `NULL` for no target Formats a detailed action name from @action_name and @target_value. It is an error to call this function with an invalid action name. This function is the opposite of [func@Gio.Action.parse_detailed_name]. It will produce a string that can be parsed back to the @action_name and @target_value by that function. See that function for the types of strings that will be printed by this function. a detailed format string a valid action name a [type@GLib.Variant] target value, or `NULL` Activates the action. @parameter must be the correct type of parameter for the action (ie: the parameter type given at construction time). If the parameter type was `NULL` then @parameter must also be `NULL`. If the @parameter [type@GLib.Variant] is floating, it is consumed. a [type@Gio.Action] the parameter to the activation Request for the state of @action to be changed to @value. The action must be stateful and @value must be of the correct type. See [method@Gio.Action.get_state_type]. This call merely requests a change. The action may refuse to change its state or may change its state to something other than @value. See [method@Gio.Action.get_state_hint]. If the @value [type@GLib.Variant] is floating, it is consumed. a [type@Gio.Action] the new state Checks if @action is currently enabled. An action must be enabled in order to be activated or in order to have its state changed from outside callers. whether the action is enabled a [type@Gio.Action] Queries the name of @action. the name of the action a [type@Gio.Action] Queries the type of the parameter that must be given when activating @action. When activating the action using [method@Gio.Action.activate], the [type@GLib.Variant] given to that function must be of the type returned by this function. In the case that this function returns `NULL`, you must not give any [type@GLib.Variant], but `NULL` instead. the parameter type a [type@Gio.Action] Queries the current state of @action. If the action is not stateful then `NULL` will be returned. If the action is stateful then the type of the return value is the type given by [method@Gio.Action.get_state_type]. The return value (if non-`NULL`) should be freed with [method@GLib.Variant.unref] when it is no longer required. the current state of the action a [type@Gio.Action] Requests a hint about the valid range of values for the state of @action. If `NULL` is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action. If a [type@GLib.Variant] array is returned then each item in the array is a possible value for the state. If a [type@GLib.Variant] pair (ie: two-tuple) is returned then the tuple specifies the inclusive lower and upper bound of valid values for the state. In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail. The return value (if non-`NULL`) should be freed with [method@GLib.Variant.unref] when it is no longer required. the state range hint a [type@Gio.Action] Queries the type of the state of @action. If the action is stateful (e.g. created with [ctor@Gio.SimpleAction.new_stateful]) then this function returns the [type@GLib.VariantType] of the state. This is the type of the initial value given as the state. All calls to [method@Gio.Action.change_state] must give a [type@GLib.Variant] of this type and [method@Gio.Action.get_state] will return a [type@GLib.Variant] of the same type. If the action is not stateful (e.g. created with [ctor@Gio.SimpleAction.new]) then this function will return `NULL`. In that case, [method@Gio.Action.get_state] will return `NULL` and you must not call [method@Gio.Action.change_state]. the state type, if the action is stateful a [type@Gio.Action] Activates the action. @parameter must be the correct type of parameter for the action (ie: the parameter type given at construction time). If the parameter type was `NULL` then @parameter must also be `NULL`. If the @parameter [type@GLib.Variant] is floating, it is consumed. a [type@Gio.Action] the parameter to the activation Request for the state of @action to be changed to @value. The action must be stateful and @value must be of the correct type. See [method@Gio.Action.get_state_type]. This call merely requests a change. The action may refuse to change its state or may change its state to something other than @value. See [method@Gio.Action.get_state_hint]. If the @value [type@GLib.Variant] is floating, it is consumed. a [type@Gio.Action] the new state Checks if @action is currently enabled. An action must be enabled in order to be activated or in order to have its state changed from outside callers. whether the action is enabled a [type@Gio.Action] Queries the name of @action. the name of the action a [type@Gio.Action] Queries the type of the parameter that must be given when activating @action. When activating the action using [method@Gio.Action.activate], the [type@GLib.Variant] given to that function must be of the type returned by this function. In the case that this function returns `NULL`, you must not give any [type@GLib.Variant], but `NULL` instead. the parameter type a [type@Gio.Action] Queries the current state of @action. If the action is not stateful then `NULL` will be returned. If the action is stateful then the type of the return value is the type given by [method@Gio.Action.get_state_type]. The return value (if non-`NULL`) should be freed with [method@GLib.Variant.unref] when it is no longer required. the current state of the action a [type@Gio.Action] Requests a hint about the valid range of values for the state of @action. If `NULL` is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action. If a [type@GLib.Variant] array is returned then each item in the array is a possible value for the state. If a [type@GLib.Variant] pair (ie: two-tuple) is returned then the tuple specifies the inclusive lower and upper bound of valid values for the state. In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail. The return value (if non-`NULL`) should be freed with [method@GLib.Variant.unref] when it is no longer required. the state range hint a [type@Gio.Action] Queries the type of the state of @action. If the action is stateful (e.g. created with [ctor@Gio.SimpleAction.new_stateful]) then this function returns the [type@GLib.VariantType] of the state. This is the type of the initial value given as the state. All calls to [method@Gio.Action.change_state] must give a [type@GLib.Variant] of this type and [method@Gio.Action.get_state] will return a [type@GLib.Variant] of the same type. If the action is not stateful (e.g. created with [ctor@Gio.SimpleAction.new]) then this function will return `NULL`. In that case, [method@Gio.Action.get_state] will return `NULL` and you must not call [method@Gio.Action.change_state]. the state type, if the action is stateful a [type@Gio.Action] If @action is currently enabled. If the action is disabled then calls to [method@Gio.Action.activate] and [method@Gio.Action.change_state] have no effect. The name of the action. This is mostly meaningful for identifying the action once it has been added to a [type@Gio.ActionGroup]. It is immutable. The type of the parameter that must be given when activating the action. This is immutable, and may be `NULL` if no parameter is needed when activating the action. The state of the action, or `NULL` if the action is stateless. The [type@GLib.VariantType] of the state that the action has, or `NULL` if the action is stateless. This is immutable. This struct defines a single action. It is for use with [method@Gio.ActionMap.add_action_entries]. The order of the items in the structure are intended to reflect frequency of use. It is permissible to use an incomplete initialiser in order to leave some of the later values as `NULL`. All values after @name are optional. Additional optional fields may be added in the future. See [method@Gio.ActionMap.add_action_entries] for an example. the name of the action the callback to connect to the "activate" signal of the action. Since GLib 2.40, this can be `NULL` for stateful actions, in which case the default handler is used. For boolean-stated actions with no parameter, this is a toggle. For other state types (and parameter type equal to the state type) this will be a function that just calls @change_state (which you should provide). the type of the parameter that must be passed to the activate function for this action, given as a single GVariant type string (or `NULL` for no parameter) the initial state for this action, given in [GVariant text format](../glib/gvariant-text-format.html). The state is parsed with no extra type information, so type tags must be added to the string if they are necessary. Stateless actions should give `NULL` here. the callback to connect to the "change-state" signal of the action. All stateful actions should provide a handler here; stateless actions should not. `GActionGroup` represents a group of actions. Actions can be used to expose functionality in a structured way, either from one part of a program to another, or to the outside world. Action groups are often used together with a [type@Gio.MenuModel] that provides additional representation data for displaying the actions to the user, e.g. in a menu. The main way to interact with the actions in a `GActionGroup` is to activate them with [method@Gio.ActionGroup.activate_action]. Activating an action may require a [type@GLib.Variant] parameter. The required type of the parameter can be inquired with [method@Gio.ActionGroup.get_action_parameter_type]. Actions may be disabled, see [method@Gio.ActionGroup.get_action_enabled]. Activating a disabled action has no effect. Actions may optionally have a state in the form of a [type@GLib.Variant]. The current state of an action can be inquired with [method@Gio.ActionGroup.get_action_state]. Activating a stateful action may change its state, but it is also possible to set the state by calling [method@Gio.ActionGroup.change_action_state]. As typical example, consider a text editing application which has an option to change the current font to ‘bold’. A good way to represent this would be a stateful action, with a boolean state. Activating the action would toggle the state. Each action in the group has a unique name (which is a string). All method calls, except [method@Gio.ActionGroup.list_actions] take the name of an action as an argument. The `GActionGroup` API is meant to be the ‘public’ API to the action group. The calls here are exactly the interaction that ‘external forces’ (eg: UI, incoming D-Bus messages, etc.) are supposed to have with actions. ‘Internal’ APIs (ie: ones meant only to be accessed by the action group implementation) are found on subclasses. This is why you will find – for example – [method@Gio.ActionGroup.get_action_enabled] but not an equivalent `set_action_enabled()` method. Signals are emitted on the action group in response to state changes on individual actions. Implementations of `GActionGroup` should provide implementations for the virtual functions [method@Gio.ActionGroup.list_actions] and [method@Gio.ActionGroup.query_action]. The other virtual functions should not be implemented — their ‘wrappers’ are actually implemented with calls to [method@Gio.ActionGroup.query_action]. Emits the [signal@Gio.ActionGroup::action-added] signal on @action_group. This function should only be called by [type@Gio.ActionGroup] implementations. a [type@Gio.ActionGroup] the name of an action in the group Emits the [signal@Gio.ActionGroup::action-enabled-changed] signal on @action_group. This function should only be called by [type@Gio.ActionGroup] implementations. a [type@Gio.ActionGroup] the name of an action in the group whether the action is now enabled Emits the [signal@Gio.ActionGroup::action-removed] signal on @action_group. This function should only be called by [type@Gio.ActionGroup] implementations. a [type@Gio.ActionGroup] the name of an action in the group Emits the [signal@Gio.ActionGroup::action-state-changed] signal on @action_group. This function should only be called by [type@Gio.ActionGroup] implementations. a [type@Gio.ActionGroup] the name of an action in the group the new state of the named action Activate the named action within @action_group. If the action is expecting a parameter, then the correct type of parameter must be given as @parameter. If the action is expecting no parameters then @parameter must be `NULL`. See [method@Gio.ActionGroup.get_action_parameter_type]. If the [type@Gio.ActionGroup] implementation supports asynchronous remote activation over D-Bus, this call may return before the relevant D-Bus traffic has been sent, or any replies have been received. In order to block on such asynchronous activation calls, [method@Gio.DBusConnection.flush] should be called prior to the code, which depends on the result of the action activation. Without flushing the D-Bus connection, there is no guarantee that the action would have been activated. The following code which runs in a remote app instance, shows an example of a ‘quit’ action being activated on the primary app instance over D-Bus. Here [method@Gio.DBusConnection.flush] is called before `exit()`. Without `g_dbus_connection_flush()`, the ‘quit’ action may fail to be activated on the primary instance. ```c // call ‘quit’ action on primary instance g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL); // make sure the action is activated now g_dbus_connection_flush (…); g_debug ("Application has been terminated. Exiting."); exit (0); ``` a [type@Gio.ActionGroup] the name of the action to activate parameters to the activation Request for the state of the named action within @action_group to be changed to @value. The action must be stateful and @value must be of the correct type. See [method@Gio.ActionGroup.get_action_state_type]. This call merely requests a change. The action may refuse to change its state or may change its state to something other than @value. See [method@Gio.ActionGroup.get_action_state_hint]. If the @value GVariant is floating, it is consumed. a [type@Gio.ActionGroup] the name of the action to request the change on the new state Checks if the named action within @action_group is currently enabled. An action must be enabled in order to be activated or in order to have its state changed from outside callers. whether the action is currently enabled a [type@Gio.ActionGroup] the name of the action to query Queries the type of the parameter that must be given when activating the named action within @action_group. When activating the action using [method@Gio.ActionGroup.activate_action], the [type@GLib.Variant] given to that function must be of the type returned by this function. In the case that this function returns `NULL`, you must not give any [type@GLib.Variant], but `NULL` instead. The parameter type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different parameter type. the parameter type a [type@Gio.ActionGroup] the name of the action to query Queries the current state of the named action within @action_group. If the action is not stateful then `NULL` will be returned. If the action is stateful then the type of the return value is the type given by [method@Gio.ActionGroup.get_action_state_type]. The return value (if non-`NULL`) should be freed with [method@GLib.Variant.unref] when it is no longer required. the current state of the action a [type@Gio.ActionGroup] the name of the action to query Requests a hint about the valid range of values for the state of the named action within @action_group. If `NULL` is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action. If a [type@GLib.Variant] array is returned then each item in the array is a possible value for the state. If a [type@GLib.Variant] pair (ie: two-tuple) is returned then the tuple specifies the inclusive lower and upper bound of valid values for the state. In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail. The return value (if non-`NULL`) should be freed with [method@GLib.Variant.unref] when it is no longer required. the state range hint a [type@Gio.ActionGroup] the name of the action to query Queries the type of the state of the named action within @action_group. If the action is stateful then this function returns the [type@GLib.VariantType] of the state. All calls to [method@Gio.ActionGroup.change_action_state] must give a [type@GLib.Variant] of this type and [method@Gio.ActionGroup.get_action_state] will return a [type@GLib.Variant] of the same type. If the action is not stateful then this function will return `NULL`. In that case, [method@Gio.ActionGroup.get_action_state] will return `NULL` and you must not call [method@Gio.ActionGroup.change_action_state]. The state type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different state type. the state type, if the action is stateful a [type@Gio.ActionGroup] the name of the action to query Checks if the named action exists within @action_group. whether the named action exists a [type@Gio.ActionGroup] the name of the action to check for Lists the actions contained within @action_group. The caller is responsible for freeing the list with [func@GLib.strfreev] when it is no longer required. a `NULL`-terminated array of the names of the actions in the group a [type@Gio.ActionGroup] Queries all aspects of the named action within an @action_group. This function acquires the information available from [method@Gio.ActionGroup.has_action], [method@Gio.ActionGroup.get_action_enabled], [method@Gio.ActionGroup.get_action_parameter_type], [method@Gio.ActionGroup.get_action_state_type], [method@Gio.ActionGroup.get_action_state_hint] and [method@Gio.ActionGroup.get_action_state] with a single function call. This provides two main benefits. The first is the improvement in efficiency that comes with not having to perform repeated lookups of the action in order to discover different things about it. The second is that implementing [type@Gio.ActionGroup] can now be done by only overriding this one virtual function. The interface provides a default implementation of this function that calls the individual functions, as required, to fetch the information. The interface also provides default implementations of those functions that call this function. All implementations, therefore, must override either this function or all of the others. If the action exists, `TRUE` is returned and any of the requested fields (as indicated by having a non-`NULL` reference passed in) are filled. If the action doesn’t exist, `FALSE` is returned and the fields may or may not have been modified. `TRUE` if the action exists, else `FALSE` a [type@Gio.ActionGroup] the name of an action in the group if the action is presently enabled the parameter type, or `NULL` if none needed the state type, or `NULL` if stateless the state hint, or `NULL` if none the current state, or `NULL` if stateless Emits the [signal@Gio.ActionGroup::action-added] signal on @action_group. This function should only be called by [type@Gio.ActionGroup] implementations. a [type@Gio.ActionGroup] the name of an action in the group Emits the [signal@Gio.ActionGroup::action-enabled-changed] signal on @action_group. This function should only be called by [type@Gio.ActionGroup] implementations. a [type@Gio.ActionGroup] the name of an action in the group whether the action is now enabled Emits the [signal@Gio.ActionGroup::action-removed] signal on @action_group. This function should only be called by [type@Gio.ActionGroup] implementations. a [type@Gio.ActionGroup] the name of an action in the group Emits the [signal@Gio.ActionGroup::action-state-changed] signal on @action_group. This function should only be called by [type@Gio.ActionGroup] implementations. a [type@Gio.ActionGroup] the name of an action in the group the new state of the named action Activate the named action within @action_group. If the action is expecting a parameter, then the correct type of parameter must be given as @parameter. If the action is expecting no parameters then @parameter must be `NULL`. See [method@Gio.ActionGroup.get_action_parameter_type]. If the [type@Gio.ActionGroup] implementation supports asynchronous remote activation over D-Bus, this call may return before the relevant D-Bus traffic has been sent, or any replies have been received. In order to block on such asynchronous activation calls, [method@Gio.DBusConnection.flush] should be called prior to the code, which depends on the result of the action activation. Without flushing the D-Bus connection, there is no guarantee that the action would have been activated. The following code which runs in a remote app instance, shows an example of a ‘quit’ action being activated on the primary app instance over D-Bus. Here [method@Gio.DBusConnection.flush] is called before `exit()`. Without `g_dbus_connection_flush()`, the ‘quit’ action may fail to be activated on the primary instance. ```c // call ‘quit’ action on primary instance g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL); // make sure the action is activated now g_dbus_connection_flush (…); g_debug ("Application has been terminated. Exiting."); exit (0); ``` a [type@Gio.ActionGroup] the name of the action to activate parameters to the activation Request for the state of the named action within @action_group to be changed to @value. The action must be stateful and @value must be of the correct type. See [method@Gio.ActionGroup.get_action_state_type]. This call merely requests a change. The action may refuse to change its state or may change its state to something other than @value. See [method@Gio.ActionGroup.get_action_state_hint]. If the @value GVariant is floating, it is consumed. a [type@Gio.ActionGroup] the name of the action to request the change on the new state Checks if the named action within @action_group is currently enabled. An action must be enabled in order to be activated or in order to have its state changed from outside callers. whether the action is currently enabled a [type@Gio.ActionGroup] the name of the action to query Queries the type of the parameter that must be given when activating the named action within @action_group. When activating the action using [method@Gio.ActionGroup.activate_action], the [type@GLib.Variant] given to that function must be of the type returned by this function. In the case that this function returns `NULL`, you must not give any [type@GLib.Variant], but `NULL` instead. The parameter type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different parameter type. the parameter type a [type@Gio.ActionGroup] the name of the action to query Queries the current state of the named action within @action_group. If the action is not stateful then `NULL` will be returned. If the action is stateful then the type of the return value is the type given by [method@Gio.ActionGroup.get_action_state_type]. The return value (if non-`NULL`) should be freed with [method@GLib.Variant.unref] when it is no longer required. the current state of the action a [type@Gio.ActionGroup] the name of the action to query Requests a hint about the valid range of values for the state of the named action within @action_group. If `NULL` is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action. If a [type@GLib.Variant] array is returned then each item in the array is a possible value for the state. If a [type@GLib.Variant] pair (ie: two-tuple) is returned then the tuple specifies the inclusive lower and upper bound of valid values for the state. In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail. The return value (if non-`NULL`) should be freed with [method@GLib.Variant.unref] when it is no longer required. the state range hint a [type@Gio.ActionGroup] the name of the action to query Queries the type of the state of the named action within @action_group. If the action is stateful then this function returns the [type@GLib.VariantType] of the state. All calls to [method@Gio.ActionGroup.change_action_state] must give a [type@GLib.Variant] of this type and [method@Gio.ActionGroup.get_action_state] will return a [type@GLib.Variant] of the same type. If the action is not stateful then this function will return `NULL`. In that case, [method@Gio.ActionGroup.get_action_state] will return `NULL` and you must not call [method@Gio.ActionGroup.change_action_state]. The state type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different state type. the state type, if the action is stateful a [type@Gio.ActionGroup] the name of the action to query Checks if the named action exists within @action_group. whether the named action exists a [type@Gio.ActionGroup] the name of the action to check for Lists the actions contained within @action_group. The caller is responsible for freeing the list with [func@GLib.strfreev] when it is no longer required. a `NULL`-terminated array of the names of the actions in the group a [type@Gio.ActionGroup] Queries all aspects of the named action within an @action_group. This function acquires the information available from [method@Gio.ActionGroup.has_action], [method@Gio.ActionGroup.get_action_enabled], [method@Gio.ActionGroup.get_action_parameter_type], [method@Gio.ActionGroup.get_action_state_type], [method@Gio.ActionGroup.get_action_state_hint] and [method@Gio.ActionGroup.get_action_state] with a single function call. This provides two main benefits. The first is the improvement in efficiency that comes with not having to perform repeated lookups of the action in order to discover different things about it. The second is that implementing [type@Gio.ActionGroup] can now be done by only overriding this one virtual function. The interface provides a default implementation of this function that calls the individual functions, as required, to fetch the information. The interface also provides default implementations of those functions that call this function. All implementations, therefore, must override either this function or all of the others. If the action exists, `TRUE` is returned and any of the requested fields (as indicated by having a non-`NULL` reference passed in) are filled. If the action doesn’t exist, `FALSE` is returned and the fields may or may not have been modified. `TRUE` if the action exists, else `FALSE` a [type@Gio.ActionGroup] the name of an action in the group if the action is presently enabled the parameter type, or `NULL` if none needed the state type, or `NULL` if stateless the state hint, or `NULL` if none the current state, or `NULL` if stateless Signals that a new action was just added to the group. This signal is emitted after the action has been added and is now visible. the name of the action in @action_group Signals that the enabled status of the named action has changed. the name of the action in @action_group whether the action is enabled Signals that an action is just about to be removed from the group. This signal is emitted before the action is removed, so the action is still visible and can be queried from the signal handler. the name of the action in @action_group Signals that the state of the named action has changed. the name of the action in @action_group the new value of the state The virtual function table for [type@Gio.ActionGroup]. the virtual function pointer for [method@Gio.ActionGroup.has_action] whether the named action exists a [type@Gio.ActionGroup] the name of the action to check for the virtual function pointer for [method@Gio.ActionGroup.list_actions] a `NULL`-terminated array of the names of the actions in the group a [type@Gio.ActionGroup] the virtual function pointer for [method@Gio.ActionGroup.get_action_enabled] whether the action is currently enabled a [type@Gio.ActionGroup] the name of the action to query the virtual function pointer for [method@Gio.ActionGroup.get_action_parameter_type] the parameter type a [type@Gio.ActionGroup] the name of the action to query the virtual function pointer for [method@Gio.ActionGroup.get_action_state_type] the state type, if the action is stateful a [type@Gio.ActionGroup] the name of the action to query the virtual function pointer for [method@Gio.ActionGroup.get_action_state_hint] the state range hint a [type@Gio.ActionGroup] the name of the action to query the virtual function pointer for [method@Gio.ActionGroup.get_action_state] the current state of the action a [type@Gio.ActionGroup] the name of the action to query the virtual function pointer for [method@Gio.ActionGroup.change_action_state] a [type@Gio.ActionGroup] the name of the action to request the change on the new state the virtual function pointer for [method@Gio.ActionGroup.activate_action] a [type@Gio.ActionGroup] the name of the action to activate parameters to the activation the class closure for the [signal@Gio.ActionGroup::action-added] signal a [type@Gio.ActionGroup] the name of an action in the group the class closure for the [signal@Gio.ActionGroup::action-removed] signal a [type@Gio.ActionGroup] the name of an action in the group the class closure for the [signal@Gio.ActionGroup::action-enabled-changed] signal a [type@Gio.ActionGroup] the name of an action in the group whether the action is now enabled the class closure for the [signal@Gio.ActionGroup::action-enabled-changed] signal a [type@Gio.ActionGroup] the name of an action in the group the new state of the named action the virtual function pointer for [method@Gio.ActionGroup.query_action] `TRUE` if the action exists, else `FALSE` a [type@Gio.ActionGroup] the name of an action in the group if the action is presently enabled the parameter type, or `NULL` if none needed the state type, or `NULL` if stateless the state hint, or `NULL` if none the current state, or `NULL` if stateless The virtual function table for [type@Gio.Action]. the virtual function pointer for [method@Gio.Action.get_name] the name of the action a [type@Gio.Action] the virtual function pointer for [method@Gio.Action.get_parameter_type] the parameter type a [type@Gio.Action] the virtual function pointer for [method@Gio.Action.get_state_type] the state type, if the action is stateful a [type@Gio.Action] the virtual function pointer for [method@Gio.Action.get_state_hint] the state range hint a [type@Gio.Action] the virtual function pointer for [method@Gio.Action.get_enabled] whether the action is enabled a [type@Gio.Action] the virtual function pointer for [method@Gio.Action.get_state] the current state of the action a [type@Gio.Action] the virtual function pointer for [method@Gio.Action.change_state] a [type@Gio.Action] the new state the virtual function pointer for [method@Gio.Action.activate]. Note that [type@Gio.Action] does not have an 'activate' signal but that implementations of it may have one. a [type@Gio.Action] the parameter to the activation `GActionMap` is an interface for action containers. The `GActionMap` interface is implemented by [iface@Gio.ActionGroup] implementations that operate by containing a number of named [iface@Gio.Action] instances, such as [class@Gio.SimpleActionGroup]. One useful application of this interface is to map the names of actions from various action groups to unique, prefixed names (e.g. by prepending "app." or "win."). This is the motivation for the ‘Map’ part of the interface name. Adds an action to the @action_map. If the action map already contains an action with the same name as @action then the old action is dropped from the action map. The action map takes its own reference on @action. an action map a [iface@Gio.Action] Looks up the action with the name @action_name in @action_map. If no such action exists, returns `NULL`. a [iface@Gio.Action] an action map the name of an action Removes the named action from the action map. If no action of this name is in the map then nothing happens. an action map the name of the action Adds an action to the @action_map. If the action map already contains an action with the same name as @action then the old action is dropped from the action map. The action map takes its own reference on @action. an action map a [iface@Gio.Action] A convenience function for creating multiple [class@Gio.SimpleAction] instances and adding them to a [iface@Gio.ActionMap]. Each action is constructed as per one [struct@Gio.ActionEntry]. ```c static void activate_quit (GSimpleAction *simple, GVariant *parameter, gpointer user_data) { exit (0); } static void activate_print_string (GSimpleAction *simple, GVariant *parameter, gpointer user_data) { g_print ("%s\n", g_variant_get_string (parameter, NULL)); } static GActionGroup * create_action_group (void) { const GActionEntry entries[] = { { "quit", activate_quit }, { "print-string", activate_print_string, "s" } }; GSimpleActionGroup *group; group = g_simple_action_group_new (); g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL); return G_ACTION_GROUP (group); } ``` an action map a pointer to the first item in an array of [struct@Gio.ActionEntry] structs the length of @entries, or -1 if @entries is `NULL`-terminated the user data for signal connections Looks up the action with the name @action_name in @action_map. If no such action exists, returns `NULL`. a [iface@Gio.Action] an action map the name of an action Removes the named action from the action map. If no action of this name is in the map then nothing happens. an action map the name of the action Remove actions from a [iface@Gio.ActionMap]. This is meant as the reverse of [method@Gio.ActionMap.add_action_entries]. ```c static const GActionEntry entries[] = { { "quit", activate_quit }, { "print-string", activate_print_string, "s" } }; void add_actions (GActionMap *map) { g_action_map_add_action_entries (map, entries, G_N_ELEMENTS (entries), NULL); } void remove_actions (GActionMap *map) { g_action_map_remove_action_entries (map, entries, G_N_ELEMENTS (entries)); } ``` The [iface@Gio.ActionMap] a pointer to the first item in an array of [struct@Gio.ActionEntry] structs the length of @entries, or -1 if @entries is `NULL`-terminated The virtual function table for [iface@Gio.ActionMap]. the virtual function pointer for [method@Gio.ActionMap.lookup_action] a [iface@Gio.Action] an action map the name of an action the virtual function pointer for [method@Gio.ActionMap.add_action] an action map a [iface@Gio.Action] the virtual function pointer for [method@Gio.ActionMap.remove_action] an action map the name of the action Information about an installed application and methods to launch it (with file arguments). `GAppInfo` and `GAppLaunchContext` are used for describing and launching applications installed on the system. As of GLib 2.20, URIs will always be converted to POSIX paths (using [method@Gio.File.get_path]) when using [method@Gio.AppInfo.launch] even if the application requested an URI and not a POSIX path. For example for a desktop-file based application with the following Exec key: ``` Exec=totem %U ``` and a single URI, `sftp://foo/file.avi`, then `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will only work if a set of suitable GIO extensions (such as GVfs 2.26 compiled with FUSE support), is available and operational; if this is not the case, the URI will be passed unmodified to the application. Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX path (in GVfs there’s no FUSE mount for it); such URIs will be passed unmodified to the application. Specifically for GVfs 2.26 and later, the POSIX URI will be mapped back to the GIO URI in the [iface@Gio.File] constructors (since GVfs implements the GVfs extension point). As such, if the application needs to examine the URI, it needs to use [method@Gio.File.get_uri] or similar on [iface@Gio.File]. In other words, an application cannot assume that the URI passed to e.g. [func@Gio.File.new_for_commandline_arg] is equal to the result of [method@Gio.File.get_uri]. The following snippet illustrates this: ```c GFile *f; char *uri; file = g_file_new_for_commandline_arg (uri_from_commandline); uri = g_file_get_uri (file); strcmp (uri, uri_from_commandline) == 0; g_free (uri); if (g_file_has_uri_scheme (file, "cdda")) { // do something special with uri } g_object_unref (file); ``` This code will work when both `cdda://sr0/Track 1.wav` and `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the application. It should be noted that it’s generally not safe for applications to rely on the format of a particular URIs. Different launcher applications (e.g. file managers) may have different ideas of what a given URI means. Creates a new [iface@Gio.AppInfo] from the given information. Note that for @commandline, the quoting rules of the `Exec` key of the [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) are applied. For example, if the @commandline contains percent-encoded URIs, the percent-character must be doubled in order to prevent it from being swallowed by `Exec` key unquoting. See [the specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s07.html) for exact quoting rules. new [iface@Gio.AppInfo] for given command. the command line to use the application name, or `NULL` to use @commandline flags that can specify details of the created [iface@Gio.AppInfo] Gets a list of all of the applications currently registered on this system. For desktop files, this includes applications that have [`NoDisplay=true`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) set or are excluded from display by means of [`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) or [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin). See [method@Gio.AppInfo.should_show]. The returned list does not include applications which have the [`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) set. a newly allocated list of references to [iface@Gio.AppInfo]s. Gets a list of all [iface@Gio.AppInfo]s for a given content type, including the recommended and fallback [iface@Gio.AppInfo]s. See [func@Gio.AppInfo.get_recommended_for_type] and [func@Gio.AppInfo.get_fallback_for_type]. list of [iface@Gio.AppInfo]s for given @content_type. the content type to find a [iface@Gio.AppInfo] for Gets the default [iface@Gio.AppInfo] for a given content type. [iface@Gio.AppInfo] for given @content_type or `NULL` on error. the content type to find a [iface@Gio.AppInfo] for if `TRUE`, the [iface@Gio.AppInfo] is expected to support URIs Asynchronously gets the default [iface@Gio.AppInfo] for a given content type. the content type to find a [iface@Gio.AppInfo] for if `TRUE`, the [iface@Gio.AppInfo] is expected to support URIs a [class@Gio.Cancellable] a [type@Gio.AsyncReadyCallback] to call when the request is done data to pass to @callback Finishes a default [iface@Gio.AppInfo] lookup started by [func@Gio.AppInfo.get_default_for_type_async]. If no #[iface@Gio.AppInfo] is found, then @error will be set to [error@Gio.IOErrorEnum.NOT_FOUND]. [iface@Gio.AppInfo] for given @content_type or `NULL` on error. the async result Gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part of the URI, up to but not including the `:`. For example, `http`, `ftp` or `sip`. [iface@Gio.AppInfo] for given @uri_scheme or `NULL` on error. a string containing a URI scheme. Asynchronously gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part of the URI, up to but not including the `:`, e.g. `http`, `ftp` or `sip`. a string containing a URI scheme. a [class@Gio.Cancellable] a [type@Gio.AsyncReadyCallback] to call when the request is done data to pass to @callback Finishes a default [iface@Gio.AppInfo] lookup started by [func@Gio.AppInfo.get_default_for_uri_scheme_async]. If no [iface@Gio.AppInfo] is found, then @error will be set to [error@Gio.IOErrorEnum.NOT_FOUND]. [iface@Gio.AppInfo] for given @uri_scheme or `NULL` on error. the async result Gets a list of fallback [iface@Gio.AppInfo]s for a given content type, i.e. those applications which claim to support the given content type by MIME type subclassing and not directly. list of [iface@Gio.AppInfo]s for given @content_type or `NULL` on error. the content type to find a [iface@Gio.AppInfo] for Gets a list of recommended [iface@Gio.AppInfo]s for a given content type, i.e. those applications which claim to support the given content type exactly, and not by MIME type subclassing. Note that the first application of the list is the last used one, i.e. the last one for which [method@Gio.AppInfo.set_as_last_used_for_type] has been called. list of [iface@Gio.AppInfo]s for given @content_type or `NULL` on error. the content type to find a [iface@Gio.AppInfo] for Utility function that launches the default application registered to handle the specified uri. Synchronous I/O is done on the uri to detect the type of the file if required. The D-Bus–activated applications don’t have to be started if your application terminates too soon after this function. To prevent this, use [func@Gio.AppInfo.launch_default_for_uri_async] instead. `TRUE` on success, `FALSE` on error. the uri to show optional launch context Async version of [func@Gio.AppInfo.launch_default_for_uri]. This version is useful if you are interested in receiving error information in the case where the application is sandboxed and the portal may present an application chooser dialog to the user. This is also useful if you want to be sure that the D-Bus–activated applications are really started before termination and if you are interested in receiving error information from their activation. the uri to show optional launch context a [class@Gio.Cancellable] a [type@Gio.AsyncReadyCallback] to call when the request is done data to pass to @callback Finishes an asynchronous launch-default-for-uri operation. `TRUE` if the launch was successful, `FALSE` if @error is set the async result Removes all changes to the type associations done by [method@Gio.AppInfo.set_as_default_for_type], [method@Gio.AppInfo.set_as_default_for_extension], [method@Gio.AppInfo.add_supports_type] or [method@Gio.AppInfo.remove_supports_type]. a content type Adds a content type to the application information to indicate the application is capable of opening files with the given content type. `TRUE` on success, `FALSE` on error. the app info a string. Obtains the information whether the [iface@Gio.AppInfo] can be deleted. See [method@Gio.AppInfo.delete]. `TRUE` if @appinfo can be deleted the app info Checks if a supported content type can be removed from an application. `TRUE` if it is possible to remove supported content types from a given @appinfo, `FALSE` if not. the app info Tries to delete a [iface@Gio.AppInfo]. On some platforms, there may be a difference between user-defined [iface@Gio.AppInfo]s which can be deleted, and system-wide ones which cannot. See [method@Gio.AppInfo.can_delete]. `TRUE` if @appinfo has been deleted the app info Creates a duplicate of a [iface@Gio.AppInfo]. a duplicate of @appinfo. the app info Checks if two [iface@Gio.AppInfo]s are equal. Note that the check *may not* compare each individual field, and only does an identity check. In case detecting changes in the contents is needed, program code must additionally compare relevant fields. `TRUE` if @appinfo1 is equal to @appinfo2. `FALSE` otherwise. the first [iface@Gio.AppInfo]. the second [iface@Gio.AppInfo]. Gets the commandline with which the application will be started. a string containing the @appinfo’s commandline, or `NULL` if this information is not available the app info Gets a human-readable description of an installed application. a string containing a description of the application @appinfo, or `NULL` if none. the app info Gets the display name of the application. The display name is often more descriptive to the user than the name itself. the display name of the application for @appinfo, or the name if no display name is available. the app info Gets the executable’s name for the installed application. This is intended to be used for debugging or labelling what program is going to be run. To launch the executable, use [method@Gio.AppInfo.launch] and related functions, rather than spawning the return value from this function. a string containing the @appinfo’s application binaries name the app info Gets the icon for the application. the default [iface@Gio.Icon] for @appinfo or `NULL` if there is no default icon. the app info Gets the ID of an application. An id is a string that identifies the application. The exact format of the id is platform dependent. For instance, on Unix this is the desktop file id from the xdg menu specification. Note that the returned ID may be `NULL`, depending on how the @appinfo has been constructed. a string containing the application’s ID. the app info Gets the installed name of the application. the name of the application for @appinfo. the app info Retrieves the list of content types that @app_info claims to support. If this information is not provided by the environment, this function will return `NULL`. This function does not take in consideration associations added with [method@Gio.AppInfo.add_supports_type], but only those exported directly by the application. a list of content types. an app info that can handle files Launches the application. Passes @files to the launched application as arguments, using the optional @context to get information about the details of the launcher (like what screen it is on). On error, @error will be set accordingly. To launch the application without arguments pass a `NULL` @files list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this. Some URIs can be changed when passed through a GFile (for instance unsupported URIs with strange formats like mailto:), so if you have a textual URI you want to pass in as argument, consider using [method@Gio.AppInfo.launch_uris] instead. The launched application inherits the environment of the launching process, but it can be modified with [method@Gio.AppLaunchContext.setenv] and [method@Gio.AppLaunchContext.unsetenv]. On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE` environment variable with the path of the launched desktop file and `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`, should it be inherited by further processes. The `DISPLAY`, `XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID` environment variables are also set, based on information provided in @context. `TRUE` on successful launch, `FALSE` otherwise. the app info a list of [iface@Gio.File] objects the launch context Launches the application. This passes the @uris to the launched application as arguments, using the optional @context to get information about the details of the launcher (like what screen it is on). On error, @error will be set accordingly. If the application only supports one URI per invocation as part of their command-line, multiple instances of the application will be spawned. To launch the application without arguments pass a `NULL` @uris list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this. `TRUE` on successful launch, `FALSE` otherwise. the app info a list of URIs to launch. the launch context Async version of [method@Gio.AppInfo.launch_uris]. The @callback is invoked immediately after the application launch, but it waits for activation in case of D-Bus–activated applications and also provides extended error information for sandboxed applications, see notes for [func@Gio.AppInfo.launch_default_for_uri_async]. the app info a list of URIs to launch. the launch context a [class@Gio.Cancellable] a [type@Gio.AsyncReadyCallback] to call when the request is done data to pass to @callback Finishes a [method@Gio.AppInfo.launch_uris_async] operation. `TRUE` on successful launch, `FALSE` otherwise. the app info the async result Removes a supported type from an application, if possible. `TRUE` on success, `FALSE` on error. the app info a string. Sets the application as the default handler for the given file extension. `TRUE` on success, `FALSE` on error. the app info a string containing the file extension (without the dot). Sets the application as the default handler for a given type. `TRUE` on success, `FALSE` on error. the app info the content type. Sets the application as the last used application for a given type. This will make the application appear as first in the list returned by [func@Gio.AppInfo.get_recommended_for_type], regardless of the default application for that content type. `TRUE` on success, `FALSE` on error. the app info the content type. Checks if the application info should be shown in menus that list available applications. `TRUE` if the @appinfo should be shown, `FALSE` otherwise. the app info Checks if the application accepts files as arguments. `TRUE` if the @appinfo supports files. the app info Checks if the application supports reading files and directories from URIs. `TRUE` if the @appinfo supports URIs. the app info Adds a content type to the application information to indicate the application is capable of opening files with the given content type. `TRUE` on success, `FALSE` on error. the app info a string. Obtains the information whether the [iface@Gio.AppInfo] can be deleted. See [method@Gio.AppInfo.delete]. `TRUE` if @appinfo can be deleted the app info Checks if a supported content type can be removed from an application. `TRUE` if it is possible to remove supported content types from a given @appinfo, `FALSE` if not. the app info Tries to delete a [iface@Gio.AppInfo]. On some platforms, there may be a difference between user-defined [iface@Gio.AppInfo]s which can be deleted, and system-wide ones which cannot. See [method@Gio.AppInfo.can_delete]. `TRUE` if @appinfo has been deleted the app info Creates a duplicate of a [iface@Gio.AppInfo]. a duplicate of @appinfo. the app info Checks if two [iface@Gio.AppInfo]s are equal. Note that the check *may not* compare each individual field, and only does an identity check. In case detecting changes in the contents is needed, program code must additionally compare relevant fields. `TRUE` if @appinfo1 is equal to @appinfo2. `FALSE` otherwise. the first [iface@Gio.AppInfo]. the second [iface@Gio.AppInfo]. Gets the commandline with which the application will be started. a string containing the @appinfo’s commandline, or `NULL` if this information is not available the app info Gets a human-readable description of an installed application. a string containing a description of the application @appinfo, or `NULL` if none. the app info Gets the display name of the application. The display name is often more descriptive to the user than the name itself. the display name of the application for @appinfo, or the name if no display name is available. the app info Gets the executable’s name for the installed application. This is intended to be used for debugging or labelling what program is going to be run. To launch the executable, use [method@Gio.AppInfo.launch] and related functions, rather than spawning the return value from this function. a string containing the @appinfo’s application binaries name the app info Gets the icon for the application. the default [iface@Gio.Icon] for @appinfo or `NULL` if there is no default icon. the app info Gets the ID of an application. An id is a string that identifies the application. The exact format of the id is platform dependent. For instance, on Unix this is the desktop file id from the xdg menu specification. Note that the returned ID may be `NULL`, depending on how the @appinfo has been constructed. a string containing the application’s ID. the app info Gets the installed name of the application. the name of the application for @appinfo. the app info Retrieves the list of content types that @app_info claims to support. If this information is not provided by the environment, this function will return `NULL`. This function does not take in consideration associations added with [method@Gio.AppInfo.add_supports_type], but only those exported directly by the application. a list of content types. an app info that can handle files Launches the application. Passes @files to the launched application as arguments, using the optional @context to get information about the details of the launcher (like what screen it is on). On error, @error will be set accordingly. To launch the application without arguments pass a `NULL` @files list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this. Some URIs can be changed when passed through a GFile (for instance unsupported URIs with strange formats like mailto:), so if you have a textual URI you want to pass in as argument, consider using [method@Gio.AppInfo.launch_uris] instead. The launched application inherits the environment of the launching process, but it can be modified with [method@Gio.AppLaunchContext.setenv] and [method@Gio.AppLaunchContext.unsetenv]. On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE` environment variable with the path of the launched desktop file and `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`, should it be inherited by further processes. The `DISPLAY`, `XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID` environment variables are also set, based on information provided in @context. `TRUE` on successful launch, `FALSE` otherwise. the app info a list of [iface@Gio.File] objects the launch context Launches the application. This passes the @uris to the launched application as arguments, using the optional @context to get information about the details of the launcher (like what screen it is on). On error, @error will be set accordingly. If the application only supports one URI per invocation as part of their command-line, multiple instances of the application will be spawned. To launch the application without arguments pass a `NULL` @uris list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this. `TRUE` on successful launch, `FALSE` otherwise. the app info a list of URIs to launch. the launch context Async version of [method@Gio.AppInfo.launch_uris]. The @callback is invoked immediately after the application launch, but it waits for activation in case of D-Bus–activated applications and also provides extended error information for sandboxed applications, see notes for [func@Gio.AppInfo.launch_default_for_uri_async]. the app info a list of URIs to launch. the launch context a [class@Gio.Cancellable] a [type@Gio.AsyncReadyCallback] to call when the request is done data to pass to @callback Finishes a [method@Gio.AppInfo.launch_uris_async] operation. `TRUE` on successful launch, `FALSE` otherwise. the app info the async result Removes a supported type from an application, if possible. `TRUE` on success, `FALSE` on error. the app info a string. Sets the application as the default handler for the given file extension. `TRUE` on success, `FALSE` on error. the app info a string containing the file extension (without the dot). Sets the application as the default handler for a given type. `TRUE` on success, `FALSE` on error. the app info the content type. Sets the application as the last used application for a given type. This will make the application appear as first in the list returned by [func@Gio.AppInfo.get_recommended_for_type], regardless of the default application for that content type. `TRUE` on success, `FALSE` on error. the app info the content type. Checks if the application info should be shown in menus that list available applications. `TRUE` if the @appinfo should be shown, `FALSE` otherwise. the app info Checks if the application accepts files as arguments. `TRUE` if the @appinfo supports files. the app info Checks if the application supports reading files and directories from URIs. `TRUE` if the @appinfo supports URIs. the app info Flags used when creating a #GAppInfo. No flags. Application opens in a terminal window. Application supports URI arguments. Application supports startup notification. Since 2.26 Application Information interface, for operating system portability. The parent interface. Copies a [iface@Gio.AppInfo]. a duplicate of @appinfo. the app info Checks two [iface@Gio.AppInfo]s for equality. `TRUE` if @appinfo1 is equal to @appinfo2. `FALSE` otherwise. the first [iface@Gio.AppInfo]. the second [iface@Gio.AppInfo]. Gets a string identifier for a [iface@Gio.AppInfo]. a string containing the application’s ID. the app info Gets the name of the application for a [iface@Gio.AppInfo]. the name of the application for @appinfo. the app info Gets a short description for the application described by the [iface@Gio.AppInfo]. a string containing a description of the application @appinfo, or `NULL` if none. the app info Gets the executable name for the [iface@Gio.AppInfo]. a string containing the @appinfo’s application binaries name the app info Gets the [iface@Gio.Icon] for the [iface@Gio.AppInfo]. the default [iface@Gio.Icon] for @appinfo or `NULL` if there is no default icon. the app info Launches an application specified by the [iface@Gio.AppInfo]. `TRUE` on successful launch, `FALSE` otherwise. the app info a list of [iface@Gio.File] objects the launch context Indicates whether the application specified supports launching URIs. `TRUE` if the @appinfo supports URIs. the app info Indicates whether the application specified accepts filename arguments. `TRUE` if the @appinfo supports files. the app info Launches an application with a list of URIs. `TRUE` on successful launch, `FALSE` otherwise. the app info a list of URIs to launch. the launch context Returns whether an application should be shown (e.g. when getting a list of installed applications). [FreeDesktop.Org Startup Notification Specification](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). `TRUE` if the @appinfo should be shown, `FALSE` otherwise. the app info Sets an application as default for a given content type. `TRUE` on success, `FALSE` on error. the app info the content type. Sets an application as default for a given file extension. `TRUE` on success, `FALSE` on error. the app info a string containing the file extension (without the dot). Adds to the [iface@Gio.AppInfo] information about supported file types. `TRUE` on success, `FALSE` on error. the app info a string. Checks for support for removing supported file types from a [iface@Gio.AppInfo]. `TRUE` if it is possible to remove supported content types from a given @appinfo, `FALSE` if not. the app info Removes a supported application type from a [iface@Gio.AppInfo]. `TRUE` on success, `FALSE` on error. the app info a string. Checks if a [iface@Gio.AppInfo] can be deleted. (Since 2.20) `TRUE` if @appinfo can be deleted the app info Deletes a [iface@Gio.AppInfo]. (Since 2.20) `TRUE` if @appinfo has been deleted the app info Gets the commandline for the [iface@Gio.AppInfo]. (Since 2.20) a string containing the @appinfo’s commandline, or `NULL` if this information is not available the app info Gets the display name for the [iface@Gio.AppInfo]. (Since 2.24) the display name of the application for @appinfo, or the name if no display name is available. the app info Sets the application as the last used. See [method@Gio.AppInfo.set_as_last_used_for_type]. `TRUE` on success, `FALSE` on error. the app info the content type. Retrieves the list of content types that @app_info claims to support. a list of content types. an app info that can handle files Asynchronously launches an application with a list of URIs. (Since: 2.60) the app info a list of URIs to launch. the launch context a [class@Gio.Cancellable] a [type@Gio.AsyncReadyCallback] to call when the request is done data to pass to @callback Finishes an operation started with @launch_uris_async. (Since: 2.60) `TRUE` on successful launch, `FALSE` otherwise. the app info the async result `GAppInfoMonitor` monitors application information for changes. `GAppInfoMonitor` is a very simple object used for monitoring the app info database for changes (newly installed or removed applications). Call [func@Gio.AppInfoMonitor.get] to get a `GAppInfoMonitor` and connect to the [signal@Gio.AppInfoMonitor::changed] signal. The signal will be emitted once when the app info database changes, and will not be emitted again until after the next call to [func@Gio.AppInfo.get_all] or another `g_app_info_*()` function. This is because monitoring the app info database for changes is expensive. The following functions will re-arm the [signal@Gio.AppInfoMonitor::changed] signal so it can be emitted again: - [func@Gio.AppInfo.get_all] - [func@Gio.AppInfo.get_all_for_type] - [func@Gio.AppInfo.get_default_for_type] - [func@Gio.AppInfo.get_fallback_for_type] - [func@Gio.AppInfo.get_recommended_for_type] - [`g_desktop_app_info_get_implementations()`](../gio-unix/type_func.DesktopAppInfo.get_implementation.html) - [`g_desktop_app_info_new()`](../gio-unix/ctor.DesktopAppInfo.new.html) - [`g_desktop_app_info_new_from_filename()`](../gio-unix/ctor.DesktopAppInfo.new_from_filename.html) - [`g_desktop_app_info_new_from_keyfile()`](../gio-unix/ctor.DesktopAppInfo.new_from_keyfile.html) - [`g_desktop_app_info_search()`](../gio-unix/type_func.DesktopAppInfo.search.html) The latter functions are available if using [`GDesktopAppInfo`](../gio-unix/class.DesktopAppInfo.html) from `gio-unix-2.0.pc` (GIR namespace `GioUnix-2.0`). In the usual case, applications should try to make note of the change (doing things like invalidating caches) but not act on it. In particular, applications should avoid making calls to `GAppInfo` APIs in response to the change signal, deferring these until the time that the updated data is actually required. The exception to this case is when application information is actually being displayed on the screen (for example, during a search or when the list of all applications is shown). The reason for this is that changes to the list of installed applications often come in groups (like during system updates) and rescanning the list on every change is pointless and expensive. Gets the #GAppInfoMonitor for the current thread-default main context. The #GAppInfoMonitor will emit a “changed” signal in the thread-default main context whenever the list of installed applications (as reported by g_app_info_get_all()) may have changed. The #GAppInfoMonitor::changed signal will only be emitted once until g_app_info_get_all() (or another `g_app_info_*()` function) is called. Doing so will re-arm the signal ready to notify about the next change. You must only call g_object_unref() on the return value from under the same main context as you created it. a reference to a #GAppInfoMonitor Signal emitted when the app info database changes, when applications are installed or removed. Integrating the launch with the launching application. This is used to handle for instance startup notification and launching the new application on the same screen as the launching window. Creates a new application launch context. This is not normally used, instead you instantiate a subclass of this, such as [`GdkAppLaunchContext`](https://docs.gtk.org/gdk4/class.AppLaunchContext.html). a launch context. Gets the display string for the @context. This is used to ensure new applications are started on the same display as the launching application, by setting the `DISPLAY` environment variable. a display string for the display. the launch context the app info a list of [iface@Gio.File] objects Initiates startup notification for the application and returns the `XDG_ACTIVATION_TOKEN` or `DESKTOP_STARTUP_ID` for the launched operation, if supported. The returned token may be referred to equivalently as an ‘activation token’ (using Wayland terminology) or a ‘startup sequence ID’ (using X11 terminology). The two [are interoperable](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/x11-interoperation.rst). Activation tokens are defined in the [XDG Activation Protocol](https://wayland.app/protocols/xdg-activation-v1), and startup notification IDs are defined in the [freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). Support for the XDG Activation Protocol was added in GLib 2.76. Since GLib 2.82 @info and @files can be `NULL`. If that’s not supported by the backend, the returned token will be `NULL`. a startup notification ID for the application, or `NULL` if not supported. the launch context the app info a list of [iface@Gio.File] objects Called when an application has failed to launch, so that it can cancel the application startup notification started in [method@Gio.AppLaunchContext.get_startup_notify_id]. the launch context the startup notification id that was returned by [method@Gio.AppLaunchContext.get_startup_notify_id]. Gets the display string for the @context. This is used to ensure new applications are started on the same display as the launching application, by setting the `DISPLAY` environment variable. a display string for the display. the launch context the app info a list of [iface@Gio.File] objects Gets the complete environment variable list to be passed to the child process when @context is used to launch an application. This is a `NULL`-terminated array of strings, where each string has the form `KEY=VALUE`. the child’s environment the launch context Initiates startup notification for the application and returns the `XDG_ACTIVATION_TOKEN` or `DESKTOP_STARTUP_ID` for the launched operation, if supported. The returned token may be referred to equivalently as an ‘activation token’ (using Wayland terminology) or a ‘startup sequence ID’ (using X11 terminology). The two [are interoperable](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/x11-interoperation.rst). Activation tokens are defined in the [XDG Activation Protocol](https://wayland.app/protocols/xdg-activation-v1), and startup notification IDs are defined in the [freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). Support for the XDG Activation Protocol was added in GLib 2.76. Since GLib 2.82 @info and @files can be `NULL`. If that’s not supported by the backend, the returned token will be `NULL`. a startup notification ID for the application, or `NULL` if not supported. the launch context the app info a list of [iface@Gio.File] objects Called when an application has failed to launch, so that it can cancel the application startup notification started in [method@Gio.AppLaunchContext.get_startup_notify_id]. the launch context the startup notification id that was returned by [method@Gio.AppLaunchContext.get_startup_notify_id]. Arranges for @variable to be set to @value in the child’s environment when @context is used to launch an application. the launch context the environment variable to set the value for to set the variable to. Arranges for @variable to be unset in the child’s environment when @context is used to launch an application. the launch context the environment variable to remove The [signal@Gio.AppLaunchContext::launch-failed] signal is emitted when a [iface@Gio.AppInfo] launch fails. The startup notification id is provided, so that the launcher can cancel the startup notification. Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple times, one for each spawned instance. the startup notification id for the failed launch The [signal@Gio.AppLaunchContext::launch-started] signal is emitted when a [iface@Gio.AppInfo] is about to be launched. If non-null the @platform_data is an GVariant dictionary mapping strings to variants (ie `a{sv}`), which contains additional, platform-specific data about this launch. On UNIX, at least the `startup-notification-id` keys will be present. The value of the `startup-notification-id` key (type `s`) is a startup notification ID corresponding to the format from the [startup-notification specification](https://specifications.freedesktop.org/startup-notification-spec/startup-notification-0.1.txt). It allows tracking the progress of the launchee through startup. It is guaranteed that this signal is followed by either a [signal@Gio.AppLaunchContext::launched] or [signal@Gio.AppLaunchContext::launch-failed] signal. Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple times, one for each spawned instance. the [iface@Gio.AppInfo] that is about to be launched additional platform-specific data for this launch The [signal@Gio.AppLaunchContext::launched] signal is emitted when a [iface@Gio.AppInfo] is successfully launched. Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple times, one time for each spawned instance. The @platform_data is an GVariant dictionary mapping strings to variants (ie `a{sv}`), which contains additional, platform-specific data about this launch. On UNIX, at least the `pid` and `startup-notification-id` keys will be present. Since 2.72 the `pid` may be 0 if the process id wasn’t known (for example if the process was launched via D-Bus). The `pid` may not be set at all in subsequent releases. On Windows, `pid` is guaranteed to be valid only for the duration of the [signal@Gio.AppLaunchContext::launched] signal emission; after the signal is emitted, GLib will call [func@GLib.spawn_close_pid]. If you need to keep the [alias@GLib.Pid] after the signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. the [iface@Gio.AppInfo] that was just launched additional platform-specific data for this launch a display string for the display. the launch context the app info a list of [iface@Gio.File] objects a startup notification ID for the application, or `NULL` if not supported. the launch context the app info a list of [iface@Gio.File] objects the launch context the startup notification id that was returned by [method@Gio.AppLaunchContext.get_startup_notify_id]. `GApplication` is the core class for application support. A `GApplication` is the foundation of an application. It wraps some low-level platform-specific services and is intended to act as the foundation for higher-level application classes such as `GtkApplication` or `MxApplication`. In general, you should not use this class outside of a higher level framework. `GApplication` provides convenient life-cycle management by maintaining a "use count" for the primary application instance. The use count can be changed using [method@Gio.Application.hold] and [method@Gio.Application.release]. If it drops to zero, the application exits. Higher-level classes such as `GtkApplication` employ the use count to ensure that the application stays alive as long as it has any opened windows. Another feature that `GApplication` (optionally) provides is process uniqueness. Applications can make use of this functionality by providing a unique application ID. If given, only one application with this ID can be running at a time per session. The session concept is platform-dependent, but corresponds roughly to a graphical desktop login. When your application is launched again, its arguments are passed through platform communication to the already running program. The already running instance of the program is called the "primary instance"; for non-unique applications this is always the current instance. On Linux, the D-Bus session bus is used for communication. The use of `GApplication` differs from some other commonly-used uniqueness libraries (such as libunique) in important ways. The application is not expected to manually register itself and check if it is the primary instance. Instead, the main() function of a `GApplication` should do very little more than instantiating the application instance, possibly connecting signal handlers, then calling [method@Gio.Application.run]. All checks for uniqueness are done internally. If the application is the primary instance then the startup signal is emitted and the mainloop runs. If the application is not the primary instance then a signal is sent to the primary instance and [method@Gio.Application.run] promptly returns. See the code examples below. If used, the expected form of an application identifier is the same as that of a [D-Bus well-known bus name](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). Examples include: `com.example.MyApp`, `org.example.internal_apps.Calculator`, `org._7_zip.Archiver`. For details on valid application identifiers, see [func@Gio.Application.id_is_valid]. On Linux, the application identifier is claimed as a well-known bus name on the user's session bus. This means that the uniqueness of your application is scoped to the current session. It also means that your application may provide additional services (through registration of other object paths) at that bus name. The registration of these object paths should be done with the shared GDBus session bus. Note that due to the internal architecture of GDBus, method calls can be dispatched at any time (even if a main loop is not running). For this reason, you must ensure that any object paths that you wish to register are registered before #GApplication attempts to acquire the bus name of your application (which happens in [method@Gio.Application.register]). Unfortunately, this means that you cannot use [property@Gio.Application:is-remote] to decide if you want to register object paths. `GApplication` also implements the [iface@Gio.ActionGroup] and [iface@Gio.ActionMap] interfaces and lets you easily export actions by adding them with [method@Gio.ActionMap.add_action]. When invoking an action by calling [method@Gio.ActionGroup.activate_action] on the application, it is always invoked in the primary instance. The actions are also exported on the session bus, and GIO provides the [class@Gio.DBusActionGroup] wrapper to conveniently access them remotely. GIO provides a [class@Gio.DBusMenuModel] wrapper for remote access to exported [class@Gio.MenuModel]s. Note: Due to the fact that actions are exported on the session bus, using `maybe` parameters is not supported, since D-Bus does not support `maybe` types. There is a number of different entry points into a `GApplication`: - via 'Activate' (i.e. just starting the application) - via 'Open' (i.e. opening some files) - by handling a command-line - via activating an action The [signal@Gio.Application::startup] signal lets you handle the application initialization for all of these in a single place. Regardless of which of these entry points is used to start the application, `GApplication` passes some ‘platform data’ from the launching instance to the primary instance, in the form of a [struct@GLib.Variant] dictionary mapping strings to variants. To use platform data, override the [vfunc@Gio.Application.before_emit] or [vfunc@Gio.Application.after_emit] virtual functions in your `GApplication` subclass. When dealing with [class@Gio.ApplicationCommandLine] objects, the platform data is directly available via [method@Gio.ApplicationCommandLine.get_cwd], [method@Gio.ApplicationCommandLine.get_environ] and [method@Gio.ApplicationCommandLine.get_platform_data]. As the name indicates, the platform data may vary depending on the operating system, but it always includes the current directory (key `cwd`), and optionally the environment (ie the set of environment variables and their values) of the calling process (key `environ`). The environment is only added to the platform data if the `G_APPLICATION_SEND_ENVIRONMENT` flag is set. `GApplication` subclasses can add their own platform data by overriding the [vfunc@Gio.Application.add_platform_data] virtual function. For instance, `GtkApplication` adds startup notification data in this way. To parse commandline arguments you may handle the [signal@Gio.Application::command-line] signal or override the [vfunc@Gio.Application.local_command_line] virtual function, to parse them in either the primary instance or the local instance, respectively. For an example of opening files with a `GApplication`, see [gapplication-example-open.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-open.c). For an example of using actions with `GApplication`, see [gapplication-example-actions.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-actions.c). For an example of using extra D-Bus hooks with `GApplication`, see [gapplication-example-dbushooks.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-dbushooks.c). Creates a new #GApplication instance. If non-%NULL, the application id must be valid. See g_application_id_is_valid(). If no application ID is given then some features of #GApplication (most notably application uniqueness) will be disabled. a new #GApplication instance the application id the application flags Returns the default #GApplication instance for this process. Normally there is only one #GApplication per process and it becomes the default when it is created. You can exercise more control over this by using g_application_set_default(). If there is no default application then %NULL is returned. the default application for this process, or %NULL Checks if @application_id is a valid application identifier. A valid ID is required for calls to g_application_new() and g_application_set_application_id(). Application identifiers follow the same format as [D-Bus well-known bus names](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). For convenience, the restrictions on application identifiers are reproduced here: - Application identifiers are composed of 1 or more elements separated by a period (`.`) character. All elements must contain at least one character. - Each element must only contain the ASCII characters `[A-Z][a-z][0-9]_-`, with `-` discouraged in new application identifiers. Each element must not begin with a digit. - Application identifiers must contain at least one `.` (period) character (and thus at least two elements). - Application identifiers must not begin with a `.` (period) character. - Application identifiers must not exceed 255 characters. Note that the hyphen (`-`) character is allowed in application identifiers, but is problematic or not allowed in various specifications and APIs that refer to D-Bus, such as [Flatpak application IDs](http://docs.flatpak.org/en/latest/introduction.html#identifiers), the [`DBusActivatable` interface in the Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus), and the convention that an application's "main" interface and object path resemble its application identifier and bus name. To avoid situations that require special-case handling, it is recommended that new application identifiers consistently replace hyphens with underscores. Like D-Bus interface names, application identifiers should start with the reversed DNS domain name of the author of the interface (in lower-case), and it is conventional for the rest of the application identifier to consist of words run together, with initial capital letters. As with D-Bus interface names, if the author's DNS domain name contains hyphen/minus characters they should be replaced by underscores, and if it contains leading digits they should be escaped by prepending an underscore. For example, if the owner of 7-zip.org used an application identifier for an archiving application, it might be named `org._7_zip.Archiver`. %TRUE if @application_id is valid a potential application identifier Activates the application. In essence, this results in the #GApplication::activate signal being emitted in the primary instance. The application must be registered before calling this function. a #GApplication invoked (locally) to add 'platform data' to be sent to the primary instance when activating, opening or invoking actions. Must chain up invoked on the primary instance after 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance. Must chain up invoked on the primary instance before 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance. Must chain up invoked on the primary instance when a command-line is not handled locally invoked locally during registration, if the application is using its D-Bus backend. You can use this to export extra objects on the bus, that need to exist before the application tries to own the bus name. The function is passed the #GDBusConnection to to session bus, and the object path that #GApplication will use to export its D-Bus API. If this function returns %TRUE, registration will proceed; otherwise registration will abort. Since: 2.34 invoked locally during unregistration, if the application is using its D-Bus backend. Use this to undo anything done by the @dbus_register vfunc. Since: 2.34 invoked locally after the parsing of the commandline options has occurred. Since: 2.40 This virtual function is always invoked in the local instance. It gets passed a pointer to a %NULL-terminated copy of @argv and is expected to remove arguments that it handled (shifting up remaining arguments). The last argument to local_command_line() is a pointer to the @status variable which can used to set the exit status that is returned from g_application_run(). See g_application_run() for more details on #GApplication startup. %TRUE if the commandline has been completely handled a #GApplication array of command line arguments exit status to fill after processing the command line. invoked when another instance is taking over the name. Since: 2.60 Opens the given files. In essence, this results in the #GApplication::open signal being emitted in the primary instance. @n_files must be greater than zero. @hint is simply passed through to the ::open signal. It is intended to be used by applications that have multiple modes for opening files (eg: "view" vs "edit", etc). Unless you have a need for this functionality, you should use "". The application must be registered before calling this function and it must have the %G_APPLICATION_HANDLES_OPEN flag set. a #GApplication an array of #GFiles to open the length of the @files array a hint (or ""), but never %NULL Used to be invoked on the primary instance when the use count of the application drops to zero (and after any inactivity timeout, if requested). Not used anymore since 2.32 Used to be invoked on the primary instance from g_application_run() if the use-count is non-zero. Since 2.32, GApplication is iterating the main context directly and is not using @run_mainloop anymore invoked only on the registered primary instance immediately after the main loop terminates invoked on the primary instance immediately after registration Activates the application. In essence, this results in the #GApplication::activate signal being emitted in the primary instance. The application must be registered before calling this function. a #GApplication Add an option to be handled by @application. Calling this function is the equivalent of calling g_application_add_main_option_entries() with a single #GOptionEntry that has its arg_data member set to %NULL. The parsed arguments will be packed into a #GVariantDict which is passed to #GApplication::handle-local-options. If %G_APPLICATION_HANDLES_COMMAND_LINE is set, then it will also be sent to the primary instance. See g_application_add_main_option_entries() for more details. See #GOptionEntry for more documentation of the arguments. the #GApplication the long name of an option used to specify it in a commandline the short name of an option flags from #GOptionFlags the type of the option, as a #GOptionArg the description for the option in `--help` output the placeholder to use for the extra argument parsed by the option in `--help` output Adds main option entries to be handled by @application. This function is comparable to g_option_context_add_main_entries(). After the commandline arguments are parsed, the #GApplication::handle-local-options signal will be emitted. At this point, the application can inspect the values pointed to by @arg_data in the given #GOptionEntrys. Unlike #GOptionContext, #GApplication supports giving a %NULL @arg_data for a non-callback #GOptionEntry. This results in the argument in question being packed into a #GVariantDict which is also passed to #GApplication::handle-local-options, where it can be inspected and modified. If %G_APPLICATION_HANDLES_COMMAND_LINE is set, then the resulting dictionary is sent to the primary instance, where g_application_command_line_get_options_dict() will return it. As it has been passed outside the process at this point, the types of all values in the options dict must be checked before being used. This "packing" is done according to the type of the argument -- booleans for normal flags, strings for strings, bytestrings for filenames, etc. The packing only occurs if the flag is given (ie: we do not pack a "false" #GVariant in the case that a flag is missing). In general, it is recommended that all commandline arguments are parsed locally. The options dictionary should then be used to transmit the result of the parsing to the primary instance, where g_variant_dict_lookup() can be used. For local options, it is possible to either use @arg_data in the usual way, or to consult (and potentially remove) the option from the options dictionary. This function is new in GLib 2.40. Before then, the only real choice was to send all of the commandline arguments (options and all) to the primary instance for handling. #GApplication ignored them completely on the local side. Calling this function "opts in" to the new behaviour, and in particular, means that unrecognized options will be treated as errors. Unrecognized options have never been ignored when %G_APPLICATION_HANDLES_COMMAND_LINE is unset. If #GApplication::handle-local-options needs to see the list of filenames, then the use of %G_OPTION_REMAINING is recommended. If @arg_data is %NULL then %G_OPTION_REMAINING can be used as a key into the options dictionary. If you do use %G_OPTION_REMAINING then you need to handle these arguments for yourself because once they are consumed, they will no longer be visible to the default handling (which treats them as filenames to be opened). It is important to use the proper GVariant format when retrieving the options with g_variant_dict_lookup(): - for %G_OPTION_ARG_NONE, use `b` - for %G_OPTION_ARG_STRING, use `&s` - for %G_OPTION_ARG_INT, use `i` - for %G_OPTION_ARG_INT64, use `x` - for %G_OPTION_ARG_DOUBLE, use `d` - for %G_OPTION_ARG_FILENAME, use `^&ay` - for %G_OPTION_ARG_STRING_ARRAY, use `^a&s` - for %G_OPTION_ARG_FILENAME_ARRAY, use `^a&ay` a #GApplication the main options for the application Adds a #GOptionGroup to the commandline handling of @application. This function is comparable to g_option_context_add_group(). Unlike g_application_add_main_option_entries(), this function does not deal with %NULL @arg_data and never transmits options to the primary instance. The reason for that is because, by the time the options arrive at the primary instance, it is typically too late to do anything with them. Taking the GTK option group as an example: GTK will already have been initialised by the time the #GApplication::command-line handler runs. In the case that this is not the first-running instance of the application, the existing instance may already have been running for a very long time. This means that the options from #GOptionGroup are only really usable in the case that the instance of the application being run is the first instance. Passing options like `--display=` or `--gdk-debug=` on future runs will have no effect on the existing primary instance. Calling this function will cause the options in the supplied option group to be parsed, but it does not cause you to be "opted in" to the new functionality whereby unrecognized options are rejected even if %G_APPLICATION_HANDLES_COMMAND_LINE was given. the #GApplication a #GOptionGroup Marks @application as busy (see g_application_mark_busy()) while @property on @object is %TRUE. The binding holds a reference to @application while it is active, but not to @object. Instead, the binding is destroyed when @object is finalized. a #GApplication a #GObject the name of a boolean property of @object Gets the unique identifier for @application. the identifier for @application, owned by @application a #GApplication Gets the #GDBusConnection being used by the application, or %NULL. If #GApplication is using its D-Bus backend then this function will return the #GDBusConnection being used for uniqueness and communication with the desktop environment and other instances of the application. If #GApplication is not using D-Bus then this function will return %NULL. This includes the situation where the D-Bus backend would normally be in use but we were unable to connect to the bus. This function must not be called before the application has been registered. See g_application_get_is_registered(). a #GDBusConnection, or %NULL a #GApplication Gets the D-Bus object path being used by the application, or %NULL. If #GApplication is using its D-Bus backend then this function will return the D-Bus object path that #GApplication is using. If the application is the primary instance then there is an object published at this path. If the application is not the primary instance then the result of this function is undefined. If #GApplication is not using D-Bus then this function will return %NULL. This includes the situation where the D-Bus backend would normally be in use but we were unable to connect to the bus. This function must not be called before the application has been registered. See g_application_get_is_registered(). the object path, or %NULL a #GApplication Gets the flags for @application. See #GApplicationFlags. the flags for @application a #GApplication Gets the current inactivity timeout for the application. This is the amount of time (in milliseconds) after the last call to g_application_release() before the application stops running. the timeout, in milliseconds a #GApplication Gets the application's current busy state, as set through g_application_mark_busy() or g_application_bind_busy_property(). %TRUE if @application is currently marked as busy a #GApplication Checks if @application is registered. An application is registered if g_application_register() has been successfully called. %TRUE if @application is registered a #GApplication Checks if @application is remote. If @application is remote then it means that another instance of application already exists (the 'primary' instance). Calls to perform actions on @application will result in the actions being performed by the primary instance. The value of this property cannot be accessed before g_application_register() has been called. See g_application_get_is_registered(). %TRUE if @application is remote a #GApplication Gets the resource base path of @application. See g_application_set_resource_base_path() for more information. the base resource path, if one is set a #GApplication Gets the version of @application. the version of @application a #GApplication Increases the use count of @application. Use this function to indicate that the application has a reason to continue to run. For example, g_application_hold() is called by GTK when a toplevel window is on the screen. To cancel the hold, call g_application_release(). a #GApplication Increases the busy count of @application. Use this function to indicate that the application is busy, for instance while a long running operation is pending. The busy state will be exposed to other processes, so a session shell will use that information to indicate the state to the user (e.g. with a spinner). To cancel the busy indication, use g_application_unmark_busy(). The application must be registered before calling this function. a #GApplication Opens the given files. In essence, this results in the #GApplication::open signal being emitted in the primary instance. @n_files must be greater than zero. @hint is simply passed through to the ::open signal. It is intended to be used by applications that have multiple modes for opening files (eg: "view" vs "edit", etc). Unless you have a need for this functionality, you should use "". The application must be registered before calling this function and it must have the %G_APPLICATION_HANDLES_OPEN flag set. a #GApplication an array of #GFiles to open the length of the @files array a hint (or ""), but never %NULL Immediately quits the application. Upon return to the mainloop, g_application_run() will return, calling only the 'shutdown' function before doing so. The hold count is ignored. Take care if your code has called g_application_hold() on the application and is therefore still expecting it to exist. (Note that you may have called g_application_hold() indirectly, for example through gtk_application_add_window().) The result of calling g_application_run() again after it returns is unspecified. a #GApplication Attempts registration of the application. This is the point at which the application discovers if it is the primary instance or merely acting as a remote for an already-existing primary instance. This is implemented by attempting to acquire the application identifier as a unique bus name on the session bus using GDBus. If there is no application ID or if %G_APPLICATION_NON_UNIQUE was given, then this process will always become the primary instance. Due to the internal architecture of GDBus, method calls can be dispatched at any time (even if a main loop is not running). For this reason, you must ensure that any object paths that you wish to register are registered before calling this function. If the application has already been registered then %TRUE is returned with no work performed. The #GApplication::startup signal is emitted if registration succeeds and @application is the primary instance (including the non-unique case). In the event of an error (such as @cancellable being cancelled, or a failure to connect to the session bus), %FALSE is returned and @error is set appropriately. Note: the return value of this function is not an indicator that this instance is or is not the primary instance of the application. See g_application_get_is_remote() for that. %TRUE if registration succeeded a #GApplication a #GCancellable, or %NULL Decrease the use count of @application. When the use count reaches zero, the application will stop running. Never call this function except to cancel the effect of a previous call to g_application_hold(). a #GApplication Runs the application. This function is intended to be run from main() and its return value is intended to be returned by main(). Although you are expected to pass the @argc, @argv parameters from main() to this function, it is possible to pass %NULL if @argv is not available or commandline handling is not required. Note that on Windows, @argc and @argv are ignored, and g_win32_get_command_line() is called internally (for proper support of Unicode commandline arguments). #GApplication will attempt to parse the commandline arguments. You can add commandline flags to the list of recognised options by way of g_application_add_main_option_entries(). After this, the #GApplication::handle-local-options signal is emitted, from which the application can inspect the values of its #GOptionEntrys. #GApplication::handle-local-options is a good place to handle options such as `--version`, where an immediate reply from the local process is desired (instead of communicating with an already-running instance). A #GApplication::handle-local-options handler can stop further processing by returning a non-negative value, which then becomes the exit status of the process. What happens next depends on the flags: if %G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining commandline arguments are sent to the primary instance, where a #GApplication::command-line signal is emitted. Otherwise, the remaining commandline arguments are assumed to be a list of files. If there are no files listed, the application is activated via the #GApplication::activate signal. If there are one or more files, and %G_APPLICATION_HANDLES_OPEN was specified then the files are opened via the #GApplication::open signal. If you are interested in doing more complicated local handling of the commandline then you should implement your own #GApplication subclass and override local_command_line(). In this case, you most likely want to return %TRUE from your local_command_line() implementation to suppress the default handling. See [gapplication-example-cmdline2.c][https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c] for an example. If, after the above is done, the use count of the application is zero then the exit status is returned immediately. If the use count is non-zero then the default main context is iterated until the use count falls to zero, at which point 0 is returned. If the %G_APPLICATION_IS_SERVICE flag is set, then the service will run for as much as 10 seconds with a use count of zero while waiting for the message that caused the activation to arrive. After that, if the use count falls to zero the application will exit immediately, except in the case that g_application_set_inactivity_timeout() is in use. This function sets the prgname (g_set_prgname()), if not already set, to the basename of argv[0]. Much like g_main_loop_run(), this function will acquire the main context for the duration that the application is running. Since 2.40, applications that are not explicitly flagged as services or launchers (ie: neither %G_APPLICATION_IS_SERVICE or %G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the default handler for local_command_line) if "--gapplication-service" was given in the command line. If this flag is present then normal commandline processing is interrupted and the %G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise" solution whereby running an application directly from the commandline will invoke it in the normal way (which can be useful for debugging) while still allowing applications to be D-Bus activated in service mode. The D-Bus service file should invoke the executable with "--gapplication-service" as the sole commandline argument. This approach is suitable for use by most graphical applications but should not be used from applications like editors that need precise control over when processes invoked via the commandline will exit and what their exit status will be. the exit status a #GApplication the argc from main() (or 0 if @argv is %NULL) the argv from main(), or %NULL Sends a notification on behalf of @application to the desktop shell. There is no guarantee that the notification is displayed immediately, or even at all. Notifications may persist after the application exits. It will be D-Bus-activated when the notification or one of its actions is activated. Modifying @notification after this call has no effect. However, the object can be reused for a later call to this function. @id may be any string that uniquely identifies the event for the application. It does not need to be in any special format. For example, "new-message" might be appropriate for a notification about new messages. If a previous notification was sent with the same @id, it will be replaced with @notification and shown again as if it was a new notification. This works even for notifications sent from a previous execution of the application, as long as @id is the same string. @id may be `NULL`, but it is impossible to replace or withdraw notifications without an id. If @notification is no longer relevant, it can be withdrawn with [method@Gio.Application.withdraw_notification]. It is an error to call this function if @application has no application ID. a #GApplication id of the notification, or %NULL the #GNotification to send This used to be how actions were associated with a #GApplication. Now there is #GActionMap for that. Use the #GActionMap interface instead. Never ever mix use of this API with use of #GActionMap on the same @application or things will go very badly wrong. This function is known to introduce buggy behaviour (ie: signals not emitted on changes to the action group), so you should really use #GActionMap instead. a #GApplication a #GActionGroup, or %NULL Sets the unique identifier for @application. The application id can only be modified if @application has not yet been registered. If non-%NULL, the application id must be valid. See g_application_id_is_valid(). a #GApplication the identifier for @application Sets or unsets the default application for the process, as returned by g_application_get_default(). This function does not take its own reference on @application. If @application is destroyed then the default application will revert back to %NULL. the application to set as default, or %NULL Sets the flags for @application. The flags can only be modified if @application has not yet been registered. See #GApplicationFlags. a #GApplication the flags for @application Sets the current inactivity timeout for the application. This is the amount of time (in milliseconds) after the last call to g_application_release() before the application stops running. This call has no side effects of its own. The value set here is only used for next time g_application_release() drops the use count to zero. Any timeouts currently in progress are not impacted. a #GApplication the timeout, in milliseconds Adds a description to the @application option context. See g_option_context_set_description() for more information. the #GApplication a string to be shown in `--help` output after the list of options, or %NULL Sets the parameter string to be used by the commandline handling of @application. This function registers the argument to be passed to g_option_context_new() when the internal #GOptionContext of @application is created. See g_option_context_new() for more information about @parameter_string. the #GApplication a string which is displayed in the first line of `--help` output, after the usage summary `programname [OPTION...]`. Adds a summary to the @application option context. See g_option_context_set_summary() for more information. the #GApplication a string to be shown in `--help` output before the list of options, or %NULL Sets (or unsets) the base resource path of @application. The path is used to automatically load various [application resources][struct@Gio.Resource] such as menu layouts and action descriptions. The various types of resources will be found at fixed names relative to the given base path. By default, the resource base path is determined from the application ID by prefixing '/' and replacing each '.' with '/'. This is done at the time that the #GApplication object is constructed. Changes to the application ID after that point will not have an impact on the resource base path. As an example, if the application has an ID of "org.example.app" then the default resource base path will be "/org/example/app". If this is a #GtkApplication (and you have not manually changed the path) then Gtk will then search for the menus of the application at "/org/example/app/gtk/menus.ui". See #GResource for more information about adding resources to your application. You can disable automatic resource loading functionality by setting the path to %NULL. Changing the resource base path once the application is running is not recommended. The point at which the resource path is consulted for forming paths for various purposes is unspecified. When writing a sub-class of #GApplication you should either set the #GApplication:resource-base-path property at construction time, or call this function during the instance initialization. Alternatively, you can call this function in the #GApplicationClass.startup virtual function, before chaining up to the parent implementation. a #GApplication the resource path to use Sets the version number of @application. This will be used to implement a `--version` command line argument The application version can only be modified if @application has not yet been registered. a #GApplication the version of @application Destroys a binding between @property and the busy state of @application that was previously created with g_application_bind_busy_property(). a #GApplication a #GObject the name of a boolean property of @object Decreases the busy count of @application. When the busy count reaches zero, the new state will be propagated to other processes. This function must only be called to cancel the effect of a previous call to g_application_mark_busy(). a #GApplication Withdraws a notification that was sent with g_application_send_notification(). This call does nothing if a notification with @id doesn't exist or the notification was never sent. This function works even for notifications sent in previous executions of this application, as long @id is the same as it was for the sent notification. Note that notifications are dismissed when the user clicks on one of the buttons in a notification or triggers its default action, so there is no need to explicitly withdraw the notification in that case. a #GApplication id of a previously sent notification The group of actions that the application exports. Use the [iface@Gio.ActionMap] interface instead. Never ever mix use of this API with use of `GActionMap` on the same @application or things will go very badly wrong. The unique identifier for the application. Flags specifying the behaviour of the application. Time (in milliseconds) to stay alive after becoming idle. Whether the application is currently marked as busy through g_application_mark_busy() or g_application_bind_busy_property(). Whether [method@Gio.Application.register] has been called. Whether this application instance is remote. The base resource path for the application. The human-readable version number of the application. The ::activate signal is emitted on the primary instance when an activation occurs. See g_application_activate(). The ::command-line signal is emitted on the primary instance when a commandline is not handled locally. See g_application_run() and the #GApplicationCommandLine documentation for more information. An integer that is set as the exit status for the calling process. See g_application_command_line_set_exit_status(). a #GApplicationCommandLine representing the passed commandline The ::handle-local-options signal is emitted on the local instance after the parsing of the commandline options has occurred. You can add options to be recognised during commandline option parsing using g_application_add_main_option_entries() and g_application_add_option_group(). Signal handlers can inspect @options (along with values pointed to from the @arg_data of an installed #GOptionEntrys) in order to decide to perform certain actions, including direct local handling (which may be useful for options like --version). In the event that the application is marked %G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will send the @options dictionary to the primary instance where it can be read with g_application_command_line_get_options_dict(). The signal handler can modify the dictionary before returning, and the modified dictionary will be sent. In the event that %G_APPLICATION_HANDLES_COMMAND_LINE is not set, "normal processing" will treat the remaining uncollected command line arguments as filenames or URIs. If there are no arguments, the application is activated by g_application_activate(). One or more arguments results in a call to g_application_open(). If you want to handle the local commandline arguments for yourself by converting them to calls to g_application_open() or g_action_group_activate_action() then you must be sure to register the application first. You should probably not call g_application_activate() for yourself, however: just return -1 and allow the default handler to do it for you. This will ensure that the `--gapplication-service` switch works properly (i.e. no activation in that case). Note that this signal is emitted from the default implementation of local_command_line(). If you override that function and don't chain up then this signal will never be emitted. You can override local_command_line() if you need more powerful capabilities than what is provided here, but this should not normally be required. an exit code. If you have handled your options and want to exit the process, return a non-negative option, 0 for success, and a positive value for failure. To continue, return -1 to let the default option processing continue. the options dictionary The ::name-lost signal is emitted only on the registered primary instance when a new instance has taken over. This can only happen if the application is using the %G_APPLICATION_ALLOW_REPLACEMENT flag. The default handler for this signal calls g_application_quit(). %TRUE if the signal has been handled The ::open signal is emitted on the primary instance when there are files to open. See g_application_open() for more information. an array of #GFiles the length of @files a hint provided by the calling instance The ::shutdown signal is emitted only on the registered primary instance immediately after the main loop terminates. The ::startup signal is emitted on the primary instance immediately after registration. See g_application_register(). Virtual function table for #GApplication. invoked on the primary instance immediately after registration invoked on the primary instance when an activation occurs a #GApplication invoked on the primary instance when there are files to open a #GApplication an array of #GFiles to open the length of the @files array a hint (or ""), but never %NULL invoked on the primary instance when a command-line is not handled locally invoked (locally). The virtual function has the chance to inspect (and possibly replace) command line arguments. See g_application_run() for more information. Also see the #GApplication::handle-local-options signal, which is a simpler alternative to handling some commandline options locally %TRUE if the commandline has been completely handled a #GApplication array of command line arguments exit status to fill after processing the command line. invoked on the primary instance before 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance. Must chain up invoked on the primary instance after 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance. Must chain up invoked (locally) to add 'platform data' to be sent to the primary instance when activating, opening or invoking actions. Must chain up Used to be invoked on the primary instance when the use count of the application drops to zero (and after any inactivity timeout, if requested). Not used anymore since 2.32 Used to be invoked on the primary instance from g_application_run() if the use-count is non-zero. Since 2.32, GApplication is iterating the main context directly and is not using @run_mainloop anymore invoked only on the registered primary instance immediately after the main loop terminates invoked locally during registration, if the application is using its D-Bus backend. You can use this to export extra objects on the bus, that need to exist before the application tries to own the bus name. The function is passed the #GDBusConnection to to session bus, and the object path that #GApplication will use to export its D-Bus API. If this function returns %TRUE, registration will proceed; otherwise registration will abort. Since: 2.34 invoked locally during unregistration, if the application is using its D-Bus backend. Use this to undo anything done by the @dbus_register vfunc. Since: 2.34 invoked locally after the parsing of the commandline options has occurred. Since: 2.40 invoked when another instance is taking over the name. Since: 2.60 `GApplicationCommandLine` represents a command-line invocation of an application. It is created by [class@Gio.Application] and emitted in the [signal@Gio.Application::command-line] signal and virtual function. The class contains the list of arguments that the program was invoked with. It is also possible to query if the commandline invocation was local (ie: the current process is running in direct response to the invocation) or remote (ie: some other process forwarded the commandline to this process). The `GApplicationCommandLine` object can provide the @argc and @argv parameters for use with the [struct@GLib.OptionContext] command-line parsing API, with the [method@Gio.ApplicationCommandLine.get_arguments] function. See [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c) for an example. The exit status of the originally-invoked process may be set and messages can be printed to stdout or stderr of that process. For remote invocation, the originally-invoked process exits when [method@Gio.ApplicationCommandLine.done] method is called. This method is also automatically called when the object is disposed. The main use for `GApplicationCommandLine` (and the [signal@Gio.Application::command-line] signal) is 'Emacs server' like use cases: You can set the `EDITOR` environment variable to have e.g. git use your favourite editor to edit commit messages, and if you already have an instance of the editor running, the editing will happen in the running instance, instead of opening a new one. An important aspect of this use case is that the process that gets started by git does not return until the editing is done. Normally, the commandline is completely handled in the [signal@Gio.Application::command-line] handler. The launching instance exits once the signal handler in the primary instance has returned, and the return value of the signal handler becomes the exit status of the launching instance. ```c static int command_line (GApplication *application, GApplicationCommandLine *cmdline) { gchar **argv; gint argc; gint i; argv = g_application_command_line_get_arguments (cmdline, &argc); g_application_command_line_print (cmdline, "This text is written back\n" "to stdout of the caller\n"); for (i = 0; i < argc; i++) g_print ("argument %d: %s\n", i, argv[i]); g_strfreev (argv); return 0; } ``` The complete example can be found here: [gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c) In more complicated cases, the handling of the commandline can be split between the launcher and the primary instance. ```c static gboolean test_local_cmdline (GApplication *application, gchar ***arguments, gint *exit_status) { gint i, j; gchar **argv; argv = *arguments; if (argv[0] == NULL) { *exit_status = 0; return FALSE; } i = 1; while (argv[i]) { if (g_str_has_prefix (argv[i], "--local-")) { g_print ("handling argument %s locally\n", argv[i]); g_free (argv[i]); for (j = i; argv[j]; j++) argv[j] = argv[j + 1]; } else { g_print ("not handling argument %s locally\n", argv[i]); i++; } } *exit_status = 0; return FALSE; } static void test_application_class_init (TestApplicationClass *class) { G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline; ... } ``` In this example of split commandline handling, options that start with `--local-` are handled locally, all other options are passed to the [signal@Gio.Application::command-line] handler which runs in the primary instance. The complete example can be found here: [gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c) If handling the commandline requires a lot of work, it may be better to defer it. ```c static gboolean my_cmdline_handler (gpointer data) { GApplicationCommandLine *cmdline = data; // do the heavy lifting in an idle g_application_command_line_set_exit_status (cmdline, 0); g_object_unref (cmdline); // this releases the application return G_SOURCE_REMOVE; } static int command_line (GApplication *application, GApplicationCommandLine *cmdline) { // keep the application running until we are done with this commandline g_application_hold (application); g_object_set_data_full (G_OBJECT (cmdline), "application", application, (GDestroyNotify)g_application_release); g_object_ref (cmdline); g_idle_add (my_cmdline_handler, cmdline); return 0; } ``` In this example the commandline is not completely handled before the [signal@Gio.Application::command-line] handler returns. Instead, we keep a reference to the `GApplicationCommandLine` object and handle it later (in this example, in an idle). Note that it is necessary to hold the application until you are done with the commandline. The complete example can be found here: [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c) Signals that command line processing is completed. For remote invocation, it causes the invoking process to terminate. For local invocation, it does nothing. This method should be called in the [signal@Gio.Application::command-line] handler, after the exit status is set and all messages are printed. After this call, g_application_command_line_set_exit_status() has no effect. Subsequent calls to this method are no-ops. This method is automatically called when the #GApplicationCommandLine object is disposed — so you can omit the call in non-garbage collected languages. a #GApplicationCommandLine Gets the stdin of the invoking process. The #GInputStream can be used to read data passed to the standard input of the invoking process. This doesn't work on all platforms. Presently, it is only available on UNIX when using a D-Bus daemon capable of passing file descriptors. If stdin is not available then %NULL will be returned. In the future, support may be expanded to other platforms. You must only call this function once per commandline invocation. a #GInputStream for stdin a #GApplicationCommandLine Prints a message using the stdout print handler in the invoking process. Unlike g_application_command_line_print(), @message is not a `printf()`-style format string. Use this function if @message contains text you don't have control over, that could include `printf()` escape sequences. a #GApplicationCommandLine the message Prints a message using the stderr print handler in the invoking process. Unlike g_application_command_line_printerr(), @message is not a `printf()`-style format string. Use this function if @message contains text you don't have control over, that could include `printf()` escape sequences. a #GApplicationCommandLine the message Creates a #GFile corresponding to a filename that was given as part of the invocation of @cmdline. This differs from g_file_new_for_commandline_arg() in that it resolves relative pathnames using the current working directory of the invoking process rather than the local process. a new #GFile a #GApplicationCommandLine an argument from @cmdline Signals that command line processing is completed. For remote invocation, it causes the invoking process to terminate. For local invocation, it does nothing. This method should be called in the [signal@Gio.Application::command-line] handler, after the exit status is set and all messages are printed. After this call, g_application_command_line_set_exit_status() has no effect. Subsequent calls to this method are no-ops. This method is automatically called when the #GApplicationCommandLine object is disposed — so you can omit the call in non-garbage collected languages. a #GApplicationCommandLine Gets the list of arguments that was passed on the command line. The strings in the array may contain non-UTF-8 data on UNIX (such as filenames or arguments given in the system locale) but are always in UTF-8 on Windows. If you wish to use the return value with #GOptionContext, you must use g_option_context_parse_strv(). The return value is %NULL-terminated and should be freed using g_strfreev(). the string array containing the arguments (the argv) a #GApplicationCommandLine the length of the arguments array, or %NULL Gets the working directory of the command line invocation. The string may contain non-utf8 data. It is possible that the remote application did not send a working directory, so this may be %NULL. The return value should not be modified or freed and is valid for as long as @cmdline exists. the current directory, or %NULL a #GApplicationCommandLine Gets the contents of the 'environ' variable of the command line invocation, as would be returned by g_get_environ(), ie as a %NULL-terminated list of strings in the form 'NAME=VALUE'. The strings may contain non-utf8 data. The remote application usually does not send an environment. Use %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag set it is possible that the environment is still not available (due to invocation messages from other applications). The return value should not be modified or freed and is valid for as long as @cmdline exists. See g_application_command_line_getenv() if you are only interested in the value of a single environment variable. the environment strings, or %NULL if they were not sent a #GApplicationCommandLine Gets the exit status of @cmdline. See g_application_command_line_set_exit_status() for more information. the exit status a #GApplicationCommandLine Determines if @cmdline represents a remote invocation. %TRUE if the invocation was remote a #GApplicationCommandLine Gets the options that were passed to g_application_command_line(). If you did not override local_command_line() then these are the same options that were parsed according to the #GOptionEntrys added to the application with g_application_add_main_option_entries() and possibly modified from your GApplication::handle-local-options handler. If no options were sent then an empty dictionary is returned so that you don't need to check for %NULL. The data has been passed via an untrusted external process, so the types of all values must be checked before being used. a #GVariantDict with the options a #GApplicationCommandLine Gets the platform data associated with the invocation of @cmdline. This is a #GVariant dictionary containing information about the context in which the invocation occurred. It typically contains information like the current working directory and the startup notification ID. It comes from an untrusted external process and hence the types of all values must be validated before being used. For local invocation, it will be %NULL. the platform data, or %NULL #GApplicationCommandLine Gets the stdin of the invoking process. The #GInputStream can be used to read data passed to the standard input of the invoking process. This doesn't work on all platforms. Presently, it is only available on UNIX when using a D-Bus daemon capable of passing file descriptors. If stdin is not available then %NULL will be returned. In the future, support may be expanded to other platforms. You must only call this function once per commandline invocation. a #GInputStream for stdin a #GApplicationCommandLine Gets the value of a particular environment variable of the command line invocation, as would be returned by g_getenv(). The strings may contain non-utf8 data. The remote application usually does not send an environment. Use %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag set it is possible that the environment is still not available (due to invocation messages from other applications). The return value should not be modified or freed and is valid for as long as @cmdline exists. the value of the variable, or %NULL if unset or unsent a #GApplicationCommandLine the environment variable to get Formats a message and prints it using the stdout print handler in the invoking process. If @cmdline is a local invocation then this is exactly equivalent to g_print(). If @cmdline is remote then this is equivalent to calling g_print() in the invoking process. a #GApplicationCommandLine a printf-style format string arguments, as per @format Prints a message using the stdout print handler in the invoking process. Unlike g_application_command_line_print(), @message is not a `printf()`-style format string. Use this function if @message contains text you don't have control over, that could include `printf()` escape sequences. a #GApplicationCommandLine the message Formats a message and prints it using the stderr print handler in the invoking process. If @cmdline is a local invocation then this is exactly equivalent to g_printerr(). If @cmdline is remote then this is equivalent to calling g_printerr() in the invoking process. a #GApplicationCommandLine a printf-style format string arguments, as per @format Prints a message using the stderr print handler in the invoking process. Unlike g_application_command_line_printerr(), @message is not a `printf()`-style format string. Use this function if @message contains text you don't have control over, that could include `printf()` escape sequences. a #GApplicationCommandLine the message Sets the exit status that will be used when the invoking process exits. The return value of the #GApplication::command-line signal is passed to this function when the handler returns. This is the usual way of setting the exit status. In the event that you want the remote invocation to continue running and want to decide on the exit status in the future, you can use this call. For the case of a remote invocation, the remote process will typically exit when the last reference is dropped on @cmdline. The exit status of the remote process will be equal to the last value that was set with this function. In the case that the commandline invocation is local, the situation is slightly more complicated. If the commandline invocation results in the mainloop running (ie: because the use-count of the application increased to a non-zero value) then the application is considered to have been 'successful' in a certain sense, and the exit status is always zero. If the application use count is zero, though, the exit status of the local #GApplicationCommandLine is used. This method is a no-op if g_application_command_line_done() has been called. a #GApplicationCommandLine the exit status The commandline that caused this [signal@Gio.Application::command-line] signal emission. Whether this is a remote commandline. The options sent along with the commandline. Platform-specific data for the commandline. The #GApplicationCommandLineClass-struct contains private data only. a #GApplicationCommandLine the message a #GApplicationCommandLine the message a #GInputStream for stdin a #GApplicationCommandLine a #GApplicationCommandLine Flags used to define the behaviour of a #GApplication. Default flags. Use [flags@Gio.ApplicationFlags.DEFAULT_FLAGS]. Default flags. Run as a service. In this mode, registration fails if the service is already running, and the application will initially wait up to 10 seconds for an initial activation message to arrive. Don't try to become the primary instance. This application handles opening files (in the primary instance). Note that this flag only affects the default implementation of local_command_line(), and has no effect if %G_APPLICATION_HANDLES_COMMAND_LINE is given. See g_application_run() for details. This application handles command line arguments (in the primary instance). Note that this flag only affect the default implementation of local_command_line(). See g_application_run() for details. Send the environment of the launching process to the primary instance. Set this flag if your application is expected to behave differently depending on certain environment variables. For instance, an editor might be expected to use the `GIT_COMMITTER_NAME` environment variable when editing a git commit message. The environment is available to the #GApplication::command-line signal handler, via g_application_command_line_getenv(). Make no attempts to do any of the typical single-instance application negotiation, even if the application ID is given. The application neither attempts to become the owner of the application ID nor does it check if an existing owner already exists. Everything occurs in the local process. Since: 2.30. Allow users to override the application ID from the command line with `--gapplication-app-id`. Since: 2.48 Allow another instance to take over the bus name. Since: 2.60 Take over from another instance. This flag is usually set by passing `--gapplication-replace` on the commandline. Since: 2.60 #GAskPasswordFlags are used to request specific information from the user, or to notify the user of their choices in an authentication situation. operation requires a password. operation requires a username. operation requires a domain. operation supports saving settings. operation supports anonymous users. operation takes TCRYPT parameters (Since: 2.58) `GAsyncInitable` is an interface for asynchronously initializable objects. This is the asynchronous version of [iface@Gio.Initable]; it behaves the same in all ways except that initialization is asynchronous. For more details see the descriptions on `GInitable`. A class may implement both the `GInitable` and `GAsyncInitable` interfaces. Users of objects implementing this are not intended to use the interface method directly; instead it will be used automatically in various ways. For C applications you generally just call [func@Gio.AsyncInitable.new_async] directly, or indirectly via a foo_thing_new_async() wrapper. This will call [method@Gio.AsyncInitable.init_async] under the covers, calling back with `NULL` and a set `GError` on failure. A typical implementation might look something like this: ```c enum { NOT_INITIALIZED, INITIALIZING, INITIALIZED }; static void _foo_ready_cb (Foo *self) { GList *l; self->priv->state = INITIALIZED; for (l = self->priv->init_results; l != NULL; l = l->next) { GTask *task = l->data; if (self->priv->success) g_task_return_boolean (task, TRUE); else g_task_return_new_error (task, ...); g_object_unref (task); } g_list_free (self->priv->init_results); self->priv->init_results = NULL; } static void foo_init_async (GAsyncInitable *initable, int io_priority, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { Foo *self = FOO (initable); GTask *task; task = g_task_new (initable, cancellable, callback, user_data); g_task_set_name (task, G_STRFUNC); switch (self->priv->state) { case NOT_INITIALIZED: _foo_get_ready (self); self->priv->init_results = g_list_append (self->priv->init_results, task); self->priv->state = INITIALIZING; break; case INITIALIZING: self->priv->init_results = g_list_append (self->priv->init_results, task); break; case INITIALIZED: if (!self->priv->success) g_task_return_new_error (task, ...); else g_task_return_boolean (task, TRUE); g_object_unref (task); break; } } static gboolean foo_init_finish (GAsyncInitable *initable, GAsyncResult *result, GError **error) { g_return_val_if_fail (g_task_is_valid (result, initable), FALSE); return g_task_propagate_boolean (G_TASK (result), error); } static void foo_async_initable_iface_init (gpointer g_iface, gpointer data) { GAsyncInitableIface *iface = g_iface; iface->init_async = foo_init_async; iface->init_finish = foo_init_finish; } ``` Helper function for constructing #GAsyncInitable object. This is similar to g_object_new() but also initializes the object asynchronously. When the initialization is finished, @callback will be called. You can then call g_async_initable_new_finish() to get the new object and check for any errors. a #GType supporting #GAsyncInitable. the [I/O priority](iface.AsyncResult.html#io-priority) of the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the initialization is finished the data to pass to callback function the name of the first property, or %NULL if no properties the value of the first property, followed by other property value pairs, and ended by %NULL. Helper function for constructing #GAsyncInitable object. This is similar to g_object_new_valist() but also initializes the object asynchronously. When the initialization is finished, @callback will be called. You can then call g_async_initable_new_finish() to get the new object and check for any errors. a #GType supporting #GAsyncInitable. the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. The var args list generated from @first_property_name. the [I/O priority](iface.AsyncResult.html#io-priority) of the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the initialization is finished the data to pass to callback function Helper function for constructing #GAsyncInitable object. This is similar to g_object_newv() but also initializes the object asynchronously. When the initialization is finished, @callback will be called. You can then call g_async_initable_new_finish() to get the new object and check for any errors. Use g_object_new_with_properties() and g_async_initable_init_async() instead. See #GParameter for more information. a #GType supporting #GAsyncInitable. the number of parameters in @parameters the parameters to use to construct the object the [I/O priority](iface.AsyncResult.html#io-priority) of the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the initialization is finished the data to pass to callback function Starts asynchronous initialization of the object implementing the interface. This must be done before any real use of the object after initial construction. If the object also implements #GInitable you can optionally call g_initable_init() instead. This method is intended for language bindings. If writing in C, g_async_initable_new_async() should typically be used instead. When the initialization is finished, @callback will be called. You can then call g_async_initable_init_finish() to get the result of the initialization. Implementations may also support cancellation. If @cancellable is not %NULL, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and the object doesn't support cancellable initialization, the error %G_IO_ERROR_NOT_SUPPORTED will be returned. As with #GInitable, if the object is not initialized, or initialization returns with an error, then all operations on the object except g_object_ref() and g_object_unref() are considered to be invalid, and have undefined behaviour. They will often fail with g_critical() or g_warning(), but this must not be relied on. Callers should not assume that a class which implements #GAsyncInitable can be initialized multiple times; for more information, see g_initable_init(). If a class explicitly supports being initialized multiple times, implementation requires yielding all subsequent calls to init_async() on the results of the first call. For classes that also support the #GInitable interface, the default implementation of this method will run the g_initable_init() function in a thread, so if you want to support asynchronous initialization via threads, just implement the #GAsyncInitable interface without overriding any interface methods. a #GAsyncInitable. the [I/O priority](iface.AsyncResult.html#io-priority) of the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes asynchronous initialization and returns the result. See g_async_initable_init_async(). %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GAsyncInitable. a #GAsyncResult. Starts asynchronous initialization of the object implementing the interface. This must be done before any real use of the object after initial construction. If the object also implements #GInitable you can optionally call g_initable_init() instead. This method is intended for language bindings. If writing in C, g_async_initable_new_async() should typically be used instead. When the initialization is finished, @callback will be called. You can then call g_async_initable_init_finish() to get the result of the initialization. Implementations may also support cancellation. If @cancellable is not %NULL, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and the object doesn't support cancellable initialization, the error %G_IO_ERROR_NOT_SUPPORTED will be returned. As with #GInitable, if the object is not initialized, or initialization returns with an error, then all operations on the object except g_object_ref() and g_object_unref() are considered to be invalid, and have undefined behaviour. They will often fail with g_critical() or g_warning(), but this must not be relied on. Callers should not assume that a class which implements #GAsyncInitable can be initialized multiple times; for more information, see g_initable_init(). If a class explicitly supports being initialized multiple times, implementation requires yielding all subsequent calls to init_async() on the results of the first call. For classes that also support the #GInitable interface, the default implementation of this method will run the g_initable_init() function in a thread, so if you want to support asynchronous initialization via threads, just implement the #GAsyncInitable interface without overriding any interface methods. a #GAsyncInitable. the [I/O priority](iface.AsyncResult.html#io-priority) of the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes asynchronous initialization and returns the result. See g_async_initable_init_async(). %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GAsyncInitable. a #GAsyncResult. Finishes the async construction for the various g_async_initable_new calls, returning the created object or %NULL on error. a newly created #GObject, or %NULL on error. Free with g_object_unref(). the #GAsyncInitable from the callback the #GAsyncResult from the callback Provides an interface for asynchronous initializing object such that initialization may fail. The parent interface. Starts initialization of the object. a #GAsyncInitable. the [I/O priority](iface.AsyncResult.html#io-priority) of the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes initialization of the object. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GAsyncInitable. a #GAsyncResult. Type definition for a function that will be called back when an asynchronous operation within GIO has been completed. #GAsyncReadyCallback callbacks from #GTask are guaranteed to be invoked in a later iteration of the thread-default main context (see [method@GLib.MainContext.push_thread_default]) where the #GTask was created. All other users of #GAsyncReadyCallback must likewise call it asynchronously in a later iteration of the main context. The asynchronous operation is guaranteed to have held a reference to @source_object from the time when the `*_async()` function was called, until after this callback returns. the object the asynchronous operation was started with. a #GAsyncResult. user data passed to the callback. `GAsyncResult` provides a base class for implementing asynchronous function results. Asynchronous operations are broken up into two separate operations which are chained together by a `GAsyncReadyCallback`. To begin an asynchronous operation, provide a `GAsyncReadyCallback` to the asynchronous function. This callback will be triggered when the operation has completed, and must be run in a later iteration of the thread-default main context (see [method@GLib.MainContext.push_thread_default]) from where the operation was initiated. It will be passed a `GAsyncResult` instance filled with the details of the operation's success or failure, the object the asynchronous function was started for and any error codes returned. The asynchronous callback function is then expected to call the corresponding `_finish()` function, passing the object the function was called for, the `GAsyncResult` instance, and (optionally) an @error to grab any error conditions that may have occurred. The `_finish()` function for an operation takes the generic result (of type `GAsyncResult`) and returns the specific result that the operation in question yields (e.g. a [class@Gio.FileEnumerator] for a "enumerate children" operation). If the result or error status of the operation is not needed, there is no need to call the `_finish()` function; GIO will take care of cleaning up the result and error information after the `GAsyncReadyCallback` returns. You can pass `NULL` for the `GAsyncReadyCallback` if you don't need to take any action at all after the operation completes. Applications may also take a reference to the `GAsyncResult` and call `_finish()` later; however, the `_finish()` function may be called at most once. Example of a typical asynchronous operation flow: ```c void _theoretical_frobnitz_async (Theoretical *t, GCancellable *c, GAsyncReadyCallback cb, gpointer u); gboolean _theoretical_frobnitz_finish (Theoretical *t, GAsyncResult *res, GError **e); static void frobnitz_result_func (GObject *source_object, GAsyncResult *res, gpointer user_data) { gboolean success = FALSE; success = _theoretical_frobnitz_finish (source_object, res, NULL); if (success) g_printf ("Hurray!\n"); else g_printf ("Uh oh!\n"); ... } int main (int argc, void *argv[]) { ... _theoretical_frobnitz_async (theoretical_data, NULL, frobnitz_result_func, NULL); ... } ``` The callback for an asynchronous operation is called only once, and is always called, even in the case of a cancelled operation. On cancellation the result is a `G_IO_ERROR_CANCELLED` error. ## I/O Priority Many I/O-related asynchronous operations have a priority parameter, which is used in certain cases to determine the order in which operations are executed. They are not used to determine system-wide I/O scheduling. Priorities are integers, with lower numbers indicating higher priority. It is recommended to choose priorities between `G_PRIORITY_LOW` and `G_PRIORITY_HIGH`, with `G_PRIORITY_DEFAULT` as a default. Gets the source object from a [iface@Gio.AsyncResult]. a new reference to the source object for the @res, or `NULL` if there is none. a [iface@Gio.AsyncResult] Gets the user data from a [iface@Gio.AsyncResult]. the user data for @res. a [iface@Gio.AsyncResult]. Checks if @res has the given @source_tag (generally a function pointer indicating the function @res was created by). `TRUE` if @res has the indicated @source_tag, `FALSE` if not. a [iface@Gio.AsyncResult] an application-defined tag Gets the source object from a [iface@Gio.AsyncResult]. a new reference to the source object for the @res, or `NULL` if there is none. a [iface@Gio.AsyncResult] Gets the user data from a [iface@Gio.AsyncResult]. the user data for @res. a [iface@Gio.AsyncResult]. Checks if @res has the given @source_tag (generally a function pointer indicating the function @res was created by). `TRUE` if @res has the indicated @source_tag, `FALSE` if not. a [iface@Gio.AsyncResult] an application-defined tag If @res is a [class@Gio.SimpleAsyncResult], this is equivalent to [method@Gio.SimpleAsyncResult.propagate_error]. Otherwise it returns `FALSE`. This can be used for legacy error handling in async `*_finish()` wrapper functions that traditionally handled [class@Gio.SimpleAsyncResult] error returns themselves rather than calling into the virtual method. This should not be used in new code; [iface@Gio.AsyncResult] errors that are set by virtual methods should also be extracted by virtual methods, to enable subclasses to chain up correctly. `TRUE` if @error is has been filled in with an error from @res, `FALSE` if not. a [iface@Gio.AsyncResult] Interface definition for [iface@Gio.AsyncResult]. The parent interface. Gets the user data passed to the callback. the user data for @res. a [iface@Gio.AsyncResult]. Gets the source object that issued the asynchronous operation. a new reference to the source object for the @res, or `NULL` if there is none. a [iface@Gio.AsyncResult] Checks if a result is tagged with a particular source. `TRUE` if @res has the indicated @source_tag, `FALSE` if not. a [iface@Gio.AsyncResult] an application-defined tag Buffered input stream implements [class@Gio.FilterInputStream] and provides for buffered reads. By default, `GBufferedInputStream`'s buffer size is set at 4 kilobytes. To create a buffered input stream, use [ctor@Gio.BufferedInputStream.new], or [ctor@Gio.BufferedInputStream.new_sized] to specify the buffer's size at construction. To get the size of a buffer within a buffered input stream, use [method@Gio.BufferedInputStream.get_buffer_size]. To change the size of a buffered input stream's buffer, use [method@Gio.BufferedInputStream.set_buffer_size]. Note that the buffer's size cannot be reduced below the size of the data within the buffer. Creates a new [class@Gio.InputStream] from the given @base_stream, with a buffer set to the default size (4 kilobytes). a [class@Gio.InputStream] for the given @base_stream. a [class@Gio.InputStream] Creates a new [class@Gio.BufferedInputStream] from the given @base_stream, with a buffer set to @size. a [class@Gio.InputStream]. a [class@Gio.InputStream] a #gsize Tries to read @count bytes from the stream into the buffer. Will block during this read. If @count is zero, returns zero and does nothing. A value of @count larger than `G_MAXSSIZE` will cause a [error@Gio.IOErrorEnum.INVALID_ARGUMENT] error. On success, the number of bytes read into the buffer is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file. Zero is returned on end of file (or if @count is zero), but never otherwise. If @count is -1 then the attempted read size is equal to the number of bytes that are required to fill the buffer. If @cancellable is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error [error@Gio.IOErrorEnum.CANCELLED] will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error `-1` is returned and @error is set accordingly. For the asynchronous, non-blocking, version of this function, see [method@Gio.BufferedInputStream.fill_async]. the number of bytes read into @stream's buffer, up to @count, or `-1` on error. a [class@Gio.BufferedInputStream] the number of bytes that will be read from the stream optional [class@Gio.Cancellable] object, `NULL` to ignore Reads data into @stream's buffer asynchronously, up to @count size. @io_priority can be used to prioritize reads. For the synchronous version of this function, see [method@Gio.BufferedInputStream.fill]. If @count is `-1` then the attempted read size is equal to the number of bytes that are required to fill the buffer. a [class@Gio.BufferedInputStream] the number of bytes that will be read from the stream the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional [class@Gio.Cancellable] object a [callback@Gio.AsyncReadyCallback] a #gpointer Finishes an asynchronous read. a #gssize of the read stream, or `-1` on an error. a [class@Gio.BufferedInputStream] a [iface@Gio.AsyncResult] Tries to read @count bytes from the stream into the buffer. Will block during this read. If @count is zero, returns zero and does nothing. A value of @count larger than `G_MAXSSIZE` will cause a [error@Gio.IOErrorEnum.INVALID_ARGUMENT] error. On success, the number of bytes read into the buffer is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file. Zero is returned on end of file (or if @count is zero), but never otherwise. If @count is -1 then the attempted read size is equal to the number of bytes that are required to fill the buffer. If @cancellable is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error [error@Gio.IOErrorEnum.CANCELLED] will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error `-1` is returned and @error is set accordingly. For the asynchronous, non-blocking, version of this function, see [method@Gio.BufferedInputStream.fill_async]. the number of bytes read into @stream's buffer, up to @count, or `-1` on error. a [class@Gio.BufferedInputStream] the number of bytes that will be read from the stream optional [class@Gio.Cancellable] object, `NULL` to ignore Reads data into @stream's buffer asynchronously, up to @count size. @io_priority can be used to prioritize reads. For the synchronous version of this function, see [method@Gio.BufferedInputStream.fill]. If @count is `-1` then the attempted read size is equal to the number of bytes that are required to fill the buffer. a [class@Gio.BufferedInputStream] the number of bytes that will be read from the stream the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional [class@Gio.Cancellable] object a [callback@Gio.AsyncReadyCallback] a #gpointer Finishes an asynchronous read. a #gssize of the read stream, or `-1` on an error. a [class@Gio.BufferedInputStream] a [iface@Gio.AsyncResult] Gets the size of the available data within the stream. size of the available stream. [class@Gio.BufferedInputStream] Gets the size of the input buffer. the current buffer size. a [class@Gio.BufferedInputStream] Peeks in the buffered input, copying @count bytes of data from @offset bytes in the buffered input into @buffer. the number of bytes copied, which may be zero a [class@Gio.BufferedInputStream] a pointer to an allocated chunk of memory, which must be at least @count bytes long offset into the buffered input to peek from, or zero to peek from the next byte in the buffered input onwards number of bytes to peek Returns the buffer with the currently available bytes. The returned buffer must not be modified and will become invalid when reading from the stream or filling the buffer. read-only buffer a [class@Gio.BufferedInputStream] a #gsize to get the number of bytes available in the buffer Tries to read a single byte from the stream or the buffer. Will block during this read. On success, the byte read from the stream is returned. On end of stream `-1` is returned but it's not an exceptional error and @error is not set. If @cancellable is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error [error@Gio.IOErrorEnum.CANCELLED] will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error `-1` is returned and @error is set accordingly. the byte read from the @stream, or `-1` on end of stream or error. a [class@Gio.BufferedInputStream] optional [class@Gio.Cancellable] object, `NULL` to ignore Sets the size of the internal buffer of @stream to @size, or to the size of the contents of the buffer. The buffer can never be resized smaller than its current contents. a [class@Gio.BufferedInputStream] a #gsize The size of the backend buffer, in bytes. the number of bytes read into @stream's buffer, up to @count, or `-1` on error. a [class@Gio.BufferedInputStream] the number of bytes that will be read from the stream optional [class@Gio.Cancellable] object, `NULL` to ignore a [class@Gio.BufferedInputStream] the number of bytes that will be read from the stream the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional [class@Gio.Cancellable] object a [callback@Gio.AsyncReadyCallback] a #gpointer a #gssize of the read stream, or `-1` on an error. a [class@Gio.BufferedInputStream] a [iface@Gio.AsyncResult] Buffered output stream implements [class@Gio.FilterOutputStream] and provides for buffered writes. By default, `GBufferedOutputStream`'s buffer size is set at 4 kilobytes. To create a buffered output stream, use [ctor@Gio.BufferedOutputStream.new], or [ctor@Gio.BufferedOutputStream.new_sized] to specify the buffer's size at construction. To get the size of a buffer within a buffered input stream, use [method@Gio.BufferedOutputStream.get_buffer_size]. To change the size of a buffered output stream's buffer, use [method@Gio.BufferedOutputStream.set_buffer_size]. Note that the buffer's size cannot be reduced below the size of the data within the buffer. Creates a new buffered output stream for a base stream. a [class@Gio.OutputStream] for the given @base_stream. a [class@Gio.OutputStream]. Creates a new buffered output stream with a given buffer size. a [class@Gio.OutputStream] with an internal buffer set to @size. a [class@Gio.OutputStream]. a #gsize. Checks if the buffer automatically grows as data is added. `TRUE` if the @stream's buffer automatically grows, `FALSE` otherwise. a [class@Gio.BufferedOutputStream]. Gets the size of the buffer in the @stream. the current size of the buffer. a [class@Gio.BufferedOutputStream]. Sets whether or not the @stream's buffer should automatically grow. If @auto_grow is true, then each write will just make the buffer larger, and you must manually flush the buffer to actually write out the data to the underlying stream. a [class@Gio.BufferedOutputStream]. a #gboolean. Sets the size of the internal buffer to @size. a [class@Gio.BufferedOutputStream]. a #gsize. Whether the buffer should automatically grow. The size of the backend buffer, in bytes. Invoked when a connection to a message bus has been obtained. the connection to a message bus the name that is requested to be owned user data passed to [func@Gio.bus_own_name] Invoked when the name is acquired. the connection on which to acquired the name the name being owned user data passed to [func@Gio.bus_own_name] or [func@Gio.bus_own_name_on_connection] Invoked when the name being watched is known to have to have an owner. The #GDBusConnection the name is being watched on. The name being watched. Unique name of the owner of the name being watched. User data passed to g_bus_watch_name(). Invoked when the name is lost or @connection has been closed. the connect on which to acquire the name or `NULL` if the connection was disconnected the name being owned user data passed to [func@Gio.bus_own_name] or [func@Gio.bus_own_name_on_connection] Flags used in g_bus_own_name(). No flags set. Allow another message bus connection to claim the name. If another message bus connection owns the name and have specified %G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT, then take the name from the other connection. If another message bus connection owns the name, immediately return an error from [func@Gio.bus_own_name] rather than entering the waiting queue for that name. Invoked when the name being watched is known not to have to have an owner. This is also invoked when the #GDBusConnection on which the watch was established has been closed. In that case, @connection will be %NULL. The #GDBusConnection the name is being watched on, or %NULL. The name being watched. User data passed to g_bus_watch_name(). Flags used in g_bus_watch_name(). No flags set. If no-one owns the name when beginning to watch the name, ask the bus to launch an owner for the name. An enumeration for well-known message buses. An alias for the message bus that activated the process, if any. Not a message bus. The system-wide message bus. The login session message bus. `GBytesIcon` specifies an image held in memory in a common format (usually PNG) to be used as icon. Creates a new icon for a bytes. This cannot fail, but loading and interpreting the bytes may fail later on (for example, if g_loadable_icon_load() is called) if the image is invalid. a #GIcon for the given @bytes. a #GBytes. Gets the #GBytes associated with the given @icon. a #GBytes. a #GIcon. The bytes containing the icon. `GCancellable` allows operations to be cancelled. `GCancellable` is a thread-safe operation cancellation stack used throughout GIO to allow for cancellation of synchronous and asynchronous operations. Creates a new #GCancellable object. Applications that want to start one or more operations that should be cancellable should create a #GCancellable and pass it to the operations. One #GCancellable can be used in multiple consecutive operations or in multiple concurrent operations. a #GCancellable. Gets the top cancellable from the stack. a #GCancellable from the top of the stack, or %NULL if the stack is empty. Will set @cancellable to cancelled, and will emit the #GCancellable::cancelled signal. (However, see the warning about race conditions in the documentation for that signal if you are planning to connect to it.) This function is thread-safe. In other words, you can safely call it from a thread other than the one running the operation that was passed the @cancellable. If @cancellable is %NULL, this function returns immediately for convenience. The convention within GIO is that cancelling an asynchronous operation causes it to complete asynchronously. That is, if you cancel the operation from the same thread in which it is running, then the operation's #GAsyncReadyCallback will not be invoked until the application returns to the main loop. It is safe (although useless, since it will be a no-op) to call this function from a [signal@Gio.Cancellable::cancelled] signal handler. a #GCancellable object. Convenience function to connect to the #GCancellable::cancelled signal. Also handles the race condition that may happen if the cancellable is cancelled right before connecting. @callback is called exactly once each time @cancellable is cancelled, either directly at the time of the connect if @cancellable is already cancelled, or when @cancellable is cancelled in some thread. In case the cancellable is reset via [method@Gio.Cancellable.reset] then the callback can be called again if the @cancellable is cancelled and if it had not been previously cancelled at the time [method@Gio.Cancellable.connect] was called (e.g. if the connection actually took place, returning a non-zero value). @data_destroy_func will be called when the handler is disconnected, or immediately if the cancellable is already cancelled. See #GCancellable::cancelled for details on how to use this. Since GLib 2.40, the lock protecting @cancellable is not held when @callback is invoked. This lifts a restriction in place for earlier GLib versions which now makes it easier to write cleanup code that unconditionally invokes e.g. [method@Gio.Cancellable.cancel]. Note that since 2.82 GLib still holds a lock during the callback but it’s designed in a way that most of the [class@Gio.Cancellable] methods can be called, including [method@Gio.Cancellable.cancel] or [method@GObject.Object.unref]. There are still some methods that will deadlock (by design) when called from the [signal@Gio.Cancellable::cancelled] callbacks: - [method@Gio.Cancellable.connect] - [method@Gio.Cancellable.disconnect] - [method@Gio.Cancellable.reset] - [method@Gio.Cancellable.make_pollfd] - [method@Gio.Cancellable.release_fd] The id of the signal handler or 0 if @cancellable has already been cancelled. A #GCancellable. The #GCallback to connect. Data to pass to @callback. Free function for @data or %NULL. Disconnects a handler from a cancellable instance similar to g_signal_handler_disconnect(). Additionally, in the event that a signal handler is currently running, this call will block until the handler has finished. Calling this function from a #GCancellable::cancelled signal handler will therefore result in a deadlock. This avoids a race condition where a thread cancels at the same time as the cancellable operation is finished and the signal handler is removed. See #GCancellable::cancelled for details on how to use this. If @cancellable is %NULL or @handler_id is `0` this function does nothing. A #GCancellable or %NULL. Handler id of the handler to be disconnected, or `0`. Gets the file descriptor for a cancellable job. This can be used to implement cancellable operations on Unix systems. The returned fd will turn readable when @cancellable is cancelled. You are not supposed to read from the fd yourself, just check for readable status. Reading to unset the readable status is done with g_cancellable_reset(). After a successful return from this function, you should use g_cancellable_release_fd() to free up resources allocated for the returned file descriptor. See also g_cancellable_make_pollfd(). A valid file descriptor. `-1` if the file descriptor is not supported, or on errors. a #GCancellable. Checks if a cancellable job has been cancelled. %TRUE if @cancellable is cancelled, FALSE if called with %NULL or if item is not cancelled. a #GCancellable or %NULL Creates a #GPollFD corresponding to @cancellable; this can be passed to g_poll() and used to poll for cancellation. This is useful both for unix systems without a native poll and for portability to windows. When this function returns %TRUE, you should use g_cancellable_release_fd() to free up resources allocated for the @pollfd. After a %FALSE return, do not call g_cancellable_release_fd(). If this function returns %FALSE, either no @cancellable was given or resource limits prevent this function from allocating the necessary structures for polling. (On Linux, you will likely have reached the maximum number of file descriptors.) The suggested way to handle these cases is to ignore the @cancellable. You are not supposed to read from the fd yourself, just check for readable status. Reading to unset the readable status is done with g_cancellable_reset(). Note that in the event that a [signal@Gio.Cancellable::cancelled] signal handler is currently running, this call will block until the handler has finished. Calling this function from a signal handler will therefore result in a deadlock. %TRUE if @pollfd was successfully initialized, %FALSE on failure to prepare the cancellable. a #GCancellable or %NULL a pointer to a #GPollFD Pops @cancellable off the cancellable stack (verifying that @cancellable is on the top of the stack). a #GCancellable object Pushes @cancellable onto the cancellable stack. The current cancellable can then be received using g_cancellable_get_current(). This is useful when implementing cancellable operations in code that does not allow you to pass down the cancellable object. This is typically called automatically by e.g. #GFile operations, so you rarely have to call this yourself. a #GCancellable object Releases a resources previously allocated by g_cancellable_get_fd() or g_cancellable_make_pollfd(). For compatibility reasons with older releases, calling this function is not strictly required, the resources will be automatically freed when the @cancellable is finalized. However, the @cancellable will block scarce file descriptors until it is finalized if this function is not called. This can cause the application to run out of file descriptors when many #GCancellables are used at the same time. Note that in the event that a [signal@Gio.Cancellable::cancelled] signal handler is currently running, this call will block until the handler has finished. Calling this function from a signal handler will therefore result in a deadlock. a #GCancellable Resets @cancellable to its uncancelled state. If cancellable is currently in use by any cancellable operation then the behavior of this function is undefined. Note that it is generally not a good idea to reuse an existing cancellable for more operations after it has been cancelled once, as this function might tempt you to do. The recommended practice is to drop the reference to a cancellable after cancelling it, and let it die with the outstanding async operations. You should create a fresh cancellable for further async operations. In the event that a [signal@Gio.Cancellable::cancelled] signal handler is currently running, this call will block until the handler has finished. Calling this function from a signal handler will therefore result in a deadlock. a #GCancellable object. If the @cancellable is cancelled, sets the error to notify that the operation was cancelled. %TRUE if @cancellable was cancelled, %FALSE if it was not a #GCancellable or %NULL Creates a source that triggers if @cancellable is cancelled and calls its callback of type #GCancellableSourceFunc. This is primarily useful for attaching to another (non-cancellable) source with g_source_add_child_source() to add cancellability to it. For convenience, you can call this with a %NULL #GCancellable, in which case the source will never trigger. The new #GSource will hold a reference to the #GCancellable. the new #GSource. a #GCancellable, or %NULL Emitted when the operation has been cancelled. Can be used by implementations of cancellable operations. If the operation is cancelled from another thread, the signal will be emitted in the thread that cancelled the operation, not the thread that is running the operation. Note that disconnecting from this signal (or any signal) in a multi-threaded program is prone to race conditions. For instance it is possible that a signal handler may be invoked even after a call to g_signal_handler_disconnect() for that handler has already returned. There is also a problem when cancellation happens right before connecting to the signal. If this happens the signal will unexpectedly not be emitted, and checking before connecting to the signal leaves a race condition where this is still happening. In order to make it safe and easy to connect handlers there are two helper functions: g_cancellable_connect() and g_cancellable_disconnect() which protect against problems like this. An example of how to us this: |[<!-- language="C" --> // Make sure we don't do unnecessary work if already cancelled if (g_cancellable_set_error_if_cancelled (cancellable, error)) return; // Set up all the data needed to be able to handle cancellation // of the operation my_data = my_data_new (...); id = 0; if (cancellable) id = g_cancellable_connect (cancellable, G_CALLBACK (cancelled_handler) data, NULL); // cancellable operation here... g_cancellable_disconnect (cancellable, id); // cancelled_handler is never called after this, it is now safe // to free the data my_data_free (my_data); ]| Note that the cancelled signal is emitted in the thread that the user cancelled from, which may be the main thread. So, the cancellable signal should not do something that can block. This is the function type of the callback used for the #GSource returned by g_cancellable_source_new(). it should return %FALSE if the source should be removed. the #GCancellable data passed in by the user. `GCharsetConverter` is an implementation of [iface@Gio.Converter] based on [struct@GLib.IConv]. Creates a new #GCharsetConverter. a new #GCharsetConverter or %NULL on error. destination charset source charset Gets the number of fallbacks that @converter has applied so far. the number of fallbacks that @converter has applied a #GCharsetConverter Gets the #GCharsetConverter:use-fallback property. %TRUE if fallbacks are used by @converter a #GCharsetConverter Sets the #GCharsetConverter:use-fallback property. a #GCharsetConverter %TRUE to use fallbacks The character encoding to convert from. The character encoding to convert to. Use fallback (of form `\<hexval>`) for invalid bytes. `GConverter` is an interface for streaming conversions. `GConverter` is implemented by objects that convert binary data in various ways. The conversion can be stateful and may fail at any place. Some example conversions are: character set conversion, compression, decompression and regular expression replace. This is the main operation used when converting data. It is to be called multiple times in a loop, and each time it will do some work, i.e. producing some output (in @outbuf) or consuming some input (from @inbuf) or both. If its not possible to do any work an error is returned. Note that a single call may not consume all input (or any input at all). Also a call may produce output even if given no input, due to state stored in the converter producing output. If any data was either produced or consumed, and then an error happens, then only the successful conversion is reported and the error is returned on the next call. A full conversion loop involves calling this method repeatedly, each time giving it new input and space output space. When there is no more input data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set. The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED each time until all data is consumed and all output is produced, then %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance in a decompression converter where the end of data is detectable from the data (and there might even be other data after the end of the compressed data). When some data has successfully been converted @bytes_read and is set to the number of bytes read from @inbuf, and @bytes_written is set to indicate how many bytes was written to @outbuf. If there are more data to output or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then %G_CONVERTER_CONVERTED is returned, and if no more data is to be output then %G_CONVERTER_FINISHED is returned. On error %G_CONVERTER_ERROR is returned and @error is set accordingly. Some errors need special handling: %G_IO_ERROR_NO_SPACE is returned if there is not enough space to write the resulting converted data, the application should call the function again with a larger @outbuf to continue. %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough input to fully determine what the conversion should produce, and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for example with an incomplete multibyte sequence when converting text, or when a regexp matches up to the end of the input (and may match further input). It may also happen when @inbuf_size is zero and there is no more data to produce. When this happens the application should read more input and then call the function again. If further input shows that there is no more data call the function again with the same data but with the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion to finish as e.g. in the regexp match case (or, to fail again with %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the input is actually partial). After g_converter_convert() has returned %G_CONVERTER_FINISHED the converter object is in an invalid state where its not allowed to call g_converter_convert() anymore. At this time you can only free the object or call g_converter_reset() to reset it to the initial state. If the flag %G_CONVERTER_FLUSH is set then conversion is modified to try to write out all internal state to the output. The application has to call the function multiple times with the flag set, and when the available input has been consumed and all internal state has been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if really at the end) is returned instead of %G_CONVERTER_CONVERTED. This is somewhat similar to what happens at the end of the input stream, but done in the middle of the data. This has different meanings for different conversions. For instance in a compression converter it would mean that we flush all the compression state into output such that if you uncompress the compressed data you get back all the input data. Doing this may make the final file larger due to padding though. Another example is a regexp conversion, where if you at the end of the flushed data have a match, but there is also a potential longer match. In the non-flushed case we would ask for more input, but when flushing we treat this as the end of input and do the match. Flushing is not always possible (like if a charset converter flushes at a partial multibyte sequence). Converters are supposed to try to produce as much output as possible and then return an error (typically %G_IO_ERROR_PARTIAL_INPUT). a #GConverterResult, %G_CONVERTER_ERROR on error. a #GConverter. the buffer containing the data to convert. the number of bytes in @inbuf a buffer to write converted data in. the number of bytes in @outbuf, must be at least one a #GConverterFlags controlling the conversion details will be set to the number of bytes read from @inbuf on success will be set to the number of bytes written to @outbuf on success Resets all internal state in the converter, making it behave as if it was just created. If the converter has any internal state that would produce output then that output is lost. a #GConverter. This is the main operation used when converting data. It is to be called multiple times in a loop, and each time it will do some work, i.e. producing some output (in @outbuf) or consuming some input (from @inbuf) or both. If its not possible to do any work an error is returned. Note that a single call may not consume all input (or any input at all). Also a call may produce output even if given no input, due to state stored in the converter producing output. If any data was either produced or consumed, and then an error happens, then only the successful conversion is reported and the error is returned on the next call. A full conversion loop involves calling this method repeatedly, each time giving it new input and space output space. When there is no more input data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set. The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED each time until all data is consumed and all output is produced, then %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance in a decompression converter where the end of data is detectable from the data (and there might even be other data after the end of the compressed data). When some data has successfully been converted @bytes_read and is set to the number of bytes read from @inbuf, and @bytes_written is set to indicate how many bytes was written to @outbuf. If there are more data to output or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then %G_CONVERTER_CONVERTED is returned, and if no more data is to be output then %G_CONVERTER_FINISHED is returned. On error %G_CONVERTER_ERROR is returned and @error is set accordingly. Some errors need special handling: %G_IO_ERROR_NO_SPACE is returned if there is not enough space to write the resulting converted data, the application should call the function again with a larger @outbuf to continue. %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough input to fully determine what the conversion should produce, and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for example with an incomplete multibyte sequence when converting text, or when a regexp matches up to the end of the input (and may match further input). It may also happen when @inbuf_size is zero and there is no more data to produce. When this happens the application should read more input and then call the function again. If further input shows that there is no more data call the function again with the same data but with the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion to finish as e.g. in the regexp match case (or, to fail again with %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the input is actually partial). After g_converter_convert() has returned %G_CONVERTER_FINISHED the converter object is in an invalid state where its not allowed to call g_converter_convert() anymore. At this time you can only free the object or call g_converter_reset() to reset it to the initial state. If the flag %G_CONVERTER_FLUSH is set then conversion is modified to try to write out all internal state to the output. The application has to call the function multiple times with the flag set, and when the available input has been consumed and all internal state has been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if really at the end) is returned instead of %G_CONVERTER_CONVERTED. This is somewhat similar to what happens at the end of the input stream, but done in the middle of the data. This has different meanings for different conversions. For instance in a compression converter it would mean that we flush all the compression state into output such that if you uncompress the compressed data you get back all the input data. Doing this may make the final file larger due to padding though. Another example is a regexp conversion, where if you at the end of the flushed data have a match, but there is also a potential longer match. In the non-flushed case we would ask for more input, but when flushing we treat this as the end of input and do the match. Flushing is not always possible (like if a charset converter flushes at a partial multibyte sequence). Converters are supposed to try to produce as much output as possible and then return an error (typically %G_IO_ERROR_PARTIAL_INPUT). a #GConverterResult, %G_CONVERTER_ERROR on error. a #GConverter. the buffer containing the data to convert. the number of bytes in @inbuf a buffer to write converted data in. the number of bytes in @outbuf, must be at least one a #GConverterFlags controlling the conversion details will be set to the number of bytes read from @inbuf on success will be set to the number of bytes written to @outbuf on success Applies @converter to the data in @bytes. A newly-allocated `GBytes` with the converted data, or `NULL` if an error occurred the `GConverter` to use the data to convert Resets all internal state in the converter, making it behave as if it was just created. If the converter has any internal state that would produce output then that output is lost. a #GConverter. Flags used when calling a g_converter_convert(). No flags. At end of input data Flush data Provides an interface for converting data from one type to another type. The conversion can be stateful and may fail at any place. The parent interface. Converts data. a #GConverterResult, %G_CONVERTER_ERROR on error. a #GConverter. the buffer containing the data to convert. the number of bytes in @inbuf a buffer to write converted data in. the number of bytes in @outbuf, must be at least one a #GConverterFlags controlling the conversion details will be set to the number of bytes read from @inbuf on success will be set to the number of bytes written to @outbuf on success Reverts the internal state of the converter to its initial state. a #GConverter. Converter input stream implements [class@Gio.InputStream] and allows conversion of data of various types during reading. As of GLib 2.34, `GConverterInputStream` implements [iface@Gio.PollableInputStream]. Creates a new converter input stream for the @base_stream. a new #GInputStream. a #GInputStream a #GConverter Gets the #GConverter that is used by @converter_stream. the converter of the converter input stream a #GConverterInputStream The converter object. Converter output stream implements [class@Gio.OutputStream] and allows conversion of data of various types during reading. As of GLib 2.34, `GConverterOutputStream` implements [iface@Gio.PollableOutputStream]. Creates a new converter output stream for the @base_stream. a new #GOutputStream. a #GOutputStream a #GConverter Gets the #GConverter that is used by @converter_stream. the converter of the converter output stream a #GConverterOutputStream The converter object. Results returned from g_converter_convert(). There was an error during conversion. Some data was consumed or produced The conversion is finished Flushing is finished The `GCredentials` type is a reference-counted wrapper for native credentials. The information in `GCredentials` is typically used for identifying, authenticating and authorizing other processes. Some operating systems supports looking up the credentials of the remote peer of a communication endpoint - see e.g. [method@Gio.Socket.get_credentials]. Some operating systems supports securely sending and receiving credentials over a Unix Domain Socket, see [class@Gio.UnixCredentialsMessage], [method@Gio.UnixConnection.send_credentials] and [method@Gio.UnixConnection.receive_credentials] for details. On Linux, the native credential type is a `struct ucred` - see the [`unix(7)` man page](man:unix(7)) for details. This corresponds to `G_CREDENTIALS_TYPE_LINUX_UCRED`. On Apple operating systems (including iOS, tvOS, and macOS), the native credential type is a `struct xucred`. This corresponds to `G_CREDENTIALS_TYPE_APPLE_XUCRED`. On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native credential type is a `struct cmsgcred`. This corresponds to `G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED`. On NetBSD, the native credential type is a `struct unpcbid`. This corresponds to `G_CREDENTIALS_TYPE_NETBSD_UNPCBID`. On OpenBSD, the native credential type is a `struct sockpeercred`. This corresponds to `G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED`. On Solaris (including OpenSolaris and its derivatives), the native credential type is a `ucred_t`. This corresponds to `G_CREDENTIALS_TYPE_SOLARIS_UCRED`. Since GLib 2.72, on Windows, the native credentials may contain the PID of a process. This corresponds to `G_CREDENTIALS_TYPE_WIN32_PID`. Creates a new #GCredentials object with credentials matching the the current process. A #GCredentials. Free with g_object_unref(). Gets a pointer to native credentials of type @native_type from @credentials. It is a programming error (which will cause a warning to be logged) to use this method if there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. The pointer to native credentials or %NULL if there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. Do not free the returned data, it is owned by @credentials. A #GCredentials. The type of native credentials to get. Tries to get the UNIX process identifier from @credentials. This method is only available on UNIX platforms. This operation can fail if #GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX process ID. The UNIX process ID, or `-1` if @error is set. A #GCredentials Tries to get the UNIX user identifier from @credentials. This method is only available on UNIX platforms. This operation can fail if #GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX user. As the signedness of `uid_t` is not specified by POSIX, it is recommended to check @error for failure rather than trying to check the return value, particularly in language bindings. The UNIX user identifier or `(uid_t) -1` if @error is set. A #GCredentials Checks if @credentials and @other_credentials is the same user. This operation can fail if #GCredentials is not supported on the the OS. %TRUE if @credentials and @other_credentials has the same user, %FALSE otherwise or if @error is set. A #GCredentials. A #GCredentials. Copies the native credentials of type @native_type from @native into @credentials. It is a programming error (which will cause a warning to be logged) to use this method if there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. A #GCredentials. The type of native credentials to set. A pointer to native credentials. Tries to set the UNIX user identifier on @credentials. This method is only available on UNIX platforms. This operation can fail if #GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX user. It can also fail if the OS does not allow the use of "spoofed" credentials. %TRUE if @uid was set, %FALSE if error is set. A #GCredentials. The UNIX user identifier to set. Creates a human-readable textual representation of @credentials that can be used in logging and debug messages. The format of the returned string may change in future GLib release. A string that should be freed with g_free(). A #GCredentials object. Class structure for #GCredentials. Enumeration describing different kinds of native credential types. Indicates an invalid native credential type. The native credentials type is a `struct ucred`. The native credentials type is a `struct cmsgcred`. The native credentials type is a `struct sockpeercred`. Added in 2.30. The native credentials type is a `ucred_t`. Added in 2.40. The native credentials type is a `struct unpcbid`. Added in 2.42. The native credentials type is a `struct xucred`. Added in 2.66. The native credentials type is a PID `DWORD`. Added in 2.72. The value returned by handlers of the signals generated by the `gdbus-codegen` tool to indicate that a method call has been handled by an implementation. It is equal to %TRUE, but using this macro is sometimes more readable. In code that needs to be backwards-compatible with older GLib, use %TRUE instead, often written like this: |[ g_dbus_method_invocation_return_error (invocation, ...); return TRUE; // handled ]| The value returned by handlers of the signals generated by the `gdbus-codegen` tool to indicate that a method call has not been handled by an implementation. It is equal to %FALSE, but using this macro is sometimes more readable. In code that needs to be backwards-compatible with older GLib, use %FALSE instead. `GDBusActionGroup` is an implementation of the [iface@Gio.ActionGroup] interface. `GDBusActionGroup` can be used as a proxy for an action group that is exported over D-Bus with [method@Gio.DBusConnection.export_action_group]. Obtains a #GDBusActionGroup for the action group which is exported at the given @bus_name and @object_path. The thread default main context is taken at the time of this call. All signals on the menu model (and any linked models) are reported with respect to this context. All calls on the returned menu model (and linked models) must also originate from this same context, with the thread default main context unchanged. This call is non-blocking. The returned action group may or may not already be filled in. The correct thing to do is connect the signals for the action group to monitor for changes and then to call g_action_group_list_actions() to get the initial list. a #GDBusActionGroup A #GDBusConnection the bus name which exports the action group or %NULL if @connection is not a message bus connection the object path at which the action group is exported Information about an annotation. The reference count or -1 if statically allocated. The name of the annotation, e.g. "org.freedesktop.DBus.Deprecated". The value of the annotation. A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. If @info is statically allocated does nothing. Otherwise increases the reference count. The same @info. A #GDBusNodeInfo If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. A #GDBusAnnotationInfo. Looks up the value of an annotation. The cost of this function is O(n) in number of annotations. The value or %NULL if not found. Do not free, it is owned by @annotations. A %NULL-terminated array of annotations or %NULL. The name of the annotation to look up. Information about an argument for a method or a signal. The reference count or -1 if statically allocated. Name of the argument, e.g. @unix_user_id. D-Bus signature of the argument (a single complete type). A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. If @info is statically allocated does nothing. Otherwise increases the reference count. The same @info. A #GDBusArgInfo If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. A #GDBusArgInfo. `GDBusAuthObserver` provides a mechanism for participating in how a [class@Gio.DBusServer] (or a [class@Gio.DBusConnection]) authenticates remote peers. Simply instantiate a `GDBusAuthObserver` and connect to the signals you are interested in. Note that new signals may be added in the future. ## Controlling Authentication Mechanisms By default, a `GDBusServer` or server-side `GDBusConnection` will allow any authentication mechanism to be used. If you only want to allow D-Bus connections with the `EXTERNAL` mechanism, which makes use of credentials passing and is the recommended mechanism for modern Unix platforms such as Linux and the BSD family, you would use a signal handler like this: ```c static gboolean on_allow_mechanism (GDBusAuthObserver *observer, const gchar *mechanism, gpointer user_data) { if (g_strcmp0 (mechanism, "EXTERNAL") == 0) { return TRUE; } return FALSE; } ``` ## Controlling Authorization By default, a `GDBusServer` or server-side `GDBusConnection` will accept connections from any successfully authenticated user (but not from anonymous connections using the `ANONYMOUS` mechanism). If you only want to allow D-Bus connections from processes owned by the same uid as the server, since GLib 2.68, you should use the `G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER` flag. It’s equivalent to the following signal handler: ```c static gboolean on_authorize_authenticated_peer (GDBusAuthObserver *observer, GIOStream *stream, GCredentials *credentials, gpointer user_data) { gboolean authorized; authorized = FALSE; if (credentials != NULL) { GCredentials *own_credentials; own_credentials = g_credentials_new (); if (g_credentials_is_same_user (credentials, own_credentials, NULL)) authorized = TRUE; g_object_unref (own_credentials); } return authorized; } ``` Creates a new #GDBusAuthObserver object. A #GDBusAuthObserver. Free with g_object_unref(). Emits the #GDBusAuthObserver::allow-mechanism signal on @observer. %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not. A #GDBusAuthObserver. The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer. %TRUE if the peer is authorized, %FALSE if not. A #GDBusAuthObserver. A #GIOStream for the #GDBusConnection. Credentials received from the peer or %NULL. Emitted to check if @mechanism is allowed to be used. %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not. The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. Emitted to check if a peer that is successfully authenticated is authorized. %TRUE if the peer is authorized, %FALSE if not. A #GIOStream for the #GDBusConnection. Credentials received from the peer or %NULL. Flags used in g_dbus_connection_call() and similar APIs. No flags set. The bus must not launch an owner for the destination name in response to this method invocation. the caller is prepared to wait for interactive authorization. Since 2.46. Capabilities negotiated with the remote peer. No flags set. The connection supports exchanging UNIX file descriptors with the remote peer. The `GDBusConnection` type is used for D-Bus connections to remote peers such as a message buses. It is a low-level API that offers a lot of flexibility. For instance, it lets you establish a connection over any transport that can by represented as a [class@Gio.IOStream]. This class is rarely used directly in D-Bus clients. If you are writing a D-Bus client, it is often easier to use the [func@Gio.bus_own_name], [func@Gio.bus_watch_name] or [func@Gio.DBusProxy.new_for_bus] APIs. As an exception to the usual GLib rule that a particular object must not be used by two threads at the same time, `GDBusConnection`s methods may be called from any thread. This is so that [func@Gio.bus_get] and [func@Gio.bus_get_sync] can safely return the same `GDBusConnection` when called from any thread. Most of the ways to obtain a `GDBusConnection` automatically initialize it (i.e. connect to D-Bus): for instance, [func@Gio.DBusConnection.new] and [func@Gio.bus_get], and the synchronous versions of those methods, give you an initialized connection. Language bindings for GIO should use [func@Gio.Initable.new] or [func@Gio.AsyncInitable.new_async], which also initialize the connection. If you construct an uninitialized `GDBusConnection`, such as via [ctor@GObject.Object.new], you must initialize it via [method@Gio.Initable.init] or [method@Gio.AsyncInitable.init_async] before using its methods or properties. Calling methods or accessing properties on a `GDBusConnection` that has not completed initialization successfully is considered to be invalid, and leads to undefined behaviour. In particular, if initialization fails with a `GError`, the only valid thing you can do with that `GDBusConnection` is to free it with [method@GObject.Object.unref]. ## An example D-Bus server Here is an example for a D-Bus server: [gdbus-example-server.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-server.c) ## An example for exporting a subtree Here is an example for exporting a subtree: [gdbus-example-subtree.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-subtree.c) ## An example for file descriptor passing Here is an example for passing UNIX file descriptors: [gdbus-unix-fd-client.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-unix-fd-client.c) ## An example for exporting a GObject Here is an example for exporting a #GObject: [gdbus-example-export.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-export.c) Finishes an operation started with g_dbus_connection_new(). a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new(). Finishes an operation started with g_dbus_connection_new_for_address(). a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new() Synchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by @address which must be in the [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). This constructor can only be used to initiate client-side connections - use g_dbus_connection_new_sync() if you need to act as the server. In particular, @flags cannot contain the %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER, %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flags. This is a synchronous failable constructor. See g_dbus_connection_new_for_address() for the asynchronous version. If @observer is not %NULL it may be used to control the authentication process. a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). a D-Bus address flags describing how to make the connection a #GDBusAuthObserver or %NULL a #GCancellable or %NULL Synchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by @stream. If @stream is a #GSocketConnection, then the corresponding #GSocket will be put into non-blocking mode. The D-Bus connection will interact with @stream from a worker thread. As a result, the caller should not interact with @stream after this method has been called, except by calling g_object_unref() on it. If @observer is not %NULL it may be used to control the authentication process. This is a synchronous failable constructor. See g_dbus_connection_new() for the asynchronous version. a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). a #GIOStream the GUID to use if authenticating as a server or %NULL flags describing how to make the connection a #GDBusAuthObserver or %NULL a #GCancellable or %NULL Asynchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by @stream. If @stream is a #GSocketConnection, then the corresponding #GSocket will be put into non-blocking mode. The D-Bus connection will interact with @stream from a worker thread. As a result, the caller should not interact with @stream after this method has been called, except by calling g_object_unref() on it. If @observer is not %NULL it may be used to control the authentication process. When the operation is finished, @callback will be invoked. You can then call g_dbus_connection_new_finish() to get the result of the operation. This is an asynchronous failable constructor. See g_dbus_connection_new_sync() for the synchronous version. a #GIOStream the GUID to use if authenticating as a server or %NULL flags describing how to make the connection a #GDBusAuthObserver or %NULL a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied the data to pass to @callback Asynchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by @address which must be in the [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). This constructor can only be used to initiate client-side connections - use g_dbus_connection_new() if you need to act as the server. In particular, @flags cannot contain the %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER, %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flags. When the operation is finished, @callback will be invoked. You can then call g_dbus_connection_new_for_address_finish() to get the result of the operation. If @observer is not %NULL it may be used to control the authentication process. This is an asynchronous failable constructor. See g_dbus_connection_new_for_address_sync() for the synchronous version. a D-Bus address flags describing how to make the connection a #GDBusAuthObserver or %NULL a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied the data to pass to @callback Adds a message filter. Filters are handlers that are run on all incoming and outgoing messages, prior to standard dispatch. Filters are run in the order that they were added. The same handler can be added as a filter more than once, in which case it will be run more than once. Filters added during a filter callback won't be run on the message being processed. Filter functions are allowed to modify and even drop messages. Note that filters are run in a dedicated message handling thread so they can't block and, generally, can't do anything but signal a worker thread. Also note that filters are rarely needed - use API such as g_dbus_connection_send_message_with_reply(), g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead. If a filter consumes an incoming message the message is not dispatched anywhere else - not even the standard dispatch machinery (that API such as g_dbus_connection_signal_subscribe() and g_dbus_connection_send_message_with_reply() relies on) will see the message. Similarly, if a filter consumes an outgoing message, the message will not be sent to the other peer. If @user_data_free_func is non-%NULL, it will be called (in the thread-default main context of the thread you are calling this method from) at some point after @user_data is no longer needed. (It is not guaranteed to be called synchronously when the filter is removed, and may be called after @connection has been destroyed.) a filter identifier that can be used with g_dbus_connection_remove_filter() a #GDBusConnection a filter function user data to pass to @filter_function function to free @user_data with when filter is removed or %NULL Asynchronously invokes the @method_name method on the @interface_name D-Bus interface on the remote object at @object_path owned by @bus_name. If @connection is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value not compatible with the D-Bus protocol, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. If @reply_type is non-%NULL then the reply will be checked for having this type and an error will be raised if it does not match. Said another way, if you give a @reply_type then any non-%NULL return value will be of this type. Unless it’s %G_VARIANT_TYPE_UNIT, the @reply_type will be a tuple containing one or more values. If the @parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: |[<!-- language="C" --> g_dbus_connection_call (connection, "org.freedesktop.StringThings", "/org/freedesktop/StringThings", "org.freedesktop.StringThings", "TwoStrings", g_variant_new ("(ss)", "Thing One", "Thing Two"), NULL, G_DBUS_CALL_FLAGS_NONE, -1, NULL, (GAsyncReadyCallback) two_strings_done, NULL); ]| This is an asynchronous method. When the operation is finished, @callback will be invoked in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. You can then call g_dbus_connection_call_finish() to get the result of the operation. See g_dbus_connection_call_sync() for the synchronous version of this function. If @callback is %NULL then the D-Bus method call message will be sent with the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. a #GDBusConnection a unique or well-known bus name or %NULL if @connection is not a message bus connection path of remote object D-Bus interface to invoke method on the name of the method to invoke a #GVariant tuple with parameters for the method or %NULL if not passing parameters the expected type of the reply (which will be a tuple), or %NULL flags from the #GDBusCallFlags enumeration the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation the data to pass to @callback Finishes an operation started with g_dbus_connection_call(). %NULL if @error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref(). a #GDBusConnection a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call() Synchronously invokes the @method_name method on the @interface_name D-Bus interface on the remote object at @object_path owned by @bus_name. If @connection is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value not compatible with the D-Bus protocol, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. If @reply_type is non-%NULL then the reply will be checked for having this type and an error will be raised if it does not match. Said another way, if you give a @reply_type then any non-%NULL return value will be of this type. If the @parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: |[<!-- language="C" --> g_dbus_connection_call_sync (connection, "org.freedesktop.StringThings", "/org/freedesktop/StringThings", "org.freedesktop.StringThings", "TwoStrings", g_variant_new ("(ss)", "Thing One", "Thing Two"), NULL, G_DBUS_CALL_FLAGS_NONE, -1, NULL, &error); ]| The calling thread is blocked until a reply is received. See g_dbus_connection_call() for the asynchronous version of this method. %NULL if @error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref(). a #GDBusConnection a unique or well-known bus name or %NULL if @connection is not a message bus connection path of remote object D-Bus interface to invoke method on the name of the method to invoke a #GVariant tuple with parameters for the method or %NULL if not passing parameters the expected type of the reply, or %NULL flags from the #GDBusCallFlags enumeration the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout a #GCancellable or %NULL Like g_dbus_connection_call() but also takes a #GUnixFDList object. The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE values in the body of the message. For example, if a message contains two file descriptors, @fd_list would have length 2, and `g_variant_new_handle (0)` and `g_variant_new_handle (1)` would appear somewhere in the body of the message (not necessarily in that order!) to represent the file descriptors at indexes 0 and 1 respectively. When designing D-Bus APIs that are intended to be interoperable, please note that non-GDBus implementations of D-Bus can usually only access file descriptors if they are referenced in this way by a value of type %G_VARIANT_TYPE_HANDLE in the body of the message. This method is only available on UNIX. a #GDBusConnection a unique or well-known bus name or %NULL if @connection is not a message bus connection path of remote object D-Bus interface to invoke method on the name of the method to invoke a #GVariant tuple with parameters for the method or %NULL if not passing parameters the expected type of the reply, or %NULL flags from the #GDBusCallFlags enumeration the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout a #GUnixFDList or %NULL a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't * care about the result of the method invocation The data to pass to @callback. Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE values in the body of the message. For example, if g_variant_get_handle() returns 5, that is intended to be a reference to the file descriptor that can be accessed by `g_unix_fd_list_get (*out_fd_list, 5, ...)`. When designing D-Bus APIs that are intended to be interoperable, please note that non-GDBus implementations of D-Bus can usually only access file descriptors if they are referenced in this way by a value of type %G_VARIANT_TYPE_HANDLE in the body of the message. %NULL if @error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref(). a #GDBusConnection return location for a #GUnixFDList or %NULL a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call_with_unix_fd_list() Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects. See g_dbus_connection_call_with_unix_fd_list() and g_dbus_connection_call_with_unix_fd_list_finish() for more details. This method is only available on UNIX. %NULL if @error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref(). a #GDBusConnection a unique or well-known bus name or %NULL if @connection is not a message bus connection path of remote object D-Bus interface to invoke method on the name of the method to invoke a #GVariant tuple with parameters for the method or %NULL if not passing parameters the expected type of the reply, or %NULL flags from the #GDBusCallFlags enumeration the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout a #GUnixFDList or %NULL return location for a #GUnixFDList or %NULL a #GCancellable or %NULL Closes @connection. Note that this never causes the process to exit (this might only happen if the other end of a shared message bus connection disconnects, see #GDBusConnection:exit-on-close). Once the connection is closed, operations such as sending a message will return with the error %G_IO_ERROR_CLOSED. Closing a connection will not automatically flush the connection so queued messages may be lost. Use g_dbus_connection_flush() if you need such guarantees. If @connection is already closed, this method fails with %G_IO_ERROR_CLOSED. When @connection has been closed, the #GDBusConnection::closed signal is emitted in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread that @connection was constructed in. This is an asynchronous method. When the operation is finished, @callback will be invoked in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. You can then call g_dbus_connection_close_finish() to get the result of the operation. See g_dbus_connection_close_sync() for the synchronous version. a #GDBusConnection a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result The data to pass to @callback Finishes an operation started with g_dbus_connection_close(). %TRUE if the operation succeeded, %FALSE if @error is set a #GDBusConnection a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_close() Synchronously closes @connection. The calling thread is blocked until this is done. See g_dbus_connection_close() for the asynchronous version of this method and more details about what it does. %TRUE if the operation succeeded, %FALSE if @error is set a #GDBusConnection a #GCancellable or %NULL Emits a signal. If the parameters GVariant is floating, it is consumed. This can only fail if @parameters is not compatible with the D-Bus protocol (%G_IO_ERROR_INVALID_ARGUMENT), or if @connection has been closed (%G_IO_ERROR_CLOSED). %TRUE unless @error is set a #GDBusConnection the unique bus name for the destination for the signal or %NULL to emit to all listeners path of remote object D-Bus interface to emit a signal on the name of the signal to emit a #GVariant tuple with parameters for the signal or %NULL if not passing parameters Exports @action_group on @connection at @object_path. The implemented D-Bus API should be considered private. It is subject to change in the future. A given object path can only have one action group exported on it. If this constraint is violated, the export will fail and 0 will be returned (with @error set accordingly). You can unexport the action group using [method@Gio.DBusConnection.unexport_action_group] with the return value of this function. The thread default main context is taken at the time of this call. All incoming action activations and state change requests are reported from this context. Any changes on the action group that cause it to emit signals must also come from this same context. Since incoming action activations and state change requests are rather likely to cause changes on the action group, this effectively limits a given action group to being exported from only one main context. the ID of the export (never zero), or 0 in case of failure the D-Bus connection a D-Bus object path an action group Exports @menu on @connection at @object_path. The implemented D-Bus API should be considered private. It is subject to change in the future. An object path can only have one menu model exported on it. If this constraint is violated, the export will fail and 0 will be returned (with @error set accordingly). Exporting menus with sections containing more than %G_MENU_EXPORTER_MAX_SECTION_SIZE items is not supported and results in undefined behavior. You can unexport the menu model using g_dbus_connection_unexport_menu_model() with the return value of this function. the ID of the export (never zero), or 0 in case of failure a #GDBusConnection a D-Bus object path a #GMenuModel Asynchronously flushes @connection, that is, writes all queued outgoing messages to the transport and then flushes the transport (using g_output_stream_flush_async()). This is useful in programs that want to emit a D-Bus signal and then exit immediately. Without flushing the connection, there is no guarantee that the message has been sent to the networking buffers in the OS kernel. This is an asynchronous method. When the operation is finished, @callback will be invoked in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. You can then call g_dbus_connection_flush_finish() to get the result of the operation. See g_dbus_connection_flush_sync() for the synchronous version. a #GDBusConnection a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result The data to pass to @callback Finishes an operation started with g_dbus_connection_flush(). %TRUE if the operation succeeded, %FALSE if @error is set a #GDBusConnection a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_flush() Synchronously flushes @connection. The calling thread is blocked until this is done. See g_dbus_connection_flush() for the asynchronous version of this method and more details about what it does. %TRUE if the operation succeeded, %FALSE if @error is set a #GDBusConnection a #GCancellable or %NULL Gets the capabilities negotiated with the remote peer zero or more flags from the #GDBusCapabilityFlags enumeration a #GDBusConnection Gets whether the process is terminated when @connection is closed by the remote peer. See #GDBusConnection:exit-on-close for more details. whether the process is terminated when @connection is closed by the remote peer a #GDBusConnection Gets the flags used to construct this connection zero or more flags from the #GDBusConnectionFlags enumeration a #GDBusConnection The GUID of the peer performing the role of server when authenticating. See #GDBusConnection:guid for more details. The GUID. Do not free this string, it is owned by @connection. a #GDBusConnection Retrieves the last serial number assigned to a #GDBusMessage on the current thread. This includes messages sent via both low-level API such as g_dbus_connection_send_message() as well as high-level API such as g_dbus_connection_emit_signal(), g_dbus_connection_call() or g_dbus_proxy_call(). the last used serial or zero when no message has been sent within the current thread a #GDBusConnection Gets the credentials of the authenticated peer. This will always return %NULL unless @connection acted as a server (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed) when set up and the client passed credentials as part of the authentication process. In a message bus setup, the message bus is always the server and each application is a client. So this method will always return %NULL for message bus clients. a #GCredentials or %NULL if not available. Do not free this object, it is owned by @connection. a #GDBusConnection Gets the underlying stream used for IO. While the #GDBusConnection is active, it will interact with this stream from a worker thread, so it is not safe to interact with the stream directly. the stream used for IO a #GDBusConnection Gets the unique name of @connection as assigned by the message bus. This can also be used to figure out if @connection is a message bus connection. the unique name or %NULL if @connection is not a message bus connection. Do not free this string, it is owned by @connection. a #GDBusConnection Gets whether @connection is closed. %TRUE if the connection is closed, %FALSE otherwise a #GDBusConnection Registers callbacks for exported objects at @object_path with the D-Bus interface that is described in @interface_info. Calls to functions in @vtable (and @user_data_free_func) will happen in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. Note that all #GVariant values passed to functions in @vtable will match the signature given in @interface_info - if a remote caller passes incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs` is returned to the remote caller. Additionally, if the remote caller attempts to invoke methods or access properties not mentioned in @interface_info the `org.freedesktop.DBus.Error.UnknownMethod` resp. `org.freedesktop.DBus.Error.InvalidArgs` errors are returned to the caller. It is considered a programming error if the #GDBusInterfaceGetPropertyFunc function in @vtable returns a #GVariant of incorrect type. If an existing callback is already registered at @object_path and @interface_name, then @error is set to %G_IO_ERROR_EXISTS. GDBus automatically implements the standard D-Bus interfaces org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable and org.freedesktop.Peer, so you don't have to implement those for the objects you export. You can implement org.freedesktop.DBus.Properties yourself, e.g. to handle getting and setting of properties asynchronously. Note that the reference count on @interface_info will be incremented by 1 (unless allocated statically, e.g. if the reference count is -1, see g_dbus_interface_info_ref()) for as long as the object is exported. Also note that @vtable will be copied. See this [server][class@Gio.DBusConnection#an-example-d-bus-server] for an example of how to use this method. 0 if @error is set, otherwise a registration id (never 0) that can be used with g_dbus_connection_unregister_object() a #GDBusConnection the object path to register at introspection data for the interface a #GDBusInterfaceVTable to call into or %NULL data to pass to functions in @vtable function to call when the object path is unregistered Version of g_dbus_connection_register_object() using closures instead of a #GDBusInterfaceVTable for easier binding in other languages. Note that the reference counting semantics of the function wrapped by @method_call_closure are the same as those of [callback@Gio.DBusInterfaceMethodCallFunc]: ownership of a reference to the [class@Gio.DBusMethodInvocation] is transferred to the function. Deprecated in favour of [method@Gio.DBusConnection.register_object_with_closures2], which has more binding-friendly reference counting semantics. 0 if @error is set, otherwise a registration ID (never 0) that can be used with g_dbus_connection_unregister_object() . A #GDBusConnection. The object path to register at. Introspection data for the interface. #GClosure for handling incoming method calls. #GClosure for getting a property. #GClosure for setting a property. Version of [method@Gio.DBusConnection.register_object] using closures instead of a [type@Gio.DBusInterfaceVTable] for easier binding in other languages. In contrast to [method@Gio.DBusConnection.register_object] and [method@Gio.DBusConnection.register_object_with_closures], the reference counting semantics of the function wrapped by @method_call_closure are *not* the same as those of [callback@Gio.DBusInterfaceMethodCallFunc]. Ownership of a reference to the [class@Gio.DBusMethodInvocation] is *not* transferred to the function. Bindings must ensure that they add a reference to the [class@Gio.DBusMethodInvocation] before calling any `g_dbus_method_invocation_return_*()` methods on it. This should be automatic as a result of the introspection annotations on those methods. `0` if @error is set, otherwise a registration ID (never `0`) that can be used with [method@Gio.DBusConnection.unregister_object]. A [class@Gio.DBusConnection]. The object path to register at. Introspection data for the interface. [type@GObject.Closure] for handling incoming method calls. [type@GObject.Closure] for getting a property. [type@GObject.Closure] for setting a property. Registers a whole subtree of dynamic objects. The @enumerate and @introspection functions in @vtable are used to convey, to remote callers, what nodes exist in the subtree rooted by @object_path. When handling remote calls into any node in the subtree, first the @enumerate function is used to check if the node exists. If the node exists or the %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set the @introspection function is used to check if the node supports the requested method. If so, the @dispatch function is used to determine where to dispatch the call. The collected #GDBusInterfaceVTable and #gpointer will be used to call into the interface vtable for processing the request. All calls into user-provided code will be invoked in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. If an existing subtree is already registered at @object_path or then @error is set to %G_IO_ERROR_EXISTS. Note that it is valid to register regular objects (using g_dbus_connection_register_object()) in a subtree registered with g_dbus_connection_register_subtree() - if so, the subtree handler is tried as the last resort. One way to think about a subtree handler is to consider it a fallback handler for object paths not registered via g_dbus_connection_register_object() or other bindings. Note that @vtable will be copied so you cannot change it after registration. See this [server][class@Gio.DBusConnection#an-example-for-exporting-a-subtree] for an example of how to use this method. 0 if @error is set, otherwise a subtree registration ID (never 0) that can be used with g_dbus_connection_unregister_subtree() a #GDBusConnection the object path to register the subtree at a #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree flags used to fine tune the behavior of the subtree data to pass to functions in @vtable function to call when the subtree is unregistered Removes a filter. Note that since filters run in a different thread, there is a race condition where it is possible that the filter will be running even after calling g_dbus_connection_remove_filter(), so you cannot just free data that the filter might be using. Instead, you should pass a #GDestroyNotify to g_dbus_connection_add_filter(), which will be called when it is guaranteed that the data is no longer needed. a #GDBusConnection an identifier obtained from g_dbus_connection_add_filter() Asynchronously sends @message to the peer represented by @connection. Unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number will be assigned by @connection and set on @message via g_dbus_message_set_serial(). If @out_serial is not %NULL, then the serial number used will be written to this location prior to submitting the message to the underlying transport. While it has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. If @connection is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @message is not well-formed, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. See this [server][class@Gio.DBusConnection#an-example-d-bus-server] and [client][class@Gio.DBusConnection#an-example-for-file-descriptor-passing] for an example of how to use this low-level API to send and receive UNIX file descriptors. Note that @message must be unlocked, unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. %TRUE if the message was well-formed and queued for transmission, %FALSE if @error is set a #GDBusConnection a #GDBusMessage flags affecting how the message is sent return location for serial number assigned to @message when sending it or %NULL Asynchronously sends @message to the peer represented by @connection. Unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number will be assigned by @connection and set on @message via g_dbus_message_set_serial(). If @out_serial is not %NULL, then the serial number used will be written to this location prior to submitting the message to the underlying transport. While it has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. If @connection is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. This is an asynchronous method. When the operation is finished, @callback will be invoked in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. You can then call g_dbus_connection_send_message_with_reply_finish() to get the result of the operation. See g_dbus_connection_send_message_with_reply_sync() for the synchronous version. Note that @message must be unlocked, unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. See this [server][class@Gio.DBusConnection#an-example-d-bus-server] and [client][class@Gio.DBusConnection#an-example-for-file-descriptor-passing] for an example of how to use this low-level API to send and receive UNIX file descriptors. a #GDBusConnection a #GDBusMessage flags affecting how the message is sent the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout return location for serial number assigned to @message when sending it or %NULL a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result The data to pass to @callback Finishes an operation started with g_dbus_connection_send_message_with_reply(). Note that @error is only set if a local in-process error occurred. That is to say that the returned #GDBusMessage object may be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use g_dbus_message_to_gerror() to transcode this to a #GError. See this [server][class@Gio.DBusConnection#an-example-d-bus-server] and [client][class@Gio.DBusConnection#an-example-for-file-descriptor-passing] for an example of how to use this low-level API to send and receive UNIX file descriptors. a locked #GDBusMessage or %NULL if @error is set a #GDBusConnection a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply() Synchronously sends @message to the peer represented by @connection and blocks the calling thread until a reply is received or the timeout is reached. See g_dbus_connection_send_message_with_reply() for the asynchronous version of this method. Unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number will be assigned by @connection and set on @message via g_dbus_message_set_serial(). If @out_serial is not %NULL, then the serial number used will be written to this location prior to submitting the message to the underlying transport. While it has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. If @connection is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. Note that @error is only set if a local in-process error occurred. That is to say that the returned #GDBusMessage object may be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use g_dbus_message_to_gerror() to transcode this to a #GError. See this [server][class@Gio.DBusConnection#an-example-d-bus-server] and [client][class@Gio.DBusConnection#an-example-for-file-descriptor-passing] for an example of how to use this low-level API to send and receive UNIX file descriptors. Note that @message must be unlocked, unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. a locked #GDBusMessage that is the reply to @message or %NULL if @error is set a #GDBusConnection a #GDBusMessage flags affecting how the message is sent. the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout return location for serial number assigned to @message when sending it or %NULL a #GCancellable or %NULL Sets whether the process should be terminated when @connection is closed by the remote peer. See #GDBusConnection:exit-on-close for more details. Note that this function should be used with care. Most modern UNIX desktops tie the notion of a user session with the session bus, and expect all of a user's applications to quit when their bus connection goes away. If you are setting @exit_on_close to %FALSE for the shared session bus connection, you should make sure that your application exits when the user session ends. a #GDBusConnection whether the process should be terminated when @connection is closed by the remote peer Subscribes to signals on @connection and invokes @callback whenever the signal is received. Note that @callback will be invoked in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. If @connection is not a message bus connection, @sender must be %NULL. If @sender is a well-known name note that @callback is invoked with the unique name for the owner of @sender, not the well-known name as one would expect. This is because the message bus rewrites the name. As such, to avoid certain race conditions, users should be tracking the name owner of the well-known name and use that when processing the received signal. If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is interpreted as part of a namespace or path. The first argument of a signal is matched against that part as specified by D-Bus. If @user_data_free_func is non-%NULL, it will be called (in the thread-default main context of the thread you are calling this method from) at some point after @user_data is no longer needed. (It is not guaranteed to be called synchronously when the signal is unsubscribed from, and may be called after @connection has been destroyed.) As @callback is potentially invoked in a different thread from where it’s emitted, it’s possible for this to happen after g_dbus_connection_signal_unsubscribe() has been called in another thread. Due to this, @user_data should have a strong reference which is freed with @user_data_free_func, rather than pointing to data whose lifecycle is tied to the signal subscription. For example, if a #GObject is used to store the subscription ID from g_dbus_connection_signal_subscribe(), a strong reference to that #GObject must be passed to @user_data, and g_object_unref() passed to @user_data_free_func. You are responsible for breaking the resulting reference count cycle by explicitly unsubscribing from the signal when dropping the last external reference to the #GObject. Alternatively, a weak reference may be used. It is guaranteed that if you unsubscribe from a signal using g_dbus_connection_signal_unsubscribe() from the same thread which made the corresponding g_dbus_connection_signal_subscribe() call, @callback will not be invoked after g_dbus_connection_signal_unsubscribe() returns. The returned subscription identifier is an opaque value which is guaranteed to never be zero. This function can never fail. a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe() a #GDBusConnection sender name to match on (unique or well-known name) or %NULL to listen from all senders D-Bus interface name to match on or %NULL to match on all interfaces D-Bus signal name to match on or %NULL to match on all signals object path to match on or %NULL to match on all object paths contents of first string argument to match on or %NULL to match on all kinds of arguments #GDBusSignalFlags describing how arg0 is used in subscribing to the signal callback to invoke when there is a signal matching the requested data user data to pass to @callback function to free @user_data with when subscription is removed or %NULL Unsubscribes from signals. Note that there may still be D-Bus traffic to process (relating to this signal subscription) in the current thread-default #GMainContext after this function has returned. You should continue to iterate the #GMainContext until the #GDestroyNotify function passed to g_dbus_connection_signal_subscribe() is called, in order to avoid memory leaks through callbacks queued on the #GMainContext after it’s stopped being iterated. Alternatively, any idle source with a priority lower than %G_PRIORITY_DEFAULT that was scheduled after unsubscription, also indicates that all resources of this subscription are released. a #GDBusConnection a subscription id obtained from g_dbus_connection_signal_subscribe() If @connection was created with %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method starts processing messages. Does nothing on if @connection wasn't created with this flag or if the method has already been called. a #GDBusConnection Reverses the effect of a previous call to [method@Gio.DBusConnection.export_action_group]. It is an error to call this function with an ID that wasn’t returned from [method@Gio.DBusConnection.export_action_group] or to call it with the same ID more than once. the D-Bus connection the ID from [method@Gio.DBusConnection.export_action_group] Reverses the effect of a previous call to g_dbus_connection_export_menu_model(). It is an error to call this function with an ID that wasn't returned from g_dbus_connection_export_menu_model() or to call it with the same ID more than once. a #GDBusConnection the ID from g_dbus_connection_export_menu_model() Unregisters an object. %TRUE if the object was unregistered, %FALSE otherwise a #GDBusConnection a registration id obtained from g_dbus_connection_register_object() Unregisters a subtree. %TRUE if the subtree was unregistered, %FALSE otherwise a #GDBusConnection a subtree registration id obtained from g_dbus_connection_register_subtree() A D-Bus address specifying potential endpoints that can be used when establishing the connection. A #GDBusAuthObserver object to assist in the authentication process or %NULL. Flags from the #GDBusCapabilityFlags enumeration representing connection features negotiated with the other peer. A boolean specifying whether the connection has been closed. A boolean specifying whether the process will be terminated (by calling `raise(SIGTERM)`) if the connection is closed by the remote peer. Note that #GDBusConnection objects returned by g_bus_get_finish() and g_bus_get_sync() will (usually) have this property set to %TRUE. Flags from the #GDBusConnectionFlags enumeration. The GUID of the peer performing the role of server when authenticating. If you are constructing a #GDBusConnection and pass %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the #GDBusConnection:flags property then you **must** also set this property to a valid guid. If you are constructing a #GDBusConnection and pass %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the #GDBusConnection:flags property you will be able to read the GUID of the other peer here after the connection has been successfully initialized. Note that the [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) uses the term ‘UUID’ to refer to this, whereas GLib consistently uses the term ‘GUID’ for historical reasons. Despite its name, the format of #GDBusConnection:guid does not follow [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122) or the Microsoft GUID format. The underlying #GIOStream used for I/O. If this is passed on construction and is a #GSocketConnection, then the corresponding #GSocket will be put into non-blocking mode. While the #GDBusConnection is active, it will interact with this stream from a worker thread, so it is not safe to interact with the stream directly. The unique name as assigned by the message bus or %NULL if the connection is not open or not a message bus connection. Emitted when the connection is closed. The cause of this event can be - If g_dbus_connection_close() is called. In this case @remote_peer_vanished is set to %FALSE and @error is %NULL. - If the remote peer closes the connection. In this case @remote_peer_vanished is set to %TRUE and @error is set. - If the remote peer sends invalid or malformed data. In this case @remote_peer_vanished is set to %FALSE and @error is set. Upon receiving this signal, you should give up your reference to @connection. You are guaranteed that this signal is emitted only once. %TRUE if @connection is closed because the remote peer closed its end of the connection a #GError with more details about the event or %NULL Flags used when creating a new #GDBusConnection. No flags set. Perform authentication against server. Perform authentication against client. When authenticating as a server, allow the anonymous authentication method. Pass this flag if connecting to a peer that is a message bus. This means that the Hello() method will be invoked as part of the connection setup. If set, processing of D-Bus messages is delayed until g_dbus_connection_start_message_processing() is called. When authenticating as a server, require the UID of the peer to be the same as the UID of the server. (Since: 2.68) When authenticating, try to use protocols that work across a Linux user namespace boundary, even if this reduces interoperability with older D-Bus implementations. This currently affects client-side `EXTERNAL` authentication, for which this flag makes connections to a server in another user namespace succeed, but causes a deadlock when connecting to a GDBus server older than 2.73.3. Since: 2.74 Error codes for the %G_DBUS_ERROR error domain. A generic error; "something went wrong" - see the error message for more. There was not enough memory to complete an operation. The bus doesn't know how to launch a service to supply the bus name you wanted. The bus name you referenced doesn't exist (i.e. no application owns it). No reply to a message expecting one, usually means a timeout occurred. Something went wrong reading or writing to a socket, for example. A D-Bus bus address was malformed. Requested operation isn't supported (like ENOSYS on UNIX). Some limited resource is exhausted. Security restrictions don't allow doing what you're trying to do. Authentication didn't work. Unable to connect to server (probably caused by ECONNREFUSED on a socket). Certain timeout errors, possibly ETIMEDOUT on a socket. Note that %G_DBUS_ERROR_NO_REPLY is used for message reply timeouts. Warning: this is confusingly-named given that %G_DBUS_ERROR_TIMED_OUT also exists. We can't fix it for compatibility reasons so just be careful. No network access (probably ENETUNREACH on a socket). Can't bind a socket since its address is in use (i.e. EADDRINUSE). The connection is disconnected and you're trying to use it. Invalid arguments passed to a method call. Missing file. Existing file and the operation you're using does not silently overwrite. Method name you invoked isn't known by the object you invoked it on. Certain timeout errors, e.g. while starting a service. Warning: this is confusingly-named given that %G_DBUS_ERROR_TIMEOUT also exists. We can't fix it for compatibility reasons so just be careful. Tried to remove or modify a match rule that didn't exist. The match rule isn't syntactically valid. While starting a new process, the exec() call failed. While starting a new process, the fork() call failed. While starting a new process, the child exited with a status code. While starting a new process, the child exited on a signal. While starting a new process, something went wrong. We failed to setup the environment correctly. We failed to setup the config parser correctly. Bus name was not valid. Service file not found in system-services directory. Permissions are incorrect on the setuid helper. Service file invalid (Name, User or Exec missing). Tried to get a UNIX process ID and it wasn't available. Tried to get a UNIX process ID and it wasn't available. A type signature is not valid. A file contains invalid syntax or is otherwise broken. Asked for SELinux security context and it wasn't available. Asked for ADT audit data and it wasn't available. There's already an object with the requested object path. Object you invoked a method on isn't known. Since 2.42 Interface you invoked a method on isn't known by the object. Since 2.42 Property you tried to access isn't known by the object. Since 2.42 Property you tried to set is read-only. Since 2.42 Creates a D-Bus error name to use for @error. If @error matches a registered error (see [func@Gio.DBusError.register_error]), the corresponding D-Bus error name will be returned. Otherwise the a name of the form `org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE` will be used. This allows other GDBus applications to map the error on the wire back to a [type@GLib.Error] using [func@Gio.DBusError.new_for_dbus_error]. This function is typically only used in object mappings to put a [type@GLib.Error] on the wire. Regular applications should not use it. a D-Bus error name an error Gets the D-Bus error name used for @error, if any. This function is guaranteed to return a D-Bus error name for all [type@GLib.Error]s returned from functions handling remote method calls (for example, [method@Gio.DBusConnection.call_finish]) unless [func@Gio.DBusError.strip_remote_error] has already been used on @error. an allocated string, or `NULL` if the D-Bus error name could not be found an error Checks if @error represents an error received via D-Bus from a remote peer. If so, use [func@Gio.DBusError.get_remote_error] to get the name of the error. true if @error represents an error from a remote peer; false otherwise an error Creates a [type@GLib.Error] based on the contents of @dbus_error_name and @dbus_error_message. Errors registered with [func@Gio.DBusError.register_error] will be looked up using @dbus_error_name and if a match is found, the error domain and code is used. Applications can use [func@Gio.DBusError.get_remote_error] to recover @dbus_error_name. If a match against a registered error is not found and the D-Bus error name is in a form as returned by [func@Gio.DBusError.encode_gerror] the error domain and code encoded in the name is used to create the [type@GLib.Error]. Also, @dbus_error_name is added to the error message such that it can be recovered with [func@Gio.DBusError.get_remote_error]. Otherwise, a [type@GLib.Error] with the error code [error@Gio.IOErrorEnum.DBUS_ERROR] in the [error@Gio.IOErrorEnum] error domain is returned. Also, @dbus_error_name is added to the error message such that it can be recovered with [func@Gio.DBusError.get_remote_error]. In all three cases, @dbus_error_name can always be recovered from the returned [type@GLib.Error] using the [func@Gio.DBusError.get_remote_error] function (unless [func@Gio.DBusError.strip_remote_error] hasn’t been used on the returned error). This function is typically only used in object mappings to prepare [type@GLib.Error] instances for applications. Regular applications should not use it. an allocated [type@GLib.Error] D-Bus error name D-Bus error message Creates an association mapping between @dbus_error_name and [type@GLib.Error]s specified by @error_domain and @error_code. This is typically done in the function that returns the [type@GLib.Quark] for an error domain. true if the association was created, false if it already exists a [type@GLib.Quark] for an error domain an error code a D-Bus error name Helper function for associating a [type@GLib.Error] error domain with D-Bus error names. While @quark_volatile has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. the error domain name return location for the [type@GLib.Quark] representing the error domain items to register number of items to register Sets `*error` to a new [type@GLib.Error] created with [func@Gio.DBusError.new_for_dbus_error]. If @format is non-`NULL` then it is prepended to @dbus_error_message. Otherwise @dbus_error_message is used unmodified. This function does nothing if @error is `NULL`. return location for a [type@GLib.Error] D-Bus error name D-Bus error message `printf()`-style format to prepend to @dbus_error_message, or `NULL` to not modify the message arguments for @format Like [func@Gio.DBusError.set_dbus_error] but intended for language bindings. return location for a [type@GLib.Error] D-Bus error name D-Bus error message `printf()`-style format to prepend to @dbus_error_message, or `NULL` to not modify the message arguments for @format Looks for extra information in the error message used to recover the D-Bus error name and strips it if found. If stripped, the message field in @error will correspond exactly to what was received on the wire. This is typically used when presenting errors to the end user. true if information was stripped; false otherwise an error Destroys an association previously set up with [func@Gio.DBusError.register_error]. true if the association was destroyed, false if it wasn’t found a [type@GLib.Quark] for an error domain an error code a D-Bus error name Struct used in [func@Gio.DBusError.register_error_domain]. an error code the D-Bus error name to associate with @error_code Base type for D-Bus interfaces. The `GDBusInterface` type is the base type for D-Bus interfaces both on the service side (see [class@Gio.DBusInterfaceSkeleton]) and client side (see [class@Gio.DBusProxy]). Gets the #GDBusObject that @interface_ belongs to, if any. A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref(). An exported D-Bus interface. Gets D-Bus introspection information for the D-Bus interface implemented by @interface_. This can return %NULL if no #GDBusInterfaceInfo was provided during construction of @interface_ and is also not made available otherwise. For example, #GDBusProxy implements #GDBusInterface but allows for a %NULL #GDBusInterfaceInfo. A #GDBusInterfaceInfo. Do not free. An exported D-Bus interface. Gets the #GDBusObject that @interface_ belongs to, if any. It is not safe to use the returned object if @interface_ or the returned object is being used from other threads. See g_dbus_interface_dup_object() for a thread-safe alternative. A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed. An exported D-Bus interface Sets the #GDBusObject for @interface_ to @object. Note that @interface_ will hold a weak reference to @object. An exported D-Bus interface. A #GDBusObject or %NULL. Gets the #GDBusObject that @interface_ belongs to, if any. A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref(). An exported D-Bus interface. Gets D-Bus introspection information for the D-Bus interface implemented by @interface_. This can return %NULL if no #GDBusInterfaceInfo was provided during construction of @interface_ and is also not made available otherwise. For example, #GDBusProxy implements #GDBusInterface but allows for a %NULL #GDBusInterfaceInfo. A #GDBusInterfaceInfo. Do not free. An exported D-Bus interface. Gets the #GDBusObject that @interface_ belongs to, if any. It is not safe to use the returned object if @interface_ or the returned object is being used from other threads. See g_dbus_interface_dup_object() for a thread-safe alternative. A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed. An exported D-Bus interface Sets the #GDBusObject for @interface_ to @object. Note that @interface_ will hold a weak reference to @object. An exported D-Bus interface. A #GDBusObject or %NULL. The type of the @get_property function in #GDBusInterfaceVTable. A #GVariant with the value for @property_name or %NULL if @error is set. If the returned #GVariant is floating, it is consumed - otherwise its reference count is decreased by one. A #GDBusConnection. The unique bus name of the remote caller or %NULL if not specified by the caller, e.g. on peer-to-peer connections. The object path that the method was invoked on. The D-Bus interface name for the property. The name of the property to get the value of. Return location for error. The @user_data #gpointer passed to g_dbus_connection_register_object(). Base type for D-Bus interfaces. The parent interface. Returns a #GDBusInterfaceInfo. See g_dbus_interface_get_info(). A #GDBusInterfaceInfo. Do not free. An exported D-Bus interface. Gets the enclosing #GDBusObject. See g_dbus_interface_get_object(). A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed. An exported D-Bus interface Sets the enclosing #GDBusObject. See g_dbus_interface_set_object(). An exported D-Bus interface. A #GDBusObject or %NULL. Gets a reference to the enclosing #GDBusObject. See g_dbus_interface_dup_object(). Added in 2.32. A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref(). An exported D-Bus interface. Information about a D-Bus interface. The reference count or -1 if statically allocated. The name of the D-Bus interface, e.g. "org.freedesktop.DBus.Properties". A pointer to a %NULL-terminated array of pointers to #GDBusMethodInfo structures or %NULL if there are no methods. A pointer to a %NULL-terminated array of pointers to #GDBusSignalInfo structures or %NULL if there are no signals. A pointer to a %NULL-terminated array of pointers to #GDBusPropertyInfo structures or %NULL if there are no properties. A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. Builds a lookup-cache to speed up g_dbus_interface_info_lookup_method(), g_dbus_interface_info_lookup_signal() and g_dbus_interface_info_lookup_property(). If this has already been called with @info, the existing cache is used and its use count is increased. Note that @info cannot be modified until g_dbus_interface_info_cache_release() is called. A #GDBusInterfaceInfo. Decrements the usage count for the cache for @info built by g_dbus_interface_info_cache_build() (if any) and frees the resources used by the cache if the usage count drops to zero. A GDBusInterfaceInfo Appends an XML representation of @info (and its children) to @string_builder. This function is typically used for generating introspection XML documents at run-time for handling the `org.freedesktop.DBus.Introspectable.Introspect` method. A #GDBusNodeInfo Indentation level. A #GString to to append XML data to. Looks up information about a method. The cost of this function is O(n) in number of methods unless g_dbus_interface_info_cache_build() has been used on @info. A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info. A #GDBusInterfaceInfo. A D-Bus method name (typically in CamelCase) Looks up information about a property. The cost of this function is O(n) in number of properties unless g_dbus_interface_info_cache_build() has been used on @info. A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. A #GDBusInterfaceInfo. A D-Bus property name (typically in CamelCase). Looks up information about a signal. The cost of this function is O(n) in number of signals unless g_dbus_interface_info_cache_build() has been used on @info. A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info. A #GDBusInterfaceInfo. A D-Bus signal name (typically in CamelCase) If @info is statically allocated does nothing. Otherwise increases the reference count. The same @info. A #GDBusInterfaceInfo If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. A #GDBusInterfaceInfo. The type of the @method_call function in #GDBusInterfaceVTable. @interface_name may be `NULL` if not specified by the sender, although it’s encouraged for the sender to set it. If unset, and the object has only one method (across all interfaces) matching @method_name, that method is invoked. Otherwise, behaviour is implementation defined. See the [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-types-method). It is recommended to return [error@Gio.DBusError.UNKNOWN_METHOD]. A #GDBusConnection. The unique bus name of the remote caller, or `NULL` if not specified by the caller, e.g. on peer-to-peer connections. The object path that the method was invoked on. The D-Bus interface name the method was invoked on, or `NULL` if not specified by the sender. The name of the method that was invoked. A #GVariant tuple with parameters. A #GDBusMethodInvocation object that must be used to return a value or error. The @user_data #gpointer passed to g_dbus_connection_register_object(). The type of the @set_property function in #GDBusInterfaceVTable. %TRUE if the property was set to @value, %FALSE if @error is set. A #GDBusConnection. The unique bus name of the remote caller or %NULL if not specified by the caller, e.g. on peer-to-peer connections. The object path that the method was invoked on. The D-Bus interface name for the property. The name of the property to get the value of. The value to set the property to. Return location for error. The @user_data #gpointer passed to g_dbus_connection_register_object(). Abstract base class for D-Bus interfaces on the service side. If @interface_ has outstanding changes, request for these changes to be emitted immediately. For example, an exported D-Bus interface may queue up property changes and emit the `org.freedesktop.DBus.Properties.PropertiesChanged` signal later (e.g. in an idle handler). This technique is useful for collapsing multiple property changes into one. A #GDBusInterfaceSkeleton. Signal class handler for the #GDBusInterfaceSkeleton::g-authorize-method signal. Gets D-Bus introspection information for the D-Bus interface implemented by @interface_. A #GDBusInterfaceInfo (never %NULL). Do not free. A #GDBusInterfaceSkeleton. Gets all D-Bus properties for @interface_. A #GVariant of type ['a{sv}'](../glib/gvariant-text-format.html#dictionaries-and-dictionary-entries). Free with g_variant_unref(). A #GDBusInterfaceSkeleton. Gets the interface vtable for the D-Bus interface implemented by @interface_. The returned function pointers should expect @interface_ itself to be passed as @user_data. the vtable of the D-Bus interface implemented by the skeleton A #GDBusInterfaceSkeleton. Dispatches a method invocation. (Since: 2.88) Exports @interface_ at @object_path on @connection. This can be called multiple times to export the same @interface_ onto multiple connections however the @object_path provided must be the same for all connections. Use g_dbus_interface_skeleton_unexport() to unexport the object. %TRUE if the interface was exported on @connection, otherwise %FALSE with @error set. The D-Bus interface to export. A #GDBusConnection to export @interface_ on. The path to export the interface at. If @interface_ has outstanding changes, request for these changes to be emitted immediately. For example, an exported D-Bus interface may queue up property changes and emit the `org.freedesktop.DBus.Properties.PropertiesChanged` signal later (e.g. in an idle handler). This technique is useful for collapsing multiple property changes into one. A #GDBusInterfaceSkeleton. Gets the first connection that @interface_ is exported on, if any. A #GDBusConnection or %NULL if @interface_ is not exported anywhere. Do not free, the object belongs to @interface_. A #GDBusInterfaceSkeleton. Gets a list of the connections that @interface_ is exported on. A list of all the connections that @interface_ is exported on. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref(). A #GDBusInterfaceSkeleton. Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior of @interface_ One or more flags from the #GDBusInterfaceSkeletonFlags enumeration. A #GDBusInterfaceSkeleton. Gets D-Bus introspection information for the D-Bus interface implemented by @interface_. A #GDBusInterfaceInfo (never %NULL). Do not free. A #GDBusInterfaceSkeleton. Gets the object path that @interface_ is exported on, if any. A string owned by @interface_ or %NULL if @interface_ is not exported anywhere. Do not free, the string belongs to @interface_. A #GDBusInterfaceSkeleton. Gets all D-Bus properties for @interface_. A #GVariant of type ['a{sv}'](../glib/gvariant-text-format.html#dictionaries-and-dictionary-entries). Free with g_variant_unref(). A #GDBusInterfaceSkeleton. Gets the interface vtable for the D-Bus interface implemented by @interface_. The returned function pointers should expect @interface_ itself to be passed as @user_data. the vtable of the D-Bus interface implemented by the skeleton A #GDBusInterfaceSkeleton. Checks if @interface_ is exported on @connection. %TRUE if @interface_ is exported on @connection, %FALSE otherwise. A #GDBusInterfaceSkeleton. A #GDBusConnection. Sets flags describing what the behavior of @skeleton should be. A #GDBusInterfaceSkeleton. Flags from the #GDBusInterfaceSkeletonFlags enumeration. Stops exporting @interface_ on all connections it is exported on. To unexport @interface_ from only a single connection, use g_dbus_interface_skeleton_unexport_from_connection() A #GDBusInterfaceSkeleton. Stops exporting @interface_ on @connection. To stop exporting on all connections the interface is exported on, use g_dbus_interface_skeleton_unexport(). A #GDBusInterfaceSkeleton. A #GDBusConnection. Flags from the #GDBusInterfaceSkeletonFlags enumeration. Emitted when a method is invoked by a remote caller and used to determine if the method call is authorized. Note that this signal is emitted in a thread dedicated to handling the method call so handlers are allowed to perform blocking IO. This means that it is appropriate to call e.g. [polkit_authority_check_authorization_sync()](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync) with the [POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS) flag set. If %FALSE is returned then no further handlers are run and the signal handler must take a reference to @invocation and finish handling the call (e.g. return an error via g_dbus_method_invocation_return_error()). Otherwise, if %TRUE is returned, signal emission continues. If no handlers return %FALSE, then the method is dispatched. If @interface has an enclosing #GDBusObjectSkeleton, then the #GDBusObjectSkeleton::authorize-method signal handlers run before the handlers for this signal. The default class handler just returns %TRUE. Please note that the common case is optimized: if no signals handlers are connected and the default class handler isn't overridden (for both @interface and the enclosing #GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does not have the %G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD flags set, no dedicated thread is ever used and the call will be handled in the same thread as the object that @interface belongs to was exported in. %TRUE if the call is authorized, %FALSE otherwise. A #GDBusMethodInvocation. Class structure for #GDBusInterfaceSkeleton. The parent class. Returns a #GDBusInterfaceInfo. See g_dbus_interface_skeleton_get_info() for details. A #GDBusInterfaceInfo (never %NULL). Do not free. A #GDBusInterfaceSkeleton. Returns a #GDBusInterfaceVTable. See g_dbus_interface_skeleton_get_vtable() for details. the vtable of the D-Bus interface implemented by the skeleton A #GDBusInterfaceSkeleton. Returns a #GVariant with all properties. See g_dbus_interface_skeleton_get_properties(). A #GVariant of type ['a{sv}'](../glib/gvariant-text-format.html#dictionaries-and-dictionary-entries). Free with g_variant_unref(). A #GDBusInterfaceSkeleton. Emits outstanding changes, if any. See g_dbus_interface_skeleton_flush(). A #GDBusInterfaceSkeleton. Dispatches a method invocation. (Since: 2.88) Signal class handler for the #GDBusInterfaceSkeleton::g-authorize-method signal. Flags describing the behavior of a #GDBusInterfaceSkeleton instance. No flags set. Each method invocation is handled in a thread dedicated to the invocation. This means that the method implementation can use blocking IO without blocking any other part of the process. It also means that the method implementation must use locking to access data structures used by other threads. Virtual table for handling properties and method calls for a D-Bus interface. Since 2.38, if you want to handle getting/setting D-Bus properties asynchronously, give %NULL as your get_property() or set_property() function. The D-Bus call will be directed to your @method_call function, with the provided @interface_name set to "org.freedesktop.DBus.Properties". Ownership of the #GDBusMethodInvocation object passed to the method_call() function is transferred to your handler; you must call one of the methods of #GDBusMethodInvocation to return a reply (possibly empty), or an error. These functions also take ownership of the passed-in invocation object, so unless the invocation object has otherwise been referenced, it will be then be freed. Calling one of these functions may be done within your method_call() implementation but it also can be done at a later point to handle the method asynchronously. The usual checks on the validity of the calls is performed. For `Get` calls, an error is automatically returned if the property does not exist or the permissions do not allow access. The same checks are performed for `Set` calls, and the provided value is also checked for being the correct type. For both `Get` and `Set` calls, the #GDBusMethodInvocation passed to the @method_call handler can be queried with g_dbus_method_invocation_get_property_info() to get a pointer to the #GDBusPropertyInfo of the property. If you have readable properties specified in your interface info, you must ensure that you either provide a non-%NULL @get_property() function or provide implementations of both the `Get` and `GetAll` methods on org.freedesktop.DBus.Properties interface in your @method_call function. Note that the required return type of the `Get` call is `(v)`, not the type of the property. `GetAll` expects a return value of type `a{sv}`. If you have writable properties specified in your interface info, you must ensure that you either provide a non-%NULL @set_property() function or provide an implementation of the `Set` call. If implementing the call, you must return the value of type %G_VARIANT_TYPE_UNIT. Function for handling incoming method calls. Function for getting a property. Function for setting a property. `GDBusMenuModel` is an implementation of [class@Gio.MenuModel] that can be used as a proxy for a menu model that is exported over D-Bus with [method@Gio.DBusConnection.export_menu_model]. Obtains a #GDBusMenuModel for the menu model which is exported at the given @bus_name and @object_path. The thread default main context is taken at the time of this call. All signals on the menu model (and any linked models) are reported with respect to this context. All calls on the returned menu model (and linked models) must also originate from this same context, with the thread default main context unchanged. a #GDBusMenuModel object. Free with g_object_unref(). a #GDBusConnection the bus name which exports the menu model or %NULL if @connection is not a message bus connection the object path at which the menu model is exported A type for representing D-Bus messages that can be sent or received on a [class@Gio.DBusConnection]. Creates a new empty #GDBusMessage. A #GDBusMessage. Free with g_object_unref(). Creates a new #GDBusMessage from the data stored at @blob. The byte order that the message was in can be retrieved using g_dbus_message_get_byte_order(). If the @blob cannot be parsed, contains invalid fields, or contains invalid headers, %G_IO_ERROR_INVALID_ARGUMENT will be returned. A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref(). A blob representing a binary D-Bus message. The length of @blob. A #GDBusCapabilityFlags describing what protocol features are supported. Creates a new #GDBusMessage for a method call. A #GDBusMessage. Free with g_object_unref(). A valid D-Bus name or %NULL. A valid object path. A valid D-Bus interface name or %NULL. A valid method name. Creates a new #GDBusMessage for a signal emission. A #GDBusMessage. Free with g_object_unref(). A valid object path. A valid D-Bus interface name. A valid signal name. Utility function to calculate how many bytes are needed to completely deserialize the D-Bus message stored at @blob. Number of bytes needed or -1 if @error is set (e.g. if @blob contains invalid data or not enough data is available to determine the size). A blob representing a binary D-Bus message. The length of @blob (must be at least 16). Copies @message. The copy is a deep copy and the returned #GDBusMessage is completely identical except that it is guaranteed to not be locked. This operation can fail if e.g. @message contains file descriptors and the per-process or system-wide open files limit is reached. A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref(). A #GDBusMessage. Convenience to get the first item in the body of @message. See [method@Gio.DBusMessage.get_arg0_path] for returning object-path-typed arg0 values. The string item or %NULL if the first item in the body of @message is not a string. A #GDBusMessage. Convenience to get the first item in the body of @message. See [method@Gio.DBusMessage.get_arg0] for returning string-typed arg0 values. The object path item or `NULL` if the first item in the body of @message is not an object path. A `GDBusMessage`. Gets the body of a message. A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message. A #GDBusMessage. Gets the byte order of @message. The byte order. A #GDBusMessage. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. The value. A #GDBusMessage. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. The value. A #GDBusMessage. Gets the flags for @message. Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). A #GDBusMessage. Gets a header field on @message. The caller is responsible for checking the type of the returned #GVariant matches what is expected. A #GVariant with the value if the header was found, %NULL otherwise. Do not free, it is owned by @message. A #GDBusMessage. A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) Gets an array of all header fields on @message that are set. An array of header fields terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a #guchar. Free with g_free(). A #GDBusMessage. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. The value. A #GDBusMessage. Checks whether @message is locked. To monitor changes to this value, connect to the #GObject::notify signal to listen for changes on the #GDBusMessage:locked property. %TRUE if @message is locked, %FALSE otherwise. A #GDBusMessage. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. The value. A #GDBusMessage. Gets the type of @message. A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). A #GDBusMessage. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. The value. A #GDBusMessage. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. The value. A #GDBusMessage. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. The value. A #GDBusMessage. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. The value. A #GDBusMessage. Gets the serial for @message. A #guint32. A #GDBusMessage. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. This will always be non-%NULL, but may be an empty string. The value. A #GDBusMessage. Gets the UNIX file descriptors associated with @message, if any. This method is only available on UNIX. The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE values in the body of the message. For example, if g_variant_get_handle() returns 5, that is intended to be a reference to the file descriptor that can be accessed by `g_unix_fd_list_get (list, 5, ...)`. A #GUnixFDList or %NULL if no file descriptors are associated. Do not free, this object is owned by @message. A #GDBusMessage. If @message is locked, does nothing. Otherwise locks the message. A #GDBusMessage. Creates a new #GDBusMessage that is an error reply to @method_call_message. A #GDBusMessage. Free with g_object_unref(). A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. A valid D-Bus error name. The D-Bus error message in a printf() format. Arguments for @error_message_format. Creates a new #GDBusMessage that is an error reply to @method_call_message. A #GDBusMessage. Free with g_object_unref(). A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. A valid D-Bus error name. The D-Bus error message. Like g_dbus_message_new_method_error() but intended for language bindings. A #GDBusMessage. Free with g_object_unref(). A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. A valid D-Bus error name. The D-Bus error message in a printf() format. Arguments for @error_message_format. Creates a new #GDBusMessage that is a reply to @method_call_message. #GDBusMessage. Free with g_object_unref(). A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. Produces a human-readable multi-line description of @message. The contents of the description has no ABI guarantees, the contents and formatting is subject to change at any time. Typical output looks something like this: ``` Flags: none Version: 0 Serial: 4 Headers: path -> objectpath '/org/gtk/GDBus/TestObject' interface -> 'org.gtk.GDBus.TestInterface' member -> 'GimmeStdout' destination -> ':1.146' Body: () UNIX File Descriptors: (none) ``` or ``` Flags: no-reply-expected Version: 0 Serial: 477 Headers: reply-serial -> uint32 4 destination -> ':1.159' sender -> ':1.146' num-unix-fds -> uint32 1 Body: () UNIX File Descriptors: fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635 ``` A string that should be freed with [func@GLib.free]. A #GDBusMessage. Indentation level. Sets the body @message. As a side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the type string of @body (or cleared if @body is %NULL). If @body is floating, @message assumes ownership of @body. A #GDBusMessage. Either %NULL or a #GVariant that is a tuple. Sets the byte order of @message. A #GDBusMessage. The byte order. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. A #GDBusMessage. The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. A #GDBusMessage. The value to set. Sets the flags to set on @message. A #GDBusMessage. Flags for @message that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). Sets a header field on @message. If @value is floating, @message assumes ownership of @value. A #GDBusMessage. A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) A #GVariant to set the header field or %NULL to clear the header field. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. A #GDBusMessage. The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. A #GDBusMessage. The value to set. Sets @message to be of @type. A #GDBusMessage. A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. A #GDBusMessage. The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. A #GDBusMessage. The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. A #GDBusMessage. The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. A #GDBusMessage. The value to set. Sets the serial for @message. The [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-messages) does not allow the @serial to be zero. A #GDBusMessage. A #guint32, which must not be zero. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. A #GDBusMessage. The value to set. Sets the UNIX file descriptors associated with @message. As a side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field is set to the number of fds in @fd_list (or cleared if @fd_list is %NULL). This method is only available on UNIX. When designing D-Bus APIs that are intended to be interoperable, please note that non-GDBus implementations of D-Bus can usually only access file descriptors if they are referenced by a value of type %G_VARIANT_TYPE_HANDLE in the body of the message. A #GDBusMessage. A #GUnixFDList or %NULL. Serializes @message to a blob. The byte order returned by g_dbus_message_get_byte_order() will be used. A pointer to a valid binary D-Bus message of @out_size bytes generated by @message or %NULL if @error is set. Free with g_free(). A #GDBusMessage. Return location for size of generated blob. A #GDBusCapabilityFlags describing what protocol features are supported. If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does nothing and returns %FALSE. Otherwise this method encodes the error in @message as a #GError using g_dbus_error_set_dbus_error() using the information in the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as well as the first string item in @message's body. %TRUE if @error was set, %FALSE otherwise. A #GDBusMessage. Enumeration used to describe the byte order of a D-Bus message. The byte order is big endian. The byte order is little endian. Signature for function used in g_dbus_connection_add_filter(). A filter function is passed a #GDBusMessage and expected to return a #GDBusMessage too. Passive filter functions that don't modify the message can simply return the @message object: |[ static GDBusMessage * passive_filter (GDBusConnection *connection GDBusMessage *message, gboolean incoming, gpointer user_data) { // inspect @message return message; } ]| Filter functions that wants to drop a message can simply return %NULL: |[ static GDBusMessage * drop_filter (GDBusConnection *connection GDBusMessage *message, gboolean incoming, gpointer user_data) { if (should_drop_message) { g_object_unref (message); message = NULL; } return message; } ]| Finally, a filter function may modify a message by copying it: |[ static GDBusMessage * modifying_filter (GDBusConnection *connection GDBusMessage *message, gboolean incoming, gpointer user_data) { GDBusMessage *copy; GError *error; error = NULL; copy = g_dbus_message_copy (message, &error); // handle @error being set g_object_unref (message); // modify @copy return copy; } ]| If the returned #GDBusMessage is different from @message and cannot be sent on @connection (it could use features, such as file descriptors, not compatible with @connection), then a warning is logged to standard error. Applications can check this ahead of time using g_dbus_message_to_blob() passing a #GDBusCapabilityFlags value obtained from @connection. A #GDBusMessage that will be freed with g_object_unref() or %NULL to drop the message. Passive filter functions can simply return the passed @message object. A #GDBusConnection. A locked #GDBusMessage that the filter function takes ownership of. %TRUE if it is a message received from the other peer, %FALSE if it is a message to be sent to the other peer. User data passed when adding the filter. Message flags used in #GDBusMessage. No flags set. A reply is not expected. The bus must not launch an owner for the destination name in response to this message. If set on a method call, this flag means that the caller is prepared to wait for interactive authorization. Since 2.46. Header fields used in #GDBusMessage. Not a valid header field. The object path. The interface name. The method or signal name. The name of the error that occurred. The serial number the message is a reply to. The name the message is intended for. Unique name of the sender of the message (filled in by the bus). The signature of the message body. The number of UNIX file descriptors that accompany the message. Message types used in #GDBusMessage. Message is of invalid type. Method call. Method reply. Error reply. Signal emission. Information about a method on a D-Bus interface. The reference count or -1 if statically allocated. The name of the D-Bus method, e.g. @RequestName. A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no in arguments. A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no out arguments. A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. If @info is statically allocated does nothing. Otherwise increases the reference count. The same @info. A #GDBusMethodInfo If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. A #GDBusMethodInfo. Instances of the `GDBusMethodInvocation` class are used when handling D-Bus method calls. It provides a way to asynchronously return results and errors. The normal way to obtain a `GDBusMethodInvocation` object is to receive it as an argument to the `handle_method_call()` function in a [type@Gio.DBusInterfaceVTable] that was passed to [method@Gio.DBusConnection.register_object]. Gets the #GDBusConnection the method was invoked on. A #GDBusConnection. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. Gets the name of the D-Bus interface the method was invoked on. This can be `NULL` if it was not specified by the sender. See [callback@Gio.DBusInterfaceMethodCallFunc] or the [D-Bus Specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-types-method) for details on when this can happen and how it should be handled. If this method call is a property Get, Set or GetAll call that has been redirected to the method call handler then "org.freedesktop.DBus.Properties" will be returned. See #GDBusInterfaceVTable for more information. A string. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. Gets the #GDBusMessage for the method invocation. This is useful if you need to use low-level protocol features, such as UNIX file descriptor passing, that cannot be properly expressed in the #GVariant API. See this [server][class@Gio.DBusConnection#an-example-d-bus-server] and [client][class@Gio.DBusConnection#an-example-for-file-descriptor-passing] for an example of how to use this low-level API to send and receive UNIX file descriptors. #GDBusMessage. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. Gets information about the method call, if any. If this method invocation is a property Get, Set or GetAll call that has been redirected to the method call handler then %NULL will be returned. See g_dbus_method_invocation_get_property_info() and #GDBusInterfaceVTable for more information. A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. Gets the name of the method that was invoked. A string. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. Gets the object path the method was invoked on. A string. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. Gets the parameters of the method invocation. If there are no input parameters then this will return a GVariant with 0 children rather than NULL. A #GVariant tuple. Do not unref this because it is owned by @invocation. A #GDBusMethodInvocation. Gets information about the property that this method call is for, if any. This will only be set in the case of an invocation in response to a property Get or Set call that has been directed to the method call handler for an object on account of its property_get() or property_set() vtable pointers being unset. See #GDBusInterfaceVTable for more information. If the call was GetAll, %NULL will be returned. a #GDBusPropertyInfo or %NULL A #GDBusMethodInvocation Gets the bus name that invoked the method. This can return %NULL if not specified by the caller, e.g. on peer-to-peer connections. A string. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. Gets the @user_data #gpointer passed to g_dbus_connection_register_object(). A #gpointer. A #GDBusMethodInvocation. Finishes handling a D-Bus method call by returning an error. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. A #GDBusMethodInvocation. A valid D-Bus error name. A valid D-Bus error message. Finishes handling a D-Bus method call by returning an error. See g_dbus_error_encode_gerror() for details about what error name will be returned on the wire. In a nutshell, if the given error is registered using g_dbus_error_register_error() the name given during registration is used. Otherwise, a name of the form `org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides transparent mapping of #GError between applications using GDBus. If you are writing an application intended to be portable, always register errors with g_dbus_error_register_error() or use g_dbus_method_invocation_return_dbus_error(). This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. Since 2.48, if the method call requested for a reply not to be sent then this call will free @invocation but otherwise do nothing (as per the recommendations of the D-Bus specification). A #GDBusMethodInvocation. A #GQuark for the #GError error domain. The error code. printf()-style format. Parameters for @format. Like g_dbus_method_invocation_return_error() but without printf()-style formatting. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. A #GDBusMethodInvocation. A #GQuark for the #GError error domain. The error code. The error message. Like g_dbus_method_invocation_return_error() but intended for language bindings. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. A #GDBusMethodInvocation. A #GQuark for the #GError error domain. The error code. printf()-style format. #va_list of parameters for @format. Like g_dbus_method_invocation_return_error() but takes a #GError instead of the error domain, error code and message. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. A #GDBusMethodInvocation. A #GError. Finishes handling a D-Bus method call by returning @parameters. If the @parameters GVariant is floating, it is consumed. It is an error if @parameters is not of the right format: it must be a tuple containing the out-parameters of the D-Bus method. Even if the method has a single out-parameter, it must be contained in a tuple. If the method has no out-parameters, @parameters may be %NULL or an empty tuple. |[<!-- language="C" --> GDBusMethodInvocation *invocation = some_invocation; g_autofree gchar *result_string = NULL; g_autoptr (GError) error = NULL; result_string = calculate_result (&error); if (error != NULL) g_dbus_method_invocation_return_gerror (invocation, error); else g_dbus_method_invocation_return_value (invocation, g_variant_new ("(s)", result_string)); // Do not free @invocation here; returning a value does that ]| This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. Since 2.48, if the method call requested for a reply not to be sent then this call will sink @parameters and free @invocation, but otherwise do nothing (as per the recommendations of the D-Bus specification). A #GDBusMethodInvocation. A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList. This method is only available on UNIX. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. A #GDBusMethodInvocation. A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. A #GUnixFDList or %NULL. Like g_dbus_method_invocation_return_gerror() but takes ownership of @error so the caller does not need to free it. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. A #GDBusMethodInvocation. A #GError. Information about nodes in a remote object hierarchy. The reference count or -1 if statically allocated. The path of the node or %NULL if omitted. Note that this may be a relative path. See the D-Bus specification for more details. A pointer to a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures or %NULL if there are no interfaces. A pointer to a %NULL-terminated array of pointers to #GDBusNodeInfo structures or %NULL if there are no nodes. A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. Parses @xml_data and returns a #GDBusNodeInfo representing the data. The introspection XML must contain exactly one top-level `<node>` element. Note that this routine is using a [GMarkup](../glib/markup.html)-based parser that only accepts a subset of valid XML documents. A #GDBusNodeInfo structure or %NULL if @error is set. Free with g_dbus_node_info_unref(). Valid D-Bus introspection XML. Appends an XML representation of @info (and its children) to @string_builder. This function is typically used for generating introspection XML documents at run-time for handling the `org.freedesktop.DBus.Introspectable.Introspect` method. A #GDBusNodeInfo. Indentation level. A #GString to to append XML data to. Looks up information about an interface. The cost of this function is O(n) in number of interfaces. A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. A #GDBusNodeInfo. A D-Bus interface name. If @info is statically allocated does nothing. Otherwise increases the reference count. The same @info. A #GDBusNodeInfo If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. A #GDBusNodeInfo. The `GDBusObject` type is the base type for D-Bus objects on both the service side (see [class@Gio.DBusObjectSkeleton]) and the client side (see [class@Gio.DBusObjectProxy]). It is essentially just a container of interfaces. Gets the D-Bus interface with name @interface_name associated with @object, if any. %NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref(). A #GDBusObject. A D-Bus interface name. Gets the D-Bus interfaces associated with @object. A list of #GDBusInterface instances. The returned list must be freed by g_list_free() after each element has been freed with g_object_unref(). A #GDBusObject. Gets the object path for @object. A string owned by @object. Do not free. A #GDBusObject. Signal handler for the #GDBusObject::interface-added signal. Signal handler for the #GDBusObject::interface-removed signal. Gets the D-Bus interface with name @interface_name associated with @object, if any. %NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref(). A #GDBusObject. A D-Bus interface name. Gets the D-Bus interfaces associated with @object. A list of #GDBusInterface instances. The returned list must be freed by g_list_free() after each element has been freed with g_object_unref(). A #GDBusObject. Gets the object path for @object. A string owned by @object. Do not free. A #GDBusObject. Emitted when @interface is added to @object. The #GDBusInterface that was added. Emitted when @interface is removed from @object. The #GDBusInterface that was removed. Base object type for D-Bus objects. The parent interface. Returns the object path. See g_dbus_object_get_object_path(). A string owned by @object. Do not free. A #GDBusObject. Returns all interfaces. See g_dbus_object_get_interfaces(). A list of #GDBusInterface instances. The returned list must be freed by g_list_free() after each element has been freed with g_object_unref(). A #GDBusObject. Returns an interface by name. See g_dbus_object_get_interface(). %NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref(). A #GDBusObject. A D-Bus interface name. Signal handler for the #GDBusObject::interface-added signal. Signal handler for the #GDBusObject::interface-removed signal. The `GDBusObjectManager` type is the base type for service- and client-side implementations of the standardized [`org.freedesktop.DBus.ObjectManager`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) interface. See [class@Gio.DBusObjectManagerClient] for the client-side implementation and [class@Gio.DBusObjectManagerServer] for the service-side implementation. Gets the interface proxy for @interface_name at @object_path, if any. A #GDBusInterface instance or %NULL. Free with g_object_unref(). A #GDBusObjectManager. Object path to look up. D-Bus interface name to look up. Gets the #GDBusObject at @object_path, if any. A #GDBusObject or %NULL. Free with g_object_unref(). A #GDBusObjectManager. Object path to look up. Gets the object path that @manager is for. A string owned by @manager. Do not free. A #GDBusObjectManager. Gets all #GDBusObject objects known to @manager. A list of #GDBusObject objects. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref(). A #GDBusObjectManager. Signal handler for the #GDBusObjectManager::interface-added signal. Signal handler for the #GDBusObjectManager::interface-removed signal. Signal handler for the #GDBusObjectManager::object-added signal. Signal handler for the #GDBusObjectManager::object-removed signal. Gets the interface proxy for @interface_name at @object_path, if any. A #GDBusInterface instance or %NULL. Free with g_object_unref(). A #GDBusObjectManager. Object path to look up. D-Bus interface name to look up. Gets the #GDBusObject at @object_path, if any. A #GDBusObject or %NULL. Free with g_object_unref(). A #GDBusObjectManager. Object path to look up. Gets the object path that @manager is for. A string owned by @manager. Do not free. A #GDBusObjectManager. Gets all #GDBusObject objects known to @manager. A list of #GDBusObject objects. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref(). A #GDBusObjectManager. Emitted when @interface is added to @object. This signal exists purely as a convenience to avoid having to connect signals to all objects managed by @manager. The #GDBusObject on which an interface was added. The #GDBusInterface that was added. Emitted when @interface has been removed from @object. This signal exists purely as a convenience to avoid having to connect signals to all objects managed by @manager. The #GDBusObject on which an interface was removed. The #GDBusInterface that was removed. Emitted when @object is added to @manager. The #GDBusObject that was added. Emitted when @object is removed from @manager. The #GDBusObject that was removed. `GDBusObjectManagerClient` is used to create, monitor and delete object proxies for remote objects exported by a [class@Gio.DBusObjectManagerServer] (or any code implementing the [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) interface). Once an instance of this type has been created, you can connect to the [signal@Gio.DBusObjectManager::object-added] and [signal@Gio.DBusObjectManager::object-removed signals] and inspect the [class@Gio.DBusObjectProxy] objects returned by [method@Gio.DBusObjectManager.get_objects]. If the name for a `GDBusObjectManagerClient` is not owned by anyone at object construction time, the default behavior is to request the message bus to launch an owner for the name. This behavior can be disabled using the `G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START` flag. It’s also worth noting that this only works if the name of interest is activatable in the first place. E.g. in some cases it is not possible to launch an owner for the requested name. In this case, `GDBusObjectManagerClient` object construction still succeeds but there will be no object proxies (e.g. [method@Gio.DBusObjectManager.get_objects] returns the empty list) and the [property@Gio.DBusObjectManagerClient:name-owner] property is `NULL`. The owner of the requested name can come and go (for example consider a system service being restarted) – `GDBusObjectManagerClient` handles this case too; simply connect to the [signal@GObject.Object::notify] signal to watch for changes on the [property@Gio.DBusObjectManagerClient:name-owner] property. When the name owner vanishes, the behavior is that [property@Gio.DBusObjectManagerClient:name-owner] is set to `NULL` (this includes emission of the [signal@GObject.Object::notify] signal) and then [signal@Gio.DBusObjectManager::object-removed] signals are synthesized for all currently existing object proxies. Since [property@Gio.DBusObjectManagerClient:name-owner] is `NULL` when this happens, you can use this information to disambiguate a synthesized signal from a genuine signal caused by object removal on the remote [iface@Gio.DBusObjectManager]. Similarly, when a new name owner appears, [signal@Gio.DBusObjectManager::object-added] signals are synthesized while [property@Gio.DBusObjectManagerClient:name-owner] is still `NULL`. Only when all object proxies have been added, the [property@Gio.DBusObjectManagerClient:name-owner] is set to the new name owner (this includes emission of the [signal@GObject.Object::notify] signal). Furthermore, you are guaranteed that [property@Gio.DBusObjectManagerClient:name-owner] will alternate between a name owner (e.g. `:1.42`) and `NULL` even in the case where the name of interest is atomically replaced Ultimately, `GDBusObjectManagerClient` is used to obtain [class@Gio.DBusProxy] instances. All signals (including the `org.freedesktop.DBus.Properties::PropertiesChanged` signal) delivered to [class@Gio.DBusProxy] instances are guaranteed to originate from the name owner. This guarantee along with the behavior described above, means that certain race conditions including the “half the proxy is from the old owner and the other half is from the new owner” problem cannot happen. To avoid having the application connect to signals on the returned [class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects, the [signal@Gio.DBusObject::interface-added], [signal@Gio.DBusObject::interface-removed], [signal@Gio.DBusProxy::g-properties-changed] and [signal@Gio.DBusProxy::g-signal] signals are also emitted on the `GDBusObjectManagerClient` instance managing these objects. The signals emitted are [signal@Gio.DBusObjectManager::interface-added], [signal@Gio.DBusObjectManager::interface-removed], [signal@Gio.DBusObjectManagerClient::interface-proxy-properties-changed] and [signal@Gio.DBusObjectManagerClient::interface-proxy-signal]. Note that all callbacks and signals are emitted in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) that the `GDBusObjectManagerClient` object was constructed in. Additionally, the [class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects originating from the `GDBusObjectManagerClient` object will be created in the same context and, consequently, will deliver signals in the same main loop. Finishes an operation started with g_dbus_object_manager_client_new(). A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new(). Finishes an operation started with g_dbus_object_manager_client_new_for_bus(). A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus(). Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead of a #GDBusConnection. This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus() for the asynchronous version. A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). A #GBusType. Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. The owner of the control object (unique or well-known name). The object path of the control object. A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. User data to pass to @get_proxy_type_func. Free function for @get_proxy_type_user_data or %NULL. A #GCancellable or %NULL Creates a new #GDBusObjectManagerClient object. This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See g_dbus_object_manager_client_new() for the asynchronous version. A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). A #GDBusConnection. Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection. The object path of the control object. A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. User data to pass to @get_proxy_type_func. Free function for @get_proxy_type_user_data or %NULL. A #GCancellable or %NULL Asynchronously creates a new #GDBusObjectManagerClient object. This is an asynchronous failable constructor. When the result is ready, @callback will be invoked in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. You can then call g_dbus_object_manager_client_new_finish() to get the result. See g_dbus_object_manager_client_new_sync() for the synchronous version. A #GDBusConnection. Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. The owner of the control object (unique or well-known name). The object path of the control object. A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. User data to pass to @get_proxy_type_func. Free function for @get_proxy_type_user_data or %NULL. A #GCancellable or %NULL A #GAsyncReadyCallback to call when the request is satisfied. The data to pass to @callback. Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a #GDBusConnection. This is an asynchronous failable constructor. When the result is ready, @callback will be invoked in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. You can then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version. A #GBusType. Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. The owner of the control object (unique or well-known name). The object path of the control object. A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. User data to pass to @get_proxy_type_func. Free function for @get_proxy_type_user_data or %NULL. A #GCancellable or %NULL A #GAsyncReadyCallback to call when the request is satisfied. The data to pass to @callback. Signal class handler for the #GDBusObjectManagerClient::interface-proxy-properties-changed signal. Signal class handler for the #GDBusObjectManagerClient::interface-proxy-signal signal. Gets the #GDBusConnection used by @manager. A #GDBusConnection object. Do not free, the object belongs to @manager. A #GDBusObjectManagerClient Gets the flags that @manager was constructed with. Zero of more flags from the #GDBusObjectManagerClientFlags enumeration. A #GDBusObjectManagerClient Gets the name that @manager is for, or %NULL if not a message bus connection. A unique or well-known name. Do not free, the string belongs to @manager. A #GDBusObjectManagerClient The unique name that owns the name that @manager is for or %NULL if no-one currently owns that name. You can connect to the #GObject::notify signal to track changes to the #GDBusObjectManagerClient:name-owner property. The name owner or %NULL if no name owner exists. Free with g_free(). A #GDBusObjectManagerClient. If this property is not %G_BUS_TYPE_NONE, then #GDBusObjectManagerClient:connection must be %NULL and will be set to the #GDBusConnection obtained by calling g_bus_get() with the value of this property. The #GDBusConnection to use. Flags from the #GDBusObjectManagerClientFlags enumeration. A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data. The #GDBusProxyTypeFunc to use when determining what #GType to use for interface proxies or %NULL. The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func. The well-known name or unique name that the manager is for. The unique name that owns #GDBusObjectManagerClient:name or %NULL if no-one is currently owning the name. Connect to the #GObject::notify signal to track changes to this property. The object path the manager is for. Emitted when one or more D-Bus properties on proxy changes. The local cache has already been updated when this signal fires. Note that both @changed_properties and @invalidated_properties are guaranteed to never be %NULL (either may be empty though). This signal exists purely as a convenience to avoid having to connect signals to all interface proxies managed by @manager. This signal is emitted in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) that @manager was constructed in. The #GDBusObjectProxy on which an interface has properties that are changing. The #GDBusProxy that has properties that are changing. A #GVariant containing the properties that changed (type: `a{sv}`). A %NULL terminated array of properties that were invalidated. Emitted when a D-Bus signal is received on @interface_proxy. This signal exists purely as a convenience to avoid having to connect signals to all interface proxies managed by @manager. This signal is emitted in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) that @manager was constructed in. The #GDBusObjectProxy on which an interface is emitting a D-Bus signal. The #GDBusProxy that is emitting a D-Bus signal. The sender of the signal or NULL if the connection is not a bus connection. The signal name. A #GVariant tuple with parameters for the signal. Class structure for #GDBusObjectManagerClient. The parent class. Signal class handler for the #GDBusObjectManagerClient::interface-proxy-signal signal. Signal class handler for the #GDBusObjectManagerClient::interface-proxy-properties-changed signal. Flags used when constructing a #GDBusObjectManagerClient. No flags set. If not set and the manager is for a well-known name, then request the bus to launch an owner for the name if no-one owns the name. This flag can only be used in managers for well-known names. Base type for D-Bus object managers. The parent interface. Virtual function for g_dbus_object_manager_get_object_path(). A string owned by @manager. Do not free. A #GDBusObjectManager. Virtual function for g_dbus_object_manager_get_objects(). A list of #GDBusObject objects. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref(). A #GDBusObjectManager. Virtual function for g_dbus_object_manager_get_object(). A #GDBusObject or %NULL. Free with g_object_unref(). A #GDBusObjectManager. Object path to look up. Virtual function for g_dbus_object_manager_get_interface(). A #GDBusInterface instance or %NULL. Free with g_object_unref(). A #GDBusObjectManager. Object path to look up. D-Bus interface name to look up. Signal handler for the #GDBusObjectManager::object-added signal. Signal handler for the #GDBusObjectManager::object-removed signal. Signal handler for the #GDBusObjectManager::interface-added signal. Signal handler for the #GDBusObjectManager::interface-removed signal. `GDBusObjectManagerServer` is used to export [iface@Gio.DBusObject] instances using the standardized [`org.freedesktop.DBus.ObjectManager`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) interface. For example, remote D-Bus clients can get all objects and properties in a single call. Additionally, any change in the object hierarchy is broadcast using signals. This means that D-Bus clients can keep caches up to date by only listening to D-Bus signals. The recommended path to export an object manager at is the path form of the well-known name of a D-Bus service, or below. For example, if a D-Bus service is available at the well-known name `net.example.ExampleService1`, the object manager should typically be exported at `/net/example/ExampleService1`, or below (to allow for multiple object managers in a service). It is supported, but not recommended, to export an object manager at the root path, `/`. See [class@Gio.DBusObjectManagerClient] for the client-side code that is intended to be used with `GDBusObjectManagerServer` or any D-Bus object implementing the `org.freedesktop.DBus.ObjectManager` interface. Creates a new #GDBusObjectManagerServer object. The returned server isn't yet exported on any connection. To do so, use g_dbus_object_manager_server_set_connection(). Normally you want to export all of your objects before doing so to avoid [InterfacesAdded](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) signals being emitted. A #GDBusObjectManagerServer object. Free with g_object_unref(). The object path to export the manager object at. Exports @object on @manager. If there is already a #GDBusObject exported at the object path, then the old object is removed. The object path for @object must be in the hierarchy rooted by the object path for @manager. Note that @manager will take a reference on @object for as long as it is exported. A #GDBusObjectManagerServer. A #GDBusObjectSkeleton. Like g_dbus_object_manager_server_export() but appends a string of the form _N (with N being a natural number) to @object's object path if an object with the given path already exists. As such, the #GDBusObjectProxy:g-object-path property of @object may be modified. A #GDBusObjectManagerServer. An object. Gets the #GDBusConnection used by @manager. A #GDBusConnection object or %NULL if @manager isn't exported on a connection. The returned object should be freed with g_object_unref(). A #GDBusObjectManagerServer Returns whether @object is currently exported on @manager. %TRUE if @object is exported A #GDBusObjectManagerServer. An object. Exports all objects managed by @manager on @connection. If @connection is %NULL, stops exporting objects. A #GDBusObjectManagerServer. A #GDBusConnection or %NULL. If @manager has an object at @path, removes the object. Otherwise does nothing. Note that @object_path must be in the hierarchy rooted by the object path for @manager. %TRUE if object at @object_path was removed, %FALSE otherwise. A #GDBusObjectManagerServer. An object path. The #GDBusConnection to export objects on. The object path to register the manager object at. Class structure for #GDBusObjectManagerServer. The parent class. A `GDBusObjectProxy` is an object used to represent a remote object with one or more D-Bus interfaces. Normally, you don’t instantiate a `GDBusObjectProxy` yourself — typically [class@Gio.DBusObjectManagerClient] is used to obtain it. Creates a new #GDBusObjectProxy for the given connection and object path. a new #GDBusObjectProxy a #GDBusConnection the object path Gets the connection that @proxy is for. A #GDBusConnection. Do not free, the object is owned by @proxy. a #GDBusObjectProxy The connection of the proxy. The object path of the proxy. Class structure for #GDBusObjectProxy. The parent class. A `GDBusObjectSkeleton` instance is essentially a group of D-Bus interfaces. The set of exported interfaces on the object may be dynamic and change at runtime. This type is intended to be used with [iface@Gio.DBusObjectManager]. Creates a new #GDBusObjectSkeleton. A #GDBusObjectSkeleton. Free with g_object_unref(). An object path. Signal class handler for the #GDBusObjectSkeleton::authorize-method signal. Adds @interface_ to @object. If @object already contains a #GDBusInterfaceSkeleton with the same interface name, it is removed before @interface_ is added. Note that @object takes its own reference on @interface_ and holds it until removed. A #GDBusObjectSkeleton. A #GDBusInterfaceSkeleton. This method simply calls g_dbus_interface_skeleton_flush() on all interfaces belonging to @object. See that method for when flushing is useful. A #GDBusObjectSkeleton. Removes @interface_ from @object. A #GDBusObjectSkeleton. A #GDBusInterfaceSkeleton. Removes the #GDBusInterface with @interface_name from @object. If no D-Bus interface of the given interface exists, this function does nothing. A #GDBusObjectSkeleton. A D-Bus interface name. Sets the object path for @object. A #GDBusObjectSkeleton. A valid D-Bus object path. The object path where the object is exported. Emitted when a method is invoked by a remote caller and used to determine if the method call is authorized. This signal is like #GDBusInterfaceSkeleton's #GDBusInterfaceSkeleton::g-authorize-method signal, except that it is for the enclosing object. The default class handler just returns %TRUE. %TRUE if the call is authorized, %FALSE otherwise. The #GDBusInterfaceSkeleton that @invocation is for. A #GDBusMethodInvocation. Class structure for #GDBusObjectSkeleton. The parent class. Signal class handler for the #GDBusObjectSkeleton::authorize-method signal. Information about a D-Bus property on a D-Bus interface. The reference count or -1 if statically allocated. The name of the D-Bus property, e.g. "SupportedFilesystems". The D-Bus signature of the property (a single complete type). Access control flags for the property. A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. If @info is statically allocated does nothing. Otherwise increases the reference count. The same @info. A #GDBusPropertyInfo If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. A #GDBusPropertyInfo. Flags describing the access control of a D-Bus property. No flags set. Property is readable. Property is writable. `GDBusProxy` is a base class used for proxies to access a D-Bus interface on a remote object. A `GDBusProxy` can be constructed for both well-known and unique names. By default, `GDBusProxy` will cache all properties (and listen to changes) of the remote object, and proxy all signals that get emitted. This behaviour can be changed by passing suitable [flags@Gio.DBusProxyFlags] when the proxy is created. If the proxy is for a well-known name, the property cache is flushed when the name owner vanishes and reloaded when a name owner appears. The unique name owner of the proxy’s name is tracked and can be read from [property@Gio.DBusProxy:g-name-owner]. Connect to the [signal@GObject.Object::notify] signal to get notified of changes. Additionally, only signals and property changes emitted from the current name owner are considered and calls are always sent to the current name owner. This avoids a number of race conditions when the name is lost by one owner and claimed by another. However, if no name owner currently exists, then calls will be sent to the well-known name which may result in the message bus launching an owner (unless `G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START` is set). If the proxy is for a stateless D-Bus service, where the name owner may be started and stopped between calls, the [property@Gio.DBusProxy:g-name-owner] tracking of `GDBusProxy` will cause the proxy to drop signal and property changes from the service after it has restarted for the first time. When interacting with a stateless D-Bus service, do not use `GDBusProxy` — use direct D-Bus method calls and signal connections. The generic [signal@Gio.DBusProxy::g-properties-changed] and [signal@Gio.DBusProxy::g-signal] signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass `GDBusProxy`, and have more natural properties and signals in your derived class. This [example](migrating-gdbus.html#using-gdbus-codegen) shows how this can easily be done using the [`gdbus-codegen`](gdbus-codegen.html) tool. A `GDBusProxy` instance can be used from multiple threads but note that all signals (e.g. [signal@Gio.DBusProxy::g-signal], [signal@Gio.DBusProxy::g-properties-changed] and [signal@GObject.Object::notify]) are emitted in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread where the instance was constructed. ## A watch proxy example An example using a proxy for a well-known name can be found in [`gdbus-example-watch-proxy.c`](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-proxy.c). Finishes creating a #GDBusProxy. A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new(). Finishes creating a #GDBusProxy. A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus(). Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. #GDBusProxy is used in this [example][class@Gio.DBusProxy#a-watch-proxy-example]. A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). A #GBusType. Flags used when constructing the proxy. A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. A bus name (well-known or unique). An object path. A D-Bus interface name. A #GCancellable or %NULL. Creates a proxy for accessing @interface_name on the remote object at @object_path owned by @name at @connection and synchronously loads D-Bus properties unless the %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the #GDBusProxy::g-signal signal to handle signals from the remote object. If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to return immediately without blocking. If @name is a well-known name and the %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name. This is a synchronous failable constructor. See g_dbus_proxy_new() and g_dbus_proxy_new_finish() for the asynchronous version. #GDBusProxy is used in this [example][class@Gio.DBusProxy#a-watch-proxy-example]. A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). A #GDBusConnection. Flags used when constructing the proxy. A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. An object path. A D-Bus interface name. A #GCancellable or %NULL. Creates a proxy for accessing @interface_name on the remote object at @object_path owned by @name at @connection and asynchronously loads D-Bus properties unless the %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to the #GDBusProxy::g-properties-changed signal to get notified about property changes. If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the #GDBusProxy::g-signal signal to handle signals from the remote object. If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to complete immediately without blocking. If @name is a well-known name and the %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name. This is a failable asynchronous constructor - when the proxy is ready, @callback will be invoked and you can use g_dbus_proxy_new_finish() to get the result. See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. #GDBusProxy is used in this [example][class@Gio.DBusProxy#a-watch-proxy-example]. A #GDBusConnection. Flags used when constructing the proxy. A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. An object path. A D-Bus interface name. A #GCancellable or %NULL. Callback function to invoke when the proxy is ready. User data to pass to @callback. Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. #GDBusProxy is used in this [example][class@Gio.DBusProxy#a-watch-proxy-example]. A #GBusType. Flags used when constructing the proxy. A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. A bus name (well-known or unique). An object path. A D-Bus interface name. A #GCancellable or %NULL. Callback function to invoke when the proxy is ready. User data to pass to @callback. Signal class handler for the #GDBusProxy::g-properties-changed signal. Signal class handler for the #GDBusProxy::g-signal signal. Asynchronously invokes the @method_name method on @proxy. If @method_name contains any dots, then @name is split into interface and method name parts. This allows using @proxy for invoking methods on other interfaces. If the #GDBusConnection associated with @proxy is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value not compatible with the D-Bus protocol, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. If the @parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: |[<!-- language="C" --> g_dbus_proxy_call (proxy, "TwoStrings", g_variant_new ("(ss)", "Thing One", "Thing Two"), G_DBUS_CALL_FLAGS_NONE, -1, NULL, (GAsyncReadyCallback) two_strings_done, &data); ]| If @proxy has an expected interface (see #GDBusProxy:g-interface-info) and @method_name is referenced by it, then the return value is checked against the return type. This is an asynchronous method. When the operation is finished, @callback will be invoked in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. You can then call g_dbus_proxy_call_finish() to get the result of the operation. See g_dbus_proxy_call_sync() for the synchronous version of this method. If @callback is %NULL then the D-Bus method call message will be sent with the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. A #GDBusProxy. Name of method to invoke. A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. Flags from the #GDBusCallFlags enumeration. The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. A #GCancellable or %NULL. A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. The data to pass to @callback. Finishes an operation started with g_dbus_proxy_call(). %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). A #GDBusProxy. A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call(). Synchronously invokes the @method_name method on @proxy. If @method_name contains any dots, then @name is split into interface and method name parts. This allows using @proxy for invoking methods on other interfaces. If the #GDBusConnection associated with @proxy is disconnected then the operation will fail with %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value not compatible with the D-Bus protocol, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. If the @parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: |[<!-- language="C" --> g_dbus_proxy_call_sync (proxy, "TwoStrings", g_variant_new ("(ss)", "Thing One", "Thing Two"), G_DBUS_CALL_FLAGS_NONE, -1, NULL, &error); ]| The calling thread is blocked until a reply is received. See g_dbus_proxy_call() for the asynchronous version of this method. If @proxy has an expected interface (see #GDBusProxy:g-interface-info) and @method_name is referenced by it, then the return value is checked against the return type. %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). A #GDBusProxy. Name of method to invoke. A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. Flags from the #GDBusCallFlags enumeration. The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. A #GCancellable or %NULL. Like g_dbus_proxy_call() but also takes a #GUnixFDList object. This method is only available on UNIX. A #GDBusProxy. Name of method to invoke. A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. Flags from the #GDBusCallFlags enumeration. The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. A #GUnixFDList or %NULL. A #GCancellable or %NULL. A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. The data to pass to @callback. Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list(). %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). A #GDBusProxy. Return location for a #GUnixFDList or %NULL. A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list(). Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects. This method is only available on UNIX. %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). A #GDBusProxy. Name of method to invoke. A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. Flags from the #GDBusCallFlags enumeration. The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. A #GUnixFDList or %NULL. Return location for a #GUnixFDList or %NULL. A #GCancellable or %NULL. Looks up the value for a property from the cache. This call does no blocking IO. If @proxy has an expected interface (see #GDBusProxy:g-interface-info) and @property_name is referenced by it, then @value is checked against the type of the property. A reference to the #GVariant instance that holds the value for @property_name or %NULL if the value is not in the cache. The returned reference must be freed with g_variant_unref(). A #GDBusProxy. Property name. Gets the names of all cached properties on @proxy. A %NULL-terminated array of strings or %NULL if @proxy has no cached properties. Free the returned array with g_strfreev(). A #GDBusProxy. Gets the connection @proxy is for. A #GDBusConnection owned by @proxy. Do not free. A #GDBusProxy. Gets the timeout to use if -1 (specifying default timeout) is passed as @timeout_msec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions. See the #GDBusProxy:g-default-timeout property for more details. Timeout to use for @proxy. A #GDBusProxy. Gets the flags that @proxy was constructed with. Flags from the #GDBusProxyFlags enumeration. A #GDBusProxy. Returns the #GDBusInterfaceInfo, if any, specifying the interface that @proxy conforms to. See the #GDBusProxy:g-interface-info property for more details. A #GDBusInterfaceInfo or %NULL. Do not unref the returned object, it is owned by @proxy. A #GDBusProxy Gets the D-Bus interface name @proxy is for. A string owned by @proxy. Do not free. A #GDBusProxy. Gets the name that @proxy was constructed for. When connected to a message bus, this will usually be non-%NULL. However, it may be %NULL for a proxy that communicates using a peer-to-peer pattern. A string owned by @proxy. Do not free. A #GDBusProxy. The unique name that owns the name that @proxy is for or %NULL if no-one currently owns that name. You may connect to the #GObject::notify signal to track changes to the #GDBusProxy:g-name-owner property. The name owner or %NULL if no name owner exists. Free with g_free(). A #GDBusProxy. Gets the object path @proxy is for. A string owned by @proxy. Do not free. A #GDBusProxy. If @value is not %NULL, sets the cached value for the property with name @property_name to the value in @value. If @value is %NULL, then the cached value is removed from the property cache. If @proxy has an expected interface (see #GDBusProxy:g-interface-info) and @property_name is referenced by it, then @value is checked against the type of the property. If the @value #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g. |[<!-- language="C" --> g_dbus_proxy_set_cached_property (proxy, "SomeProperty", g_variant_new ("(si)", "A String", 42)); ]| Normally you will not need to use this method since @proxy is tracking changes using the `org.freedesktop.DBus.Properties.PropertiesChanged` D-Bus signal. However, for performance reasons an object may decide to not use this signal for some properties and instead use a proprietary out-of-band mechanism to transmit changes. As a concrete example, consider an object with a property `ChatroomParticipants` which is an array of strings. Instead of transmitting the same (long) array every time the property changes, it is more efficient to only transmit the delta using e.g. signals `ChatroomParticipantJoined(String name)` and `ChatroomParticipantParted(String name)`. A #GDBusProxy Property name. Value for the property or %NULL to remove it from the cache. Sets the timeout to use if -1 (specifying default timeout) is passed as @timeout_msec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions. See the #GDBusProxy:g-default-timeout property for more details. A #GDBusProxy. Timeout in milliseconds. Ensure that interactions with @proxy conform to the given interface. See the #GDBusProxy:g-interface-info property for more details. A #GDBusProxy Minimum interface this proxy conforms to or %NULL to unset. If this property is not %G_BUS_TYPE_NONE, then #GDBusProxy:g-connection must be %NULL and will be set to the #GDBusConnection obtained by calling g_bus_get() with the value of this property. The #GDBusConnection the proxy is for. The timeout to use if -1 (specifying default timeout) is passed as @timeout_msec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions. This allows applications to set a proxy-wide timeout for all remote method invocations on the proxy. If this property is -1, the default timeout (typically 25 seconds) is used. If set to %G_MAXINT, then no timeout is used. Flags from the #GDBusProxyFlags enumeration. Ensure that interactions with this proxy conform to the given interface. This is mainly to ensure that malformed data received from the other peer is ignored. The given #GDBusInterfaceInfo is said to be the "expected interface". The checks performed are: - When completing a method call, if the type signature of the reply message isn't what's expected, the reply is discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT. - Received signals that have a type signature mismatch are dropped and a warning is logged via g_warning(). - Properties received via the initial `GetAll()` call or via the `::PropertiesChanged` signal (on the [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) interface) or set using g_dbus_proxy_set_cached_property() with a type signature mismatch are ignored and a warning is logged via g_warning(). Note that these checks are never done on methods, signals and properties that are not referenced in the given #GDBusInterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break. The D-Bus interface name the proxy is for. The well-known or unique name that the proxy is for. The unique name that owns #GDBusProxy:g-name or %NULL if no-one currently owns that name. You may connect to #GObject::notify signal to track changes to this property. The object path the proxy is for. Emitted when one or more D-Bus properties on @proxy changes. The local cache has already been updated when this signal fires. Note that both @changed_properties and @invalidated_properties are guaranteed to never be %NULL (either may be empty though). If the proxy has the flag %G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then @invalidated_properties will always be empty. This signal corresponds to the `PropertiesChanged` D-Bus signal on the `org.freedesktop.DBus.Properties` interface. A #GVariant containing the properties that changed (type: `a{sv}`) A %NULL terminated array of properties that was invalidated Emitted when a signal from the remote object and interface that @proxy is for, has been received. Since 2.72 this signal supports detailed connections. You can connect to the detailed signal `g-signal::x` in order to receive callbacks only when signal `x` is received from the remote object. The sender of the signal or %NULL if the connection is not a bus connection. The name of the signal. A #GVariant tuple with parameters for the signal. Class structure for #GDBusProxy. Signal class handler for the #GDBusProxy::g-properties-changed signal. Signal class handler for the #GDBusProxy::g-signal signal. Flags used when constructing an instance of a #GDBusProxy derived class. No flags set. Don't load properties. Don't connect to signals on the remote object. If the proxy is for a well-known name, do not ask the bus to launch an owner during proxy initialization or a method call. This flag is only meaningful in proxies for well-known names. If set, the property value for any __invalidated property__ will be (asynchronously) retrieved upon receiving the [`PropertiesChanged`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) D-Bus signal and the property will not cause emission of the #GDBusProxy::g-properties-changed signal. When the value is received the #GDBusProxy::g-properties-changed signal is emitted for the property along with the retrieved value. Since 2.32. If the proxy is for a well-known name, do not ask the bus to launch an owner during proxy initialization, but allow it to be autostarted by a method call. This flag is only meaningful in proxies for well-known names, and only if %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is not also specified. Don't actually send the AddMatch D-Bus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually). (Since: 2.72) Function signature for a function used to determine the #GType to use for an interface proxy (if @interface_name is not %NULL) or object proxy (if @interface_name is %NULL). This function is called in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) that @manager was constructed in. A #GType to use for the remote object. The returned type must be a #GDBusProxy or #GDBusObjectProxy -derived type. A #GDBusObjectManagerClient. The object path of the remote object. The interface name of the remote object or %NULL if a #GDBusObjectProxy #GType is requested. data passed in by the user. Flags used when sending #GDBusMessages on a #GDBusConnection. No flags set. Do not automatically assign a serial number from the #GDBusConnection object when sending a message. `GDBusServer` is a helper for listening to and accepting D-Bus connections. This can be used to create a new D-Bus server, allowing two peers to use the D-Bus protocol for their own specialized communication. A server instance provided in this way will not perform message routing or implement the [`org.freedesktop.DBus` interface](https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-messages). To just export an object on a well-known name on a message bus, such as the session or system bus, you should instead use [func@Gio.bus_own_name]. An example of peer-to-peer communication with GDBus can be found in [gdbus-example-peer.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c). Note that a minimal `GDBusServer` will accept connections from any peer. In many use-cases it will be necessary to add a [class@Gio.DBusAuthObserver] that only accepts connections that have successfully authenticated as the same user that is running the `GDBusServer`. Since GLib 2.68 this can be achieved more simply by passing the `G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER` flag to the server. Creates a new D-Bus server that listens on the first address in @address that works. Once constructed, you can use g_dbus_server_get_client_address() to get a D-Bus address string that clients can use to connect. To have control over the available authentication mechanisms and the users that are authorized to connect, it is strongly recommended to provide a non-%NULL #GDBusAuthObserver. Connect to the #GDBusServer::new-connection signal to handle incoming connections. The returned #GDBusServer isn't active - you have to start it with g_dbus_server_start(). #GDBusServer is used in this [example](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c). This is a synchronous failable constructor. There is currently no asynchronous version. A #GDBusServer or %NULL if @error is set. Free with g_object_unref(). A D-Bus address. Flags from the #GDBusServerFlags enumeration. A D-Bus GUID. A #GDBusAuthObserver or %NULL. A #GCancellable or %NULL. Gets a [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) string that can be used by clients to connect to @server. This is valid and non-empty if initializing the #GDBusServer succeeded. A D-Bus address string. Do not free, the string is owned by @server. A #GDBusServer. Gets the flags for @server. A set of flags from the #GDBusServerFlags enumeration. A #GDBusServer. Gets the GUID for @server, as provided to g_dbus_server_new_sync(). A D-Bus GUID. Do not free this string, it is owned by @server. A #GDBusServer. Gets whether @server is active. %TRUE if server is active, %FALSE otherwise. A #GDBusServer. Starts @server. A #GDBusServer. Stops @server. A #GDBusServer. Whether the server is currently active. The D-Bus address to listen on. A #GDBusAuthObserver object to assist in the authentication process or %NULL. The D-Bus address that clients can use. Flags from the #GDBusServerFlags enumeration. The GUID of the server. See #GDBusConnection:guid for more details. Emitted when a new authenticated connection has been made. Use g_dbus_connection_get_peer_credentials() to figure out what identity (if any), was authenticated. If you want to accept the connection, take a reference to the @connection object and return %TRUE. When you are done with the connection call g_dbus_connection_close() and give up your reference. Note that the other peer may disconnect at any time - a typical thing to do when accepting a connection is to listen to the #GDBusConnection::closed signal. If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD then the signal is emitted in a new thread dedicated to the connection. Otherwise the signal is emitted in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread that @server was constructed in. You are guaranteed that signal handlers for this signal runs before incoming messages on @connection are processed. This means that it's suitable to call g_dbus_connection_register_object() or similar from the signal handler. %TRUE to claim @connection, %FALSE to let other handlers run. A #GDBusConnection for the new connection. Flags used when creating a #GDBusServer. No flags set. All #GDBusServer::new-connection signals will run in separated dedicated threads (see signal for details). Allow the anonymous authentication method. Require the UID of the peer to be the same as the UID of the server when authenticating. (Since: 2.68) Signature for callback function used in g_dbus_connection_signal_subscribe(). A #GDBusConnection. The unique bus name of the sender of the signal, or %NULL on a peer-to-peer D-Bus connection. The object path that the signal was emitted on. The name of the interface. The name of the signal. A #GVariant tuple with parameters for the signal. User data passed when subscribing to the signal. Flags used when subscribing to signals via g_dbus_connection_signal_subscribe(). No flags set. Don't actually send the AddMatch D-Bus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually). Match first arguments that contain a bus or interface name with the given namespace. Match first arguments that contain an object path that is either equivalent to the given path, or one of the paths is a subpath of the other. Information about a signal on a D-Bus interface. The reference count or -1 if statically allocated. The name of the D-Bus signal, e.g. "NameOwnerChanged". A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no arguments. A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. If @info is statically allocated does nothing. Otherwise increases the reference count. The same @info. A #GDBusSignalInfo If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. A #GDBusSignalInfo. The type of the @dispatch function in #GDBusSubtreeVTable. Subtrees are flat. @node, if non-%NULL, is always exactly one segment of the object path (ie: it never contains a slash). A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods. A #GDBusConnection. The unique bus name of the remote caller. The object path that was registered with g_dbus_connection_register_subtree(). The D-Bus interface name that the method call or property access is for. A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. Return location for user data to pass to functions in the returned #GDBusInterfaceVTable. The @user_data #gpointer passed to g_dbus_connection_register_subtree(). The type of the @enumerate function in #GDBusSubtreeVTable. This function is called when generating introspection data and also when preparing to dispatch incoming messages in the event that the %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not specified (ie: to verify that the object path is valid). Hierarchies are not supported; the items that you return should not contain the `/` character. The return value will be freed with g_strfreev(). A newly allocated array of strings for node names that are children of @object_path. A #GDBusConnection. The unique bus name of the remote caller. The object path that was registered with g_dbus_connection_register_subtree(). The @user_data #gpointer passed to g_dbus_connection_register_subtree(). Flags passed to g_dbus_connection_register_subtree(). No flags set. Method calls to objects not in the enumerated range will still be dispatched. This is useful if you want to dynamically spawn objects in the subtree. The type of the @introspect function in #GDBusSubtreeVTable. Subtrees are flat. @node, if non-%NULL, is always exactly one segment of the object path (ie: it never contains a slash). This function should return %NULL to indicate that there is no object at this node. If this function returns non-%NULL, the return value is expected to be a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures describing the interfaces implemented by @node. This array will have g_dbus_interface_info_unref() called on each item before being freed with g_free(). The difference between returning %NULL and an array containing zero items is that the standard DBus interfaces will returned to the remote introspector in the empty array case, but not in the %NULL case. A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL. A #GDBusConnection. The unique bus name of the remote caller. The object path that was registered with g_dbus_connection_register_subtree(). A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. The @user_data #gpointer passed to g_dbus_connection_register_subtree(). Virtual table for handling subtrees registered with g_dbus_connection_register_subtree(). Function for enumerating child nodes. Function for introspecting a child node. Function for dispatching a remote call on a child node. Extension point for debug control functionality. See [Extending GIO](overview.html#extending-gio). The string used to obtain a Unix device path with g_drive_get_identifier(). Data input stream implements [class@Gio.InputStream] and includes functions for reading structured data directly from a binary input stream. Creates a new data input stream for the @base_stream. a new #GDataInputStream. a #GInputStream. Gets the byte order for the data input stream. the @stream's current #GDataStreamByteOrder. a given #GDataInputStream. Gets the current newline type for the @stream. #GDataStreamNewlineType for the given @stream. a given #GDataInputStream. Reads an unsigned 8-bit/1-byte value from @stream. an unsigned 8-bit/1-byte value read from the @stream or `0` if an error occurred. a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. Reads a 16-bit/2-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). a signed 16-bit/2-byte value read from @stream or `0` if an error occurred. a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. Reads a signed 32-bit/4-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a signed 32-bit/4-byte value read from the @stream or `0` if an error occurred. a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. Reads a 64-bit/8-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a signed 64-bit/8-byte value read from @stream or `0` if an error occurred. a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. Reads a line from the data input stream. Note that no encoding checks or conversion is performed; the input is not guaranteed to be UTF-8, and may in fact have embedded NUL characters. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a NUL terminated byte array with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. If there's no content to read, it will still return %NULL, but @error won't be set. a given #GDataInputStream. a #gsize to get the length of the data read in. optional #GCancellable object, %NULL to ignore. The asynchronous version of g_data_input_stream_read_line(). It is an error to have two outstanding calls to this function. When the operation is finished, @callback will be called. You can then call g_data_input_stream_read_line_finish() to get the result of the operation. a given #GDataInputStream. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied. the data to pass to callback function. Finish an asynchronous call started by g_data_input_stream_read_line_async(). Note the warning about string encoding in g_data_input_stream_read_line() applies here as well. a NUL-terminated byte array with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. If there's no content to read, it will still return %NULL, but @error won't be set. a given #GDataInputStream. the #GAsyncResult that was provided to the callback. a #gsize to get the length of the data read in. Finish an asynchronous call started by g_data_input_stream_read_line_async(). a string with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. For UTF-8 conversion errors, the set error domain is %G_CONVERT_ERROR. If there's no content to read, it will still return %NULL, but @error won't be set. a given #GDataInputStream. the #GAsyncResult that was provided to the callback. a #gsize to get the length of the data read in. Reads a UTF-8 encoded line from the data input stream. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a NUL terminated UTF-8 string with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. For UTF-8 conversion errors, the set error domain is %G_CONVERT_ERROR. If there's no content to read, it will still return %NULL, but @error won't be set. a given #GDataInputStream. a #gsize to get the length of the data read in. optional #GCancellable object, %NULL to ignore. Reads an unsigned 16-bit/2-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). an unsigned 16-bit/2-byte value read from the @stream or `0` if an error occurred. a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. Reads an unsigned 32-bit/4-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. an unsigned 32-bit/4-byte value read from the @stream or `0` if an error occurred. a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. Reads an unsigned 64-bit/8-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. an unsigned 64-bit/8-byte read from @stream or `0` if an error occurred. a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. Reads a string from the data input stream, up to the first occurrence of any of the stop characters. Note that, in contrast to g_data_input_stream_read_until_async(), this function consumes the stop character that it finds. Don't use this function in new code. Its functionality is inconsistent with g_data_input_stream_read_until_async(). Both functions will be marked as deprecated in a future release. Use g_data_input_stream_read_upto() instead, but note that that function does not consume the stop character. Use g_data_input_stream_read_upto() instead, which has more consistent behaviour regarding the stop character. a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error. a given #GDataInputStream. characters to terminate the read. a #gsize to get the length of the data read in. optional #GCancellable object, %NULL to ignore. The asynchronous version of g_data_input_stream_read_until(). It is an error to have two outstanding calls to this function. Note that, in contrast to g_data_input_stream_read_until(), this function does not consume the stop character that it finds. You must read it for yourself. When the operation is finished, @callback will be called. You can then call g_data_input_stream_read_until_finish() to get the result of the operation. Don't use this function in new code. Its functionality is inconsistent with g_data_input_stream_read_until(). Both functions will be marked as deprecated in a future release. Use g_data_input_stream_read_upto_async() instead. Use g_data_input_stream_read_upto_async() instead, which has more consistent behaviour regarding the stop character. a given #GDataInputStream. characters to terminate the read. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied. the data to pass to callback function. Finish an asynchronous call started by g_data_input_stream_read_until_async(). Use g_data_input_stream_read_upto_finish() instead, which has more consistent behaviour regarding the stop character. a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error. a given #GDataInputStream. the #GAsyncResult that was provided to the callback. a #gsize to get the length of the data read in. Reads a string from the data input stream, up to the first occurrence of any of the stop characters. In contrast to g_data_input_stream_read_until(), this function does not consume the stop character. You have to use g_data_input_stream_read_byte() to get it before calling g_data_input_stream_read_upto() again. Note that @stop_chars may contain '\0' if @stop_chars_len is specified. The returned string will always be nul-terminated on success. a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error a #GDataInputStream characters to terminate the read length of @stop_chars. May be -1 if @stop_chars is nul-terminated a #gsize to get the length of the data read in optional #GCancellable object, %NULL to ignore The asynchronous version of g_data_input_stream_read_upto(). It is an error to have two outstanding calls to this function. In contrast to g_data_input_stream_read_until(), this function does not consume the stop character. You have to use g_data_input_stream_read_byte() to get it before calling g_data_input_stream_read_upto() again. Note that @stop_chars may contain '\0' if @stop_chars_len is specified. When the operation is finished, @callback will be called. You can then call g_data_input_stream_read_upto_finish() to get the result of the operation. a #GDataInputStream characters to terminate the read length of @stop_chars. May be -1 if @stop_chars is nul-terminated the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore callback to call when the request is satisfied the data to pass to callback function Finish an asynchronous call started by g_data_input_stream_read_upto_async(). Note that this function does not consume the stop character. You have to use g_data_input_stream_read_byte() to get it before calling g_data_input_stream_read_upto_async() again. The returned string will always be nul-terminated on success. a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error. a #GDataInputStream the #GAsyncResult that was provided to the callback a #gsize to get the length of the data read in This function sets the byte order for the given @stream. All subsequent reads from the @stream will be read in the given @order. a given #GDataInputStream. a #GDataStreamByteOrder to set. Sets the newline type for the @stream. Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read chunk ends in "CR" we must read an additional byte to know if this is "CR" or "CR LF", and this might block if there is no more data available. a #GDataInputStream. the type of new line return as #GDataStreamNewlineType. The :byte-order property determines the byte ordering that is used when reading multi-byte entities (such as integers) from the stream. The :newline-type property determines what is considered as a line ending when reading complete lines from the stream. Data output stream implements [class@Gio.OutputStream] and includes functions for writing data directly to an output stream. Creates a new data output stream for @base_stream. #GDataOutputStream. a #GOutputStream. Gets the byte order for the stream. the #GDataStreamByteOrder for the @stream. a #GDataOutputStream. Puts a byte into the output stream. %TRUE if @data was successfully added to the @stream. a #GDataOutputStream. a #guchar. optional #GCancellable object, %NULL to ignore. Puts a signed 16-bit integer into the output stream. %TRUE if @data was successfully added to the @stream. a #GDataOutputStream. a #gint16. optional #GCancellable object, %NULL to ignore. Puts a signed 32-bit integer into the output stream. %TRUE if @data was successfully added to the @stream. a #GDataOutputStream. a #gint32. optional #GCancellable object, %NULL to ignore. Puts a signed 64-bit integer into the stream. %TRUE if @data was successfully added to the @stream. a #GDataOutputStream. a #gint64. optional #GCancellable object, %NULL to ignore. Puts a string into the output stream. %TRUE if @string was successfully added to the @stream. a #GDataOutputStream. a string. optional #GCancellable object, %NULL to ignore. Puts an unsigned 16-bit integer into the output stream. %TRUE if @data was successfully added to the @stream. a #GDataOutputStream. a #guint16. optional #GCancellable object, %NULL to ignore. Puts an unsigned 32-bit integer into the stream. %TRUE if @data was successfully added to the @stream. a #GDataOutputStream. a #guint32. optional #GCancellable object, %NULL to ignore. Puts an unsigned 64-bit integer into the stream. %TRUE if @data was successfully added to the @stream. a #GDataOutputStream. a #guint64. optional #GCancellable object, %NULL to ignore. Sets the byte order of the data output stream to @order. a #GDataOutputStream. a %GDataStreamByteOrder. Determines the byte ordering that is used when writing multi-byte entities (such as integers) to the stream. #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources across various machine architectures. Selects Big Endian byte order. Selects Little Endian byte order. Selects endianness based on host machine's architecture. #GDataStreamNewlineType is used when checking for or setting the line endings for a given file. Selects "LF" line endings, common on most modern UNIX platforms. Selects "CR" line endings. Selects "CR, LF" line ending, common on Microsoft Windows. Automatically try to handle any line ending type. Interface for socket-like objects with datagram semantics. A `GDatagramBased` is a networking interface for representing datagram-based communications. It is a more or less direct mapping of the core parts of the BSD socket API in a portable GObject interface. It is implemented by [class@Gio.Socket], which wraps the UNIX socket API on UNIX and winsock2 on Windows. `GDatagramBased` is entirely platform independent, and is intended to be used alongside higher-level networking APIs such as [class@Gio.IOStream]. It uses vectored scatter/gather I/O by default, allowing for many messages to be sent or received in a single call. Where possible, implementations of the interface should take advantage of vectored I/O to minimise processing or system calls. For example, `GSocket` uses `recvmmsg()` and `sendmmsg()` where possible. Callers should take advantage of scatter/gather I/O (the use of multiple buffers per message) to avoid unnecessary copying of data to assemble or disassemble a message. Each `GDatagramBased` operation has a timeout parameter which may be negative for blocking behaviour, zero for non-blocking behaviour, or positive for timeout behaviour. A blocking operation blocks until finished or there is an error. A non-blocking operation will return immediately with a `G_IO_ERROR_WOULD_BLOCK` error if it cannot make progress. A timeout operation will block until the operation is complete or the timeout expires; if the timeout expires it will return what progress it made, or `G_IO_ERROR_TIMED_OUT` if no progress was made. To know when a call would successfully run you can call [method@Gio.DatagramBased.condition_check] or [method@Gio.DatagramBased.condition_wait]. You can also use [method@Gio.DatagramBased.create_source] and attach it to a [struct@GLib.MainContext] to get callbacks when I/O is possible. When running a non-blocking operation applications should always be able to handle getting a `G_IO_ERROR_WOULD_BLOCK` error even when some other function said that I/O was possible. This can easily happen in case of a race condition in the application, but it can also happen for other reasons. For instance, on Windows a socket is always seen as writable until a write returns `G_IO_ERROR_WOULD_BLOCK`. As with `GSocket`, `GDatagramBased`s can be either connection oriented (for example, SCTP) or connectionless (for example, UDP). `GDatagramBased`s must be datagram-based, not stream-based. The interface does not cover connection establishment — use methods on the underlying type to establish a connection before sending and receiving data through the `GDatagramBased` API. For connectionless socket types the target/source address is specified or received in each I/O operation. Like most other APIs in GLib, `GDatagramBased` is not inherently thread safe. To use a `GDatagramBased` concurrently from multiple threads, you must implement your own locking. Checks on the readiness of @datagram_based to perform operations. The operations specified in @condition are checked for and masked against the currently-satisfied conditions on @datagram_based. The result is returned. %G_IO_IN will be set in the return value if data is available to read with g_datagram_based_receive_messages(), or if the connection is closed remotely (EOS); and if the datagram_based has not been closed locally using some implementation-specific method (such as g_socket_close() or g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket). If the connection is shut down or closed (by calling g_socket_close() or g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for example), all calls to this function will return %G_IO_ERROR_CLOSED. %G_IO_OUT will be set if it is expected that at least one byte can be sent using g_datagram_based_send_messages() without blocking. It will not be set if the datagram_based has been closed locally. %G_IO_HUP will be set if the connection has been closed locally. %G_IO_ERR will be set if there was an asynchronous error in transmitting data previously enqueued using g_datagram_based_send_messages(). Note that on Windows, it is possible for an operation to return %G_IO_ERROR_WOULD_BLOCK even immediately after g_datagram_based_condition_check() has claimed that the #GDatagramBased is ready for writing. Rather than calling g_datagram_based_condition_check() and then writing to the #GDatagramBased if it succeeds, it is generally better to simply try writing right away, and try again later if the initial attempt returns %G_IO_ERROR_WOULD_BLOCK. It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these conditions will always be set in the output if they are true. Apart from these flags, the output is guaranteed to be masked by @condition. This call never blocks. the #GIOCondition mask of the current state a #GDatagramBased a #GIOCondition mask to check Waits for up to @timeout microseconds for condition to become true on @datagram_based. If the condition is met, %TRUE is returned. If @cancellable is cancelled before the condition is met, or if @timeout is reached before the condition is met, then %FALSE is returned and @error is set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). %TRUE if the condition was met, %FALSE otherwise a #GDatagramBased a #GIOCondition mask to wait for the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely a #GCancellable Creates a #GSource that can be attached to a #GMainContext to monitor for the availability of the specified @condition on the #GDatagramBased. The #GSource keeps a reference to the @datagram_based. The callback on the source is of the #GDatagramBasedSourceFunc type. It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these conditions will always be reported in the callback if they are true. If non-%NULL, @cancellable can be used to cancel the source, which will cause the source to trigger, reporting the current condition (which is likely 0 unless cancellation happened at the same time as a condition change). You can check for this in the callback using g_cancellable_is_cancelled(). a newly allocated #GSource a #GDatagramBased a #GIOCondition mask to monitor a #GCancellable Receive one or more data messages from @datagram_based in one go. @messages must point to an array of #GInputMessage structs and @num_messages must be the length of this array. Each #GInputMessage contains a pointer to an array of #GInputVector structs describing the buffers that the data received in each message will be written to. @flags modify how all messages are received. The commonly available arguments for this are available in the #GSocketMsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. These flags affect the overall receive operation. Flags affecting individual messages are returned in #GInputMessage.flags. The other members of #GInputMessage are treated as described in its documentation. If @timeout is negative the call will block until @num_messages have been received, the connection is closed remotely (EOS), @cancellable is cancelled, or an error occurs. If @timeout is 0 the call will return up to @num_messages without blocking, or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system to be received. If @timeout is positive the call will block on the same conditions as if @timeout were negative. If the timeout is reached before any messages are received, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number of messages received before timing out. (Note: This is effectively the behaviour of `MSG_WAITFORONE` with recvmmsg().) To be notified when messages are available, wait for the %G_IO_IN condition. Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from g_datagram_based_receive_messages() even if you were previously notified of a %G_IO_IN condition. If the remote peer closes the connection, any messages queued in the underlying receive buffer will be returned, and subsequent calls to g_datagram_based_receive_messages() will return 0 (with no error set). If the connection is shut down or closed (by calling g_socket_close() or g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for example), all calls to this function will return %G_IO_ERROR_CLOSED. On error -1 is returned and @error is set accordingly. An error will only be returned if zero messages could be received; otherwise the number of messages successfully received before the error will be returned. If @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. number of messages received, or -1 on error. Note that the number of messages received may be smaller than @num_messages if @timeout is zero or positive, if the peer closed the connection, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try to receive the remaining messages. a #GDatagramBased an array of #GInputMessage structs the number of elements in @messages an int containing #GSocketMsgFlags flags for the overall operation the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely a %GCancellable Send one or more data messages from @datagram_based in one go. @messages must point to an array of #GOutputMessage structs and @num_messages must be the length of this array. Each #GOutputMessage contains an address to send the data to, and a pointer to an array of #GOutputVector structs to describe the buffers that the data to be sent for each message will be gathered from. @flags modify how the message is sent. The commonly available arguments for this are available in the #GSocketMsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. The other members of #GOutputMessage are treated as described in its documentation. If @timeout is negative the call will block until @num_messages have been sent, @cancellable is cancelled, or an error occurs. If @timeout is 0 the call will send up to @num_messages without blocking, or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages. If @timeout is positive the call will block on the same conditions as if @timeout were negative. If the timeout is reached before any messages are sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number of messages sent before timing out. To be notified when messages can be sent, wait for the %G_IO_OUT condition. Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from g_datagram_based_send_messages() even if you were previously notified of a %G_IO_OUT condition. (On Windows in particular, this is very common due to the way the underlying APIs work.) If the connection is shut down or closed (by calling g_socket_close() or g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for example), all calls to this function will return %G_IO_ERROR_CLOSED. On error -1 is returned and @error is set accordingly. An error will only be returned if zero messages could be sent; otherwise the number of messages successfully sent before the error will be returned. If @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than @num_messages if @timeout is zero or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try to send the remaining messages. a #GDatagramBased an array of #GOutputMessage structs the number of elements in @messages an int containing #GSocketMsgFlags flags the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely a %GCancellable Checks on the readiness of @datagram_based to perform operations. The operations specified in @condition are checked for and masked against the currently-satisfied conditions on @datagram_based. The result is returned. %G_IO_IN will be set in the return value if data is available to read with g_datagram_based_receive_messages(), or if the connection is closed remotely (EOS); and if the datagram_based has not been closed locally using some implementation-specific method (such as g_socket_close() or g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket). If the connection is shut down or closed (by calling g_socket_close() or g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for example), all calls to this function will return %G_IO_ERROR_CLOSED. %G_IO_OUT will be set if it is expected that at least one byte can be sent using g_datagram_based_send_messages() without blocking. It will not be set if the datagram_based has been closed locally. %G_IO_HUP will be set if the connection has been closed locally. %G_IO_ERR will be set if there was an asynchronous error in transmitting data previously enqueued using g_datagram_based_send_messages(). Note that on Windows, it is possible for an operation to return %G_IO_ERROR_WOULD_BLOCK even immediately after g_datagram_based_condition_check() has claimed that the #GDatagramBased is ready for writing. Rather than calling g_datagram_based_condition_check() and then writing to the #GDatagramBased if it succeeds, it is generally better to simply try writing right away, and try again later if the initial attempt returns %G_IO_ERROR_WOULD_BLOCK. It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these conditions will always be set in the output if they are true. Apart from these flags, the output is guaranteed to be masked by @condition. This call never blocks. the #GIOCondition mask of the current state a #GDatagramBased a #GIOCondition mask to check Waits for up to @timeout microseconds for condition to become true on @datagram_based. If the condition is met, %TRUE is returned. If @cancellable is cancelled before the condition is met, or if @timeout is reached before the condition is met, then %FALSE is returned and @error is set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). %TRUE if the condition was met, %FALSE otherwise a #GDatagramBased a #GIOCondition mask to wait for the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely a #GCancellable Creates a #GSource that can be attached to a #GMainContext to monitor for the availability of the specified @condition on the #GDatagramBased. The #GSource keeps a reference to the @datagram_based. The callback on the source is of the #GDatagramBasedSourceFunc type. It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these conditions will always be reported in the callback if they are true. If non-%NULL, @cancellable can be used to cancel the source, which will cause the source to trigger, reporting the current condition (which is likely 0 unless cancellation happened at the same time as a condition change). You can check for this in the callback using g_cancellable_is_cancelled(). a newly allocated #GSource a #GDatagramBased a #GIOCondition mask to monitor a #GCancellable Receive one or more data messages from @datagram_based in one go. @messages must point to an array of #GInputMessage structs and @num_messages must be the length of this array. Each #GInputMessage contains a pointer to an array of #GInputVector structs describing the buffers that the data received in each message will be written to. @flags modify how all messages are received. The commonly available arguments for this are available in the #GSocketMsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. These flags affect the overall receive operation. Flags affecting individual messages are returned in #GInputMessage.flags. The other members of #GInputMessage are treated as described in its documentation. If @timeout is negative the call will block until @num_messages have been received, the connection is closed remotely (EOS), @cancellable is cancelled, or an error occurs. If @timeout is 0 the call will return up to @num_messages without blocking, or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system to be received. If @timeout is positive the call will block on the same conditions as if @timeout were negative. If the timeout is reached before any messages are received, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number of messages received before timing out. (Note: This is effectively the behaviour of `MSG_WAITFORONE` with recvmmsg().) To be notified when messages are available, wait for the %G_IO_IN condition. Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from g_datagram_based_receive_messages() even if you were previously notified of a %G_IO_IN condition. If the remote peer closes the connection, any messages queued in the underlying receive buffer will be returned, and subsequent calls to g_datagram_based_receive_messages() will return 0 (with no error set). If the connection is shut down or closed (by calling g_socket_close() or g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for example), all calls to this function will return %G_IO_ERROR_CLOSED. On error -1 is returned and @error is set accordingly. An error will only be returned if zero messages could be received; otherwise the number of messages successfully received before the error will be returned. If @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. number of messages received, or -1 on error. Note that the number of messages received may be smaller than @num_messages if @timeout is zero or positive, if the peer closed the connection, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try to receive the remaining messages. a #GDatagramBased an array of #GInputMessage structs the number of elements in @messages an int containing #GSocketMsgFlags flags for the overall operation the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely a %GCancellable Send one or more data messages from @datagram_based in one go. @messages must point to an array of #GOutputMessage structs and @num_messages must be the length of this array. Each #GOutputMessage contains an address to send the data to, and a pointer to an array of #GOutputVector structs to describe the buffers that the data to be sent for each message will be gathered from. @flags modify how the message is sent. The commonly available arguments for this are available in the #GSocketMsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. The other members of #GOutputMessage are treated as described in its documentation. If @timeout is negative the call will block until @num_messages have been sent, @cancellable is cancelled, or an error occurs. If @timeout is 0 the call will send up to @num_messages without blocking, or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages. If @timeout is positive the call will block on the same conditions as if @timeout were negative. If the timeout is reached before any messages are sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number of messages sent before timing out. To be notified when messages can be sent, wait for the %G_IO_OUT condition. Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from g_datagram_based_send_messages() even if you were previously notified of a %G_IO_OUT condition. (On Windows in particular, this is very common due to the way the underlying APIs work.) If the connection is shut down or closed (by calling g_socket_close() or g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for example), all calls to this function will return %G_IO_ERROR_CLOSED. On error -1 is returned and @error is set accordingly. An error will only be returned if zero messages could be sent; otherwise the number of messages successfully sent before the error will be returned. If @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than @num_messages if @timeout is zero or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try to send the remaining messages. a #GDatagramBased an array of #GOutputMessage structs the number of elements in @messages an int containing #GSocketMsgFlags flags the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely a %GCancellable Provides an interface for socket-like objects which have datagram semantics, following the Berkeley sockets API. The interface methods are thin wrappers around the corresponding virtual methods, and no pre-processing of inputs is implemented — so implementations of this API must handle all functionality documented in the interface methods. The parent interface. Virtual method for g_datagram_based_receive_messages(). number of messages received, or -1 on error. Note that the number of messages received may be smaller than @num_messages if @timeout is zero or positive, if the peer closed the connection, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try to receive the remaining messages. a #GDatagramBased an array of #GInputMessage structs the number of elements in @messages an int containing #GSocketMsgFlags flags for the overall operation the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely a %GCancellable Virtual method for g_datagram_based_send_messages(). number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than @num_messages if @timeout is zero or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try to send the remaining messages. a #GDatagramBased an array of #GOutputMessage structs the number of elements in @messages an int containing #GSocketMsgFlags flags the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely a %GCancellable Virtual method for g_datagram_based_create_source(). a newly allocated #GSource a #GDatagramBased a #GIOCondition mask to monitor a #GCancellable Virtual method for g_datagram_based_condition_check(). the #GIOCondition mask of the current state a #GDatagramBased a #GIOCondition mask to check Virtual method for g_datagram_based_condition_wait(). %TRUE if the condition was met, %FALSE otherwise a #GDatagramBased a #GIOCondition mask to wait for the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely a #GCancellable This is the function type of the callback used for the #GSource returned by g_datagram_based_create_source(). %G_SOURCE_REMOVE if the source should be removed, %G_SOURCE_CONTINUE otherwise the #GDatagramBased the current condition at the source fired data passed in by the user `GDebugController` is an interface to expose control of debugging features and debug output. It is implemented on Linux using [class@Gio.DebugControllerDBus], which exposes a D-Bus interface to allow authenticated peers to control debug features in this process. Whether debug output is enabled is exposed as [property@Gio.DebugController:debug-enabled]. This controls [func@GLib.log_set_debug_enabled] by default. Application code may connect to the [signal@GObject.Object::notify] signal for it to control other parts of its debug infrastructure as necessary. If your application or service is using the default GLib log writer function, creating one of the built-in implementations of `GDebugController` should be all that’s needed to dynamically enable or disable debug output. Get the value of #GDebugController:debug-enabled. %TRUE if debug output should be exposed, %FALSE otherwise a #GDebugController Set the value of #GDebugController:debug-enabled. a #GDebugController %TRUE if debug output should be exposed, %FALSE otherwise %TRUE if debug output should be exposed (for example by forwarding it to the journal), %FALSE otherwise. `GDebugControllerDBus` is an implementation of [iface@Gio.DebugController] which exposes debug settings as a D-Bus object. It is a [iface@Gio.Initable] object, and will register an object at `/org/gtk/Debugging` on the bus given as [property@Gio.DebugControllerDBus:connection] once it’s initialized. The object will be unregistered when the last reference to the `GDebugControllerDBus` is dropped. This D-Bus object can be used by remote processes to enable or disable debug output in this process. Remote processes calling `org.gtk.Debugging.SetDebugEnabled()` will affect the value of [property@Gio.DebugController:debug-enabled] and, by default, [func@GLib.log_get_debug_enabled]. By default, no processes are allowed to call `SetDebugEnabled()` unless a [signal@Gio.DebugControllerDBus::authorize] signal handler is installed. This is because the process may be privileged, or might expose sensitive information in its debug output. You may want to restrict the ability to enable debug output to privileged users or processes. One option is to install a D-Bus security policy which restricts access to `SetDebugEnabled()`, installing something like the following in `$datadir/dbus-1/system.d/`: ```xml <?xml version="1.0"?> <!--*-nxml-*--> <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"> <busconfig> <policy user="root"> <allow send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/> </policy> <policy context="default"> <deny send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/> </policy> </busconfig> ``` This will prevent the `SetDebugEnabled()` method from being called by all except root. It will not prevent the `DebugEnabled` property from being read, as it’s accessed through the `org.freedesktop.DBus.Properties` interface. Another option is to use polkit to allow or deny requests on a case-by-case basis, allowing for the possibility of dynamic authorisation. To do this, connect to the [signal@Gio.DebugControllerDBus::authorize] signal and query polkit in it: ```c g_autoptr(GError) child_error = NULL; g_autoptr(GDBusConnection) connection = g_bus_get_sync (G_BUS_TYPE_SYSTEM, NULL, NULL); gulong debug_controller_authorize_id = 0; // Set up the debug controller. debug_controller = G_DEBUG_CONTROLLER (g_debug_controller_dbus_new (priv->connection, NULL, &child_error)); if (debug_controller == NULL) { g_error ("Could not register debug controller on bus: %s", child_error->message); } debug_controller_authorize_id = g_signal_connect (debug_controller, "authorize", G_CALLBACK (debug_controller_authorize_cb), self); static gboolean debug_controller_authorize_cb (GDebugControllerDBus *debug_controller, GDBusMethodInvocation *invocation, gpointer user_data) { g_autoptr(PolkitAuthority) authority = NULL; g_autoptr(PolkitSubject) subject = NULL; g_autoptr(PolkitAuthorizationResult) auth_result = NULL; g_autoptr(GError) local_error = NULL; GDBusMessage *message; GDBusMessageFlags message_flags; PolkitCheckAuthorizationFlags flags = POLKIT_CHECK_AUTHORIZATION_FLAGS_NONE; message = g_dbus_method_invocation_get_message (invocation); message_flags = g_dbus_message_get_flags (message); authority = polkit_authority_get_sync (NULL, &local_error); if (authority == NULL) { g_warning ("Failed to get polkit authority: %s", local_error->message); return FALSE; } if (message_flags & G_DBUS_MESSAGE_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION) flags |= POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION; subject = polkit_system_bus_name_new (g_dbus_method_invocation_get_sender (invocation)); auth_result = polkit_authority_check_authorization_sync (authority, subject, "com.example.MyService.set-debug-enabled", NULL, flags, NULL, &local_error); if (auth_result == NULL) { g_warning ("Failed to get check polkit authorization: %s", local_error->message); return FALSE; } return polkit_authorization_result_get_is_authorized (auth_result); } ``` Create a new #GDebugControllerDBus and synchronously initialize it. Initializing the object will export the debug object on @connection. The object will remain registered until the last reference to the #GDebugControllerDBus is dropped. Initialization may fail if registering the object on @connection fails. a new #GDebugControllerDBus, or %NULL on failure a #GDBusConnection to register the debug object on a #GCancellable, or %NULL Default handler for the #GDebugControllerDBus::authorize signal. Stop the debug controller, unregistering its object from the bus. Any pending method calls to the object will complete successfully, but new ones will return an error. This method will block until all pending #GDebugControllerDBus::authorize signals have been handled. This is expected to not take long, as it will just be waiting for threads to join. If any #GDebugControllerDBus::authorize signal handlers are still executing in other threads, this will block until after they have returned. This method will be called automatically when the final reference to the #GDebugControllerDBus is dropped. You may want to call it explicitly to know when the controller has been fully removed from the bus, or to break reference count cycles. Calling this method from within a #GDebugControllerDBus::authorize signal handler will cause a deadlock and must not be done. a #GDebugControllerDBus The D-Bus connection to expose the debugging interface on. Typically this will be the same connection (to the system or session bus) which the rest of the application or service’s D-Bus objects are registered on. Emitted when a D-Bus peer is trying to change the debug settings and used to determine if that is authorized. This signal is emitted in a dedicated worker thread, so handlers are allowed to perform blocking I/O. This means that, for example, it is appropriate to call `polkit_authority_check_authorization_sync()` to check authorization using polkit. If %FALSE is returned then no further handlers are run and the request to change the debug settings is rejected. Otherwise, if %TRUE is returned, signal emission continues. If no handlers return %FALSE, then the debug settings are allowed to be changed. Signal handlers must not modify @invocation, or cause it to return a value. The default class handler just returns %TRUE. %TRUE if the call is authorized, %FALSE otherwise. A #GDBusMethodInvocation. The virtual function table for #GDebugControllerDBus. The parent class. Default handler for the #GDebugControllerDBus::authorize signal. The virtual function table for #GDebugController. The parent interface. `GDrive` represents a piece of hardware connected to the machine. It’s generally only created for removable hardware or hardware with removable media. For example, an optical disc drive, or a USB flash drive. `GDrive` is a container class for [iface@Gio.Volume] objects that stem from the same piece of media. As such, `GDrive` abstracts a drive with (or without) removable media and provides operations for querying whether media is available, determining whether media change is automatically detected and ejecting the media. If the `GDrive` reports that media isn’t automatically detected, one can poll for media; typically one should not do this periodically as a poll for media operation is potentially expensive and may spin up the drive creating noise. `GDrive` supports starting and stopping drives with authentication support for the former. This can be used to support a diverse set of use cases including connecting/disconnecting iSCSI devices, powering down external disk enclosures and starting/stopping multi-disk devices such as RAID devices. Note that the actual semantics and side-effects of starting/stopping a `GDrive` may vary according to implementation. To choose the correct verbs in e.g. a file manager, use [method@Gio.Drive.get_start_stop_type]. For [porting from GnomeVFS](migrating-gnome-vfs.html) note that there is no equivalent of `GDrive` in that API. Checks if a drive can be ejected. %TRUE if the @drive can be ejected, %FALSE otherwise. a #GDrive. Checks if a drive can be polled for media changes. %TRUE if the @drive can be polled for media changes, %FALSE otherwise. a #GDrive. Checks if a drive can be started. %TRUE if the @drive can be started, %FALSE otherwise. a #GDrive. Checks if a drive can be started degraded. %TRUE if the @drive can be started degraded, %FALSE otherwise. a #GDrive. Checks if a drive can be stopped. %TRUE if the @drive can be stopped, %FALSE otherwise. a #GDrive. Signal emitted when the drive is changed. The removed signal that is emitted when the #GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized. Asynchronously ejects a drive. When the operation is finished, @callback will be called. You can then call g_drive_eject_finish() to obtain the result of the operation. Use g_drive_eject_with_operation() instead. a #GDrive. flags affecting the unmount if required for eject optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Signal emitted when the physical eject button (if any) of a drive have been pressed. Finishes ejecting a drive. Use g_drive_eject_with_operation_finish() instead. %TRUE if the drive has been ejected successfully, %FALSE otherwise. a #GDrive. a #GAsyncResult. Ejects a drive. This is an asynchronous operation, and is finished by calling g_drive_eject_with_operation_finish() with the @drive and #GAsyncResult data returned in the @callback. a #GDrive. flags affecting the unmount if required for eject a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes ejecting a drive. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. %TRUE if the drive was successfully ejected. %FALSE otherwise. a #GDrive. a #GAsyncResult. Gets the kinds of identifiers that @drive has. Use g_drive_get_identifier() to obtain the identifiers themselves. a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. a #GDrive Gets the icon for @drive. #GIcon for the @drive. Free the returned object with g_object_unref(). a #GDrive. Gets the identifier of the given kind for @drive. The only identifier currently available is %G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE. a newly allocated string containing the requested identifier, or %NULL if the #GDrive doesn't have this kind of identifier. a #GDrive the kind of identifier to return Gets the name of @drive. a string containing @drive's name. The returned string should be freed when no longer needed. a #GDrive. Gets the sort key for @drive, if any. Sorting key for @drive or %NULL if no such key is available. A #GDrive. Gets a hint about how a drive can be started/stopped. A value from the #GDriveStartStopType enumeration. a #GDrive. Gets the icon for @drive. symbolic #GIcon for the @drive. Free the returned object with g_object_unref(). a #GDrive. Get a list of mountable volumes for @drive. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). #GList containing any #GVolume objects on the given @drive. a #GDrive. Checks if the @drive has media. Note that the OS may not be polling the drive for media changes; see g_drive_is_media_check_automatic() for more details. %TRUE if @drive has media, %FALSE otherwise. a #GDrive. Check if @drive has any mountable volumes. %TRUE if the @drive contains volumes, %FALSE otherwise. a #GDrive. Checks if @drive is capable of automatically detecting media changes. %TRUE if the @drive is capable of automatically detecting media changes, %FALSE otherwise. a #GDrive. Checks if the @drive supports removable media. %TRUE if @drive supports removable media, %FALSE otherwise. a #GDrive. Checks if the #GDrive and/or its media is considered removable by the user. See g_drive_is_media_removable(). %TRUE if @drive and/or its media is considered removable, %FALSE otherwise. a #GDrive. Asynchronously polls @drive to see if media has been inserted or removed. When the operation is finished, @callback will be called. You can then call g_drive_poll_for_media_finish() to obtain the result of the operation. a #GDrive. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes an operation started with g_drive_poll_for_media() on a drive. %TRUE if the drive has been poll_for_mediaed successfully, %FALSE otherwise. a #GDrive. a #GAsyncResult. Asynchronously starts a drive. When the operation is finished, @callback will be called. You can then call g_drive_start_finish() to obtain the result of the operation. a #GDrive. flags affecting the start operation. a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes starting a drive. %TRUE if the drive has been started successfully, %FALSE otherwise. a #GDrive. a #GAsyncResult. Asynchronously stops a drive. When the operation is finished, @callback will be called. You can then call g_drive_stop_finish() to obtain the result of the operation. a #GDrive. flags affecting the unmount if required for stopping. a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22. Finishes stopping a drive. %TRUE if the drive has been stopped successfully, %FALSE otherwise. a #GDrive. a #GAsyncResult. Checks if a drive can be ejected. %TRUE if the @drive can be ejected, %FALSE otherwise. a #GDrive. Checks if a drive can be polled for media changes. %TRUE if the @drive can be polled for media changes, %FALSE otherwise. a #GDrive. Checks if a drive can be started. %TRUE if the @drive can be started, %FALSE otherwise. a #GDrive. Checks if a drive can be started degraded. %TRUE if the @drive can be started degraded, %FALSE otherwise. a #GDrive. Checks if a drive can be stopped. %TRUE if the @drive can be stopped, %FALSE otherwise. a #GDrive. Asynchronously ejects a drive. When the operation is finished, @callback will be called. You can then call g_drive_eject_finish() to obtain the result of the operation. Use g_drive_eject_with_operation() instead. a #GDrive. flags affecting the unmount if required for eject optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes ejecting a drive. Use g_drive_eject_with_operation_finish() instead. %TRUE if the drive has been ejected successfully, %FALSE otherwise. a #GDrive. a #GAsyncResult. Ejects a drive. This is an asynchronous operation, and is finished by calling g_drive_eject_with_operation_finish() with the @drive and #GAsyncResult data returned in the @callback. a #GDrive. flags affecting the unmount if required for eject a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes ejecting a drive. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. %TRUE if the drive was successfully ejected. %FALSE otherwise. a #GDrive. a #GAsyncResult. Gets the kinds of identifiers that @drive has. Use g_drive_get_identifier() to obtain the identifiers themselves. a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. a #GDrive Gets the icon for @drive. #GIcon for the @drive. Free the returned object with g_object_unref(). a #GDrive. Gets the identifier of the given kind for @drive. The only identifier currently available is %G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE. a newly allocated string containing the requested identifier, or %NULL if the #GDrive doesn't have this kind of identifier. a #GDrive the kind of identifier to return Gets the name of @drive. a string containing @drive's name. The returned string should be freed when no longer needed. a #GDrive. Gets the sort key for @drive, if any. Sorting key for @drive or %NULL if no such key is available. A #GDrive. Gets a hint about how a drive can be started/stopped. A value from the #GDriveStartStopType enumeration. a #GDrive. Gets the icon for @drive. symbolic #GIcon for the @drive. Free the returned object with g_object_unref(). a #GDrive. Get a list of mountable volumes for @drive. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). #GList containing any #GVolume objects on the given @drive. a #GDrive. Checks if the @drive has media. Note that the OS may not be polling the drive for media changes; see g_drive_is_media_check_automatic() for more details. %TRUE if @drive has media, %FALSE otherwise. a #GDrive. Check if @drive has any mountable volumes. %TRUE if the @drive contains volumes, %FALSE otherwise. a #GDrive. Checks if @drive is capable of automatically detecting media changes. %TRUE if the @drive is capable of automatically detecting media changes, %FALSE otherwise. a #GDrive. Checks if the @drive supports removable media. %TRUE if @drive supports removable media, %FALSE otherwise. a #GDrive. Checks if the #GDrive and/or its media is considered removable by the user. See g_drive_is_media_removable(). %TRUE if @drive and/or its media is considered removable, %FALSE otherwise. a #GDrive. Asynchronously polls @drive to see if media has been inserted or removed. When the operation is finished, @callback will be called. You can then call g_drive_poll_for_media_finish() to obtain the result of the operation. a #GDrive. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes an operation started with g_drive_poll_for_media() on a drive. %TRUE if the drive has been poll_for_mediaed successfully, %FALSE otherwise. a #GDrive. a #GAsyncResult. Asynchronously starts a drive. When the operation is finished, @callback will be called. You can then call g_drive_start_finish() to obtain the result of the operation. a #GDrive. flags affecting the start operation. a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes starting a drive. %TRUE if the drive has been started successfully, %FALSE otherwise. a #GDrive. a #GAsyncResult. Asynchronously stops a drive. When the operation is finished, @callback will be called. You can then call g_drive_stop_finish() to obtain the result of the operation. a #GDrive. flags affecting the unmount if required for stopping. a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes stopping a drive. %TRUE if the drive has been stopped successfully, %FALSE otherwise. a #GDrive. a #GAsyncResult. Emitted when the drive's state has changed. This signal is emitted when the #GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized. Emitted when the physical eject button (if any) of a drive has been pressed. Emitted when the physical stop button (if any) of a drive has been pressed. Interface for creating #GDrive implementations. The parent interface. Signal emitted when the drive is changed. The removed signal that is emitted when the #GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized. Signal emitted when the physical eject button (if any) of a drive have been pressed. Returns the name for the given #GDrive. a string containing @drive's name. The returned string should be freed when no longer needed. a #GDrive. Returns a #GIcon for the given #GDrive. #GIcon for the @drive. Free the returned object with g_object_unref(). a #GDrive. Returns %TRUE if the #GDrive has mountable volumes. %TRUE if the @drive contains volumes, %FALSE otherwise. a #GDrive. Returns a list #GList of #GVolume for the #GDrive. #GList containing any #GVolume objects on the given @drive. a #GDrive. Returns %TRUE if the #GDrive supports removal and insertion of media. %TRUE if @drive supports removable media, %FALSE otherwise. a #GDrive. Returns %TRUE if the #GDrive has media inserted. %TRUE if @drive has media, %FALSE otherwise. a #GDrive. Returns %TRUE if the #GDrive is capable of automatically detecting media changes. %TRUE if the @drive is capable of automatically detecting media changes, %FALSE otherwise. a #GDrive. Returns %TRUE if the #GDrive can eject media. %TRUE if the @drive can be ejected, %FALSE otherwise. a #GDrive. Returns %TRUE if the #GDrive is capable of manually polling for media change. %TRUE if the @drive can be polled for media changes, %FALSE otherwise. a #GDrive. Ejects a #GDrive. a #GDrive. flags affecting the unmount if required for eject optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes an eject operation. %TRUE if the drive has been ejected successfully, %FALSE otherwise. a #GDrive. a #GAsyncResult. Poll for media insertion/removal on a #GDrive. a #GDrive. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes a media poll operation. %TRUE if the drive has been poll_for_mediaed successfully, %FALSE otherwise. a #GDrive. a #GAsyncResult. Returns the identifier of the given kind, or %NULL if the #GDrive doesn't have one. a newly allocated string containing the requested identifier, or %NULL if the #GDrive doesn't have this kind of identifier. a #GDrive the kind of identifier to return Returns an array strings listing the kinds of identifiers which the #GDrive has. a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. a #GDrive Gets a #GDriveStartStopType with details about starting/stopping the drive. Since 2.22. A value from the #GDriveStartStopType enumeration. a #GDrive. Returns %TRUE if a #GDrive can be started. Since 2.22. %TRUE if the @drive can be started, %FALSE otherwise. a #GDrive. Returns %TRUE if a #GDrive can be started degraded. Since 2.22. %TRUE if the @drive can be started degraded, %FALSE otherwise. a #GDrive. Starts a #GDrive. Since 2.22. a #GDrive. flags affecting the start operation. a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes a start operation. Since 2.22. %TRUE if the drive has been started successfully, %FALSE otherwise. a #GDrive. a #GAsyncResult. Returns %TRUE if a #GDrive can be stopped. Since 2.22. %TRUE if the @drive can be stopped, %FALSE otherwise. a #GDrive. Stops a #GDrive. Since 2.22. a #GDrive. flags affecting the unmount if required for stopping. a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes a stop operation. Since 2.22. %TRUE if the drive has been stopped successfully, %FALSE otherwise. a #GDrive. a #GAsyncResult. Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22. Starts ejecting a #GDrive using a #GMountOperation. Since 2.22. a #GDrive. flags affecting the unmount if required for eject a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes an eject operation using a #GMountOperation. Since 2.22. %TRUE if the drive was successfully ejected. %FALSE otherwise. a #GDrive. a #GAsyncResult. Gets a key used for sorting #GDrive instances or %NULL if no such key exists. Since 2.32. Sorting key for @drive or %NULL if no such key is available. A #GDrive. Returns a symbolic #GIcon for the given #GDrive. Since 2.34. symbolic #GIcon for the @drive. Free the returned object with g_object_unref(). a #GDrive. Returns %TRUE if the #GDrive and/or its media is considered removable by the user. Since 2.50. %TRUE if @drive and/or its media is considered removable, %FALSE otherwise. a #GDrive. Flags used when starting a drive. No flags set. Enumeration describing how a drive can be started/stopped. Unknown or drive doesn't support start/stop. The stop method will physically shut down the drive and e.g. power down the port the drive is attached to. The start/stop methods are used for connecting/disconnect to the drive over the network. The start/stop methods will assemble/disassemble a virtual drive from several physical drives. The start/stop methods will unlock/lock the disk (for example using the ATA `SECURITY UNLOCK DEVICE` command) `GDtlsClientConnection` is the client-side subclass of [iface@Gio.DtlsConnection], representing a client-side DTLS connection. Creates a new #GDtlsClientConnection wrapping @base_socket which is assumed to communicate with the server identified by @server_identity. the new #GDtlsClientConnection, or %NULL on error the #GDatagramBased to wrap the expected identity of the server Gets the list of distinguished names of the Certificate Authorities that the server will accept certificates from. This will be set during the TLS handshake if the server requests a certificate. Otherwise, it will be %NULL. Each item in the list is a #GByteArray which contains the complete subject DN of the certificate authority. the list of CA DNs. You should unref each element with g_byte_array_unref() and then the free the list with g_list_free(). the #GDtlsClientConnection Gets @conn's expected server identity a #GSocketConnectable describing the expected server identity, or %NULL if the expected identity is not known. the #GDtlsClientConnection Gets @conn's validation flags This function does not work as originally designed and is impossible to use correctly. See #GDtlsClientConnection:validation-flags for more information. Do not attempt to ignore validation errors. the validation flags the #GDtlsClientConnection Sets @conn's expected server identity, which is used both to tell servers on virtual hosts which certificate to present, and also to let @conn know what name to look for in the certificate when performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. the #GDtlsClientConnection a #GSocketConnectable describing the expected server identity Sets @conn's validation flags, to override the default set of checks performed when validating a server certificate. By default, %G_TLS_CERTIFICATE_VALIDATE_ALL is used. This function does not work as originally designed and is impossible to use correctly. See #GDtlsClientConnection:validation-flags for more information. Do not attempt to ignore validation errors. the #GDtlsClientConnection the #GTlsCertificateFlags to use A list of the distinguished names of the Certificate Authorities that the server will accept client certificates signed by. If the server requests a client certificate during the handshake, then this property will be set after the handshake completes. Each item in the list is a #GByteArray which contains the complete subject DN of the certificate authority. A #GSocketConnectable describing the identity of the server that is expected on the other end of the connection. If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in #GDtlsClientConnection:validation-flags, this object will be used to determine the expected identify of the remote end of the connection; if #GDtlsClientConnection:server-identity is not set, or does not match the identity presented by the server, then the %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail. In addition to its use in verifying the server certificate, this is also used to give a hint to the server about what certificate we expect, which is useful for servers that serve virtual hosts. What steps to perform when validating a certificate received from a server. Server certificates that fail to validate in any of the ways indicated here will be rejected unless the application overrides the default via #GDtlsConnection::accept-certificate. GLib guarantees that if certificate verification fails, at least one flag will be set, but it does not guarantee that all possible flags will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Therefore, there is no safe way to use this property. This is not a horrible problem, though, because you should not be attempting to ignore validation errors anyway. If you really must ignore TLS certificate errors, connect to #GDtlsConnection::accept-certificate. Do not attempt to ignore validation errors. vtable for a #GDtlsClientConnection implementation. The parent interface. `GDtlsConnection` is the base DTLS connection class type, which wraps a [iface@Gio.DatagramBased] and provides DTLS encryption on top of it. Its subclasses, [iface@Gio.DtlsClientConnection] and [iface@Gio.DtlsServerConnection], implement client-side and server-side DTLS, respectively. For TLS support, see [class@Gio.TlsConnection]. As DTLS is datagram based, `GDtlsConnection` implements [iface@Gio.DatagramBased], presenting a datagram-socket-like API for the encrypted connection. This operates over a base datagram connection, which is also a `GDatagramBased` ([property@Gio.DtlsConnection:base-socket]). To close a DTLS connection, use [method@Gio.DtlsConnection.close]. Neither [iface@Gio.DtlsServerConnection] or [iface@Gio.DtlsClientConnection] set the peer address on their base [iface@Gio.DatagramBased] if it is a [class@Gio.Socket] — it is up to the caller to do that if they wish. If they do not, and [method@Gio.Socket.close] is called on the base socket, the `GDtlsConnection` will not raise a `G_IO_ERROR_NOT_CONNECTED` error on further I/O. Check whether to accept a certificate. Retrieve TLS channel binding data (Since: 2.66) Gets the name of the application-layer protocol negotiated during the handshake. If the peer did not use the ALPN extension, or did not advertise a protocol that matched one of @conn's protocols, or the TLS backend does not support ALPN, then this will be %NULL. See g_dtls_connection_set_advertised_protocols(). the negotiated protocol, or %NULL a #GDtlsConnection Attempts a TLS handshake on @conn. On the client side, it is never necessary to call this method; although the connection needs to perform a handshake after connecting, #GDtlsConnection will handle this for you automatically when you try to send or receive data on the connection. You can call g_dtls_connection_handshake() manually if you want to know whether the initial handshake succeeded or failed (as opposed to just immediately trying to use @conn to read or write, in which case, if it fails, it may not be possible to tell if it failed before or after completing the handshake), but beware that servers may reject client authentication after the handshake has completed, so a successful handshake does not indicate the connection will be usable. Likewise, on the server side, although a handshake is necessary at the beginning of the communication, you do not need to call this function explicitly unless you want clearer error reporting. Previously, calling g_dtls_connection_handshake() after the initial handshake would trigger a rehandshake; however, this usage was deprecated in GLib 2.60 because rehandshaking was removed from the TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after the initial handshake will no longer do anything. #GDtlsConnection::accept_certificate may be emitted during the handshake. success or failure a #GDtlsConnection a #GCancellable, or %NULL Asynchronously performs a TLS handshake on @conn. See g_dtls_connection_handshake() for more information. a #GDtlsConnection the [I/O priority](iface.AsyncResult.html#io-priority) of the request a #GCancellable, or %NULL callback to call when the handshake is complete the data to pass to the callback function Finish an asynchronous TLS handshake operation. See g_dtls_connection_handshake() for more information. %TRUE on success, %FALSE on failure, in which case @error will be set. a #GDtlsConnection a #GAsyncResult. Sets the list of application-layer protocols to advertise that the caller is willing to speak on this connection. The Application-Layer Protocol Negotiation (ALPN) extension will be used to negotiate a compatible protocol with the peer; use g_dtls_connection_get_negotiated_protocol() to find the negotiated protocol after the handshake. Specifying %NULL for the the value of @protocols will disable ALPN negotiation. See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) for a list of registered protocol IDs. a #GDtlsConnection a %NULL-terminated array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL Shut down part or all of a DTLS connection. If @shutdown_read is %TRUE then the receiving side of the connection is shut down, and further reading is disallowed. Subsequent calls to g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED. If @shutdown_write is %TRUE then the sending side of the connection is shut down, and further writing is disallowed. Subsequent calls to g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED. It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this is equivalent to calling g_dtls_connection_close(). If @cancellable is cancelled, the #GDtlsConnection may be left partially-closed and any pending untransmitted data may be lost. Call g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection. %TRUE on success, %FALSE otherwise a #GDtlsConnection %TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams a #GCancellable, or %NULL Asynchronously shut down part or all of the DTLS connection. See g_dtls_connection_shutdown() for more information. a #GDtlsConnection %TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams the [I/O priority](iface.AsyncResult.html#io-priority) of the request a #GCancellable, or %NULL callback to call when the shutdown operation is complete the data to pass to the callback function Finish an asynchronous TLS shutdown operation. See g_dtls_connection_shutdown() for more information. %TRUE on success, %FALSE on failure, in which case @error will be set a #GDtlsConnection a #GAsyncResult Close the DTLS connection. This is equivalent to calling g_dtls_connection_shutdown() to shut down both sides of the connection. Closing a #GDtlsConnection waits for all buffered but untransmitted data to be sent before it completes. It then sends a `close_notify` DTLS alert to the peer and may wait for a `close_notify` to be received from the peer. It does not close the underlying #GDtlsConnection:base-socket; that must be closed separately. Once @conn is closed, all other operations will return %G_IO_ERROR_CLOSED. Closing a #GDtlsConnection multiple times will not return an error. #GDtlsConnections will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. If @cancellable is cancelled, the #GDtlsConnection may be left partially-closed and any pending untransmitted data may be lost. Call g_dtls_connection_close() again to complete closing the #GDtlsConnection. %TRUE on success, %FALSE otherwise a #GDtlsConnection a #GCancellable, or %NULL Asynchronously close the DTLS connection. See g_dtls_connection_close() for more information. a #GDtlsConnection the [I/O priority](iface.AsyncResult.html#io-priority) of the request a #GCancellable, or %NULL callback to call when the close operation is complete the data to pass to the callback function Finish an asynchronous TLS close operation. See g_dtls_connection_close() for more information. %TRUE on success, %FALSE on failure, in which case @error will be set a #GDtlsConnection a #GAsyncResult Used by #GDtlsConnection implementations to emit the #GDtlsConnection::accept-certificate signal. %TRUE if one of the signal handlers has returned %TRUE to accept @peer_cert a #GDtlsConnection the peer's #GTlsCertificate the problems with @peer_cert Gets @conn's certificate, as set by g_dtls_connection_set_certificate(). @conn's certificate, or %NULL a #GDtlsConnection Query the TLS backend for TLS channel binding data of @type for @conn. This call retrieves TLS channel binding data as specified in RFC [5056](https://tools.ietf.org/html/rfc5056), RFC [5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The binding data is returned in @data. The @data is resized by the callee using #GByteArray buffer management and will be freed when the @data is destroyed by g_byte_array_unref(). If @data is %NULL, it will only check whether TLS backend is able to fetch the data (e.g. whether @type is supported by the TLS backend). It does not guarantee that the data will be available though. That could happen if TLS connection does not support @type or the binding data is not available yet due to additional negotiation or input required. %TRUE on success, %FALSE otherwise a #GDtlsConnection #GTlsChannelBindingType type of data to fetch #GByteArray is filled with the binding data, or %NULL Returns the name of the current DTLS ciphersuite, or %NULL if the connection has not handshaked or has been closed. Beware that the TLS backend may use any of multiple different naming conventions, because OpenSSL and GnuTLS have their own ciphersuite naming conventions that are different from each other and different from the standard, IANA- registered ciphersuite names. The ciphersuite name is intended to be displayed to the user for informative purposes only, and parsing it is not recommended. The name of the current DTLS ciphersuite, or %NULL a #GDTlsConnection Gets the certificate database that @conn uses to verify peer certificates. See g_dtls_connection_set_database(). the certificate database that @conn uses or %NULL a #GDtlsConnection Get the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. If %NULL is returned, then no user interaction will occur for this connection. The interaction object. a connection Gets the name of the application-layer protocol negotiated during the handshake. If the peer did not use the ALPN extension, or did not advertise a protocol that matched one of @conn's protocols, or the TLS backend does not support ALPN, then this will be %NULL. See g_dtls_connection_set_advertised_protocols(). the negotiated protocol, or %NULL a #GDtlsConnection Gets @conn's peer's certificate after the handshake has completed or failed. (It is not set during the emission of #GDtlsConnection::accept-certificate.) @conn's peer's certificate, or %NULL a #GDtlsConnection Gets the errors associated with validating @conn's peer's certificate, after the handshake has completed or failed. (It is not set during the emission of #GDtlsConnection::accept-certificate.) @conn's peer's certificate errors a #GDtlsConnection Returns the current DTLS protocol version, which may be %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or has been closed, or if the TLS backend has implemented a protocol version that is not a recognized #GTlsProtocolVersion. The current DTLS protocol version a #GDTlsConnection Gets @conn rehandshaking mode. See g_dtls_connection_set_rehandshake_mode() for details. Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. %G_TLS_REHANDSHAKE_SAFELY a #GDtlsConnection Tests whether or not @conn expects a proper TLS close notification when the connection is closed. See g_dtls_connection_set_require_close_notify() for details. %TRUE if @conn requires a proper TLS close notification. a #GDtlsConnection Attempts a TLS handshake on @conn. On the client side, it is never necessary to call this method; although the connection needs to perform a handshake after connecting, #GDtlsConnection will handle this for you automatically when you try to send or receive data on the connection. You can call g_dtls_connection_handshake() manually if you want to know whether the initial handshake succeeded or failed (as opposed to just immediately trying to use @conn to read or write, in which case, if it fails, it may not be possible to tell if it failed before or after completing the handshake), but beware that servers may reject client authentication after the handshake has completed, so a successful handshake does not indicate the connection will be usable. Likewise, on the server side, although a handshake is necessary at the beginning of the communication, you do not need to call this function explicitly unless you want clearer error reporting. Previously, calling g_dtls_connection_handshake() after the initial handshake would trigger a rehandshake; however, this usage was deprecated in GLib 2.60 because rehandshaking was removed from the TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after the initial handshake will no longer do anything. #GDtlsConnection::accept_certificate may be emitted during the handshake. success or failure a #GDtlsConnection a #GCancellable, or %NULL Asynchronously performs a TLS handshake on @conn. See g_dtls_connection_handshake() for more information. a #GDtlsConnection the [I/O priority](iface.AsyncResult.html#io-priority) of the request a #GCancellable, or %NULL callback to call when the handshake is complete the data to pass to the callback function Finish an asynchronous TLS handshake operation. See g_dtls_connection_handshake() for more information. %TRUE on success, %FALSE on failure, in which case @error will be set. a #GDtlsConnection a #GAsyncResult. Sets the list of application-layer protocols to advertise that the caller is willing to speak on this connection. The Application-Layer Protocol Negotiation (ALPN) extension will be used to negotiate a compatible protocol with the peer; use g_dtls_connection_get_negotiated_protocol() to find the negotiated protocol after the handshake. Specifying %NULL for the the value of @protocols will disable ALPN negotiation. See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) for a list of registered protocol IDs. a #GDtlsConnection a %NULL-terminated array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL This sets the certificate that @conn will present to its peer during the TLS handshake. For a #GDtlsServerConnection, it is mandatory to set this, and that will normally be done at construct time. For a #GDtlsClientConnection, this is optional. If a handshake fails with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server requires a certificate, and if you try connecting again, you should call this method first. You can call g_dtls_client_connection_get_accepted_cas() on the failed connection to get a list of Certificate Authorities that the server will accept certificates from. (It is also possible that a server will allow the connection with or without a certificate; in that case, if you don't provide a certificate, you can tell that the server requested one by the fact that g_dtls_client_connection_get_accepted_cas() will return non-%NULL.) a #GDtlsConnection the certificate to use for @conn Sets the certificate database that is used to verify peer certificates. This is set to the default database by default. See g_tls_backend_get_default_database(). If set to %NULL, then peer certificate validation will always set the %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning #GDtlsConnection::accept-certificate will always be emitted on client-side connections, unless that bit is not set in #GDtlsClientConnection:validation-flags). There are nonintuitive security implications when using a non-default database. See #GDtlsConnection:database for details. a #GDtlsConnection a #GTlsDatabase Set the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. The @interaction argument will normally be a derived subclass of #GTlsInteraction. %NULL can also be provided if no user interaction should occur for this connection. a connection an interaction object, or %NULL Since GLib 2.64, changing the rehandshake mode is no longer supported and will have no effect. With TLS 1.3, rehandshaking has been removed from the TLS protocol, replaced by separate post-handshake authentication and rekey operations. Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. a #GDtlsConnection the rehandshaking mode Sets whether or not @conn expects a proper TLS close notification before the connection is closed. If this is %TRUE (the default), then @conn will expect to receive a TLS close notification from its peer before the connection is closed, and will return a %G_TLS_ERROR_EOF error if the connection is closed without proper notification (since this may indicate a network error, or man-in-the-middle attack). In some protocols, the application will know whether or not the connection was closed cleanly based on application-level data (because the application-level data includes a length field, or is somehow self-delimiting); in this case, the close notify is redundant and may be omitted. You can use g_dtls_connection_set_require_close_notify() to tell @conn to allow an "unannounced" connection close, in which case the close will show up as a 0-length read, as in a non-TLS #GDatagramBased, and it is up to the application to check that the data has been fully received. Note that this only affects the behavior when the peer closes the connection; when the application calls g_dtls_connection_close_async() on @conn itself, this will send a close notification regardless of the setting of this property. If you explicitly want to do an unclean close, you can close @conn's #GDtlsConnection:base-socket rather than closing @conn itself. a #GDtlsConnection whether or not to require close notification Shut down part or all of a DTLS connection. If @shutdown_read is %TRUE then the receiving side of the connection is shut down, and further reading is disallowed. Subsequent calls to g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED. If @shutdown_write is %TRUE then the sending side of the connection is shut down, and further writing is disallowed. Subsequent calls to g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED. It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this is equivalent to calling g_dtls_connection_close(). If @cancellable is cancelled, the #GDtlsConnection may be left partially-closed and any pending untransmitted data may be lost. Call g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection. %TRUE on success, %FALSE otherwise a #GDtlsConnection %TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams a #GCancellable, or %NULL Asynchronously shut down part or all of the DTLS connection. See g_dtls_connection_shutdown() for more information. a #GDtlsConnection %TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams the [I/O priority](iface.AsyncResult.html#io-priority) of the request a #GCancellable, or %NULL callback to call when the shutdown operation is complete the data to pass to the callback function Finish an asynchronous TLS shutdown operation. See g_dtls_connection_shutdown() for more information. %TRUE on success, %FALSE on failure, in which case @error will be set a #GDtlsConnection a #GAsyncResult The list of application-layer protocols that the connection advertises that it is willing to speak. See g_dtls_connection_set_advertised_protocols(). The #GDatagramBased that the connection wraps. Note that this may be any implementation of #GDatagramBased, not just a #GSocket. The connection's certificate; see g_dtls_connection_set_certificate(). The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name(). The certificate database to use when verifying this TLS connection. If no certificate database is set, then the default database will be used. See g_tls_backend_get_default_database(). When using a non-default database, #GDtlsConnection must fall back to using the #GTlsDatabase to perform certificate verification using g_tls_database_verify_chain(), which means certificate verification will not be able to make use of TLS session context. This may be less secure. For example, if you create your own #GTlsDatabase that just wraps the default #GTlsDatabase, you might expect that you have not changed anything, but this is not true because you may have altered the behavior of #GDtlsConnection by causing it to use g_tls_database_verify_chain(). See the documentation of g_tls_database_verify_chain() for more details on specific security checks that may not be performed. Accordingly, setting a non-default database is discouraged except for specialty applications with unusual security requirements. A #GTlsInteraction object to be used when the connection or certificate database need to interact with the user. This will be used to prompt the user for passwords where necessary. The application-layer protocol negotiated during the TLS handshake. See g_dtls_connection_get_negotiated_protocol(). The connection's peer's certificate, after the TLS handshake has completed or failed. Note in particular that this is not yet set during the emission of #GDtlsConnection::accept-certificate. (You can watch for a #GObject::notify signal on this property to detect when a handshake has occurred.) The errors noticed while verifying #GDtlsConnection:peer-certificate. Normally this should be 0, but it may not be if #GDtlsClientConnection:validation-flags is not %G_TLS_CERTIFICATE_VALIDATE_ALL, or if #GDtlsConnection::accept-certificate overrode the default behavior. GLib guarantees that if certificate verification fails, at least one error will be set, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. The DTLS protocol version in use. See g_dtls_connection_get_protocol_version(). The rehandshaking mode. See g_dtls_connection_set_rehandshake_mode(). The rehandshake mode is ignored. Whether or not proper TLS close notification is required. See g_dtls_connection_set_require_close_notify(). Emitted during the TLS handshake after the peer certificate has been received. You can examine @peer_cert's certification path by calling g_tls_certificate_get_issuer() on it. For a client-side connection, @peer_cert is the server's certificate, and the signal will only be emitted if the certificate was not acceptable according to @conn's #GDtlsClientConnection:validation_flags. If you would like the certificate to be accepted despite @errors, return %TRUE from the signal handler. Otherwise, if no handler accepts the certificate, the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE. GLib guarantees that if certificate verification fails, this signal will be emitted with at least one error will be set in @errors, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to ignore %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. For a server-side connection, @peer_cert is the certificate presented by the client, if this was requested via the server's #GDtlsServerConnection:authentication_mode. On the server side, the signal is always emitted when the client presents a certificate, and the certificate will only be accepted if a handler returns %TRUE. Note that if this signal is emitted as part of asynchronous I/O in the main thread, then you should not attempt to interact with the user before returning from the signal handler. If you want to let the user decide whether or not to accept the certificate, you would have to return %FALSE from the signal handler on the first attempt, and then after the connection attempt returns a %G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and if the user decides to accept the certificate, remember that fact, create a new connection, and return %TRUE from the signal handler the next time. If you are doing I/O in another thread, you do not need to worry about this, and can simply block in the signal handler until the UI thread returns an answer. %TRUE to accept @peer_cert (which will also immediately end the signal emission). %FALSE to allow the signal emission to continue, which will cause the handshake to fail if no one else overrides it. the peer's #GTlsCertificate the problems with @peer_cert. Virtual method table for a #GDtlsConnection implementation. The parent interface. Check whether to accept a certificate. Perform a handshake operation. success or failure a #GDtlsConnection a #GCancellable, or %NULL Start an asynchronous handshake operation. a #GDtlsConnection the [I/O priority](iface.AsyncResult.html#io-priority) of the request a #GCancellable, or %NULL callback to call when the handshake is complete the data to pass to the callback function Finish an asynchronous handshake operation. %TRUE on success, %FALSE on failure, in which case @error will be set. a #GDtlsConnection a #GAsyncResult. Shut down one or both directions of the connection. %TRUE on success, %FALSE otherwise a #GDtlsConnection %TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams a #GCancellable, or %NULL Start an asynchronous shutdown operation. a #GDtlsConnection %TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams the [I/O priority](iface.AsyncResult.html#io-priority) of the request a #GCancellable, or %NULL callback to call when the shutdown operation is complete the data to pass to the callback function Finish an asynchronous shutdown operation. %TRUE on success, %FALSE on failure, in which case @error will be set a #GDtlsConnection a #GAsyncResult Set APLN protocol list (Since: 2.60) a #GDtlsConnection a %NULL-terminated array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL Get ALPN-negotiated protocol (Since: 2.60) the negotiated protocol, or %NULL a #GDtlsConnection Retrieve TLS channel binding data (Since: 2.66) `GDtlsServerConnection` is the server-side subclass of [iface@Gio.DtlsConnection], representing a server-side DTLS connection. Creates a new #GDtlsServerConnection wrapping @base_socket. the new #GDtlsServerConnection, or %NULL on error the #GDatagramBased to wrap the default server certificate, or %NULL The #GTlsAuthenticationMode for the server. This can be changed before calling g_dtls_connection_handshake() if you want to rehandshake with a different mode from the initial handshake. vtable for a #GDtlsServerConnection implementation. The parent interface. Possible values of Explicit Congestion Notification code points. These appear in `TOS` (IPv4) or `TCLASS` (IPv6) packet headers and are described in [RFC 3168](https://www.rfc-editor.org/rfc/rfc3168#section-5). Not ECN-capable transport ECN Capable Transport(1) ECN Capable Transport(0) Congestion Experienced `GEmblem` is an implementation of [iface@Gio.Icon] that supports having an emblem, which is an icon with additional properties. It can than be added to a [class@Gio.EmblemedIcon]. Currently, only metainformation about the emblem's origin is supported. More may be added in the future. Creates a new emblem for @icon. a new #GEmblem. a GIcon containing the icon. Creates a new emblem for @icon. a new #GEmblem. a GIcon containing the icon. a GEmblemOrigin enum defining the emblem's origin Gives back the icon from @emblem. a #GIcon. The returned object belongs to the emblem and should not be modified or freed. a #GEmblem from which the icon should be extracted. Gets the origin of the emblem. the origin of the emblem a #GEmblem The actual icon of the emblem. The origin the emblem is derived from. GEmblemOrigin is used to add information about the origin of the emblem to #GEmblem. Emblem of unknown origin Emblem adds device-specific information Emblem depicts live metadata, such as "readonly" Emblem comes from a user-defined tag, e.g. set by nautilus (in the future) `GEmblemedIcon` is an implementation of [iface@Gio.Icon] that supports adding an emblem to an icon. Adding multiple emblems to an icon is ensured via [method@Gio.EmblemedIcon.add_emblem]. Note that `GEmblemedIcon` allows no control over the position of the emblems. See also [class@Gio.Emblem] for more information. Creates a new emblemed icon for @icon with the emblem @emblem. a new #GIcon a #GIcon a #GEmblem, or %NULL Adds @emblem to the #GList of #GEmblems. a #GEmblemedIcon a #GEmblem Removes all the emblems from @icon. a #GEmblemedIcon Gets the list of emblems for the @icon. a #GList of #GEmblems that is owned by @emblemed a #GEmblemedIcon Gets the main icon for @emblemed. a #GIcon that is owned by @emblemed a #GEmblemedIcon The [iface@Gio.Icon] to attach emblems to. A key in the "access" namespace for checking deletion privileges. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be %TRUE if the user is able to delete the file. A key in the "access" namespace for getting execution privileges. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be %TRUE if the user is able to execute the file. A key in the "access" namespace for getting read privileges. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be %TRUE if the user is able to read the file. A key in the "access" namespace for checking renaming privileges. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be %TRUE if the user is able to rename the file. A key in the "access" namespace for checking trashing privileges. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be %TRUE if the user is able to move the file to the trash. A key in the "access" namespace for getting write privileges. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be %TRUE if the user is able to write to the file. A key in the "dos" namespace for checking if the file's archive flag is set. This attribute is %TRUE if the archive flag is set. This attribute is only available for DOS file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "dos" namespace for checking if the file is a NTFS mount point (a volume mount or a junction point). This attribute is %TRUE if file is a reparse point of type [IO_REPARSE_TAG_MOUNT_POINT](https://msdn.microsoft.com/en-us/library/dd541667.aspx). This attribute is only available for DOS file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "dos" namespace for checking if the file's backup flag is set. This attribute is %TRUE if the backup flag is set. This attribute is only available for DOS file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "dos" namespace for getting the file NTFS reparse tag. This value is 0 for files that are not reparse points. See the [Reparse Tags](https://msdn.microsoft.com/en-us/library/dd541667.aspx) page for possible reparse tag values. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "etag" namespace for getting the value of the file's entity tag. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "filesystem" namespace for getting the number of bytes of free space left on the file system. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "filesystem" namespace for checking if the file system is read only. Is set to %TRUE if the file system is read only. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "filesystem" namespace for checking if the file system is remote. Is set to %TRUE if the file system is remote. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "filesystem" namespace for getting the total size (in bytes) of the file system, used in g_file_query_filesystem_info(). Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "filesystem" namespace for getting the file system's type. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "filesystem" namespace for getting the number of bytes used by data on the file system. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "filesystem" namespace for hinting a file manager application whether it should preview (e.g. thumbnail) files on the file system. The value for this key contain a #GFilesystemPreviewType. A key in the "gvfs" namespace that gets the name of the current GVFS backend in use. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "id" namespace for getting a file identifier. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. An example use would be during listing files, to avoid recursive directory scanning. For local files on Linux, this is a combination of the file’s device number and inode, so is invariant with respect to hard linking. The format used by other VFS implementations may vary, and some VFS backends may not set it. For simply seeing if two [iface@Gio.File] instances refer to the same path on disk, see [method@Gio.File.equal]. A key in the "id" namespace for getting the file system identifier. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. An example use would be during drag and drop to see if the source and target are on the same filesystem (default to move) or not (default to copy). A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be polled. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started degraded. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be stopped. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "mountable" namespace for getting the HAL UDI for the mountable file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is automatically polled for media. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "mountable" namespace for getting the #GDriveStartStopType. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "mountable" namespace for getting the unix device. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "mountable" namespace for getting the unix device file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "owner" namespace for getting the file owner's group. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "owner" namespace for getting the user name of the file's owner. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "owner" namespace for getting the real name of the user that owns the file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "preview" namespace for getting a #GIcon that can be used to get preview of the file. For example, it may be a low resolution thumbnail without metadata. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value for this key should contain a #GIcon. A key in the "recent" namespace for getting time, when the metadata for the file in `recent:///` was last changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT64. A key in the "selinux" namespace for getting the file's SELinux context. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. Note that this attribute is only available if GLib has been built with SELinux support. A key in the "standard" namespace for getting the amount of disk space that is consumed by the file (in bytes). This will generally be larger than the file size (due to block size overhead) but can occasionally be smaller (for example, for sparse files). Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "standard" namespace for getting the content type of the file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. The value for this key should contain a valid content type. A key in the "standard" namespace for getting the copy name of the file. The copy name is an optional version of the name. If available it's always in UTF8, and corresponds directly to the original filename (only transcoded to UTF8). This is useful if you want to copy the file to another filesystem that might have a different encoding. If the filename is not a valid string in the encoding selected for the filesystem it is in then the copy name will not be set. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for getting the description of the file. The description is a utf8 string that describes the file, generally containing the filename, but can also contain further information. Example descriptions could be "filename (on hostname)" for a remote file or "filename (in trash)" for a file in the trash. This is useful for instance as the window title when displaying a directory or for a bookmarks menu. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for getting the display name of the file. A display name is guaranteed to be in UTF-8 and can thus be displayed in the UI. It is guaranteed to be set on every file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for edit name of the file. An edit name is similar to the display name, but it is meant to be used when you want to rename the file in the UI. The display name might contain information you don't want in the new filename (such as "(invalid unicode)" if the filename was in an invalid encoding). Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for getting the fast content type. The fast content type isn't as reliable as the regular one, as it only uses the filename to guess it, but it is faster to calculate than the regular content type. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for getting the icon for the file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value for this key should contain a #GIcon. A key in the "standard" namespace for checking if a file is a backup file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "standard" namespace for checking if a file is hidden. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "standard" namespace for checking if the file is a symlink. Typically the actual type is something else, if we followed the symlink to get the type. On Windows NTFS mountpoints are considered to be symlinks as well. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "standard" namespace for checking if a file is virtual. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "standard" namespace for checking if a file is volatile. This is meant for opaque, non-POSIX-like backends to indicate that the URI is not persistent. Applications should look at %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET for the persistent URI. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "standard" namespace for getting the name of the file. The name is the on-disk filename which may not be in any known encoding, and can thus not be generally displayed as is. It is guaranteed to be set on every file. Use %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the name in a user interface. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. A key in the "standard" namespace for getting the file's size (in bytes). Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "standard" namespace for setting the sort order of a file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32. An example use would be in file managers, which would use this key to set the order files are displayed. Files with smaller sort order should be sorted first, and files without sort order as if sort order was zero. A key in the "standard" namespace for getting the symbolic icon for the file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value for this key should contain a #GIcon. A key in the "standard" namespace for getting the symlink target, if the file is a symlink. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. A key in the "standard" namespace for getting the target URI for the file, in the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for storing file types. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. The value for this key should contain a #GFileType. A key in the "thumbnail" namespace for checking if thumbnailing failed. This attribute is %TRUE if thumbnailing failed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "thumbnail" namespace for checking if thumbnailing failed for the large image. This attribute is %TRUE if thumbnailing failed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "thumbnail" namespace for checking if thumbnailing failed for the normal image. This attribute is %TRUE if thumbnailing failed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "thumbnail" namespace for checking if thumbnailing failed for the x-large image. This attribute is %TRUE if thumbnailing failed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "thumbnail" namespace for checking if thumbnailing failed for the xx-large image. This attribute is %TRUE if thumbnailing failed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "thumbnail" namespace for checking whether the thumbnail is outdated. This attribute is %TRUE if the thumbnail is up-to-date with the file it represents, and %FALSE if the file has been modified since the thumbnail was generated. If %G_FILE_ATTRIBUTE_THUMBNAILING_FAILED is %TRUE and this attribute is %FALSE, it indicates that thumbnailing may be attempted again and may succeed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "thumbnail" namespace for checking whether the large thumbnail is outdated. This attribute is %TRUE if the large thumbnail is up-to-date with the file it represents, and %FALSE if the file has been modified since the thumbnail was generated. If %G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_LARGE is %TRUE and this attribute is %FALSE, it indicates that thumbnailing may be attempted again and may succeed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "thumbnail" namespace for checking whether the normal thumbnail is outdated. This attribute is %TRUE if the normal thumbnail is up-to-date with the file it represents, and %FALSE if the file has been modified since the thumbnail was generated. If %G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_NORMAL is %TRUE and this attribute is %FALSE, it indicates that thumbnailing may be attempted again and may succeed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "thumbnail" namespace for checking whether the x-large thumbnail is outdated. This attribute is %TRUE if the x-large thumbnail is up-to-date with the file it represents, and %FALSE if the file has been modified since the thumbnail was generated. If %G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_XLARGE is %TRUE and this attribute is %FALSE, it indicates that thumbnailing may be attempted again and may succeed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "thumbnail" namespace for checking whether the xx-large thumbnail is outdated. This attribute is %TRUE if the x-large thumbnail is up-to-date with the file it represents, and %FALSE if the file has been modified since the thumbnail was generated. If %G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_XXLARGE is %TRUE and this attribute is %FALSE, it indicates that thumbnailing may be attempted again and may succeed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "thumbnail" namespace for getting the path to the thumbnail image with the biggest size available. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. A key in the "thumbnail" namespace for getting the path to the large thumbnail image. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. A key in the "thumbnail" namespace for getting the path to the normal thumbnail image. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. A key in the "thumbnail" namespace for getting the path to the x-large thumbnail image. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. A key in the "thumbnail" namespace for getting the path to the xx-large thumbnail image. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. A key in the "time" namespace for getting the time the file was last accessed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the file was last accessed, in seconds since the UNIX epoch. A key in the "time" namespace for getting the nanoseconds of the time the file was last accessed. This should be used in conjunction with #G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "time" namespace for getting the microseconds of the time the file was last accessed. This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "time" namespace for getting the time the file was last changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the file was last changed, in seconds since the UNIX epoch. This corresponds to the traditional UNIX ctime. A key in the "time" namespace for getting the nanoseconds of the time the file was last changed. This should be used in conjunction with #G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "time" namespace for getting the microseconds of the time the file was last changed. This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "time" namespace for getting the time the file was created. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the file was created, in seconds since the UNIX epoch. This may correspond to Linux `stx_btime`, FreeBSD `st_birthtim`, NetBSD `st_birthtime` or NTFS `ctime`. A key in the "time" namespace for getting the nanoseconds of the time the file was created. This should be used in conjunction with #G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "time" namespace for getting the microseconds of the time the file was created. This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "time" namespace for getting the time the file was last modified. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the file was modified, in seconds since the UNIX epoch. A key in the "time" namespace for getting the nanoseconds of the time the file was last modified. This should be used in conjunction with #G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "time" namespace for getting the microseconds of the time the file was last modified. This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "trash" namespace for getting the deletion date and time of a file inside the `trash:///` folder. The format of the returned string is `YYYY-MM-DDThh:mm:ss`. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "trash" namespace for getting the number of (toplevel) items that are present in the `trash:///` folder. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "trash" namespace for getting the original path of a file inside the `trash:///` folder before it was trashed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. A key in the "unix" namespace for getting the number of blocks allocated for the file. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "unix" namespace for getting the block size for the file system. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "unix" namespace for getting the device id of the device the file is located on (see stat() documentation). This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "unix" namespace for getting the group ID for the file. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "unix" namespace for getting the inode of the file. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "unix" namespace for checking if the file represents a UNIX mount point. This attribute is %TRUE if the file is a UNIX mount point. Since 2.58, `/` is considered to be a mount point. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "unix" namespace for getting the mode of the file (e.g. whether the file is a regular file, symlink, etc). See the documentation for `lstat()`: this attribute is equivalent to the `st_mode` member of `struct stat`, and includes both the file type and permissions. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "unix" namespace for getting the number of hard links for a file. See the documentation for `lstat()`. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "unix" namespace for getting the device ID for the file (if it is a special file). See the documentation for `lstat()`. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "unix" namespace for getting the user ID for the file. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. `GFile` is a high level abstraction for manipulating files on a virtual file system. `GFile`s are lightweight, immutable objects that do no I/O upon creation. It is necessary to understand that `GFile` objects do not represent files, merely an identifier for a file. All file content I/O is implemented as streaming operations (see [class@Gio.InputStream] and [class@Gio.OutputStream]). To construct a `GFile`, you can use: - [func@Gio.File.new_for_path] if you have a path. - [func@Gio.File.new_for_uri] if you have a URI. - [func@Gio.File.new_for_commandline_arg] or [func@Gio.File.new_for_commandline_arg_and_cwd] for a command line argument. - [func@Gio.File.new_tmp] to create a temporary file from a template. - [func@Gio.File.new_tmp_async] to asynchronously create a temporary file. - [func@Gio.File.new_tmp_dir_async] to asynchronously create a temporary directory. - [func@Gio.File.parse_name] from a UTF-8 string gotten from [method@Gio.File.get_parse_name]. - [func@Gio.File.new_build_filename] or [func@Gio.File.new_build_filenamev] to create a file from path elements. One way to think of a `GFile` is as an abstraction of a pathname. For normal files the system pathname is what is stored internally, but as `GFile`s are extensible it could also be something else that corresponds to a pathname in a userspace implementation of a filesystem. `GFile`s make up hierarchies of directories and files that correspond to the files on a filesystem. You can move through the file system with `GFile` using [method@Gio.File.get_parent] to get an identifier for the parent directory, [method@Gio.File.get_child] to get a child within a directory, and [method@Gio.File.resolve_relative_path] to resolve a relative path between two `GFile`s. There can be multiple hierarchies, so you may not end up at the same root if you repeatedly call [method@Gio.File.get_parent] on two different files. All `GFile`s have a basename (get with [method@Gio.File.get_basename]). These names are byte strings that are used to identify the file on the filesystem (relative to its parent directory) and there is no guarantees that they have any particular charset encoding or even make any sense at all. If you want to use filenames in a user interface you should use the display name that you can get by requesting the `G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME` attribute with [method@Gio.File.query_info]. This is guaranteed to be in UTF-8 and can be used in a user interface. But always store the real basename or the `GFile` to use to actually access the file, because there is no way to go from a display name to the actual name. Using `GFile` as an identifier has the same weaknesses as using a path in that there may be multiple aliases for the same file. For instance, hard or soft links may cause two different `GFile`s to refer to the same file. Other possible causes for aliases are: case insensitive filesystems, short and long names on FAT/NTFS, or bind mounts in Linux. If you want to check if two `GFile`s point to the same file you can query for the `G_FILE_ATTRIBUTE_ID_FILE` attribute. Note that `GFile` does some trivial canonicalization of pathnames passed in, so that trivial differences in the path string used at creation (duplicated slashes, slash at end of path, `.` or `..` path segments, etc) does not create different `GFile`s. Many `GFile` operations have both synchronous and asynchronous versions to suit your application. Asynchronous versions of synchronous functions simply have `_async()` appended to their function names. The asynchronous I/O functions call a [callback@Gio.AsyncReadyCallback] which is then used to finalize the operation, producing a [iface@Gio.AsyncResult] which is then passed to the function’s matching `_finish()` operation. It is highly recommended to use asynchronous calls when running within a shared main loop, such as in the main thread of an application. This avoids I/O operations blocking other sources on the main loop from being dispatched. Synchronous I/O operations should be performed from worker threads. See the [introduction to asynchronous programming section](overview.html#asynchronous-programming) for more. Some `GFile` operations almost always take a noticeable amount of time, and so do not have synchronous analogs. Notable cases include: - [method@Gio.File.mount_mountable] to mount a mountable file. - [method@Gio.File.unmount_mountable_with_operation] to unmount a mountable file. - [method@Gio.File.eject_mountable_with_operation] to eject a mountable file. ## Entity Tags One notable feature of `GFile`s are entity tags, or ‘etags’ for short. Entity tags are somewhat like a more abstract version of the traditional mtime, and can be used to quickly determine if the file has been modified from the version on the file system. See the description of HTTP ETags in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-etag). `GFile` Entity Tags are a very similar concept. Constructs a #GFile from a series of elements using the correct separator for filenames. Using this function is equivalent to calling g_build_filename(), followed by g_file_new_for_path() on the result. a new #GFile the first element in the path remaining elements in path, terminated by %NULL Constructs a #GFile from a vector of elements using the correct separator for filenames. Using this function is equivalent to calling g_build_filenamev(), followed by g_file_new_for_path() on the result. a new #GFile %NULL-terminated array of strings containing the path elements. Creates a #GFile with the given argument from the command line. The value of @arg can be either a URI, an absolute path or a relative path resolved relative to the current working directory. This operation never fails, but the returned object might not support any I/O operation if @arg points to a malformed path. Note that on Windows, this function expects its argument to be in UTF-8 -- not the system code page. This means that you should not use this function with string from argv as it is passed to main(). g_win32_get_command_line() will return a UTF-8 version of the commandline. #GApplication also uses UTF-8 but g_application_command_line_create_file_for_arg() may be more useful for you there. It is also always possible to use this function with #GOptionContext arguments of type %G_OPTION_ARG_FILENAME. a new #GFile. Free the returned object with g_object_unref(). a command line string Creates a #GFile with the given argument from the command line. This function is similar to g_file_new_for_commandline_arg() except that it allows for passing the current working directory as an argument instead of using the current working directory of the process. This is useful if the commandline argument was given in a context other than the invocation of the current process. See also g_application_command_line_create_file_for_arg(). a new #GFile a command line string the current working directory of the commandline Constructs a #GFile for a given path. This operation never fails, but the returned object might not support any I/O operation if @path is malformed. a new #GFile for the given @path. Free the returned object with g_object_unref(). a string containing a relative or absolute path. The string must be encoded in the glib filename encoding. Constructs a #GFile for a given URI. This operation never fails, but the returned object might not support any I/O operation if @uri is malformed or if the uri type is not supported. a new #GFile for the given @uri. Free the returned object with g_object_unref(). a UTF-8 string containing a URI Opens a file in the preferred directory for temporary files (as returned by g_get_tmp_dir()) and returns a #GFile and #GFileIOStream pointing to it. @tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is %NULL, a default template is used. Unlike the other #GFile constructors, this will return %NULL if a temporary file could not be created. a new #GFile. Free the returned object with g_object_unref(). Template for the file name, as in g_file_open_tmp(), or %NULL for a default template on return, a #GFileIOStream for the created file Asynchronously opens a file in the preferred directory for temporary files (as returned by g_get_tmp_dir()) as g_file_new_tmp(). @tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is %NULL, a default template is used. Template for the file name, as in g_file_open_tmp(), or %NULL for a default template the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is done data to pass to @callback Asynchronously creates a directory in the preferred directory for temporary files (as returned by g_get_tmp_dir()) as g_dir_make_tmp(). @tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is %NULL, a default template is used. Template for the file name, as in g_dir_make_tmp(), or %NULL for a default template the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is done data to pass to @callback Finishes a temporary directory creation started by g_file_new_tmp_dir_async(). a new #GFile. Free the returned object with g_object_unref(). a #GAsyncResult Finishes a temporary file creation started by g_file_new_tmp_async(). a new #GFile. Free the returned object with g_object_unref(). a #GAsyncResult on return, a #GFileIOStream for the created file Constructs a #GFile with the given @parse_name (i.e. something given by g_file_get_parse_name()). This operation never fails, but the returned object might not support any I/O operation if the @parse_name cannot be parsed. a new #GFile. a file name or path to be parsed Gets an output stream for appending data to the file. If the file doesn't already exist it is created. By default files created are generally readable by everyone, but if you pass %G_FILE_CREATE_PRIVATE in @flags the file will be made readable only to the current user, to the level that is supported on the target filesystem. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Some file systems don't allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously opens @file for appending. For more details, see g_file_append_to() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_append_to_finish() to get the result of the operation. input #GFile a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file append operation started with g_file_append_to_async(). a valid #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile #GAsyncResult Copies the file @source to the location specified by @destination. Can not handle recursive copies of directories. If the flag %G_FILE_COPY_OVERWRITE is specified an already existing @destination file is overwritten. If the flag %G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks will be copied as symlinks, otherwise the target of the @source symlink will be copied. If the flag %G_FILE_COPY_ALL_METADATA is specified then all the metadata that is possible to copy is copied, not just the default subset (which, for instance, does not include the owner, see #GFileInfo). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If @progress_callback is not %NULL, then the operation can be monitored by setting this to a #GFileProgressCallback function. @progress_callback_data will be passed to this function. It is guaranteed that this callback will be called after all data has been transferred with the total number of bytes copied during the operation. If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error is returned, independent on the status of the @destination. If %G_FILE_COPY_OVERWRITE is not specified and the target exists, then the error %G_IO_ERROR_EXISTS is returned. If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY error is returned. If trying to overwrite a directory with a directory the %G_IO_ERROR_WOULD_MERGE error is returned. If the source is a directory and the target does not exist, or %G_FILE_COPY_OVERWRITE is specified and the target is a file, then the %G_IO_ERROR_WOULD_RECURSE error is returned. If you are interested in copying the #GFile object itself (not the on-disk file), see g_file_dup(). %TRUE on success, %FALSE otherwise. input #GFile destination #GFile set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore function to callback with progress information, or %NULL if progress information is not needed user data to pass to @progress_callback Copies the file @source to the location specified by @destination asynchronously. For details of the behaviour, see g_file_copy(). If @progress_callback is not %NULL, then that function that will be called just like in g_file_copy(). The callback will run in the default main context of the thread calling g_file_copy_async() — the same context as @callback is run in. When the operation is finished, @callback will be called. You can then call g_file_copy_finish() to get the result of the operation. input #GFile destination #GFile set of #GFileCopyFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore function to callback with progress information, or %NULL if progress information is not needed user data to pass to @progress_callback a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback Finishes copying the file started with g_file_copy_async(). a %TRUE on success, %FALSE on error. input #GFile a #GAsyncResult Creates a new file and returns an output stream for writing to it. The file must not already exist. By default files created are generally readable by everyone, but if you pass %G_FILE_CREATE_PRIVATE in @flags the file will be made readable only to the current user, to the level that is supported on the target filesystem. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If a file or directory with this name already exists the %G_IO_ERROR_EXISTS error will be returned. Some file systems don't allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. a #GFileOutputStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously creates a new file and returns an output stream for writing to it. The file must not already exist. For more details, see g_file_create() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_create_finish() to get the result of the operation. input #GFile a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file create operation started with g_file_create_async(). a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Creates a new file and returns a stream for reading and writing to it. The file must not already exist. By default files created are generally readable by everyone, but if you pass %G_FILE_CREATE_PRIVATE in @flags the file will be made readable only to the current user, to the level that is supported on the target filesystem. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If a file or directory with this name already exists, the %G_IO_ERROR_EXISTS error will be returned. Some file systems don't allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. a #GFileIOStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). a #GFile a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously creates a new file and returns a stream for reading and writing to it. The file must not already exist. For more details, see g_file_create_readwrite() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_create_readwrite_finish() to get the result of the operation. input #GFile a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file create operation started with g_file_create_readwrite_async(). a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Deletes a file. If the @file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink(). If @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows for deletion to be implemented avoiding [time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use): |[ g_autoptr(GError) local_error = NULL; if (!g_file_delete (my_file, my_cancellable, &local_error) && !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND)) { // deletion failed for some reason other than the file not existing: // so report the error g_warning ("Failed to delete %s: %s", g_file_peek_path (my_file), local_error->message); } ]| If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if the file was deleted. %FALSE otherwise. input #GFile optional #GCancellable object, %NULL to ignore Asynchronously delete a file. If the @file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink(). input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes deleting a file started with g_file_delete_async(). %TRUE if the file was deleted. %FALSE otherwise. input #GFile a #GAsyncResult Duplicates a #GFile handle. This operation does not duplicate the actual file or directory represented by the #GFile; see g_file_copy() if attempting to copy a file. g_file_dup() is useful when a second handle is needed to the same underlying file, for use in a separate thread (#GFile is not thread-safe). For use within the same thread, use g_object_ref() to increment the existing object’s reference count. This call does no blocking I/O. a new #GFile that is a duplicate of the given #GFile. input #GFile Starts an asynchronous eject on a mountable. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_eject_mountable_finish(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Use g_file_eject_mountable_with_operation() instead. input #GFile flags affecting the operation optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous eject operation started by g_file_eject_mountable(). Use g_file_eject_mountable_with_operation_finish() instead. %TRUE if the @file was ejected successfully. %FALSE otherwise. input #GFile a #GAsyncResult Starts an asynchronous eject on a mountable. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_eject_mountable_with_operation_finish(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous eject operation started by g_file_eject_mountable_with_operation(). %TRUE if the @file was ejected successfully. %FALSE otherwise. input #GFile a #GAsyncResult Gets the requested information about the files in a directory. The result is a #GFileEnumerator object that will give out #GFileInfo objects for all the files in the directory. The @attributes value is a string that specifies the file attributes that should be gathered. It is not an error if it's not possible to read a particular requested attribute from a file - it just won't be set. @attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "standard::*" means all attributes in the standard namespace. An example attribute query be "standard::*,owner::user". The standard attributes are available as defines, like %G_FILE_ATTRIBUTE_STANDARD_NAME. %G_FILE_ATTRIBUTE_STANDARD_NAME should always be specified if you plan to call g_file_enumerator_get_child() or g_file_enumerator_iterate() on the returned enumerator. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY error will be returned. Other errors are possible too. A #GFileEnumerator if successful, %NULL on error. Free the returned object with g_object_unref(). input #GFile an attribute query string a set of #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Asynchronously gets the requested information about the files in a directory. The result is a #GFileEnumerator object that will give out #GFileInfo objects for all the files in the directory. For more details, see g_file_enumerate_children() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_enumerate_children_finish() to get the result of the operation. input #GFile an attribute query string a set of #GFileQueryInfoFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an async enumerate children operation. See g_file_enumerate_children_async(). a #GFileEnumerator or %NULL if an error occurred. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Checks if the two given #GFiles refer to the same file. This function can be used with [method@Gio.File.hash] to insert [iface@Gio.File]s efficiently in a hash table. Note that two #GFiles that differ can still refer to the same file on the filesystem due to various forms of filename aliasing. For local files, this function essentially compares the file paths, so two [iface@Gio.File]s which point to different hard or soft links will not be considered equal, despite pointing to the same content. For determining whether two files are hardlinked, see [const@Gio.FILE_ATTRIBUTE_ID_FILE]. This call does no blocking I/O. %TRUE if @file1 and @file2 are equal. the first #GFile the second #GFile Gets a #GMount for the #GFile. #GMount is returned only for user interesting locations, see #GVolumeMonitor. If the #GFileIface for @file does not have a #mount, @error will be set to %G_IO_ERROR_NOT_FOUND and %NULL #will be returned. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GMount where the @file is located or %NULL on error. Free the returned object with g_object_unref(). input #GFile optional #GCancellable object, %NULL to ignore Asynchronously gets the mount for the file. For more details, see g_file_find_enclosing_mount() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_find_enclosing_mount_finish() to get the result of the operation. a #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous find mount request. See g_file_find_enclosing_mount_async(). #GMount for given @file or %NULL on error. Free the returned object with g_object_unref(). a #GFile a #GAsyncResult Gets the base name (the last component of the path) for a given #GFile. If called for the top level of a system (such as the filesystem root or a uri like sftp://host/) it will return a single directory separator (and on Windows, possibly a drive letter). The base name is a byte string (not UTF-8). It has no defined encoding or rules other than it may not contain zero bytes. If you want to use filenames in a user interface you should use the display name that you can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info(). This call does no blocking I/O. string containing the #GFile's base name, or %NULL if given #GFile is invalid. The returned string should be freed with g_free() when no longer needed. input #GFile Gets the child of @file for a given @display_name (i.e. a UTF-8 version of the name). If this function fails, it returns %NULL and @error will be set. This is very useful when constructing a #GFile for a new file and the user entered the filename in the user interface, for instance when you select a directory and type a filename in the file selector. This call does no blocking I/O. a #GFile to the specified child, or %NULL if the display name couldn't be converted. Free the returned object with g_object_unref(). input #GFile string to a possible child Gets the parent directory for the @file. If the @file represents the root directory of the file system, then %NULL will be returned. This call does no blocking I/O. a #GFile structure to the parent of the given #GFile or %NULL if there is no parent. Free the returned object with g_object_unref(). input #GFile Gets the parse name of the @file. A parse name is a UTF-8 string that describes the file such that one can get the #GFile back using g_file_parse_name(). This is generally used to show the #GFile as a nice full-pathname kind of string in a user interface, like in a location entry. For local files with names that can safely be converted to UTF-8 the pathname is used, otherwise the IRI is used (a form of URI that allows UTF-8 characters unescaped). This call does no blocking I/O. a string containing the #GFile's parse name. The returned string should be freed with g_free() when no longer needed. input #GFile Gets the local pathname for #GFile, if one exists. If non-%NULL, this is guaranteed to be an absolute, canonical path. It might contain symlinks. This call does no blocking I/O. string containing the #GFile's path, or %NULL if no such path exists. The returned string should be freed with g_free() when no longer needed. input #GFile Gets the path for @descendant relative to @parent. This call does no blocking I/O. string with the relative path from @descendant to @parent, or %NULL if @descendant doesn't have @parent as prefix. The returned string should be freed with g_free() when no longer needed. input #GFile input #GFile Gets the URI for the @file. This call does no blocking I/O. a string containing the #GFile's URI. If the #GFile was constructed with an invalid URI, an invalid URI is returned. The returned string should be freed with g_free() when no longer needed. input #GFile Gets the URI scheme for a #GFile. RFC 3986 decodes the scheme as: |[ URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] ]| Common schemes include "file", "http", "ftp", etc. The scheme can be different from the one used to construct the #GFile, in that it might be replaced with one that is logically equivalent to the #GFile. This call does no blocking I/O. a string containing the URI scheme for the given #GFile or %NULL if the #GFile was constructed with an invalid URI. The returned string should be freed with g_free() when no longer needed. input #GFile Checks to see if a #GFile has a given URI scheme. This call does no blocking I/O. %TRUE if #GFile's backend supports the given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid. input #GFile a string containing a URI scheme Creates a hash value for a #GFile. This call does no blocking I/O. 0 if @file is not a valid #GFile, otherwise an integer that can be used as hash value for the #GFile. This function is intended for easily hashing a #GFile to add to a #GHashTable or similar data structure. #gconstpointer to a #GFile Checks to see if a file is native to the platform. A native file is one expressed in the platform-native filename format, e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local, as it might be on a locally mounted remote filesystem. On some systems non-native files may be available using the native filesystem via a userspace filesystem (FUSE), in these cases this call will return %FALSE, but g_file_get_path() will still return a native path. This call does no blocking I/O. %TRUE if @file is native input #GFile Creates a directory. Note that this will only create a child directory of the immediate parent directory of the path or URI given by the #GFile. To recursively create directories, see g_file_make_directory_with_parents(). This function will fail if the parent directory does not exist, setting @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support creating directories, this function will fail, setting @error to %G_IO_ERROR_NOT_SUPPORTED. If the directory already exists, [error@Gio.IOErrorEnum.EXISTS] will be returned. For a local #GFile the newly created directory will have the default (current) ownership and permissions of the current process. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE on successful creation, %FALSE otherwise. input #GFile optional #GCancellable object, %NULL to ignore Asynchronously creates a directory. input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous directory creation, started with g_file_make_directory_async(). %TRUE on successful directory creation, %FALSE otherwise. input #GFile a #GAsyncResult Creates a symbolic link named @file which contains the string @symlink_value. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE on the creation of a new symlink, %FALSE otherwise. a #GFile with the name of the symlink to create a string with the path for the target of the new symlink optional #GCancellable object, %NULL to ignore Asynchronously creates a symbolic link named @file which contains the string @symlink_value. a #GFile with the name of the symlink to create a string with the path for the target of the new symlink the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous symbolic link creation, started with g_file_make_symbolic_link_async(). %TRUE on successful directory creation, %FALSE otherwise. input #GFile a #GAsyncResult Recursively measures the disk usage of @file. This is essentially an analog of the 'du' command, but it also reports the number of directories and non-directory files encountered (including things like symbolic links). By default, errors are only reported against the toplevel file itself. Errors found while recursing are silently ignored, unless %G_FILE_MEASURE_REPORT_ANY_ERROR is given in @flags. The returned size, @disk_usage, is in bytes and should be formatted with g_format_size() in order to get something reasonable for showing in a user interface. @progress_callback and @progress_data can be given to request periodic progress updates while scanning. See the documentation for #GFileMeasureProgressCallback for information about when and how the callback will be invoked. %TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. a #GFile #GFileMeasureFlags optional #GCancellable a #GFileMeasureProgressCallback user_data for @progress_callback the number of bytes of disk space used the number of directories encountered the number of non-directories encountered Recursively measures the disk usage of @file. This is the asynchronous version of g_file_measure_disk_usage(). See there for more information. a #GFile #GFileMeasureFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable a #GFileMeasureProgressCallback user_data for @progress_callback a #GAsyncReadyCallback to call when complete the data to pass to callback function Collects the results from an earlier call to g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for more information. %TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. a #GFile the #GAsyncResult passed to your #GAsyncReadyCallback the number of bytes of disk space used the number of directories encountered the number of non-directories encountered Obtains a directory monitor for the given file. This may fail if directory monitoring is not supported. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. It does not make sense for @flags to contain %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to directories. It is not possible to monitor all the files in a directory for changes made via hard links; if you want to do this then you must register individual watches with g_file_monitor(). a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a set of #GFileMonitorFlags optional #GCancellable object, %NULL to ignore Obtains a file monitor for the given file. If no file notification mechanism exists, then regular polling of the file is used. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor will also attempt to report changes made to the file via another filename (ie, a hard link). Without this flag, you can only rely on changes made through the filename contained in @file to be reported. Using this flag may result in an increase in resource usage, and may not have any effect depending on the #GFileMonitor backend and/or filesystem type. a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a set of #GFileMonitorFlags optional #GCancellable object, %NULL to ignore Starts a @mount_operation, mounting the volume that contains the file @location. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_mount_enclosing_volume_finish(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile flags affecting the operation a #GMountOperation or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a mount operation started by g_file_mount_enclosing_volume(). %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. input #GFile a #GAsyncResult Mounts a file of type G_FILE_TYPE_MOUNTABLE. Using @mount_operation, you can request callbacks when, for instance, passwords are needed during authentication. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes a mount operation. See g_file_mount_mountable() for details. Finish an asynchronous mount operation that was started with g_file_mount_mountable(). a #GFile or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Tries to move the file or directory @source to the location specified by @destination. If native move operations are supported then this is used, otherwise a copy + delete fallback is used. The native implementation may support moving directories (for instance on moves inside the same filesystem), but the fallback code does not. If the flag %G_FILE_COPY_OVERWRITE is specified an already existing @destination file is overwritten. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If @progress_callback is not %NULL, then the operation can be monitored by setting this to a #GFileProgressCallback function. @progress_callback_data will be passed to this function. It is guaranteed that this callback will be called after all data has been transferred with the total number of bytes copied during the operation. If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error is returned, independent on the status of the @destination. If %G_FILE_COPY_OVERWRITE is not specified and the target exists, then the error %G_IO_ERROR_EXISTS is returned. If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY error is returned. If trying to overwrite a directory with a directory the %G_IO_ERROR_WOULD_MERGE error is returned. If the source is a directory and the target does not exist, or %G_FILE_COPY_OVERWRITE is specified and the target is a file, then the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native move operation isn't available). %TRUE on successful move, %FALSE otherwise. #GFile pointing to the source location #GFile pointing to the destination location set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore #GFileProgressCallback function for updates gpointer to user data for the callback function Asynchronously moves a file @source to the location of @destination. For details of the behaviour, see g_file_move(). If @progress_callback is not %NULL, then that function that will be called just like in g_file_move(). The callback will run in the default main context of the thread calling g_file_move_async() — the same context as @callback is run in. When the operation is finished, @callback will be called. You can then call g_file_move_finish() to get the result of the operation. #GFile pointing to the source location #GFile pointing to the destination location set of #GFileCopyFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore #GFileProgressCallback function for updates gpointer to user data for the callback function a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file movement, started with g_file_move_async(). %TRUE on successful file move, %FALSE otherwise. input source #GFile a #GAsyncResult Opens an existing file for reading and writing. The result is a #GFileIOStream that can be used to read and write the contents of the file. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). #GFile to open a #GCancellable Asynchronously opens @file for reading and writing. For more details, see g_file_open_readwrite() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_open_readwrite_finish() to get the result of the operation. input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file read operation started with g_file_open_readwrite_async(). a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Polls a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation. input #GFile optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a poll operation. See g_file_poll_mountable() for details. Finish an asynchronous poll operation that was polled with g_file_poll_mountable(). %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Checks whether @file has the prefix specified by @prefix. In other words, if the names of initial elements of @file's pathname match @prefix. Only full pathname elements are matched, so a path like /foo is not considered a prefix of /foobar, only of /foo/bar. A #GFile is not a prefix of itself. If you want to check for equality, use g_file_equal(). This call does no I/O, as it works purely on names. As such it can sometimes return %FALSE even if @file is inside a @prefix (from a filesystem point of view), because the prefix of @file is an alias of @prefix. %TRUE if the @file's parent, grandparent, etc is @prefix, %FALSE otherwise. input #GFile input #GFile Utility function to check if a particular file exists. The fallback implementation of this API is using [method@Gio.File.query_info] and therefore may do blocking I/O. To asynchronously query the existence of a file, use [method@Gio.File.query_info_async]. Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use) and then execute something based on the outcome of that, because the file might have been created or removed in between the operations. The general approach to handling that is to not check, but just do the operation and handle the errors as they come. As an example of race-free checking, take the case of reading a file, and if it doesn't exist, creating it. There are two racy versions: read it, and on error create it; and: check if it exists, if not create it. These can both result in two processes creating the file (with perhaps a partially written file as the result). The correct approach is to always try to create the file with g_file_create() which will either atomically create the file or fail with a %G_IO_ERROR_EXISTS error. However, in many cases an existence check is useful in a user interface, for instance to make a menu item sensitive/insensitive, so that you don't have to fool users that something is possible and then just show an error dialog. If you do this, you should make sure to also handle the errors that can happen due to races when you execute the operation. %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled). input #GFile optional #GCancellable object, %NULL to ignore Similar to g_file_query_info(), but obtains information about the filesystem the @file is on, rather than the file itself. For instance the amount of space available and the type of the filesystem. The @attributes value is a string that specifies the attributes that should be gathered. It is not an error if it's not possible to read a particular requested attribute from a file - it just won't be set. @attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "filesystem::*" means all attributes in the filesystem namespace. The standard namespace for filesystem attributes is "filesystem". Common attributes of interest are %G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem in bytes), %G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available), and %G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. a #GFileInfo or %NULL if there was an error. Free the returned object with g_object_unref(). input #GFile an attribute query string optional #GCancellable object, %NULL to ignore Asynchronously gets the requested information about the filesystem that the specified @file is on. The result is a #GFileInfo object that contains key-value attributes (such as type or size for the file). For more details, see g_file_query_filesystem_info() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_query_info_finish() to get the result of the operation. input #GFile an attribute query string the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous filesystem info query. See g_file_query_filesystem_info_async(). #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Gets the requested information about specified @file. The result is a [class@Gio.FileInfo] object that contains key-value attributes (such as the type or size of the file). The @attributes value is a string that specifies the file attributes that should be gathered. It is not an error if it’s not possible to read a particular requested attribute from a file — it just won't be set. In particular this means that if a file is inaccessible (due to being in a folder with restrictive permissions), for example, you can expect the returned [class@Gio.FileInfo] to have very few attributes set. You should check whether an attribute is set using [method@Gio.FileInfo.has_attribute] before trying to retrieve its value. It is guaranteed that if any of the following attributes are listed in @attributes, they will always be set in the returned [class@Gio.FileInfo], even if the user doesn’t have permissions to access the file: - [const@Gio.FILE_ATTRIBUTE_STANDARD_NAME] - [const@Gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME] @attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard `"*"` means all attributes, and a wildcard like `"standard::*"` means all attributes in the standard namespace. An example attribute query might be `"standard::*,owner::user"`. The standard attributes are available as defines, like [const@Gio.FILE_ATTRIBUTE_STANDARD_NAME]. If @cancellable is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error [error@Gio.IOErrorEnum.CANCELLED] will be returned. For symlinks, normally the information about the target of the symlink is returned, rather than information about the symlink itself. However if you pass [flags@Gio.FileQueryInfoFlags.NOFOLLOW_SYMLINKS] in @flags the information about the symlink itself will be returned. Also, for symlinks that point to non-existing files the information about the symlink itself will be returned. If the file does not exist, the [error@Gio.IOErrorEnum.NOT_FOUND] error will be returned. Other errors are possible too, and depend on what kind of file system the file is on. a [class@Gio.FileInfo] for the given @file input file an attribute query string flags to affect the query operation optional cancellable object Asynchronously gets the requested information about specified @file. The result is a #GFileInfo object that contains key-value attributes (such as type or size for the file). For more details, see g_file_query_info() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_query_info_finish() to get the result of the operation. input #GFile an attribute query string a set of #GFileQueryInfoFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file info query. See g_file_query_info_async(). #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Obtain the list of settable attributes for the file. Returns the type and full attribute name of all the attributes that can be set on this file. This doesn't mean setting it will always succeed though, you might get an access failure, or some specific file may not support a specific attribute. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GFileAttributeInfoList describing the settable attributes. When you are done with it, release it with g_file_attribute_info_list_unref() input #GFile optional #GCancellable object, %NULL to ignore Obtain the list of attribute namespaces where new attributes can be created by a user. An example of this is extended attributes (in the "xattr" namespace). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GFileAttributeInfoList describing the writable namespaces. When you are done with it, release it with g_file_attribute_info_list_unref() input #GFile optional #GCancellable object, %NULL to ignore Asynchronously opens @file for reading. For more details, see g_file_read() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_read_finish() to get the result of the operation. input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file read operation started with g_file_read_async(). a #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Opens a file for reading. The result is a #GFileInputStream that can be used to read the contents of the file. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). #GFile to read a #GCancellable Returns an output stream for overwriting the file, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created. This will try to replace the file in the safest way possible so that any errors during the writing will not affect an already existing copy of the file. For instance, for local files it may write to a temporary file and then atomically rename over the destination when the stream is closed. By default files created are generally readable by everyone, but if you pass %G_FILE_CREATE_PRIVATE in @flags the file will be made readable only to the current user, to the level that is supported on the target filesystem. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If you pass in a non-%NULL @etag value and @file already exists, then this value is compared to the current entity tag of the file, and if they differ an %G_IO_ERROR_WRONG_ETAG error is returned. This generally means that the file has been changed since you last read it. You can get the new etag from g_file_output_stream_get_etag() after you've finished writing and closed the #GFileOutputStream. When you load a new file you can use g_file_input_stream_query_info() to get the etag of the file. If @make_backup is %TRUE, this function will attempt to make a backup of the current file before overwriting it. If this fails a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you want to replace anyway, try again with @make_backup set to %FALSE. If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will be returned, and if the file is some other form of non-regular file then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some file systems don't allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first. For more details, see g_file_replace() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_replace_finish() to get the result of the operation. input #GFile an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file replace operation started with g_file_replace_async(). a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Returns an output stream for overwriting the file in readwrite mode, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created. For details about the behaviour, see g_file_replace() which does the same thing but returns an output stream only. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). a #GFile an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously overwrites the file in read-write mode, replacing the contents, possibly creating a backup copy of the file first. For more details, see g_file_replace_readwrite() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_replace_readwrite_finish() to get the result of the operation. input #GFile an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file replace operation started with g_file_replace_readwrite_async(). a #GFileIOStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Resolves a relative path for @file to an absolute path. This call does no blocking I/O. If the @relative_path is an absolute path name, the resolution is done absolutely (without taking @file path as base). a #GFile for the resolved path. input #GFile a given relative path string Sets an attribute in the file with attribute name @attribute to @value_p. Some attributes can be unset by setting @type to %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if the attribute was set, %FALSE otherwise. input #GFile a string containing the attribute's name The type of the attribute a pointer to the value (or the pointer itself if the type is a pointer type) a set of #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Asynchronously sets the attributes of @file with @info. For more details, see g_file_set_attributes_from_info(), which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_set_attributes_finish() to get the result of the operation. input #GFile a #GFileInfo a #GFileQueryInfoFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes setting an attribute started in g_file_set_attributes_async(). %TRUE if the attributes were set correctly, %FALSE otherwise. input #GFile a #GAsyncResult a #GFileInfo Tries to set all attributes in the #GFileInfo on the target values, not stopping on the first error. If there is any error during this operation then @error will be set to the first error. Error on particular fields are flagged by setting the "status" field in the attribute value to %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can also detect further errors. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %FALSE if there was any error, %TRUE otherwise. input #GFile a #GFileInfo #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Renames @file to the specified display name. The display name is converted from UTF-8 to the correct encoding for the target filesystem if possible and the @file is renamed to this. If you want to implement a rename operation in the user interface the edit name (%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the initial value in the rename widget, and then the result after editing should be passed to g_file_set_display_name(). On success the resulting converted filename is returned. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GFile specifying what @file was renamed to, or %NULL if there was an error. Free the returned object with g_object_unref(). input #GFile a string optional #GCancellable object, %NULL to ignore Asynchronously sets the display name for a given #GFile. For more details, see g_file_set_display_name() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_set_display_name_finish() to get the result of the operation. input #GFile a string the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes setting a display name started with g_file_set_display_name_async(). a #GFile or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Starts a file of type %G_FILE_TYPE_MOUNTABLE. Using @start_operation, you can request callbacks when, for instance, passwords are needed during authentication. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a start operation. See g_file_start_mountable() for details. Finish an asynchronous start operation that was started with g_file_start_mountable(). %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Stops a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_stop_mountable_finish() to get the result of the operation. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a stop operation, see g_file_stop_mountable() for details. Finish an asynchronous stop operation that was started with g_file_stop_mountable(). %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Sends @file to the "Trashcan", if possible. This is similar to deleting it, but the user can recover it before emptying the trashcan. Trashing is disabled for system mounts by default (see g_unix_mount_entry_is_system_internal()), so this call can return the %G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix mount option can be used to disable g_file_trash() support for particular mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case. Since 2.82, the `x-gvfs-trash` unix mount option can be used to enable g_file_trash() support for particular system mounts. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE on successful trash, %FALSE otherwise. #GFile to send to trash optional #GCancellable object, %NULL to ignore Asynchronously sends @file to the Trash location, if possible. input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file trashing operation, started with g_file_trash_async(). %TRUE on successful trash, %FALSE otherwise. input #GFile a #GAsyncResult Unmounts a file of type G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_unmount_mountable_finish() to get the result of the operation. Use g_file_unmount_mountable_with_operation() instead. input #GFile flags affecting the operation optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an unmount operation, see g_file_unmount_mountable() for details. Finish an asynchronous unmount operation that was started with g_file_unmount_mountable(). Use g_file_unmount_mountable_with_operation_finish() instead. %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Unmounts a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_unmount_mountable_finish() to get the result of the operation. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an unmount operation, see g_file_unmount_mountable_with_operation() for details. Finish an asynchronous unmount operation that was started with g_file_unmount_mountable_with_operation(). %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Gets an output stream for appending data to the file. If the file doesn't already exist it is created. By default files created are generally readable by everyone, but if you pass %G_FILE_CREATE_PRIVATE in @flags the file will be made readable only to the current user, to the level that is supported on the target filesystem. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Some file systems don't allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously opens @file for appending. For more details, see g_file_append_to() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_append_to_finish() to get the result of the operation. input #GFile a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file append operation started with g_file_append_to_async(). a valid #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile #GAsyncResult Prepares the file attribute query string for copying to @file. This function prepares an attribute query string to be passed to g_file_query_info() to get a list of attributes normally copied with the file (see g_file_copy_attributes() for the detailed description). This function is used by the implementation of g_file_copy_attributes() and is useful when one needs to query and set the attributes in two stages (e.g., for recursive move of a directory). an attribute query string for g_file_query_info(), or %NULL if an error occurs. a #GFile to copy attributes to a set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore Copies the file @source to the location specified by @destination. Can not handle recursive copies of directories. If the flag %G_FILE_COPY_OVERWRITE is specified an already existing @destination file is overwritten. If the flag %G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks will be copied as symlinks, otherwise the target of the @source symlink will be copied. If the flag %G_FILE_COPY_ALL_METADATA is specified then all the metadata that is possible to copy is copied, not just the default subset (which, for instance, does not include the owner, see #GFileInfo). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If @progress_callback is not %NULL, then the operation can be monitored by setting this to a #GFileProgressCallback function. @progress_callback_data will be passed to this function. It is guaranteed that this callback will be called after all data has been transferred with the total number of bytes copied during the operation. If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error is returned, independent on the status of the @destination. If %G_FILE_COPY_OVERWRITE is not specified and the target exists, then the error %G_IO_ERROR_EXISTS is returned. If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY error is returned. If trying to overwrite a directory with a directory the %G_IO_ERROR_WOULD_MERGE error is returned. If the source is a directory and the target does not exist, or %G_FILE_COPY_OVERWRITE is specified and the target is a file, then the %G_IO_ERROR_WOULD_RECURSE error is returned. If you are interested in copying the #GFile object itself (not the on-disk file), see g_file_dup(). %TRUE on success, %FALSE otherwise. input #GFile destination #GFile set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore function to callback with progress information, or %NULL if progress information is not needed user data to pass to @progress_callback Copies the file @source to the location specified by @destination asynchronously. For details of the behaviour, see g_file_copy(). If @progress_callback is not %NULL, then that function that will be called just like in g_file_copy(). The callback will run in the default main context of the thread calling g_file_copy_async() — the same context as @callback is run in. When the operation is finished, @callback will be called. You can then call g_file_copy_finish() to get the result of the operation. input #GFile destination #GFile set of #GFileCopyFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore function to callback with progress information, or %NULL if progress information is not needed user data to pass to @progress_callback a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback Version of [method@Gio.File.copy_async] using closures instead of callbacks for easier binding in other languages. input [type@Gio.File] destination [type@Gio.File] set of [flags@Gio.FileCopyFlags] the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional [class@Gio.Cancellable] object, `NULL` to ignore [type@GObject.Closure] to invoke with progress information, or `NULL` if progress information is not needed [type@GObject.Closure] to invoke when the request is satisfied Copies the file attributes from @source to @destination. Normally only a subset of the file attributes are copied, those that are copies in a normal file copy operation (which for instance does not include e.g. owner). However if %G_FILE_COPY_ALL_METADATA is specified in @flags, then all the metadata that is possible to copy is copied. This is useful when implementing move by copy + delete source. %TRUE if the attributes were copied successfully, %FALSE otherwise. a #GFile with attributes a #GFile to copy attributes to a set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore Finishes copying the file started with g_file_copy_async(). a %TRUE on success, %FALSE on error. input #GFile a #GAsyncResult Creates a new file and returns an output stream for writing to it. The file must not already exist. By default files created are generally readable by everyone, but if you pass %G_FILE_CREATE_PRIVATE in @flags the file will be made readable only to the current user, to the level that is supported on the target filesystem. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If a file or directory with this name already exists the %G_IO_ERROR_EXISTS error will be returned. Some file systems don't allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. a #GFileOutputStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously creates a new file and returns an output stream for writing to it. The file must not already exist. For more details, see g_file_create() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_create_finish() to get the result of the operation. input #GFile a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file create operation started with g_file_create_async(). a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Creates a new file and returns a stream for reading and writing to it. The file must not already exist. By default files created are generally readable by everyone, but if you pass %G_FILE_CREATE_PRIVATE in @flags the file will be made readable only to the current user, to the level that is supported on the target filesystem. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If a file or directory with this name already exists, the %G_IO_ERROR_EXISTS error will be returned. Some file systems don't allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. a #GFileIOStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). a #GFile a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously creates a new file and returns a stream for reading and writing to it. The file must not already exist. For more details, see g_file_create_readwrite() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_create_readwrite_finish() to get the result of the operation. input #GFile a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file create operation started with g_file_create_readwrite_async(). a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Deletes a file. If the @file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink(). If @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows for deletion to be implemented avoiding [time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use): |[ g_autoptr(GError) local_error = NULL; if (!g_file_delete (my_file, my_cancellable, &local_error) && !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND)) { // deletion failed for some reason other than the file not existing: // so report the error g_warning ("Failed to delete %s: %s", g_file_peek_path (my_file), local_error->message); } ]| If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if the file was deleted. %FALSE otherwise. input #GFile optional #GCancellable object, %NULL to ignore Asynchronously delete a file. If the @file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink(). input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes deleting a file started with g_file_delete_async(). %TRUE if the file was deleted. %FALSE otherwise. input #GFile a #GAsyncResult Duplicates a #GFile handle. This operation does not duplicate the actual file or directory represented by the #GFile; see g_file_copy() if attempting to copy a file. g_file_dup() is useful when a second handle is needed to the same underlying file, for use in a separate thread (#GFile is not thread-safe). For use within the same thread, use g_object_ref() to increment the existing object’s reference count. This call does no blocking I/O. a new #GFile that is a duplicate of the given #GFile. input #GFile Starts an asynchronous eject on a mountable. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_eject_mountable_finish(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Use g_file_eject_mountable_with_operation() instead. input #GFile flags affecting the operation optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous eject operation started by g_file_eject_mountable(). Use g_file_eject_mountable_with_operation_finish() instead. %TRUE if the @file was ejected successfully. %FALSE otherwise. input #GFile a #GAsyncResult Starts an asynchronous eject on a mountable. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_eject_mountable_with_operation_finish(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous eject operation started by g_file_eject_mountable_with_operation(). %TRUE if the @file was ejected successfully. %FALSE otherwise. input #GFile a #GAsyncResult Gets the requested information about the files in a directory. The result is a #GFileEnumerator object that will give out #GFileInfo objects for all the files in the directory. The @attributes value is a string that specifies the file attributes that should be gathered. It is not an error if it's not possible to read a particular requested attribute from a file - it just won't be set. @attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "standard::*" means all attributes in the standard namespace. An example attribute query be "standard::*,owner::user". The standard attributes are available as defines, like %G_FILE_ATTRIBUTE_STANDARD_NAME. %G_FILE_ATTRIBUTE_STANDARD_NAME should always be specified if you plan to call g_file_enumerator_get_child() or g_file_enumerator_iterate() on the returned enumerator. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY error will be returned. Other errors are possible too. A #GFileEnumerator if successful, %NULL on error. Free the returned object with g_object_unref(). input #GFile an attribute query string a set of #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Asynchronously gets the requested information about the files in a directory. The result is a #GFileEnumerator object that will give out #GFileInfo objects for all the files in the directory. For more details, see g_file_enumerate_children() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_enumerate_children_finish() to get the result of the operation. input #GFile an attribute query string a set of #GFileQueryInfoFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an async enumerate children operation. See g_file_enumerate_children_async(). a #GFileEnumerator or %NULL if an error occurred. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Checks if the two given #GFiles refer to the same file. This function can be used with [method@Gio.File.hash] to insert [iface@Gio.File]s efficiently in a hash table. Note that two #GFiles that differ can still refer to the same file on the filesystem due to various forms of filename aliasing. For local files, this function essentially compares the file paths, so two [iface@Gio.File]s which point to different hard or soft links will not be considered equal, despite pointing to the same content. For determining whether two files are hardlinked, see [const@Gio.FILE_ATTRIBUTE_ID_FILE]. This call does no blocking I/O. %TRUE if @file1 and @file2 are equal. the first #GFile the second #GFile Gets a #GMount for the #GFile. #GMount is returned only for user interesting locations, see #GVolumeMonitor. If the #GFileIface for @file does not have a #mount, @error will be set to %G_IO_ERROR_NOT_FOUND and %NULL #will be returned. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GMount where the @file is located or %NULL on error. Free the returned object with g_object_unref(). input #GFile optional #GCancellable object, %NULL to ignore Asynchronously gets the mount for the file. For more details, see g_file_find_enclosing_mount() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_find_enclosing_mount_finish() to get the result of the operation. a #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous find mount request. See g_file_find_enclosing_mount_async(). #GMount for given @file or %NULL on error. Free the returned object with g_object_unref(). a #GFile a #GAsyncResult Gets the base name (the last component of the path) for a given #GFile. If called for the top level of a system (such as the filesystem root or a uri like sftp://host/) it will return a single directory separator (and on Windows, possibly a drive letter). The base name is a byte string (not UTF-8). It has no defined encoding or rules other than it may not contain zero bytes. If you want to use filenames in a user interface you should use the display name that you can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info(). This call does no blocking I/O. string containing the #GFile's base name, or %NULL if given #GFile is invalid. The returned string should be freed with g_free() when no longer needed. input #GFile Gets a child of @file with basename equal to @name. Note that the file with that specific name might not exist, but you can still have a #GFile that points to it. You can use this for instance to create that file. This call does no blocking I/O. a #GFile to a child specified by @name. Free the returned object with g_object_unref(). input #GFile string containing the child's basename Gets the child of @file for a given @display_name (i.e. a UTF-8 version of the name). If this function fails, it returns %NULL and @error will be set. This is very useful when constructing a #GFile for a new file and the user entered the filename in the user interface, for instance when you select a directory and type a filename in the file selector. This call does no blocking I/O. a #GFile to the specified child, or %NULL if the display name couldn't be converted. Free the returned object with g_object_unref(). input #GFile string to a possible child Gets the parent directory for the @file. If the @file represents the root directory of the file system, then %NULL will be returned. This call does no blocking I/O. a #GFile structure to the parent of the given #GFile or %NULL if there is no parent. Free the returned object with g_object_unref(). input #GFile Gets the parse name of the @file. A parse name is a UTF-8 string that describes the file such that one can get the #GFile back using g_file_parse_name(). This is generally used to show the #GFile as a nice full-pathname kind of string in a user interface, like in a location entry. For local files with names that can safely be converted to UTF-8 the pathname is used, otherwise the IRI is used (a form of URI that allows UTF-8 characters unescaped). This call does no blocking I/O. a string containing the #GFile's parse name. The returned string should be freed with g_free() when no longer needed. input #GFile Gets the local pathname for #GFile, if one exists. If non-%NULL, this is guaranteed to be an absolute, canonical path. It might contain symlinks. This call does no blocking I/O. string containing the #GFile's path, or %NULL if no such path exists. The returned string should be freed with g_free() when no longer needed. input #GFile Gets the path for @descendant relative to @parent. This call does no blocking I/O. string with the relative path from @descendant to @parent, or %NULL if @descendant doesn't have @parent as prefix. The returned string should be freed with g_free() when no longer needed. input #GFile input #GFile Gets the URI for the @file. This call does no blocking I/O. a string containing the #GFile's URI. If the #GFile was constructed with an invalid URI, an invalid URI is returned. The returned string should be freed with g_free() when no longer needed. input #GFile Gets the URI scheme for a #GFile. RFC 3986 decodes the scheme as: |[ URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] ]| Common schemes include "file", "http", "ftp", etc. The scheme can be different from the one used to construct the #GFile, in that it might be replaced with one that is logically equivalent to the #GFile. This call does no blocking I/O. a string containing the URI scheme for the given #GFile or %NULL if the #GFile was constructed with an invalid URI. The returned string should be freed with g_free() when no longer needed. input #GFile Checks if @file has a parent, and optionally, if it is @parent. If @parent is %NULL then this function returns %TRUE if @file has any parent at all. If @parent is non-%NULL then %TRUE is only returned if @file is an immediate child of @parent. %TRUE if @file is an immediate child of @parent (or any parent in the case that @parent is %NULL). input #GFile the parent to check for, or %NULL Checks whether @file has the prefix specified by @prefix. In other words, if the names of initial elements of @file's pathname match @prefix. Only full pathname elements are matched, so a path like /foo is not considered a prefix of /foobar, only of /foo/bar. A #GFile is not a prefix of itself. If you want to check for equality, use g_file_equal(). This call does no I/O, as it works purely on names. As such it can sometimes return %FALSE even if @file is inside a @prefix (from a filesystem point of view), because the prefix of @file is an alias of @prefix. %TRUE if the @file's parent, grandparent, etc is @prefix, %FALSE otherwise. input #GFile input #GFile Checks to see if a #GFile has a given URI scheme. This call does no blocking I/O. %TRUE if #GFile's backend supports the given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid. input #GFile a string containing a URI scheme Creates a hash value for a #GFile. This call does no blocking I/O. 0 if @file is not a valid #GFile, otherwise an integer that can be used as hash value for the #GFile. This function is intended for easily hashing a #GFile to add to a #GHashTable or similar data structure. #gconstpointer to a #GFile Checks to see if a file is native to the platform. A native file is one expressed in the platform-native filename format, e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local, as it might be on a locally mounted remote filesystem. On some systems non-native files may be available using the native filesystem via a userspace filesystem (FUSE), in these cases this call will return %FALSE, but g_file_get_path() will still return a native path. This call does no blocking I/O. %TRUE if @file is native input #GFile Loads the contents of @file and returns it as #GBytes. If @file is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to calling g_file_load_contents() and g_bytes_new_take(). For resources, @etag_out will be set to %NULL. The data contained in the resulting #GBytes is always zero-terminated, but this is not included in the #GBytes length. The resulting #GBytes should be freed with g_bytes_unref() when no longer in use. a #GBytes or %NULL and @error is set a #GFile a #GCancellable or %NULL a location to place the current entity tag for the file, or %NULL if the entity tag is not needed Asynchronously loads the contents of @file as #GBytes. If @file is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to calling g_file_load_contents_async() and g_bytes_new_take(). @callback should call g_file_load_bytes_finish() to get the result of this asynchronous operation. See g_file_load_bytes() for more information. a #GFile a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Completes an asynchronous request to g_file_load_bytes_async(). For resources, @etag_out will be set to %NULL. The data contained in the resulting #GBytes is always zero-terminated, but this is not included in the #GBytes length. The resulting #GBytes should be freed with g_bytes_unref() when no longer in use. See g_file_load_bytes() for more information. a #GBytes or %NULL and @error is set a #GFile a #GAsyncResult provided to the callback a location to place the current entity tag for the file, or %NULL if the entity tag is not needed Loads the content of the file into memory. The data is always zero-terminated, but this is not included in the resultant @length. The returned @contents should be freed with g_free() when no longer needed. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if the @file's contents were successfully loaded. %FALSE if there were errors. input #GFile optional #GCancellable object, %NULL to ignore a location to place the contents of the file a location to place the length of the contents of the file, or %NULL if the length is not needed a location to place the current entity tag for the file, or %NULL if the entity tag is not needed Starts an asynchronous load of the @file's contents. For more details, see g_file_load_contents() which is the synchronous version of this call. When the load operation has completed, @callback will be called with @user data. To finish the operation, call g_file_load_contents_finish() with the #GAsyncResult returned by the @callback. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous load of the @file's contents. The contents are placed in @contents, and @length is set to the size of the @contents string. The @contents should be freed with g_free() when no longer needed. If @etag_out is present, it will be set to the new entity tag for the @file. %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately. input #GFile a #GAsyncResult a location to place the contents of the file a location to place the length of the contents of the file, or %NULL if the length is not needed a location to place the current entity tag for the file, or %NULL if the entity tag is not needed Reads the partial contents of a file. A #GFileReadMoreCallback should be used to stop reading from the file when appropriate, else this function will behave exactly as g_file_load_contents_async(). This operation can be finished by g_file_load_partial_contents_finish(). Users of this function should be aware that @user_data is passed to both the @read_more_callback and the @callback. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile optional #GCancellable object, %NULL to ignore a #GFileReadMoreCallback to receive partial data and to specify whether further data should be read a #GAsyncReadyCallback to call when the request is satisfied the data to pass to the callback functions Finishes an asynchronous partial load operation that was started with g_file_load_partial_contents_async(). The data is always zero-terminated, but this is not included in the resultant @length. The returned @contents should be freed with g_free() when no longer needed. %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately. input #GFile a #GAsyncResult a location to place the contents of the file a location to place the length of the contents of the file, or %NULL if the length is not needed a location to place the current entity tag for the file, or %NULL if the entity tag is not needed Creates a directory. Note that this will only create a child directory of the immediate parent directory of the path or URI given by the #GFile. To recursively create directories, see g_file_make_directory_with_parents(). This function will fail if the parent directory does not exist, setting @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support creating directories, this function will fail, setting @error to %G_IO_ERROR_NOT_SUPPORTED. If the directory already exists, [error@Gio.IOErrorEnum.EXISTS] will be returned. For a local #GFile the newly created directory will have the default (current) ownership and permissions of the current process. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE on successful creation, %FALSE otherwise. input #GFile optional #GCancellable object, %NULL to ignore Asynchronously creates a directory. input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous directory creation, started with g_file_make_directory_async(). %TRUE on successful directory creation, %FALSE otherwise. input #GFile a #GAsyncResult Creates a directory and any parent directories that may not exist similar to 'mkdir -p'. If the file system does not support creating directories, this function will fail, setting @error to %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists, this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike the similar g_mkdir_with_parents(). For a local #GFile the newly created directories will have the default (current) ownership and permissions of the current process. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if all directories have been successfully created, %FALSE otherwise. input #GFile optional #GCancellable object, %NULL to ignore Creates a symbolic link named @file which contains the string @symlink_value. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE on the creation of a new symlink, %FALSE otherwise. a #GFile with the name of the symlink to create a string with the path for the target of the new symlink optional #GCancellable object, %NULL to ignore Asynchronously creates a symbolic link named @file which contains the string @symlink_value. a #GFile with the name of the symlink to create a string with the path for the target of the new symlink the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous symbolic link creation, started with g_file_make_symbolic_link_async(). %TRUE on successful directory creation, %FALSE otherwise. input #GFile a #GAsyncResult Recursively measures the disk usage of @file. This is essentially an analog of the 'du' command, but it also reports the number of directories and non-directory files encountered (including things like symbolic links). By default, errors are only reported against the toplevel file itself. Errors found while recursing are silently ignored, unless %G_FILE_MEASURE_REPORT_ANY_ERROR is given in @flags. The returned size, @disk_usage, is in bytes and should be formatted with g_format_size() in order to get something reasonable for showing in a user interface. @progress_callback and @progress_data can be given to request periodic progress updates while scanning. See the documentation for #GFileMeasureProgressCallback for information about when and how the callback will be invoked. %TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. a #GFile #GFileMeasureFlags optional #GCancellable a #GFileMeasureProgressCallback user_data for @progress_callback the number of bytes of disk space used the number of directories encountered the number of non-directories encountered Recursively measures the disk usage of @file. This is the asynchronous version of g_file_measure_disk_usage(). See there for more information. a #GFile #GFileMeasureFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable a #GFileMeasureProgressCallback user_data for @progress_callback a #GAsyncReadyCallback to call when complete the data to pass to callback function Collects the results from an earlier call to g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for more information. %TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. a #GFile the #GAsyncResult passed to your #GAsyncReadyCallback the number of bytes of disk space used the number of directories encountered the number of non-directories encountered Obtains a file or directory monitor for the given file, depending on the type of the file. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a set of #GFileMonitorFlags optional #GCancellable object, %NULL to ignore Obtains a directory monitor for the given file. This may fail if directory monitoring is not supported. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. It does not make sense for @flags to contain %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to directories. It is not possible to monitor all the files in a directory for changes made via hard links; if you want to do this then you must register individual watches with g_file_monitor(). a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a set of #GFileMonitorFlags optional #GCancellable object, %NULL to ignore Obtains a file monitor for the given file. If no file notification mechanism exists, then regular polling of the file is used. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor will also attempt to report changes made to the file via another filename (ie, a hard link). Without this flag, you can only rely on changes made through the filename contained in @file to be reported. Using this flag may result in an increase in resource usage, and may not have any effect depending on the #GFileMonitor backend and/or filesystem type. a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a set of #GFileMonitorFlags optional #GCancellable object, %NULL to ignore Starts a @mount_operation, mounting the volume that contains the file @location. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_mount_enclosing_volume_finish(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile flags affecting the operation a #GMountOperation or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a mount operation started by g_file_mount_enclosing_volume(). %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. input #GFile a #GAsyncResult Mounts a file of type G_FILE_TYPE_MOUNTABLE. Using @mount_operation, you can request callbacks when, for instance, passwords are needed during authentication. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes a mount operation. See g_file_mount_mountable() for details. Finish an asynchronous mount operation that was started with g_file_mount_mountable(). a #GFile or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Tries to move the file or directory @source to the location specified by @destination. If native move operations are supported then this is used, otherwise a copy + delete fallback is used. The native implementation may support moving directories (for instance on moves inside the same filesystem), but the fallback code does not. If the flag %G_FILE_COPY_OVERWRITE is specified an already existing @destination file is overwritten. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If @progress_callback is not %NULL, then the operation can be monitored by setting this to a #GFileProgressCallback function. @progress_callback_data will be passed to this function. It is guaranteed that this callback will be called after all data has been transferred with the total number of bytes copied during the operation. If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error is returned, independent on the status of the @destination. If %G_FILE_COPY_OVERWRITE is not specified and the target exists, then the error %G_IO_ERROR_EXISTS is returned. If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY error is returned. If trying to overwrite a directory with a directory the %G_IO_ERROR_WOULD_MERGE error is returned. If the source is a directory and the target does not exist, or %G_FILE_COPY_OVERWRITE is specified and the target is a file, then the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native move operation isn't available). %TRUE on successful move, %FALSE otherwise. #GFile pointing to the source location #GFile pointing to the destination location set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore #GFileProgressCallback function for updates gpointer to user data for the callback function Asynchronously moves a file @source to the location of @destination. For details of the behaviour, see g_file_move(). If @progress_callback is not %NULL, then that function that will be called just like in g_file_move(). The callback will run in the default main context of the thread calling g_file_move_async() — the same context as @callback is run in. When the operation is finished, @callback will be called. You can then call g_file_move_finish() to get the result of the operation. #GFile pointing to the source location #GFile pointing to the destination location set of #GFileCopyFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore #GFileProgressCallback function for updates gpointer to user data for the callback function a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Version of [method@Gio.File.move_async] using closures instead of callbacks for easier binding in other languages. input [type@Gio.File] destination [type@Gio.File] set of [flags@Gio.FileCopyFlags] the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional [class@Gio.Cancellable] object, `NULL` to ignore [type@GObject.Closure] to invoke with progress information, or `NULL` if progress information is not needed [type@GObject.Closure] to invoke when the request is satisfied Finishes an asynchronous file movement, started with g_file_move_async(). %TRUE on successful file move, %FALSE otherwise. input source #GFile a #GAsyncResult Opens an existing file for reading and writing. The result is a #GFileIOStream that can be used to read and write the contents of the file. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). #GFile to open a #GCancellable Asynchronously opens @file for reading and writing. For more details, see g_file_open_readwrite() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_open_readwrite_finish() to get the result of the operation. input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file read operation started with g_file_open_readwrite_async(). a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Exactly like g_file_get_path(), but caches the result via g_object_set_qdata_full(). This is useful for example in C applications which mix `g_file_*` APIs with native ones. It also avoids an extra duplicated string when possible, so will be generally more efficient. This call does no blocking I/O. string containing the #GFile's path, or %NULL if no such path exists. The returned string is owned by @file. input #GFile Polls a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation. input #GFile optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a poll operation. See g_file_poll_mountable() for details. Finish an asynchronous poll operation that was polled with g_file_poll_mountable(). %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Returns the #GAppInfo that is registered as the default application to handle the file specified by @file. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GAppInfo if the handle was found, %NULL if there were errors. When you are done with it, release it with g_object_unref() a #GFile to open optional #GCancellable object, %NULL to ignore Async version of g_file_query_default_handler(). a #GFile to open the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is done data to pass to @callback Finishes a g_file_query_default_handler_async() operation. a #GAppInfo if the handle was found, %NULL if there were errors. When you are done with it, release it with g_object_unref() a #GFile to open a #GAsyncResult Utility function to check if a particular file exists. The fallback implementation of this API is using [method@Gio.File.query_info] and therefore may do blocking I/O. To asynchronously query the existence of a file, use [method@Gio.File.query_info_async]. Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use) and then execute something based on the outcome of that, because the file might have been created or removed in between the operations. The general approach to handling that is to not check, but just do the operation and handle the errors as they come. As an example of race-free checking, take the case of reading a file, and if it doesn't exist, creating it. There are two racy versions: read it, and on error create it; and: check if it exists, if not create it. These can both result in two processes creating the file (with perhaps a partially written file as the result). The correct approach is to always try to create the file with g_file_create() which will either atomically create the file or fail with a %G_IO_ERROR_EXISTS error. However, in many cases an existence check is useful in a user interface, for instance to make a menu item sensitive/insensitive, so that you don't have to fool users that something is possible and then just show an error dialog. If you do this, you should make sure to also handle the errors that can happen due to races when you execute the operation. %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled). input #GFile optional #GCancellable object, %NULL to ignore Utility function to inspect the #GFileType of a file. This is implemented using g_file_query_info() and as such does blocking I/O. The primary use case of this method is to check if a file is a regular file, directory, or symlink. The #GFileType of the file and %G_FILE_TYPE_UNKNOWN if the file does not exist input #GFile a set of #GFileQueryInfoFlags passed to g_file_query_info() optional #GCancellable object, %NULL to ignore Similar to g_file_query_info(), but obtains information about the filesystem the @file is on, rather than the file itself. For instance the amount of space available and the type of the filesystem. The @attributes value is a string that specifies the attributes that should be gathered. It is not an error if it's not possible to read a particular requested attribute from a file - it just won't be set. @attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "filesystem::*" means all attributes in the filesystem namespace. The standard namespace for filesystem attributes is "filesystem". Common attributes of interest are %G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem in bytes), %G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available), and %G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. a #GFileInfo or %NULL if there was an error. Free the returned object with g_object_unref(). input #GFile an attribute query string optional #GCancellable object, %NULL to ignore Asynchronously gets the requested information about the filesystem that the specified @file is on. The result is a #GFileInfo object that contains key-value attributes (such as type or size for the file). For more details, see g_file_query_filesystem_info() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_query_info_finish() to get the result of the operation. input #GFile an attribute query string the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous filesystem info query. See g_file_query_filesystem_info_async(). #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Gets the requested information about specified @file. The result is a [class@Gio.FileInfo] object that contains key-value attributes (such as the type or size of the file). The @attributes value is a string that specifies the file attributes that should be gathered. It is not an error if it’s not possible to read a particular requested attribute from a file — it just won't be set. In particular this means that if a file is inaccessible (due to being in a folder with restrictive permissions), for example, you can expect the returned [class@Gio.FileInfo] to have very few attributes set. You should check whether an attribute is set using [method@Gio.FileInfo.has_attribute] before trying to retrieve its value. It is guaranteed that if any of the following attributes are listed in @attributes, they will always be set in the returned [class@Gio.FileInfo], even if the user doesn’t have permissions to access the file: - [const@Gio.FILE_ATTRIBUTE_STANDARD_NAME] - [const@Gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME] @attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard `"*"` means all attributes, and a wildcard like `"standard::*"` means all attributes in the standard namespace. An example attribute query might be `"standard::*,owner::user"`. The standard attributes are available as defines, like [const@Gio.FILE_ATTRIBUTE_STANDARD_NAME]. If @cancellable is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error [error@Gio.IOErrorEnum.CANCELLED] will be returned. For symlinks, normally the information about the target of the symlink is returned, rather than information about the symlink itself. However if you pass [flags@Gio.FileQueryInfoFlags.NOFOLLOW_SYMLINKS] in @flags the information about the symlink itself will be returned. Also, for symlinks that point to non-existing files the information about the symlink itself will be returned. If the file does not exist, the [error@Gio.IOErrorEnum.NOT_FOUND] error will be returned. Other errors are possible too, and depend on what kind of file system the file is on. a [class@Gio.FileInfo] for the given @file input file an attribute query string flags to affect the query operation optional cancellable object Asynchronously gets the requested information about specified @file. The result is a #GFileInfo object that contains key-value attributes (such as type or size for the file). For more details, see g_file_query_info() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_query_info_finish() to get the result of the operation. input #GFile an attribute query string a set of #GFileQueryInfoFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file info query. See g_file_query_info_async(). #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Obtain the list of settable attributes for the file. Returns the type and full attribute name of all the attributes that can be set on this file. This doesn't mean setting it will always succeed though, you might get an access failure, or some specific file may not support a specific attribute. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GFileAttributeInfoList describing the settable attributes. When you are done with it, release it with g_file_attribute_info_list_unref() input #GFile optional #GCancellable object, %NULL to ignore Obtain the list of attribute namespaces where new attributes can be created by a user. An example of this is extended attributes (in the "xattr" namespace). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GFileAttributeInfoList describing the writable namespaces. When you are done with it, release it with g_file_attribute_info_list_unref() input #GFile optional #GCancellable object, %NULL to ignore Opens a file for reading. The result is a #GFileInputStream that can be used to read the contents of the file. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). #GFile to read a #GCancellable Asynchronously opens @file for reading. For more details, see g_file_read() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_read_finish() to get the result of the operation. input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file read operation started with g_file_read_async(). a #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Returns an output stream for overwriting the file, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created. This will try to replace the file in the safest way possible so that any errors during the writing will not affect an already existing copy of the file. For instance, for local files it may write to a temporary file and then atomically rename over the destination when the stream is closed. By default files created are generally readable by everyone, but if you pass %G_FILE_CREATE_PRIVATE in @flags the file will be made readable only to the current user, to the level that is supported on the target filesystem. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If you pass in a non-%NULL @etag value and @file already exists, then this value is compared to the current entity tag of the file, and if they differ an %G_IO_ERROR_WRONG_ETAG error is returned. This generally means that the file has been changed since you last read it. You can get the new etag from g_file_output_stream_get_etag() after you've finished writing and closed the #GFileOutputStream. When you load a new file you can use g_file_input_stream_query_info() to get the etag of the file. If @make_backup is %TRUE, this function will attempt to make a backup of the current file before overwriting it. If this fails a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you want to replace anyway, try again with @make_backup set to %FALSE. If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will be returned, and if the file is some other form of non-regular file then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some file systems don't allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first. For more details, see g_file_replace() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_replace_finish() to get the result of the operation. input #GFile an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Replaces the contents of @file with @contents of @length bytes. If @etag is specified (not %NULL), any existing file must have that etag, or the error %G_IO_ERROR_WRONG_ETAG will be returned. If @make_backup is %TRUE, this function will attempt to make a backup of @file. Internally, it uses g_file_replace(), so will try to replace the file contents in the safest way possible. For example, atomic renames are used when replacing local files’ contents. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. The returned @new_etag can be used to verify that the file hasn't changed the next time it is saved over. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. input #GFile a string containing the new contents for @file the length of @contents in bytes the old [entity-tag](#entity-tags) for the document, or %NULL %TRUE if a backup should be created a set of #GFileCreateFlags a location to a new [entity tag](#entity-tags) for the document. This should be freed with g_free() when no longer needed, or %NULL optional #GCancellable object, %NULL to ignore Starts an asynchronous replacement of @file with the given @contents of @length bytes. @etag will replace the document's current entity tag. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_replace_contents_finish(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If @make_backup is %TRUE, this function will attempt to make a backup of @file. Note that no copy of @contents will be made, so it must stay valid until @callback is called. See g_file_replace_contents_bytes_async() for a #GBytes version that will automatically hold a reference to the contents (without copying) for the duration of the call. input #GFile string of contents to replace the file with the length of @contents in bytes a new [entity tag](#entity-tags) for the @file, or %NULL %TRUE if a backup should be created a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Same as g_file_replace_contents_async() but takes a #GBytes input instead. This function will keep a ref on @contents until the operation is done. Unlike g_file_replace_contents_async() this allows forgetting about the content without waiting for the callback. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_replace_contents_finish(). input #GFile a #GBytes a new [entity tag](#entity-tags) for the @file, or %NULL %TRUE if a backup should be created a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous replace of the given @file. See g_file_replace_contents_async(). Sets @new_etag to the new entity tag for the document, if present. %TRUE on success, %FALSE on failure. input #GFile a #GAsyncResult a location of a new [entity tag](#entity-tags) for the document. This should be freed with g_free() when it is no longer needed, or %NULL Finishes an asynchronous file replace operation started with g_file_replace_async(). a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Returns an output stream for overwriting the file in readwrite mode, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created. For details about the behaviour, see g_file_replace() which does the same thing but returns an output stream only. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). a #GFile an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously overwrites the file in read-write mode, replacing the contents, possibly creating a backup copy of the file first. For more details, see g_file_replace_readwrite() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_replace_readwrite_finish() to get the result of the operation. input #GFile an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file replace operation started with g_file_replace_readwrite_async(). a #GFileIOStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Resolves a relative path for @file to an absolute path. This call does no blocking I/O. If the @relative_path is an absolute path name, the resolution is done absolutely (without taking @file path as base). a #GFile for the resolved path. input #GFile a given relative path string Sets an attribute in the file with attribute name @attribute to @value_p. Some attributes can be unset by setting @type to %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if the attribute was set, %FALSE otherwise. input #GFile a string containing the attribute's name The type of the attribute a pointer to the value (or the pointer itself if the type is a pointer type) a set of #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value. If @attribute is of a different type, this operation will fail, returning %FALSE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. input #GFile a string containing the attribute's name a string containing the attribute's new value a #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. If @attribute is of a different type, this operation will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. input #GFile a string containing the attribute's name a #gint32 containing the attribute's new value a #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value. If @attribute is of a different type, this operation will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if the @attribute was successfully set, %FALSE otherwise. input #GFile a string containing the attribute's name a #guint64 containing the attribute's new value a #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. If @attribute is of a different type, this operation will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if the @attribute was successfully set, %FALSE otherwise. input #GFile a string containing the attribute's name a string containing the attribute's value #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. If @attribute is of a different type, this operation will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. input #GFile a string containing the attribute's name a #guint32 containing the attribute's new value a #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. If @attribute is of a different type, this operation will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. input #GFile a string containing the attribute's name a #guint64 containing the attribute's new value a #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Asynchronously sets the attributes of @file with @info. For more details, see g_file_set_attributes_from_info(), which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_set_attributes_finish() to get the result of the operation. input #GFile a #GFileInfo a #GFileQueryInfoFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes setting an attribute started in g_file_set_attributes_async(). %TRUE if the attributes were set correctly, %FALSE otherwise. input #GFile a #GAsyncResult a #GFileInfo Tries to set all attributes in the #GFileInfo on the target values, not stopping on the first error. If there is any error during this operation then @error will be set to the first error. Error on particular fields are flagged by setting the "status" field in the attribute value to %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can also detect further errors. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %FALSE if there was any error, %TRUE otherwise. input #GFile a #GFileInfo #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Renames @file to the specified display name. The display name is converted from UTF-8 to the correct encoding for the target filesystem if possible and the @file is renamed to this. If you want to implement a rename operation in the user interface the edit name (%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the initial value in the rename widget, and then the result after editing should be passed to g_file_set_display_name(). On success the resulting converted filename is returned. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GFile specifying what @file was renamed to, or %NULL if there was an error. Free the returned object with g_object_unref(). input #GFile a string optional #GCancellable object, %NULL to ignore Asynchronously sets the display name for a given #GFile. For more details, see g_file_set_display_name() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_set_display_name_finish() to get the result of the operation. input #GFile a string the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes setting a display name started with g_file_set_display_name_async(). a #GFile or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Starts a file of type %G_FILE_TYPE_MOUNTABLE. Using @start_operation, you can request callbacks when, for instance, passwords are needed during authentication. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a start operation. See g_file_start_mountable() for details. Finish an asynchronous start operation that was started with g_file_start_mountable(). %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Stops a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_stop_mountable_finish() to get the result of the operation. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a stop operation, see g_file_stop_mountable() for details. Finish an asynchronous stop operation that was started with g_file_stop_mountable(). %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Checks if @file supports thread-default main contexts (see [method@GLib.MainContext.push_thread_default]) If this returns %FALSE, you cannot perform asynchronous operations on @file in a thread that has a thread-default context. Whether or not @file supports thread-default contexts. a #GFile Sends @file to the "Trashcan", if possible. This is similar to deleting it, but the user can recover it before emptying the trashcan. Trashing is disabled for system mounts by default (see g_unix_mount_entry_is_system_internal()), so this call can return the %G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix mount option can be used to disable g_file_trash() support for particular mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case. Since 2.82, the `x-gvfs-trash` unix mount option can be used to enable g_file_trash() support for particular system mounts. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE on successful trash, %FALSE otherwise. #GFile to send to trash optional #GCancellable object, %NULL to ignore Asynchronously sends @file to the Trash location, if possible. input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file trashing operation, started with g_file_trash_async(). %TRUE on successful trash, %FALSE otherwise. input #GFile a #GAsyncResult Unmounts a file of type G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_unmount_mountable_finish() to get the result of the operation. Use g_file_unmount_mountable_with_operation() instead. input #GFile flags affecting the operation optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an unmount operation, see g_file_unmount_mountable() for details. Finish an asynchronous unmount operation that was started with g_file_unmount_mountable(). Use g_file_unmount_mountable_with_operation_finish() instead. %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Unmounts a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_unmount_mountable_finish() to get the result of the operation. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an unmount operation, see g_file_unmount_mountable_with_operation() for details. Finish an asynchronous unmount operation that was started with g_file_unmount_mountable_with_operation(). %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Information about a specific attribute. the name of the attribute. the #GFileAttributeType type of the attribute. a set of #GFileAttributeInfoFlags. Flags specifying the behaviour of an attribute. no flags set. copy the attribute values when the file is copied. copy the attribute values when the file is moved. Acts as a lightweight registry for possible valid file attributes. The registry stores Key-Value pair formats as #GFileAttributeInfos. an array of #GFileAttributeInfos. the number of values in the array. Creates a new file attribute info list. a #GFileAttributeInfoList. Adds a new attribute with @name to the @list, setting its @type and @flags. a #GFileAttributeInfoList. the name of the attribute to add. the #GFileAttributeType for the attribute. #GFileAttributeInfoFlags for the attribute. Makes a duplicate of a file attribute info list. a copy of the given @list. a #GFileAttributeInfoList to duplicate. Gets the file attribute with the name @name from @list. a #GFileAttributeInfo for the @name, or %NULL if an attribute isn't found. a #GFileAttributeInfoList. the name of the attribute to look up. References a file attribute info list. #GFileAttributeInfoList or %NULL on error. a #GFileAttributeInfoList to reference. Removes a reference from the given @list. If the reference count falls to zero, the @list is deleted. The #GFileAttributeInfoList to unreference. Determines if a string matches a file attribute. Creates a new file attribute matcher, which matches attributes against a given string. #GFileAttributeMatchers are reference counted structures, and are created with a reference count of 1. If the number of references falls to 0, the #GFileAttributeMatcher is automatically destroyed. The @attributes string should be formatted with specific keys separated from namespaces with a double colon. Several "namespace::key" strings may be concatenated with a single comma (e.g. "standard::type,standard::is-hidden"). The wildcard "*" may be used to match all keys and namespaces, or "namespace::*" will match all keys in a given namespace. ## Examples of file attribute matcher strings and results - `"*"`: matches all attributes. - `"standard::is-hidden"`: matches only the key is-hidden in the standard namespace. - `"standard::type,unix::*"`: matches the type key in the standard namespace and all keys in the unix namespace. a #GFileAttributeMatcher an attribute string to match. Checks if the matcher will match all of the keys in a given namespace. This will always return %TRUE if a wildcard character is in use (e.g. if matcher was created with "standard::*" and @ns is "standard", or if matcher was created using "*" and namespace is anything.) TODO: this is awkwardly worded. %TRUE if the matcher matches all of the entries in the given @ns, %FALSE otherwise. a #GFileAttributeMatcher. a string containing a file attribute namespace. Gets the next matched attribute from a #GFileAttributeMatcher. a string containing the next attribute or, %NULL if no more attribute exist. a #GFileAttributeMatcher. Checks if an attribute will be matched by an attribute matcher. If the matcher was created with the "*" matching string, this function will always return %TRUE. %TRUE if @attribute matches @matcher. %FALSE otherwise. a #GFileAttributeMatcher. a file attribute key. Checks if an attribute matcher only matches a given attribute. Always returns %FALSE if "*" was used when creating the matcher. %TRUE if the matcher only matches @attribute. %FALSE otherwise. a #GFileAttributeMatcher. a file attribute key. References a file attribute matcher. a #GFileAttributeMatcher. a #GFileAttributeMatcher. Subtracts all attributes of @subtract from @matcher and returns a matcher that supports those attributes. Note that currently it is not possible to remove a single attribute when the @matcher matches the whole namespace - or remove a namespace or attribute when the matcher matches everything. This is a limitation of the current implementation, but may be fixed in the future. A file attribute matcher matching all attributes of @matcher that are not matched by @subtract Matcher to subtract from The matcher to subtract Prints what the matcher is matching against. The format will be equal to the format passed to g_file_attribute_matcher_new(). The output however, might not be identical, as the matcher may decide to use a different order or omit needless parts. a string describing the attributes the matcher matches against or %NULL if @matcher was %NULL. a #GFileAttributeMatcher. Unreferences @matcher. If the reference count falls below 1, the @matcher is automatically freed. a #GFileAttributeMatcher. Used by g_file_set_attributes_from_info() when setting file attributes. Attribute value is unset (empty). Attribute value is set. Indicates an error in setting the value. The data types for file attributes. indicates an invalid or uninitialized type. a null terminated UTF8 string. a zero terminated string of non-zero bytes. a boolean value. an unsigned 4-byte/32-bit integer. a signed 4-byte/32-bit integer. an unsigned 8-byte/64-bit integer. a signed 8-byte/64-bit integer. a #GObject. a %NULL terminated char **. Since 2.22 Flags used when copying or moving files. No flags set. Overwrite any existing files Make a backup of any existing files. Don't follow symlinks. Copy all file metadata instead of just default set used for copy (see #GFileInfo). Don't use copy and delete fallback if native move not supported. Leaves target file with default perms, instead of setting the source file perms. Use default modification timestamps instead of copying them from the source file. Since 2.80 Flags used when an operation may create a file. No flags set. Create a file that can only be accessed by the current user. Replace the destination as if it didn't exist before. Don't try to keep any old permissions, replace instead of following links. This is generally useful if you're doing a "copy over" rather than a "save new version of" replace operation. You can think of it as "unlink destination" before writing to it, although the implementation may not be exactly like that. This flag can only be used with g_file_replace() and its variants, including g_file_replace_contents(). Since 2.20 `GFileEnumerator` allows you to operate on a set of [iface@Gio.File] objects, returning a [class@Gio.FileInfo] structure for each file enumerated (e.g. [method@Gio.File.enumerate_children] will return a `GFileEnumerator` for each of the children within a directory). To get the next file's information from a `GFileEnumerator`, use [method@Gio.FileEnumerator.next_file] or its asynchronous version, [method@Gio.FileEnumerator.next_files_async]. Note that the asynchronous version will return a list of [class@Gio.FileInfo] objects, whereas the synchronous will only return the next file in the enumerator. The ordering of returned files is unspecified for non-Unix platforms; for more information, see [method@GLib.Dir.read_name]. On Unix, when operating on local files, returned files will be sorted by inode number. Effectively you can assume that the ordering of returned files will be stable between successive calls (and applications) assuming the directory is unchanged. If your application needs a specific ordering, such as by name or modification time, you will have to implement that in your application code. To close a `GFileEnumerator`, use [method@Gio.FileEnumerator.close], or its asynchronous version, [method@Gio.FileEnumerator.close_async]. Once a `GFileEnumerator` is closed, no further actions may be performed on it, and it should be freed with [method@GObject.Object.unref]. Asynchronously closes the file enumerator. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in g_file_enumerator_close_finish(). a #GFileEnumerator. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes closing a file enumerator, started from g_file_enumerator_close_async(). If the file enumerator was already closed when g_file_enumerator_close_async() was called, then this function will report %G_IO_ERROR_CLOSED in @error, and return %FALSE. If the file enumerator had pending operation when the close operation was started, then this function will report %G_IO_ERROR_PENDING, and return %FALSE. If @cancellable was not %NULL, then the operation may have been cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be returned. %TRUE if the close operation has finished successfully. a #GFileEnumerator. a #GAsyncResult. Returns information for the next file in the enumerated object. Will block until the information is available. The #GFileInfo returned from this function will contain attributes that match the attribute string that was passed when the #GFileEnumerator was created. See the documentation of #GFileEnumerator for information about the order of returned files. On error, returns %NULL and sets @error to the error. If the enumerator is at the end, %NULL will be returned and @error will be unset. A #GFileInfo or %NULL on error or end of enumerator. Free the returned object with g_object_unref() when no longer needed. a #GFileEnumerator. optional #GCancellable object, %NULL to ignore. Request information for a number of files from the enumerator asynchronously. When all I/O for the operation is finished the @callback will be called with the requested information. See the documentation of #GFileEnumerator for information about the order of returned files. Once the end of the enumerator is reached, or if an error occurs, the @callback will be called with an empty list. In this case, the previous call to g_file_enumerator_next_files_async() will typically have returned fewer than @num_files items. If a request is cancelled the callback will be called with %G_IO_ERROR_CANCELLED. This leads to the following pseudo-code usage: |[ g_autoptr(GFile) dir = get_directory (); g_autoptr(GFileEnumerator) enumerator = NULL; g_autolist(GFileInfo) files = NULL; g_autoptr(GError) local_error = NULL; enumerator = yield g_file_enumerate_children_async (dir, G_FILE_ATTRIBUTE_STANDARD_NAME "," G_FILE_ATTRIBUTE_STANDARD_TYPE, G_FILE_QUERY_INFO_NONE, G_PRIORITY_DEFAULT, cancellable, …, &local_error); if (enumerator == NULL) g_error ("Error enumerating: %s", local_error->message); // Loop until no files are returned, either because the end of the enumerator // has been reached, or an error was returned. do { files = yield g_file_enumerator_next_files_async (enumerator, 5, // number of files to request G_PRIORITY_DEFAULT, cancellable, …, &local_error); // Process the returned files, but don’t assume that exactly 5 were returned. for (GList *l = files; l != NULL; l = l->next) { GFileInfo *info = l->data; handle_file_info (info); } } while (files != NULL); if (local_error != NULL && !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_CANCELLED)) g_error ("Error while enumerating: %s", local_error->message); ]| During an async request no other sync and async calls are allowed, and will result in %G_IO_ERROR_PENDING errors. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. a #GFileEnumerator. the number of file info objects to request the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). a #GList of #GFileInfos. You must free the list with g_list_free() and unref the infos with g_object_unref() when you're done with them. a #GFileEnumerator. a #GAsyncResult. Releases all resources used by this enumerator, making the enumerator return %G_IO_ERROR_CLOSED on all calls. This will be automatically called when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. #TRUE on success or #FALSE on error. a #GFileEnumerator. optional #GCancellable object, %NULL to ignore. Asynchronously closes the file enumerator. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in g_file_enumerator_close_finish(). a #GFileEnumerator. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes closing a file enumerator, started from g_file_enumerator_close_async(). If the file enumerator was already closed when g_file_enumerator_close_async() was called, then this function will report %G_IO_ERROR_CLOSED in @error, and return %FALSE. If the file enumerator had pending operation when the close operation was started, then this function will report %G_IO_ERROR_PENDING, and return %FALSE. If @cancellable was not %NULL, then the operation may have been cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be returned. %TRUE if the close operation has finished successfully. a #GFileEnumerator. a #GAsyncResult. Return a new #GFile which refers to the file named by @info in the source directory of @enumerator. This function is primarily intended to be used inside loops with g_file_enumerator_next_file(). To use this, %G_FILE_ATTRIBUTE_STANDARD_NAME must have been listed in the attributes list used when creating the #GFileEnumerator. This is a convenience method that's equivalent to: |[<!-- language="C" --> gchar *name = g_file_info_get_name (info); GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr), name); ]| a #GFile for the #GFileInfo passed it. a #GFileEnumerator a #GFileInfo gotten from g_file_enumerator_next_file() or the async equivalents. Get the #GFile container which is being enumerated. the #GFile which is being enumerated. a #GFileEnumerator Checks if the file enumerator has pending operations. %TRUE if the @enumerator has pending operations. a #GFileEnumerator. Checks if the file enumerator has been closed. %TRUE if the @enumerator is closed. a #GFileEnumerator. This is a version of g_file_enumerator_next_file() that's easier to use correctly from C programs. With g_file_enumerator_next_file(), the gboolean return value signifies "end of iteration or error", which requires allocation of a temporary #GError. In contrast, with this function, a %FALSE return from g_file_enumerator_iterate() *always* means "error". End of iteration is signaled by @out_info or @out_child being %NULL. Another crucial difference is that the references for @out_info and @out_child are owned by @direnum (they are cached as hidden properties). You must not unref them in your own code. This makes memory management significantly easier for C code in combination with loops. Finally, this function optionally allows retrieving a #GFile as well. You must specify at least one of @out_info or @out_child. The code pattern for correctly using g_file_enumerator_iterate() from C is: |[ direnum = g_file_enumerate_children (file, ...); while (TRUE) { GFileInfo *info; if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error)) goto out; if (!info) break; ... do stuff with "info"; do not unref it! ... } out: g_object_unref (direnum); // Note: frees the last @info ]| an open #GFileEnumerator Output location for the next #GFileInfo, or %NULL Output location for the next #GFile, or %NULL a #GCancellable Returns information for the next file in the enumerated object. Will block until the information is available. The #GFileInfo returned from this function will contain attributes that match the attribute string that was passed when the #GFileEnumerator was created. See the documentation of #GFileEnumerator for information about the order of returned files. On error, returns %NULL and sets @error to the error. If the enumerator is at the end, %NULL will be returned and @error will be unset. A #GFileInfo or %NULL on error or end of enumerator. Free the returned object with g_object_unref() when no longer needed. a #GFileEnumerator. optional #GCancellable object, %NULL to ignore. Request information for a number of files from the enumerator asynchronously. When all I/O for the operation is finished the @callback will be called with the requested information. See the documentation of #GFileEnumerator for information about the order of returned files. Once the end of the enumerator is reached, or if an error occurs, the @callback will be called with an empty list. In this case, the previous call to g_file_enumerator_next_files_async() will typically have returned fewer than @num_files items. If a request is cancelled the callback will be called with %G_IO_ERROR_CANCELLED. This leads to the following pseudo-code usage: |[ g_autoptr(GFile) dir = get_directory (); g_autoptr(GFileEnumerator) enumerator = NULL; g_autolist(GFileInfo) files = NULL; g_autoptr(GError) local_error = NULL; enumerator = yield g_file_enumerate_children_async (dir, G_FILE_ATTRIBUTE_STANDARD_NAME "," G_FILE_ATTRIBUTE_STANDARD_TYPE, G_FILE_QUERY_INFO_NONE, G_PRIORITY_DEFAULT, cancellable, …, &local_error); if (enumerator == NULL) g_error ("Error enumerating: %s", local_error->message); // Loop until no files are returned, either because the end of the enumerator // has been reached, or an error was returned. do { files = yield g_file_enumerator_next_files_async (enumerator, 5, // number of files to request G_PRIORITY_DEFAULT, cancellable, …, &local_error); // Process the returned files, but don’t assume that exactly 5 were returned. for (GList *l = files; l != NULL; l = l->next) { GFileInfo *info = l->data; handle_file_info (info); } } while (files != NULL); if (local_error != NULL && !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_CANCELLED)) g_error ("Error while enumerating: %s", local_error->message); ]| During an async request no other sync and async calls are allowed, and will result in %G_IO_ERROR_PENDING errors. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. a #GFileEnumerator. the number of file info objects to request the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). a #GList of #GFileInfos. You must free the list with g_list_free() and unref the infos with g_object_unref() when you're done with them. a #GFileEnumerator. a #GAsyncResult. Sets the file enumerator as having pending operations. a #GFileEnumerator. a boolean value. The container that is being enumerated. A #GFileInfo or %NULL on error or end of enumerator. Free the returned object with g_object_unref() when no longer needed. a #GFileEnumerator. optional #GCancellable object, %NULL to ignore. a #GFileEnumerator. the number of file info objects to request the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function a #GList of #GFileInfos. You must free the list with g_list_free() and unref the infos with g_object_unref() when you're done with them. a #GFileEnumerator. a #GAsyncResult. a #GFileEnumerator. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function %TRUE if the close operation has finished successfully. a #GFileEnumerator. a #GAsyncResult. `GFileIOStream` provides I/O streams that both read and write to the same file handle. `GFileIOStream` implements [iface@Gio.Seekable], which allows the I/O stream to jump to arbitrary positions in the file and to truncate the file, provided the filesystem of the file supports these operations. To find the position of a file I/O stream, use [method@Gio.Seekable.tell]. To find out if a file I/O stream supports seeking, use [method@Gio.Seekable.can_seek]. To position a file I/O stream, use [method@Gio.Seekable.seek]. To find out if a file I/O stream supports truncating, use [method@Gio.Seekable.can_truncate]. To truncate a file I/O stream, use [method@Gio.Seekable.truncate]. The default implementation of all the `GFileIOStream` operations and the implementation of [iface@Gio.Seekable] just call into the same operations on the output stream. Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. the entity tag for the stream. a #GFileIOStream. Queries a file io stream for the given @attributes. This function blocks while querying the stream. For the asynchronous version of this function, see g_file_io_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with %G_IO_ERROR_PENDING. Can fail if the stream was already closed (with @error being set to %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being set to %G_IO_ERROR_PENDING), or if querying info is not supported for the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I all cases of failure, %NULL will be returned. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will be returned. a #GFileInfo for the @stream, or %NULL on error. a #GFileIOStream. a file attribute query string. optional #GCancellable object, %NULL to ignore. Asynchronously queries the @stream for a #GFileInfo. When completed, @callback will be called with a #GAsyncResult which can be used to finish the operation with g_file_io_stream_query_info_finish(). For the synchronous version of this function, see g_file_io_stream_query_info(). a #GFileIOStream. a file attribute query string. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finalizes the asynchronous query started by g_file_io_stream_query_info_async(). A #GFileInfo for the finished query. a #GFileIOStream. a #GAsyncResult. Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. the entity tag for the stream. a #GFileIOStream. Queries a file io stream for the given @attributes. This function blocks while querying the stream. For the asynchronous version of this function, see g_file_io_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with %G_IO_ERROR_PENDING. Can fail if the stream was already closed (with @error being set to %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being set to %G_IO_ERROR_PENDING), or if querying info is not supported for the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I all cases of failure, %NULL will be returned. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will be returned. a #GFileInfo for the @stream, or %NULL on error. a #GFileIOStream. a file attribute query string. optional #GCancellable object, %NULL to ignore. Asynchronously queries the @stream for a #GFileInfo. When completed, @callback will be called with a #GAsyncResult which can be used to finish the operation with g_file_io_stream_query_info_finish(). For the synchronous version of this function, see g_file_io_stream_query_info(). a #GFileIOStream. a file attribute query string. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finalizes the asynchronous query started by g_file_io_stream_query_info_async(). A #GFileInfo for the finished query. a #GFileIOStream. a #GAsyncResult. a #GFileInfo for the @stream, or %NULL on error. a #GFileIOStream. a file attribute query string. optional #GCancellable object, %NULL to ignore. a #GFileIOStream. a file attribute query string. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function A #GFileInfo for the finished query. a #GFileIOStream. a #GAsyncResult. the entity tag for the stream. a #GFileIOStream. `GFileIcon` specifies an icon by pointing to an image file to be used as icon. It implements [iface@Gio.LoadableIcon]. Creates a new icon for a file. a #GIcon for the given @file, or %NULL on error. a #GFile. Gets the #GFile associated with the given @icon. a #GFile. a #GIcon. The file containing the icon. An interface for writing VFS file handles. The parent interface. Duplicates a #GFile. a new #GFile that is a duplicate of the given #GFile. input #GFile Creates a hash of a #GFile. 0 if @file is not a valid #GFile, otherwise an integer that can be used as hash value for the #GFile. This function is intended for easily hashing a #GFile to add to a #GHashTable or similar data structure. #gconstpointer to a #GFile Checks equality of two given #GFiles. %TRUE if @file1 and @file2 are equal. the first #GFile the second #GFile Checks to see if a file is native to the system. %TRUE if @file is native input #GFile Checks to see if a #GFile has a given URI scheme. %TRUE if #GFile's backend supports the given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid. input #GFile a string containing a URI scheme Gets the URI scheme for a #GFile. a string containing the URI scheme for the given #GFile or %NULL if the #GFile was constructed with an invalid URI. The returned string should be freed with g_free() when no longer needed. input #GFile Gets the basename for a given #GFile. string containing the #GFile's base name, or %NULL if given #GFile is invalid. The returned string should be freed with g_free() when no longer needed. input #GFile Gets the current path within a #GFile. string containing the #GFile's path, or %NULL if no such path exists. The returned string should be freed with g_free() when no longer needed. input #GFile Gets a URI for the path within a #GFile. a string containing the #GFile's URI. If the #GFile was constructed with an invalid URI, an invalid URI is returned. The returned string should be freed with g_free() when no longer needed. input #GFile Gets the parsed name for the #GFile. a string containing the #GFile's parse name. The returned string should be freed with g_free() when no longer needed. input #GFile Gets the parent directory for the #GFile. a #GFile structure to the parent of the given #GFile or %NULL if there is no parent. Free the returned object with g_object_unref(). input #GFile Checks whether a #GFile contains a specified file. %TRUE if the @file's parent, grandparent, etc is @prefix, %FALSE otherwise. input #GFile input #GFile Gets the path for a #GFile relative to a given path. string with the relative path from @descendant to @parent, or %NULL if @descendant doesn't have @parent as prefix. The returned string should be freed with g_free() when no longer needed. input #GFile input #GFile Resolves a relative path for a #GFile to an absolute path. a #GFile for the resolved path. input #GFile a given relative path string Gets the child #GFile for a given display name. a #GFile to the specified child, or %NULL if the display name couldn't be converted. Free the returned object with g_object_unref(). input #GFile string to a possible child Gets a #GFileEnumerator with the children of a #GFile. A #GFileEnumerator if successful, %NULL on error. Free the returned object with g_object_unref(). input #GFile an attribute query string a set of #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Asynchronously gets a #GFileEnumerator with the children of a #GFile. input #GFile an attribute query string a set of #GFileQueryInfoFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes asynchronously enumerating the children. a #GFileEnumerator or %NULL if an error occurred. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Gets the #GFileInfo for a #GFile. a [class@Gio.FileInfo] for the given @file input file an attribute query string flags to affect the query operation optional cancellable object Asynchronously gets the #GFileInfo for a #GFile. input #GFile an attribute query string a set of #GFileQueryInfoFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous query info operation. #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Gets a #GFileInfo for the file system #GFile is on. a #GFileInfo or %NULL if there was an error. Free the returned object with g_object_unref(). input #GFile an attribute query string optional #GCancellable object, %NULL to ignore Asynchronously gets a #GFileInfo for the file system #GFile is on. input #GFile an attribute query string the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes asynchronously getting the file system info. #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Gets a #GMount for the #GFile. a #GMount where the @file is located or %NULL on error. Free the returned object with g_object_unref(). input #GFile optional #GCancellable object, %NULL to ignore Asynchronously gets the #GMount for a #GFile. a #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes asynchronously getting the volume. #GMount for given @file or %NULL on error. Free the returned object with g_object_unref(). a #GFile a #GAsyncResult Sets the display name for a #GFile. a #GFile specifying what @file was renamed to, or %NULL if there was an error. Free the returned object with g_object_unref(). input #GFile a string optional #GCancellable object, %NULL to ignore Asynchronously sets a #GFile's display name. input #GFile a string the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes asynchronously setting a #GFile's display name. a #GFile or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Returns a list of #GFileAttributeInfos that can be set. a #GFileAttributeInfoList describing the settable attributes. When you are done with it, release it with g_file_attribute_info_list_unref() input #GFile optional #GCancellable object, %NULL to ignore Asynchronously gets a list of #GFileAttributeInfos that can be set. Finishes asynchronously querying settable attributes. Returns a list of #GFileAttributeInfo namespaces that are writable. a #GFileAttributeInfoList describing the writable namespaces. When you are done with it, release it with g_file_attribute_info_list_unref() input #GFile optional #GCancellable object, %NULL to ignore Asynchronously gets a list of #GFileAttributeInfo namespaces that are writable. Finishes asynchronously querying the writable namespaces. Sets a #GFileAttributeInfo. %TRUE if the attribute was set, %FALSE otherwise. input #GFile a string containing the attribute's name The type of the attribute a pointer to the value (or the pointer itself if the type is a pointer type) a set of #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Sets a #GFileAttributeInfo with information from a #GFileInfo. %FALSE if there was any error, %TRUE otherwise. input #GFile a #GFileInfo #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore Asynchronously sets a file's attributes. input #GFile a #GFileInfo a #GFileQueryInfoFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes setting a file's attributes asynchronously. %TRUE if the attributes were set correctly, %FALSE otherwise. input #GFile a #GAsyncResult a #GFileInfo Reads a file asynchronously. #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). #GFile to read a #GCancellable Asynchronously reads a file. input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes asynchronously reading a file. a #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Writes to the end of a file. a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously writes to the end of a file. input #GFile a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file append operation. a valid #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile #GAsyncResult Creates a new file. a #GFileOutputStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously creates a file. input #GFile a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes asynchronously creating a file. a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Replaces the contents of a file. a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously replaces the contents of a file. input #GFile an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes asynchronously replacing a file. a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Deletes a file. %TRUE if the file was deleted. %FALSE otherwise. input #GFile optional #GCancellable object, %NULL to ignore Asynchronously deletes a file. input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous delete. %TRUE if the file was deleted. %FALSE otherwise. input #GFile a #GAsyncResult Sends a #GFile to the Trash location. %TRUE on successful trash, %FALSE otherwise. #GFile to send to trash optional #GCancellable object, %NULL to ignore Asynchronously sends a #GFile to the Trash location. input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file trashing operation. %TRUE on successful trash, %FALSE otherwise. input #GFile a #GAsyncResult Makes a directory. %TRUE on successful creation, %FALSE otherwise. input #GFile optional #GCancellable object, %NULL to ignore Asynchronously makes a directory. input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes making a directory asynchronously. %TRUE on successful directory creation, %FALSE otherwise. input #GFile a #GAsyncResult Makes a symbolic link. %NULL if symbolic links are unsupported. %TRUE on the creation of a new symlink, %FALSE otherwise. a #GFile with the name of the symlink to create a string with the path for the target of the new symlink optional #GCancellable object, %NULL to ignore Asynchronously makes a symbolic link a #GFile with the name of the symlink to create a string with the path for the target of the new symlink the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes making a symbolic link asynchronously. %TRUE on successful directory creation, %FALSE otherwise. input #GFile a #GAsyncResult Copies a file. %NULL if copying is unsupported, which will cause `GFile` to use a fallback copy method where it reads from the source and writes to the destination. %TRUE on success, %FALSE otherwise. input #GFile destination #GFile set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore function to callback with progress information, or %NULL if progress information is not needed user data to pass to @progress_callback Asynchronously copies a file. input #GFile destination #GFile set of #GFileCopyFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore function to callback with progress information, or %NULL if progress information is not needed user data to pass to @progress_callback a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback Finishes an asynchronous copy operation. a %TRUE on success, %FALSE on error. input #GFile a #GAsyncResult Moves a file. %TRUE on successful move, %FALSE otherwise. #GFile pointing to the source location #GFile pointing to the destination location set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore #GFileProgressCallback function for updates gpointer to user data for the callback function Asynchronously moves a file. Since: 2.72 #GFile pointing to the source location #GFile pointing to the destination location set of #GFileCopyFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore #GFileProgressCallback function for updates gpointer to user data for the callback function a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous move operation. Since: 2.72 %TRUE on successful file move, %FALSE otherwise. input source #GFile a #GAsyncResult Mounts a mountable object. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes a mounting operation. a #GFile or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Unmounts a mountable object. input #GFile flags affecting the operation optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an unmount operation. %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Ejects a mountable. input #GFile flags affecting the operation optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an eject operation. %TRUE if the @file was ejected successfully. %FALSE otherwise. input #GFile a #GAsyncResult Mounts a specified location. input #GFile flags affecting the operation a #GMountOperation or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes mounting a specified location. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. input #GFile a #GAsyncResult Creates a #GFileMonitor for the location. a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a set of #GFileMonitorFlags optional #GCancellable object, %NULL to ignore Creates a #GFileMonitor for the location. a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a set of #GFileMonitorFlags optional #GCancellable object, %NULL to ignore Open file read/write. Since 2.22. #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). #GFile to open a #GCancellable Asynchronously opens file read/write. Since 2.22. input #GFile the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous open read/write. Since 2.22. a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Creates file read/write. Since 2.22. a #GFileIOStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). a #GFile a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously creates file read/write. Since 2.22. input #GFile a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous creates read/write. Since 2.22. a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Replaces file read/write. Since 2.22. a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). a #GFile an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore Asynchronously replaces file read/write. Since 2.22. input #GFile an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous replace read/write. Since 2.22. a #GFileIOStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile a #GAsyncResult Starts a mountable object. Since 2.22. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a start operation. Since 2.22. %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Stops a mountable. Since 2.22. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a stop operation. Since 2.22. %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult a boolean that indicates whether the #GFile implementation supports thread-default contexts. Since 2.22. Unmounts a mountable object using a #GMountOperation. Since 2.22. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an unmount operation using a #GMountOperation. Since 2.22. %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Ejects a mountable object using a #GMountOperation. Since 2.22. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an eject operation using a #GMountOperation. Since 2.22. %TRUE if the @file was ejected successfully. %FALSE otherwise. input #GFile a #GAsyncResult Polls a mountable object for media changes. Since 2.22. input #GFile optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a poll operation for media changes. Since 2.22. %TRUE if the operation finished successfully. %FALSE otherwise. input #GFile a #GAsyncResult Recursively measures the disk usage of @file. Since 2.38 %TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. a #GFile #GFileMeasureFlags optional #GCancellable a #GFileMeasureProgressCallback user_data for @progress_callback the number of bytes of disk space used the number of directories encountered the number of non-directories encountered Asynchronously recursively measures the disk usage of @file. Since 2.38 a #GFile #GFileMeasureFlags the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable a #GFileMeasureProgressCallback user_data for @progress_callback a #GAsyncReadyCallback to call when complete the data to pass to callback function Finishes an asynchronous recursive measurement of the disk usage of @file. Since 2.38 %TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. a #GFile the #GAsyncResult passed to your #GAsyncReadyCallback the number of bytes of disk space used the number of directories encountered the number of non-directories encountered Queries whether a file exists. Since 2.84 %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled). input #GFile optional #GCancellable object, %NULL to ignore Stores information about a file system object referenced by a [iface@Gio.File]. Functionality for manipulating basic metadata for files. `GFileInfo` implements methods for getting information that all files should contain, and allows for manipulation of extended attributes. See the [file attributes](file-attributes.html) document for more information on how GIO handles file attributes. To obtain a `GFileInfo` for a [iface@Gio.File], use [method@Gio.File.query_info] (or its async variant). To obtain a `GFileInfo` for a file input or output stream, use [method@Gio.FileInputStream.query_info] or [method@Gio.FileOutputStream.query_info] (or their async variants). To change the actual attributes of a file, you should then set the attribute in the `GFileInfo` and call [method@Gio.File.set_attributes_from_info] or [method@Gio.File.set_attributes_async] on a `GFile`. However, not all attributes can be changed in the file. For instance, the actual size of a file cannot be changed via [method@Gio.FileInfo.set_size]. You may call [method@Gio.File.query_settable_attributes] and [method@Gio.File.query_writable_namespaces] to discover the settable attributes of a particular file at runtime. The direct accessors, such as [method@Gio.FileInfo.get_name], are slightly more optimized than the generic attribute accessors, such as [method@Gio.FileInfo.get_attribute_byte_string].This optimization will matter only if calling the API in a tight loop. It is an error to call these accessors without specifying their required file attributes when creating the `GFileInfo`. Use [method@Gio.FileInfo.has_attribute] or [method@Gio.FileInfo.list_attributes] to check what attributes are specified for a `GFileInfo`. [struct@Gio.FileAttributeMatcher] allows for searching through a `GFileInfo` for attributes. Creates a new file info structure. a #GFileInfo. Clears the status information from @info. a #GFileInfo. First clears all of the [GFileAttribute](file-attributes.html#file-attributes) of @dest_info, and then copies all of the file attributes from @src_info to @dest_info. source to copy attributes from. destination to copy attributes to. Duplicates a file info structure. a duplicate #GFileInfo of @other. a #GFileInfo. Gets the access time of the current @info and returns it as a #GDateTime. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_TIME_ACCESS. If %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC is provided, the resulting #GDateTime will additionally have microsecond precision. If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC must be queried separately using g_file_info_get_attribute_uint32(). access time, or %NULL if unknown a #GFileInfo. Gets the value of an attribute, formatted as a human readable string. This escapes things as needed to make the string valid UTF-8 and readable by humans. It’s not meant to be a machine readable or reversible escaping format. To format file name attributes of type [enum@Gio.FileAttributeType.BYTE_STRING] for output as UTF-8, use [func@GLib.filename_to_utf8] instead: ```c const char *trash_orig_path_byte_string; g_autofree char *trash_orig_path_utf8 = NULL; trash_orig_path_byte_string = g_file_info_get_attribute_byte_string (info, G_FILE_ATTRIBUTE_TRASH_ORIG_PATH); trash_orig_path_utf8 = g_filename_to_utf8 (trash_orig_path_byte_string, -1, NULL, NULL, NULL); if (trash_orig_path_utf8 != NULL) g_message ("Some larger UTF-8 string with filename embedded as %s", trash_orig_path_utf8); ``` a UTF-8 string associated with the given @attribute, or %NULL if the attribute wasn’t set. When you're done with the string it must be freed with g_free(). a #GFileInfo. a file attribute key. Gets the value of a boolean attribute. If the attribute does not contain a boolean value, %FALSE will be returned. the boolean value contained within the attribute. a #GFileInfo. a file attribute key. Gets the value of a byte string attribute. If the attribute does not contain a byte string, %NULL will be returned. the contents of the @attribute value as a byte string, or %NULL otherwise. a #GFileInfo. a file attribute key. Gets the attribute type, value and status for an attribute key. %TRUE if @info has an attribute named @attribute, %FALSE otherwise. a #GFileInfo a file attribute key return location for the attribute type, or %NULL return location for the attribute value, or %NULL; the attribute value will not be %NULL return location for the attribute status, or %NULL Gets the value of a byte string attribute as a file path. If the attribute does not contain a byte string, `NULL` will be returned. This function is meant to be used by language bindings that have specific handling for Unix paths. the contents of the @attribute value as a file path, or %NULL otherwise. a #GFileInfo. a file attribute key. Gets a signed 32-bit integer contained within the attribute. If the attribute does not contain a signed 32-bit integer, or is invalid, 0 will be returned. a signed 32-bit integer from the attribute. a #GFileInfo. a file attribute key. Gets a signed 64-bit integer contained within the attribute. If the attribute does not contain a signed 64-bit integer, or is invalid, 0 will be returned. a signed 64-bit integer from the attribute. a #GFileInfo. a file attribute key. Gets the value of a #GObject attribute. If the attribute does not contain a #GObject, %NULL will be returned. a #GObject associated with the given @attribute, or %NULL otherwise. a #GFileInfo. a file attribute key. Gets the attribute status for an attribute key. a #GFileAttributeStatus for the given @attribute, or %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. a #GFileInfo a file attribute key Gets the value of a string attribute. If the attribute does not contain a string, %NULL will be returned. the contents of the @attribute value as a UTF-8 string, or %NULL otherwise. a #GFileInfo. a file attribute key. Gets the value of a stringv attribute. If the attribute does not contain a stringv, %NULL will be returned. the contents of the @attribute value as a stringv, or %NULL otherwise. Do not free. These returned strings are UTF-8. a #GFileInfo. a file attribute key. Gets the attribute type for an attribute key. a #GFileAttributeType for the given @attribute, or %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. a #GFileInfo. a file attribute key. Gets an unsigned 32-bit integer contained within the attribute. If the attribute does not contain an unsigned 32-bit integer, or is invalid, 0 will be returned. an unsigned 32-bit integer from the attribute. a #GFileInfo. a file attribute key. Gets a unsigned 64-bit integer contained within the attribute. If the attribute does not contain an unsigned 64-bit integer, or is invalid, 0 will be returned. a unsigned 64-bit integer from the attribute. a #GFileInfo. a file attribute key. Gets the file's content type. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. a string containing the file's content type, or %NULL if unknown. a #GFileInfo. Gets the creation time of the current @info and returns it as a #GDateTime. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_TIME_CREATED. If %G_FILE_ATTRIBUTE_TIME_CREATED_USEC is provided, the resulting #GDateTime will additionally have microsecond precision. If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_CREATED_NSEC must be queried separately using g_file_info_get_attribute_uint32(). creation time, or %NULL if unknown a #GFileInfo. Returns the #GDateTime representing the deletion date of the file, as available in %G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the %G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned. a #GDateTime, or %NULL. a #GFileInfo. Gets a display name for a file. This is guaranteed to always be set. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME. a string containing the display name. a #GFileInfo. Gets the edit name for a file. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME. a string containing the edit name. a #GFileInfo. Gets the [entity tag][iface@Gio.File#entity-tags] for a given #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_ETAG_VALUE. a string containing the value of the "etag:value" attribute. a #GFileInfo. Gets a file's type (whether it is a regular file, symlink, etc). This is different from the file's content type, see g_file_info_get_content_type(). It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_TYPE. a #GFileType for the given file. a #GFileInfo. Gets the icon for a file. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_ICON. #GIcon for the given @info. a #GFileInfo. Checks if a file is a backup file. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP. %TRUE if file is a backup file, %FALSE otherwise. a #GFileInfo. Checks if a file is hidden. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN. %TRUE if the file is a hidden file, %FALSE otherwise. a #GFileInfo. Checks if a file is a symlink. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK. %TRUE if the given @info is a symlink. a #GFileInfo. Gets the modification time of the current @info and returns it as a #GDateTime. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_TIME_MODIFIED. If %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC is provided, the resulting #GDateTime will additionally have microsecond precision. If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC must be queried separately using g_file_info_get_attribute_uint32(). modification time, or %NULL if unknown a #GFileInfo. Gets the modification time of the current @info and sets it in @result. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_TIME_MODIFIED. If %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC is provided it will be used too. Use g_file_info_get_modification_date_time() instead, as #GTimeVal is deprecated due to the year 2038 problem. a #GFileInfo. a #GTimeVal. Gets the name for a file. This is guaranteed to always be set. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_NAME. a string containing the file name. a #GFileInfo. Gets the file's size (in bytes). The size is retrieved through the value of the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute and is converted from #guint64 to #goffset before returning the result. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_SIZE. a #goffset containing the file's size (in bytes). a #GFileInfo. Gets the value of the sort_order attribute from the #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. a #gint32 containing the value of the "standard::sort_order" attribute. a #GFileInfo. Gets the symbolic icon for a file. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON. #GIcon for the given @info. a #GFileInfo. Gets the symlink target for a given #GFileInfo. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET. a string containing the symlink target. a #GFileInfo. Checks if a file info structure has an attribute named @attribute. %TRUE if @info has an attribute named @attribute, %FALSE otherwise. a #GFileInfo. a file attribute key. Checks if a file info structure has an attribute in the specified @name_space. %TRUE if @info has an attribute in @name_space, %FALSE otherwise. a #GFileInfo. a file attribute namespace. Lists the file info structure's attributes. a null-terminated array of strings of all of the possible attribute types for the given @name_space, or %NULL on error. a #GFileInfo. a file attribute key's namespace, or %NULL to list all attributes. Removes all cases of @attribute from @info if it exists. a #GFileInfo. a file attribute key. Sets the %G_FILE_ATTRIBUTE_TIME_ACCESS and %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC attributes in the file info to the given date/time value. %G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC will be cleared. a #GFileInfo. a #GDateTime. Sets the @attribute to contain the given value, if possible. To unset the attribute, use %G_FILE_ATTRIBUTE_TYPE_INVALID for @type. a #GFileInfo. a file attribute key. a #GFileAttributeType pointer to the value Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. a boolean value. Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. a byte string. Sets the @attribute to contain the given @attr_value, if possible. This function is meant to be used by language bindings that have specific handling for Unix paths. a #GFileInfo. a file attribute key. a file path. Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. a signed 32-bit integer Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. attribute name to set. int64 value to set attribute to. Sets @mask on @info to match specific attribute types. a #GFileInfo. a #GFileAttributeMatcher. Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. a #GObject. Sets the attribute status for an attribute key. This is only needed by external code that implement g_file_set_attributes_from_info() or similar functions. The attribute must exist in @info for this to work. Otherwise %FALSE is returned and @info is unchanged. %TRUE if the status was changed, %FALSE if the key was not set. a #GFileInfo a file attribute key a #GFileAttributeStatus Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. a UTF-8 string. Sets the @attribute to contain the given @attr_value, if possible. Sinze: 2.22 a #GFileInfo. a file attribute key a %NULL terminated array of UTF-8 strings. Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. an unsigned 32-bit integer. Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. an unsigned 64-bit integer. Sets the content type attribute for a given #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. a #GFileInfo. a [content type](content-types.html#content-types). Sets the %G_FILE_ATTRIBUTE_TIME_CREATED and %G_FILE_ATTRIBUTE_TIME_CREATED_USEC attributes in the file info to the given date/time value. %G_FILE_ATTRIBUTE_TIME_CREATED_NSEC will be cleared. a #GFileInfo. a #GDateTime. Sets the display name for the current #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME. a #GFileInfo. a string containing a display name. Sets the edit name for the current file. See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME. a #GFileInfo. a string containing an edit name. Sets the file type in a #GFileInfo to @type. See %G_FILE_ATTRIBUTE_STANDARD_TYPE. a #GFileInfo. a #GFileType. Sets the icon for a given #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_ICON. a #GFileInfo. a #GIcon. Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden. See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN. a #GFileInfo. a #gboolean. Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink. See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK. a #GFileInfo. a #gboolean. Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the given date/time value. %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared. a #GFileInfo. a #GDateTime. Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the given time value. %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared. Use g_file_info_set_modification_date_time() instead, as #GTimeVal is deprecated due to the year 2038 problem. a #GFileInfo. a #GTimeVal. Sets the name attribute for the current #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_NAME. a #GFileInfo. a string containing a name. Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info to the given size. a #GFileInfo. a #goffset containing the file's size. Sets the sort order attribute in the file info structure. See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. a #GFileInfo. a sort order integer. Sets the symbolic icon for a given #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON. a #GFileInfo. a #GIcon. Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info to the given symlink target. a #GFileInfo. a static string containing a path to a symlink target. Unsets a mask set by g_file_info_set_attribute_mask(), if one is set. #GFileInfo. `GFileInputStream` provides input streams that take their content from a file. `GFileInputStream` implements [iface@Gio.Seekable], which allows the input stream to jump to arbitrary positions in the file, provided the filesystem of the file allows it. To find the position of a file input stream, use [method@Gio.Seekable.tell]. To find out if a file input stream supports seeking, use [vfunc@Gio.Seekable.can_seek]. To position a file input stream, use [vfunc@Gio.Seekable.seek]. Queries a file input stream the given @attributes. This function blocks while querying the stream. For the asynchronous (non-blocking) version of this function, see g_file_input_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with %G_IO_ERROR_PENDING. a #GFileInfo, or %NULL on error. a #GFileInputStream. a file attribute query string. optional #GCancellable object, %NULL to ignore. Queries the stream information asynchronously. When the operation is finished @callback will be called. You can then call g_file_input_stream_query_info_finish() to get the result of the operation. For the synchronous version of this function, see g_file_input_stream_query_info(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set a #GFileInputStream. a file attribute query string. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous info query operation. #GFileInfo. a #GFileInputStream. a #GAsyncResult. Queries a file input stream the given @attributes. This function blocks while querying the stream. For the asynchronous (non-blocking) version of this function, see g_file_input_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with %G_IO_ERROR_PENDING. a #GFileInfo, or %NULL on error. a #GFileInputStream. a file attribute query string. optional #GCancellable object, %NULL to ignore. Queries the stream information asynchronously. When the operation is finished @callback will be called. You can then call g_file_input_stream_query_info_finish() to get the result of the operation. For the synchronous version of this function, see g_file_input_stream_query_info(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set a #GFileInputStream. a file attribute query string. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous info query operation. #GFileInfo. a #GFileInputStream. a #GAsyncResult. a #GFileInfo, or %NULL on error. a #GFileInputStream. a file attribute query string. optional #GCancellable object, %NULL to ignore. a #GFileInputStream. a file attribute query string. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function #GFileInfo. a #GFileInputStream. a #GAsyncResult. Flags that can be used with g_file_measure_disk_usage(). No flags set. Report any error encountered while traversing the directory tree. Normally errors are only reported for the toplevel file. Tally usage based on apparent file sizes. Normally, the block-size is used, if available, as this is a more accurate representation of disk space used. Compare with `du --apparent-size`. Since GLib 2.78. and similarly to `du` since GNU Coreutils 9.2, this will ignore the sizes of file types other than regular files and links, as the sizes of other file types are not specified in a standard way. Do not cross mount point boundaries. Compare with `du -x`. This callback type is used by g_file_measure_disk_usage() to make periodic progress reports when measuring the amount of disk spaced used by a directory. These calls are made on a best-effort basis and not all types of #GFile will support them. At the minimum, however, one call will always be made immediately. In the case that there is no support, @reporting will be set to %FALSE (and the other values undefined) and no further calls will be made. Otherwise, the @reporting will be %TRUE and the other values all-zeros during the first (immediate) call. In this way, you can know which type of progress UI to show without a delay. For g_file_measure_disk_usage() the callback is made directly. For g_file_measure_disk_usage_async() the callback is made via the default main context of the calling thread (ie: the same way that the final async result would be reported). @current_size is in the same units as requested by the operation (see %G_FILE_MEASURE_APPARENT_SIZE). The frequency of the updates is implementation defined, but is ideally about once every 200ms. The last progress callback may or may not be equal to the final result. Always check the async result to get the final value. %TRUE if more reports will come the current cumulative size measurement the number of directories visited so far the number of non-directory files encountered the data passed to the original request for this callback Monitors a file or directory for changes. To obtain a `GFileMonitor` for a file or directory, use [method@Gio.File.monitor], [method@Gio.File.monitor_file], or [method@Gio.File.monitor_directory]. To get informed about changes to the file or directory you are monitoring, connect to the [signal@Gio.FileMonitor::changed] signal. The signal will be emitted in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread that the monitor was created in (though if the global default main context is blocked, this may cause notifications to be blocked even if the thread-default context is still running). Cancels a file monitor. always %TRUE a #GFileMonitor. Cancels a file monitor. always %TRUE a #GFileMonitor. Emits the #GFileMonitor::changed signal if a change has taken place. Should be called from file monitor implementations only. Implementations are responsible to call this method from the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread that the monitor was created in. a #GFileMonitor. a #GFile. a #GFile, or %NULL. a set of #GFileMonitorEvent flags. Returns whether the monitor is canceled. %TRUE if monitor is canceled. %FALSE otherwise. a #GFileMonitor Sets the rate limit to which the @monitor will report consecutive change events to the same file. a #GFileMonitor. a non-negative integer with the limit in milliseconds to poll for changes Whether the monitor has been cancelled. The limit of the monitor to watch for changes, in milliseconds. Emitted when @file has been changed. If using %G_FILE_MONITOR_WATCH_MOVES on a directory monitor, and the information is available (and if supported by the backend), @event_type may be %G_FILE_MONITOR_EVENT_RENAMED, %G_FILE_MONITOR_EVENT_MOVED_IN or %G_FILE_MONITOR_EVENT_MOVED_OUT. In all cases @file will be a child of the monitored directory. For renames, @file will be the old name and @other_file is the new name. For "moved in" events, @file is the name of the file that appeared and @other_file is the old name that it was moved from (in another directory). For "moved out" events, @file is the name of the file that used to be in this directory and @other_file is the name of the file at its new location. It makes sense to treat %G_FILE_MONITOR_EVENT_MOVED_IN as equivalent to %G_FILE_MONITOR_EVENT_CREATED and %G_FILE_MONITOR_EVENT_MOVED_OUT as equivalent to %G_FILE_MONITOR_EVENT_DELETED, with extra information. %G_FILE_MONITOR_EVENT_RENAMED is equivalent to a delete/create pair. This is exactly how the events will be reported in the case that the %G_FILE_MONITOR_WATCH_MOVES flag is not in use. If using the deprecated flag %G_FILE_MONITOR_SEND_MOVED flag and @event_type is %G_FILE_MONITOR_EVENT_MOVED, @file will be set to a #GFile containing the old path, and @other_file will be set to a #GFile containing the new path. In all the other cases, @other_file will be set to #NULL. a #GFile. a #GFile or #NULL. a #GFileMonitorEvent. always %TRUE a #GFileMonitor. Specifies what type of event a monitor event is. a file changed. a hint that this was probably the last change in a set of changes. a file was deleted. a file was created. a file attribute was changed. the file location will soon be unmounted. the file location was unmounted. the file was moved -- only sent if the (deprecated) %G_FILE_MONITOR_SEND_MOVED flag is set the file was renamed within the current directory -- only sent if the %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46. the file was moved into the monitored directory from another location -- only sent if the %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46. the file was moved out of the monitored directory to another location -- only sent if the %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46 Flags used to set what a #GFileMonitor will watch for. No flags set. Watch for mount events. Pair DELETED and CREATED events caused by file renames (moves) and send a single G_FILE_MONITOR_EVENT_MOVED event instead (NB: not supported on all backends; the default behaviour -without specifying this flag- is to send single DELETED and CREATED events). Deprecated since 2.46: use %G_FILE_MONITOR_WATCH_MOVES instead. Watch for changes to the file made via another hard link. Since 2.36. Watch for rename operations on a monitored directory. This causes %G_FILE_MONITOR_EVENT_RENAMED, %G_FILE_MONITOR_EVENT_MOVED_IN and %G_FILE_MONITOR_EVENT_MOVED_OUT events to be emitted when possible. Since: 2.46. `GFileOutputStream` provides output streams that write their content to a file. `GFileOutputStream` implements [iface@Gio.Seekable], which allows the output stream to jump to arbitrary positions in the file and to truncate the file, provided the filesystem of the file supports these operations. To find the position of a file output stream, use [method@Gio.Seekable.tell]. To find out if a file output stream supports seeking, use [method@Gio.Seekable.can_seek].To position a file output stream, use [method@Gio.Seekable.seek]. To find out if a file output stream supports truncating, use [method@Gio.Seekable.can_truncate]. To truncate a file output stream, use [method@Gio.Seekable.truncate]. Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. the entity tag for the stream. a #GFileOutputStream. Queries a file output stream for the given @attributes. This function blocks while querying the stream. For the asynchronous version of this function, see g_file_output_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with %G_IO_ERROR_PENDING. Can fail if the stream was already closed (with @error being set to %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being set to %G_IO_ERROR_PENDING), or if querying info is not supported for the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In all cases of failure, %NULL will be returned. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will be returned. a #GFileInfo for the @stream, or %NULL on error. a #GFileOutputStream. a file attribute query string. optional #GCancellable object, %NULL to ignore. Asynchronously queries the @stream for a #GFileInfo. When completed, @callback will be called with a #GAsyncResult which can be used to finish the operation with g_file_output_stream_query_info_finish(). For the synchronous version of this function, see g_file_output_stream_query_info(). a #GFileOutputStream. a file attribute query string. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function Finalizes the asynchronous query started by g_file_output_stream_query_info_async(). A #GFileInfo for the finished query. a #GFileOutputStream. a #GAsyncResult. Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. the entity tag for the stream. a #GFileOutputStream. Queries a file output stream for the given @attributes. This function blocks while querying the stream. For the asynchronous version of this function, see g_file_output_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with %G_IO_ERROR_PENDING. Can fail if the stream was already closed (with @error being set to %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being set to %G_IO_ERROR_PENDING), or if querying info is not supported for the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In all cases of failure, %NULL will be returned. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will be returned. a #GFileInfo for the @stream, or %NULL on error. a #GFileOutputStream. a file attribute query string. optional #GCancellable object, %NULL to ignore. Asynchronously queries the @stream for a #GFileInfo. When completed, @callback will be called with a #GAsyncResult which can be used to finish the operation with g_file_output_stream_query_info_finish(). For the synchronous version of this function, see g_file_output_stream_query_info(). a #GFileOutputStream. a file attribute query string. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function Finalizes the asynchronous query started by g_file_output_stream_query_info_async(). A #GFileInfo for the finished query. a #GFileOutputStream. a #GAsyncResult. a #GFileInfo for the @stream, or %NULL on error. a #GFileOutputStream. a file attribute query string. optional #GCancellable object, %NULL to ignore. a #GFileOutputStream. a file attribute query string. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function A #GFileInfo for the finished query. a #GFileOutputStream. a #GAsyncResult. the entity tag for the stream. a #GFileOutputStream. When doing file operations that may take a while, such as moving a file or copying a file, a progress callback is used to pass how far along that operation is to the application. the current number of bytes in the operation. the total number of bytes in the operation. user data passed to the callback. Flags used when querying a #GFileInfo. No flags set. Don't follow symlinks. When loading the partial contents of a file with g_file_load_partial_contents_async(), it may become necessary to determine if any more data from the file should be loaded. A #GFileReadMoreCallback function facilitates this by returning %TRUE if more data should be read, or %FALSE otherwise. %TRUE if more data should be read back. %FALSE otherwise. the data as currently read. the size of the data currently read. data passed to the callback. Indicates the file's on-disk type. On Windows systems a file will never have %G_FILE_TYPE_SYMBOLIC_LINK type; use #GFileInfo and %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK to determine whether a file is a symlink or not. This is due to the fact that NTFS does not have a single filesystem object type for symbolic links - it has files that symlink to files, and directories that symlink to directories. #GFileType enumeration cannot precisely represent this important distinction, which is why all Windows symlinks will continue to be reported as %G_FILE_TYPE_REGULAR or %G_FILE_TYPE_DIRECTORY. File's type is unknown. File handle represents a regular file. File handle represents a directory. File handle represents a symbolic link (Unix systems). File is a "special" file, such as a socket, fifo, block device, or character device. File is a shortcut (Windows systems). File is a mountable location. Completes partial file and directory names given a partial string by looking in the file system for clues. Can return a list of possible completion strings for widget implementations. Creates a new filename completer. a #GFilenameCompleter. Obtains a suffix completion for @initial_text from @completer. Suffix will be an empty string if there's no shared suffix among matching completions. If there's no matching completions anyway, `NULL` is returned. a suffix completion string, or `NULL` if no completion exists. the filename completer. text to be completed. Gets an array of completion strings for a given initial text. array of strings with possible completions for @initial_text. This array must be freed by g_strfreev() when finished. the filename completer. text to be completed. If @dirs_only is %TRUE, @completer will only complete directory names, and not file names. This function needs to be called before waiting for results from the completer to be populated. the filename completer. a #gboolean. Emitted when the file name completion information comes available. Indicates a hint from the file system whether files should be previewed in a file manager. Returned as the value of the key %G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW. Only preview files if user has explicitly requested it. Preview files if user has requested preview of "local" files. Never preview files. Base class for input stream implementations that perform some kind of filtering operation on a base stream. Typical examples of filtering operations are character set conversion, compression and byte order flipping. Gets the base stream for the filter stream. a #GInputStream. a #GFilterInputStream. Returns whether the base stream will be closed when @stream is closed. %TRUE if the base stream will be closed. a #GFilterInputStream. Sets whether the base stream will be closed when @stream is closed. a #GFilterInputStream. %TRUE to close the base stream. The underlying base stream on which the I/O ops will be done. Whether the base stream should be closed when the filter stream is closed. Base class for output stream implementations that perform some kind of filtering operation on a base stream. Typical examples of filtering operations are character set conversion, compression and byte order flipping. Gets the base stream for the filter stream. a [class@Gio.OutputStream]. a [class@Gio.FilterOutputStream]. Returns whether the base stream will be closed when @stream is closed. `TRUE` if the base stream will be closed. a [class@Gio.FilterOutputStream]. Sets whether the base stream will be closed when @stream is closed. a [class@Gio.FilterOutputStream]. `TRUE` to close the base stream. The underlying base stream on which the I/O ops will be done. Whether the base stream should be closed when the filter stream is closed. Error codes returned by GIO functions. Note that this domain may be extended in future GLib releases. In general, new error codes either only apply to new APIs, or else replace %G_IO_ERROR_FAILED in cases that were not explicitly distinguished before. You should therefore avoid writing code like |[<!-- language="C" --> if (g_error_matches (error, G_IO_ERROR, G_IO_ERROR_FAILED)) { // Assume that this is EPRINTERONFIRE ... } ]| but should instead treat all unrecognized error codes the same as %G_IO_ERROR_FAILED. See also #GPollableReturn for a cheaper way of returning %G_IO_ERROR_WOULD_BLOCK to callers without allocating a #GError. Generic error condition for when an operation fails and no more specific #GIOErrorEnum value is defined. File not found. File already exists. File is a directory. File is not a directory. File is a directory that isn't empty. File is not a regular file. File is not a symbolic link. File cannot be mounted. Filename is too many characters. Filename is invalid or contains invalid characters. File contains too many symbolic links. No space left on drive. Invalid argument. Permission denied. Operation (or one of its parameters) not supported File isn't mounted. File is already mounted. File was closed. Operation was cancelled. See #GCancellable. Operations are still pending. File is read only. Backup couldn't be created. File's Entity Tag was incorrect. Operation timed out. Operation would be recursive. File is busy. Operation would block. Host couldn't be found (remote operations). Operation would merge files. Operation failed and a helper program has already interacted with the user. Do not display any error dialog. The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. Since 2.20 The object has not been initialized. Since 2.22 The requested address is already in use. Since 2.22 Need more input to finish operation. Since 2.24 The input data was invalid. Since 2.24 A remote object generated an error that doesn't correspond to a locally registered #GError error domain. Use g_dbus_error_get_remote_error() to extract the D-Bus error name and g_dbus_error_strip_remote_error() to fix up the message so it matches what was received on the wire. Since 2.26. Host unreachable. Since 2.26 Network unreachable. Since 2.26 Connection refused. Since 2.26 Connection to proxy server failed. Since 2.26 Proxy authentication failed. Since 2.26 Proxy server needs authentication. Since 2.26 Proxy connection is not allowed by ruleset. Since 2.26 Broken pipe. Since 2.36 Connection closed by peer. Note that this is the same code as %G_IO_ERROR_BROKEN_PIPE; before 2.44 some "connection closed" errors returned %G_IO_ERROR_BROKEN_PIPE, but others returned %G_IO_ERROR_FAILED. Now they should all return the same value, which has this more logical name. Since 2.44. Transport endpoint is not connected. Since 2.44 Message too large. Since 2.48. No such device found. Since 2.74 Destination address unset. Since 2.80 #GIOExtension is an opaque data structure and can only be accessed using the following functions. Gets the name under which @extension was registered. Note that the same type may be registered as extension for multiple extension points, under different names. the name of @extension. a #GIOExtension Gets the priority with which @extension was registered. the priority of @extension a #GIOExtension Gets the type associated with @extension. the type of @extension a #GIOExtension Gets a reference to the class for the type that is associated with @extension. the #GTypeClass for the type of @extension a #GIOExtension `GIOExtensionPoint` provides a mechanism for modules to extend the functionality of the library or application that loaded it in an organized fashion. An extension point is identified by a name, and it may optionally require that any implementation must be of a certain type (or derived thereof). Use [func@Gio.IOExtensionPoint.register] to register an extension point, and [method@Gio.IOExtensionPoint.set_required_type] to set a required type. A module can implement an extension point by specifying the [type@GObject.Type] that implements the functionality. Additionally, each implementation of an extension point has a name, and a priority. Use [func@Gio.IOExtensionPoint.implement] to implement an extension point. ```c GIOExtensionPoint *ep; // Register an extension point ep = g_io_extension_point_register ("my-extension-point"); g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); ``` ```c // Implement an extension point G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE) g_io_extension_point_implement ("my-extension-point", my_example_impl_get_type (), "my-example", 10); ``` It is up to the code that registered the extension point how it uses the implementations that have been associated with it. Depending on the use case, it may use all implementations, or only the one with the highest priority, or pick a specific one by name. To avoid opening all modules just to find out what extension points they implement, GIO makes use of a caching mechanism, see [gio-querymodules](gio-querymodules.html). You are expected to run this command after installing a GIO module. The `GIO_EXTRA_MODULES` environment variable can be used to specify additional directories to automatically load modules from. This environment variable has the same syntax as the `PATH`. If two modules have the same base name in different directories, then the latter one will be ignored. If additional directories are specified GIO will load modules from the built-in directory last. Finds a #GIOExtension for an extension point by name. the #GIOExtension for @extension_point that has the given name, or %NULL if there is no extension with that name a #GIOExtensionPoint the name of the extension to get Gets a list of all extensions that implement this extension point. The list is sorted by priority, beginning with the highest priority. a #GList of #GIOExtensions. The list is owned by GIO and should not be modified. a #GIOExtensionPoint Gets the required type for @extension_point. the #GType that all implementations must have, or %G_TYPE_INVALID if the extension point has no required type a #GIOExtensionPoint Sets the required type for @extension_point to @type. All implementations must henceforth have this type. a #GIOExtensionPoint the #GType to require Registers @type as extension for the extension point with name @extension_point_name. If @type has already been registered as an extension for this extension point, the existing #GIOExtension object is returned. a #GIOExtension object for #GType the name of the extension point the #GType to register as extension the name for the extension the priority for the extension Looks up an existing extension point. the #GIOExtensionPoint, or %NULL if there is no registered extension point with the given name. the name of the extension point Registers an extension point. the new #GIOExtensionPoint. This object is owned by GIO and should not be freed. The name of the extension point Provides an interface and default functions for loading and unloading modules. This is used internally to make GIO extensible, but can also be used by others to implement module loading. Creates a new GIOModule that will load the specific shared library when in use. a #GIOModule from given @filename, or %NULL on error. filename of the shared library module. Optional API for GIO modules to implement. Should return a list of all the extension points that may be implemented in this module. This method will not be called in normal use, however it may be called when probing existing modules and recording which extension points that this model is used for. This means we won't have to load and initialize this module unless its needed. If this function is not implemented by the module the module will always be loaded, initialized and then unloaded on application startup so that it can register its extension points during init. Note that a module need not actually implement all the extension points that g_io_module_query() returns, since the exact list of extension may depend on runtime issues. However all extension points actually implemented must be returned by g_io_module_query() (if defined). When installing a module that implements g_io_module_query() you must run gio-querymodules in order to build the cache files required for lazy loading. Since 2.56, this function should be named `g_io_<modulename>_query`, where `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and everything after the first dot removed, and with `-` replaced with `_` throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. Using the new symbol names avoids name clashes when building modules statically. The old symbol names continue to be supported, but cannot be used for static builds. A %NULL-terminated array of strings, listing the supported extension points of the module. The array must be suitable for freeing with g_strfreev(). Required API for GIO modules to implement. This function is run after the module has been loaded into GIO, to initialize the module. Typically, this function will call g_io_extension_point_implement(). Since 2.56, this function should be named `g_io_<modulename>_load`, where `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and everything after the first dot removed, and with `-` replaced with `_` throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. Using the new symbol names avoids name clashes when building modules statically. The old symbol names continue to be supported, but cannot be used for static builds. a #GIOModule. Required API for GIO modules to implement. This function is run when the module is being unloaded from GIO, to finalize the module. Since 2.56, this function should be named `g_io_<modulename>_unload`, where `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and everything after the first dot removed, and with `-` replaced with `_` throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. Using the new symbol names avoids name clashes when building modules statically. The old symbol names continue to be supported, but cannot be used for static builds. a #GIOModule. Represents a scope for loading IO modules. A scope can be used for blocking duplicate modules, or blocking a module you don't want to load. The scope can be used with g_io_modules_load_all_in_directory_with_scope() or g_io_modules_scan_all_in_directory_with_scope(). Block modules with the given @basename from being loaded when this scope is used with g_io_modules_scan_all_in_directory_with_scope() or g_io_modules_load_all_in_directory_with_scope(). a module loading scope the basename to block Free a module scope. a module loading scope Create a new scope for loading of IO modules. A scope can be used for blocking duplicate modules, or blocking a module you don't want to load. Specify the %G_IO_MODULE_SCOPE_BLOCK_DUPLICATES flag to block modules which have the same base name as a module that has already been seen in this scope. the new module scope flags for the new scope Flags for use with g_io_module_scope_new(). No module scan flags When using this scope to load or scan modules, automatically block a modules which has the same base basename as previously loaded module. Opaque class for defining and scheduling IO jobs. Use [struct@GLib.ThreadPool] or [method@Gio.Task.run_in_thread] Used from an I/O job to send a callback to be run in the thread that the job was started from, waiting for the result (and thus blocking the I/O job). Use g_main_context_invoke(). The return value of @func a #GIOSchedulerJob a #GSourceFunc callback that will be called in the original thread data to pass to @func a #GDestroyNotify for @user_data, or %NULL Used from an I/O job to send a callback to be run asynchronously in the thread that the job was started from. The callback will be run when the main loop is available, but at that time the I/O job might have finished. The return value from the callback is ignored. Note that if you are passing the @user_data from g_io_scheduler_push_job() on to this function you have to ensure that it is not freed before @func is called, either by passing %NULL as @notify to g_io_scheduler_push_job() or by using refcounting for @user_data. Use g_main_context_invoke(). a #GIOSchedulerJob a #GSourceFunc callback that will be called in the original thread data to pass to @func a #GDestroyNotify for @user_data, or %NULL I/O Job function. Long-running jobs should periodically check the @cancellable to see if they have been cancelled. Use [struct@GLib.ThreadPool] or [method@Gio.Task.run_in_thread] %TRUE if this function should be called again to complete the job, %FALSE if the job is complete (or cancelled) a #GIOSchedulerJob. optional #GCancellable object, %NULL to ignore. data passed to the callback function `GIOStream` represents an object that has both read and write streams. Generally the two streams act as separate input and output streams, but they share some common resources and state. For instance, for seekable streams, both streams may use the same position. Examples of `GIOStream` objects are [class@Gio.SocketConnection], which represents a two-way network connection; and [class@Gio.FileIOStream], which represents a file handle opened in read-write mode. To do the actual reading and writing you need to get the substreams with [method@Gio.IOStream.get_input_stream] and [method@Gio.IOStream.get_output_stream]. The `GIOStream` object owns the input and the output streams, not the other way around, so keeping the substreams alive will not keep the `GIOStream` object alive. If the `GIOStream` object is freed it will be closed, thus closing the substreams, so even if the substreams stay alive they will always return `G_IO_ERROR_CLOSED` for all operations. To close a stream use [method@Gio.IOStream.close] which will close the common stream object and also the individual substreams. You can also close the substreams themselves. In most cases this only marks the substream as closed, so further I/O on it fails but common state in the `GIOStream` may still be open. However, some streams may support ‘half-closed’ states where one direction of the stream is actually shut down. Operations on `GIOStream`s cannot be started while another operation on the `GIOStream` or its substreams is in progress. Specifically, an application can read from the [class@Gio.InputStream] and write to the [class@Gio.OutputStream] simultaneously (either in separate threads, or as asynchronous operations in the same thread), but an application cannot start any `GIOStream` operation while there is a `GIOStream`, `GInputStream` or `GOutputStream` operation in progress, and an application can’t start any `GInputStream` or `GOutputStream` operation while there is a `GIOStream` operation in progress. This is a product of individual stream operations being associated with a given [type@GLib.MainContext] (the thread-default context at the time the operation was started), rather than entire streams being associated with a single `GMainContext`. GIO may run operations on `GIOStream`s from other (worker) threads, and this may be exposed to application code in the behaviour of wrapper streams, such as [class@Gio.BufferedInputStream] or [class@Gio.TlsConnection]. With such wrapper APIs, application code may only run operations on the base (wrapped) stream when the wrapper stream is idle. Note that the semantics of such operations may not be well-defined due to the state the wrapper stream leaves the base stream in (though they are guaranteed not to crash). Finishes an asynchronous io stream splice operation. %TRUE on success, %FALSE otherwise. a #GAsyncResult. Requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished @callback will be called. You can then call g_io_stream_close_finish() to get the result of the operation. For behaviour details see g_io_stream_close(). The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. a #GIOStream the io priority of the request optional cancellable object a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Closes a stream. %TRUE if stream was successfully closed, %FALSE otherwise. a #GIOStream a #GAsyncResult Gets the input stream for this object. This is used for reading. a #GInputStream, owned by the #GIOStream. Do not free. a #GIOStream Gets the output stream for this object. This is used for writing. a #GOutputStream, owned by the #GIOStream. Do not free. a #GIOStream Clears the pending flag on @stream. a #GIOStream Closes the stream, releasing resources related to it. This will also close the individual input and output streams, if they are not already closed. Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. Closing a stream multiple times will not return an error. Closing a stream will automatically flush any outstanding buffers in the stream. Streams will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. Some streams might keep the backing store of the stream (e.g. a file descriptor) open after the stream is closed. See the documentation for the individual stream for details. On failure the first error that happened will be reported, but the close operation will finish as much as possible. A stream that failed to close will still return %G_IO_ERROR_CLOSED for all operations. Still, it is important to check and report the error to the user, otherwise there might be a loss of data as all data might not be written. If @cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave the stream closed, but some streams can use a faster close that doesn't block to e.g. check errors. The default implementation of this method just calls close on the individual input/output streams. %TRUE on success, %FALSE on failure a #GIOStream optional #GCancellable object, %NULL to ignore Requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished @callback will be called. You can then call g_io_stream_close_finish() to get the result of the operation. For behaviour details see g_io_stream_close(). The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. a #GIOStream the io priority of the request optional cancellable object a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Closes a stream. %TRUE if stream was successfully closed, %FALSE otherwise. a #GIOStream a #GAsyncResult Gets the input stream for this object. This is used for reading. a #GInputStream, owned by the #GIOStream. Do not free. a #GIOStream Gets the output stream for this object. This is used for writing. a #GOutputStream, owned by the #GIOStream. Do not free. a #GIOStream Checks if a stream has pending actions. %TRUE if @stream has pending actions. a #GIOStream Checks if a stream is closed. %TRUE if the stream is closed. a #GIOStream Sets @stream to have actions pending. If the pending flag is already set or @stream is closed, it will return %FALSE and set @error. %TRUE if pending was previously unset and is now set. a #GIOStream Asynchronously splice the output stream of @stream1 to the input stream of @stream2, and splice the output stream of @stream2 to the input stream of @stream1. When the operation is finished @callback will be called. You can then call g_io_stream_splice_finish() to get the result of the operation. a #GIOStream. a #GIOStream. a set of #GIOStreamSpliceFlags. the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Whether the stream is closed. The [class@Gio.InputStream] to read from. The [class@Gio.OutputStream] to write to. a #GInputStream, owned by the #GIOStream. Do not free. a #GIOStream a #GOutputStream, owned by the #GIOStream. Do not free. a #GIOStream a #GIOStream the io priority of the request optional cancellable object a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function %TRUE if stream was successfully closed, %FALSE otherwise. a #GIOStream a #GAsyncResult GIOStreamSpliceFlags determine how streams should be spliced. Do not close either stream. Close the first stream after the splice. Close the second stream after the splice. Wait for both splice operations to finish before calling the callback. Contains the type of service (ToS) byte of an IPv4 header. This consists of the DSCP field as per [RFC 2474](https://www.rfc-editor.org/rfc/rfc2474#section-3), and the ECN field as per [RFC 3168](https://www.rfc-editor.org/rfc/rfc3168#section-5). It may be received using [method@Gio.Socket.receive_message] over UDP sockets (i.e. sockets in the `G_SOCKET_FAMILY_IPV4` family with `G_SOCKET_TYPE_DATAGRAM` type). The message is not meant for sending. To set ToS field to be used in datagrams sent on a [class@Gio.Socket] use: ```c g_socket_set_option (socket, IPPROTO_IP, IP_TOS, <ToS value>, &error); ``` Creates a new type-of-service message with given DSCP and ECN values. a new type-of-service message the DSCP value of the message the ECN value of the message Gets the differentiated services code point stored in @message. A DSCP value as described in [RFC 2474](https://www.rfc-editor.org/rfc/rfc2474.html#section-3). a type-of-service message Gets the Explicit Congestion Notification code point stored in @message. An ECN value as described in [RFC 3168](https://www.rfc-editor.org/rfc/rfc3168#section-5). a type-of-service message Contains the Traffic Class byte of an IPv6 header. This consists of the DSCP field as per [RFC 2474](https://www.rfc-editor.org/rfc/rfc2474#section-3), and the ECN field as per [RFC 3168](https://www.rfc-editor.org/rfc/rfc3168#section-5). It may be received using [method@Gio.Socket.receive_message] over UDP sockets (i.e. sockets in the `G_SOCKET_FAMILY_IPV6` family with `G_SOCKET_TYPE_DATAGRAM` type). The message is not meant for sending. To set Traffic Class field to be used in datagrams sent on a [class@Gio.Socket] use: ```c g_socket_set_option (socket, IPPROTO_IPV6, IPV6_TCLASS, <TC value>, &error); ``` Creates a new traffic class message with given DSCP and ECN values. a new traffic class message the DSCP value of the message the ECN value of the message Gets the differentiated services code point stored in @message. A DSCP value as described in [RFC 2474](https://www.rfc-editor.org/rfc/rfc2474.html#section-3). a traffic class message Gets the Explicit Congestion Notification code point stored in @message. An ECN value as described in [RFC 3168](https://www.rfc-editor.org/rfc/rfc3168#section-5). a traffic class message `GIcon` is a very minimal interface for icons. It provides functions for checking the equality of two icons, hashing of icons and serializing an icon to and from strings. `GIcon` does not provide the actual pixmap for the icon as this is out of GIO's scope, however implementations of `GIcon` may contain the name of an icon (see [class@Gio.ThemedIcon]), or the path to an icon (see [iface@Gio.LoadableIcon]). To obtain a hash of a `GIcon`, see [method@Gio.Icon.hash]. To check if two `GIcon`s are equal, see [method@Gio.Icon.equal]. For serializing a `GIcon`, use [method@Gio.Icon.serialize] and [func@Gio.Icon.deserialize]. If you want to consume `GIcon` (for example, in a toolkit) you must be prepared to handle at least the three following cases: [iface@Gio.LoadableIcon], [class@Gio.ThemedIcon] and [class@Gio.EmblemedIcon]. It may also make sense to have fast-paths for other cases (like handling [`GdkPixbuf`](https://docs.gtk.org/gdk-pixbuf/class.Pixbuf.html) directly, for example) but all compliant `GIcon` implementations outside of GIO must implement [iface@Gio.LoadableIcon]. If your application or library provides one or more `GIcon` implementations you need to ensure that your new implementation also implements [iface@Gio.LoadableIcon]. Additionally, you must provide an implementation of [method@Gio.Icon.serialize] that gives a result that is understood by [func@Gio.Icon.deserialize], yielding one of the built-in icon types. Deserializes a #GIcon previously serialized using g_icon_serialize(). a #GIcon, or %NULL when deserialization fails. a #GVariant created with g_icon_serialize() Generate a #GIcon instance from @str. This function can fail if @str is not valid - see g_icon_to_string() for discussion. If your application or library provides one or more #GIcon implementations you need to ensure that each #GType is registered with the type system prior to calling g_icon_new_for_string(). An object implementing the #GIcon interface or %NULL if @error is set. A string obtained via g_icon_to_string(). Checks if two icons are equal. %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. pointer to the first #GIcon. pointer to the second #GIcon. Gets a hash for an icon. a #guint containing a hash for the @icon, suitable for use in a #GHashTable or similar data structure. #gconstpointer to an icon object. Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved back by calling g_icon_deserialize() on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the #GVariant between processes on the same machine, (as opposed to over the network), and within the same file system namespace. a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. a #GIcon Serializes the @icon into string tokens. This is can be invoked when g_icon_new_for_string() is called. %TRUE if serialization took place, %FALSE otherwise The #GIcon The array to fill with tokens version of serialized tokens Checks if two icons are equal. %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. pointer to the first #GIcon. pointer to the second #GIcon. Gets a hash for an icon. a #guint containing a hash for the @icon, suitable for use in a #GHashTable or similar data structure. #gconstpointer to an icon object. Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved back by calling g_icon_deserialize() on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the #GVariant between processes on the same machine, (as opposed to over the network), and within the same file system namespace. a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. a #GIcon Generates a textual representation of @icon that can be used for serialization such as when passing @icon to a different process or saving it to persistent storage. Use g_icon_new_for_string() to get @icon back from the returned string. The encoding of the returned string is proprietary to #GIcon except in the following two cases - If @icon is a #GFileIcon, the returned string is a native path (such as `/path/to/my icon.png`) without escaping if the #GFile for @icon is a native file. If the file is not native, the returned string is the result of g_file_get_uri() (such as `sftp://path/to/my%20icon.png`). - If @icon is a #GThemedIcon with exactly one name and no fallbacks, the encoding is simply the name (such as `network-server`). An allocated NUL-terminated UTF8 string or %NULL if @icon can't be serialized. Use g_free() to free. a #GIcon. GIconIface is used to implement GIcon types for various different systems. See #GThemedIcon and #GLoadableIcon for examples of how to implement this interface. The parent interface. A hash for a given #GIcon. a #guint containing a hash for the @icon, suitable for use in a #GHashTable or similar data structure. #gconstpointer to an icon object. Checks if two #GIcons are equal. %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. pointer to the first #GIcon. pointer to the second #GIcon. Serializes a #GIcon into tokens. The tokens must not contain any whitespace. Don't implement if the #GIcon can't be serialized (Since 2.20). %TRUE if serialization took place, %FALSE otherwise The #GIcon The array to fill with tokens version of serialized tokens Constructs a #GIcon from tokens. Set the #GError if the tokens are malformed. Don't implement if the #GIcon can't be serialized (Since 2.20). Serializes a #GIcon into a #GVariant. Since: 2.38 a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. a #GIcon `GInetAddress` represents an IPv4 or IPv6 internet address. Use [method@Gio.Resolver.lookup_by_name] or [method@Gio.Resolver.lookup_by_name_async] to look up the `GInetAddress` for a hostname. Use [method@Gio.Resolver.lookup_by_address] or [method@Gio.Resolver.lookup_by_address_async] to look up the hostname for a `GInetAddress`. To actually connect to a remote host, you will need a [class@Gio.InetSocketAddress] (which includes a `GInetAddress` as well as a port number). Creates a #GInetAddress for the "any" address (unassigned/"don't care") for @family. a new #GInetAddress corresponding to the "any" address for @family. Free the returned object with g_object_unref(). the address family Creates a new #GInetAddress from the given @family and @bytes. @bytes should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for %G_SOCKET_FAMILY_IPV6. a new #GInetAddress corresponding to @family and @bytes. Free the returned object with g_object_unref(). raw address data the address family of @bytes Creates a new [class@Gio.InetAddress] from the given @family, @bytes and @scope_id. @bytes must be 4 bytes for [enum@Gio.SocketFamily.IPV4] and 16 bytes for [enum@Gio.SocketFamily.IPV6]. a new internet address corresponding to @family, @bytes and @scope_id raw address data the address family of @bytes the scope-id of the address Parses @string as an IP address and creates a new #GInetAddress. If @address is an IPv6 address, it can also contain a scope ID (separated from the address by a `%`). Note that currently this behavior is platform specific. This may change in a future release. a new #GInetAddress corresponding to @string, or %NULL if @string could not be parsed. Free the returned object with g_object_unref(). a string representation of an IP address Creates a #GInetAddress for the loopback address for @family. a new #GInetAddress corresponding to the loopback address for @family. Free the returned object with g_object_unref(). the address family Gets the raw binary address data from @address. a pointer to an internal array of the bytes in @address, which should not be modified, stored, or freed. The size of this array can be gotten with g_inet_address_get_native_size(). a #GInetAddress Converts @address to string form. a representation of @address as a string, which should be freed after use. a #GInetAddress Checks if two #GInetAddress instances are equal, e.g. the same address. %TRUE if @address and @other_address are equal, %FALSE otherwise. A #GInetAddress. Another #GInetAddress. Gets @address's family @address's family a #GInetAddress Gets the value of [property@Gio.InetAddress:flowinfo]. The flowinfo for the address, `0` if unset or not IPv6 address. a #GInetAddress Tests whether @address is the "any" address for its family. %TRUE if @address is the "any" address for its family. a #GInetAddress Tests whether @address is a link-local address (that is, if it identifies a host on a local network that is not connected to the Internet). %TRUE if @address is a link-local address. a #GInetAddress Tests whether @address is the loopback address for its family. %TRUE if @address is the loopback address for its family. a #GInetAddress Tests whether @address is a global multicast address. %TRUE if @address is a global multicast address. a #GInetAddress Tests whether @address is a link-local multicast address. %TRUE if @address is a link-local multicast address. a #GInetAddress Tests whether @address is a node-local multicast address. %TRUE if @address is a node-local multicast address. a #GInetAddress Tests whether @address is an organization-local multicast address. %TRUE if @address is an organization-local multicast address. a #GInetAddress Tests whether @address is a site-local multicast address. %TRUE if @address is a site-local multicast address. a #GInetAddress Tests whether @address is a multicast address. %TRUE if @address is a multicast address. a #GInetAddress Tests whether @address is a site-local address such as 10.0.0.1 (that is, the address identifies a host on a local network that can not be reached directly from the Internet, but which may have outgoing Internet connectivity via a NAT or firewall). %TRUE if @address is a site-local address. a #GInetAddress Gets the size of the native raw binary address for @address. This is the size of the data that you get from g_inet_address_to_bytes(). the number of bytes used for the native version of @address. a #GInetAddress Gets the value of [property@Gio.InetAddress:scope-id]. The scope-id for the address, `0` if unset or not IPv6 address. a #GInetAddress Gets the raw binary address data from @address. a pointer to an internal array of the bytes in @address, which should not be modified, stored, or freed. The size of this array can be gotten with g_inet_address_get_native_size(). a #GInetAddress Converts @address to string form. a representation of @address as a string, which should be freed after use. a #GInetAddress The raw address data. The address family (IPv4 or IPv6). The flowinfo for an IPv6 address. See [method@Gio.InetAddress.get_flowinfo]. Whether this is the "any" address for its family. See g_inet_address_get_is_any(). Whether this is a link-local address. See g_inet_address_get_is_link_local(). Whether this is the loopback address for its family. See g_inet_address_get_is_loopback(). Whether this is a global multicast address. See g_inet_address_get_is_mc_global(). Whether this is a link-local multicast address. See g_inet_address_get_is_mc_link_local(). Whether this is a node-local multicast address. See g_inet_address_get_is_mc_node_local(). Whether this is an organization-local multicast address. See g_inet_address_get_is_mc_org_local(). Whether this is a site-local multicast address. See g_inet_address_get_is_mc_site_local(). Whether this is a multicast address. See g_inet_address_get_is_multicast(). Whether this is a site-local address. See g_inet_address_get_is_loopback(). The scope-id for an IPv6 address. See [method@Gio.InetAddress.get_scope_id]. a representation of @address as a string, which should be freed after use. a #GInetAddress a pointer to an internal array of the bytes in @address, which should not be modified, stored, or freed. The size of this array can be gotten with g_inet_address_get_native_size(). a #GInetAddress `GInetAddressMask` represents a range of IPv4 or IPv6 addresses described by a base address and a length indicating how many bits of the base address are relevant for matching purposes. These are often given in string form. For example, `10.0.0.0/8`, or `fe80::/10`. Creates a new #GInetAddressMask representing all addresses whose first @length bits match @addr. a new #GInetAddressMask, or %NULL on error a #GInetAddress number of bits of @addr to use Parses @mask_string as an IP address and (optional) length, and creates a new #GInetAddressMask. The length, if present, is delimited by a "/". If it is not present, then the length is assumed to be the full length of the address. a new #GInetAddressMask corresponding to @string, or %NULL on error. an IP address or address/length string Tests if @mask and @mask2 are the same mask. whether @mask and @mask2 are the same mask a #GInetAddressMask another #GInetAddressMask Gets @mask's base address @mask's base address a #GInetAddressMask Gets the #GSocketFamily of @mask's address the #GSocketFamily of @mask's address a #GInetAddressMask Gets @mask's length @mask's length a #GInetAddressMask Tests if @address falls within the range described by @mask. whether @address falls within the range described by @mask. a #GInetAddressMask a #GInetAddress Converts @mask back to its corresponding string form. a string corresponding to @mask. a #GInetAddressMask The base address. The address family (IPv4 or IPv6). The prefix length, in bytes. An IPv4 or IPv6 socket address. That is, the combination of a [class@Gio.InetAddress] and a port number. In UNIX terms, `GInetSocketAddress` corresponds to a [`struct sockaddr_in` or `struct sockaddr_in6`](man:sockaddr(3type)). Creates a new #GInetSocketAddress for @address and @port. a new #GInetSocketAddress a #GInetAddress a port number Creates a new #GInetSocketAddress for @address and @port. If @address is an IPv6 address, it can also contain a scope ID (separated from the address by a `%`). Note that currently this behavior is platform specific. This may change in a future release. a new #GInetSocketAddress, or %NULL if @address cannot be parsed. the string form of an IP address a port number Gets @address's #GInetAddress. the #GInetAddress for @address, which must be g_object_ref()'d if it will be stored a #GInetSocketAddress Gets the `sin6_flowinfo` field from @address, which must be an IPv6 address. If not overridden this value will be inherited from [property@Gio.InetSocketAddress:address]. the flowinfo field a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress Gets @address's port. the port for @address a #GInetSocketAddress Gets the `sin6_scope_id` field from @address, which must be an IPv6 address. If not overridden this value will be inherited from [property@Gio.InetSocketAddress:address]. the scope id field a %G_SOCKET_FAMILY_IPV6 #GInetAddress The address. The `sin6_flowinfo` field, for IPv6 addresses. If unset this property is inherited from [property@Gio.InetSocketAddress:address]. The port. The `sin6_scope_id` field, for IPv6 addresses. If unset this property is inherited from [property@Gio.InetSocketAddress:address]. `GInitable` is implemented by objects that can fail during initialization. If an object implements this interface then it must be initialized as the first thing after construction, either via [method@Gio.Initable.init] or [method@Gio.AsyncInitable.init_async] (the latter is only available if it also implements [iface@Gio.AsyncInitable]). If the object is not initialized, or initialization returns with an error, then all operations on the object except `g_object_ref()` and `g_object_unref()` are considered to be invalid, and have undefined behaviour. They will often fail with [func@GLib.critical] or [func@GLib.warning], but this must not be relied on. Users of objects implementing this are not intended to use the interface method directly, instead it will be used automatically in various ways. For C applications you generally just call [func@Gio.Initable.new] directly, or indirectly via a `foo_thing_new()` wrapper. This will call [method@Gio.Initable.init] under the cover, returning `NULL` and setting a `GError` on failure (at which point the instance is unreferenced). For bindings in languages where the native constructor supports exceptions the binding could check for objects implementing `GInitable` during normal construction and automatically initialize them, throwing an exception on failure. Helper function for constructing #GInitable object. This is similar to g_object_new() but also initializes the object and returns %NULL, setting an error on failure. a newly allocated #GObject, or %NULL on error a #GType supporting #GInitable. optional #GCancellable object, %NULL to ignore. a #GError location to store the error occurring, or %NULL to ignore. the name of the first property, or %NULL if no properties the value if the first property, followed by and other property value pairs, and ended by %NULL. Helper function for constructing #GInitable object. This is similar to g_object_new_valist() but also initializes the object and returns %NULL, setting an error on failure. a newly allocated #GObject, or %NULL on error a #GType supporting #GInitable. the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. The var args list generated from @first_property_name. optional #GCancellable object, %NULL to ignore. Helper function for constructing #GInitable object. This is similar to g_object_newv() but also initializes the object and returns %NULL, setting an error on failure. Use g_object_new_with_properties() and g_initable_init() instead. See #GParameter for more information. a newly allocated #GObject, or %NULL on error a #GType supporting #GInitable. the number of parameters in @parameters the parameters to use to construct the object optional #GCancellable object, %NULL to ignore. Initializes the object implementing the interface. This method is intended for language bindings. If writing in C, g_initable_new() should typically be used instead. The object must be initialized before any real use after initial construction, either with this function or g_async_initable_init_async(). Implementations may also support cancellation. If @cancellable is not %NULL, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and the object doesn't support cancellable initialization the error %G_IO_ERROR_NOT_SUPPORTED will be returned. If the object is not initialized, or initialization returns with an error, then all operations on the object except g_object_ref() and g_object_unref() are considered to be invalid, and have undefined behaviour. See the [description][iface@Gio.Initable#description] for more details. Callers should not assume that a class which implements #GInitable can be initialized multiple times, unless the class explicitly documents itself as supporting this. Generally, a class’ implementation of init() can assume (and assert) that it will only be called once. Previously, this documentation recommended all #GInitable implementations should be idempotent; that recommendation was relaxed in GLib 2.54. If a class explicitly supports being initialized multiple times, it is recommended that the method is idempotent: multiple calls with the same arguments should return the same results. Only the first call initializes the object; further calls return the result of the first call. One reason why a class might need to support idempotent initialization is if it is designed to be used via the singleton pattern, with a #GObjectClass.constructor that sometimes returns an existing instance. In this pattern, a caller would expect to be able to call g_initable_init() on the result of g_object_new(), regardless of whether it is in fact a new instance. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GInitable. optional #GCancellable object, %NULL to ignore. Initializes the object implementing the interface. This method is intended for language bindings. If writing in C, g_initable_new() should typically be used instead. The object must be initialized before any real use after initial construction, either with this function or g_async_initable_init_async(). Implementations may also support cancellation. If @cancellable is not %NULL, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and the object doesn't support cancellable initialization the error %G_IO_ERROR_NOT_SUPPORTED will be returned. If the object is not initialized, or initialization returns with an error, then all operations on the object except g_object_ref() and g_object_unref() are considered to be invalid, and have undefined behaviour. See the [description][iface@Gio.Initable#description] for more details. Callers should not assume that a class which implements #GInitable can be initialized multiple times, unless the class explicitly documents itself as supporting this. Generally, a class’ implementation of init() can assume (and assert) that it will only be called once. Previously, this documentation recommended all #GInitable implementations should be idempotent; that recommendation was relaxed in GLib 2.54. If a class explicitly supports being initialized multiple times, it is recommended that the method is idempotent: multiple calls with the same arguments should return the same results. Only the first call initializes the object; further calls return the result of the first call. One reason why a class might need to support idempotent initialization is if it is designed to be used via the singleton pattern, with a #GObjectClass.constructor that sometimes returns an existing instance. In this pattern, a caller would expect to be able to call g_initable_init() on the result of g_object_new(), regardless of whether it is in fact a new instance. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GInitable. optional #GCancellable object, %NULL to ignore. Provides an interface for initializing object such that initialization may fail. The parent interface. Initializes the object. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GInitable. optional #GCancellable object, %NULL to ignore. Structure used for scatter/gather data input when receiving multiple messages or packets in one go. You generally pass in an array of empty #GInputVectors and the operation will use all the buffers as if they were one buffer, and will set @bytes_received to the total number of bytes received across all #GInputVectors. This structure closely mirrors `struct mmsghdr` and `struct msghdr` from the POSIX sockets API (see `man 2 recvmmsg`). If @address is non-%NULL then it is set to the source address the message was received from, and the caller must free it afterwards. If @control_messages is non-%NULL then it is set to an array of control messages received with the message (if any), and the caller must free it afterwards. @num_control_messages is set to the number of elements in this array, which may be zero. Flags relevant to this message will be returned in @flags. For example, `MSG_EOR` or `MSG_TRUNC`. return location for a #GSocketAddress, or %NULL pointer to an array of input vectors the number of input vectors pointed to by @vectors will be set to the number of bytes that have been received collection of #GSocketMsgFlags for the received message, outputted by the call return location for a caller-allocated array of #GSocketControlMessages, or %NULL return location for the number of elements in @control_messages `GInputStream` is a base class for implementing streaming input. It has functions to read from a stream ([method@Gio.InputStream.read]), to close a stream ([method@Gio.InputStream.close]) and to skip some content ([method@Gio.InputStream.skip]). To copy the content of an input stream to an output stream without manually handling the reads and writes, use [method@Gio.OutputStream.splice]. See the documentation for [class@Gio.IOStream] for details of thread safety of streaming APIs. All of these functions have async variants too. Requests an asynchronous closes of the stream, releasing resources related to it. When the operation is finished @callback will be called. You can then call g_input_stream_close_finish() to get the result of the operation. For behaviour details see g_input_stream_close(). The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. A #GInputStream. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional cancellable object a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes closing a stream asynchronously, started from g_input_stream_close_async(). %TRUE if the stream was closed successfully. a #GInputStream. a #GAsyncResult. Request an asynchronous read of @count bytes from the stream into the buffer starting at @buffer. When the operation is finished @callback will be called. You can then call g_input_stream_read_finish() to get the result of the operation. During an async request no other sync and async calls are allowed on @stream, and will result in %G_IO_ERROR_PENDING errors. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, the number of bytes read into the buffer will be passed to the callback. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file, but generally we try to read as many bytes as requested. Zero is returned on end of file (or if @count is zero), but never otherwise. Any outstanding i/o request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. A #GInputStream. a buffer to read data into (which should be at least count bytes long). the number of bytes that will be read from the stream the [I/O priority](iface.AsyncResult.html#io-priority) of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous stream read operation. number of bytes read in, or -1 on error, or 0 on end of file. a #GInputStream. a #GAsyncResult. Tries to skip @count bytes from the stream. Will block during the operation. This is identical to g_input_stream_read(), from a behaviour standpoint, but the bytes that are skipped are not returned to the user. Some streams have an implementation that is more efficient than reading the data. This function is optional for inherited classes, as the default implementation emulates it using read. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. Number of bytes skipped, or -1 on error a #GInputStream. the number of bytes that will be skipped from the stream optional #GCancellable object, %NULL to ignore. Request an asynchronous skip of @count bytes from the stream. When the operation is finished @callback will be called. You can then call g_input_stream_skip_finish() to get the result of the operation. During an async request no other sync and async calls are allowed, and will result in %G_IO_ERROR_PENDING errors. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, the number of bytes skipped will be passed to the callback. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file, but generally we try to skip as many bytes as requested. Zero is returned on end of file (or if @count is zero), but never otherwise. Any outstanding i/o request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one, you must override all. A #GInputStream. the number of bytes that will be skipped from the stream the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes a stream skip operation. the size of the bytes skipped, or `-1` on error. a #GInputStream. a #GAsyncResult. Clears the pending flag on @stream. input stream Closes the stream, releasing resources related to it. Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. Closing a stream multiple times will not return an error. Streams will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. Some streams might keep the backing store of the stream (e.g. a file descriptor) open after the stream is closed. See the documentation for the individual stream for details. On failure the first error that happened will be reported, but the close operation will finish as much as possible. A stream that failed to close will still return %G_IO_ERROR_CLOSED for all operations. Still, it is important to check and report the error to the user. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave the stream closed, but some streams can use a faster close that doesn't block to e.g. check errors. %TRUE on success, %FALSE on failure A #GInputStream. optional #GCancellable object, %NULL to ignore. Requests an asynchronous closes of the stream, releasing resources related to it. When the operation is finished @callback will be called. You can then call g_input_stream_close_finish() to get the result of the operation. For behaviour details see g_input_stream_close(). The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. A #GInputStream. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional cancellable object a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes closing a stream asynchronously, started from g_input_stream_close_async(). %TRUE if the stream was closed successfully. a #GInputStream. a #GAsyncResult. Checks if an input stream has pending actions. %TRUE if @stream has pending actions. input stream. Checks if an input stream is closed. %TRUE if the stream is closed. input stream. Tries to read @count bytes from the stream into the buffer starting at @buffer. Will block during this read. If count is zero returns zero and does nothing. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, the number of bytes read into the buffer is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file. Zero is returned on end of file (or if @count is zero), but never otherwise. The returned @buffer is not a nul-terminated string, it can contain nul bytes at any position, and this function doesn't nul-terminate the @buffer. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error -1 is returned and @error is set accordingly. Number of bytes read, or -1 on error, or 0 on end of file. a #GInputStream. a buffer to read data into (which should be at least count bytes long). the number of bytes that will be read from the stream optional #GCancellable object, %NULL to ignore. Tries to read @count bytes from the stream into the buffer starting at @buffer. Will block during this read. This function is similar to g_input_stream_read(), except it tries to read as many bytes as requested, only stopping on an error or end of stream. On a successful read of @count bytes, or if we reached the end of the stream, %TRUE is returned, and @bytes_read is set to the number of bytes read into @buffer. If there is an error during the operation %FALSE is returned and @error is set to indicate the error status. As a special exception to the normal conventions for functions that use #GError, if this function returns %FALSE (and sets @error) then @bytes_read will be set to the number of bytes that were successfully read before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_input_stream_read(). %TRUE on success, %FALSE if there was an error a #GInputStream. a buffer to read data into (which should be at least count bytes long). the number of bytes that will be read from the stream location to store the number of bytes that was read from the stream optional #GCancellable object, %NULL to ignore. Request an asynchronous read of @count bytes from the stream into the buffer starting at @buffer. This is the asynchronous equivalent of [method@InputStream.read_all]. Call [method@InputStream.read_all_finish] to collect the result. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. A #GInputStream a buffer to read data into (which should be at least count bytes long) the number of bytes that will be read from the stream the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous stream read operation started with [method@InputStream.read_all_async]. As a special exception to the normal conventions for functions that use #GError, if this function returns %FALSE (and sets @error) then @bytes_read will be set to the number of bytes that were successfully read before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_input_stream_read_async(). %TRUE on success, %FALSE if there was an error a #GInputStream a #GAsyncResult location to store the number of bytes that was read from the stream Request an asynchronous read of @count bytes from the stream into the buffer starting at @buffer. When the operation is finished @callback will be called. You can then call g_input_stream_read_finish() to get the result of the operation. During an async request no other sync and async calls are allowed on @stream, and will result in %G_IO_ERROR_PENDING errors. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, the number of bytes read into the buffer will be passed to the callback. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file, but generally we try to read as many bytes as requested. Zero is returned on end of file (or if @count is zero), but never otherwise. Any outstanding i/o request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. A #GInputStream. a buffer to read data into (which should be at least count bytes long). the number of bytes that will be read from the stream the [I/O priority](iface.AsyncResult.html#io-priority) of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Like g_input_stream_read(), this tries to read @count bytes from the stream in a blocking fashion. However, rather than reading into a user-supplied buffer, this will create a new #GBytes containing the data that was read. This may be easier to use from language bindings. If count is zero, returns a zero-length #GBytes and does nothing. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, a new #GBytes is returned. It is not an error if the size of this object is not the same as the requested size, as it can happen e.g. near the end of a file. A zero-length #GBytes is returned on end of file (or if @count is zero), but never otherwise. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error %NULL is returned and @error is set accordingly. a new #GBytes, or %NULL on error a #GInputStream. maximum number of bytes that will be read from the stream. Common values include 4096 and 8192. optional #GCancellable object, %NULL to ignore. Request an asynchronous read of @count bytes from the stream into a new #GBytes. When the operation is finished @callback will be called. You can then call g_input_stream_read_bytes_finish() to get the result of the operation. During an async request no other sync and async calls are allowed on @stream, and will result in %G_IO_ERROR_PENDING errors. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, the new #GBytes will be passed to the callback. It is not an error if this is smaller than the requested size, as it can happen e.g. near the end of a file, but generally we try to read as many bytes as requested. Zero is returned on end of file (or if @count is zero), but never otherwise. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. A #GInputStream. the number of bytes that will be read from the stream the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous stream read-into-#GBytes operation. the newly-allocated #GBytes, or %NULL on error a #GInputStream. a #GAsyncResult. Finishes an asynchronous stream read operation. number of bytes read in, or -1 on error, or 0 on end of file. a #GInputStream. a #GAsyncResult. Sets @stream to have actions pending. If the pending flag is already set or @stream is closed, it will return %FALSE and set @error. %TRUE if pending was previously unset and is now set. input stream Tries to skip @count bytes from the stream. Will block during the operation. This is identical to g_input_stream_read(), from a behaviour standpoint, but the bytes that are skipped are not returned to the user. Some streams have an implementation that is more efficient than reading the data. This function is optional for inherited classes, as the default implementation emulates it using read. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. Number of bytes skipped, or -1 on error a #GInputStream. the number of bytes that will be skipped from the stream optional #GCancellable object, %NULL to ignore. Request an asynchronous skip of @count bytes from the stream. When the operation is finished @callback will be called. You can then call g_input_stream_skip_finish() to get the result of the operation. During an async request no other sync and async calls are allowed, and will result in %G_IO_ERROR_PENDING errors. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, the number of bytes skipped will be passed to the callback. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file, but generally we try to skip as many bytes as requested. Zero is returned on end of file (or if @count is zero), but never otherwise. Any outstanding i/o request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one, you must override all. A #GInputStream. the number of bytes that will be skipped from the stream the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes a stream skip operation. the size of the bytes skipped, or `-1` on error. a #GInputStream. a #GAsyncResult. Number of bytes skipped, or -1 on error a #GInputStream. the number of bytes that will be skipped from the stream optional #GCancellable object, %NULL to ignore. A #GInputStream. a buffer to read data into (which should be at least count bytes long). the number of bytes that will be read from the stream the [I/O priority](iface.AsyncResult.html#io-priority) of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function number of bytes read in, or -1 on error, or 0 on end of file. a #GInputStream. a #GAsyncResult. A #GInputStream. the number of bytes that will be skipped from the stream the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function the size of the bytes skipped, or `-1` on error. a #GInputStream. a #GAsyncResult. A #GInputStream. the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional cancellable object a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function %TRUE if the stream was closed successfully. a #GInputStream. a #GAsyncResult. Structure used for scatter/gather data input. You generally pass in an array of #GInputVectors and the operation will store the read data starting in the first buffer, switching to the next as needed. Pointer to a buffer where data will be written. the available size in @buffer. `GListModel` is an interface that represents a mutable list of [class@GObject.Object]. Its main intention is as a model for various widgets in user interfaces, such as list views, but it can also be used as a convenient method of returning lists of data, with support for updates. Each object in the list may also report changes in itself via some mechanism (normally the [signal@GObject.Object::notify] signal). Taken together with the [signal@Gio.ListModel::items-changed] signal, this provides for a list that can change its membership, and in which the members can change their individual properties. A good example would be the list of visible wireless network access points, where each access point can report dynamic properties such as signal strength. It is important to note that the `GListModel` itself does not report changes to the individual items. It only reports changes to the list membership. If you want to observe changes to the objects themselves then you need to connect signals to the objects that you are interested in. All items in a `GListModel` are of (or derived from) the same type. [method@Gio.ListModel.get_item_type] returns that type. The type may be an interface, in which case all objects in the list must implement it. The semantics are close to that of an array: [method@Gio.ListModel.get_n_items] returns the number of items in the list and [method@Gio.ListModel.get_item] returns an item at a (0-based) position. In order to allow implementations to calculate the list length lazily, you can also iterate over items: starting from 0, repeatedly call [method@Gio.ListModel.get_item] until it returns `NULL`. An implementation may create objects lazily, but must take care to return the same object for a given position until all references to it are gone. On the other side, a consumer is expected only to hold references on objects that are currently ‘user visible’, in order to facilitate the maximum level of laziness in the implementation of the list and to reduce the required number of signal connections at a given time. This interface is intended only to be used from a single thread. The thread in which it is appropriate to use it depends on the particular implementation, but typically it will be from the thread that owns the thread-default main context (see [method@GLib.MainContext.push_thread_default]) in effect at the time that the model was created. Over time, it has established itself as good practice for list model implementations to provide properties `item-type` and `n-items` to ease working with them. While it is not required, it is recommended that implementations provide these two properties. They should return the values of [method@Gio.ListModel.get_item_type] and [method@Gio.ListModel.get_n_items] respectively and be defined as such: ```c properties[PROP_ITEM_TYPE] = g_param_spec_gtype ("item-type", NULL, NULL, G_TYPE_OBJECT, G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); properties[PROP_N_ITEMS] = g_param_spec_uint ("n-items", NULL, NULL, 0, G_MAXUINT, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); ``` Get the item at @position. If @position is greater than the number of items in @list, %NULL is returned. %NULL is never returned for an index that is smaller than the length of the list. See g_list_model_get_n_items(). The same #GObject instance may not appear more than once in a #GListModel. the object at @position. a #GListModel the position of the item to fetch Gets the type of the items in @list. All items returned from g_list_model_get_item() are of the type returned by this function, or a subtype, or if the type is an interface, they are an implementation of that interface. The item type of a #GListModel can not change during the life of the model. the #GType of the items contained in @list. a #GListModel Gets the number of items in @list. Depending on the model implementation, calling this function may be less efficient than iterating the list with increasing values for @position until g_list_model_get_item() returns %NULL. the number of items in @list. a #GListModel Get the item at @position. If @position is greater than the number of items in @list, %NULL is returned. %NULL is never returned for an index that is smaller than the length of the list. See also: g_list_model_get_n_items() the item at @position. a #GListModel the position of the item to fetch Gets the type of the items in @list. All items returned from g_list_model_get_item() are of the type returned by this function, or a subtype, or if the type is an interface, they are an implementation of that interface. The item type of a #GListModel can not change during the life of the model. the #GType of the items contained in @list. a #GListModel Gets the number of items in @list. Depending on the model implementation, calling this function may be less efficient than iterating the list with increasing values for @position until g_list_model_get_item() returns %NULL. the number of items in @list. a #GListModel Get the item at @position. If @position is greater than the number of items in @list, %NULL is returned. %NULL is never returned for an index that is smaller than the length of the list. This function is meant to be used by language bindings in place of g_list_model_get_item(). See also: g_list_model_get_n_items() the object at @position. a #GListModel the position of the item to fetch Emits the #GListModel::items-changed signal on @list. This function should only be called by classes implementing #GListModel. It has to be called after the internal representation of @list has been updated, because handlers connected to this signal might query the new state of the list. Implementations must only make changes to the model (as visible to its consumer) in places that will not cause problems for that consumer. For models that are driven directly by a write API (such as #GListStore), changes can be reported in response to uses of that API. For models that represent remote data, changes should only be made from a fresh mainloop dispatch. It is particularly not permitted to make changes in response to a call to the #GListModel consumer API. Stated another way: in general, it is assumed that code making a series of accesses to the model via the API, without returning to the mainloop, and without calling other code, will continue to view the same contents of the model. a #GListModel the position at which @list changed the number of items removed the number of items added This signal is emitted whenever items were added to or removed from @list. At @position, @removed items were removed and @added items were added in their place. Note: If `removed != added`, the positions of all later items in the model change. the position at which @list changed the number of items removed the number of items added The virtual function table for #GListModel. parent #GTypeInterface the virtual function pointer for g_list_model_get_item_type() the #GType of the items contained in @list. a #GListModel the virtual function pointer for g_list_model_get_n_items() the number of items in @list. a #GListModel the virtual function pointer for g_list_model_get_item() the object at @position. a #GListModel the position of the item to fetch `GListStore` is a simple implementation of [iface@Gio.ListModel] that stores all items in memory. It provides insertions, deletions, and lookups in logarithmic time with a fast path for the common case of iterating the list linearly. Creates a new #GListStore with items of type @item_type. @item_type must be a subclass of #GObject. a new #GListStore the #GType of items in the list Appends @item to @store. @item must be of type #GListStore:item-type. This function takes a ref on @item. Use g_list_store_splice() to append multiple items at the same time efficiently. a #GListStore the new item Looks up the given @item in the list store by looping over the items until the first occurrence of @item. If @item was not found, then @position will not be set, and this method will return %FALSE. If you need to compare the two items with a custom comparison function, use g_list_store_find_with_equal_func() with a custom #GEqualFunc instead. Whether @store contains @item. If it was found, @position will be set to the position where @item occurred for the first time. a #GListStore an item the first position of @item, if it was found. Looks up the given @item in the list store by looping over the items and comparing them with @equal_func until the first occurrence of @item which matches. If @item was not found, then @position will not be set, and this method will return %FALSE. @item is always passed as second parameter to @equal_func. Since GLib 2.76 it is possible to pass `NULL` for @item. Whether @store contains @item. If it was found, @position will be set to the position where @item occurred for the first time. a #GListStore an item A custom equality check function the first position of @item, if it was found. Like g_list_store_find_with_equal_func() but with an additional @user_data that is passed to @equal_func. @item is always passed as second parameter to @equal_func. Since GLib 2.76 it is possible to pass `NULL` for @item. Whether @store contains @item. If it was found, @position will be set to the position where @item occurred for the first time. a #GListStore an item A custom equality check function user data for @equal_func the first position of @item, if it was found. Inserts @item into @store at @position. @item must be of type #GListStore:item-type or derived from it. @position must be smaller than the length of the list, or equal to it to append. This function takes a ref on @item. Use g_list_store_splice() to insert multiple items at the same time efficiently. a #GListStore the position at which to insert the new item the new item Inserts @item into @store at a position to be determined by the @compare_func. The list must already be sorted before calling this function or the result is undefined. Usually you would approach this by only ever inserting items by way of this function. This function takes a ref on @item. the position at which @item was inserted a #GListStore the new item pairwise comparison function for sorting user data for @compare_func Removes the item from @store that is at @position. @position must be smaller than the current length of the list. Use g_list_store_splice() to remove multiple items at the same time efficiently. a #GListStore the position of the item that is to be removed Removes all items from @store. a #GListStore Sort the items in @store according to @compare_func. a #GListStore pairwise comparison function for sorting user data for @compare_func Changes @store by removing @n_removals items and adding @n_additions items to it. @additions must contain @n_additions items of type #GListStore:item-type. %NULL is not permitted. This function is more efficient than g_list_store_insert() and g_list_store_remove(), because it only emits #GListModel::items-changed once for the change. This function takes a ref on each item in @additions. The parameters @position and @n_removals must be correct (ie: @position + @n_removals must be less than or equal to the length of the list at the time this function is called). a #GListStore the position at which to make the change the number of items to remove the items to add the number of items to add The type of items contained in this list store. Items must be subclasses of #GObject. The number of items contained in this list store. `GLoadableIcon` extends the [iface@Gio.Icon] interface and adds the ability to load icons from streams. Loads a loadable icon. For the asynchronous version of this function, see g_loadable_icon_load_async(). a #GInputStream to read the icon from. a #GLoadableIcon. an integer. a location to store the type of the loaded icon, %NULL to ignore. optional #GCancellable object, %NULL to ignore. Loads an icon asynchronously. To finish this function, see g_loadable_icon_load_finish(). For the synchronous, blocking version of this function, see g_loadable_icon_load(). a #GLoadableIcon. an integer. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous icon load started in g_loadable_icon_load_async(). a #GInputStream to read the icon from. a #GLoadableIcon. a #GAsyncResult. a location to store the type of the loaded icon, %NULL to ignore. Loads a loadable icon. For the asynchronous version of this function, see g_loadable_icon_load_async(). a #GInputStream to read the icon from. a #GLoadableIcon. an integer. a location to store the type of the loaded icon, %NULL to ignore. optional #GCancellable object, %NULL to ignore. Loads an icon asynchronously. To finish this function, see g_loadable_icon_load_finish(). For the synchronous, blocking version of this function, see g_loadable_icon_load(). a #GLoadableIcon. an integer. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous icon load started in g_loadable_icon_load_async(). a #GInputStream to read the icon from. a #GLoadableIcon. a #GAsyncResult. a location to store the type of the loaded icon, %NULL to ignore. Interface for icons that can be loaded as a stream. The parent interface. Loads an icon. a #GInputStream to read the icon from. a #GLoadableIcon. an integer. a location to store the type of the loaded icon, %NULL to ignore. optional #GCancellable object, %NULL to ignore. Loads an icon asynchronously. a #GLoadableIcon. an integer. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous icon load. a #GInputStream to read the icon from. a #GLoadableIcon. a #GAsyncResult. a location to store the type of the loaded icon, %NULL to ignore. Extension point for memory usage monitoring functionality. See [Extending GIO](overview.html#extending-gio). The menu item attribute which holds the action name of the item. Action names are namespaced with an identifier for the action group in which the action resides. For example, "win." for window-specific actions and "app." for application-wide actions. See also g_menu_model_get_item_attribute() and g_menu_item_set_attribute(). The menu item attribute that holds the namespace for all action names in menus that are linked from this item. The menu item attribute which holds the icon of the item. The icon is stored in the format returned by g_icon_serialize(). This attribute is intended only to represent 'noun' icons such as favicons for a webpage, or application icons. It should not be used for 'verbs' (ie: stock icons). The menu item attribute which holds the label of the item. The menu item attribute which holds the target with which the item's action will be activated. See also g_menu_item_set_action_and_target() The maximum number of entries in a menu section supported by g_dbus_connection_export_menu_model(). The exact value of the limit may change in future GLib versions. The name of the link that associates a menu item with a section. The linked menu will usually be shown in place of the menu item, using the item's label as a header. See also g_menu_item_set_link(). The name of the link that associates a menu item with a submenu. See also g_menu_item_set_link(). `GMemoryInputStream` is a class for using arbitrary memory chunks as input for GIO streaming input operations. As of GLib 2.34, `GMemoryInputStream` implements [iface@Gio.PollableInputStream]. Creates a new empty #GMemoryInputStream. a new #GInputStream Creates a new #GMemoryInputStream with data from the given @bytes. new #GInputStream read from @bytes a #GBytes Creates a new #GMemoryInputStream with data in memory of a given size. new #GInputStream read from @data of @len bytes. input data length of the data, may be -1 if @data is a nul-terminated string function that is called to free @data, or %NULL Appends @bytes to data that can be read from the input stream. a #GMemoryInputStream input data Appends @data to data that can be read from the input stream a #GMemoryInputStream input data length of the data, may be -1 if @data is a nul-terminated string function that is called to free @data, or %NULL `GMemoryMonitor` will monitor system memory and suggest to the application when to free memory so as to leave more room for other applications. It is implemented on Linux using the [Low Memory Monitor](https://gitlab.freedesktop.org/hadess/low-memory-monitor/) ([API documentation](https://hadess.pages.freedesktop.org/low-memory-monitor/)). There is also an implementation for use inside Flatpak sandboxes. Possible actions to take when the signal is received are: - Free caches - Save files that haven’t been looked at in a while to disk, ready to be reopened when needed - Run a garbage collection cycle - Try and compress fragmented allocations - Exit on idle if the process has no reason to stay around - Call [`malloc_trim(3)`](man:malloc_trim(3)) to return cached heap pages to the kernel (if supported by your libc) Note that some actions may not always improve system performance, and so should be profiled for your application. `malloc_trim()`, for example, may make future heap allocations slower (due to releasing cached heap pages back to the kernel). See [type@Gio.MemoryMonitorWarningLevel] for details on the various warning levels. ```c static void warning_cb (GMemoryMonitor *m, GMemoryMonitorWarningLevel level) { g_debug ("Warning level: %d", level); if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW) drop_caches (); } static GMemoryMonitor * monitor_low_memory (void) { GMemoryMonitor *m; m = g_memory_monitor_dup_default (); g_signal_connect (G_OBJECT (m), "low-memory-warning", G_CALLBACK (warning_cb), NULL); return m; } ``` Don’t forget to disconnect the [signal@Gio.MemoryMonitor::low-memory-warning] signal, and unref the `GMemoryMonitor` itself when exiting. Gets a reference to the default #GMemoryMonitor for the system. a new reference to the default #GMemoryMonitor the virtual function pointer for the #GMemoryMonitor::low-memory-warning signal. Emitted when the system is running low on free memory. The signal handler should then take the appropriate action depending on the warning level. See the #GMemoryMonitorWarningLevel documentation for details. Since the [iface@Gio.MemoryMonitor] is a singleton, this signal will be emitted in the [func@GLib.MainContext.default][global-default main context]. the #GMemoryMonitorWarningLevel warning level The virtual function table for #GMemoryMonitor. The parent interface. the virtual function pointer for the #GMemoryMonitor::low-memory-warning signal. Memory availability warning levels. Note that because new values might be added, it is recommended that applications check #GMemoryMonitorWarningLevel as ranges, for example: |[<!-- language="C" --> if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW) drop_caches (); ]| Memory on the device is low, processes should free up unneeded resources (for example, in-memory caches) so they can be used elsewhere. Same as @G_MEMORY_MONITOR_WARNING_LEVEL_LOW but the device has even less free memory, so processes should try harder to free up unneeded resources. If your process does not need to stay running, it is a good time for it to quit. The system will soon start terminating processes to reclaim memory, including background processes. `GMemoryOutputStream` is a class for using arbitrary memory chunks as output for GIO streaming output operations. As of GLib 2.34, `GMemoryOutputStream` trivially implements [iface@Gio.PollableOutputStream]: it always polls as ready. Creates a new #GMemoryOutputStream. In most cases this is not the function you want. See g_memory_output_stream_new_resizable() instead. If @data is non-%NULL, the stream will use that for its internal storage. If @realloc_fn is non-%NULL, it will be used for resizing the internal storage when necessary and the stream will be considered resizable. In that case, the stream will start out being (conceptually) empty. @size is used only as a hint for how big @data is. Specifically, seeking to the end of a newly-created stream will seek to zero, not @size. Seeking past the end of the stream and then writing will introduce a zero-filled gap. If @realloc_fn is %NULL then the stream is fixed-sized. Seeking to the end will seek to @size exactly. Writing past the end will give an 'out of space' error. Attempting to seek past the end will fail. Unlike the resizable case, seeking to an offset within the stream and writing will preserve the bytes passed in as @data before that point and will return them as part of g_memory_output_stream_steal_data(). If you intend to seek you should probably therefore ensure that @data is properly initialised. It is probably only meaningful to provide @data and @size in the case that you want a fixed-sized stream. Put another way: if @realloc_fn is non-%NULL then it makes most sense to give @data as %NULL and @size as 0 (allowing #GMemoryOutputStream to do the initial allocation for itself). |[<!-- language="C" --> // a stream that can grow stream = g_memory_output_stream_new (NULL, 0, realloc, free); // another stream that can grow stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free); // a fixed-size stream data = malloc (200); stream3 = g_memory_output_stream_new (data, 200, NULL, free); ]| A newly created #GMemoryOutputStream object. pointer to a chunk of memory to use, or %NULL the size of @data a function with realloc() semantics (like g_realloc()) to be called when @data needs to be grown, or %NULL a function to be called on @data when the stream is finalized, or %NULL Creates a new #GMemoryOutputStream, using g_realloc() and g_free() for memory allocation. Gets any loaded data from the @ostream. Note that the returned pointer may become invalid on the next write or truncate operation on the stream. pointer to the stream's data, or %NULL if the data has been stolen a #GMemoryOutputStream Returns the number of bytes from the start up to including the last byte written in the stream that has not been truncated away. the number of bytes written to the stream a #GMemoryOutputStream Gets the size of the currently allocated data area (available from g_memory_output_stream_get_data()). You probably don't want to use this function on resizable streams. See g_memory_output_stream_get_data_size() instead. For resizable streams the size returned by this function is an implementation detail and may be change at any time in response to operations on the stream. If the stream is fixed-sized (ie: no realloc was passed to g_memory_output_stream_new()) then this is the maximum size of the stream and further writes will return %G_IO_ERROR_NO_SPACE. In any case, if you want the number of bytes currently written to the stream, use g_memory_output_stream_get_data_size(). the number of bytes allocated for the data buffer a #GMemoryOutputStream Returns data from the @ostream as a #GBytes. @ostream must be closed before calling this function. the stream's data a #GMemoryOutputStream Gets any loaded data from the @ostream. Ownership of the data is transferred to the caller; when no longer needed it must be freed using the free function set in @ostream's #GMemoryOutputStream:destroy-function property. @ostream must be closed before calling this function. the stream's data, or %NULL if it has previously been stolen a #GMemoryOutputStream Pointer to buffer where data will be written. Size of data written to the buffer. Function called with the buffer as argument when the stream is destroyed. Function with realloc semantics called to enlarge the buffer. Current size of the data buffer. `GMenu` is a simple implementation of [class@Gio.MenuModel]. You populate a `GMenu` by adding [class@Gio.MenuItem] instances to it. There are some convenience functions to allow you to directly add items (avoiding [class@Gio.MenuItem]) for the common cases. To add a regular item, use [method@Gio.Menu.insert]. To add a section, use [method@Gio.Menu.insert_section]. To add a submenu, use [method@Gio.Menu.insert_submenu]. Creates a new #GMenu. The new menu has no items. a new #GMenu Convenience function for appending a normal menu item to the end of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more flexible alternative. a #GMenu the section label, or %NULL the detailed action string, or %NULL Appends @item to the end of @menu. See g_menu_insert_item() for more information. a #GMenu a #GMenuItem to append Convenience function for appending a section menu item to the end of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a more flexible alternative. a #GMenu the section label, or %NULL a #GMenuModel with the items of the section Convenience function for appending a submenu menu item to the end of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more flexible alternative. a #GMenu the section label, or %NULL a #GMenuModel with the items of the submenu Marks @menu as frozen. After the menu is frozen, it is an error to attempt to make any changes to it. In effect this means that the #GMenu API must no longer be used. This function causes g_menu_model_is_mutable() to begin returning %FALSE, which has some positive performance implications. a #GMenu Convenience function for inserting a normal menu item into @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more flexible alternative. a #GMenu the position at which to insert the item the section label, or %NULL the detailed action string, or %NULL Inserts @item into @menu. The "insertion" is actually done by copying all of the attribute and link values of @item and using them to form a new item within @menu. As such, @item itself is not really inserted, but rather, a menu item that is exactly the same as the one presently described by @item. This means that @item is essentially useless after the insertion occurs. Any changes you make to it are ignored unless it is inserted again (at which point its updated values will be copied). You should probably just free @item once you're done. There are many convenience functions to take care of common cases. See g_menu_insert(), g_menu_insert_section() and g_menu_insert_submenu() as well as "prepend" and "append" variants of each of these functions. a #GMenu the position at which to insert the item the #GMenuItem to insert Convenience function for inserting a section menu item into @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a more flexible alternative. a #GMenu the position at which to insert the item the section label, or %NULL a #GMenuModel with the items of the section Convenience function for inserting a submenu menu item into @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more flexible alternative. a #GMenu the position at which to insert the item the section label, or %NULL a #GMenuModel with the items of the submenu Convenience function for prepending a normal menu item to the start of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more flexible alternative. a #GMenu the section label, or %NULL the detailed action string, or %NULL Prepends @item to the start of @menu. See g_menu_insert_item() for more information. a #GMenu a #GMenuItem to prepend Convenience function for prepending a section menu item to the start of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a more flexible alternative. a #GMenu the section label, or %NULL a #GMenuModel with the items of the section Convenience function for prepending a submenu menu item to the start of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more flexible alternative. a #GMenu the section label, or %NULL a #GMenuModel with the items of the submenu Removes an item from the menu. @position gives the index of the item to remove. It is an error if position is not in range the range from 0 to one less than the number of items in the menu. It is not possible to remove items by identity since items are added to the menu simply by copying their links and attributes (ie: identity of the item itself is not preserved). a #GMenu the position of the item to remove Removes all items in the menu. a #GMenu #GMenuAttributeIter is an opaque structure type. You must access it using the functions below. This function combines g_menu_attribute_iter_next() with g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value(). First the iterator is advanced to the next (possibly first) attribute. If that fails, then %FALSE is returned and there are no other effects. If successful, @name and @value are set to the name and value of the attribute that has just been advanced to. At this point, g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will return the same values again. The value returned in @name remains valid for as long as the iterator remains at the current position. The value returned in @value must be unreffed using g_variant_unref() when it is no longer in use. %TRUE on success, or %FALSE if there is no additional attribute a #GMenuAttributeIter the type of the attribute the attribute value Gets the name of the attribute at the current iterator position, as a string. The iterator is not advanced. the name of the attribute a #GMenuAttributeIter This function combines g_menu_attribute_iter_next() with g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value(). First the iterator is advanced to the next (possibly first) attribute. If that fails, then %FALSE is returned and there are no other effects. If successful, @name and @value are set to the name and value of the attribute that has just been advanced to. At this point, g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will return the same values again. The value returned in @name remains valid for as long as the iterator remains at the current position. The value returned in @value must be unreffed using g_variant_unref() when it is no longer in use. %TRUE on success, or %FALSE if there is no additional attribute a #GMenuAttributeIter the type of the attribute the attribute value Gets the value of the attribute at the current iterator position. The iterator is not advanced. the value of the current attribute a #GMenuAttributeIter Attempts to advance the iterator to the next (possibly first) attribute. %TRUE is returned on success, or %FALSE if there are no more attributes. You must call this function when you first acquire the iterator to advance it to the first attribute (and determine if the first attribute exists at all). %TRUE on success, or %FALSE when there are no more attributes a #GMenuAttributeIter %TRUE on success, or %FALSE if there is no additional attribute a #GMenuAttributeIter the type of the attribute the attribute value #GMenuItem is an opaque structure type. You must access it using the functions below. Creates a new #GMenuItem. If @label is non-%NULL it is used to set the "label" attribute of the new item. If @detailed_action is non-%NULL it is used to set the "action" and possibly the "target" attribute of the new item. See g_menu_item_set_detailed_action() for more information. a new #GMenuItem the section label, or %NULL the detailed action string, or %NULL Creates a #GMenuItem as an exact copy of an existing menu item in a #GMenuModel. @item_index must be valid (ie: be sure to call g_menu_model_get_n_items() first). a new #GMenuItem. a #GMenuModel the index of an item in @model Creates a new #GMenuItem representing a section. This is a convenience API around g_menu_item_new() and g_menu_item_set_section(). The effect of having one menu appear as a section of another is exactly as it sounds: the items from @section become a direct part of the menu that @menu_item is added to. Visual separation is typically displayed between two non-empty sections. If @label is non-%NULL then it will be incorporated into this visual indication. This allows for labeled subsections of a menu. As a simple example, consider a typical "Edit" menu from a simple program. It probably contains an "Undo" and "Redo" item, followed by a separator, followed by "Cut", "Copy" and "Paste". This would be accomplished by creating three #GMenu instances. The first would be populated with the "Undo" and "Redo" items, and the second with the "Cut", "Copy" and "Paste" items. The first and second menus would then be added as submenus of the third. In XML format, this would look something like the following: |[ <menu id='edit-menu'> <section> <item label='Undo'/> <item label='Redo'/> </section> <section> <item label='Cut'/> <item label='Copy'/> <item label='Paste'/> </section> </menu> ]| The following example is exactly equivalent. It is more illustrative of the exact relationship between the menus and items (keeping in mind that the 'link' element defines a new menu that is linked to the containing one). The style of the second example is more verbose and difficult to read (and therefore not recommended except for the purpose of understanding what is really going on). |[ <menu id='edit-menu'> <item> <link name='section'> <item label='Undo'/> <item label='Redo'/> </link> </item> <item> <link name='section'> <item label='Cut'/> <item label='Copy'/> <item label='Paste'/> </link> </item> </menu> ]| a new #GMenuItem the section label, or %NULL a #GMenuModel with the items of the section Creates a new #GMenuItem representing a submenu. This is a convenience API around g_menu_item_new() and g_menu_item_set_submenu(). a new #GMenuItem the section label, or %NULL a #GMenuModel with the items of the submenu Queries the named @attribute on @menu_item. If the attribute exists and matches the #GVariantType corresponding to @format_string then @format_string is used to deconstruct the value into the positional parameters and %TRUE is returned. If the attribute does not exist, or it does exist but has the wrong type, then the positional parameters are ignored and %FALSE is returned. %TRUE if the named attribute was found with the expected type a #GMenuItem the attribute name to query a #GVariant format string positional parameters, as per @format_string Queries the named @attribute on @menu_item. If @expected_type is specified and the attribute does not have this type, %NULL is returned. %NULL is also returned if the attribute simply does not exist. the attribute value, or %NULL a #GMenuItem the attribute name to query the expected type of the attribute Queries the named @link on @menu_item. the link, or %NULL a #GMenuItem the link name to query Sets or unsets the "action" and "target" attributes of @menu_item. If @action is %NULL then both the "action" and "target" attributes are unset (and @format_string is ignored along with the positional parameters). If @action is non-%NULL then the "action" attribute is set. @format_string is then inspected. If it is non-%NULL then the proper position parameters are collected to create a #GVariant instance to use as the target value. If it is %NULL then the positional parameters are ignored and the "target" attribute is unset. See also g_menu_item_set_action_and_target_value() for an equivalent call that directly accepts a #GVariant. See g_menu_item_set_detailed_action() for a more convenient version that works with string-typed targets. See also g_menu_item_set_action_and_target_value() for a description of the semantics of the action and target attributes. a #GMenuItem the name of the action for this item a GVariant format string positional parameters, as per @format_string Sets or unsets the "action" and "target" attributes of @menu_item. If @action is %NULL then both the "action" and "target" attributes are unset (and @target_value is ignored). If @action is non-%NULL then the "action" attribute is set. The "target" attribute is then set to the value of @target_value if it is non-%NULL or unset otherwise. Normal menu items (ie: not submenu, section or other custom item types) are expected to have the "action" attribute set to identify the action that they are associated with. The state type of the action help to determine the disposition of the menu item. See #GAction and #GActionGroup for an overview of actions. In general, clicking on the menu item will result in activation of the named action with the "target" attribute given as the parameter to the action invocation. If the "target" attribute is not set then the action is invoked with no parameter. If the action has no state then the menu item is usually drawn as a plain menu item (ie: with no additional decoration). If the action has a boolean state then the menu item is usually drawn as a toggle menu item (ie: with a checkmark or equivalent indication). The item should be marked as 'toggled' or 'checked' when the boolean state is %TRUE. If the action has a string state then the menu item is usually drawn as a radio menu item (ie: with a radio bullet or equivalent indication). The item should be marked as 'selected' when the string state is equal to the value of the @target property. See g_menu_item_set_action_and_target() or g_menu_item_set_detailed_action() for two equivalent calls that are probably more convenient for most uses. a #GMenuItem the name of the action for this item a #GVariant to use as the action target Sets or unsets an attribute on @menu_item. The attribute to set or unset is specified by @attribute. This can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL, %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom attribute name. Attribute names are restricted to lowercase characters, numbers and '-'. Furthermore, the names must begin with a lowercase character, must not end with a '-', and must not contain consecutive dashes. If @format_string is non-%NULL then the proper position parameters are collected to create a #GVariant instance to use as the attribute value. If it is %NULL then the positional parameterrs are ignored and the named attribute is unset. See also g_menu_item_set_attribute_value() for an equivalent call that directly accepts a #GVariant. a #GMenuItem the attribute to set a #GVariant format string, or %NULL positional parameters, as per @format_string Sets or unsets an attribute on @menu_item. The attribute to set or unset is specified by @attribute. This can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL, %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom attribute name. Attribute names are restricted to lowercase characters, numbers and '-'. Furthermore, the names must begin with a lowercase character, must not end with a '-', and must not contain consecutive dashes. must consist only of lowercase ASCII characters, digits and '-'. If @value is non-%NULL then it is used as the new value for the attribute. If @value is %NULL then the attribute is unset. If the @value #GVariant is floating, it is consumed. See also g_menu_item_set_attribute() for a more convenient way to do the same. a #GMenuItem the attribute to set a #GVariant to use as the value, or %NULL Sets the "action" and possibly the "target" attribute of @menu_item. The format of @detailed_action is the same format parsed by g_action_parse_detailed_name(). See g_menu_item_set_action_and_target() or g_menu_item_set_action_and_target_value() for more flexible (but slightly less convenient) alternatives. See also g_menu_item_set_action_and_target_value() for a description of the semantics of the action and target attributes. a #GMenuItem the "detailed" action string Sets (or unsets) the icon on @menu_item. This call is the same as calling g_icon_serialize() and using the result as the value to g_menu_item_set_attribute_value() for %G_MENU_ATTRIBUTE_ICON. This API is only intended for use with "noun" menu items; things like bookmarks or applications in an "Open With" menu. Don't use it on menu items corresponding to verbs (eg: stock icons for 'Save' or 'Quit'). If @icon is %NULL then the icon is unset. a #GMenuItem a #GIcon, or %NULL Sets or unsets the "label" attribute of @menu_item. If @label is non-%NULL it is used as the label for the menu item. If it is %NULL then the label attribute is unset. a #GMenuItem the label to set, or %NULL to unset Creates a link from @menu_item to @model if non-%NULL, or unsets it. Links are used to establish a relationship between a particular menu item and another menu. For example, %G_MENU_LINK_SUBMENU is used to associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION is used to create a section. Other types of link can be used, but there is no guarantee that clients will be able to make sense of them. Link types are restricted to lowercase characters, numbers and '-'. Furthermore, the names must begin with a lowercase character, must not end with a '-', and must not contain consecutive dashes. a #GMenuItem type of link to establish or unset the #GMenuModel to link to (or %NULL to unset) Sets or unsets the "section" link of @menu_item to @section. The effect of having one menu appear as a section of another is exactly as it sounds: the items from @section become a direct part of the menu that @menu_item is added to. See g_menu_item_new_section() for more information about what it means for a menu item to be a section. a #GMenuItem a #GMenuModel, or %NULL Sets or unsets the "submenu" link of @menu_item to @submenu. If @submenu is non-%NULL, it is linked to. If it is %NULL then the link is unset. The effect of having one menu appear as a submenu of another is exactly as it sounds. a #GMenuItem a #GMenuModel, or %NULL #GMenuLinkIter is an opaque structure type. You must access it using the functions below. This function combines g_menu_link_iter_next() with g_menu_link_iter_get_name() and g_menu_link_iter_get_value(). First the iterator is advanced to the next (possibly first) link. If that fails, then %FALSE is returned and there are no other effects. If successful, @out_link and @value are set to the name and #GMenuModel of the link that has just been advanced to. At this point, g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the same values again. The value returned in @out_link remains valid for as long as the iterator remains at the current position. The value returned in @value must be unreffed using g_object_unref() when it is no longer in use. %TRUE on success, or %FALSE if there is no additional link a #GMenuLinkIter the name of the link the linked #GMenuModel Gets the name of the link at the current iterator position. The iterator is not advanced. the type of the link a #GMenuLinkIter This function combines g_menu_link_iter_next() with g_menu_link_iter_get_name() and g_menu_link_iter_get_value(). First the iterator is advanced to the next (possibly first) link. If that fails, then %FALSE is returned and there are no other effects. If successful, @out_link and @value are set to the name and #GMenuModel of the link that has just been advanced to. At this point, g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the same values again. The value returned in @out_link remains valid for as long as the iterator remains at the current position. The value returned in @value must be unreffed using g_object_unref() when it is no longer in use. %TRUE on success, or %FALSE if there is no additional link a #GMenuLinkIter the name of the link the linked #GMenuModel Gets the linked #GMenuModel at the current iterator position. The iterator is not advanced. the #GMenuModel that is linked to a #GMenuLinkIter Attempts to advance the iterator to the next (possibly first) link. %TRUE is returned on success, or %FALSE if there are no more links. You must call this function when you first acquire the iterator to advance it to the first link (and determine if the first link exists at all). %TRUE on success, or %FALSE when there are no more links a #GMenuLinkIter %TRUE on success, or %FALSE if there is no additional link a #GMenuLinkIter the name of the link the linked #GMenuModel `GMenuModel` represents the contents of a menu — an ordered list of menu items. The items are associated with actions, which can be activated through them. Items can be grouped in sections, and may have submenus associated with them. Both items and sections usually have some representation data, such as labels or icons. The type of the associated action (ie whether it is stateful, and what kind of state it has) can influence the representation of the item. The conceptual model of menus in `GMenuModel` is hierarchical: sections and submenus are again represented by `GMenuModel`s. Menus themselves do not define their own roles. Rather, the role of a particular `GMenuModel` is defined by the item that references it (or, in the case of the ‘root’ menu, is defined by the context in which it is used). As an example, consider the visible portions of this menu: ## An example menu ![](menu-example.png) While this kind of deeply nested menu is no longer considered good UI practice, it serves as a good example of the concepts in `GMenuModel`. There are 8 ‘menus’ visible in the screenshot: one menubar, two submenus and 5 sections: - the toplevel menubar (containing 4 items) - the View submenu (containing 3 sections) - the first section of the View submenu (containing 2 items) - the second section of the View submenu (containing 1 item) - the final section of the View submenu (containing 1 item) - the Highlight Mode submenu (containing 2 sections) - the Sources section (containing 2 items) - the Markup section (containing 2 items) The [example](#a-menu-example) illustrates the conceptual connection between these 8 menus. Each large block in the figure represents a menu and the smaller blocks within the large block represent items in that menu. Some items contain references to other menus. ## A menu example <picture> <source srcset="menu-model-dark.svg" media="(prefers-color-scheme: dark)"> <img src="menu-model-light.svg" alt="menu model"> </picture> Notice that the separators visible in the [example](#an-example-menu) appear nowhere in the [menu model](#a-menu-example). This is because separators are not explicitly represented in the menu model. Instead, a separator is inserted between any two non-empty sections of a menu. Section items can have labels just like any other item. In that case, a display system may show a section header instead of a separator. The motivation for this abstract model of application controls is that modern user interfaces tend to make these controls available outside the application. Examples include global menus, jumplists, dash boards, etc. To support such uses, it is necessary to ‘export’ information about actions and their representation in menus, which is exactly what the action group exporter and the menu model exporter do for [iface@Gio.ActionGroup] and [class@Gio.MenuModel]. The client-side counterparts to make use of the exported information are [class@Gio.DBusActionGroup] and [class@Gio.DBusMenuModel]. The API of `GMenuModel` is very generic, with iterators for the attributes and links of an item, see [method@Gio.MenuModel.iterate_item_attributes] and [method@Gio.MenuModel.iterate_item_links]. The ‘standard’ attributes and link types have predefined names: `G_MENU_ATTRIBUTE_LABEL`, `G_MENU_ATTRIBUTE_ACTION`, `G_MENU_ATTRIBUTE_TARGET`, `G_MENU_LINK_SECTION` and `G_MENU_LINK_SUBMENU`. Items in a `GMenuModel` represent active controls if they refer to an action that can get activated when the user interacts with the menu item. The reference to the action is encoded by the string ID in the `G_MENU_ATTRIBUTE_ACTION` attribute. An action ID uniquely identifies an action in an action group. Which action group(s) provide actions depends on the context in which the menu model is used. E.g. when the model is exported as the application menu of a [`GtkApplication`](https://docs.gtk.org/gtk4/class.Application.html), actions can be application-wide or window-specific (and thus come from two different action groups). By convention, the application-wide actions have names that start with `app.`, while the names of window-specific actions start with `win.`. While a wide variety of stateful actions is possible, the following is the minimum that is expected to be supported by all users of exported menu information: - an action with no parameter type and no state - an action with no parameter type and boolean state - an action with string parameter type and string state ## Stateless A stateless action typically corresponds to an ordinary menu item. Selecting such a menu item will activate the action (with no parameter). ## Boolean State An action with a boolean state will most typically be used with a ‘toggle’ or ‘switch’ menu item. The state can be set directly, but activating the action (with no parameter) results in the state being toggled. Selecting a toggle menu item will activate the action. The menu item should be rendered as ‘checked’ when the state is true. ## String Parameter and State Actions with string parameters and state will most typically be used to represent an enumerated choice over the items available for a group of radio menu items. Activating the action with a string parameter is equivalent to setting that parameter as the state. Radio menu items, in addition to being associated with the action, will have a target value. Selecting that menu item will result in activation of the action with the target value as the parameter. The menu item should be rendered as ‘selected’ when the state of the action is equal to the target value of the menu item. Queries the item at position @item_index in @model for the attribute specified by @attribute. If @expected_type is non-%NULL then it specifies the expected type of the attribute. If it is %NULL then any type will be accepted. If the attribute exists and matches @expected_type (or if the expected type is unspecified) then the value is returned. If the attribute does not exist, or does not match the expected type then %NULL is returned. the value of the attribute a #GMenuModel the index of the item the attribute to query the expected type of the attribute, or %NULL Gets all the attributes associated with the item in the menu model. the #GMenuModel to query The #GMenuItem to query Attributes on the item Queries the item at position @item_index in @model for the link specified by @link. If the link exists, the linked #GMenuModel is returned. If the link does not exist, %NULL is returned. the linked #GMenuModel, or %NULL a #GMenuModel the index of the item the link to query Gets all the links associated with the item in the menu model. the #GMenuModel to query The #GMenuItem to query Links from the item Query the number of items in @model. the number of items a #GMenuModel Queries if @model is mutable. An immutable #GMenuModel will never emit the #GMenuModel::items-changed signal. Consumers of the model may make optimisations accordingly. %TRUE if the model is mutable (ie: "items-changed" may be emitted). a #GMenuModel Creates a #GMenuAttributeIter to iterate over the attributes of the item at position @item_index in @model. You must free the iterator with g_object_unref() when you are done. a new #GMenuAttributeIter a #GMenuModel the index of the item Creates a #GMenuLinkIter to iterate over the links of the item at position @item_index in @model. You must free the iterator with g_object_unref() when you are done. a new #GMenuLinkIter a #GMenuModel the index of the item Queries item at position @item_index in @model for the attribute specified by @attribute. If the attribute exists and matches the #GVariantType corresponding to @format_string then @format_string is used to deconstruct the value into the positional parameters and %TRUE is returned. If the attribute does not exist, or it does exist but has the wrong type, then the positional parameters are ignored and %FALSE is returned. This function is a mix of g_menu_model_get_item_attribute_value() and g_variant_get(), followed by a g_variant_unref(). As such, @format_string must make a complete copy of the data (since the #GVariant may go away after the call to g_variant_unref()). In particular, no '&' characters are allowed in @format_string. %TRUE if the named attribute was found with the expected type a #GMenuModel the index of the item the attribute to query a #GVariant format string positional parameters, as per @format_string Queries the item at position @item_index in @model for the attribute specified by @attribute. If @expected_type is non-%NULL then it specifies the expected type of the attribute. If it is %NULL then any type will be accepted. If the attribute exists and matches @expected_type (or if the expected type is unspecified) then the value is returned. If the attribute does not exist, or does not match the expected type then %NULL is returned. the value of the attribute a #GMenuModel the index of the item the attribute to query the expected type of the attribute, or %NULL Queries the item at position @item_index in @model for the link specified by @link. If the link exists, the linked #GMenuModel is returned. If the link does not exist, %NULL is returned. the linked #GMenuModel, or %NULL a #GMenuModel the index of the item the link to query Query the number of items in @model. the number of items a #GMenuModel Queries if @model is mutable. An immutable #GMenuModel will never emit the #GMenuModel::items-changed signal. Consumers of the model may make optimisations accordingly. %TRUE if the model is mutable (ie: "items-changed" may be emitted). a #GMenuModel Requests emission of the #GMenuModel::items-changed signal on @model. This function should never be called except by #GMenuModel subclasses. Any other calls to this function will very likely lead to a violation of the interface of the model. The implementation should update its internal representation of the menu before emitting the signal. The implementation should further expect to receive queries about the new state of the menu (and particularly added menu items) while signal handlers are running. The implementation must dispatch this call directly from a mainloop entry and not in response to calls -- particularly those from the #GMenuModel API. Said another way: the menu must not change while user code is running without returning to the mainloop. a #GMenuModel the position of the change the number of items removed the number of items added Creates a #GMenuAttributeIter to iterate over the attributes of the item at position @item_index in @model. You must free the iterator with g_object_unref() when you are done. a new #GMenuAttributeIter a #GMenuModel the index of the item Creates a #GMenuLinkIter to iterate over the links of the item at position @item_index in @model. You must free the iterator with g_object_unref() when you are done. a new #GMenuLinkIter a #GMenuModel the index of the item Emitted when a change has occurred to the menu. The only changes that can occur to a menu is that items are removed or added. Items may not change (except by being removed and added back in the same location). This signal is capable of describing both of those changes (at the same time). The signal means that starting at the index @position, @removed items were removed and @added items were added in their place. If @removed is zero then only items were added. If @added is zero then only items were removed. As an example, if the menu contains items a, b, c, d (in that order) and the signal (2, 1, 3) occurs then the new composition of the menu will be a, b, _, _, _, d (with each _ representing some new item). Signal handlers may query the model (particularly the added items) and expect to see the results of the modification that is being reported. The signal is emitted after the modification. the position of the change the number of items removed the number of items added %TRUE if the model is mutable (ie: "items-changed" may be emitted). a #GMenuModel the number of items a #GMenuModel the #GMenuModel to query The #GMenuItem to query Attributes on the item a new #GMenuAttributeIter a #GMenuModel the index of the item the value of the attribute a #GMenuModel the index of the item the attribute to query the expected type of the attribute, or %NULL the #GMenuModel to query The #GMenuItem to query Links from the item a new #GMenuLinkIter a #GMenuModel the index of the item the linked #GMenuModel, or %NULL a #GMenuModel the index of the item the link to query The `GMount` interface represents a user-visible mount, such as a mounted file system. `GMount` is a ‘mounted’ filesystem that you can access. Mounted is in quotes because it’s not the same as a UNIX mount, it might be a GVFS mount, but you can still access the files on it if you use GIO. A `GMount` might be associated with a [iface@Gio.Volume] (such as a USB flash drive) which hosts it. Unmounting a `GMount` instance is an asynchronous operation. For more information about asynchronous operations, see [iface@Gio.AsyncResult] and [class@Gio.Task]. To unmount a `GMount` instance, first call [method@Gio.Mount.unmount_with_operation] with (at least) the `GMount` instance and a [type@Gio.AsyncReadyCallback]. The callback will be fired when the operation has resolved (either with success or failure), and a [iface@Gio.AsyncResult] structure will be passed to the callback. That callback should then call [method@Gio.Mount.unmount_with_operation_finish] with the `GMount` and the [iface@Gio.AsyncResult] data to see if the operation was completed successfully. If an `error` is present when [method@Gio.Mount.unmount_with_operation_finish] is called, then it will be filled with any error information. Note, when [porting from GnomeVFS](migrating-gnome-vfs.html), `GMount` is the moral equivalent of `GnomeVFSVolume`. Checks if @mount can be ejected. %TRUE if the @mount can be ejected. a #GMount. Checks if @mount can be unmounted. %TRUE if the @mount can be unmounted. a #GMount. Changed signal that is emitted when the mount's state has changed. Ejects a mount. This is an asynchronous operation, and is finished by calling g_mount_eject_finish() with the @mount and #GAsyncResult data returned in the @callback. Use g_mount_eject_with_operation() instead. a #GMount. flags affecting the unmount if required for eject optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes ejecting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Use g_mount_eject_with_operation_finish() instead. %TRUE if the mount was successfully ejected. %FALSE otherwise. a #GMount. a #GAsyncResult. Ejects a mount. This is an asynchronous operation, and is finished by calling g_mount_eject_with_operation_finish() with the @mount and #GAsyncResult data returned in the @callback. a #GMount. flags affecting the unmount if required for eject a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes ejecting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. %TRUE if the mount was successfully ejected. %FALSE otherwise. a #GMount. a #GAsyncResult. Gets the default location of @mount. The default location of the given @mount is a path that reflects the main entry point for the user (e.g. the home directory, or the root of the volume). a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets the drive for the @mount. This is a convenience method for getting the #GVolume and then using that object to get the #GDrive. a #GDrive or %NULL if @mount is not associated with a volume or a drive. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets the icon for @mount. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets the name of @mount. the name for the given @mount. The returned string should be freed with g_free() when no longer needed. a #GMount. Gets the root directory on @mount. a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets the sort key for @mount, if any. Sorting key for @mount or %NULL if no such key is available. A #GMount. Gets the symbolic icon for @mount. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets the UUID for the @mount. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available. the UUID for @mount or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. a #GMount. Gets the volume for the @mount. a #GVolume or %NULL if @mount is not associated with a volume. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Tries to guess the type of content stored on @mount. Returns one or more textual identifiers of well-known content types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory cards. See the [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on x-content types. This is an asynchronous operation (see g_mount_guess_content_type_sync() for the synchronous version), and is finished by calling g_mount_guess_content_type_finish() with the @mount and #GAsyncResult data returned in the @callback. a #GMount Whether to force a rescan of the content. Otherwise a cached result will be used if available optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback user data passed to @callback Finishes guessing content types of @mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. In particular, you may get an %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content guessing. a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. a #GMount a #GAsyncResult Tries to guess the type of content stored on @mount. Returns one or more textual identifiers of well-known content types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory cards. See the [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on x-content types. This is a synchronous operation and as such may block doing IO; see g_mount_guess_content_type() for the asynchronous version. a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. a #GMount Whether to force a rescan of the content. Otherwise a cached result will be used if available optional #GCancellable object, %NULL to ignore The ::pre-unmount signal that is emitted when the #GMount will soon be emitted. If the recipient is somehow holding the mount open by keeping an open file on it it should close the file. Remounts a mount. This is an asynchronous operation, and is finished by calling g_mount_remount_finish() with the @mount and #GAsyncResults data returned in the @callback. Remounting is useful when some setting affecting the operation of the volume has been changed, as these may need a remount to take affect. While this is semantically equivalent with unmounting and then remounting not all backends might need to actually be unmounted. a #GMount. flags affecting the operation a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes remounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. %TRUE if the mount was successfully remounted. %FALSE otherwise. a #GMount. a #GAsyncResult. Unmounts a mount. This is an asynchronous operation, and is finished by calling g_mount_unmount_finish() with the @mount and #GAsyncResult data returned in the @callback. Use g_mount_unmount_with_operation() instead. a #GMount. flags affecting the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes unmounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Use g_mount_unmount_with_operation_finish() instead. %TRUE if the mount was successfully unmounted. %FALSE otherwise. a #GMount. a #GAsyncResult. Unmounts a mount. This is an asynchronous operation, and is finished by calling g_mount_unmount_with_operation_finish() with the @mount and #GAsyncResult data returned in the @callback. a #GMount. flags affecting the operation a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes unmounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. %TRUE if the mount was successfully unmounted. %FALSE otherwise. a #GMount. a #GAsyncResult. The unmounted signal that is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized. Checks if @mount can be ejected. %TRUE if the @mount can be ejected. a #GMount. Checks if @mount can be unmounted. %TRUE if the @mount can be unmounted. a #GMount. Ejects a mount. This is an asynchronous operation, and is finished by calling g_mount_eject_finish() with the @mount and #GAsyncResult data returned in the @callback. Use g_mount_eject_with_operation() instead. a #GMount. flags affecting the unmount if required for eject optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes ejecting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Use g_mount_eject_with_operation_finish() instead. %TRUE if the mount was successfully ejected. %FALSE otherwise. a #GMount. a #GAsyncResult. Ejects a mount. This is an asynchronous operation, and is finished by calling g_mount_eject_with_operation_finish() with the @mount and #GAsyncResult data returned in the @callback. a #GMount. flags affecting the unmount if required for eject a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes ejecting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. %TRUE if the mount was successfully ejected. %FALSE otherwise. a #GMount. a #GAsyncResult. Gets the default location of @mount. The default location of the given @mount is a path that reflects the main entry point for the user (e.g. the home directory, or the root of the volume). a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets the drive for the @mount. This is a convenience method for getting the #GVolume and then using that object to get the #GDrive. a #GDrive or %NULL if @mount is not associated with a volume or a drive. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets the icon for @mount. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets the name of @mount. the name for the given @mount. The returned string should be freed with g_free() when no longer needed. a #GMount. Gets the root directory on @mount. a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets the sort key for @mount, if any. Sorting key for @mount or %NULL if no such key is available. A #GMount. Gets the symbolic icon for @mount. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets the UUID for the @mount. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available. the UUID for @mount or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. a #GMount. Gets the volume for the @mount. a #GVolume or %NULL if @mount is not associated with a volume. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Tries to guess the type of content stored on @mount. Returns one or more textual identifiers of well-known content types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory cards. See the [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on x-content types. This is an asynchronous operation (see g_mount_guess_content_type_sync() for the synchronous version), and is finished by calling g_mount_guess_content_type_finish() with the @mount and #GAsyncResult data returned in the @callback. a #GMount Whether to force a rescan of the content. Otherwise a cached result will be used if available optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback user data passed to @callback Finishes guessing content types of @mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. In particular, you may get an %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content guessing. a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. a #GMount a #GAsyncResult Tries to guess the type of content stored on @mount. Returns one or more textual identifiers of well-known content types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory cards. See the [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on x-content types. This is a synchronous operation and as such may block doing IO; see g_mount_guess_content_type() for the asynchronous version. a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. a #GMount Whether to force a rescan of the content. Otherwise a cached result will be used if available optional #GCancellable object, %NULL to ignore Determines if @mount is shadowed. Applications or libraries should avoid displaying @mount in the user interface if it is shadowed. A mount is said to be shadowed if there exists one or more user visible objects (currently #GMount objects) with a root that is inside the root of @mount. One application of shadow mounts is when exposing a single file system that is used to address several logical volumes. In this situation, a #GVolumeMonitor implementation would create two #GVolume objects (for example, one for the camera functionality of the device and one for a SD card reader on the device) with activation URIs `gphoto2://[usb:001,002]/store1/` and `gphoto2://[usb:001,002]/store2/`. When the underlying mount (with root `gphoto2://[usb:001,002]/`) is mounted, said #GVolumeMonitor implementation would create two #GMount objects (each with their root matching the corresponding volume activation root) that would shadow the original mount. The proxy monitor in GVfs 2.26 and later, automatically creates and manage shadow mounts (and shadows the underlying mount) if the activation root on a #GVolume is set. %TRUE if @mount is shadowed. A #GMount. Remounts a mount. This is an asynchronous operation, and is finished by calling g_mount_remount_finish() with the @mount and #GAsyncResults data returned in the @callback. Remounting is useful when some setting affecting the operation of the volume has been changed, as these may need a remount to take affect. While this is semantically equivalent with unmounting and then remounting not all backends might need to actually be unmounted. a #GMount. flags affecting the operation a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes remounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. %TRUE if the mount was successfully remounted. %FALSE otherwise. a #GMount. a #GAsyncResult. Increments the shadow count on @mount. Usually used by #GVolumeMonitor implementations when creating a shadow mount for @mount, see g_mount_is_shadowed() for more information. The caller will need to emit the #GMount::changed signal on @mount manually. A #GMount. Unmounts a mount. This is an asynchronous operation, and is finished by calling g_mount_unmount_finish() with the @mount and #GAsyncResult data returned in the @callback. Use g_mount_unmount_with_operation() instead. a #GMount. flags affecting the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes unmounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Use g_mount_unmount_with_operation_finish() instead. %TRUE if the mount was successfully unmounted. %FALSE otherwise. a #GMount. a #GAsyncResult. Unmounts a mount. This is an asynchronous operation, and is finished by calling g_mount_unmount_with_operation_finish() with the @mount and #GAsyncResult data returned in the @callback. a #GMount. flags affecting the operation a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes unmounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. %TRUE if the mount was successfully unmounted. %FALSE otherwise. a #GMount. a #GAsyncResult. Decrements the shadow count on @mount. Usually used by #GVolumeMonitor implementations when destroying a shadow mount for @mount, see g_mount_is_shadowed() for more information. The caller will need to emit the #GMount::changed signal on @mount manually. A #GMount. Emitted when the mount has been changed. This signal may be emitted when the #GMount is about to be unmounted. This signal depends on the backend and is only emitted if GIO was used to unmount. This signal is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized. Interface for implementing operations for mounts. The parent interface. Changed signal that is emitted when the mount's state has changed. The unmounted signal that is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized. Gets a #GFile to the root directory of the #GMount. a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets a string containing the name of the #GMount. the name for the given @mount. The returned string should be freed with g_free() when no longer needed. a #GMount. Gets a #GIcon for the #GMount. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets the UUID for the #GMount. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available. the UUID for @mount or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. a #GMount. Gets a #GVolume the mount is located on. Returns %NULL if the #GMount is not associated with a #GVolume. a #GVolume or %NULL if @mount is not associated with a volume. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets a #GDrive the volume of the mount is located on. Returns %NULL if the #GMount is not associated with a #GDrive or a #GVolume. This is convenience method for getting the #GVolume and using that to get the #GDrive. a #GDrive or %NULL if @mount is not associated with a volume or a drive. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Checks if a #GMount can be unmounted. %TRUE if the @mount can be unmounted. a #GMount. Checks if a #GMount can be ejected. %TRUE if the @mount can be ejected. a #GMount. Starts unmounting a #GMount. a #GMount. flags affecting the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes an unmounting operation. %TRUE if the mount was successfully unmounted. %FALSE otherwise. a #GMount. a #GAsyncResult. Starts ejecting a #GMount. a #GMount. flags affecting the unmount if required for eject optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes an eject operation. %TRUE if the mount was successfully ejected. %FALSE otherwise. a #GMount. a #GAsyncResult. Starts remounting a #GMount. a #GMount. flags affecting the operation a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes a remounting operation. %TRUE if the mount was successfully remounted. %FALSE otherwise. a #GMount. a #GAsyncResult. Starts guessing the type of the content of a #GMount. See g_mount_guess_content_type() for more information on content type guessing. This operation was added in 2.18. a #GMount Whether to force a rescan of the content. Otherwise a cached result will be used if available optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback user data passed to @callback Finishes a content type guessing operation. Added in 2.18. a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. a #GMount a #GAsyncResult Synchronous variant of @guess_content_type. Added in 2.18 a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. a #GMount Whether to force a rescan of the content. Otherwise a cached result will be used if available optional #GCancellable object, %NULL to ignore The ::pre-unmount signal that is emitted when the #GMount will soon be emitted. If the recipient is somehow holding the mount open by keeping an open file on it it should close the file. Starts unmounting a #GMount using a #GMountOperation. Since 2.22. a #GMount. flags affecting the operation a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes an unmounting operation using a #GMountOperation. Since 2.22. %TRUE if the mount was successfully unmounted. %FALSE otherwise. a #GMount. a #GAsyncResult. Starts ejecting a #GMount using a #GMountOperation. Since 2.22. a #GMount. flags affecting the unmount if required for eject a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes an eject operation using a #GMountOperation. Since 2.22. %TRUE if the mount was successfully ejected. %FALSE otherwise. a #GMount. a #GAsyncResult. Gets a #GFile indication a start location that can be use as the entry point for this mount. Since 2.24. a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Gets a key used for sorting #GMount instance or %NULL if no such key exists. Since 2.32. Sorting key for @mount or %NULL if no such key is available. A #GMount. Gets a symbolic #GIcon for the #GMount. Since 2.34. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. a #GMount. Flags used when mounting a mount. No flags set. `GMountOperation` provides a mechanism for interacting with the user. It can be used for authenticating mountable operations, such as loop mounting files, hard drive partitions or server locations. It can also be used to ask the user questions or show a list of applications preventing unmount or eject operations from completing. Note that `GMountOperation` is used for more than just [iface@Gio.Mount] objects – for example it is also used in [method@Gio.Drive.start] and [method@Gio.Drive.stop]. Users should instantiate a subclass of this that implements all the various callbacks to show the required dialogs, such as [`GtkMountOperation`](https://docs.gtk.org/gtk4/class.MountOperation.html). If no user interaction is desired (for example when automounting filesystems at login time), usually `NULL` can be passed, see each method taking a `GMountOperation` for details. Throughout the API, the term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’. [TrueCrypt](https://en.wikipedia.org/wiki/TrueCrypt) is a discontinued system for encrypting file containers, partitions or whole disks, typically used with Windows. [VeraCrypt](https://www.veracrypt.fr/) is a maintained fork of TrueCrypt with various improvements and auditing fixes. Creates a new mount operation. a #GMountOperation. Virtual implementation of #GMountOperation::ask-question. a #GMountOperation string containing a message to display to the user an array of strings for each possible choice Emits the #GMountOperation::reply signal. a #GMountOperation a #GMountOperationResult Virtual implementation of #GMountOperation::show-processes. a #GMountOperation string containing a message to display to the user an array of #GPid for processes blocking the operation an array of strings for each possible choice Check to see whether the mount operation is being used for an anonymous user. %TRUE if mount operation is anonymous. a #GMountOperation. Gets a choice from the mount operation. an integer containing an index of the user's choice from the choice's list, or `0`. a #GMountOperation. Gets the domain of the mount operation. a string set to the domain. a #GMountOperation. Check to see whether the mount operation is being used for a TCRYPT hidden volume. %TRUE if mount operation is for hidden volume. a #GMountOperation. Check to see whether the mount operation is being used for a TCRYPT system volume. %TRUE if mount operation is for system volume. a #GMountOperation. Gets a password from the mount operation. a string containing the password within @op. a #GMountOperation. Gets the state of saving passwords for the mount operation. a #GPasswordSave flag. a #GMountOperation. Gets a PIM from the mount operation. The VeraCrypt PIM within @op. a #GMountOperation. Get the user name from the mount operation. a string containing the user name. a #GMountOperation. Emits the #GMountOperation::reply signal. a #GMountOperation a #GMountOperationResult Sets the mount operation to use an anonymous user if @anonymous is %TRUE. a #GMountOperation. boolean value. Sets a default choice for the mount operation. a #GMountOperation. an integer. Sets the mount operation's domain. a #GMountOperation. the domain to set. Sets the mount operation to use a hidden volume if @hidden_volume is %TRUE. a #GMountOperation. boolean value. Sets the mount operation to use a system volume if @system_volume is %TRUE. a #GMountOperation. boolean value. Sets the mount operation's password to @password. a #GMountOperation. password to set. Sets the state of saving passwords for the mount operation. a #GMountOperation. a set of #GPasswordSave flags. Sets the mount operation's PIM to @pim. a #GMountOperation. an unsigned integer. Sets the user name within @op to @username. a #GMountOperation. input username. Whether to use an anonymous user when authenticating. The index of the user's choice when a question is asked during the mount operation. See the #GMountOperation::ask-question signal. The domain to use for the mount operation. Whether the device to be unlocked is a TCRYPT hidden volume. See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Hidden%20Volume.html). Whether the device to be unlocked is a TCRYPT system volume. In this context, a system volume is a volume with a bootloader and operating system installed. This is only supported for Windows operating systems. For further documentation, see [the VeraCrypt documentation](https://www.veracrypt.fr/en/System%20Encryption.html). The password that is used for authentication when carrying out the mount operation. Determines if and how the password information should be saved. The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20(PIM).html). The user name that is used for authentication when carrying out the mount operation. Emitted by the backend when e.g. a device becomes unavailable while a mount operation is in progress. Implementations of GMountOperation should handle this signal by dismissing open password dialogs. Emitted when a mount operation asks the user for a password. If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a #GtkMessageDialog. string containing a message to display to the user. string containing the default user name. string containing the default domain. a set of #GAskPasswordFlags. Emitted when asking the user a question and gives a list of choices for the user to choose from. If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a #GtkMessageDialog. string containing a message to display to the user. an array of strings for each possible choice. Emitted when the user has replied to the mount operation. a #GMountOperationResult indicating how the request was handled Emitted when one or more processes are blocking an operation e.g. unmounting/ejecting a #GMount or stopping a #GDrive. Note that this signal may be emitted several times to update the list of blocking processes as processes close files. The application should only respond with g_mount_operation_reply() to the latest signal (setting #GMountOperation:choice to the choice the user made). If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a #GtkMessageDialog. string containing a message to display to the user. an array of #GPid for processes blocking the operation. an array of strings for each possible choice. Emitted when an unmount operation has been busy for more than some time (typically 1.5 seconds). When unmounting or ejecting a volume, the kernel might need to flush pending data in its buffers to the volume stable storage, and this operation can take a considerable amount of time. This signal may be emitted several times as long as the unmount operation is outstanding, and then one last time when the operation is completed, with @bytes_left set to zero. Implementations of GMountOperation should handle this signal by showing an UI notification, and then dismiss it, or show another notification of completion, when @bytes_left reaches zero. If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a #GtkMessageDialog. string containing a message to display to the user the estimated time left before the operation completes, in microseconds, or -1 the amount of bytes to be written before the operation completes (or -1 if such amount is not known), or zero if the operation is completed a #GMountOperation string containing a message to display to the user an array of strings for each possible choice a #GMountOperation a #GMountOperationResult a #GMountOperation string containing a message to display to the user an array of #GPid for processes blocking the operation an array of strings for each possible choice #GMountOperationResult is returned as a result when a request for information is send by the mounting operation. The request was fulfilled and the user specified data is now available The user requested the mount operation to be aborted The request was unhandled (i.e. not implemented) Flags used when an unmounting a mount. No flags set. Unmount even if there are outstanding file operations on the mount. Extension point for network status monitoring functionality. See [Extending GIO](overview.html#extending-gio). A socket address of some unknown native type. This corresponds to a general `struct sockaddr` of a type not otherwise handled by GLib. Creates a new #GNativeSocketAddress for @native and @len. a new #GNativeSocketAddress a native address object the length of @native, in bytes `GNetworkAddress` provides an easy way to resolve a hostname and then attempt to connect to that host, handling the possibility of multiple IP addresses and multiple address families. The enumeration results of resolved addresses *may* be cached as long as this object is kept alive which may have unexpected results if alive for too long. See [iface@Gio.SocketConnectable] for an example of using the connectable interface. Creates a new #GSocketConnectable for connecting to the given @hostname and @port. Note that depending on the configuration of the machine, a @hostname of `localhost` may refer to the IPv4 loopback address only, or to both IPv4 and IPv6; use g_network_address_new_loopback() to create a #GNetworkAddress that is guaranteed to resolve to both addresses. the new #GNetworkAddress the hostname the port Creates a new #GSocketConnectable for connecting to the local host over a loopback connection to the given @port. This is intended for use in connecting to local services which may be running on IPv4 or IPv6. The connectable will return IPv4 and IPv6 loopback addresses, regardless of how the host resolves `localhost`. By contrast, g_network_address_new() will often only return an IPv4 address when resolving `localhost`, and an IPv6 address for `localhost6`. g_network_address_get_hostname() will always return `localhost` for a #GNetworkAddress created with this constructor. the new #GNetworkAddress the port Creates a new #GSocketConnectable for connecting to the given @hostname and @port. May fail and return %NULL in case parsing @host_and_port fails. @host_and_port may be in any of a number of recognised formats; an IPv6 address, an IPv4 address, or a domain name (in which case a DNS lookup is performed). Quoting with [] is supported for all address types. A port override may be specified in the usual way with a colon. If no port is specified in @host_and_port then @default_port will be used as the port number to connect to. In general, @host_and_port is expected to be provided by the user (allowing them to give the hostname, and a port override if necessary) and @default_port is expected to be provided by the application. (The port component of @host_and_port can also be specified as a service name rather than as a numeric port, but this functionality is deprecated, because it depends on the contents of /etc/services, which is generally quite sparse on platforms other than Linux.) the new #GNetworkAddress, or %NULL on error the hostname and optionally a port the default port if not in @host_and_port Creates a new #GSocketConnectable for connecting to the given @uri. May fail and return %NULL in case parsing @uri fails. Using this rather than g_network_address_new() or g_network_address_parse() allows #GSocketClient to determine when to use application-specific proxy protocols. the new #GNetworkAddress, or %NULL on error the hostname and optionally a port The default port if none is found in the URI Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded, depending on what @addr was created with. @addr's hostname a #GNetworkAddress Gets @addr's port number @addr's port (which may be 0) a #GNetworkAddress Gets @addr's scheme @addr's scheme (%NULL if not built from URI) a #GNetworkAddress Hostname to resolve. Network port. URI scheme. The host's network connectivity state, as reported by #GNetworkMonitor. The host is not configured with a route to the Internet; it may or may not be connected to a local network. The host is connected to a network, but does not appear to be able to reach the full Internet, perhaps due to upstream network problems. The host is behind a captive portal and cannot reach the full Internet. The host is connected to a network, and appears to be able to reach the full Internet. `GNetworkMonitor` provides an easy-to-use cross-platform API for monitoring network connectivity. On Linux, the available implementations are based on the kernel's netlink interface and on NetworkManager. There is also an implementation for use inside Flatpak sandboxes. Gets the default #GNetworkMonitor for the system. a #GNetworkMonitor, which will be a dummy object if no network monitor is available Attempts to determine whether or not the host pointed to by @connectable can be reached, without actually trying to connect to it. This may return %TRUE even when #GNetworkMonitor:network-available is %FALSE, if, for example, @monitor can determine that @connectable refers to a host on a local network. If @monitor believes that an attempt to connect to @connectable will succeed, it will return %TRUE. Otherwise, it will return %FALSE and set @error to an appropriate error (such as %G_IO_ERROR_HOST_UNREACHABLE). Note that although this does not attempt to connect to @connectable, it may still block for a brief period of time (eg, trying to do multicast DNS on the local network), so if you do not want to block, you should use g_network_monitor_can_reach_async(). %TRUE if @connectable is reachable, %FALSE if not. a #GNetworkMonitor a #GSocketConnectable a #GCancellable, or %NULL Asynchronously attempts to determine whether or not the host pointed to by @connectable can be reached, without actually trying to connect to it. For more details, see g_network_monitor_can_reach(). When the operation is finished, @callback will be called. You can then call g_network_monitor_can_reach_finish() to get the result of the operation. a #GNetworkMonitor a #GSocketConnectable a #GCancellable, or %NULL a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an async network connectivity test. See g_network_monitor_can_reach_async(). %TRUE if network is reachable, %FALSE if not. a #GNetworkMonitor a #GAsyncResult the virtual function pointer for the GNetworkMonitor::network-changed signal. Attempts to determine whether or not the host pointed to by @connectable can be reached, without actually trying to connect to it. This may return %TRUE even when #GNetworkMonitor:network-available is %FALSE, if, for example, @monitor can determine that @connectable refers to a host on a local network. If @monitor believes that an attempt to connect to @connectable will succeed, it will return %TRUE. Otherwise, it will return %FALSE and set @error to an appropriate error (such as %G_IO_ERROR_HOST_UNREACHABLE). Note that although this does not attempt to connect to @connectable, it may still block for a brief period of time (eg, trying to do multicast DNS on the local network), so if you do not want to block, you should use g_network_monitor_can_reach_async(). %TRUE if @connectable is reachable, %FALSE if not. a #GNetworkMonitor a #GSocketConnectable a #GCancellable, or %NULL Asynchronously attempts to determine whether or not the host pointed to by @connectable can be reached, without actually trying to connect to it. For more details, see g_network_monitor_can_reach(). When the operation is finished, @callback will be called. You can then call g_network_monitor_can_reach_finish() to get the result of the operation. a #GNetworkMonitor a #GSocketConnectable a #GCancellable, or %NULL a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an async network connectivity test. See g_network_monitor_can_reach_async(). %TRUE if network is reachable, %FALSE if not. a #GNetworkMonitor a #GAsyncResult Gets a more detailed networking state than g_network_monitor_get_network_available(). If #GNetworkMonitor:network-available is %FALSE, then the connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL. If #GNetworkMonitor:network-available is %TRUE, then the connectivity state will be %G_NETWORK_CONNECTIVITY_FULL (if there is full Internet connectivity), %G_NETWORK_CONNECTIVITY_LIMITED (if the host has a default route, but appears to be unable to actually reach the full Internet), or %G_NETWORK_CONNECTIVITY_PORTAL (if the host is trapped behind a "captive portal" that requires some sort of login or acknowledgement before allowing full Internet access). Note that in the case of %G_NETWORK_CONNECTIVITY_LIMITED and %G_NETWORK_CONNECTIVITY_PORTAL, it is possible that some sites are reachable but others are not. In this case, applications can attempt to connect to remote servers, but should gracefully fall back to their "offline" behavior if the connection attempt fails. the network connectivity state the #GNetworkMonitor Checks if the network is available. "Available" here means that the system has a default route available for at least one of IPv4 or IPv6. It does not necessarily imply that the public Internet is reachable. See #GNetworkMonitor:network-available for more details. whether the network is available the #GNetworkMonitor Checks if the network is metered. See #GNetworkMonitor:network-metered for more details. whether the connection is metered the #GNetworkMonitor More detailed information about the host's network connectivity. See g_network_monitor_get_connectivity() and #GNetworkConnectivity for more details. Whether the network is considered available. That is, whether the system has a default route for at least one of IPv4 or IPv6. Real-world networks are of course much more complicated than this; the machine may be connected to a wifi hotspot that requires payment before allowing traffic through, or may be connected to a functioning router that has lost its own upstream connectivity. Some hosts might only be accessible when a VPN is active. Other hosts might only be accessible when the VPN is not active. Thus, it is best to use g_network_monitor_can_reach() or g_network_monitor_can_reach_async() to test for reachability on a host-by-host basis. (On the other hand, when the property is %FALSE, the application can reasonably expect that no remote hosts at all are reachable, and should indicate this to the user in its UI.) See also #GNetworkMonitor::network-changed. Whether the network is considered metered. That is, whether the system has traffic flowing through the default connection that is subject to limitations set by service providers. For example, traffic might be billed by the amount of data transmitted, or there might be a quota on the amount of traffic per month. This is typical with tethered connections (3G and 4G) and in such situations, bandwidth intensive applications may wish to avoid network activity where possible if it will cost the user money or use up their limited quota. Anything more than a few hundreds of kilobytes of data usage per hour should be avoided without asking permission from the user. If more information is required about specific devices then the system network management API should be used instead (for example, NetworkManager or ConnMan). If this information is not available then no networks will be marked as metered. See also #GNetworkMonitor:network-available. Emitted when the network configuration changes. the current value of #GNetworkMonitor:network-available The virtual function table for #GNetworkMonitor. The parent interface. the virtual function pointer for the GNetworkMonitor::network-changed signal. the virtual function pointer for g_network_monitor_can_reach() %TRUE if @connectable is reachable, %FALSE if not. a #GNetworkMonitor a #GSocketConnectable a #GCancellable, or %NULL the virtual function pointer for g_network_monitor_can_reach_async() a #GNetworkMonitor a #GSocketConnectable a #GCancellable, or %NULL a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function the virtual function pointer for g_network_monitor_can_reach_finish() %TRUE if network is reachable, %FALSE if not. a #GNetworkMonitor a #GAsyncResult Like [class@Gio.NetworkAddress] does with hostnames, `GNetworkService` provides an easy way to resolve a SRV record, and then attempt to connect to one of the hosts that implements that service, handling service priority/weighting, multiple IP addresses, and multiple address families. See [struct@Gio.SrvTarget] for more information about SRV records, and see [iface@Gio.SocketConnectable] for an example of using the connectable interface. Creates a new #GNetworkService representing the given @service, @protocol, and @domain. This will initially be unresolved; use the #GSocketConnectable interface to resolve it. a new #GNetworkService the service type to look up (eg, "ldap") the networking protocol to use for @service (eg, "tcp") the DNS domain to look up the service in Gets the domain that @srv serves. This might be either UTF-8 or ASCII-encoded, depending on what @srv was created with. @srv's domain name a #GNetworkService Gets @srv's protocol name (eg, "tcp"). @srv's protocol name a #GNetworkService Gets the URI scheme used to resolve proxies. By default, the service name is used as scheme. @srv's scheme name a #GNetworkService Gets @srv's service name (eg, "ldap"). @srv's service name a #GNetworkService Set's the URI scheme used to resolve proxies. By default, the service name is used as scheme. a #GNetworkService a URI scheme Network domain, for example `example.com`. Network protocol, for example `tcp`. Network scheme (default is to use service). Service name, for example `ldap`. `GNotification` is a mechanism for creating a notification to be shown to the user — typically as a pop-up notification presented by the desktop environment shell. The key difference between `GNotification` and other similar APIs is that, if supported by the desktop environment, notifications sent with `GNotification` will persist after the application has exited, and even across system reboots. Since the user may click on a notification while the application is not running, applications using `GNotification` should be able to be started as a D-Bus service, using [class@Gio.Application]. In order for `GNotification` to work, the application must have installed a `.desktop` file. For example: ``` [Desktop Entry] Name=Test Application Comment=Description of what Test Application does Exec=gnome-test-application Icon=org.gnome.TestApplication Terminal=false Type=Application Categories=GNOME;GTK;TestApplication Category; StartupNotify=true DBusActivatable=true X-GNOME-UsesNotifications=true ``` The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center that this application uses notifications, so it can be listed in the Control Center’s ‘Notifications’ panel. The `.desktop` file must be named as `org.gnome.TestApplication.desktop`, where `org.gnome.TestApplication` is the ID passed to [ctor@Gio.Application.new]. User interaction with a notification (either the default action, or buttons) must be associated with actions on the application (ie: `app.` actions). It is not possible to route user interaction through the notification itself, because the object will not exist if the application is autostarted as a result of a notification being clicked. A notification can be sent with [method@Gio.Application.send_notification]. In Windows, notification actions are unsupported, when sending the notification a warning will be printed if a default action or action buttons were added. Creates a new #GNotification with @title as its title. After populating @notification with more details, it can be sent to the desktop shell with g_application_send_notification(). Changing any properties after this call will not have any effect until resending @notification. a new #GNotification instance the title of the notification Adds a button to @notification that activates the action in @detailed_action when clicked. That action must be an application-wide action (starting with "app."). If @detailed_action contains a target, the action will be activated with that target as its parameter. See g_action_parse_detailed_name() for a description of the format for @detailed_action. a #GNotification label of the button a detailed action name Adds a button to @notification that activates @action when clicked. @action must be an application-wide action (it must start with "app."). If @target_format is given, it is used to collect remaining positional parameters into a #GVariant instance, similar to g_variant_new(). @action will be activated with that #GVariant as its parameter. a #GNotification label of the button an action name a #GVariant format string, or %NULL positional parameters, as determined by @target_format Adds a button to @notification that activates @action when clicked. @action must be an application-wide action (it must start with "app."). If @target is non-%NULL, @action will be activated with @target as its parameter. a #GNotification label of the button an action name a #GVariant to use as @action's parameter, or %NULL Sets the body of @notification to @body. a #GNotification the new body for @notification, or %NULL Sets the type of @notification to @category. Categories have a main type like `email`, `im` or `device` and can have a detail separated by a `.`, e.g. `im.received` or `email.arrived`. Setting the category helps the notification server to select proper feedback to the user. Standard categories are [listed in the specification](https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html). a #GNotification the category for @notification, or %NULL for no category Sets the default action of @notification to @detailed_action. This action is activated when the notification is clicked on. The action in @detailed_action must be an application-wide action (it must start with "app."). If @detailed_action contains a target, the given action will be activated with that target as its parameter. See g_action_parse_detailed_name() for a description of the format for @detailed_action. When no default action is set, the application that the notification was sent on is activated. a #GNotification a detailed action name Sets the default action of @notification to @action. This action is activated when the notification is clicked on. It must be an application-wide action (it must start with "app."). If @target_format is given, it is used to collect remaining positional parameters into a #GVariant instance, similar to g_variant_new(). @action will be activated with that #GVariant as its parameter. When no default action is set, the application that the notification was sent on is activated. a #GNotification an action name a #GVariant format string, or %NULL positional parameters, as determined by @target_format Sets the default action of @notification to @action. This action is activated when the notification is clicked on. It must be an application-wide action (start with "app."). If @target is non-%NULL, @action will be activated with @target as its parameter. If @target is floating, it will be consumed. When no default action is set, the application that the notification was sent on is activated. a #GNotification an action name a #GVariant to use as @action's parameter, or %NULL Sets the icon of @notification to @icon. a #GNotification the icon to be shown in @notification, as a #GIcon Sets the priority of @notification to @priority. See #GNotificationPriority for possible values. a #GNotification a #GNotificationPriority Sets the title of @notification to @title. a #GNotification the new title for @notification Deprecated in favor of g_notification_set_priority(). Since 2.42, this has been deprecated in favour of g_notification_set_priority(). a #GNotification %TRUE if @notification is urgent Priority levels for #GNotifications. the default priority, to be used for the majority of notifications (for example email messages, software updates, completed download/sync operations) for notifications that do not require immediate attention - typically used for contextual background information, such as contact birthdays or local weather for events that require more attention, usually because responses are time-sensitive (for example chat and SMS messages or alarms) for urgent notifications, or notifications that require a response in a short space of time (for example phone calls or emergency warnings) Structure used for scatter/gather data output when sending multiple messages or packets in one go. You generally pass in an array of #GOutputVectors and the operation will use all the buffers as if they were one buffer. If @address is %NULL then the message is sent to the default receiver (as previously set by g_socket_connect()). a #GSocketAddress, or %NULL pointer to an array of output vectors the number of output vectors pointed to by @vectors. initialize to 0. Will be set to the number of bytes that have been sent a pointer to an array of #GSocketControlMessages, or %NULL. number of elements in @control_messages. `GOutputStream` is a base class for implementing streaming output. It has functions to write to a stream ([method@Gio.OutputStream.write]), to close a stream ([method@Gio.OutputStream.close]) and to flush pending writes ([method@Gio.OutputStream.flush]). To copy the content of an input stream to an output stream without manually handling the reads and writes, use [method@Gio.OutputStream.splice]. See the documentation for [class@Gio.IOStream] for details of thread safety of streaming APIs. All of these functions have async variants too. All classes derived from `GOutputStream` *should* implement synchronous writing, splicing, flushing and closing streams, but *may* implement asynchronous versions. Requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished @callback will be called. You can then call g_output_stream_close_finish() to get the result of the operation. For behaviour details see g_output_stream_close(). The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. A #GOutputStream. the io priority of the request. optional cancellable object a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Closes an output stream. %TRUE if stream was successfully closed, %FALSE otherwise. a #GOutputStream. a #GAsyncResult. Forces a write of all user-space buffered data for the given @stream. Will block during the operation. Closing the stream will implicitly cause a flush. This function is optional for inherited classes. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE on success, %FALSE on error a #GOutputStream. optional cancellable object Forces an asynchronous write of all user-space buffered data for the given @stream. For behaviour details see g_output_stream_flush(). When the operation is finished @callback will be called. You can then call g_output_stream_flush_finish() to get the result of the operation. a #GOutputStream. the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes flushing an output stream. %TRUE if flush operation succeeded, %FALSE otherwise. a #GOutputStream. a GAsyncResult. Splices an input stream into an output stream. a #gssize containing the size of the data spliced, or -1 if an error occurred. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced. a #GOutputStream. a #GInputStream. a set of #GOutputStreamSpliceFlags. optional #GCancellable object, %NULL to ignore. Splices a stream asynchronously. When the operation is finished @callback will be called. You can then call g_output_stream_splice_finish() to get the result of the operation. For the synchronous, blocking version of this function, see g_output_stream_splice(). a #GOutputStream. a #GInputStream. a set of #GOutputStreamSpliceFlags. the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous stream splice operation. a #gssize of the number of bytes spliced. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced. a #GOutputStream. a #GAsyncResult. Request an asynchronous write of @count bytes from @buffer into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_write_finish() to get the result of the operation. During an async request no other sync and async calls are allowed, and will result in %G_IO_ERROR_PENDING errors. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, the number of bytes written will be passed to the @callback. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, but generally we try to write as many bytes as requested. You are guaranteed that this method will never fail with %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the method will just wait until this changes. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. For the synchronous, blocking version of this function, see g_output_stream_write(). Note that no copy of @buffer will be made, so it must stay valid until @callback is called. See g_output_stream_write_bytes_async() for a #GBytes version that will automatically hold a reference to the contents (without copying) for the duration of the call. A #GOutputStream. the buffer containing the data to write. the number of bytes to write the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes a stream write operation. a #gssize containing the number of bytes written to the stream. a #GOutputStream. a #GAsyncResult. Tries to write @count bytes from @buffer into the stream. Will block during the operation. If count is 0, returns 0 and does nothing. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, the number of bytes written to the stream is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, or if there is not enough storage in the stream. All writes block until at least one byte is written or an error occurs; 0 is never returned (unless @count is 0). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error -1 is returned and @error is set accordingly. Number of bytes written, or -1 on error a #GOutputStream. the buffer containing the data to write. the number of bytes to write optional cancellable object Request an asynchronous write of the bytes contained in @n_vectors @vectors into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_writev_finish() to get the result of the operation. During an async request no other sync and async calls are allowed, and will result in %G_IO_ERROR_PENDING errors. On success, the number of bytes written will be passed to the @callback. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, but generally we try to write as many bytes as requested. You are guaranteed that this method will never fail with %G_IO_ERROR_WOULD_BLOCK — if @stream can't accept more data, the method will just wait until this changes. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. For the synchronous, blocking version of this function, see g_output_stream_writev(). Note that no copy of @vectors will be made, so it must stay valid until @callback is called. A #GOutputStream. the buffer containing the #GOutputVectors to write. the number of vectors to write the I/O priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes a stream writev operation. %TRUE on success, %FALSE if there was an error a #GOutputStream. a #GAsyncResult. location to store the number of bytes that were written to the stream Tries to write the bytes contained in the @n_vectors @vectors into the stream. Will block during the operation. If @n_vectors is 0 or the sum of all bytes in @vectors is 0, returns 0 and does nothing. On success, the number of bytes written to the stream is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, or if there is not enough storage in the stream. All writes block until at least one byte is written or an error occurs; 0 is never returned (unless @n_vectors is 0 or the sum of all bytes in @vectors is 0). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. Some implementations of g_output_stream_writev() may have limitations on the aggregate buffer size, and will return %G_IO_ERROR_INVALID_ARGUMENT if these are exceeded. For example, when writing to a local file on UNIX platforms, the aggregate buffer size must not exceed %G_MAXSSIZE bytes. %TRUE on success, %FALSE if there was an error a #GOutputStream. the buffer containing the #GOutputVectors to write. the number of vectors to write location to store the number of bytes that were written to the stream optional cancellable object Clears the pending flag on @stream. output stream Closes the stream, releasing resources related to it. Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. Closing a stream multiple times will not return an error. Closing a stream will automatically flush any outstanding buffers in the stream. Streams will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. Some streams might keep the backing store of the stream (e.g. a file descriptor) open after the stream is closed. See the documentation for the individual stream for details. On failure the first error that happened will be reported, but the close operation will finish as much as possible. A stream that failed to close will still return %G_IO_ERROR_CLOSED for all operations. Still, it is important to check and report the error to the user, otherwise there might be a loss of data as all data might not be written. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave the stream closed, but there some streams can use a faster close that doesn't block to e.g. check errors. On cancellation (as with any error) there is no guarantee that all written data will reach the target. %TRUE on success, %FALSE on failure A #GOutputStream. optional cancellable object Requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished @callback will be called. You can then call g_output_stream_close_finish() to get the result of the operation. For behaviour details see g_output_stream_close(). The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. A #GOutputStream. the io priority of the request. optional cancellable object a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Closes an output stream. %TRUE if stream was successfully closed, %FALSE otherwise. a #GOutputStream. a #GAsyncResult. Forces a write of all user-space buffered data for the given @stream. Will block during the operation. Closing the stream will implicitly cause a flush. This function is optional for inherited classes. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE on success, %FALSE on error a #GOutputStream. optional cancellable object Forces an asynchronous write of all user-space buffered data for the given @stream. For behaviour details see g_output_stream_flush(). When the operation is finished @callback will be called. You can then call g_output_stream_flush_finish() to get the result of the operation. a #GOutputStream. the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes flushing an output stream. %TRUE if flush operation succeeded, %FALSE otherwise. a #GOutputStream. a GAsyncResult. Checks if an output stream has pending actions. %TRUE if @stream has pending actions. a #GOutputStream. Checks if an output stream has already been closed. %TRUE if @stream is closed. %FALSE otherwise. a #GOutputStream. Checks if an output stream is being closed. This can be used inside e.g. a flush implementation to see if the flush (or other i/o operation) is called from within the closing operation. %TRUE if @stream is being closed. %FALSE otherwise. a #GOutputStream. This is a utility function around g_output_stream_write_all(). It uses g_strdup_vprintf() to turn @format and @... into a string that is then written to @stream. See the documentation of g_output_stream_write_all() about the behavior of the actual write operation. Note that partial writes cannot be properly checked with this function due to the variable length of the written string, if you need precise control over partial write failures, you need to create you own printf()-like wrapper around g_output_stream_write() or g_output_stream_write_all(). %TRUE on success, %FALSE if there was an error a #GOutputStream. location to store the number of bytes that was written to the stream optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore the format string. See the printf() documentation the parameters to insert into the format string Sets @stream to have actions pending. If the pending flag is already set or @stream is closed, it will return %FALSE and set @error. %TRUE if pending was previously unset and is now set. a #GOutputStream. Splices an input stream into an output stream. a #gssize containing the size of the data spliced, or -1 if an error occurred. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced. a #GOutputStream. a #GInputStream. a set of #GOutputStreamSpliceFlags. optional #GCancellable object, %NULL to ignore. Splices a stream asynchronously. When the operation is finished @callback will be called. You can then call g_output_stream_splice_finish() to get the result of the operation. For the synchronous, blocking version of this function, see g_output_stream_splice(). a #GOutputStream. a #GInputStream. a set of #GOutputStreamSpliceFlags. the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous stream splice operation. a #gssize of the number of bytes spliced. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced. a #GOutputStream. a #GAsyncResult. This is a utility function around g_output_stream_write_all(). It uses g_strdup_vprintf() to turn @format and @args into a string that is then written to @stream. See the documentation of g_output_stream_write_all() about the behavior of the actual write operation. Note that partial writes cannot be properly checked with this function due to the variable length of the written string, if you need precise control over partial write failures, you need to create you own printf()-like wrapper around g_output_stream_write() or g_output_stream_write_all(). %TRUE on success, %FALSE if there was an error a #GOutputStream. location to store the number of bytes that was written to the stream optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore the format string. See the printf() documentation the parameters to insert into the format string Tries to write @count bytes from @buffer into the stream. Will block during the operation. If count is 0, returns 0 and does nothing. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, the number of bytes written to the stream is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, or if there is not enough storage in the stream. All writes block until at least one byte is written or an error occurs; 0 is never returned (unless @count is 0). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error -1 is returned and @error is set accordingly. Number of bytes written, or -1 on error a #GOutputStream. the buffer containing the data to write. the number of bytes to write optional cancellable object Tries to write @count bytes from @buffer into the stream. Will block during the operation. This function is similar to g_output_stream_write(), except it tries to write as many bytes as requested, only stopping on an error. On a successful write of @count bytes, %TRUE is returned, and @bytes_written is set to @count. If there is an error during the operation %FALSE is returned and @error is set to indicate the error status. As a special exception to the normal conventions for functions that use #GError, if this function returns %FALSE (and sets @error) then @bytes_written will be set to the number of bytes that were successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_output_stream_write(). %TRUE on success, %FALSE if there was an error a #GOutputStream. the buffer containing the data to write. the number of bytes to write location to store the number of bytes that was written to the stream optional #GCancellable object, %NULL to ignore. Request an asynchronous write of @count bytes from @buffer into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_write_all_finish() to get the result of the operation. This is the asynchronous version of g_output_stream_write_all(). Call g_output_stream_write_all_finish() to collect the result. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. Note that no copy of @buffer will be made, so it must stay valid until @callback is called. A #GOutputStream the buffer containing the data to write the number of bytes to write the io priority of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous stream write operation started with g_output_stream_write_all_async(). As a special exception to the normal conventions for functions that use #GError, if this function returns %FALSE (and sets @error) then @bytes_written will be set to the number of bytes that were successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_output_stream_write_async(). %TRUE on success, %FALSE if there was an error a #GOutputStream a #GAsyncResult location to store the number of bytes that was written to the stream Request an asynchronous write of @count bytes from @buffer into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_write_finish() to get the result of the operation. During an async request no other sync and async calls are allowed, and will result in %G_IO_ERROR_PENDING errors. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, the number of bytes written will be passed to the @callback. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, but generally we try to write as many bytes as requested. You are guaranteed that this method will never fail with %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the method will just wait until this changes. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. For the synchronous, blocking version of this function, see g_output_stream_write(). Note that no copy of @buffer will be made, so it must stay valid until @callback is called. See g_output_stream_write_bytes_async() for a #GBytes version that will automatically hold a reference to the contents (without copying) for the duration of the call. A #GOutputStream. the buffer containing the data to write. the number of bytes to write the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function A wrapper function for g_output_stream_write() which takes a #GBytes as input. This can be more convenient for use by language bindings or in other cases where the refcounted nature of #GBytes is helpful over a bare pointer interface. However, note that this function may still perform partial writes, just like g_output_stream_write(). If that occurs, to continue writing, you will need to create a new #GBytes containing just the remaining bytes, using g_bytes_new_from_bytes(). Passing the same #GBytes instance multiple times potentially can result in duplicated data in the output stream. Number of bytes written, or -1 on error a #GOutputStream. the #GBytes to write optional cancellable object This function is similar to g_output_stream_write_async(), but takes a #GBytes as input. Due to the refcounted nature of #GBytes, this allows the stream to avoid taking a copy of the data. However, note that this function may still perform partial writes, just like g_output_stream_write_async(). If that occurs, to continue writing, you will need to create a new #GBytes containing just the remaining bytes, using g_bytes_new_from_bytes(). Passing the same #GBytes instance multiple times potentially can result in duplicated data in the output stream. For the synchronous, blocking version of this function, see g_output_stream_write_bytes(). A #GOutputStream. The bytes to write the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes a stream write-from-#GBytes operation. a #gssize containing the number of bytes written to the stream. a #GOutputStream. a #GAsyncResult. Finishes a stream write operation. a #gssize containing the number of bytes written to the stream. a #GOutputStream. a #GAsyncResult. Tries to write the bytes contained in the @n_vectors @vectors into the stream. Will block during the operation. If @n_vectors is 0 or the sum of all bytes in @vectors is 0, returns 0 and does nothing. On success, the number of bytes written to the stream is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, or if there is not enough storage in the stream. All writes block until at least one byte is written or an error occurs; 0 is never returned (unless @n_vectors is 0 or the sum of all bytes in @vectors is 0). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. Some implementations of g_output_stream_writev() may have limitations on the aggregate buffer size, and will return %G_IO_ERROR_INVALID_ARGUMENT if these are exceeded. For example, when writing to a local file on UNIX platforms, the aggregate buffer size must not exceed %G_MAXSSIZE bytes. %TRUE on success, %FALSE if there was an error a #GOutputStream. the buffer containing the #GOutputVectors to write. the number of vectors to write location to store the number of bytes that were written to the stream optional cancellable object Tries to write the bytes contained in the @n_vectors @vectors into the stream. Will block during the operation. This function is similar to g_output_stream_writev(), except it tries to write as many bytes as requested, only stopping on an error. On a successful write of all @n_vectors vectors, %TRUE is returned, and @bytes_written is set to the sum of all the sizes of @vectors. If there is an error during the operation %FALSE is returned and @error is set to indicate the error status. As a special exception to the normal conventions for functions that use #GError, if this function returns %FALSE (and sets @error) then @bytes_written will be set to the number of bytes that were successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_output_stream_write(). The content of the individual elements of @vectors might be changed by this function. %TRUE on success, %FALSE if there was an error a #GOutputStream. the buffer containing the #GOutputVectors to write. the number of vectors to write location to store the number of bytes that were written to the stream optional #GCancellable object, %NULL to ignore. Request an asynchronous write of the bytes contained in the @n_vectors @vectors into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_writev_all_finish() to get the result of the operation. This is the asynchronous version of g_output_stream_writev_all(). Call g_output_stream_writev_all_finish() to collect the result. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. Note that no copy of @vectors will be made, so it must stay valid until @callback is called. The content of the individual elements of @vectors might be changed by this function. A #GOutputStream the buffer containing the #GOutputVectors to write. the number of vectors to write the I/O priority of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous stream write operation started with g_output_stream_writev_all_async(). As a special exception to the normal conventions for functions that use #GError, if this function returns %FALSE (and sets @error) then @bytes_written will be set to the number of bytes that were successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_output_stream_writev_async(). %TRUE on success, %FALSE if there was an error a #GOutputStream a #GAsyncResult location to store the number of bytes that were written to the stream Request an asynchronous write of the bytes contained in @n_vectors @vectors into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_writev_finish() to get the result of the operation. During an async request no other sync and async calls are allowed, and will result in %G_IO_ERROR_PENDING errors. On success, the number of bytes written will be passed to the @callback. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, but generally we try to write as many bytes as requested. You are guaranteed that this method will never fail with %G_IO_ERROR_WOULD_BLOCK — if @stream can't accept more data, the method will just wait until this changes. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. For the synchronous, blocking version of this function, see g_output_stream_writev(). Note that no copy of @vectors will be made, so it must stay valid until @callback is called. A #GOutputStream. the buffer containing the #GOutputVectors to write. the number of vectors to write the I/O priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes a stream writev operation. %TRUE on success, %FALSE if there was an error a #GOutputStream. a #GAsyncResult. location to store the number of bytes that were written to the stream Number of bytes written, or -1 on error a #GOutputStream. the buffer containing the data to write. the number of bytes to write optional cancellable object a #gssize containing the size of the data spliced, or -1 if an error occurred. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced. a #GOutputStream. a #GInputStream. a set of #GOutputStreamSpliceFlags. optional #GCancellable object, %NULL to ignore. %TRUE on success, %FALSE on error a #GOutputStream. optional cancellable object A #GOutputStream. the buffer containing the data to write. the number of bytes to write the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function a #gssize containing the number of bytes written to the stream. a #GOutputStream. a #GAsyncResult. a #GOutputStream. a #GInputStream. a set of #GOutputStreamSpliceFlags. the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function a #gssize of the number of bytes spliced. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced. a #GOutputStream. a #GAsyncResult. a #GOutputStream. the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function %TRUE if flush operation succeeded, %FALSE otherwise. a #GOutputStream. a GAsyncResult. A #GOutputStream. the io priority of the request. optional cancellable object a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function %TRUE if stream was successfully closed, %FALSE otherwise. a #GOutputStream. a #GAsyncResult. %TRUE on success, %FALSE if there was an error a #GOutputStream. the buffer containing the #GOutputVectors to write. the number of vectors to write location to store the number of bytes that were written to the stream optional cancellable object A #GOutputStream. the buffer containing the #GOutputVectors to write. the number of vectors to write the I/O priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function %TRUE on success, %FALSE if there was an error a #GOutputStream. a #GAsyncResult. location to store the number of bytes that were written to the stream GOutputStreamSpliceFlags determine how streams should be spliced. Do not close either stream. Close the source stream after the splice. Close the target stream after the splice. Structure used for scatter/gather data output. You generally pass in an array of #GOutputVectors and the operation will use all the buffers as if they were one buffer. Pointer to a buffer of data to read. the size of @buffer. Extension point for power profile usage monitoring functionality. See [Extending GIO](overview.html#extending-gio). Extension point for proxy functionality. See [Extending GIO](overview.html#extending-gio). Extension point for proxy resolving functionality. See [Extending GIO](overview.html#extending-gio). #GPasswordSave is used to indicate the lifespan of a saved password. #Gvfs stores passwords in the Gnome keyring when this flag allows it to, and later retrieves it again from there. never save a password. save a password for the session. save a password permanently. A `GPermission` represents the status of the caller’s permission to perform a certain action. You can query if the action is currently allowed and if it is possible to acquire the permission so that the action will be allowed in the future. There is also an API to actually acquire the permission and one to release it. As an example, a `GPermission` might represent the ability for the user to write to a [class@Gio.Settings] object. This `GPermission` object could then be used to decide if it is appropriate to show a “Click here to unlock” button in a dialog and to provide the mechanism to invoke when that button is clicked. Attempts to acquire the permission represented by @permission. The precise method by which this happens depends on the permission and the underlying authentication mechanism. A simple example is that a dialog may appear asking the user to enter their password. You should check with g_permission_get_can_acquire() before calling this function. If the permission is acquired then %TRUE is returned. Otherwise, %FALSE is returned and @error is set appropriately. This call is blocking, likely for a very long time (in the case that user interaction is required). See g_permission_acquire_async() for the non-blocking version. %TRUE if the permission was successfully acquired a #GPermission instance a #GCancellable, or %NULL Attempts to acquire the permission represented by @permission. This is the first half of the asynchronous version of g_permission_acquire(). a #GPermission instance a #GCancellable, or %NULL the #GAsyncReadyCallback to call when done the user data to pass to @callback Collects the result of attempting to acquire the permission represented by @permission. This is the second half of the asynchronous version of g_permission_acquire(). %TRUE if the permission was successfully acquired a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback Attempts to release the permission represented by @permission. The precise method by which this happens depends on the permission and the underlying authentication mechanism. In most cases the permission will be dropped immediately without further action. You should check with g_permission_get_can_release() before calling this function. If the permission is released then %TRUE is returned. Otherwise, %FALSE is returned and @error is set appropriately. This call is blocking, likely for a very long time (in the case that user interaction is required). See g_permission_release_async() for the non-blocking version. %TRUE if the permission was successfully released a #GPermission instance a #GCancellable, or %NULL Attempts to release the permission represented by @permission. This is the first half of the asynchronous version of g_permission_release(). a #GPermission instance a #GCancellable, or %NULL the #GAsyncReadyCallback to call when done the user data to pass to @callback Collects the result of attempting to release the permission represented by @permission. This is the second half of the asynchronous version of g_permission_release(). %TRUE if the permission was successfully released a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback Attempts to acquire the permission represented by @permission. The precise method by which this happens depends on the permission and the underlying authentication mechanism. A simple example is that a dialog may appear asking the user to enter their password. You should check with g_permission_get_can_acquire() before calling this function. If the permission is acquired then %TRUE is returned. Otherwise, %FALSE is returned and @error is set appropriately. This call is blocking, likely for a very long time (in the case that user interaction is required). See g_permission_acquire_async() for the non-blocking version. %TRUE if the permission was successfully acquired a #GPermission instance a #GCancellable, or %NULL Attempts to acquire the permission represented by @permission. This is the first half of the asynchronous version of g_permission_acquire(). a #GPermission instance a #GCancellable, or %NULL the #GAsyncReadyCallback to call when done the user data to pass to @callback Collects the result of attempting to acquire the permission represented by @permission. This is the second half of the asynchronous version of g_permission_acquire(). %TRUE if the permission was successfully acquired a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback Gets the value of the 'allowed' property. This property is %TRUE if the caller currently has permission to perform the action that @permission represents the permission to perform. the value of the 'allowed' property a #GPermission instance Gets the value of the 'can-acquire' property. This property is %TRUE if it is generally possible to acquire the permission by calling g_permission_acquire(). the value of the 'can-acquire' property a #GPermission instance Gets the value of the 'can-release' property. This property is %TRUE if it is generally possible to release the permission by calling g_permission_release(). the value of the 'can-release' property a #GPermission instance This function is called by the #GPermission implementation to update the properties of the permission. You should never call this function except from a #GPermission implementation. GObject notify signals are generated, as appropriate. a #GPermission instance the new value for the 'allowed' property the new value for the 'can-acquire' property the new value for the 'can-release' property Attempts to release the permission represented by @permission. The precise method by which this happens depends on the permission and the underlying authentication mechanism. In most cases the permission will be dropped immediately without further action. You should check with g_permission_get_can_release() before calling this function. If the permission is released then %TRUE is returned. Otherwise, %FALSE is returned and @error is set appropriately. This call is blocking, likely for a very long time (in the case that user interaction is required). See g_permission_release_async() for the non-blocking version. %TRUE if the permission was successfully released a #GPermission instance a #GCancellable, or %NULL Attempts to release the permission represented by @permission. This is the first half of the asynchronous version of g_permission_release(). a #GPermission instance a #GCancellable, or %NULL the #GAsyncReadyCallback to call when done the user data to pass to @callback Collects the result of attempting to release the permission represented by @permission. This is the second half of the asynchronous version of g_permission_release(). %TRUE if the permission was successfully released a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback %TRUE if the caller currently has permission to perform the action that @permission represents the permission to perform. %TRUE if it is generally possible to acquire the permission by calling g_permission_acquire(). %TRUE if it is generally possible to release the permission by calling g_permission_release(). %TRUE if the permission was successfully acquired a #GPermission instance a #GCancellable, or %NULL a #GPermission instance a #GCancellable, or %NULL the #GAsyncReadyCallback to call when done the user data to pass to @callback %TRUE if the permission was successfully acquired a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback %TRUE if the permission was successfully released a #GPermission instance a #GCancellable, or %NULL a #GPermission instance a #GCancellable, or %NULL the #GAsyncReadyCallback to call when done the user data to pass to @callback %TRUE if the permission was successfully released a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback `GPollableInputStream` is implemented by [class@Gio.InputStream]s that can be polled for readiness to read. This can be used when interfacing with a non-GIO API that expects UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. Some classes may implement `GPollableInputStream` but have only certain instances of that class be pollable. If [method@Gio.PollableInputStream.can_poll] returns false, then the behavior of other `GPollableInputStream` methods is undefined. Checks if @stream is actually pollable. Some classes may implement #GPollableInputStream but have only certain instances of that class be pollable. If this method returns %FALSE, then the behavior of other #GPollableInputStream methods is undefined. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. %TRUE if @stream is pollable, %FALSE if not. a #GPollableInputStream. Creates a #GSource that triggers when @stream can be read, or @cancellable is triggered or an error occurs. The callback on the source is of the #GPollableSourceFunc type. As with g_pollable_input_stream_is_readable(), it is possible that the stream may not actually be readable even after the source triggers, so you should use g_pollable_input_stream_read_nonblocking() rather than g_input_stream_read() from the callback. The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns %FALSE for @stream. a new #GSource a #GPollableInputStream. a #GCancellable, or %NULL Checks if @stream can be read. Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to g_input_stream_read() after this returns %TRUE would still block. To guarantee non-blocking behavior, you should always use g_pollable_input_stream_read_nonblocking(), which will return a %G_IO_ERROR_WOULD_BLOCK error rather than blocking. The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns %FALSE for @stream. %TRUE if @stream is readable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_input_stream_is_readable() returning %TRUE, and the next attempt to read will return the error. a #GPollableInputStream. Attempts to read up to @count bytes from @stream into @buffer, as with g_input_stream_read(). If @stream is not currently readable, this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can use g_pollable_input_stream_create_source() to create a #GSource that will be triggered when @stream is readable. Note that since this method never blocks, you cannot actually use @cancellable to cancel it. However, it will return an error if @cancellable has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled. The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns %FALSE for @stream. the number of bytes read, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). a #GPollableInputStream a buffer to read data into (which should be at least @count bytes long). the number of bytes you want to read Checks if @stream is actually pollable. Some classes may implement #GPollableInputStream but have only certain instances of that class be pollable. If this method returns %FALSE, then the behavior of other #GPollableInputStream methods is undefined. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. %TRUE if @stream is pollable, %FALSE if not. a #GPollableInputStream. Creates a #GSource that triggers when @stream can be read, or @cancellable is triggered or an error occurs. The callback on the source is of the #GPollableSourceFunc type. As with g_pollable_input_stream_is_readable(), it is possible that the stream may not actually be readable even after the source triggers, so you should use g_pollable_input_stream_read_nonblocking() rather than g_input_stream_read() from the callback. The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns %FALSE for @stream. a new #GSource a #GPollableInputStream. a #GCancellable, or %NULL Checks if @stream can be read. Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to g_input_stream_read() after this returns %TRUE would still block. To guarantee non-blocking behavior, you should always use g_pollable_input_stream_read_nonblocking(), which will return a %G_IO_ERROR_WOULD_BLOCK error rather than blocking. The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns %FALSE for @stream. %TRUE if @stream is readable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_input_stream_is_readable() returning %TRUE, and the next attempt to read will return the error. a #GPollableInputStream. Attempts to read up to @count bytes from @stream into @buffer, as with g_input_stream_read(). If @stream is not currently readable, this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can use g_pollable_input_stream_create_source() to create a #GSource that will be triggered when @stream is readable. Note that since this method never blocks, you cannot actually use @cancellable to cancel it. However, it will return an error if @cancellable has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled. The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns %FALSE for @stream. the number of bytes read, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). a #GPollableInputStream a buffer to read data into (which should be at least @count bytes long). the number of bytes you want to read a #GCancellable, or %NULL The interface for pollable input streams. The default implementation of @can_poll always returns %TRUE. The default implementation of @read_nonblocking calls g_pollable_input_stream_is_readable(), and then calls g_input_stream_read() if it returns %TRUE. This means you only need to override it if it is possible that your @is_readable implementation may return %TRUE when the stream is not actually readable. The parent interface. Checks if the #GPollableInputStream instance is actually pollable %TRUE if @stream is pollable, %FALSE if not. a #GPollableInputStream. Checks if the stream is readable %TRUE if @stream is readable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_input_stream_is_readable() returning %TRUE, and the next attempt to read will return the error. a #GPollableInputStream. Creates a #GSource to poll the stream a new #GSource a #GPollableInputStream. a #GCancellable, or %NULL Does a non-blocking read or returns %G_IO_ERROR_WOULD_BLOCK the number of bytes read, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). a #GPollableInputStream a buffer to read data into (which should be at least @count bytes long). the number of bytes you want to read `GPollableOutputStream` is implemented by [class@Gio.OutputStream]s that can be polled for readiness to write. This can be used when interfacing with a non-GIO API that expects UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. Some classes may implement `GPollableOutputStream` but have only certain instances of that class be pollable. If [method@Gio.PollableOutputStream.can_poll] returns false, then the behavior of other `GPollableOutputStream` methods is undefined. Checks if @stream is actually pollable. Some classes may implement #GPollableOutputStream but have only certain instances of that class be pollable. If this method returns %FALSE, then the behavior of other #GPollableOutputStream methods is undefined. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. %TRUE if @stream is pollable, %FALSE if not. a #GPollableOutputStream. Creates a #GSource that triggers when @stream can be written, or @cancellable is triggered or an error occurs. The callback on the source is of the #GPollableSourceFunc type. As with g_pollable_output_stream_is_writable(), it is possible that the stream may not actually be writable even after the source triggers, so you should use g_pollable_output_stream_write_nonblocking() rather than g_output_stream_write() from the callback. The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. a new #GSource a #GPollableOutputStream. a #GCancellable, or %NULL Checks if @stream can be written. Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to g_output_stream_write() after this returns %TRUE would still block. To guarantee non-blocking behavior, you should always use g_pollable_output_stream_write_nonblocking(), which will return a %G_IO_ERROR_WOULD_BLOCK error rather than blocking. The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. %TRUE if @stream is writable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_output_stream_is_writable() returning %TRUE, and the next attempt to write will return the error. a #GPollableOutputStream. Attempts to write up to @count bytes from @buffer to @stream, as with g_output_stream_write(). If @stream is not currently writable, this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can use g_pollable_output_stream_create_source() to create a #GSource that will be triggered when @stream is writable. Note that since this method never blocks, you cannot actually use @cancellable to cancel it. However, it will return an error if @cancellable has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled. Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying transports like D/TLS require that you re-send the same @buffer and @count in the next write call. The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. the number of bytes written, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). a #GPollableOutputStream a buffer to write data from the number of bytes you want to write Attempts to write the bytes contained in the @n_vectors @vectors to @stream, as with g_output_stream_writev(). If @stream is not currently writable, this will immediately return %@G_POLLABLE_RETURN_WOULD_BLOCK, and you can use g_pollable_output_stream_create_source() to create a #GSource that will be triggered when @stream is writable. @error will *not* be set in that case. Note that since this method never blocks, you cannot actually use @cancellable to cancel it. However, it will return an error if @cancellable has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled. Also note that if %G_POLLABLE_RETURN_WOULD_BLOCK is returned some underlying transports like D/TLS require that you re-send the same @vectors and @n_vectors in the next write call. The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK if the stream is not currently writable (and @error is *not* set), or %G_POLLABLE_RETURN_FAILED if there was an error in which case @error will be set. a #GPollableOutputStream the buffer containing the #GOutputVectors to write. the number of vectors to write location to store the number of bytes that were written to the stream Checks if @stream is actually pollable. Some classes may implement #GPollableOutputStream but have only certain instances of that class be pollable. If this method returns %FALSE, then the behavior of other #GPollableOutputStream methods is undefined. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. %TRUE if @stream is pollable, %FALSE if not. a #GPollableOutputStream. Creates a #GSource that triggers when @stream can be written, or @cancellable is triggered or an error occurs. The callback on the source is of the #GPollableSourceFunc type. As with g_pollable_output_stream_is_writable(), it is possible that the stream may not actually be writable even after the source triggers, so you should use g_pollable_output_stream_write_nonblocking() rather than g_output_stream_write() from the callback. The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. a new #GSource a #GPollableOutputStream. a #GCancellable, or %NULL Checks if @stream can be written. Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to g_output_stream_write() after this returns %TRUE would still block. To guarantee non-blocking behavior, you should always use g_pollable_output_stream_write_nonblocking(), which will return a %G_IO_ERROR_WOULD_BLOCK error rather than blocking. The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. %TRUE if @stream is writable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_output_stream_is_writable() returning %TRUE, and the next attempt to write will return the error. a #GPollableOutputStream. Attempts to write up to @count bytes from @buffer to @stream, as with g_output_stream_write(). If @stream is not currently writable, this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can use g_pollable_output_stream_create_source() to create a #GSource that will be triggered when @stream is writable. Note that since this method never blocks, you cannot actually use @cancellable to cancel it. However, it will return an error if @cancellable has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled. Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying transports like D/TLS require that you re-send the same @buffer and @count in the next write call. The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. the number of bytes written, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). a #GPollableOutputStream a buffer to write data from the number of bytes you want to write a #GCancellable, or %NULL Attempts to write the bytes contained in the @n_vectors @vectors to @stream, as with g_output_stream_writev(). If @stream is not currently writable, this will immediately return %@G_POLLABLE_RETURN_WOULD_BLOCK, and you can use g_pollable_output_stream_create_source() to create a #GSource that will be triggered when @stream is writable. @error will *not* be set in that case. Note that since this method never blocks, you cannot actually use @cancellable to cancel it. However, it will return an error if @cancellable has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled. Also note that if %G_POLLABLE_RETURN_WOULD_BLOCK is returned some underlying transports like D/TLS require that you re-send the same @vectors and @n_vectors in the next write call. The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK if the stream is not currently writable (and @error is *not* set), or %G_POLLABLE_RETURN_FAILED if there was an error in which case @error will be set. a #GPollableOutputStream the buffer containing the #GOutputVectors to write. the number of vectors to write location to store the number of bytes that were written to the stream a #GCancellable, or %NULL The interface for pollable output streams. The default implementation of @can_poll always returns %TRUE. The default implementation of @write_nonblocking calls g_pollable_output_stream_is_writable(), and then calls g_output_stream_write() if it returns %TRUE. This means you only need to override it if it is possible that your @is_writable implementation may return %TRUE when the stream is not actually writable. The default implementation of @writev_nonblocking calls g_pollable_output_stream_write_nonblocking() for each vector, and converts its return value and error (if set) to a #GPollableReturn. You should override this where possible to avoid having to allocate a #GError to return %G_IO_ERROR_WOULD_BLOCK. The parent interface. Checks if the #GPollableOutputStream instance is actually pollable %TRUE if @stream is pollable, %FALSE if not. a #GPollableOutputStream. Checks if the stream is writable %TRUE if @stream is writable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_output_stream_is_writable() returning %TRUE, and the next attempt to write will return the error. a #GPollableOutputStream. Creates a #GSource to poll the stream a new #GSource a #GPollableOutputStream. a #GCancellable, or %NULL Does a non-blocking write or returns %G_IO_ERROR_WOULD_BLOCK the number of bytes written, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). a #GPollableOutputStream a buffer to write data from the number of bytes you want to write Does a vectored non-blocking write, or returns %G_POLLABLE_RETURN_WOULD_BLOCK %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK if the stream is not currently writable (and @error is *not* set), or %G_POLLABLE_RETURN_FAILED if there was an error in which case @error will be set. a #GPollableOutputStream the buffer containing the #GOutputVectors to write. the number of vectors to write location to store the number of bytes that were written to the stream Return value for various IO operations that signal errors via the return value and not necessarily via a #GError. This enum exists to be able to return errors to callers without having to allocate a #GError. Allocating #GErrors can be quite expensive for regularly happening errors like %G_IO_ERROR_WOULD_BLOCK. In case of %G_POLLABLE_RETURN_FAILED a #GError should be set for the operation to give details about the error that happened. Generic error condition for when an operation fails. The operation was successfully finished. The operation would block. This is the function type of the callback used for the #GSource returned by g_pollable_input_stream_create_source() and g_pollable_output_stream_create_source(). it should return %FALSE if the source should be removed. the #GPollableInputStream or #GPollableOutputStream data passed in by the user. `GPowerProfileMonitor` makes it possible for applications as well as OS components to monitor system power profiles and act upon them. It currently only exports whether the system is in “Power Saver” mode (known as “Low Power” mode on some systems). When in “Low Power” mode, it is recommended that applications: - disable automatic downloads; - reduce the rate of refresh from online sources such as calendar or email synchronisation; - reduce the use of expensive visual effects. It is also likely that OS components providing services to applications will lower their own background activity, for the sake of the system. There are a variety of tools that exist for power consumption analysis, but those usually depend on the OS and hardware used. On Linux, one could use `upower` to monitor the battery discharge rate, `powertop` to check on the background activity or activity at all), `sysprof` to inspect CPU usage, and `intel_gpu_time` to profile GPU usage. Don’t forget to disconnect the [signal@GObject.Object::notify] signal for [property@Gio.PowerProfileMonitor:power-saver-enabled], and unref the `GPowerProfileMonitor` itself when exiting. Gets a reference to the default #GPowerProfileMonitor for the system. a new reference to the default #GPowerProfileMonitor Gets whether the system is in “Power Saver” mode. You are expected to listen to the #GPowerProfileMonitor::notify::power-saver-enabled signal to know when the profile has changed. Whether the system is in “Power Saver” mode. a #GPowerProfileMonitor Whether “Power Saver” mode is enabled on the system. The virtual function table for #GPowerProfileMonitor. The parent interface. A `GPropertyAction` is a way to get a [iface@Gio.Action] with a state value reflecting and controlling the value of a [class@GObject.Object] property. The state of the action will correspond to the value of the property. Changing it will change the property (assuming the requested value matches the requirements as specified in the [type@GObject.ParamSpec]). Only the most common types are presently supported. Booleans are mapped to booleans, strings to strings, signed/unsigned integers to int32/uint32 and floats and doubles to doubles. If the property is an enum then the state will be string-typed and conversion will automatically be performed between the enum value and ‘nick’ string as per the [type@GObject.EnumValue] table. Flags types are not currently supported. Properties of object types, boxed types and pointer types are not supported and probably never will be. Properties of [type@GLib.Variant] types are not currently supported. If the property is boolean-valued then the action will have a `NULL` parameter type, and activating the action (with no parameter) will toggle the value of the property. In all other cases, the parameter type will correspond to the type of the property. The general idea here is to reduce the number of locations where a particular piece of state is kept (and therefore has to be synchronised between). `GPropertyAction` does not have a separate state that is kept in sync with the property value — its state is the property value. For example, it might be useful to create a [iface@Gio.Action] corresponding to the `visible-child-name` property of a [`GtkStack`](https://docs.gtk.org/gtk4/class.Stack.html) so that the current page can be switched from a menu. The active radio indication in the menu is then directly determined from the active page of the `GtkStack`. An anti-example would be binding the `active-id` property on a [`GtkComboBox`](https://docs.gtk.org/gtk4/class.ComboBox.html). This is because the state of the combo box itself is probably uninteresting and is actually being used to control something else. Another anti-example would be to bind to the `visible-child-name` property of a [`GtkStack`](https://docs.gtk.org/gtk4/class.Stack.html) if this value is actually stored in [class@Gio.Settings]. In that case, the real source of the value is* [class@Gio.Settings]. If you want a [iface@Gio.Action] to control a setting stored in [class@Gio.Settings], see [method@Gio.Settings.create_action] instead, and possibly combine its use with [method@Gio.Settings.bind]. Creates a #GAction corresponding to the value of property @property_name on @object. The property must be existent and readable and writable (and not construct-only). This function takes a reference on @object and doesn't release it until the action is destroyed. a new #GPropertyAction the name of the action to create the object that has the property to wrap the name of the property If @action is currently enabled. If the action is disabled then calls to g_action_activate() and g_action_change_state() have no effect. If %TRUE, the state of the action will be the negation of the property value, provided the property is boolean. The name of the action. This is mostly meaningful for identifying the action once it has been added to a #GActionMap. The object to wrap a property on. The object must be a non-%NULL #GObject with properties. The type of the parameter that must be given when activating the action. The name of the property to wrap on the object. The property must exist on the passed-in object and it must be readable and writable (and not construct-only). The state of the action, or %NULL if the action is stateless. The #GVariantType of the state that the action has, or %NULL if the action is stateless. A `GProxy` handles connecting to a remote host via a given type of proxy server. It is implemented by the `gio-proxy` extension point. The extensions are named after their proxy protocol name. As an example, a SOCKS5 proxy implementation can be retrieved with the name `socks5` using the function [method@Gio.IOExtensionPoint.get_extension_by_name]. Find the `gio-proxy` extension point for a proxy implementation that supports the specified protocol. return a #GProxy or NULL if protocol is not supported. the proxy protocol name (e.g. http, socks, etc) Given @connection to communicate with a proxy (eg, a #GSocketConnection that is connected to the proxy server), this does the necessary handshake to connect to @proxy_address, and if required, wraps the #GIOStream to handle proxy payload. a #GIOStream that will replace @connection. This might be the same as @connection, in which case a reference will be added. a #GProxy a #GIOStream a #GProxyAddress a #GCancellable Asynchronous version of g_proxy_connect(). a #GProxy a #GIOStream a #GProxyAddress a #GCancellable a #GAsyncReadyCallback callback data See g_proxy_connect(). a #GIOStream. a #GProxy a #GAsyncResult Some proxy protocols expect to be passed a hostname, which they will resolve to an IP address themselves. Others, like SOCKS4, do not allow this. This function will return %FALSE if @proxy is implementing such a protocol. When %FALSE is returned, the caller should resolve the destination hostname first, and then pass a #GProxyAddress containing the stringified IP address to g_proxy_connect() or g_proxy_connect_async(). %TRUE if hostname resolution is supported. a #GProxy Given @connection to communicate with a proxy (eg, a #GSocketConnection that is connected to the proxy server), this does the necessary handshake to connect to @proxy_address, and if required, wraps the #GIOStream to handle proxy payload. a #GIOStream that will replace @connection. This might be the same as @connection, in which case a reference will be added. a #GProxy a #GIOStream a #GProxyAddress a #GCancellable Asynchronous version of g_proxy_connect(). a #GProxy a #GIOStream a #GProxyAddress a #GCancellable a #GAsyncReadyCallback callback data See g_proxy_connect(). a #GIOStream. a #GProxy a #GAsyncResult Some proxy protocols expect to be passed a hostname, which they will resolve to an IP address themselves. Others, like SOCKS4, do not allow this. This function will return %FALSE if @proxy is implementing such a protocol. When %FALSE is returned, the caller should resolve the destination hostname first, and then pass a #GProxyAddress containing the stringified IP address to g_proxy_connect() or g_proxy_connect_async(). %TRUE if hostname resolution is supported. a #GProxy A [class@Gio.InetSocketAddress] representing a connection via a proxy server. Creates a new #GProxyAddress for @inetaddr with @protocol that should tunnel through @dest_hostname and @dest_port. (Note that this method doesn't set the #GProxyAddress:uri or #GProxyAddress:destination-protocol fields; use g_object_new() directly if you want to set those.) a new #GProxyAddress The proxy server #GInetAddress. The proxy server port. The proxy protocol to support, in lower case (e.g. socks, http). The destination hostname the proxy should tunnel to. The destination port to tunnel to. The username to authenticate to the proxy server (or %NULL). The password to authenticate to the proxy server (or %NULL). Gets @proxy's destination hostname; that is, the name of the host that will be connected to via the proxy, not the name of the proxy itself. the @proxy's destination hostname a #GProxyAddress Gets @proxy's destination port; that is, the port on the destination host that will be connected to via the proxy, not the port number of the proxy itself. the @proxy's destination port a #GProxyAddress Gets the protocol that is being spoken to the destination server; eg, "http" or "ftp". the @proxy's destination protocol a #GProxyAddress Gets @proxy's password. the @proxy's password a #GProxyAddress Gets @proxy's protocol. eg, "socks" or "http" the @proxy's protocol a #GProxyAddress Gets the proxy URI that @proxy was constructed from. the @proxy's URI, or %NULL if unknown a #GProxyAddress Gets @proxy's username. the @proxy's username a #GProxyAddress The proxy destination hostname. The proxy destination port. The protocol being spoke to the destination host, or %NULL if the #GProxyAddress doesn't know. The proxy password. The proxy protocol. The URI string that the proxy was constructed from (or %NULL if the creator didn't specify this). The proxy username. Class structure for #GProxyAddress. `GProxyAddressEnumerator` is a wrapper around [class@Gio.SocketAddressEnumerator] which takes the [class@Gio.SocketAddress] instances returned by the [class@Gio.SocketAddressEnumerator] and wraps them in [class@Gio.ProxyAddress] instances, using the given [property@Gio.ProxyAddressEnumerator:proxy-resolver]. This enumerator will be returned (for example, by [method@Gio.SocketConnectable.enumerate]) as appropriate when a proxy is configured; there should be no need to manually wrap a [class@Gio.SocketAddressEnumerator] instance with one. The connectable being enumerated. The default port to use if #GProxyAddressEnumerator:uri does not specify one. The proxy resolver to use. The destination URI. Use `none://` for a generic socket. Class structure for #GProxyAddressEnumerator. Provides an interface for handling proxy connection and payload. The parent interface. Connect to proxy server and wrap (if required) the #connection to handle payload. a #GIOStream that will replace @connection. This might be the same as @connection, in which case a reference will be added. a #GProxy a #GIOStream a #GProxyAddress a #GCancellable Same as connect() but asynchronous. a #GProxy a #GIOStream a #GProxyAddress a #GCancellable a #GAsyncReadyCallback callback data Returns the result of connect_async() a #GIOStream. a #GProxy a #GAsyncResult Returns whether the proxy supports hostname lookups. %TRUE if hostname resolution is supported. a #GProxy `GProxyResolver` provides synchronous and asynchronous network proxy resolution. `GProxyResolver` is used within [class@Gio.SocketClient] through the method [method@Gio.SocketConnectable.proxy_enumerate]. Implementations of `GProxyResolver` based on [libproxy](https://github.com/libproxy/libproxy) and GNOME settings can be found in [glib-networking](https://gitlab.gnome.org/GNOME/glib-networking). GIO comes with an implementation for use inside Flatpak portals. Gets the default #GProxyResolver for the system. the default #GProxyResolver, which will be a dummy object if no proxy resolver is available Checks if @resolver can be used on this system. (This is used internally; g_proxy_resolver_get_default() will only return a proxy resolver that returns %TRUE for this method.) %TRUE if @resolver is supported. a #GProxyResolver Looks into the system proxy configuration to determine what proxy, if any, to use to connect to @uri. The returned proxy URIs are of the form `<protocol>://[user[:password]@]host[:port]` or `direct://`, where `<protocol>` could be http, rtsp, socks or other proxying protocol. If you don't know what network protocol is being used on the socket, you should use `none` as the URI protocol. In this case, the resolver might still return a generic proxy type (such as SOCKS), but would not return protocol-specific proxy types (such as http). `direct://` is used when no proxy is needed. Direct connection should not be attempted unless it is part of the returned array of proxies. A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). a #GProxyResolver a URI representing the destination to connect to a #GCancellable, or %NULL Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more details. a #GProxyResolver a URI representing the destination to connect to a #GCancellable, or %NULL callback to call after resolution completes data for @callback Call this function to obtain the array of proxy URIs when g_proxy_resolver_lookup_async() is complete. See g_proxy_resolver_lookup() for more details. A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). a #GProxyResolver the result passed to your #GAsyncReadyCallback Checks if @resolver can be used on this system. (This is used internally; g_proxy_resolver_get_default() will only return a proxy resolver that returns %TRUE for this method.) %TRUE if @resolver is supported. a #GProxyResolver Looks into the system proxy configuration to determine what proxy, if any, to use to connect to @uri. The returned proxy URIs are of the form `<protocol>://[user[:password]@]host[:port]` or `direct://`, where `<protocol>` could be http, rtsp, socks or other proxying protocol. If you don't know what network protocol is being used on the socket, you should use `none` as the URI protocol. In this case, the resolver might still return a generic proxy type (such as SOCKS), but would not return protocol-specific proxy types (such as http). `direct://` is used when no proxy is needed. Direct connection should not be attempted unless it is part of the returned array of proxies. A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). a #GProxyResolver a URI representing the destination to connect to a #GCancellable, or %NULL Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more details. a #GProxyResolver a URI representing the destination to connect to a #GCancellable, or %NULL callback to call after resolution completes data for @callback Call this function to obtain the array of proxy URIs when g_proxy_resolver_lookup_async() is complete. See g_proxy_resolver_lookup() for more details. A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). a #GProxyResolver the result passed to your #GAsyncReadyCallback The virtual function table for #GProxyResolver. The parent interface. the virtual function pointer for g_proxy_resolver_is_supported() %TRUE if @resolver is supported. a #GProxyResolver the virtual function pointer for g_proxy_resolver_lookup() A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). a #GProxyResolver a URI representing the destination to connect to a #GCancellable, or %NULL the virtual function pointer for g_proxy_resolver_lookup_async() a #GProxyResolver a URI representing the destination to connect to a #GCancellable, or %NULL callback to call after resolution completes data for @callback the virtual function pointer for g_proxy_resolver_lookup_finish() A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). a #GProxyResolver the result passed to your #GAsyncReadyCallback Changes the size of the memory block pointed to by @data to @size bytes. The function should have the same semantics as realloc(). a pointer to the reallocated memory memory block to reallocate size to reallocate @data to The `GRemoteActionGroup` interface is implemented by [iface@Gio.ActionGroup] instances that either transmit action invocations to other processes or receive action invocations in the local process from other processes. The interface has `_full` variants of the two methods on [iface@Gio.ActionGroup] used to activate actions: [method@Gio.ActionGroup.activate_action] and [method@Gio.ActionGroup.change_action_state]. These variants allow a ‘platform data’ [struct@GLib.Variant] to be specified: a dictionary providing context for the action invocation (for example: timestamps, startup notification IDs, etc). [class@Gio.DBusActionGroup] implements `GRemoteActionGroup`. This provides a mechanism to send platform data for action invocations over D-Bus. Additionally, [method@Gio.DBusConnection.export_action_group] will check if the exported [iface@Gio.ActionGroup] implements `GRemoteActionGroup` and use the `_full` variants of the calls if available. This provides a mechanism by which to receive platform data for action invocations that arrive by way of D-Bus. Activates the remote action. This is the same as g_action_group_activate_action() except that it allows for provision of "platform data" to be sent along with the activation request. This typically contains details such as the user interaction timestamp or startup notification information. @platform_data must be non-%NULL and must have the type %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. a #GDBusActionGroup the name of the action to activate the optional parameter to the activation the platform data to send Changes the state of a remote action. This is the same as g_action_group_change_action_state() except that it allows for provision of "platform data" to be sent along with the state change request. This typically contains details such as the user interaction timestamp or startup notification information. @platform_data must be non-%NULL and must have the type %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. a #GRemoteActionGroup the name of the action to change the state of the new requested value for the state the platform data to send Activates the remote action. This is the same as g_action_group_activate_action() except that it allows for provision of "platform data" to be sent along with the activation request. This typically contains details such as the user interaction timestamp or startup notification information. @platform_data must be non-%NULL and must have the type %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. a #GDBusActionGroup the name of the action to activate the optional parameter to the activation the platform data to send Changes the state of a remote action. This is the same as g_action_group_change_action_state() except that it allows for provision of "platform data" to be sent along with the state change request. This typically contains details such as the user interaction timestamp or startup notification information. @platform_data must be non-%NULL and must have the type %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. a #GRemoteActionGroup the name of the action to change the state of the new requested value for the state the platform data to send The virtual function table for #GRemoteActionGroup. the virtual function pointer for g_remote_action_group_activate_action_full() a #GDBusActionGroup the name of the action to activate the optional parameter to the activation the platform data to send the virtual function pointer for g_remote_action_group_change_action_state_full() a #GRemoteActionGroup the name of the action to change the state of the new requested value for the state the platform data to send The object that handles DNS resolution. Use [func@Gio.Resolver.get_default] to get the default resolver. `GResolver` provides cancellable synchronous and asynchronous DNS resolution, for hostnames ([method@Gio.Resolver.lookup_by_address], [method@Gio.Resolver.lookup_by_name] and their async variants) and SRV (service) records ([method@Gio.Resolver.lookup_service]). [class@Gio.NetworkAddress] and [class@Gio.NetworkService] provide wrappers around `GResolver` functionality that also implement [iface@Gio.SocketConnectable], making it easy to connect to a remote host/service. The default resolver (see [func@Gio.Resolver.get_default]) has a timeout of 30s set on it since GLib 2.78. Earlier versions of GLib did not support resolver timeouts. This is an abstract type; subclasses of it implement different resolvers for different platforms and situations. Frees @addresses (which should be the return value from g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()). (This is a convenience method; you can also simply free the results by hand.) a #GList of #GInetAddress Frees @targets (which should be the return value from g_resolver_lookup_service() or g_resolver_lookup_service_finish()). (This is a convenience method; you can also simply free the results by hand.) a #GList of #GSrvTarget Gets the default #GResolver. You should unref it when you are done with it. #GResolver may use its reference count as a hint about how many threads it should allocate for concurrent DNS resolutions. the default #GResolver. Synchronously reverse-resolves @address to determine its associated hostname. If the DNS resolution fails, @error (if non-%NULL) will be set to a value from #GResolverError. If @cancellable is non-%NULL, it can be used to cancel the operation, in which case @error (if non-%NULL) will be set to %G_IO_ERROR_CANCELLED. a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. a #GResolver the address to reverse-resolve a #GCancellable, or %NULL Begins asynchronously reverse-resolving @address to determine its associated hostname, and eventually calls @callback, which must call g_resolver_lookup_by_address_finish() to get the final result. a #GResolver the address to reverse-resolve a #GCancellable, or %NULL callback to call after resolution completes data for @callback Retrieves the result of a previous call to g_resolver_lookup_by_address_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. a #GResolver the result passed to your #GAsyncReadyCallback Synchronously resolves @hostname to determine its associated IP address(es). @hostname may be an ASCII-only or UTF-8 hostname, or the textual form of an IP address (in which case this just becomes a wrapper around g_inet_address_new_from_string()). On success, g_resolver_lookup_by_name() will return a non-empty #GList of #GInetAddress, sorted in order of preference and guaranteed to not contain duplicates. That is, if using the result to connect to @hostname, you should attempt to connect to the first address first, then the second if the first fails, etc. If you are using the result to listen on a socket, it is appropriate to add each result using e.g. g_socket_listener_add_address(). If the DNS resolution fails, @error (if non-%NULL) will be set to a value from #GResolverError and %NULL will be returned. If @cancellable is non-%NULL, it can be used to cancel the operation, in which case @error (if non-%NULL) will be set to %G_IO_ERROR_CANCELLED. If you are planning to connect to a socket on the resolved IP address, it may be easier to create a #GNetworkAddress and use its #GSocketConnectable interface. a non-empty #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) a #GResolver the hostname to look up a #GCancellable, or %NULL Begins asynchronously resolving @hostname to determine its associated IP address(es), and eventually calls @callback, which must call g_resolver_lookup_by_name_finish() to get the result. See g_resolver_lookup_by_name() for more details. a #GResolver the hostname to look up the address of a #GCancellable, or %NULL callback to call after resolution completes data for @callback Retrieves the result of a call to g_resolver_lookup_by_name_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. a #GResolver the result passed to your #GAsyncReadyCallback This differs from g_resolver_lookup_by_name() in that you can modify the lookup behavior with @flags. For example this can be used to limit results with %G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY. a non-empty #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) a #GResolver the hostname to look up extra #GResolverNameLookupFlags for the lookup a #GCancellable, or %NULL Begins asynchronously resolving @hostname to determine its associated IP address(es), and eventually calls @callback, which must call g_resolver_lookup_by_name_with_flags_finish() to get the result. See g_resolver_lookup_by_name() for more details. a #GResolver the hostname to look up the address of extra #GResolverNameLookupFlags for the lookup a #GCancellable, or %NULL callback to call after resolution completes data for @callback Retrieves the result of a call to g_resolver_lookup_by_name_with_flags_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. a #GResolver the result passed to your #GAsyncReadyCallback Synchronously performs a DNS record lookup for the given @rrname and returns a list of records as #GVariant tuples. See #GResolverRecordType for information on what the records contain for each @record_type. If the DNS resolution fails, @error (if non-%NULL) will be set to a value from #GResolverError and %NULL will be returned. If @cancellable is non-%NULL, it can be used to cancel the operation, in which case @error (if non-%NULL) will be set to %G_IO_ERROR_CANCELLED. a non-empty #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) a #GResolver the DNS name to look up the record for the type of DNS record to look up a #GCancellable, or %NULL Begins asynchronously performing a DNS lookup for the given @rrname, and eventually calls @callback, which must call g_resolver_lookup_records_finish() to get the final result. See g_resolver_lookup_records() for more details. a #GResolver the DNS name to look up the record for the type of DNS record to look up a #GCancellable, or %NULL callback to call after resolution completes data for @callback Retrieves the result of a previous call to g_resolver_lookup_records_async(). Returns a non-empty list of records as #GVariant tuples. See #GResolverRecordType for information on what the records contain. If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. a non-empty #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) a #GResolver the result passed to your #GAsyncReadyCallback Retrieves the result of a previous call to g_resolver_lookup_service_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. a non-empty #GList of #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more details. a #GResolver the result passed to your #GAsyncReadyCallback Get the timeout applied to all resolver lookups. See #GResolver:timeout. the resolver timeout, in milliseconds, or `0` for no timeout a #GResolver Synchronously reverse-resolves @address to determine its associated hostname. If the DNS resolution fails, @error (if non-%NULL) will be set to a value from #GResolverError. If @cancellable is non-%NULL, it can be used to cancel the operation, in which case @error (if non-%NULL) will be set to %G_IO_ERROR_CANCELLED. a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. a #GResolver the address to reverse-resolve a #GCancellable, or %NULL Begins asynchronously reverse-resolving @address to determine its associated hostname, and eventually calls @callback, which must call g_resolver_lookup_by_address_finish() to get the final result. a #GResolver the address to reverse-resolve a #GCancellable, or %NULL callback to call after resolution completes data for @callback Retrieves the result of a previous call to g_resolver_lookup_by_address_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. a #GResolver the result passed to your #GAsyncReadyCallback Synchronously resolves @hostname to determine its associated IP address(es). @hostname may be an ASCII-only or UTF-8 hostname, or the textual form of an IP address (in which case this just becomes a wrapper around g_inet_address_new_from_string()). On success, g_resolver_lookup_by_name() will return a non-empty #GList of #GInetAddress, sorted in order of preference and guaranteed to not contain duplicates. That is, if using the result to connect to @hostname, you should attempt to connect to the first address first, then the second if the first fails, etc. If you are using the result to listen on a socket, it is appropriate to add each result using e.g. g_socket_listener_add_address(). If the DNS resolution fails, @error (if non-%NULL) will be set to a value from #GResolverError and %NULL will be returned. If @cancellable is non-%NULL, it can be used to cancel the operation, in which case @error (if non-%NULL) will be set to %G_IO_ERROR_CANCELLED. If you are planning to connect to a socket on the resolved IP address, it may be easier to create a #GNetworkAddress and use its #GSocketConnectable interface. a non-empty #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) a #GResolver the hostname to look up a #GCancellable, or %NULL Begins asynchronously resolving @hostname to determine its associated IP address(es), and eventually calls @callback, which must call g_resolver_lookup_by_name_finish() to get the result. See g_resolver_lookup_by_name() for more details. a #GResolver the hostname to look up the address of a #GCancellable, or %NULL callback to call after resolution completes data for @callback Retrieves the result of a call to g_resolver_lookup_by_name_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. a #GResolver the result passed to your #GAsyncReadyCallback This differs from g_resolver_lookup_by_name() in that you can modify the lookup behavior with @flags. For example this can be used to limit results with %G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY. a non-empty #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) a #GResolver the hostname to look up extra #GResolverNameLookupFlags for the lookup a #GCancellable, or %NULL Begins asynchronously resolving @hostname to determine its associated IP address(es), and eventually calls @callback, which must call g_resolver_lookup_by_name_with_flags_finish() to get the result. See g_resolver_lookup_by_name() for more details. a #GResolver the hostname to look up the address of extra #GResolverNameLookupFlags for the lookup a #GCancellable, or %NULL callback to call after resolution completes data for @callback Retrieves the result of a call to g_resolver_lookup_by_name_with_flags_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. a #GResolver the result passed to your #GAsyncReadyCallback Synchronously performs a DNS record lookup for the given @rrname and returns a list of records as #GVariant tuples. See #GResolverRecordType for information on what the records contain for each @record_type. If the DNS resolution fails, @error (if non-%NULL) will be set to a value from #GResolverError and %NULL will be returned. If @cancellable is non-%NULL, it can be used to cancel the operation, in which case @error (if non-%NULL) will be set to %G_IO_ERROR_CANCELLED. a non-empty #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) a #GResolver the DNS name to look up the record for the type of DNS record to look up a #GCancellable, or %NULL Begins asynchronously performing a DNS lookup for the given @rrname, and eventually calls @callback, which must call g_resolver_lookup_records_finish() to get the final result. See g_resolver_lookup_records() for more details. a #GResolver the DNS name to look up the record for the type of DNS record to look up a #GCancellable, or %NULL callback to call after resolution completes data for @callback Retrieves the result of a previous call to g_resolver_lookup_records_async(). Returns a non-empty list of records as #GVariant tuples. See #GResolverRecordType for information on what the records contain. If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. a non-empty #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) a #GResolver the result passed to your #GAsyncReadyCallback Synchronously performs a DNS SRV lookup for the given @service and @protocol in the given @domain and returns an array of #GSrvTarget. @domain may be an ASCII-only or UTF-8 hostname. Note also that the @service and @protocol arguments do not include the leading underscore that appears in the actual DNS entry. On success, g_resolver_lookup_service() will return a non-empty #GList of #GSrvTarget, sorted in order of preference. (That is, you should attempt to connect to the first target first, then the second if the first fails, etc.) If the DNS resolution fails, @error (if non-%NULL) will be set to a value from #GResolverError and %NULL will be returned. If @cancellable is non-%NULL, it can be used to cancel the operation, in which case @error (if non-%NULL) will be set to %G_IO_ERROR_CANCELLED. If you are planning to connect to the service, it is usually easier to create a #GNetworkService and use its #GSocketConnectable interface. a non-empty #GList of #GSrvTarget, or %NULL on error. You must free each of the targets and the list when you are done with it. (You can use g_resolver_free_targets() to do this.) a #GResolver the service type to look up (eg, "ldap") the networking protocol to use for @service (eg, "tcp") the DNS domain to look up the service in a #GCancellable, or %NULL Begins asynchronously performing a DNS SRV lookup for the given @service and @protocol in the given @domain, and eventually calls @callback, which must call g_resolver_lookup_service_finish() to get the final result. See g_resolver_lookup_service() for more details. a #GResolver the service type to look up (eg, "ldap") the networking protocol to use for @service (eg, "tcp") the DNS domain to look up the service in a #GCancellable, or %NULL callback to call after resolution completes data for @callback Retrieves the result of a previous call to g_resolver_lookup_service_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. a non-empty #GList of #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more details. a #GResolver the result passed to your #GAsyncReadyCallback Sets @resolver to be the application's default resolver (reffing @resolver, and unreffing the previous default resolver, if any). Future calls to g_resolver_get_default() will return this resolver. This can be used if an application wants to perform any sort of DNS caching or "pinning"; it can implement its own #GResolver that calls the original default resolver for DNS operations, and implements its own cache policies on top of that, and then set itself as the default resolver for all later code to use. the new default #GResolver Set the timeout applied to all resolver lookups. See #GResolver:timeout. a #GResolver timeout in milliseconds, or `0` for no timeouts The timeout applied to all resolver lookups, in milliseconds. This may be changed through the lifetime of the #GResolver. The new value will apply to any lookups started after the change, but not to any already-ongoing lookups. If this is `0`, no timeout is applied to lookups. No timeout was applied to lookups before this property was added in GLib 2.78. Emitted when the resolver notices that the system resolver configuration has changed. a non-empty #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) a #GResolver the hostname to look up a #GCancellable, or %NULL a #GResolver the hostname to look up the address of a #GCancellable, or %NULL callback to call after resolution completes data for @callback a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. a #GResolver the result passed to your #GAsyncReadyCallback a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. a #GResolver the address to reverse-resolve a #GCancellable, or %NULL a #GResolver the address to reverse-resolve a #GCancellable, or %NULL callback to call after resolution completes data for @callback a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. a #GResolver the result passed to your #GAsyncReadyCallback a non-empty #GList of #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more details. a #GResolver the result passed to your #GAsyncReadyCallback a non-empty #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) a #GResolver the DNS name to look up the record for the type of DNS record to look up a #GCancellable, or %NULL a #GResolver the DNS name to look up the record for the type of DNS record to look up a #GCancellable, or %NULL callback to call after resolution completes data for @callback a non-empty #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) a #GResolver the result passed to your #GAsyncReadyCallback a #GResolver the hostname to look up the address of extra #GResolverNameLookupFlags for the lookup a #GCancellable, or %NULL callback to call after resolution completes data for @callback a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. a #GResolver the result passed to your #GAsyncReadyCallback a non-empty #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) a #GResolver the hostname to look up extra #GResolverNameLookupFlags for the lookup a #GCancellable, or %NULL An error code used with %G_RESOLVER_ERROR in a #GError returned from a #GResolver routine. the requested name/address/service was not found the requested information could not be looked up due to a network error or similar problem unknown error Gets the #GResolver Error Quark. a #GQuark. Flags to modify lookup behavior. default behavior (same as g_resolver_lookup_by_name()) only resolve ipv4 addresses only resolve ipv6 addresses The type of record that g_resolver_lookup_records() or g_resolver_lookup_records_async() should retrieve. The records are returned as lists of #GVariant tuples. Each record type has different values in the variant tuples returned. %G_RESOLVER_RECORD_SRV records are returned as variants with the signature `(qqqs)`, containing a `guint16` with the priority, a `guint16` with the weight, a `guint16` with the port, and a string of the hostname. %G_RESOLVER_RECORD_MX records are returned as variants with the signature `(qs)`, representing a `guint16` with the preference, and a string containing the mail exchanger hostname. %G_RESOLVER_RECORD_TXT records are returned as variants with the signature `(as)`, representing an array of the strings in the text record. Note: Most TXT records only contain a single string, but [RFC 1035](https://tools.ietf.org/html/rfc1035#section-3.3.14) does allow a record to contain multiple strings. The RFC which defines the interpretation of a specific TXT record will likely require concatenation of multiple strings if they are present, as with [RFC 7208](https://tools.ietf.org/html/rfc7208#section-3.3). %G_RESOLVER_RECORD_SOA records are returned as variants with the signature `(ssuuuuu)`, representing a string containing the primary name server, a string containing the administrator, the serial as a `guint32`, the refresh interval as a `guint32`, the retry interval as a `guint32`, the expire timeout as a `guint32`, and the TTL as a `guint32`. %G_RESOLVER_RECORD_NS records are returned as variants with the signature `(s)`, representing a string of the hostname of the name server. look up DNS SRV records for a domain look up DNS MX records for a domain look up DNS TXT records for a name look up DNS SOA records for a zone look up DNS NS records for a domain Applications and libraries often contain binary or textual data that is really part of the application, rather than user data. For instance [`GtkBuilder`](https://docs.gtk.org/gtk4/class.Builder.html) `.ui` files, splashscreen images, [class@Gio.Menu] markup XML, CSS files, icons, etc. These are often shipped as files in `$datadir/appname`, or manually included as literal strings in the code. The `GResource` API and the [`glib-compile-resources`](glib-compile-resources.html) program provide a convenient and efficient alternative to this which has some nice properties. You maintain the files as normal files, so it’s easy to edit them, but during the build the files are combined into a binary bundle that is linked into the executable. This means that loading the resource files are efficient (as they are already in memory, shared with other instances) and simple (no need to check for things like I/O errors or locate the files in the filesystem). It also makes it easier to create relocatable applications. Resource files can also be marked as compressed. Such files will be included in the resource bundle in a compressed form, but will be automatically uncompressed when the resource is used. This is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away. Resource files can also be marked to be preprocessed, by setting the value of the `preprocess` attribute to a comma-separated list of preprocessing options. The only options currently supported are: - `xml-stripblanks` which will use the [`xmllint`](man:xmllint(1)) command to strip ignorable whitespace from the XML file. For this to work, the `XMLLINT` environment variable must be set to the full path to the xmllint executable, or xmllint must be in the `PATH`; otherwise the preprocessing step is skipped. - `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the `gdk-pixbuf-pixdata` command to convert images to the [`GdkPixdata`](https://docs.gtk.org/gdk-pixbuf/class.Pixdata.html) format, which allows you to create pixbufs directly using the data inside the resource file, rather than an (uncompressed) copy of it. For this, the `gdk-pixbuf-pixdata` program must be in the `PATH`, or the `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to the `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will abort. `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as `GResource` supports embedding modern image formats just as well. Instead of using it, embed a PNG or SVG file in your `GResource`. - `json-stripblanks` which will use the [`json-glib-format`](man:json-glib-format(1)) command to strip ignorable whitespace from the JSON file. For this to work, the `JSON_GLIB_FORMAT` environment variable must be set to the full path to the `json-glib-format` executable, or it must be in the `PATH`; otherwise the preprocessing step is skipped. In addition, at least version 1.6 of `json-glib-format` is required. Resource files will be exported in the `GResource` namespace using the combination of the given `prefix` and the filename from the `file` element. The `alias` attribute can be used to alter the filename to expose them at a different location in the resource namespace. Typically, this is used to include files from a different source directory without exposing the source directory in the resource namespace, as in the example below. Resource bundles are created by the [`glib-compile-resources`](glib-compile-resources.html) program which takes an XML file that describes the bundle, and a set of files that the XML references. These are combined into a binary resource bundle. An example resource description: ```xml <?xml version="1.0" encoding="UTF-8"?> <gresources> <gresource prefix="/org/gtk/Example"> <file>data/splashscreen.png</file> <file compressed="true">dialog.ui</file> <file preprocess="xml-stripblanks">menumarkup.xml</file> <file alias="example.css">data/example.css</file> </gresource> </gresources> ``` This will create a resource bundle with the following files: ``` /org/gtk/Example/data/splashscreen.png /org/gtk/Example/dialog.ui /org/gtk/Example/menumarkup.xml /org/gtk/Example/example.css ``` Note that all resources in the process share the same namespace, so use Java-style path prefixes (like in the above example) to avoid conflicts. You can then use [`glib-compile-resources`](glib-compile-resources.html) to compile the XML to a binary bundle that you can load with [func@Gio.Resource.load]. However, it’s more common to use the `--generate-source` and `--generate-header` arguments to create a source file and header to link directly into your application. This will generate `get_resource()`, `register_resource()` and `unregister_resource()` functions, prefixed by the `--c-name` argument passed to [`glib-compile-resources`](glib-compile-resources.html). `get_resource()` returns the generated `GResource` object. The register and unregister functions register the resource so its files can be accessed using [func@Gio.resources_lookup_data]. Once a `GResource` has been created and registered all the data in it can be accessed globally in the process by using API calls like [func@Gio.resources_open_stream] to stream the data or [func@Gio.resources_lookup_data] to get a direct pointer to the data. You can also use URIs like `resource:///org/gtk/Example/data/splashscreen.png` with [iface@Gio.File] to access the resource data. Some higher-level APIs, such as [`GtkApplication`](https://docs.gtk.org/gtk4/class.Application.html), will automatically load resources from certain well-known paths in the resource namespace as a convenience. See the documentation for those APIs for details. There are two forms of the generated source, the default version uses the compiler support for constructor and destructor functions (where available) to automatically create and register the `GResource` on startup or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created instead. This requires an explicit initialization call in your application/library, but it works on all platforms, even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.) Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses are for your own resources, and resource data is often used once, during parsing, and then released. # Overlays When debugging a program or testing a change to an installed version, it is often useful to be able to replace resources in the program or library, without recompiling, for debugging or quick hacking and testing purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay resources with replacements from the filesystem. It is a `G_SEARCHPATH_SEPARATOR`-separated list of substitutions to perform during resource lookups. It is ignored when running in a setuid process. A substitution has the form ``` /org/gtk/libgtk=/home/desrt/gtk-overlay ``` The part before the `=` is the resource subpath for which the overlay applies. The part after is a filesystem path which contains files and subdirectories as you would like to be loaded as resources with the equivalent names. In the example above, if an application tried to load a resource with the resource path `/org/gtk/libgtk/ui/gtkdialog.ui` then `GResource` would check the filesystem path `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an overlay, not an outright replacement, which means that if a file is not found at that path, the built-in version will be used instead. Whiteouts are not currently supported. Substitutions must start with a slash, and must not contain a trailing slash before the `=`. The filesystem path after the `=` should ideally be absolute, but this is not strictly required. It is possible to overlay the location of a single resource with an individual file. Creates a [struct@Gio.Resource] from a reference to the binary resource bundle. This will keep a reference to @data while the resource lives, so the data should not be modified or freed. If you want to use this resource in the global resource namespace you need to register it with [func@Gio.resources_register]. Note: @data must be backed by memory that is at least pointer aligned. Otherwise this function will internally create a copy of the memory since GLib 2.56, or in older versions fail and exit the process. If @data is empty or corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. a new [struct@Gio.Resource], or `NULL` on error A [struct@GLib.Bytes] Registers the resource with the process-global set of resources. Once a resource is registered the files in it can be accessed with the global resource lookup functions like [func@Gio.resources_lookup_data]. A [struct@Gio.Resource] Unregisters the resource from the process-global set of resources. A [struct@Gio.Resource] Returns all the names of children at the specified @path in the resource. The return result is a `NULL` terminated list of strings which should be released with [func@GLib.strfreev]. If @path is invalid or does not exist in the [struct@Gio.Resource], %G_RESOURCE_ERROR_NOT_FOUND will be returned. @lookup_flags controls the behaviour of the lookup. an array of constant strings A [struct@Gio.Resource] A path name inside the resource A [flags@Gio.ResourceLookupFlags] Looks for a file at the specified @path in the resource and if found returns information about it. @lookup_flags controls the behaviour of the lookup. The only error this can return is %G_RESOURCE_ERROR_NOT_FOUND, if @path was not found in @resource. `TRUE` if the file was found, `FALSE` if there were errors A [struct@Gio.Resource] A path name inside the resource A [flags@Gio.ResourceLookupFlags] a location to place the length of the contents of the file, or `NULL` if the length is not needed a location to place the flags about the file, or `NULL` if the length is not needed Returns whether the specified @path in the resource has children. %TRUE if @path has children A #GResource A pathname inside the resource Looks for a file at the specified @path in the resource and returns a [struct@GLib.Bytes] that lets you directly access the data in memory. The data is always followed by a zero byte, so you can safely use the data as a C string. However, that byte is not included in the size of the [struct@GLib.Bytes]. For uncompressed resource files this is a pointer directly into the resource bundle, which is typically in some read-only data section in the program binary. For compressed files, memory is allocated on the heap and the data is automatically uncompressed. @lookup_flags controls the behaviour of the lookup. This can return error %G_RESOURCE_ERROR_NOT_FOUND if @path was not found in @resource, or %G_RESOURCE_ERROR_INTERNAL if decompression of a compressed resource failed. [struct@GLib.Bytes] or `NULL` on error A [struct@Gio.Resource] A path name inside the resource A [flags@Gio.ResourceLookupFlags] Looks for a file at the specified @path in the resource and returns a [class@Gio.InputStream] that lets you read the data. @lookup_flags controls the behaviour of the lookup. The only error this can return is %G_RESOURCE_ERROR_NOT_FOUND, if @path was not found in @resource. [class@Gio.InputStream] or `NULL` on error A [struct@Gio.Resource] A path name inside the resource A [flags@Gio.ResourceLookupFlags] Atomically increments the reference count of @resource by one. This function is threadsafe and may be called from any thread. The passed in [struct@Gio.Resource] A [struct@Gio.Resource] Atomically decrements the reference count of @resource by one. If the reference count drops to 0, all memory allocated by the resource is released. This function is threadsafe and may be called from any thread. A [struct@Gio.Resource] Loads a binary resource bundle and creates a [struct@Gio.Resource] representation of it, allowing you to query it for data. If you want to use this resource in the global resource namespace you need to register it with [func@Gio.resources_register]. If @filename is empty or the data in it is corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or there is an error in reading it, an error from [ctor@GLib.MappedFile.new] will be returned. a new [struct@Gio.Resource], or `NULL` on error the path of a filename to load, in the GLib filename encoding An error code used with %G_RESOURCE_ERROR in a #GError returned from a #GResource routine. no file was found at the requested path unknown error Gets the [struct@Gio.Resource] Error Quark. a [type@GLib.Quark] GResourceFlags give information about a particular file inside a resource bundle. No flags set. The file is compressed. GResourceLookupFlags determine how resource path lookups are handled. No flags set. Extension point for #GSettingsBackend functionality. `GSeekable` is implemented by streams (implementations of [class@Gio.InputStream] or [class@Gio.OutputStream]) that support seeking. Seekable streams largely fall into two categories: resizable and fixed-size. `GSeekable` on fixed-sized streams is approximately the same as POSIX [`lseek()`](man:lseek(2)) on a block device (for example: attempting to seek past the end of the device is an error). Fixed streams typically cannot be truncated. `GSeekable` on resizable streams is approximately the same as POSIX [`lseek()`](man:lseek(2)) on a normal file. Seeking past the end and writing data will usually cause the stream to resize by introducing zero bytes. Tests if the stream supports the #GSeekableIface. %TRUE if @seekable can be seeked. %FALSE otherwise. a #GSeekable. Tests if the length of the stream can be adjusted with g_seekable_truncate(). %TRUE if the stream can be truncated, %FALSE otherwise. a #GSeekable. Seeks in the stream by the given @offset, modified by @type. Attempting to seek past the end of the stream will have different results depending on if the stream is fixed-sized or resizable. If the stream is resizable then seeking past the end and then writing will result in zeros filling the empty space. Seeking past the end of a resizable stream and reading will result in EOF. Seeking past the end of a fixed-sized stream will fail. Any operation that would result in a negative offset will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GSeekable. a #goffset. a #GSeekType. optional #GCancellable object, %NULL to ignore. Tells the current position within the stream. the (positive or zero) offset from the beginning of the buffer, zero if the target is not seekable. a #GSeekable. Sets the length of the stream to @offset. If the stream was previously larger than @offset, the extra data is discarded. If the stream was previously shorter than @offset, it is extended with NUL ('\0') bytes. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GSeekable. new length for @seekable, in bytes. optional #GCancellable object, %NULL to ignore. Tests if the stream supports the #GSeekableIface. %TRUE if @seekable can be seeked. %FALSE otherwise. a #GSeekable. Tests if the length of the stream can be adjusted with g_seekable_truncate(). %TRUE if the stream can be truncated, %FALSE otherwise. a #GSeekable. Seeks in the stream by the given @offset, modified by @type. Attempting to seek past the end of the stream will have different results depending on if the stream is fixed-sized or resizable. If the stream is resizable then seeking past the end and then writing will result in zeros filling the empty space. Seeking past the end of a resizable stream and reading will result in EOF. Seeking past the end of a fixed-sized stream will fail. Any operation that would result in a negative offset will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GSeekable. a #goffset. a #GSeekType. optional #GCancellable object, %NULL to ignore. Tells the current position within the stream. the (positive or zero) offset from the beginning of the buffer, zero if the target is not seekable. a #GSeekable. Sets the length of the stream to @offset. If the stream was previously larger than @offset, the extra data is discarded. If the stream was previously shorter than @offset, it is extended with NUL ('\0') bytes. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GSeekable. new length for @seekable, in bytes. optional #GCancellable object, %NULL to ignore. Provides an interface for implementing seekable functionality on I/O Streams. The parent interface. Tells the current location within a stream. the (positive or zero) offset from the beginning of the buffer, zero if the target is not seekable. a #GSeekable. Checks if seeking is supported by the stream. %TRUE if @seekable can be seeked. %FALSE otherwise. a #GSeekable. Seeks to a location within a stream. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GSeekable. a #goffset. a #GSeekType. optional #GCancellable object, %NULL to ignore. Checks if truncation is supported by the stream. %TRUE if the stream can be truncated, %FALSE otherwise. a #GSeekable. Truncates a stream. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GSeekable. new length for @seekable, in bytes. optional #GCancellable object, %NULL to ignore. The `GSettings` class provides a convenient API for storing and retrieving application settings. Reads and writes can be considered to be non-blocking. Reading settings with `GSettings` is typically extremely fast: on approximately the same order of magnitude (but slower than) a [struct@GLib.HashTable] lookup. Writing settings is also extremely fast in terms of time to return to your application, but can be extremely expensive for other threads and other processes. Many settings backends (including dconf) have lazy initialisation which means in the common case of the user using their computer without modifying any settings a lot of work can be avoided. For dconf, the D-Bus service doesn’t even need to be started in this case. For this reason, you should only ever modify `GSettings` keys in response to explicit user action. Particular care should be paid to ensure that modifications are not made during startup — for example, when setting the initial value of preferences widgets. The built-in [method@Gio.Settings.bind] functionality is careful not to write settings in response to notify signals as a result of modifications that it makes to widgets. When creating a `GSettings` instance, you have to specify a schema that describes the keys in your settings and their types and default values, as well as some other information. Normally, a schema has a fixed path that determines where the settings are stored in the conceptual global tree of settings. However, schemas can also be ‘[relocatable](#relocatable-schemas)’, i.e. not equipped with a fixed path. This is useful e.g. when the schema describes an ‘account’, and you want to be able to store a arbitrary number of accounts. Paths must start with and end with a forward slash character (`/`) and must not contain two sequential slash characters. Paths should be chosen based on a domain name associated with the program or library to which the settings belong. Examples of paths are `/org/gtk/settings/file-chooser/` and `/ca/desrt/dconf-editor/`. Paths should not start with `/apps/`, `/desktop/` or `/system/` as they often did in GConf. Unlike other configuration systems (like GConf), GSettings does not restrict keys to basic types like strings and numbers. GSettings stores values as [struct@GLib.Variant], and allows any [type@GLib.VariantType] for keys. Key names are restricted to lowercase characters, numbers and `-`. Furthermore, the names must begin with a lowercase character, must not end with a `-`, and must not contain consecutive dashes. Similar to GConf, the default values in GSettings schemas can be localized, but the localized values are stored in gettext catalogs and looked up with the domain that is specified in the `gettext-domain` attribute of the `<schemalist>` or `<schema>` elements and the category that is specified in the `l10n` attribute of the `<default>` element. The string which is translated includes all text in the `<default>` element, including any surrounding quotation marks. The `l10n` attribute must be set to `messages` or `time`, and sets the [locale category for translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1). The `messages` category should be used by default; use `time` for translatable date or time formats. A translation comment can be added as an XML comment immediately above the `<default>` element — it is recommended to add these comments to aid translators understand the meaning and implications of the default value. An optional translation `context` attribute can be set on the `<default>` element to disambiguate multiple defaults which use the same string. For example: ```xml <!-- Translators: A list of words which are not allowed to be typed, in GVariant serialization syntax. See: https://developer.gnome.org/glib/stable/gvariant-text.html --> <default l10n='messages' context='Banned words'>['bad', 'words']</default> ``` Translations of default values must remain syntactically valid serialized [struct@GLib.Variant]s (e.g. retaining any surrounding quotation marks) or runtime errors will occur. GSettings uses schemas in a compact binary form that is created by the [`glib-compile-schemas`](glib-compile-schemas.html) utility. The input is a schema description in an XML format. A DTD for the gschema XML format can be found here: [gschema.dtd](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/gschema.dtd) The [`glib-compile-schemas`](glib-compile-schemas.html) tool expects schema files to have the extension `.gschema.xml`. At runtime, schemas are identified by their ID (as specified in the `id` attribute of the `<schema>` element). The convention for schema IDs is to use a dotted name, similar in style to a D-Bus bus name, e.g. `org.gnome.SessionManager`. In particular, if the settings are for a specific service that owns a D-Bus bus name, the D-Bus bus name and schema ID should match. For schemas which deal with settings not associated with one named application, the ID should not use StudlyCaps, e.g. `org.gnome.font-rendering`. In addition to [struct@GLib.Variant] types, keys can have types that have enumerated types. These can be described by a `<choice>`, `<enum>` or `<flags>` element, as seen in the second example below. The underlying type of such a key is string, but you can use [method@Gio.Settings.get_enum], [method@Gio.Settings.set_enum], [method@Gio.Settings.get_flags], [method@Gio.Settings.set_flags] access the numeric values corresponding to the string value of enum and flags keys. An example for default value: ```xml <schemalist> <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test"> <key name="greeting" type="s"> <default l10n="messages">"Hello, earthlings"</default> <summary>A greeting</summary> <description> Greeting of the invading martians </description> </key> <key name="box" type="(ii)"> <default>(20,30)</default> </key> <key name="empty-string" type="s"> <default>""</default> <summary>Empty strings have to be provided in GVariant form</summary> </key> </schema> </schemalist> ``` An example for ranges, choices and enumerated types: ```xml <schemalist> <enum id="org.gtk.Test.myenum"> <value nick="first" value="1"/> <value nick="second" value="2"/> </enum> <flags id="org.gtk.Test.myflags"> <value nick="flag1" value="1"/> <value nick="flag2" value="2"/> <value nick="flag3" value="4"/> </flags> <schema id="org.gtk.Test"> <key name="key-with-range" type="i"> <range min="1" max="100"/> <default>10</default> </key> <key name="key-with-choices" type="s"> <choices> <choice value='Elisabeth'/> <choice value='Annabeth'/> <choice value='Joe'/> </choices> <aliases> <alias value='Anna' target='Annabeth'/> <alias value='Beth' target='Elisabeth'/> </aliases> <default>'Joe'</default> </key> <key name='enumerated-key' enum='org.gtk.Test.myenum'> <default>'first'</default> </key> <key name='flags-key' flags='org.gtk.Test.myflags'> <default>["flag1","flag2"]</default> </key> </schema> </schemalist> ``` ## Vendor overrides Default values are defined in the schemas that get installed by an application. Sometimes, it is necessary for a vendor or distributor to adjust these defaults. Since patching the XML source for the schema is inconvenient and error-prone, [`glib-compile-schemas`](glib-compile-schemas.html) reads so-called ‘vendor override’ files. These are keyfiles in the same directory as the XML schema sources which can override default values. The schema ID serves as the group name in the key file, and the values are expected in serialized [struct@GLib.Variant] form, as in the following example: ``` [org.gtk.Example] key1='string' key2=1.5 ``` `glib-compile-schemas` expects schema files to have the extension `.gschema.override`. ## Delay-apply mode By default, values set on a [class@Gio.Settings] instance immediately start to be written to the backend (although these writes may not complete by the time that [method@Gio.Settings.set]) returns; see [func@Gio.Settings.sync]). In order to allow groups of settings to be changed simultaneously and atomically, GSettings also supports a ‘delay-apply’ mode. In this mode, updated values are kept locally in the [class@Gio.Settings] instance until they are explicitly applied by calling [method@Gio.Settings.apply]. For example, this could be useful for a preferences dialog where the preferences all need to be applied simultaneously when the user clicks ‘Save’. Switching a [class@Gio.Settings] instance to ‘delay-apply’ mode is a one-time irreversible operation: from that point onwards, *all* changes made to that [class@Gio.Settings] have to be explicitly applied by calling [method@Gio.Settings.apply]. The ‘delay-apply’ mode is also propagated to any child settings objects subsequently created using [method@Gio.Settings.get_child]. At any point, the set of unapplied changes can be queried using [property@Gio.Settings:has-unapplied], and discarded by calling [method@Gio.Settings.revert]. ## Binding A very convenient feature of GSettings lets you bind [class@GObject.Object] properties directly to settings, using [method@Gio.Settings.bind]. Once a [class@GObject.Object] property has been bound to a setting, changes on either side are automatically propagated to the other side. GSettings handles details like mapping between [class@GObject.Object] and [struct@GLib.Variant] types, and preventing infinite cycles. This makes it very easy to hook up a preferences dialog to the underlying settings. To make this even more convenient, GSettings looks for a boolean property with the name `sensitivity` and automatically binds it to the writability of the bound setting. If this ‘magic’ gets in the way, it can be suppressed with the `G_SETTINGS_BIND_NO_SENSITIVITY` flag. ## Relocatable schemas A relocatable schema is one with no `path` attribute specified on its `<schema>` element. By using [ctor@Gio.Settings.new_with_path], a `GSettings` object can be instantiated for a relocatable schema, assigning a path to the instance. Paths passed to [ctor@Gio.Settings.new_with_path] will typically be constructed dynamically from a constant prefix plus some form of instance identifier; but they must still be valid GSettings paths. Paths could also be constant and used with a globally installed schema originating from a dependency library. For example, a relocatable schema could be used to store geometry information for different windows in an application. If the schema ID was `org.foo.MyApp.Window`, it could be instantiated for paths `/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`, `/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known they can be specified as `<child>` elements in the parent schema, e.g.: ```xml <schema id="org.foo.MyApp" path="/org/foo/MyApp/"> <child name="main" schema="org.foo.MyApp.Window"/> </schema> ``` ## Build system integration ### Meson GSettings is natively supported by Meson’s [GNOME module](https://mesonbuild.com/Gnome-module.html). You can install the schemas as any other data file: ``` install_data( 'org.foo.MyApp.gschema.xml', install_dir: get_option('datadir') / 'glib-2.0/schemas', ) ``` You can use `gnome.post_install()` function to compile the schemas on installation: ``` gnome = import('gnome') gnome.post_install( glib_compile_schemas: true, ) ``` If an enumerated type defined in a C header file is to be used in a GSettings schema, it can either be defined manually using an `<enum>` element in the schema XML, or it can be extracted automatically from the C header. This approach is preferred, as it ensures the two representations are always synchronised. To do so, you will need to use the `gnome.mkenums()` function with the following templates: ``` schemas_enums = gnome.mkenums('org.foo.MyApp.enums.xml', comments: '<!-- @comment@ -->', fhead: '<schemalist>', vhead: ' <@type@ id="org.foo.MyApp.@EnumName@">', vprod: ' <value nick="@valuenick@" value="@valuenum@"/>', vtail: ' </@type@>', ftail: '</schemalist>', sources: enum_sources, install_header: true, install_dir: get_option('datadir') / 'glib-2.0/schemas', ) ``` It is recommended to validate your schemas as part of the test suite for your application: ``` test('validate-schema', find_program('glib-compile-schemas'), args: ['--strict', '--dry-run', meson.current_source_dir()], ) ``` If your application allows running uninstalled, you should also use the `gnome.compile_schemas()` function to compile the schemas in the current build directory: ``` gnome.compile_schemas() ``` ### Autotools GSettings comes with autotools integration to simplify compiling and installing schemas. To add GSettings support to an application, add the following to your `configure.ac`: ``` GLIB_GSETTINGS ``` In the appropriate `Makefile.am`, use the following snippet to compile and install the named schema: ``` gsettings_SCHEMAS = org.foo.MyApp.gschema.xml EXTRA_DIST = $(gsettings_SCHEMAS) @GSETTINGS_RULES@ ``` If an enumerated type defined in a C header file is to be used in a GSettings schema, it can either be defined manually using an `<enum>` element in the schema XML, or it can be extracted automatically from the C header. This approach is preferred, as it ensures the two representations are always synchronised. To do so, add the following to the relevant `Makefile.am`: ``` gsettings_ENUM_NAMESPACE = org.foo.MyApp gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h ``` `gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files, which are specified in `gsettings_ENUM_FILES`. This will generate a `org.foo.MyApp.enums.xml` file containing the extracted enums, which will be automatically included in the schema compilation, install and uninstall rules. It should not be committed to version control or included in `EXTRA_DIST`. ## Localization No changes are needed to the build system to mark a schema XML file for translation. Assuming it sets the `gettext-domain` attribute, a schema may be marked for translation by adding it to `POTFILES.in`, assuming gettext 0.19 or newer is in use (the preferred method for translation): ``` data/org.foo.MyApp.gschema.xml ``` Alternatively, if intltool 0.50.1 is in use: ``` [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml ``` GSettings will use gettext to look up translations for the `<summary>` and `<description>` elements, and also any `<default>` elements which have a `l10n` attribute set. Translations **must not** be included in the `.gschema.xml` file by the build system, for example by using a rule to generate the XML file from a template. Creates a new [class@Gio.Settings] object with the schema specified by @schema_id. It is an error for the schema to not exist: schemas are an essential part of a program, as they provide type information. If schemas need to be dynamically loaded (for example, from an optional runtime dependency), [method@Gio.SettingsSchemaSource.lookup] can be used to test for their existence before loading them. Signals on the newly created [class@Gio.Settings] object will be dispatched via the thread-default [struct@GLib.MainContext] in effect at the time of the call to [ctor@Gio.Settings.new]. The new [class@Gio.Settings] will hold a reference on the context. See [method@GLib.MainContext.push_thread_default]. a new [class@Gio.Settings] object the ID of the schema Creates a new [class@Gio.Settings] object with a given schema, backend and path. It should be extremely rare that you ever want to use this function. It is made available for advanced use-cases (such as plugin systems that want to provide access to schemas loaded from custom locations, etc). At the most basic level, a [class@Gio.Settings] object is a pure composition of four things: a [struct@Gio.SettingsSchema], a [class@Gio.SettingsBackend], a path within that backend, and a [struct@GLib.MainContext] to which signals are dispatched. This constructor therefore gives you full control over constructing [class@Gio.Settings] instances. The first 3 parameters are given directly as @schema, @backend and @path, and the main context is taken from the thread-default (as per [ctor@Gio.Settings.new]). If @backend is `NULL` then the default backend is used. If @path is `NULL` then the path from the schema is used. It is an error if @path is `NULL` and the schema has no path of its own or if @path is non-`NULL` and not equal to the path that the schema does have. a new [class@Gio.Settings] object the schema describing the settings the settings backend to use the path to use Creates a new [class@Gio.Settings] object with the schema specified by @schema_id and a given [class@Gio.SettingsBackend]. Creating a [class@Gio.Settings] object with a different backend allows accessing settings from a database other than the usual one. For example, it may make sense to pass a backend corresponding to the ‘defaults’ settings database on the system to get a settings object that modifies the system default settings instead of the settings for this user. a new [class@Gio.Settings] object the ID of the schema the settings backend to use Creates a new [class@Gio.Settings] object with the schema specified by @schema_id and a given [class@Gio.SettingsBackend] and path. This is a mix of [ctor@Gio.Settings.new_with_backend] and [ctor@Gio.Settings.new_with_path]. a new [class@Gio.Settings] object the ID of the schema the settings backend to use the path to use Creates a new [class@Gio.Settings] object with the relocatable schema specified by @schema_id and a given path. You only need to do this if you want to directly create a settings object with a schema that doesn’t have a specified path of its own. That’s quite rare. It is a programmer error to call this function for a schema that has an explicitly specified path. It is a programmer error if @path is not a valid path. A valid path begins and ends with `/` and does not contain two consecutive `/` characters. a new [class@Gio.Settings] object the ID of the schema the path to use Deprecated. Use g_settings_schema_source_list_schemas() instead a list of relocatable #GSettings schemas that are available, in no defined order. The list must not be modified or freed. Deprecated. Use g_settings_schema_source_list_schemas() instead. If you used g_settings_list_schemas() to check for the presence of a particular schema, use g_settings_schema_source_lookup() instead of your whole loop. a list of #GSettings schemas that are available, in no defined order. The list must not be modified or freed. Ensures that all pending operations are complete for the default backend. Writes made to a [class@Gio.Settings] are handled asynchronously. For this reason, it is very unlikely that the changes have it to disk by the time [method@Gio.Settings.set] returns. This call will block until all of the writes have made it to the backend. Since the main loop is not running, no change notifications will be dispatched during this call (but some may be queued by the time the call is done). Removes an existing binding for @property on @object. Note that bindings are automatically removed when the object is finalized, so it is rarely necessary to call this function. the object with property to unbind the property whose binding is removed Applies any changes that have been made to the settings. This function does nothing unless @settings is in [‘delay-apply’ mode](class.Settings.html#delay-apply-mode). In the normal case settings are always applied immediately. the settings object Create a binding between the @key in the @settings object and the property @property of @object. The binding uses the default GIO mapping functions to map between the settings and property values. These functions handle booleans, numeric types and string types in a straightforward way. Use [method@Gio.Settings.bind_with_mapping] if you need a custom mapping, or map between types that are not supported by the default mapping functions. Unless the @flags include [flags@Gio.SettingsBindFlags.NO_SENSITIVITY], this function also establishes a binding between the writability of @key and the `sensitive` property of @object (if @object has a boolean property by that name). See [method@Gio.Settings.bind_writable] for more details about writable bindings. Note that the lifecycle of the binding is tied to @object, and that you can have only one binding per object property. If you bind the same property twice on the same object, the second binding overrides the first one. the settings object the key to bind the object with property to bind the name of the property to bind flags for the binding Create a binding between the @key in the @settings object and the property @property of @object. The binding uses the provided mapping functions to map between settings and property values. Note that the lifecycle of the binding is tied to @object, and that you can have only one binding per object property. If you bind the same property twice on the same object, the second binding overrides the first one. the settings object the key to bind the object with property to bind the name of the property to bind flags for the binding a function that gets called to convert values from @settings to @object, or `NULL` to use the default GIO mapping a function that gets called to convert values from @object to @settings, or `NULL` to use the default GIO mapping data that gets passed to @get_mapping and @set_mapping destroy notify function for @user_data Version of [method@Gio.Settings.bind_with_mapping] using closures instead of callbacks for easier binding in other languages. the settings object the key to bind the object with property to bind the name of the property to bind flags for the binding a function that gets called to convert values from @settings to @object, or `NULL` to use the default GIO mapping a function that gets called to convert values from @object to @settings, or `NULL` to use the default GIO mapping Create a binding between the writability of @key in the @settings object and the property @property of @object. The property must be boolean; `sensitive` or `visible` properties of widgets are the most likely candidates. Writable bindings are always uni-directional; changes of the writability of the setting will be propagated to the object property, not the other way. When the @inverted argument is true, the binding inverts the value as it passes from the setting to the object, i.e. @property will be set to true if the key is not writable. Note that the lifecycle of the binding is tied to @object, and that you can have only one binding per object property. If you bind the same property twice on the same object, the second binding overrides the first one. the settings object the key to bind the object with property to bind the name of a boolean property to bind whether to ‘invert’ the value Creates a [iface@Gio.Action] corresponding to a given [class@Gio.Settings] key. The action has the same name as the key. The value of the key becomes the state of the action and the action is enabled when the key is writable. Changing the state of the action results in the key being written to. Changes to the value or writability of the key cause appropriate change notifications to be emitted for the action. For boolean-valued keys, action activations take no parameter and result in the toggling of the value. For all other types, activations take the new value for the key (which must have the correct type). a new [iface@Gio.Action] the settings object the name of a key in @settings Changes the [class@Gio.Settings] object into [‘delay-apply’ mode](class.Settings.html#delay-apply-mode). In this mode, changes to @settings are not immediately propagated to the backend, but kept locally until [method@Gio.Settings.apply] is called. the settings object Gets the value that is stored at @key in @settings. A convenience function that combines [method@Gio.Settings.get_value] with [method@GLib.Variant.get]. It is a programmer error to give a @key that isn’t contained in the schema for @settings or for the [struct@GLib.VariantType] of @format to mismatch the type given in the schema. the settings object the key to get the value for a [struct@GLib.Variant] format string arguments as per @format Gets the value that is stored at @key in @settings. A convenience variant of [method@Gio.Settings.get] for booleans. It is a programmer error to give a @key that isn’t specified as having a `b` type in the schema for @settings (see [struct@GLib.VariantType]). a boolean the settings object the key to get the value for Creates a child settings object which has a base path of `base-path/name`, where `base-path` is the base path of @settings and `name` is as specified by the caller. The schema for the child settings object must have been declared in the schema of @settings using a `<child>` element. The created child settings object will inherit the [property@Gio.Settings:delay-apply] mode from @settings. a ‘child’ settings object the settings object the name of the child schema Gets the ‘default value’ of a key. This is the value that would be read if [method@Gio.Settings.reset] were to be called on the key. Note that this may be a different value than returned by [method@Gio.SettingsSchemaKey.get_default_value] if the system administrator has provided a default value. Comparing the return values of [method@Gio.Settings.get_default_value] and [method@Gio.Settings.get_value] is not sufficient for determining if a value has been set because the user may have explicitly set the value to something that happens to be equal to the default. The difference here is that if the default changes in the future, the user’s key will still be set. This function may be useful for adding an indication to a UI of what the default value was before the user set it. It is a programmer error to give a @key that isn’t contained in the schema for @settings. the default value the settings object the key to get the default value for Gets the value that is stored at @key in @settings. A convenience variant of [method@Gio.Settings.get] for doubles. It is a programmer error to give a @key that isn’t specified as having a `d` type in the schema for @settings (see [struct@GLib.VariantType]). a double the settings object the key to get the value for Gets the value that is stored in @settings for @key and converts it to the enum value that it represents. In order to use this function the type of the value must be a string and it must be marked in the schema file as an enumerated type. It is a programmer error to give a @key that isn’t contained in the schema for @settings or is not marked as an enumerated type. If the value stored in the configuration database is not a valid value for the enumerated type then this function will return the default value. the enum value the settings object the key to get the value for Gets the value that is stored in @settings for @key and converts it to the flags value that it represents. In order to use this function the type of the value must be an array of strings and it must be marked in the schema file as a flags type. It is a programmer error to give a @key that isn’t contained in the schema for @settings or is not marked as a flags type. If the value stored in the configuration database is not a valid value for the flags type then this function will return the default value. the flags value the settings object the key to get the value for Returns whether the [class@Gio.Settings] object has any unapplied changes. This can only be the case if it is in [‘delay-apply’ mode](class.Settings.html#delay-apply-mode). true if @settings has unapplied changes, false otherwise the settings object Gets the value that is stored at @key in @settings. A convenience variant of [method@Gio.Settings.get] for 32-bit integers. It is a programmer error to give a @key that isn’t specified as having an `i` type in the schema for @settings (see [struct@GLib.VariantType]). an integer the settings object the key to get the value for Gets the value that is stored at @key in @settings. A convenience variant of [method@Gio.Settings.get] for 64-bit integers. It is a programmer error to give a @key that isn’t specified as having an `x` type in the schema for @settings (see [struct@GLib.VariantType]). a 64-bit integer the settings object the key to get the value for Gets the value that is stored at @key in @settings, subject to application-level validation/mapping. You should use this function when the application needs to perform some processing on the value of the key (for example, parsing). The @mapping function performs that processing. If the function indicates that the processing was unsuccessful (due to a parse error, for example) then the mapping is tried again with another value. This allows a robust ‘fall back to defaults’ behaviour to be implemented somewhat automatically. The first value that is tried is the user’s setting for the key. If the mapping function fails to map this value, other values may be tried in an unspecified order (system or site defaults, translated schema default values, untranslated schema default values, etc). If the mapping function fails for all possible values, one additional attempt is made: the mapping function is called with a `NULL` value. If the mapping function still indicates failure at this point then the application will be aborted. The result parameter for the @mapping function is pointed to a `gpointer` which is initially set to `NULL`. The same pointer is given to each invocation of @mapping. The final value of that `gpointer` is what is returned by this function. `NULL` is valid; it is returned just as any other value would be. the result, which may be `NULL` the settings object the key to get the value for the function to map the value in the settings database to the value used by the application user data for @mapping Queries the range of a key. Use [method@Gio.SettingsSchemaKey.get_range] instead. the settings object the key to query the range of Gets the value that is stored at @key in @settings. A convenience variant of [method@Gio.Settings.get] for strings. It is a programmer error to give a @key that isn’t specified as having an `s` type in the schema for @settings (see [struct@GLib.VariantType]). a newly-allocated string the settings object the key to get the value for A convenience variant of [method@Gio.Settings.get] for string arrays. It is a programmer error to give a @key that isn’t specified as having an `as` type in the schema for @settings (see [struct@GLib.VariantType]). a newly-allocated, `NULL`-terminated array of strings, the value that is stored at @key in @settings. the settings object the key to get the value for Gets the value that is stored at @key in @settings. A convenience variant of [method@Gio.Settings.get] for 32-bit unsigned integers. It is a programmer error to give a @key that isn’t specified as having a `u` type in the schema for @settings (see [struct@GLib.VariantType]). an unsigned integer the settings object the key to get the value for Gets the value that is stored at @key in @settings. A convenience variant of [method@Gio.Settings.get] for 64-bit unsigned integers. It is a programmer error to give a @key that isn’t specified as having a `t` type in the schema for @settings (see [struct@GLib.VariantType]). a 64-bit unsigned integer the settings object the key to get the value for Checks the ‘user value’ of a key, if there is one. The user value of a key is the last value that was set by the user. After calling [method@Gio.Settings.reset] this function should always return `NULL` (assuming something is not wrong with the system configuration). It is possible that [method@Gio.Settings.get_value] will return a different value than this function. This can happen in the case that the user set a value for a key that was subsequently locked down by the system administrator — this function will return the user’s old value. This function may be useful for adding a ‘reset’ option to a UI or for providing indication that a particular value has been changed. It is a programmer error to give a @key that isn’t contained in the schema for @settings. the user’s value, if set the settings object the key to get the user value for Gets the value that is stored in @settings for @key. It is a programmer error to give a @key that isn’t contained in the schema for @settings. a new [struct@GLib.Variant] the settings object the key to get the value for Finds out if a key can be written. true if the key @name is writable, false otherwise the settings object the name of a key Gets the list of children on @settings. The list is exactly the list of strings for which it is not an error to call [method@Gio.Settings.get_child]. There is little reason to call this function from ‘normal’ code, since you should already know what children are in your schema. This function may still be useful there for introspection reasons, however. You should free the return value with [func@GLib.strfreev] when you are done with it. a list of the children on @settings, in no defined order the settings object Introspects the list of keys on @settings. You should probably not be calling this function from ‘normal’ code (since you should already know what keys are in your schema). This function is intended for introspection reasons. You should free the return value with [func@GLib.strfreev] when you are done with it. Use [method@Gio.SettingsSchema.list_keys] instead. a list of the keys on @settings, in no defined order the settings object Checks if the given @value is of the correct type and within the permitted range for @key. Use [method@Gio.SettingsSchemaKey.range_check] instead. true if @value is valid for @key, false otherwise the settings object the key to check the value to check Resets @key to its default value. This call resets the key, as much as possible, to its default value. That might be the value specified in the schema or the one set by the administrator. the settings object the name of a key Reverts all unapplied changes to the settings. This function does nothing unless @settings is in [‘delay-apply’ mode](class.Settings.html#delay-apply-mode). In the normal case settings are always applied immediately. Change notifications will be emitted for affected keys. the settings object Sets @key in @settings to @value. A convenience function that combines [method@Gio.Settings.set_value] with [ctor@GLib.Variant.new]. It is a programmer error to give a @key that isn’t contained in the schema for @settings or for the [struct@GLib.VariantType] of @format to mismatch the type given in the schema. true if setting the key succeeded, false if the key was not writable the settings object the key to set the value for a [struct@GLib.Variant] format string arguments as per @format Sets @key in @settings to @value. A convenience variant of [method@Gio.Settings.set] for booleans. It is a programmer error to give a @key that isn’t specified as having a `b` type in the schema for @settings (see [struct@GLib.VariantType]). true if setting the key succeeded, false if the key was not writable the settings object the key to set the value for the value to set it to Sets @key in @settings to @value. A convenience variant of [method@Gio.Settings.set] for doubles. It is a programmer error to give a @key that isn’t specified as having a `d` type in the schema for @settings (see [struct@GLib.VariantType]). true if setting the key succeeded, false if the key was not writable the settings object the key to set the value for the value to set it to Looks up the enumerated type nick for @value and writes it to @key, within @settings. It is a programmer error to give a @key that isn’t contained in the schema for @settings or is not marked as an enumerated type, or for @value not to be a valid value for the named type. After performing the write, accessing @key directly with [method@Gio.Settings.get_string] will return the ‘nick’ associated with @value. true if the set succeeds, false otherwise the settings object the key to set the value for an enumerated value Looks up the flags type nicks for the bits specified by @value, puts them in an array of strings and writes the array to @key, within @settings. It is a programmer error to give a @key that isn’t contained in the schema for @settings or is not marked as a flags type, or for @value to contain any bits that are not value for the named type. After performing the write, accessing @key directly with [method@Gio.Settings.get_strv] will return an array of ‘nicks’; one for each bit in @value. true if the set succeeds, false otherwise the settings object the key to set the value for a flags value Sets @key in @settings to @value. A convenience variant of [method@Gio.Settings.set] for 32-bit integers. It is a programmer error to give a @key that isn’t specified as having an `i` type in the schema for @settings (see [struct@GLib.VariantType]). true if setting the key succeeded, false if the key was not writable the settings object the key to set the value for the value to set it to Sets @key in @settings to @value. A convenience variant of [method@Gio.Settings.set] for 64-bit integers. It is a programmer error to give a @key that isn’t specified as having an `x` type in the schema for @settings (see [struct@GLib.VariantType]). true if setting the key succeeded, false if the key was not writable the settings object the key to set the value for the value to set it to Sets @key in @settings to @value. A convenience variant of [method@Gio.Settings.set] for strings. It is a programmer error to give a @key that isn’t specified as having an `s` type in the schema for @settings (see [struct@GLib.VariantType]). true if setting the key succeeded, false if the key was not writable the settings object the key to set the value for the value to set it to Sets @key in @settings to @value. A convenience variant of [method@Gio.Settings.set] for string arrays. If @value is `NULL`, then @key is set to be the empty array. It is a programmer error to give a @key that isn’t specified as having an `as` type in the schema for @settings (see [struct@GLib.VariantType]). true if setting the key succeeded, false if the key was not writable the settings object the key to set the value for the value to set it to Sets @key in @settings to @value. A convenience variant of [method@Gio.Settings.set] for 32-bit unsigned integers. It is a programmer error to give a @key that isn’t specified as having a `u` type in the schema for @settings (see [struct@GLib.VariantType]). true if setting the key succeeded, false if the key was not writable the settings object the key to set the value for the value to set it to Sets @key in @settings to @value. A convenience variant of [method@Gio.Settings.set] for 64-bit unsigned integers. It is a programmer error to give a @key that isn’t specified as having a `t` type in the schema for @settings (see [struct@GLib.VariantType]). true if setting the key succeeded, false if the key was not writable the settings object the key to set the value for the value to set it to Sets @key in @settings to @value. It is a programmer error to give a @key that isn’t contained in the schema for @settings or for @value to have the incorrect type, per the schema. If @value is floating then this function consumes the reference. true if setting the key succeeded, false if the key was not writable the settings object the key to set the value for a [struct@GLib.Variant] of the correct type The name of the context that the settings are stored in. Whether the [class@Gio.Settings] object is in [‘delay-apply’ mode](class.Settings.html#delay-apply-mode). Whether the [class@Gio.Settings] object has outstanding changes. These changes will be applied when [method@Gio.Settings.apply] is called. The path within the backend where the settings are stored. The name of the schema that describes the types of keys for this [class@Gio.Settings] object. The type of this property is *not* [struct@Gio.SettingsSchema]. [struct@Gio.SettingsSchema] has only existed since version 2.32 and unfortunately this name was used in previous versions to refer to the schema ID rather than the schema itself. Take care to use the [property@Gio.Settings:settings-schema] property if you wish to pass in a [struct@Gio.SettingsSchema]. Use the [property@Gio.Settings:schema-id] property instead. In a future version, this property may instead refer to a [struct@Gio.SettingsSchema]. The name of the schema that describes the types of keys for this [class@Gio.Settings] object. The [struct@Gio.SettingsSchema] describing the types of keys for this [class@Gio.Settings] object. Ideally, this property would be called [property@Gio.Settings:schema]. [struct@Gio.SettingsSchema] has only existed since version 2.32, however, and before then the [property@Gio.Settings:schema] property was used to refer to the ID of the schema rather than the schema itself. Take care. Emitted once per change event that affects this settings object. You should connect to this signal only if you are interested in viewing groups of changes before they are split out into multiple emissions of the [signal@Gio.Settings::changed] signal. For most use cases it is more appropriate to use the [signal@Gio.Settings::changed] signal. In the event that the change event applies to one or more specified keys, @keys will be an array of [alias@GLib.Quark]s of length @n_keys. In the event that the change event applies to the [class@Gio.Settings] object as a whole (ie: potentially every key has been changed) then @keys will be `NULL` and @n_keys will be `0`. The default handler for this signal invokes the [signal@Gio.Settings::changed] signal for each affected key. If any other connected handler returns true then this default functionality will be suppressed. true to stop other handlers from being invoked for the event, false to propagate the event further array of the keys which have changed the length of the @keys array, or `0` Emitted when a key has potentially changed. You should call one of the [method@Gio.Settings.get] calls to check the new value. This signal supports detailed connections. You can connect to the detailed signal `changed::x` in order to only receive callbacks when key `x` changes. Note that @settings only emits this signal if you have read @key at least once while a signal handler was already connected for @key. the name of the key that changed Emitted once per writability change event that affects this settings object. You should connect to this signal if you are interested in viewing groups of changes before they are split out into multiple emissions of the [signal@Gio.Settings::writable-changed] signal. For most use cases it is more appropriate to use the [signal@Gio.Settings::writable-changed] signal. In the event that the writability change applies only to a single key, @key will be set to the [alias@GLib.Quark] for that key. In the event that the writability change affects the entire settings object, @key will be `0`. The default handler for this signal invokes the [signal@Gio.Settings::writable-changed] and [signal@Gio.Settings::changed] signals for each affected key. This is done because changes in writability might also imply changes in value (if for example, a new mandatory setting is introduced). If any other connected handler returns true then this default functionality will be suppressed. true to stop other handlers from being invoked for the event, false to propagate the event further the quark of the key, or `0` Emitted when the writability of a key has potentially changed. You should call [method@Gio.Settings.is_writable] in order to determine the new status. This signal supports detailed connections. You can connect to the detailed signal `writable-changed::x` in order to only receive callbacks when the writability of `x` changes. the key The `GSettingsBackend` interface defines a generic interface for non-strictly-typed data that is stored in a hierarchy. To implement an alternative storage backend for [class@Gio.Settings], you need to implement the `GSettingsBackend` interface and then make it implement the extension point `G_SETTINGS_BACKEND_EXTENSION_POINT_NAME`. The interface defines methods for reading and writing values, a method for determining if writing of certain values will fail (lockdown) and a change notification mechanism. The semantics of the interface are very precisely defined and implementations must carefully adhere to the expectations of callers that are documented on each of the interface methods. Some of the `GSettingsBackend` functions accept or return a [struct@GLib.Tree]. These trees always have strings as keys and [struct@GLib.Variant] as values. The `GSettingsBackend` API is exported to allow third-party implementations, but does not carry the same stability guarantees as the public GIO API. For this reason, you have to define the C preprocessor symbol `G_SETTINGS_ENABLE_BACKEND` before including `gio/gsettingsbackend.h`. Calculate the longest common prefix of all keys in a tree and write out an array of the key names relative to that prefix and, optionally, the value to store at each of those keys. You must free the value returned in @path, @keys and @values using g_free(). You should not attempt to free or unref the contents of @keys or @values. a #GTree containing the changes the location to save the path the location to save the relative keys the location to save the values, or %NULL Returns the default #GSettingsBackend. It is possible to override the default by setting the `GSETTINGS_BACKEND` environment variable to the name of a settings backend. The user gets a reference to the backend. the default #GSettingsBackend, which will be a dummy (memory) settings backend if no other settings backend is available. virtual method to get permission of a key virtual method to get if a key is writable virtual method to read a key's value virtual method to read user's key value virtual method to reset state virtual method to subscribe to key changes virtual method to sync state virtual method to unsubscribe to key changes virtual method to change key's value virtual method to change a tree of keys Signals that a single key has possibly changed. Backend implementations should call this if a key has possibly changed its value. @key must be a valid key (ie starting with a slash, not containing '//', and not ending with a slash). The implementation must call this function during any call to g_settings_backend_write(), before the call returns (except in the case that no keys are actually changed and it cares to detect this fact). It may not rely on the existence of a mainloop for dispatching the signal later. The implementation may call this function at any other time it likes in response to other events (such as changes occurring outside of the program). These calls may originate from a mainloop or may originate in response to any other action (including from calls to g_settings_backend_write()). In the case that this call is in response to a call to g_settings_backend_write() then @origin_tag must be set to the same value that was passed to that call. a #GSettingsBackend implementation the name of the key the origin tag This call is a convenience wrapper. It gets the list of changes from @tree, computes the longest common prefix and calls g_settings_backend_changed(). a #GSettingsBackend implementation a #GTree containing the changes the origin tag Signals that a list of keys have possibly changed. Backend implementations should call this if keys have possibly changed their values. @path must be a valid path (ie starting and ending with a slash and not containing '//'). Each string in @items must form a valid key name when @path is prefixed to it (ie: each item must not start or end with '/' and must not contain '//'). The meaning of this signal is that any of the key names resulting from the concatenation of @path with each item in @items may have changed. The same rules for when notifications must occur apply as per g_settings_backend_changed(). These two calls can be used interchangeably if exactly one item has changed (although in that case g_settings_backend_changed() is definitely preferred). For efficiency reasons, the implementation should strive for @path to be as long as possible (ie: the longest common prefix of all of the keys that were changed) but this is not strictly required. a #GSettingsBackend implementation the path containing the changes the %NULL-terminated list of changed keys the origin tag Signals that all keys below a given path may have possibly changed. Backend implementations should call this if an entire path of keys have possibly changed their values. @path must be a valid path (ie starting and ending with a slash and not containing '//'). The meaning of this signal is that any of the key which has a name starting with @path may have changed. The same rules for when notifications must occur apply as per g_settings_backend_changed(). This call might be an appropriate reasponse to a 'reset' call but implementations are also free to explicitly list the keys that were affected by that call if they can easily do so. For efficiency reasons, the implementation should strive for @path to be as long as possible (ie: the longest common prefix of all of the keys that were changed) but this is not strictly required. As an example, if this function is called with the path of "/" then every single key in the application will be notified of a possible change. a #GSettingsBackend implementation the path containing the changes the origin tag Signals that the writability of all keys below a given path may have changed. Since GSettings performs no locking operations for itself, this call will always be made in response to external events. a #GSettingsBackend implementation the name of the path Signals that the writability of a single key has possibly changed. Since GSettings performs no locking operations for itself, this call will always be made in response to external events. a #GSettingsBackend implementation the name of the key Class structure for #GSettingsBackend. virtual method to read a key's value virtual method to get if a key is writable virtual method to change key's value virtual method to change a tree of keys virtual method to reset state virtual method to subscribe to key changes virtual method to unsubscribe to key changes virtual method to sync state virtual method to get permission of a key virtual method to read user's key value Flags used when creating a binding. These flags determine in which direction the binding works. The default is to synchronize in both directions. Equivalent to `G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET` Update the [class@GObject.Object] property when the setting changes. It is an error to use this flag if the property is not writable. Update the setting when the [class@GObject.Object] property changes. It is an error to use this flag if the property is not readable. Do not try to bind a ‘sensitivity’ property to the writability of the setting When set in addition to [flags@Gio.SettingsBindFlags.GET], set the [class@GObject.Object] property value initially from the setting, but do not listen for changes of the setting When passed to [method@Gio.Settings.bind], uses a pair of mapping functions that invert the boolean value when mapping between the setting and the property. The setting and property must both be booleans. You cannot pass this flag to [method@Gio.Settings.bind_with_mapping]. The type for the function that is used to convert from [class@Gio.Settings] to an object property. The @value is already initialized to hold values of the appropriate type. true if the conversion succeeded, false in case of an error return location for the property value variant to map to the property value user data that was specified when the binding was created The type for the function that is used to convert an object property value to a [struct@GLib.Variant] for storing it in [class@Gio.Settings]. a new [struct@GLib.Variant] holding the data from @value, or `NULL` in case of an error the property value to map expected type of the result user data that was specified when the binding was created The type of the function that is used to convert from a value stored in a [class@Gio.Settings] to a value that is useful to the application. If the value is successfully mapped, the result should be stored at @result and true returned. If mapping fails (for example, if @value is not in the right format) then false should be returned. If @value is `NULL` then it means that the mapping function is being given a ‘last chance’ to successfully return a valid value. True must be returned in this case. true if the conversion succeeded, false in case of an error variant to map to the application value the result of the mapping the user data that was passed to [method@Gio.Settings.get_mapped] The [struct@Gio.SettingsSchemaSource] and `GSettingsSchema` APIs provide a mechanism for advanced control over the loading of schemas and a mechanism for introspecting their content. Plugin loading systems that wish to provide plugins a way to access settings face the problem of how to make the schemas for these settings visible to GSettings. Typically, a plugin will want to ship the schema along with itself and it won't be installed into the standard system directories for schemas. [struct@Gio.SettingsSchemaSource] provides a mechanism for dealing with this by allowing the creation of a new ‘schema source’ from which schemas can be acquired. This schema source can then become part of the metadata associated with the plugin and queried whenever the plugin requires access to some settings. Consider the following example: ```c typedef struct { … GSettingsSchemaSource *schema_source; … } Plugin; Plugin * initialise_plugin (const gchar *dir) { Plugin *plugin; … plugin->schema_source = g_settings_schema_source_new_from_directory (dir, g_settings_schema_source_get_default (), FALSE, NULL); … return plugin; } … GSettings * plugin_get_settings (Plugin *plugin, const gchar *schema_id) { GSettingsSchema *schema; if (schema_id == NULL) schema_id = plugin->identifier; schema = g_settings_schema_source_lookup (plugin->schema_source, schema_id, FALSE); if (schema == NULL) { … disable the plugin or abort, etc … } return g_settings_new_full (schema, NULL, NULL); } ``` The code above shows how hooks should be added to the code that initialises (or enables) the plugin to create the schema source and how an API can be added to the plugin system to provide a convenient way for the plugin to access its settings, using the schemas that it ships. From the standpoint of the plugin, it would need to ensure that it ships a gschemas.compiled file as part of itself, and then simply do the following: ```c { GSettings *settings; gint some_value; settings = plugin_get_settings (self, NULL); some_value = g_settings_get_int (settings, "some-value"); … } ``` It's also possible that the plugin system expects the schema source files (ie: `.gschema.xml` files) instead of a `gschemas.compiled` file. In that case, the plugin loading system must compile the schemas for itself before attempting to create the settings source. Get the ID of @schema. the ID a #GSettingsSchema Gets the key named @name from @schema. It is a programmer error to request a key that does not exist. See g_settings_schema_list_keys(). the #GSettingsSchemaKey for @name a #GSettingsSchema the name of a key Gets the path associated with @schema, or %NULL. Schemas may be single-instance or relocatable. Single-instance schemas correspond to exactly one set of keys in the backend database: those located at the path returned by this function. Relocatable schemas can be referenced by other schemas and can therefore describe multiple sets of keys at different locations. For relocatable schemas, this function will return %NULL. the path of the schema, or %NULL a #GSettingsSchema Checks if @schema has a key named @name. %TRUE if such a key exists a #GSettingsSchema the name of a key Gets the list of children in @schema. You should free the return value with g_strfreev() when you are done with it. a list of the children on @settings, in no defined order a #GSettingsSchema Introspects the list of keys on @schema. You should probably not be calling this function from "normal" code (since you should already know what keys are in your schema). This function is intended for introspection reasons. a list of the keys on @schema, in no defined order a #GSettingsSchema Increase the reference count of @schema, returning a new reference. a new reference to @schema a #GSettingsSchema Decrease the reference count of @schema, possibly freeing it. a #GSettingsSchema #GSettingsSchemaKey is an opaque data structure and can only be accessed using the following functions. Gets the default value for @key. Note that this is the default value according to the schema. System administrator defaults and lockdown are not visible via this API. the default value for the key a #GSettingsSchemaKey Gets the description for @key. If no description has been provided in the schema for @key, returns %NULL. The description can be one sentence to several paragraphs in length. Paragraphs are delimited with a double newline. Descriptions can be translated and the value returned from this function is is the current locale. This function is slow. The summary and description information for the schemas is not stored in the compiled schema database so this function has to parse all of the source XML files in the schema directory. the description for @key, or %NULL a #GSettingsSchemaKey Gets the name of @key. the name of @key. a #GSettingsSchemaKey Queries the range of a key. This function will return a #GVariant that fully describes the range of values that are valid for @key. The type of #GVariant returned is `(sv)`. The string describes the type of range restriction in effect. The type and meaning of the value contained in the variant depends on the string. If the string is `'type'` then the variant contains an empty array. The element type of that empty array is the expected type of value and all values of that type are valid. If the string is `'enum'` then the variant contains an array enumerating the possible values. Each item in the array is a possible valid value and no other values are valid. If the string is `'flags'` then the variant contains an array. Each item in the array is a value that may appear zero or one times in an array to be used as the value for this key. For example, if the variant contained the array `['x', 'y']` then the valid values for the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and `['y', 'x']`. Finally, if the string is `'range'` then the variant contains a pair of like-typed values -- the minimum and maximum permissible values for this key. This information should not be used by normal programs. It is considered to be a hint for introspection purposes. Normal programs should already know what is permitted by their own schema. The format may change in any way in the future -- but particularly, new forms may be added to the possibilities described above. You should free the returned value with g_variant_unref() when it is no longer needed. a #GVariant describing the range a #GSettingsSchemaKey Gets the summary for @key. If no summary has been provided in the schema for @key, returns %NULL. The summary is a short description of the purpose of the key; usually one short sentence. Summaries can be translated and the value returned from this function is is the current locale. This function is slow. The summary and description information for the schemas is not stored in the compiled schema database so this function has to parse all of the source XML files in the schema directory. the summary for @key, or %NULL a #GSettingsSchemaKey Gets the #GVariantType of @key. the type of @key a #GSettingsSchemaKey Checks if the given @value is within the permitted range for @key. It is a programmer error if @value is not of the correct type — you must check for this first. %TRUE if @value is valid for @key a #GSettingsSchemaKey the value to check Increase the reference count of @key, returning a new reference. a new reference to @key a #GSettingsSchemaKey Decrease the reference count of @key, possibly freeing it. a #GSettingsSchemaKey This is an opaque structure type. You may not access it directly. Attempts to create a new schema source corresponding to the contents of the given directory. This function is not required for normal uses of #GSettings but it may be useful to authors of plugin management systems. The directory should contain a file called `gschemas.compiled` as produced by the [glib-compile-schemas][glib-compile-schemas] tool. If @trusted is %TRUE then `gschemas.compiled` is trusted not to be corrupted. This assumption has a performance advantage, but can result in crashes or inconsistent behaviour in the case of a corrupted file. Generally, you should set @trusted to %TRUE for files installed by the system and to %FALSE for files in the home directory. In either case, an empty file or some types of corruption in the file will result in %G_FILE_ERROR_INVAL being returned. If @parent is non-%NULL then there are two effects. First, if g_settings_schema_source_lookup() is called with the @recursive flag set to %TRUE and the schema can not be found in the source, the lookup will recurse to the parent. Second, any references to other schemas specified within this source (ie: `child` or `extends`) references may be resolved from the @parent. For this second reason, except in very unusual situations, the @parent should probably be given as the default schema source, as returned by g_settings_schema_source_get_default(). the filename of a directory a #GSettingsSchemaSource, or %NULL %TRUE, if the directory is trusted Lists the schemas in a given source. If @recursive is %TRUE then include parent sources. If %FALSE then only include the schemas from one source (ie: one directory). You probably want %TRUE. Non-relocatable schemas are those for which you can call g_settings_new(). Relocatable schemas are those for which you must use g_settings_new_with_path(). Do not call this function from normal programs. This is designed for use by database editors, commandline tools, etc. a #GSettingsSchemaSource if we should recurse the list of non-relocatable schemas, in no defined order the list of relocatable schemas, in no defined order Looks up a schema with the identifier @schema_id in @source. This function is not required for normal uses of #GSettings but it may be useful to authors of plugin management systems or to those who want to introspect the content of schemas. If the schema isn't found directly in @source and @recursive is %TRUE then the parent sources will also be checked. If the schema isn't found, %NULL is returned. a new #GSettingsSchema a #GSettingsSchemaSource a schema ID %TRUE if the lookup should be recursive Increase the reference count of @source, returning a new reference. a new reference to @source a #GSettingsSchemaSource Decrease the reference count of @source, possibly freeing it. a #GSettingsSchemaSource Gets the default system schema source. This function is not required for normal uses of #GSettings but it may be useful to authors of plugin management systems or to those who want to introspect the content of schemas. If no schemas are installed, %NULL will be returned. The returned source may actually consist of multiple schema sources from different directories, depending on which directories were given in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all lookups performed against the default source should probably be done recursively. the default schema source A `GSimpleAction` is the obvious simple implementation of the [iface@Gio.Action] interface. This is the easiest way to create an action for purposes of adding it to a [class@Gio.SimpleActionGroup]. Creates a new action. The created action is stateless. See g_simple_action_new_stateful() to create an action that has state. a new #GSimpleAction the name of the action the type of parameter that will be passed to handlers for the #GSimpleAction::activate signal, or %NULL for no parameter Creates a new stateful action. All future state values must have the same #GVariantType as the initial @state. If the @state #GVariant is floating, it is consumed. a new #GSimpleAction the name of the action the type of the parameter that will be passed to handlers for the #GSimpleAction::activate signal, or %NULL for no parameter the initial state of the action Sets the action as enabled or not. An action must be enabled in order to be activated or in order to have its state changed from outside callers. This should only be called by the implementor of the action. Users of the action should not attempt to modify its enabled flag. a #GSimpleAction whether the action is enabled Sets the state of the action. This directly updates the 'state' property to the given value. This should only be called by the implementor of the action. Users of the action should not attempt to directly modify the 'state' property. Instead, they should call g_action_change_state() to request the change. If the @value GVariant is floating, it is consumed. a #GSimpleAction the new #GVariant for the state Sets the state hint for the action. See g_action_get_state_hint() for more information about action state hints. a #GSimpleAction a #GVariant representing the state hint If @action is currently enabled. If the action is disabled then calls to g_action_activate() and g_action_change_state() have no effect. The name of the action. This is mostly meaningful for identifying the action once it has been added to a #GSimpleActionGroup. The type of the parameter that must be given when activating the action. The state of the action, or %NULL if the action is stateless. The #GVariantType of the state that the action has, or %NULL if the action is stateless. Indicates that the action was just activated. @parameter will always be of the expected type, i.e. the parameter type specified when the action was created. If an incorrect type is given when activating the action, this signal is not emitted. Since GLib 2.40, if no handler is connected to this signal then the default behaviour for boolean-stated actions with a %NULL parameter type is to toggle them via the #GSimpleAction::change-state signal. For stateful actions where the state type is equal to the parameter type, the default is to forward them directly to #GSimpleAction::change-state. This should allow almost all users of #GSimpleAction to connect only one handler or the other. the parameter to the activation, or %NULL if it has no parameter Indicates that the action just received a request to change its state. @value will always be of the correct state type, i.e. the type of the initial state passed to g_simple_action_new_stateful(). If an incorrect type is given when requesting to change the state, this signal is not emitted. If no handler is connected to this signal then the default behaviour is to call g_simple_action_set_state() to set the state to the requested value. If you connect a signal handler then no default action is taken. If the state should change then you must call g_simple_action_set_state() from the handler. An example of a 'change-state' handler: |[<!-- language="C" --> static void change_volume_state (GSimpleAction *action, GVariant *value, gpointer user_data) { gint requested; requested = g_variant_get_int32 (value); // Volume only goes from 0 to 10 if (0 <= requested && requested <= 10) g_simple_action_set_state (action, value); } ]| The handler need not set the state to the requested value. It could set it to any value at all, or take some other action. the requested value for the state `GSimpleActionGroup` is a hash table filled with [iface@Gio.Action] objects, implementing the [iface@Gio.ActionGroup] and [iface@Gio.ActionMap] interfaces. Creates a new, empty, #GSimpleActionGroup. a new #GSimpleActionGroup A convenience function for creating multiple #GSimpleAction instances and adding them to the action group. Use g_action_map_add_action_entries() a #GSimpleActionGroup a pointer to the first item in an array of #GActionEntry structs the length of @entries, or -1 the user data for signal connections Adds an action to the action group. If the action group already contains an action with the same name as @action then the old action is dropped from the group. The action group takes its own reference on @action. Use g_action_map_add_action() a #GSimpleActionGroup a #GAction Looks up the action with the name @action_name in the group. If no such action exists, returns %NULL. Use g_action_map_lookup_action() a #GAction, or %NULL a #GSimpleActionGroup the name of an action Removes the named action from the action group. If no action of this name is in the group then nothing happens. Use g_action_map_remove_action() a #GSimpleActionGroup the name of the action As of GLib 2.46, `GSimpleAsyncResult` is deprecated in favor of [class@Gio.Task], which provides a simpler API. `GSimpleAsyncResult` implements [iface@Gio.AsyncResult]. `GSimpleAsyncResult` handles [type@Gio.AsyncReadyCallback]s, error reporting, operation cancellation and the final state of an operation, completely transparent to the application. Results can be returned as a pointer e.g. for functions that return data that is collected asynchronously, a boolean value for checking the success or failure of an operation, or a `gssize` for operations which return the number of bytes modified by the operation; all of the simple return cases are covered. Most of the time, an application will not need to know of the details of this API; it is handled transparently, and any necessary operations are handled by [iface@Gio.AsyncResult]’s interface. However, if implementing a new GIO module, for writing language bindings, or for complex applications that need better control of how asynchronous operations are completed, it is important to understand this functionality. `GSimpleAsyncResult`s are tagged with the calling function to ensure that asynchronous functions and their finishing functions are used together correctly. To create a new `GSimpleAsyncResult`, call [ctor@Gio.SimpleAsyncResult.new]. If the result needs to be created for a `GError`, use [ctor@Gio.SimpleAsyncResult.new_from_error] or [ctor@Gio.SimpleAsyncResult.new_take_error]. If a `GError` is not available (e.g. the asynchronous operation doesn’t take a `GError` argument), but the result still needs to be created for an error condition, use [ctor@Gio.SimpleAsyncResult.new_error] (or [method@Gio.SimpleAsyncResult.set_error_va] if your application or binding requires passing a variable argument list directly), and the error can then be propagated through the use of [method@Gio.SimpleAsyncResult.propagate_error]. An asynchronous operation can be made to ignore a cancellation event by calling [method@Gio.SimpleAsyncResult.set_handle_cancellation] with a `GSimpleAsyncResult` for the operation and `FALSE`. This is useful for operations that are dangerous to cancel, such as close (which would cause a leak if cancelled before being run). `GSimpleAsyncResult` can integrate into GLib’s event loop, [type@GLib.MainLoop], or it can use [type@GLib.Thread]s. [method@Gio.SimpleAsyncResult.complete] will finish an I/O task directly from the point where it is called. [method@Gio.SimpleAsyncResult.complete_in_idle] will finish it from an idle handler in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) where the `GSimpleAsyncResult` was created. [method@Gio.SimpleAsyncResult.run_in_thread] will run the job in a separate thread and then use [method@Gio.SimpleAsyncResult.complete_in_idle] to deliver the result. To set the results of an asynchronous function, [method@Gio.SimpleAsyncResult.set_op_res_gpointer], [method@Gio.SimpleAsyncResult.set_op_res_gboolean], and [method@Gio.SimpleAsyncResult.set_op_res_gssize] are provided, setting the operation's result to a `gpointer`, `gboolean`, or `gssize`, respectively. Likewise, to get the result of an asynchronous function, [method@Gio.SimpleAsyncResult.get_op_res_gpointer], [method@Gio.SimpleAsyncResult.get_op_res_gboolean], and [method@Gio.SimpleAsyncResult.get_op_res_gssize] are provided, getting the operation’s result as a `gpointer`, `gboolean`, and `gssize`, respectively. For the details of the requirements implementations must respect, see [iface@Gio.AsyncResult]. A typical implementation of an asynchronous operation using `GSimpleAsyncResult` looks something like this: ```c static void baked_cb (Cake *cake, gpointer user_data) { // In this example, this callback is not given a reference to the cake, // so the GSimpleAsyncResult has to take a reference to it. GSimpleAsyncResult *result = user_data; if (cake == NULL) g_simple_async_result_set_error (result, BAKER_ERRORS, BAKER_ERROR_NO_FLOUR, "Go to the supermarket"); else g_simple_async_result_set_op_res_gpointer (result, g_object_ref (cake), g_object_unref); // In this example, we assume that baked_cb is called as a callback from // the mainloop, so it's safe to complete the operation synchronously here. // If, however, _baker_prepare_cake () might call its callback without // first returning to the mainloop — inadvisable, but some APIs do so — // we would need to use g_simple_async_result_complete_in_idle(). g_simple_async_result_complete (result); g_object_unref (result); } void baker_bake_cake_async (Baker *self, guint radius, GAsyncReadyCallback callback, gpointer user_data) { GSimpleAsyncResult *simple; Cake *cake; if (radius < 3) { g_simple_async_report_error_in_idle (G_OBJECT (self), callback, user_data, BAKER_ERRORS, BAKER_ERROR_TOO_SMALL, "%ucm radius cakes are silly", radius); return; } simple = g_simple_async_result_new (G_OBJECT (self), callback, user_data, baker_bake_cake_async); cake = _baker_get_cached_cake (self, radius); if (cake != NULL) { g_simple_async_result_set_op_res_gpointer (simple, g_object_ref (cake), g_object_unref); g_simple_async_result_complete_in_idle (simple); g_object_unref (simple); // Drop the reference returned by _baker_get_cached_cake(); // the GSimpleAsyncResult has taken its own reference. g_object_unref (cake); return; } _baker_prepare_cake (self, radius, baked_cb, simple); } Cake * baker_bake_cake_finish (Baker *self, GAsyncResult *result, GError **error) { GSimpleAsyncResult *simple; Cake *cake; g_return_val_if_fail (g_simple_async_result_is_valid (result, G_OBJECT (self), baker_bake_cake_async), NULL); simple = (GSimpleAsyncResult *) result; if (g_simple_async_result_propagate_error (simple, error)) return NULL; cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple)); return g_object_ref (cake); } ``` Creates a #GSimpleAsyncResult. The common convention is to create the #GSimpleAsyncResult in the function that starts the asynchronous operation and use that same function as the @source_tag. If your operation supports cancellation with #GCancellable (which it probably should) then you should provide the user's cancellable to g_simple_async_result_set_check_cancellable() immediately after this function returns. Use g_task_new() instead. a #GSimpleAsyncResult. a #GObject, or %NULL. a #GAsyncReadyCallback. user data passed to @callback. the asynchronous function. Creates a new #GSimpleAsyncResult with a set error. Use g_task_new() and g_task_return_new_error() instead. a #GSimpleAsyncResult. a #GObject, or %NULL. a #GAsyncReadyCallback. user data passed to @callback. a #GQuark. an error code. a string with format characters. a list of values to insert into @format. Creates a #GSimpleAsyncResult from an error condition. Use g_task_new() and g_task_return_error() instead. a #GSimpleAsyncResult. a #GObject, or %NULL. a #GAsyncReadyCallback. user data passed to @callback. a #GError Creates a #GSimpleAsyncResult from an error condition, and takes over the caller's ownership of @error, so the caller does not need to free it anymore. Use g_task_new() and g_task_return_error() instead. a #GSimpleAsyncResult a #GObject, or %NULL a #GAsyncReadyCallback. user data passed to @callback. a #GError Ensures that the data passed to the _finish function of an async operation is consistent. Three checks are performed. First, @result is checked to ensure that it is really a #GSimpleAsyncResult. Second, @source is checked to ensure that it matches the source object of @result. Third, @source_tag is checked to ensure that it is equal to the @source_tag argument given to g_simple_async_result_new() (which, by convention, is a pointer to the _async function corresponding to the _finish function from which this function is called). (Alternatively, if either @source_tag or @result's source tag is %NULL, then the source tag check is skipped.) Use #GTask and g_task_is_valid() instead. #TRUE if all checks passed or #FALSE if any failed. the #GAsyncResult passed to the _finish function. the #GObject passed to the _finish function. the asynchronous function. Completes an asynchronous I/O job immediately. Must be called in the thread where the asynchronous result was to be delivered, as it invokes the callback directly. If you are in a different thread use g_simple_async_result_complete_in_idle(). Calling this function takes a reference to @simple for as long as is needed to complete the call. Use #GTask instead. a #GSimpleAsyncResult. Completes an asynchronous function in an idle handler in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread that @simple was initially created in (and re-pushes that context around the invocation of the callback). Calling this function takes a reference to @simple for as long as is needed to complete the call. Use #GTask instead. a #GSimpleAsyncResult. Gets the operation result boolean from within the asynchronous result. Use #GTask and g_task_propagate_boolean() instead. %TRUE if the operation's result was %TRUE, %FALSE if the operation's result was %FALSE. a #GSimpleAsyncResult. Gets a pointer result as returned by the asynchronous function. Use #GTask and g_task_propagate_pointer() instead. a pointer from the result. a #GSimpleAsyncResult. Gets a gssize from the asynchronous result. Use #GTask and g_task_propagate_int() instead. a gssize returned from the asynchronous function. a #GSimpleAsyncResult. Gets the source tag for the #GSimpleAsyncResult. Use #GTask and g_task_get_source_tag() instead. a #gpointer to the source object for the #GSimpleAsyncResult. a #GSimpleAsyncResult. Propagates an error from within the simple asynchronous result to a given destination. If the #GCancellable given to a prior call to g_simple_async_result_set_check_cancellable() is cancelled then this function will return %TRUE with @dest set appropriately. Use #GTask instead. %TRUE if the error was propagated to @dest. %FALSE otherwise. a #GSimpleAsyncResult. Runs the asynchronous job in a separate thread and then calls g_simple_async_result_complete_in_idle() on @simple to return the result to the appropriate main loop. Calling this function takes a reference to @simple for as long as is needed to run the job and report its completion. Use #GTask and g_task_run_in_thread() instead. a #GSimpleAsyncResult. a #GSimpleAsyncThreadFunc. the io priority of the request. optional #GCancellable object, %NULL to ignore. Sets a #GCancellable to check before dispatching results. This function has one very specific purpose: the provided cancellable is checked at the time of g_simple_async_result_propagate_error() If it is cancelled, these functions will return an "Operation was cancelled" error (%G_IO_ERROR_CANCELLED). Implementors of cancellable asynchronous functions should use this in order to provide a guarantee to their callers that cancelling an async operation will reliably result in an error being returned for that operation (even if a positive result for the operation has already been sent as an idle to the main context to be dispatched). The checking described above is done regardless of any call to the unrelated g_simple_async_result_set_handle_cancellation() function. Use #GTask instead. a #GSimpleAsyncResult a #GCancellable to check, or %NULL to unset Sets an error within the asynchronous result without a #GError. Use #GTask and g_task_return_new_error() instead. a #GSimpleAsyncResult. a #GQuark (usually %G_IO_ERROR). an error code. a formatted error reporting string. a list of variables to fill in @format. Sets an error within the asynchronous result without a #GError. Unless writing a binding, see g_simple_async_result_set_error(). Use #GTask and g_task_return_error() instead. a #GSimpleAsyncResult. a #GQuark (usually %G_IO_ERROR). an error code. a formatted error reporting string. va_list of arguments. Sets the result from a #GError. Use #GTask and g_task_return_error() instead. a #GSimpleAsyncResult. #GError. Sets whether to handle cancellation within the asynchronous operation. This function has nothing to do with g_simple_async_result_set_check_cancellable(). It only refers to the #GCancellable passed to g_simple_async_result_run_in_thread(). a #GSimpleAsyncResult. a #gboolean. Sets the operation result to a boolean within the asynchronous result. Use #GTask and g_task_return_boolean() instead. a #GSimpleAsyncResult. a #gboolean. Sets the operation result within the asynchronous result to a pointer. Use #GTask and g_task_return_pointer() instead. a #GSimpleAsyncResult. a pointer result from an asynchronous function. a #GDestroyNotify function. Sets the operation result within the asynchronous result to the given @op_res. Use #GTask and g_task_return_int() instead. a #GSimpleAsyncResult. a #gssize. Sets the result from @error, and takes over the caller's ownership of @error, so the caller does not need to free it any more. Use #GTask and g_task_return_error() instead. a #GSimpleAsyncResult a #GError Simple thread function that runs an asynchronous operation and checks for cancellation. a #GSimpleAsyncResult. a #GObject. optional #GCancellable object, %NULL to ignore. `GSimpleIOStream` creates a [class@Gio.IOStream] from an arbitrary [class@Gio.InputStream] and [class@Gio.OutputStream]. This allows any pair of input and output streams to be used with [class@Gio.IOStream] methods. This is useful when you obtained a [class@Gio.InputStream] and a [class@Gio.OutputStream] by other means, for instance creating them with platform specific methods as [`g_unix_input_stream_new()`](../gio-unix/ctor.UnixInputStream.new.html) (from `gio-unix-2.0.pc` / `GioUnix-2.0`), and you want to take advantage of the methods provided by [class@Gio.IOStream]. Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream. See also #GIOStream. a new #GSimpleIOStream instance. a #GInputStream. a #GOutputStream. The [class@Gio.InputStream] to read from. The [class@Gio.OutputStream] to write to. `GSimplePermission` is a trivial implementation of [class@Gio.Permission] that represents a permission that is either always or never allowed. The value is given at construction and doesn’t change. Calling [method@Gio.Permission.acquire] or [method@Gio.Permission.release] on a `GSimplePermission` will result in errors. Creates a new #GPermission instance that represents an action that is either always or never allowed. the #GSimplePermission, as a #GPermission %TRUE if the action is allowed `GSimpleProxyResolver` is a simple [iface@Gio.ProxyResolver] implementation that handles a single default proxy, multiple URI-scheme-specific proxies, and a list of hosts that proxies should not be used for. `GSimpleProxyResolver` is never the default proxy resolver, but it can be used as the base class for another proxy resolver implementation, or it can be created and used manually, such as with [method@Gio.SocketClient.set_proxy_resolver]. Creates a new #GSimpleProxyResolver. See #GSimpleProxyResolver:default-proxy and #GSimpleProxyResolver:ignore-hosts for more details on how the arguments are interpreted. a new #GSimpleProxyResolver the default proxy to use, eg "socks://192.168.1.1" an optional list of hosts/IP addresses to not use a proxy for. Sets the default proxy on @resolver, to be used for any URIs that don't match #GSimpleProxyResolver:ignore-hosts or a proxy set via g_simple_proxy_resolver_set_uri_proxy(). If @default_proxy starts with "socks://", #GSimpleProxyResolver will treat it as referring to all three of the socks5, socks4a, and socks4 proxy types. a #GSimpleProxyResolver the default proxy to use Sets the list of ignored hosts. See #GSimpleProxyResolver:ignore-hosts for more details on how the @ignore_hosts argument is interpreted. a #GSimpleProxyResolver %NULL-terminated list of hosts/IP addresses to not use a proxy for Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme matches @uri_scheme (and which don't match #GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy. As with #GSimpleProxyResolver:default-proxy, if @proxy starts with "socks://", #GSimpleProxyResolver will treat it as referring to all three of the socks5, socks4a, and socks4 proxy types. a #GSimpleProxyResolver the URI scheme to add a proxy for the proxy to use for @uri_scheme The default proxy URI that will be used for any URI that doesn't match #GSimpleProxyResolver:ignore-hosts, and doesn't match any of the schemes set with g_simple_proxy_resolver_set_uri_proxy(). Note that as a special case, if this URI starts with "socks://", #GSimpleProxyResolver will treat it as referring to all three of the socks5, socks4a, and socks4 proxy types. A list of hostnames and IP addresses that the resolver should allow direct connections to. Entries can be in one of 4 formats: - A hostname, such as "example.com", ".example.com", or "*.example.com", any of which match "example.com" or any subdomain of it. - An IPv4 or IPv6 address, such as "192.168.1.1", which matches only that address. - A hostname or IP address followed by a port, such as "example.com:80", which matches whatever the hostname or IP address would match, but only for URLs with the (explicitly) indicated port. In the case of an IPv6 address, the address part must appear in brackets: "[::1]:443" - An IP address range, given by a base address and prefix length, such as "fe80::/10", which matches any address in that range. Note that when dealing with Unicode hostnames, the matching is done against the ASCII form of the name. Also note that hostname exclusions apply only to connections made to hosts identified by name, and IP address exclusions apply only to connections made to hosts identified by address. That is, if example.com has an address of 192.168.1.1, and the :ignore-hosts list contains only "192.168.1.1", then a connection to "example.com" (eg, via a #GNetworkAddress) will use the proxy, and a connection to "192.168.1.1" (eg, via a #GInetSocketAddress) will not. These rules match the "ignore-hosts"/"noproxy" rules most commonly used by other applications. A `GSocket` is a low-level networking primitive. It is a more or less direct mapping of the BSD socket API in a portable GObject based API. It supports both the UNIX socket implementations and winsock2 on Windows. `GSocket` is the platform independent base upon which the higher level network primitives are based. Applications are not typically meant to use it directly, but rather through classes like [class@Gio.SocketClient], [class@Gio.SocketService] and [class@Gio.SocketConnection]. However there may be cases where direct use of `GSocket` is useful. `GSocket` implements the [iface@Gio.Initable] interface, so if it is manually constructed by e.g. [ctor@GObject.Object.new] you must call [method@Gio.Initable.init] and check the results before using the object. This is done automatically in [ctor@Gio.Socket.new] and [ctor@Gio.Socket.new_from_fd], so these functions can return `NULL`. Sockets operate in two general modes, blocking or non-blocking. When in blocking mode all operations (which don’t take an explicit blocking parameter) block until the requested operation is finished or there is an error. In non-blocking mode all calls that would block return immediately with a `G_IO_ERROR_WOULD_BLOCK` error. To know when a call would successfully run you can call [method@Gio.Socket.condition_check], or [method@Gio.Socket.condition_wait]. You can also use [method@Gio.Socket.create_source] and attach it to a [type@GLib.MainContext] to get callbacks when I/O is possible. Note that all sockets are always set to non blocking mode in the system, and blocking mode is emulated in `GSocket`. When working in non-blocking mode applications should always be able to handle getting a `G_IO_ERROR_WOULD_BLOCK` error even when some other function said that I/O was possible. This can easily happen in case of a race condition in the application, but it can also happen for other reasons. For instance, on Windows a socket is always seen as writable until a write returns `G_IO_ERROR_WOULD_BLOCK`. `GSocket`s can be either connection oriented or datagram based. For connection oriented types you must first establish a connection by either connecting to an address or accepting a connection from another address. For connectionless socket types the target/source address is specified or received in each I/O operation. All socket file descriptors are set to be close-on-exec. Note that creating a `GSocket` causes the signal `SIGPIPE` to be ignored for the remainder of the program. If you are writing a command-line utility that uses `GSocket`, you may need to take into account the fact that your program will not automatically be killed if it tries to write to `stdout` after it has been closed. Like most other APIs in GLib, `GSocket` is not inherently thread safe. To use a `GSocket` concurrently from multiple threads, you must implement your own locking. ## Nagle’s algorithm Since GLib 2.80, `GSocket` will automatically set the `TCP_NODELAY` option on all `G_SOCKET_TYPE_STREAM` sockets. This disables [Nagle’s algorithm](https://en.wikipedia.org/wiki/Nagle%27s_algorithm) as it typically does more harm than good on modern networks. If your application needs Nagle’s algorithm enabled, call [method@Gio.Socket.set_option] after constructing a `GSocket` to enable it: ```c socket = g_socket_new (…, G_SOCKET_TYPE_STREAM, …); if (socket != NULL) { g_socket_set_option (socket, IPPROTO_TCP, TCP_NODELAY, FALSE, &local_error); // handle error if needed } ``` Creates a new #GSocket with the defined family, type and protocol. If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type for the family and type is used. The @protocol is a family and type specific int that specifies what kind of protocol to use. #GSocketProtocol lists several common ones. Many families only support one protocol, and use 0 for this, others support several and using 0 means to use the default protocol for the family and type. The protocol id is passed directly to the operating system, so you can use protocols not listed in #GSocketProtocol if you know the protocol number used for it. a #GSocket or %NULL on error. Free the returned object with g_object_unref(). the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4. the socket type to use. the id of the protocol to use, or 0 for default. Creates a new #GSocket from a native file descriptor or winsock SOCKET handle. This reads all the settings from the file descriptor so that all properties should work. Note that the file descriptor will be set to non-blocking mode, independent on the blocking mode of the #GSocket. On success, the returned #GSocket takes ownership of @fd. On failure, the caller must close @fd themselves. Since GLib 2.46, it is no longer a fatal error to call this on a non-socket descriptor. Instead, a GError will be set with code %G_IO_ERROR_FAILED a #GSocket or %NULL on error. Free the returned object with g_object_unref(). a native socket file descriptor. Accept incoming connections on a connection-based socket. This removes the first outstanding connection request from the listening socket and creates a #GSocket object for it. The @socket must be bound to a local address with g_socket_bind() and must be listening for incoming connections (g_socket_listen()). If there are no outstanding connections then the operation will block or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled. To be notified of an incoming connection, wait for the %G_IO_IN condition. a new #GSocket, or %NULL on error. Free the returned object with g_object_unref(). a #GSocket. a %GCancellable or %NULL When a socket is created it is attached to an address family, but it doesn't have an address in this family. g_socket_bind() assigns the address (sometimes called name) of the socket. It is generally required to bind to a local address before you can receive connections. (See g_socket_listen() and g_socket_accept() ). In certain situations, you may also want to bind a socket that will be used to initiate connections, though this is not normally required. If @socket is a TCP socket, then @allow_reuse controls the setting of the `SO_REUSEADDR` socket option; normally it should be %TRUE for server sockets (sockets that you will eventually call g_socket_accept() on), and %FALSE for client sockets. (Failing to set this flag on a server socket may cause g_socket_bind() to return %G_IO_ERROR_ADDRESS_IN_USE if the server program is stopped and then immediately restarted.) If @socket is a UDP socket, then @allow_reuse determines whether or not other UDP sockets can be bound to the same address at the same time. In particular, you can have several UDP sockets bound to the same address, and they will all receive all of the multicast and broadcast packets sent to that address. (The behavior of unicast UDP packets to an address with multiple listeners is not defined.) %TRUE on success, %FALSE on error. a #GSocket. a #GSocketAddress specifying the local address. whether to allow reusing this address Checks and resets the pending connect error for the socket. This is used to check for errors when g_socket_connect() is used in non-blocking mode. %TRUE if no error, %FALSE otherwise, setting @error to the error a #GSocket Closes the socket, shutting down any active connection. Closing a socket does not wait for all outstanding I/O operations to finish, so the caller should not rely on them to be guaranteed to complete even if the close returns with no error. Once the socket is closed, all other operations will return %G_IO_ERROR_CLOSED. Closing a socket multiple times will not return an error. Sockets will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. Beware that due to the way that TCP works, it is possible for recently-sent data to be lost if either you close a socket while the %G_IO_IN condition is set, or else if the remote connection tries to send something to you after you close the socket but before it has finished reading all of the data you sent. There is no easy generic way to avoid this problem; the easiest fix is to design the network protocol such that the client will never send data "out of turn". Another solution is for the server to half-close the connection by calling g_socket_shutdown() with only the @shutdown_write flag set, and then wait for the client to notice this and close its side of the connection, after which the server can safely call g_socket_close(). (This is what #GTcpConnection does if you call g_tcp_connection_set_graceful_disconnect(). But of course, this only works if the client will close its connection after the server does.) %TRUE on success, %FALSE on error a #GSocket Checks on the readiness of @socket to perform operations. The operations specified in @condition are checked for and masked against the currently-satisfied conditions on @socket. The result is returned. Note that on Windows, it is possible for an operation to return %G_IO_ERROR_WOULD_BLOCK even immediately after g_socket_condition_check() has claimed that the socket is ready for writing. Rather than calling g_socket_condition_check() and then writing to the socket if it succeeds, it is generally better to simply try writing to the socket right away, and try again later if the initial attempt returns %G_IO_ERROR_WOULD_BLOCK. It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition; these conditions will always be set in the output if they are true. This call never blocks. the @GIOCondition mask of the current state a #GSocket a #GIOCondition mask to check Waits for up to @timeout_us microseconds for @condition to become true on @socket. If the condition is met, %TRUE is returned. If @cancellable is cancelled before the condition is met, or if @timeout_us (or the socket's #GSocket:timeout) is reached before the condition is met, then %FALSE is returned and @error, if non-%NULL, is set to the appropriate value (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). If you don't want a timeout, use g_socket_condition_wait(). (Alternatively, you can pass -1 for @timeout_us.) Note that although @timeout_us is in microseconds for consistency with other GLib APIs, this function actually only has millisecond resolution, and the behavior is undefined if @timeout_us is not an exact number of milliseconds. %TRUE if the condition was met, %FALSE otherwise a #GSocket a #GIOCondition mask to wait for the maximum time (in microseconds) to wait, or -1 a #GCancellable, or %NULL Waits for @condition to become true on @socket. When the condition is met, %TRUE is returned. If @cancellable is cancelled before the condition is met, or if the socket has a timeout set and it is reached before the condition is met, then %FALSE is returned and @error, if non-%NULL, is set to the appropriate value (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). See also g_socket_condition_timed_wait(). %TRUE if the condition was met, %FALSE otherwise a #GSocket a #GIOCondition mask to wait for a #GCancellable, or %NULL Connect the socket to the specified remote address. For connection oriented socket this generally means we attempt to make a connection to the @address. For a connection-less socket it sets the default address for g_socket_send() and discards all incoming datagrams from other sources. Generally connection oriented sockets can only connect once, but connection-less sockets can connect multiple times to change the default address. If the connect call needs to do network I/O it will block, unless non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned and the user can be notified of the connection finishing by waiting for the G_IO_OUT condition. The result of the connection must then be checked with g_socket_check_connect_result(). %TRUE if connected, %FALSE on error. a #GSocket. a #GSocketAddress specifying the remote address. a %GCancellable or %NULL Creates a #GSocketConnection subclass of the right type for @socket. a #GSocketConnection a #GSocket Creates a #GSource that can be attached to a %GMainContext to monitor for the availability of the specified @condition on the socket. The #GSource keeps a reference to the @socket. The callback on the source is of the #GSocketSourceFunc type. It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these conditions will always be reported output if they are true. @cancellable if not %NULL can be used to cancel the source, which will cause the source to trigger, reporting the current condition (which is likely 0 unless cancellation happened at the same time as a condition change). You can check for this in the callback using g_cancellable_is_cancelled(). If @socket has a timeout set, and it is reached before @condition occurs, the source will then trigger anyway, reporting %G_IO_IN or %G_IO_OUT depending on @condition. However, @socket will have been marked as having had a timeout, and so the next #GSocket I/O method you call will then fail with a %G_IO_ERROR_TIMED_OUT. a newly allocated %GSource, free with g_source_unref(). a #GSocket a #GIOCondition mask to monitor a %GCancellable or %NULL Get the amount of data pending in the OS input buffer, without blocking. If @socket is a UDP or SCTP socket, this will return the size of just the next packet, even if additional packets are buffered after that one. Note that on Windows, this function is rather inefficient in the UDP case, and so if you know any plausible upper bound on the size of the incoming packet, it is better to just do a g_socket_receive() with a buffer of that size, rather than calling g_socket_get_available_bytes() first and then doing a receive of exactly the right size. the number of bytes that can be read from the socket without blocking or truncating, or -1 on error. a #GSocket Gets the blocking mode of the socket. For details on blocking I/O, see g_socket_set_blocking(). %TRUE if blocking I/O is used, %FALSE otherwise. a #GSocket. Gets the broadcast setting on @socket; if %TRUE, it is possible to send packets to broadcast addresses. the broadcast setting on @socket a #GSocket. Returns the credentials of the foreign process connected to this socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX sockets). If this operation isn't supported on the OS, the method fails with the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented by reading the %SO_PEERCRED option on the underlying socket. This method can be expected to be available on the following platforms: - Linux since GLib 2.26 - OpenBSD since GLib 2.30 - Solaris, Illumos and OpenSolaris since GLib 2.40 - NetBSD since GLib 2.42 - macOS, tvOS, iOS since GLib 2.66 Other ways to obtain credentials from a foreign peer includes the #GUnixCredentialsMessage type and g_unix_connection_send_credentials() / g_unix_connection_receive_credentials() functions. %NULL if @error is set, otherwise a #GCredentials object that must be freed with g_object_unref(). a #GSocket. Gets the socket family of the socket. a #GSocketFamily a #GSocket. Returns the underlying OS socket object. On unix this is a socket file descriptor, and on Windows this is a Winsock2 SOCKET handle. This may be useful for doing platform specific or otherwise unusual operations on the socket. the file descriptor of the socket. a #GSocket. Gets the keepalive mode of the socket. For details on this, see g_socket_set_keepalive(). %TRUE if keepalive is active, %FALSE otherwise. a #GSocket. Gets the listen backlog setting of the socket. For details on this, see g_socket_set_listen_backlog(). the maximum number of pending connections. a #GSocket. Try to get the local address of a bound socket. This is only useful if the socket has been bound to a local address, either explicitly or implicitly when connecting. a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). a #GSocket. Gets the multicast loopback setting on @socket; if %TRUE (the default), outgoing multicast packets will be looped back to multicast listeners on the same host. the multicast loopback setting on @socket a #GSocket. Gets the multicast time-to-live setting on @socket; see g_socket_set_multicast_ttl() for more details. the multicast time-to-live setting on @socket a #GSocket. Gets the value of an integer-valued option on @socket, as with getsockopt(). (If you need to fetch a non-integer-valued option, you will need to call getsockopt() directly.) The [`<gio/gnetworking.h>`](networking.html) header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional headers. Note that even for socket options that are a single byte in size, @value is still a pointer to a #gint variable, not a #guchar; g_socket_get_option() will handle the conversion internally. success or failure. On failure, @error will be set, and the system error value (`errno` or WSAGetLastError()) will still be set to the result of the getsockopt() call. a #GSocket the "API level" of the option (eg, `SOL_SOCKET`) the "name" of the option (eg, `SO_BROADCAST`) return location for the option value Gets the socket protocol id the socket was created with. In case the protocol is unknown, -1 is returned. a protocol id, or -1 if unknown a #GSocket. Try to get the remote address of a connected socket. This is only useful for connection oriented sockets that have been connected. a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). a #GSocket. Gets the socket type of the socket. a #GSocketType a #GSocket. Gets the timeout setting of the socket. For details on this, see g_socket_set_timeout(). the timeout in seconds a #GSocket. Gets the unicast time-to-live setting on @socket; see g_socket_set_ttl() for more details. the time-to-live setting on @socket a #GSocket. Checks whether a socket is closed. %TRUE if socket is closed, %FALSE otherwise a #GSocket Check whether the socket is connected. This is only useful for connection-oriented sockets. If using g_socket_shutdown(), this function will return %TRUE until the socket has been shut down for reading and writing. If you do a non-blocking connect, this function will not return %TRUE until after you call g_socket_check_connect_result(). %TRUE if socket is connected, %FALSE otherwise. a #GSocket. Registers @socket to receive multicast messages sent to @group. @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have been bound to an appropriate interface and port with g_socket_bind(). If @iface is %NULL, the system will automatically pick an interface to bind to based on @group. If @source_specific is %TRUE, source-specific multicast as defined in RFC 4604 is used. Note that on older platforms this may fail with a %G_IO_ERROR_NOT_SUPPORTED error. To bind to a given source-specific multicast address, use g_socket_join_multicast_group_ssm() instead. %TRUE on success, %FALSE on error. a #GSocket. a #GInetAddress specifying the group address to join. %TRUE if source-specific multicast should be used Name of the interface to use, or %NULL Registers @socket to receive multicast messages sent to @group. @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have been bound to an appropriate interface and port with g_socket_bind(). If @iface is %NULL, the system will automatically pick an interface to bind to based on @group. If @source_specific is not %NULL, use source-specific multicast as defined in RFC 4604. Note that on older platforms this may fail with a %G_IO_ERROR_NOT_SUPPORTED error. Note that this function can be called multiple times for the same @group with different @source_specific in order to receive multicast packets from more than one source. %TRUE on success, %FALSE on error. a #GSocket. a #GInetAddress specifying the group address to join. a #GInetAddress specifying the source-specific multicast address or %NULL to ignore. Name of the interface to use, or %NULL Removes @socket from the multicast group defined by @group, @iface, and @source_specific (which must all have the same values they had when you joined the group). @socket remains bound to its address and port, and can still receive unicast messages after calling this. To unbind to a given source-specific multicast address, use g_socket_leave_multicast_group_ssm() instead. %TRUE on success, %FALSE on error. a #GSocket. a #GInetAddress specifying the group address to leave. %TRUE if source-specific multicast was used Interface used Removes @socket from the multicast group defined by @group, @iface, and @source_specific (which must all have the same values they had when you joined the group). @socket remains bound to its address and port, and can still receive unicast messages after calling this. %TRUE on success, %FALSE on error. a #GSocket. a #GInetAddress specifying the group address to leave. a #GInetAddress specifying the source-specific multicast address or %NULL to ignore. Name of the interface to use, or %NULL Marks the socket as a server socket, i.e. a socket that is used to accept incoming requests using g_socket_accept(). Before calling this the socket must be bound to a local address using g_socket_bind(). To set the maximum amount of outstanding clients, use g_socket_set_listen_backlog(). %TRUE on success, %FALSE on error. a #GSocket. Receive data (up to @size bytes) from a socket. This is mainly used by connection-oriented sockets; it is identical to g_socket_receive_from() with @address set to %NULL. For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets, g_socket_receive() will always read either 0 or 1 complete messages from the socket. If the received message is too large to fit in @buffer, then the data beyond @size bytes will be discarded, without any explicit indication that this has occurred. For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any number of bytes, up to @size. If more than @size bytes have been received, the additional data will be returned in future calls to g_socket_receive(). If the socket is in blocking mode the call will block until there is some data to receive, the connection is closed, or there is an error. If there is no data available and the socket is in non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be returned. To be notified when data is available, wait for the %G_IO_IN condition. On error -1 is returned and @error is set accordingly. Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error a #GSocket a buffer to read data into (which should be at least @size bytes long). the number of bytes you want to read from the socket a %GCancellable or %NULL Receives data (up to @size bytes) from a socket. This function is a variant of [method@Gio.Socket.receive] which returns a [struct@GLib.Bytes] rather than a plain buffer. Pass `-1` to @timeout_us to block indefinitely until data is received (or the connection is closed, or there is an error). Pass `0` to use the default timeout from [property@Gio.Socket:timeout], or pass a positive number to wait for that many microseconds for data before returning `G_IO_ERROR_TIMED_OUT`. a bytes buffer containing the received bytes, or `NULL` on error a #GSocket the number of bytes you want to read from the socket the timeout to wait for, in microseconds, or `-1` to block indefinitely a %GCancellable, or `NULL` Receive data (up to @size bytes) from a socket. This function is a variant of [method@Gio.Socket.receive_from] which returns a [struct@GLib.Bytes] rather than a plain buffer. If @address is non-%NULL then @address will be set equal to the source address of the received packet. The @address is owned by the caller. Pass `-1` to @timeout_us to block indefinitely until data is received (or the connection is closed, or there is an error). Pass `0` to use the default timeout from [property@Gio.Socket:timeout], or pass a positive number to wait for that many microseconds for data before returning `G_IO_ERROR_TIMED_OUT`. a bytes buffer containing the received bytes, or `NULL` on error a #GSocket return location for a #GSocketAddress the number of bytes you want to read from the socket the timeout to wait for, in microseconds, or `-1` to block indefinitely a #GCancellable, or `NULL` Receive data (up to @size bytes) from a socket. If @address is non-%NULL then @address will be set equal to the source address of the received packet. @address is owned by the caller. See g_socket_receive() for additional information. Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error a #GSocket a pointer to a #GSocketAddress pointer, or %NULL a buffer to read data into (which should be at least @size bytes long). the number of bytes you want to read from the socket a %GCancellable or %NULL Receive data from a socket. For receiving multiple messages, see g_socket_receive_messages(); for easier use, see g_socket_receive() and g_socket_receive_from(). If @address is non-%NULL then @address will be set equal to the source address of the received packet. @address is owned by the caller. @vector must point to an array of #GInputVector structs and @num_vectors must be the length of this array. These structs describe the buffers that received data will be scattered into. If @num_vectors is -1, then @vectors is assumed to be terminated by a #GInputVector with a %NULL buffer pointer. As a special case, if @num_vectors is 0 (in which case, @vectors may of course be %NULL), then a single byte is received and discarded. This is to facilitate the common practice of sending a single '\0' byte for the purposes of transferring ancillary data. @messages, if non-%NULL, will be set to point to a newly-allocated array of #GSocketControlMessage instances or %NULL if no such messages was received. These correspond to the control messages received from the kernel, one #GSocketControlMessage per message from the kernel. This array is %NULL-terminated and must be freed by the caller using g_free() after calling g_object_unref() on each element. If @messages is %NULL, any control messages received will be discarded. @num_messages, if non-%NULL, will be set to the number of control messages received. If both @messages and @num_messages are non-%NULL, then @num_messages gives the number of #GSocketControlMessage instances in @messages (ie: not including the %NULL terminator). @flags is an in/out parameter. The commonly available arguments for this are available in the #GSocketMsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too (and g_socket_receive_message() may pass system-specific flags out). Flags passed in to the parameter affect the receive operation; flags returned out of it are relevant to the specific returned message. As with g_socket_receive(), data may be discarded if @socket is %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not provide enough buffer space to read a complete message. You can pass %G_SOCKET_MSG_PEEK in @flags to peek at the current message without removing it from the receive queue, but there is no portable way to find out the length of the message other than by reading it into a sufficiently-large buffer. If the socket is in blocking mode the call will block until there is some data to receive, the connection is closed, or there is an error. If there is no data available and the socket is in non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be returned. To be notified when data is available, wait for the %G_IO_IN condition. On error -1 is returned and @error is set accordingly. Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error a #GSocket a pointer to a #GSocketAddress pointer, or %NULL an array of #GInputVector structs the number of elements in @vectors, or -1 a pointer which may be filled with an array of #GSocketControlMessages, or %NULL a pointer which will be filled with the number of elements in @messages, or %NULL a pointer to an int containing #GSocketMsgFlags flags, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) a %GCancellable or %NULL Receive multiple data messages from @socket in one go. This is the most complicated and fully-featured version of this call. For easier use, see g_socket_receive(), g_socket_receive_from(), and g_socket_receive_message(). @messages must point to an array of #GInputMessage structs and @num_messages must be the length of this array. Each #GInputMessage contains a pointer to an array of #GInputVector structs describing the buffers that the data received in each message will be written to. Using multiple #GInputVectors is more memory-efficient than manually copying data out of a single buffer to multiple sources, and more system-call-efficient than making multiple calls to g_socket_receive(), such as in scenarios where a lot of data packets need to be received (e.g. high-bandwidth video streaming over RTP/UDP). @flags modify how all messages are received. The commonly available arguments for this are available in the #GSocketMsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. These flags affect the overall receive operation. Flags affecting individual messages are returned in #GInputMessage.flags. The other members of #GInputMessage are treated as described in its documentation. If #GSocket:blocking is %TRUE the call will block until @num_messages have been received, or the end of the stream is reached. If #GSocket:blocking is %FALSE the call will return up to @num_messages without blocking, or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system to be received. In blocking mode, if #GSocket:timeout is positive and is reached before any messages are received, %G_IO_ERROR_TIMED_OUT is returned, otherwise up to @num_messages are returned. (Note: This is effectively the behaviour of `MSG_WAITFORONE` with recvmmsg().) To be notified when messages are available, wait for the %G_IO_IN condition. Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from g_socket_receive_messages() even if you were previously notified of a %G_IO_IN condition. If the remote peer closes the connection, any messages queued in the operating system will be returned, and subsequent calls to g_socket_receive_messages() will return 0 (with no error set). On error -1 is returned and @error is set accordingly. An error will only be returned if zero messages could be received; otherwise the number of messages successfully received before the error will be returned. number of messages received, or -1 on error. Note that the number of messages received may be smaller than @num_messages if in non-blocking mode, if the peer closed the connection, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try to receive the remaining messages. a #GSocket an array of #GInputMessage structs the number of elements in @messages an int containing #GSocketMsgFlags flags for the overall operation, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) a %GCancellable or %NULL This behaves exactly the same as g_socket_receive(), except that the choice of blocking or non-blocking behavior is determined by the @blocking argument rather than by @socket's properties. Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error a #GSocket a buffer to read data into (which should be at least @size bytes long). the number of bytes you want to read from the socket whether to do blocking or non-blocking I/O a %GCancellable or %NULL Tries to send @size bytes from @buffer on the socket. This is mainly used by connection-oriented sockets; it is identical to g_socket_send_to() with @address set to %NULL. If the socket is in blocking mode the call will block until there is space for the data in the socket queue. If there is no space available and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error will be returned. To be notified when space is available, wait for the %G_IO_OUT condition. Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously notified of a %G_IO_OUT condition. (On Windows in particular, this is very common due to the way the underlying APIs work.) On error -1 is returned and @error is set accordingly. Number of bytes written (which may be less than @size), or -1 on error a #GSocket the buffer containing the data to send. the number of bytes to send a %GCancellable or %NULL Send data to @address on @socket. For sending multiple messages see g_socket_send_messages(); for easier use, see g_socket_send() and g_socket_send_to(). If @address is %NULL then the message is sent to the default receiver (set by g_socket_connect()). @vectors must point to an array of #GOutputVector structs and @num_vectors must be the length of this array. (If @num_vectors is -1, then @vectors is assumed to be terminated by a #GOutputVector with a %NULL buffer pointer.) The #GOutputVector structs describe the buffers that the sent data will be gathered from. Using multiple #GOutputVectors is more memory-efficient than manually copying data from multiple sources into a single buffer, and more network-efficient than making multiple calls to g_socket_send(). @messages, if non-%NULL, is taken to point to an array of @num_messages #GSocketControlMessage instances. These correspond to the control messages to be sent on the socket. If @num_messages is -1 then @messages is treated as a %NULL-terminated array. @flags modify how the message is sent. The commonly available arguments for this are available in the #GSocketMsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. If the socket is in blocking mode the call will block until there is space for the data in the socket queue. If there is no space available and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error will be returned. To be notified when space is available, wait for the %G_IO_OUT condition. Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously notified of a %G_IO_OUT condition. (On Windows in particular, this is very common due to the way the underlying APIs work.) The sum of the sizes of each #GOutputVector in vectors must not be greater than %G_MAXSSIZE. If the message can be larger than this, then it is mandatory to use the g_socket_send_message_with_timeout() function. On error -1 is returned and @error is set accordingly. Number of bytes written (which may be less than @size), or -1 on error a #GSocket a #GSocketAddress, or %NULL an array of #GOutputVector structs the number of elements in @vectors, or -1 a pointer to an array of #GSocketControlMessages, or %NULL. number of elements in @messages, or -1. an int containing #GSocketMsgFlags flags, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) a %GCancellable or %NULL This behaves exactly the same as g_socket_send_message(), except that the choice of timeout behavior is determined by the @timeout_us argument rather than by @socket's properties. On error %G_POLLABLE_RETURN_FAILED is returned and @error is set accordingly, or if the socket is currently not writable %G_POLLABLE_RETURN_WOULD_BLOCK is returned. @bytes_written will contain 0 in both cases. %G_POLLABLE_RETURN_OK if all data was successfully written, %G_POLLABLE_RETURN_WOULD_BLOCK if the socket is currently not writable, or %G_POLLABLE_RETURN_FAILED if an error happened and @error is set. a #GSocket a #GSocketAddress, or %NULL an array of #GOutputVector structs the number of elements in @vectors, or -1 a pointer to an array of #GSocketControlMessages, or %NULL. number of elements in @messages, or -1. an int containing #GSocketMsgFlags flags, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) the maximum time (in microseconds) to wait, or -1 location to store the number of bytes that were written to the socket a %GCancellable or %NULL Send multiple data messages from @socket in one go. This is the most complicated and fully-featured version of this call. For easier use, see g_socket_send(), g_socket_send_to(), and g_socket_send_message(). @messages must point to an array of #GOutputMessage structs and @num_messages must be the length of this array. Each #GOutputMessage contains an address to send the data to, and a pointer to an array of #GOutputVector structs to describe the buffers that the data to be sent for each message will be gathered from. Using multiple #GOutputVectors is more memory-efficient than manually copying data from multiple sources into a single buffer, and more network-efficient than making multiple calls to g_socket_send(). Sending multiple messages in one go avoids the overhead of making a lot of syscalls in scenarios where a lot of data packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP), or where the same data needs to be sent to multiple recipients. @flags modify how the message is sent. The commonly available arguments for this are available in the #GSocketMsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. If the socket is in blocking mode the call will block until there is space for all the data in the socket queue. If there is no space available and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error will be returned if no data was written at all, otherwise the number of messages sent will be returned. To be notified when space is available, wait for the %G_IO_OUT condition. Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously notified of a %G_IO_OUT condition. (On Windows in particular, this is very common due to the way the underlying APIs work.) On error -1 is returned and @error is set accordingly. An error will only be returned if zero messages could be sent; otherwise the number of messages successfully sent before the error will be returned. number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than @num_messages if the socket is non-blocking or if @num_messages was larger than UIO_MAXIOV (1024), in which case the caller may re-try to send the remaining messages. a #GSocket an array of #GOutputMessage structs the number of elements in @messages an int containing #GSocketMsgFlags flags, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) a %GCancellable or %NULL Tries to send @size bytes from @buffer to @address. If @address is %NULL then the message is sent to the default receiver (set by g_socket_connect()). See g_socket_send() for additional information. Number of bytes written (which may be less than @size), or -1 on error a #GSocket a #GSocketAddress, or %NULL the buffer containing the data to send. the number of bytes to send a %GCancellable or %NULL This behaves exactly the same as g_socket_send(), except that the choice of blocking or non-blocking behavior is determined by the @blocking argument rather than by @socket's properties. Number of bytes written (which may be less than @size), or -1 on error a #GSocket the buffer containing the data to send. the number of bytes to send whether to do blocking or non-blocking I/O a %GCancellable or %NULL Sets the blocking mode of the socket. In blocking mode all operations (which don’t take an explicit blocking parameter) block until they succeed or there is an error. In non-blocking mode all functions return results immediately or with a %G_IO_ERROR_WOULD_BLOCK error. All sockets are created in blocking mode. However, note that the platform level socket is always non-blocking, and blocking mode is a GSocket level feature. a #GSocket. Whether to use blocking I/O or not. Sets whether @socket should allow sending to broadcast addresses. This is %FALSE by default. a #GSocket. whether @socket should allow sending to broadcast addresses Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When this flag is set on a socket, the system will attempt to verify that the remote socket endpoint is still present if a sufficiently long period of time passes with no data being exchanged. If the system is unable to verify the presence of the remote endpoint, it will automatically close the connection. This option is only functional on certain kinds of sockets. (Notably, %G_SOCKET_PROTOCOL_TCP sockets.) The exact time between pings is system- and protocol-dependent, but will normally be at least two hours. Most commonly, you would set this flag on a server socket if you want to allow clients to remain idle for long periods of time, but also want to ensure that connections are eventually garbage-collected if clients crash or become unreachable. a #GSocket. Value for the keepalive flag Sets the maximum number of outstanding connections allowed when listening on this socket. If more clients than this are connecting to the socket and the application is not handling them on time then the new connections will be refused. Note that this must be called before g_socket_listen() and has no effect if called after that. a #GSocket. the maximum number of pending connections. Sets whether outgoing multicast packets will be received by sockets listening on that multicast address on the same host. This is %TRUE by default. a #GSocket. whether @socket should receive messages sent to its multicast groups from the local host Sets the time-to-live for outgoing multicast datagrams on @socket. By default, this is 1, meaning that multicast packets will not leave the local network. a #GSocket. the time-to-live value for all multicast datagrams on @socket Sets the value of an integer-valued option on @socket, as with setsockopt(). (If you need to set a non-integer-valued option, you will need to call setsockopt() directly.) The [`<gio/gnetworking.h>`](networking.html) header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional headers. success or failure. On failure, @error will be set, and the system error value (`errno` or WSAGetLastError()) will still be set to the result of the setsockopt() call. a #GSocket the "API level" of the option (eg, `SOL_SOCKET`) the "name" of the option (eg, `SO_BROADCAST`) the value to set the option to Sets the time in seconds after which I/O operations on @socket will time out if they have not yet completed. On a blocking socket, this means that any blocking #GSocket operation will time out after @timeout seconds of inactivity, returning %G_IO_ERROR_TIMED_OUT. On a non-blocking socket, calls to g_socket_condition_wait() will also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources created with g_socket_create_source() will trigger after @timeout seconds of inactivity, with the requested condition set, at which point calling g_socket_receive(), g_socket_send(), g_socket_check_connect_result(), etc, will fail with %G_IO_ERROR_TIMED_OUT. If @timeout is 0 (the default), operations will never time out on their own. Note that if an I/O operation is interrupted by a signal, this may cause the timeout to be reset. a #GSocket. the timeout for @socket, in seconds, or 0 for none Sets the time-to-live for outgoing unicast packets on @socket. By default the platform-specific default value is used. a #GSocket. the time-to-live value for all unicast packets on @socket Shut down part or all of a full-duplex connection. If @shutdown_read is %TRUE then the receiving side of the connection is shut down, and further reading is disallowed. If @shutdown_write is %TRUE then the sending side of the connection is shut down, and further writing is disallowed. It is allowed for both @shutdown_read and @shutdown_write to be %TRUE. One example where it is useful to shut down only one side of a connection is graceful disconnect for TCP connections where you close the sending side, then wait for the other side to close the connection, thus ensuring that the other side saw all sent data. %TRUE on success, %FALSE on error a #GSocket whether to shut down the read side whether to shut down the write side Checks if a socket is capable of speaking IPv4. IPv4 sockets are capable of speaking IPv4. On some operating systems and under some combinations of circumstances IPv6 sockets are also capable of speaking IPv4. See RFC 3493 section 3.7 for more information. No other types of sockets are currently considered as being capable of speaking IPv4. %TRUE if this socket can be used with IPv4. a #GSocket Whether I/O on this socket is blocking. Whether the socket should allow sending to broadcast addresses. The socket’s address family. The socket’s file descriptor. Whether to keep the connection alive by sending periodic pings. The number of outstanding connections in the listen queue. The local address the socket is bound to. Whether outgoing multicast packets loop back to the local host. Time-to-live out outgoing multicast packets The ID of the protocol to use, or `-1` for unknown. The remote address the socket is connected to. The timeout in seconds on socket I/O Time-to-live for outgoing unicast packets The socket’s type. `GSocketAddress` is the equivalent of [`struct sockaddr`](man:sockaddr(3type)) and its subtypes in the BSD sockets API. This is an abstract class; use [class@Gio.InetSocketAddress] for internet sockets, or [class@Gio.UnixSocketAddress] for UNIX domain sockets. Creates a #GSocketAddress subclass corresponding to the native struct sockaddr @native. a new #GSocketAddress if @native could successfully be converted, otherwise %NULL a pointer to a struct sockaddr the size of the memory location pointed to by @native Gets the socket family type of @address. the socket family type of @address a #GSocketAddress Gets the size of @address's native struct sockaddr. You can use this to allocate memory to pass to g_socket_address_to_native(). the size of the native struct sockaddr that @address represents, or `-1` if @address is not valid a #GSocketAddress Converts a #GSocketAddress to a native struct sockaddr, which can be passed to low-level functions like connect() or bind(). If not enough space is available, a %G_IO_ERROR_NO_SPACE error is returned. If the address type is not known on the system then a %G_IO_ERROR_NOT_SUPPORTED error is returned. %TRUE if @dest was filled in, %FALSE on error a #GSocketAddress a pointer to a memory location that will contain the native struct sockaddr the size of @dest. Must be at least as large as g_socket_address_get_native_size() Gets the socket family type of @address. the socket family type of @address a #GSocketAddress Gets the size of @address's native struct sockaddr. You can use this to allocate memory to pass to g_socket_address_to_native(). the size of the native struct sockaddr that @address represents, or `-1` if @address is not valid a #GSocketAddress Converts a #GSocketAddress to a native struct sockaddr, which can be passed to low-level functions like connect() or bind(). If not enough space is available, a %G_IO_ERROR_NO_SPACE error is returned. If the address type is not known on the system then a %G_IO_ERROR_NOT_SUPPORTED error is returned. %TRUE if @dest was filled in, %FALSE on error a #GSocketAddress a pointer to a memory location that will contain the native struct sockaddr the size of @dest. Must be at least as large as g_socket_address_get_native_size() The family of the socket address. the socket family type of @address a #GSocketAddress the size of the native struct sockaddr that @address represents, or `-1` if @address is not valid a #GSocketAddress %TRUE if @dest was filled in, %FALSE on error a #GSocketAddress a pointer to a memory location that will contain the native struct sockaddr the size of @dest. Must be at least as large as g_socket_address_get_native_size() `GSocketAddressEnumerator` is an enumerator type for [class@Gio.SocketAddress] instances. It is returned by enumeration functions such as [method@Gio.SocketConnectable.enumerate], which returns a `GSocketAddressEnumerator` to list each [class@Gio.SocketAddress] which could be used to connect to that [iface@Gio.SocketConnectable]. Enumeration is typically a blocking operation, so the asynchronous methods [method@Gio.SocketAddressEnumerator.next_async] and [method@Gio.SocketAddressEnumerator.next_finish] should be used where possible. Each `GSocketAddressEnumerator` can only be enumerated once. Once [method@Gio.SocketAddressEnumerator.next] has returned `NULL`, further enumeration with that `GSocketAddressEnumerator` is not possible, and it can be unreffed. Retrieves the next #GSocketAddress from @enumerator. Note that this may block for some amount of time. (Eg, a #GNetworkAddress may need to do a DNS lookup before it can return an address.) Use g_socket_address_enumerator_next_async() if you need to avoid blocking. If @enumerator is expected to yield addresses, but for some reason is unable to (eg, because of a DNS error), then the first call to g_socket_address_enumerator_next() will return an appropriate error in `*error`. However, if the first call to g_socket_address_enumerator_next() succeeds, then any further internal errors (other than @cancellable being triggered) will be ignored. a #GSocketAddress (owned by the caller), or %NULL on error (in which case `*error` will be set) or if there are no more addresses. a #GSocketAddressEnumerator optional #GCancellable object, %NULL to ignore. Asynchronously retrieves the next #GSocketAddress from @enumerator and then calls @callback, which must call g_socket_address_enumerator_next_finish() to get the result. It is an error to call this multiple times before the previous callback has finished. a #GSocketAddressEnumerator optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Retrieves the result of a completed call to g_socket_address_enumerator_next_async(). See g_socket_address_enumerator_next() for more information about error handling. a #GSocketAddress (owned by the caller), or %NULL on error (in which case `*error` will be set) or if there are no more addresses. a #GSocketAddressEnumerator a #GAsyncResult Retrieves the next #GSocketAddress from @enumerator. Note that this may block for some amount of time. (Eg, a #GNetworkAddress may need to do a DNS lookup before it can return an address.) Use g_socket_address_enumerator_next_async() if you need to avoid blocking. If @enumerator is expected to yield addresses, but for some reason is unable to (eg, because of a DNS error), then the first call to g_socket_address_enumerator_next() will return an appropriate error in `*error`. However, if the first call to g_socket_address_enumerator_next() succeeds, then any further internal errors (other than @cancellable being triggered) will be ignored. a #GSocketAddress (owned by the caller), or %NULL on error (in which case `*error` will be set) or if there are no more addresses. a #GSocketAddressEnumerator optional #GCancellable object, %NULL to ignore. Asynchronously retrieves the next #GSocketAddress from @enumerator and then calls @callback, which must call g_socket_address_enumerator_next_finish() to get the result. It is an error to call this multiple times before the previous callback has finished. a #GSocketAddressEnumerator optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Retrieves the result of a completed call to g_socket_address_enumerator_next_async(). See g_socket_address_enumerator_next() for more information about error handling. a #GSocketAddress (owned by the caller), or %NULL on error (in which case `*error` will be set) or if there are no more addresses. a #GSocketAddressEnumerator a #GAsyncResult Class structure for #GSocketAddressEnumerator. Virtual method for g_socket_address_enumerator_next(). a #GSocketAddress (owned by the caller), or %NULL on error (in which case `*error` will be set) or if there are no more addresses. a #GSocketAddressEnumerator optional #GCancellable object, %NULL to ignore. Virtual method for g_socket_address_enumerator_next_async(). a #GSocketAddressEnumerator optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Virtual method for g_socket_address_enumerator_next_finish(). a #GSocketAddress (owned by the caller), or %NULL on error (in which case `*error` will be set) or if there are no more addresses. a #GSocketAddressEnumerator a #GAsyncResult `GSocketClient` is a lightweight high-level utility class for connecting to a network host using a connection oriented socket type. You create a `GSocketClient` object, set any options you want, and then call a sync or async connect operation, which returns a [class@Gio.SocketConnection] subclass on success. The type of the [class@Gio.SocketConnection] object returned depends on the type of the underlying socket that is in use. For instance, for a TCP/IP connection it will be a [class@Gio.TcpConnection]. As `GSocketClient` is a lightweight object, you don't need to cache it. You can just create a new one any time you need one. Creates a new #GSocketClient with the default options. a #GSocketClient. Free the returned object with g_object_unref(). Enable proxy protocols to be handled by the application. When the indicated proxy protocol is returned by the #GProxyResolver, #GSocketClient will consider this protocol as supported but will not try to find a #GProxy instance to handle handshaking. The application must check for this case by calling g_socket_connection_get_remote_address() on the returned #GSocketConnection, and seeing if it's a #GProxyAddress of the appropriate type, to determine whether or not it needs to handle the proxy handshaking itself. This should be used for proxy protocols that are dialects of another protocol such as HTTP proxy. It also allows cohabitation of proxy protocols that are reused between protocols. A good example is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also be use as generic socket proxy through the HTTP CONNECT method. When the proxy is detected as being an application proxy, TLS handshake will be skipped. This is required to let the application do the proxy specific handshake. a #GSocketClient The proxy protocol Tries to resolve the @connectable and make a network connection to it. Upon a successful connection, a new #GSocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. The type of the #GSocketConnection object returned depends on the type of the underlying socket that is used. For instance, for a TCP/IP connection it will be a #GTcpConnection. The socket created will be the same family as the address that the @connectable resolves to, unless family is set with g_socket_client_set_family() or indirectly via g_socket_client_set_local_address(). The socket type defaults to %G_SOCKET_TYPE_STREAM but can be set with g_socket_client_set_socket_type(). If a local address is specified with g_socket_client_set_local_address() the socket will be bound to this address before connecting. a #GSocketConnection on success, %NULL on error. a #GSocketClient. a #GSocketConnectable specifying the remote address. optional #GCancellable object, %NULL to ignore. This is the asynchronous version of g_socket_client_connect(). You may wish to prefer the asynchronous version even in synchronous command line programs because, since 2.60, it implements [RFC 8305](https://tools.ietf.org/html/rfc8305) "Happy Eyeballs" recommendations to work around long connection timeouts in networks where IPv6 is broken by performing an IPv4 connection simultaneously without waiting for IPv6 to time out, which is not supported by the synchronous call. (This is not an API guarantee, and may change in the future.) When the operation is finished @callback will be called. You can then call g_socket_client_connect_finish() to get the result of the operation. a #GSocketClient a #GSocketConnectable specifying the remote address. a #GCancellable, or %NULL a #GAsyncReadyCallback user data for the callback Finishes an async connect operation. See g_socket_client_connect_async() a #GSocketConnection on success, %NULL on error. a #GSocketClient. a #GAsyncResult. This is a helper function for g_socket_client_connect(). Attempts to create a TCP connection to the named host. @host_and_port may be in any of a number of recognized formats; an IPv6 address, an IPv4 address, or a domain name (in which case a DNS lookup is performed). Quoting with [] is supported for all address types. A port override may be specified in the usual way with a colon. Ports may be given as decimal numbers or symbolic names (in which case an /etc/services lookup is performed). If no port override is given in @host_and_port then @default_port will be used as the port number to connect to. In general, @host_and_port is expected to be provided by the user (allowing them to give the hostname, and a port override if necessary) and @default_port is expected to be provided by the application. In the case that an IP address is given, a single connection attempt is made. In the case that a name is given, multiple connection attempts may be made, in turn and according to the number of address records in DNS, until a connection succeeds. Upon a successful connection, a new #GSocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) %NULL is returned and @error (if non-%NULL) is set accordingly. a #GSocketConnection on success, %NULL on error. a #GSocketClient the name and optionally port of the host to connect to the default port to connect to a #GCancellable, or %NULL This is the asynchronous version of g_socket_client_connect_to_host(). When the operation is finished @callback will be called. You can then call g_socket_client_connect_to_host_finish() to get the result of the operation. a #GSocketClient the name and optionally the port of the host to connect to the default port to connect to a #GCancellable, or %NULL a #GAsyncReadyCallback user data for the callback Finishes an async connect operation. See g_socket_client_connect_to_host_async() a #GSocketConnection on success, %NULL on error. a #GSocketClient. a #GAsyncResult. Attempts to create a TCP connection to a service. This call looks up the SRV record for @service at @domain for the "tcp" protocol. It then attempts to connect, in turn, to each of the hosts providing the service until either a connection succeeds or there are no hosts remaining. Upon a successful connection, a new #GSocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) %NULL is returned and @error (if non-%NULL) is set accordingly. a #GSocketConnection if successful, or %NULL on error a #GSocketConnection a domain name the name of the service to connect to a #GCancellable, or %NULL This is the asynchronous version of g_socket_client_connect_to_service(). a #GSocketClient a domain name the name of the service to connect to a #GCancellable, or %NULL a #GAsyncReadyCallback user data for the callback Finishes an async connect operation. See g_socket_client_connect_to_service_async() a #GSocketConnection on success, %NULL on error. a #GSocketClient. a #GAsyncResult. This is a helper function for g_socket_client_connect(). Attempts to create a TCP connection with a network URI. @uri may be any valid URI containing an "authority" (hostname/port) component. If a port is not specified in the URI, @default_port will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE. (#GSocketClient does not know to automatically assume TLS for certain URI schemes.) Using this rather than g_socket_client_connect() or g_socket_client_connect_to_host() allows #GSocketClient to determine when to use application-specific proxy protocols. Upon a successful connection, a new #GSocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) %NULL is returned and @error (if non-%NULL) is set accordingly. a #GSocketConnection on success, %NULL on error. a #GSocketClient A network URI the default port to connect to a #GCancellable, or %NULL This is the asynchronous version of g_socket_client_connect_to_uri(). When the operation is finished @callback will be called. You can then call g_socket_client_connect_to_uri_finish() to get the result of the operation. a #GSocketClient a network uri the default port to connect to a #GCancellable, or %NULL a #GAsyncReadyCallback user data for the callback Finishes an async connect operation. See g_socket_client_connect_to_uri_async() a #GSocketConnection on success, %NULL on error. a #GSocketClient. a #GAsyncResult. Gets the proxy enable state; see g_socket_client_set_enable_proxy() whether proxying is enabled a #GSocketClient. Gets the socket family of the socket client. See g_socket_client_set_family() for details. a #GSocketFamily a #GSocketClient. Gets the local address of the socket client. See g_socket_client_set_local_address() for details. a #GSocketAddress or %NULL. Do not free. a #GSocketClient. Gets the protocol name type of the socket client. See g_socket_client_set_protocol() for details. a #GSocketProtocol a #GSocketClient Gets the #GProxyResolver being used by @client. Normally, this will be the resolver returned by g_proxy_resolver_get_default(), but you can override it with g_socket_client_set_proxy_resolver(). The #GProxyResolver being used by @client. a #GSocketClient. Gets the socket type of the socket client. See g_socket_client_set_socket_type() for details. a #GSocketFamily a #GSocketClient. Gets the I/O timeout time for sockets created by @client. See g_socket_client_set_timeout() for details. the timeout in seconds a #GSocketClient Gets whether @client creates TLS connections. See g_socket_client_set_tls() for details. whether @client uses TLS a #GSocketClient. Gets the TLS validation flags used creating TLS connections via @client. This function does not work as originally designed and is impossible to use correctly. See #GSocketClient:tls-validation-flags for more information. Do not attempt to ignore validation errors. the TLS validation flags a #GSocketClient. Sets whether or not @client attempts to make connections via a proxy server. When enabled (the default), #GSocketClient will use a #GProxyResolver to determine if a proxy protocol such as SOCKS is needed, and automatically do the necessary proxy negotiation. See also g_socket_client_set_proxy_resolver(). a #GSocketClient. whether to enable proxies Sets the socket family of the socket client. If this is set to something other than %G_SOCKET_FAMILY_INVALID then the sockets created by this object will be of the specified family. This might be useful for instance if you want to force the local connection to be an ipv4 socket, even though the address might be an ipv6 mapped to ipv4 address. a #GSocketClient. a #GSocketFamily Sets the local address of the socket client. The sockets created by this object will bound to the specified address (if not %NULL) before connecting. This is useful if you want to ensure that the local side of the connection is on a specific port, or on a specific interface. a #GSocketClient. a #GSocketAddress, or %NULL Sets the protocol of the socket client. The sockets created by this object will use of the specified protocol. If @protocol is %G_SOCKET_PROTOCOL_DEFAULT that means to use the default protocol for the socket family and type. a #GSocketClient. a #GSocketProtocol Overrides the #GProxyResolver used by @client. You can call this if you want to use specific proxies, rather than using the system default proxy settings. Note that whether or not the proxy resolver is actually used depends on the setting of #GSocketClient:enable-proxy, which is not changed by this function (but which is %TRUE by default) a #GSocketClient. a #GProxyResolver, or %NULL for the default. Sets the socket type of the socket client. The sockets created by this object will be of the specified type. It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM, as GSocketClient is used for connection oriented services. a #GSocketClient. a #GSocketType Sets the I/O timeout for sockets created by @client. @timeout is a time in seconds, or 0 for no timeout (the default). The timeout value affects the initial connection attempt as well, so setting this may cause calls to g_socket_client_connect(), etc, to fail with %G_IO_ERROR_TIMED_OUT. a #GSocketClient. the timeout Sets whether @client creates TLS (aka SSL) connections. If @tls is %TRUE, @client will wrap its connections in a #GTlsClientConnection and perform a TLS handshake when connecting. Note that since #GSocketClient must return a #GSocketConnection, but #GTlsClientConnection is not a #GSocketConnection, this actually wraps the resulting #GTlsClientConnection in a #GTcpWrapperConnection when returning it. You can use g_tcp_wrapper_connection_get_base_io_stream() on the return value to extract the #GTlsClientConnection. If you need to modify the behavior of the TLS handshake (eg, by setting a client-side certificate to use, or connecting to the #GTlsConnection::accept-certificate signal), you can connect to @client's #GSocketClient::event signal and wait for it to be emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you a chance to see the #GTlsClientConnection before the handshake starts. a #GSocketClient. whether to use TLS Sets the TLS validation flags used when creating TLS connections via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. This function does not work as originally designed and is impossible to use correctly. See #GSocketClient:tls-validation-flags for more information. Do not attempt to ignore validation errors. a #GSocketClient. the validation flags Enable proxy support. The address family to use for socket construction. The local address constructed sockets will be bound to. The protocol to use for socket construction, or `0` for default. The proxy resolver to use The I/O timeout for sockets, in seconds, or `0` for none. Whether to create TLS connections. The TLS validation flags used when creating TLS connections. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. GLib guarantees that if certificate verification fails, at least one flag will be set, but it does not guarantee that all possible flags will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Therefore, there is no safe way to use this property. This is not a horrible problem, though, because you should not be attempting to ignore validation errors anyway. If you really must ignore TLS certificate errors, connect to the #GSocketClient::event signal, wait for it to be emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, and use that to connect to #GTlsConnection::accept-certificate. Do not attempt to ignore validation errors. The type to use for socket construction. Emitted when @client's activity on @connectable changes state. Among other things, this can be used to provide progress information about a network connection in the UI. The meanings of the different @event values are as follows: - %G_SOCKET_CLIENT_RESOLVING: @client is about to look up @connectable in DNS. @connection will be %NULL. - %G_SOCKET_CLIENT_RESOLVED: @client has successfully resolved @connectable in DNS. @connection will be %NULL. - %G_SOCKET_CLIENT_CONNECTING: @client is about to make a connection to a remote host; either a proxy server or the destination server itself. @connection is the #GSocketConnection, which is not yet connected. Since GLib 2.40, you can access the remote address via g_socket_connection_get_remote_address(). - %G_SOCKET_CLIENT_CONNECTED: @client has successfully connected to a remote host. @connection is the connected #GSocketConnection. - %G_SOCKET_CLIENT_PROXY_NEGOTIATING: @client is about to negotiate with a proxy to get it to connect to @connectable. @connection is the #GSocketConnection to the proxy server. - %G_SOCKET_CLIENT_PROXY_NEGOTIATED: @client has negotiated a connection to @connectable through a proxy server. @connection is the stream returned from g_proxy_connect(), which may or may not be a #GSocketConnection. - %G_SOCKET_CLIENT_TLS_HANDSHAKING: @client is about to begin a TLS handshake. @connection is a #GTlsClientConnection. - %G_SOCKET_CLIENT_TLS_HANDSHAKED: @client has successfully completed the TLS handshake. @connection is a #GTlsClientConnection. - %G_SOCKET_CLIENT_COMPLETE: @client has either successfully connected to @connectable (in which case @connection is the #GSocketConnection that it will be returning to the caller) or has failed (in which case @connection is %NULL and the client is about to return an error). Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted multiple times (or not at all) for a given connectable (in particular, if @client ends up attempting to connect to more than one address). However, if @client emits the #GSocketClient::event signal at all for a given connectable, then it will always emit it with %G_SOCKET_CLIENT_COMPLETE when it is done. Note that there may be additional #GSocketClientEvent values in the future; unrecognized @event values should be ignored. the event that is occurring the #GSocketConnectable that @event is occurring on the current representation of the connection Describes an event occurring on a #GSocketClient. See the #GSocketClient::event signal for more details. Additional values may be added to this type in the future. The client is doing a DNS lookup. The client has completed a DNS lookup. The client is connecting to a remote host (either a proxy or the destination server). The client has connected to a remote host. The client is negotiating with a proxy to connect to the destination server. The client has negotiated with the proxy server. The client is performing a TLS handshake. The client has performed a TLS handshake. The client is done with a particular #GSocketConnectable. Objects that describe one or more potential socket endpoints implement `GSocketConnectable`. Callers can then use [method@Gio.SocketConnectable.enumerate] to get a [class@Gio.SocketAddressEnumerator] to try out each socket address in turn until one succeeds, as shown in the sample code below. ```c MyConnectionType * connect_to_host (const char *hostname, guint16 port, GCancellable *cancellable, GError **error) { MyConnection *conn = NULL; GSocketConnectable *addr; GSocketAddressEnumerator *enumerator; GSocketAddress *sockaddr; GError *conn_error = NULL; addr = g_network_address_new (hostname, port); enumerator = g_socket_connectable_enumerate (addr); g_object_unref (addr); // Try each sockaddr until we succeed. Record the first connection error, // but not any further ones (since they'll probably be basically the same // as the first). while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error)) { conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error); g_object_unref (sockaddr); } g_object_unref (enumerator); if (conn) { if (conn_error) { // We couldn't connect to the first address, but we succeeded // in connecting to a later address. g_error_free (conn_error); } return conn; } else if (error) { /// Either initial lookup failed, or else the caller cancelled us. if (conn_error) g_error_free (conn_error); return NULL; } else { g_error_propagate (error, conn_error); return NULL; } } ``` Creates a #GSocketAddressEnumerator for @connectable. a new #GSocketAddressEnumerator. a #GSocketConnectable Creates a #GSocketAddressEnumerator for @connectable that will return a #GProxyAddress for each of its addresses that you must connect to via a proxy. If @connectable does not implement g_socket_connectable_proxy_enumerate(), this will fall back to calling g_socket_connectable_enumerate(). a new #GSocketAddressEnumerator. a #GSocketConnectable Format a #GSocketConnectable as a string. This is a human-readable format for use in debugging output, and is not a stable serialization format. It is not suitable for use in user interfaces as it exposes too much information for a user. If the #GSocketConnectable implementation does not support string formatting, the implementation’s type name will be returned as a fallback. the formatted string a #GSocketConnectable Creates a #GSocketAddressEnumerator for @connectable. a new #GSocketAddressEnumerator. a #GSocketConnectable Creates a #GSocketAddressEnumerator for @connectable that will return a #GProxyAddress for each of its addresses that you must connect to via a proxy. If @connectable does not implement g_socket_connectable_proxy_enumerate(), this will fall back to calling g_socket_connectable_enumerate(). a new #GSocketAddressEnumerator. a #GSocketConnectable Format a #GSocketConnectable as a string. This is a human-readable format for use in debugging output, and is not a stable serialization format. It is not suitable for use in user interfaces as it exposes too much information for a user. If the #GSocketConnectable implementation does not support string formatting, the implementation’s type name will be returned as a fallback. the formatted string a #GSocketConnectable Provides an interface for returning a #GSocketAddressEnumerator and #GProxyAddressEnumerator The parent interface. Creates a #GSocketAddressEnumerator a new #GSocketAddressEnumerator. a #GSocketConnectable Creates a #GProxyAddressEnumerator a new #GSocketAddressEnumerator. a #GSocketConnectable Format the connectable’s address as a string for debugging. Implementing this is optional. (Since: 2.48) the formatted string a #GSocketConnectable `GSocketConnection` is a [class@Gio.IOStream] for a connected socket. They can be created either by [class@Gio.SocketClient] when connecting to a host, or by [class@Gio.SocketListener] when accepting a new client. The type of the `GSocketConnection` object returned from these calls depends on the type of the underlying socket that is in use. For instance, for a TCP/IP connection it will be a [class@Gio.TcpConnection]. Choosing what type of object to construct is done with the socket connection factory, and it is possible for third parties to register custom socket connection types for specific combination of socket family/type/protocol using [func@Gio.SocketConnection.factory_register_type]. To close a `GSocketConnection`, use [method@Gio.IOStream.close]. Closing both substreams of the [class@Gio.IOStream] separately will not close the underlying [class@Gio.Socket]. Looks up the #GType to be used when creating socket connections on sockets with the specified @family, @type and @protocol_id. If no type is registered, the #GSocketConnection base type is returned. a #GType a #GSocketFamily a #GSocketType a protocol id Looks up the #GType to be used when creating socket connections on sockets with the specified @family, @type and @protocol. If no type is registered, the #GSocketConnection base type is returned. a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION a #GSocketFamily a #GSocketType a protocol id Connect @connection to the specified remote address. %TRUE if the connection succeeded, %FALSE on error a #GSocketConnection a #GSocketAddress specifying the remote address. a %GCancellable or %NULL Asynchronously connect @connection to the specified remote address. This clears the #GSocket:blocking flag on @connection's underlying socket if it is currently set. If #GSocket:timeout is set, the operation will time out and return %G_IO_ERROR_TIMED_OUT after that period. Otherwise, it will continue indefinitely until operating system timeouts (if any) are hit. Use g_socket_connection_connect_finish() to retrieve the result. a #GSocketConnection a #GSocketAddress specifying the remote address. a %GCancellable or %NULL a #GAsyncReadyCallback user data for the callback Gets the result of a g_socket_connection_connect_async() call. %TRUE if the connection succeeded, %FALSE on error a #GSocketConnection the #GAsyncResult Try to get the local address of a socket connection. a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). a #GSocketConnection Try to get the remote address of a socket connection. Since GLib 2.40, when used with g_socket_client_connect() or g_socket_client_connect_async(), during emission of %G_SOCKET_CLIENT_CONNECTING, this function will return the remote address that will be used for the connection. This allows applications to print e.g. "Connecting to example.com (10.42.77.3)...". a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). a #GSocketConnection Gets the underlying #GSocket object of the connection. This can be useful if you want to do something unusual on it not supported by the #GSocketConnection APIs. a #GSocket or %NULL on error. a #GSocketConnection Checks if @connection is connected. This is equivalent to calling g_socket_is_connected() on @connection's underlying #GSocket. whether @connection is connected a #GSocketConnection The underlying [class@Gio.Socket]. A `GSocketControlMessage` is a special-purpose utility message that can be sent to or received from a [class@Gio.Socket]. These types of messages are often called ‘ancillary data’. The message can represent some sort of special instruction to or information from the socket or can represent a special kind of transfer to the peer (for example, sending a file descriptor over a UNIX socket). These messages are sent with [method@Gio.Socket.send_message] and received with [method@Gio.Socket.receive_message]. To extend the set of control messages that can be sent, subclass this class and override the `get_size`, `get_level`, `get_type` and `serialize` methods. To extend the set of control messages that can be received, subclass this class and implement the `deserialize` method. Also, make sure your class is registered with the [type@GObject.Type] type system before calling [method@Gio.Socket.receive_message] to read such a message. Tries to deserialize a socket control message of a given @level and @type. This will ask all known (to GType) subclasses of #GSocketControlMessage if they can understand this kind of message and if so deserialize it into a #GSocketControlMessage. If there is no implementation for this kind of control message, %NULL will be returned. the deserialized message or %NULL a socket level a socket control message type for the given @level the size of the data in bytes pointer to the message data Returns the "level" (i.e. the originating protocol) of the control message. This is often SOL_SOCKET. an integer describing the level a #GSocketControlMessage Returns the space required for the control message, not including headers or alignment. The number of bytes required. a #GSocketControlMessage gets the protocol specific type of the message. Converts the data in the message to bytes placed in the message. @data is guaranteed to have enough space to fit the size returned by g_socket_control_message_get_size() on this object. a #GSocketControlMessage A buffer to write data to Returns the "level" (i.e. the originating protocol) of the control message. This is often SOL_SOCKET. an integer describing the level a #GSocketControlMessage Returns the protocol specific type of the control message. For instance, for UNIX fd passing this would be SCM_RIGHTS. an integer describing the type of control message a #GSocketControlMessage Returns the space required for the control message, not including headers or alignment. The number of bytes required. a #GSocketControlMessage Converts the data in the message to bytes placed in the message. @data is guaranteed to have enough space to fit the size returned by g_socket_control_message_get_size() on this object. a #GSocketControlMessage A buffer to write data to Class structure for #GSocketControlMessage. gets the size of the message. The number of bytes required. a #GSocketControlMessage gets the protocol of the message. an integer describing the level a #GSocketControlMessage gets the protocol specific type of the message. Writes out the message data. a #GSocketControlMessage A buffer to write data to Tries to deserialize a message. The protocol family of a #GSocketAddress. (These values are identical to the system defines %AF_INET, %AF_INET6 and %AF_UNIX, if available.) no address family the UNIX domain family the IPv4 family the IPv6 family A `GSocketListener` is an object that keeps track of a set of server sockets and helps you accept sockets from any of the socket, either sync or async. Add addresses and ports to listen on using [method@Gio.SocketListener.add_address] and [method@Gio.SocketListener.add_inet_port]. These will be listened on until [method@Gio.SocketListener.close] is called. Dropping your final reference to the `GSocketListener` will not cause [method@Gio.SocketListener.close] to be called implicitly, as some references to the `GSocketListener` may be held internally. If you want to implement a network server, also look at [class@Gio.SocketService] and [class@Gio.ThreadedSocketService] which are subclasses of `GSocketListener` that make this even easier. Creates a new #GSocketListener with no sockets to listen for. New listeners can be added with e.g. g_socket_listener_add_address() or g_socket_listener_add_inet_port(). a new #GSocketListener. virtual method called when the set of socket listened to changes Blocks waiting for a client to connect to any of the sockets added to the listener. Returns a #GSocketConnection for the socket that was accepted. If @source_object is not %NULL it will be filled out with the source object specified when the corresponding socket or address was added to the listener. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GSocketConnection on success, %NULL on error. a #GSocketListener location where #GObject pointer will be stored, or %NULL optional #GCancellable object, %NULL to ignore. This is the asynchronous version of g_socket_listener_accept(). When the operation is finished @callback will be called. You can then call g_socket_listener_accept_finish() to get the result of the operation. a #GSocketListener a #GCancellable, or %NULL a #GAsyncReadyCallback user data for the callback Finishes an async accept operation. See g_socket_listener_accept_async() a #GSocketConnection on success, %NULL on error. a #GSocketListener a #GAsyncResult. Optional #GObject identifying this source Blocks waiting for a client to connect to any of the sockets added to the listener. Returns the #GSocket that was accepted. If you want to accept the high-level #GSocketConnection, not a #GSocket, which is often the case, then you should use g_socket_listener_accept() instead. If @source_object is not %NULL it will be filled out with the source object specified when the corresponding socket or address was added to the listener. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GSocket on success, %NULL on error. a #GSocketListener location where #GObject pointer will be stored, or %NULL. optional #GCancellable object, %NULL to ignore. This is the asynchronous version of g_socket_listener_accept_socket(). When the operation is finished @callback will be called. You can then call g_socket_listener_accept_socket_finish() to get the result of the operation. a #GSocketListener a #GCancellable, or %NULL a #GAsyncReadyCallback user data for the callback Finishes an async accept operation. See g_socket_listener_accept_socket_async() a #GSocket on success, %NULL on error. a #GSocketListener a #GAsyncResult. Optional #GObject identifying this source Creates a socket of type @type and protocol @protocol, binds it to @address and adds it to the set of sockets we're accepting sockets from. Note that adding an IPv6 address, depending on the platform, may or may not result in a listener that also accepts IPv4 connections. For more deterministic behavior, see g_socket_listener_add_inet_port(). @source_object will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to. If successful and @effective_address is non-%NULL then it will be set to the address that the binding actually occurred at. This is helpful for determining the port number that was used for when requesting a binding to port 0 (ie: "any port"). This address, if requested, belongs to the caller and must be freed. Call g_socket_listener_close() to stop listening on @address; this will not be done automatically when you drop your final reference to @listener, as references may be held internally. %TRUE on success, %FALSE on error. a #GSocketListener a #GSocketAddress a #GSocketType a #GSocketProtocol Optional #GObject identifying this source location to store the address that was bound to, or %NULL. Listens for TCP connections on any available port number for both IPv6 and IPv4 (if each is available). This is useful if you need to have a socket for incoming connections but don't care about the specific port number. If possible, the [class@Gio.SocketListener] will listen on both IPv4 and IPv6 (listening on the same port on both). If listening on one of the socket families fails, the [class@Gio.SocketListener] will only listen on the other. If listening on both fails, an error will be returned. If you need to distinguish whether listening on IPv4 or IPv6 or both was successful, connect to [signal@Gio.SocketListener::event]. @source_object will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to. the port number, or 0 in case of failure. a #GSocketListener Optional #GObject identifying this source Helper function for g_socket_listener_add_address() that creates a TCP/IP socket listening on IPv4 and IPv6 (if supported) on the specified port on all interfaces. If possible, the [class@Gio.SocketListener] will listen on both IPv4 and IPv6 (listening on the same port on both). If listening on one of the socket families fails, the [class@Gio.SocketListener] will only listen on the other. If listening on both fails, an error will be returned. If you need to distinguish whether listening on IPv4 or IPv6 or both was successful, connect to [signal@Gio.SocketListener::event]. @source_object will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to. Call g_socket_listener_close() to stop listening on @port; this will not be done automatically when you drop your final reference to @listener, as references may be held internally. %TRUE on success, %FALSE on error. a #GSocketListener an IP port number (non-zero) Optional #GObject identifying this source Adds @socket to the set of sockets that we try to accept new clients from. The socket must be bound to a local address and listened to. For parallel calls to [class@Gio.SocketListener] methods to work, the socket must be in non-blocking mode. (See [property@Gio.Socket:blocking].) @source_object will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to. The @socket will not be automatically closed when the @listener is finalized unless the listener held the final reference to the socket. Before GLib 2.42, the @socket was automatically closed on finalization of the @listener, even if references to it were held elsewhere. %TRUE on success, %FALSE on error. a #GSocketListener a listening #GSocket Optional #GObject identifying this source Closes all the sockets in the listener. a #GSocketListener Sets the listen backlog on the sockets in the listener. This must be called before adding any sockets, addresses or ports to the #GSocketListener (for example, by calling g_socket_listener_add_inet_port()) to be effective. See g_socket_set_listen_backlog() for details a #GSocketListener an integer The number of outstanding connections in the listen queue. Emitted when @listener's activity on @socket changes state. Note that when @listener is used to listen on both IPv4 and IPv6, a separate set of signals will be emitted for each, and the order they happen in is undefined. the event that is occurring the #GSocket the event is occurring on Class structure for #GSocketListener. virtual method called when the set of socket listened to changes Describes an event occurring on a #GSocketListener. See the #GSocketListener::event signal for more details. Additional values may be added to this type in the future. The listener is about to bind a socket. The listener has bound a socket. The listener is about to start listening on this socket. The listener is now listening on this socket. Flags used in g_socket_receive_message() and g_socket_send_message(). The flags listed in the enum are some commonly available flags, but the values used for them are the same as on the platform, and any other flags are passed in/out as is. So to use a platform specific flag, just include the right system header and pass in the flag. No flags. Request to send/receive out of band data. Read data from the socket without removing it from the queue. Don't use a gateway to send out the packet, only send to hosts on directly connected networks. A protocol identifier is specified when creating a #GSocket, which is a family/type specific identifier, where 0 means the default protocol for the particular family/type. This enum contains a set of commonly available and used protocols. You can also pass any other identifiers handled by the platform in order to use protocols not listed here. The protocol type is unknown The default protocol for the family/type TCP over IP UDP over IP SCTP over IP A `GSocketService` is an object that represents a service that is provided to the network or over local sockets. When a new connection is made to the service the [signal@Gio.SocketService::incoming] signal is emitted. A `GSocketService` is a subclass of [class@Gio.SocketListener] and you need to add the addresses you want to accept connections on with the [class@Gio.SocketListener] APIs. There are two options for implementing a network service based on `GSocketService`. The first is to create the service using [ctor@Gio.SocketService.new] and to connect to the [signal@Gio.SocketService::incoming] signal. The second is to subclass `GSocketService` and override the default signal handler implementation. In either case, the handler must immediately return, or else it will block additional incoming connections from being serviced. If you are interested in writing connection handlers that contain blocking code then see [class@Gio.ThreadedSocketService]. The socket service runs on the main loop of the thread-default context (see [method@GLib.MainContext.push_thread_default]) of the thread it is created in, and is not threadsafe in general. However, the calls to start and stop the service are thread-safe so these can be used from threads that handle incoming clients. Creates a new #GSocketService with no sockets to listen for. New listeners can be added with e.g. g_socket_listener_add_address() or g_socket_listener_add_inet_port(). New services are created active, there is no need to call g_socket_service_start(), unless g_socket_service_stop() has been called before. a new #GSocketService. signal emitted when new connections are accepted Check whether the service is active or not. An active service will accept new clients that connect, while a non-active service will let connecting clients queue up until the service is started. %TRUE if the service is active, %FALSE otherwise a #GSocketService Restarts the service, i.e. start accepting connections from the added sockets when the mainloop runs. This only needs to be called after the service has been stopped from g_socket_service_stop(). This call is thread-safe, so it may be called from a thread handling an incoming client request. a #GSocketService Stops the service, i.e. stops accepting connections from the added sockets when the mainloop runs. This call is thread-safe, so it may be called from a thread handling an incoming client request. Note that this only stops accepting new connections; it does not close the listening sockets, and you can call g_socket_service_start() again later to begin listening again. To close the listening sockets, call g_socket_listener_close(). (This will happen automatically when the #GSocketService is finalized.) This must be called before calling g_socket_listener_close() as the socket service will start accepting connections immediately when a new socket is added. a #GSocketService Whether the service is currently accepting connections. The ::incoming signal is emitted when a new incoming connection to @service needs to be handled. The handler must initiate the handling of @connection, but may not block; in essence, asynchronous operations must be used. @connection will be unreffed once the signal handler returns, so you need to ref it yourself if you are planning to use it. %TRUE to stop other handlers from being called a new #GSocketConnection object the source_object passed to g_socket_listener_add_address() Class structure for #GSocketService. signal emitted when new connections are accepted This is the function type of the callback used for the #GSource returned by g_socket_create_source(). it should return %FALSE if the source should be removed. the #GSocket the current condition at the source fired. data passed in by the user. Flags used when creating a #GSocket. Some protocols may not implement all the socket types. Type unknown or wrong Reliable connection-based byte streams (e.g. TCP). Connectionless, unreliable datagram passing. (e.g. UDP) Reliable connection-based passing of datagrams of fixed maximum length (e.g. SCTP). A single target host/port that a network service is running on. SRV (service) records are used by some network protocols to provide service-specific aliasing and load-balancing. For example, XMPP (Jabber) uses SRV records to locate the XMPP server for a domain; rather than connecting directly to ‘example.com’ or assuming a specific server hostname like ‘xmpp.example.com’, an XMPP client would look up the `xmpp-client` SRV record for ‘example.com’, and then connect to whatever host was pointed to by that record. You can use [method@Gio.Resolver.lookup_service] or [method@Gio.Resolver.lookup_service_async] to find the `GSrvTarget`s for a given service. However, if you are simply planning to connect to the remote service, you can use [class@Gio.NetworkService]’s [iface@Gio.SocketConnectable] interface and not need to worry about `GSrvTarget` at all. Creates a new #GSrvTarget with the given parameters. You should not need to use this; normally #GSrvTargets are created by #GResolver. a new #GSrvTarget. the host that the service is running on the port that the service is running on the target's priority the target's weight Copies @target a copy of @target a #GSrvTarget Frees @target a #GSrvTarget Gets @target's hostname (in ASCII form; if you are going to present this to the user, you should use g_hostname_is_ascii_encoded() to check if it contains encoded Unicode segments, and use g_hostname_to_unicode() to convert it if it does.) @target's hostname a #GSrvTarget Gets @target's port @target's port a #GSrvTarget Gets @target's priority. You should not need to look at this; #GResolver already sorts the targets according to the algorithm in RFC 2782. @target's priority a #GSrvTarget Gets @target's weight. You should not need to look at this; #GResolver already sorts the targets according to the algorithm in RFC 2782. @target's weight a #GSrvTarget Sorts @targets in place according to the algorithm in RFC 2782. the head of the sorted list. a #GList of #GSrvTarget `GStaticResource` is an opaque data structure and can only be accessed using the following functions. Finalizes a [struct@Gio.Resource] initialized by [method@Gio.StaticResource.init]. This is normally used by code generated by [`glib-compile-resources`](glib-compile-resources.html) and is not typically used by other code. pointer to a static [struct@Gio.StaticResource] Gets the [struct@Gio.Resource] that was registered by a call to [method@Gio.StaticResource.init]. This is normally used by code generated by [`glib-compile-resources`](glib-compile-resources.html) and is not typically used by other code. a [struct@Gio.Resource] pointer to a static [struct@Gio.StaticResource] Initializes a [struct@Gio.Resource] from static data using a [struct@Gio.StaticResource]. This is normally used by code generated by [`glib-compile-resources`](glib-compile-resources.html) and is not typically used by other code. pointer to a static [struct@Gio.StaticResource] `GSubprocess` allows the creation of and interaction with child processes. Processes can be communicated with using standard GIO-style APIs (ie: [class@Gio.InputStream], [class@Gio.OutputStream]). There are GIO-style APIs to wait for process termination (ie: cancellable and with an asynchronous variant). There is an API to force a process to terminate, as well as a race-free API for sending UNIX signals to a subprocess. One major advantage that GIO brings over the core GLib library is comprehensive API for asynchronous I/O, such [method@Gio.OutputStream.splice_async]. This makes `GSubprocess` significantly more powerful and flexible than equivalent APIs in some other languages such as the `subprocess.py` included with Python. For example, using `GSubprocess` one could create two child processes, reading standard output from the first, processing it, and writing to the input stream of the second, all without blocking the main loop. A powerful [method@Gio.Subprocess.communicate] API is provided similar to the `communicate()` method of `subprocess.py`. This enables very easy interaction with a subprocess that has been opened with pipes. `GSubprocess` defaults to tight control over the file descriptors open in the child process, avoiding dangling-FD issues that are caused by a simple `fork()`/`exec()`. The only open file descriptors in the spawned process are ones that were explicitly specified by the `GSubprocess` API (unless `G_SUBPROCESS_FLAGS_INHERIT_FDS` was specified). `GSubprocess` will quickly reap all child processes as they exit, avoiding ‘zombie processes’ remaining around for long periods of time. [method@Gio.Subprocess.wait] can be used to wait for this to happen, but it will happen even without the call being explicitly made. As a matter of principle, `GSubprocess` has no API that accepts shell-style space-separated strings. It will, however, match the typical shell behaviour of searching the `PATH` for executables that do not contain a directory separator in their name. By default, the `PATH` of the current process is used. You can specify `G_SUBPROCESS_FLAGS_SEARCH_PATH_FROM_ENVP` to use the `PATH` of the launcher environment instead. `GSubprocess` attempts to have a very simple API for most uses (ie: spawning a subprocess with arguments and support for most typical kinds of input and output redirection). See [ctor@Gio.Subprocess.new]. The [class@Gio.SubprocessLauncher] API is provided for more complicated cases (advanced types of redirection, environment variable manipulation, change of working directory, child setup functions, etc). A typical use of `GSubprocess` will involve calling [ctor@Gio.Subprocess.new], followed by [method@Gio.Subprocess.wait_async] or [method@Gio.Subprocess.wait]. After the process exits, the status can be checked using functions such as [method@Gio.Subprocess.get_if_exited] (which are similar to the familiar `WIFEXITED`-style POSIX macros). Note that as of GLib 2.82, creating a `GSubprocess` causes the signal `SIGPIPE` to be ignored for the remainder of the program. If you are writing a command-line utility that uses `GSubprocess`, you may need to take into account the fact that your program will not automatically be killed if it tries to write to `stdout` after it has been closed. Create a new process with the given flags and varargs argument list. By default, matching the g_spawn_async() defaults, the child's stdin will be set to the system null device, and stdout/stderr will be inherited from the parent. You can use @flags to control this behavior. The argument list must be terminated with %NULL. A newly created #GSubprocess, or %NULL on error (and @error will be set) flags that define the behaviour of the subprocess return location for an error, or %NULL first commandline argument to pass to the subprocess more commandline arguments, followed by %NULL Create a new process with the given flags and argument list. The argument list is expected to be %NULL-terminated. A newly created #GSubprocess, or %NULL on error (and @error will be set) commandline arguments for the subprocess flags that define the behaviour of the subprocess Communicate with the subprocess until it terminates, and all input and output has been completed. If @stdin_buf is given, the subprocess must have been created with %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the stdin of the subprocess and the pipe is closed (ie: EOF). At the same time (as not to cause blocking when dealing with large amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those streams. The data that was read is returned in @stdout and/or the @stderr. If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, @stdout_buf will contain the data read from stdout. Otherwise, for subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, @stdout_buf will be set to %NULL. Similar provisions apply to @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE. As usual, any output variable may be given as %NULL to ignore it. If you desire the stdout and stderr data to be interleaved, create the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and %G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned in @stdout_buf and @stderr_buf will be set to %NULL. In case of any error (including cancellation), %FALSE will be returned with @error set. Some or all of the stdin data may have been written. Any stdout or stderr data that has been read will be discarded. None of the out variables (aside from @error) will have been set to anything in particular and should not be inspected. In the case that %TRUE is returned, the subprocess has exited and the exit status inspection APIs (eg: g_subprocess_get_if_exited(), g_subprocess_get_exit_status()) may be used. You should not attempt to use any of the subprocess pipes after starting this function, since they may be left in strange states, even if the operation was cancelled. You should especially not attempt to interact with the pipes while the operation is in progress (either from another thread or if using the asynchronous version). %TRUE if successful a #GSubprocess data to send to the stdin of the subprocess, or %NULL a #GCancellable data read from the subprocess stdout data read from the subprocess stderr Asynchronous version of g_subprocess_communicate(). Complete invocation with g_subprocess_communicate_finish(). Self Input data, or %NULL Cancellable Callback User data Complete an invocation of g_subprocess_communicate_async(). Self Result Return location for stdout data Return location for stderr data Like g_subprocess_communicate(), but validates the output of the process as UTF-8, and returns it as a regular NUL terminated string. On error, @stdout_buf and @stderr_buf will be set to undefined values and should not be used. a #GSubprocess data to send to the stdin of the subprocess, or %NULL a #GCancellable data read from the subprocess stdout data read from the subprocess stderr Asynchronous version of g_subprocess_communicate_utf8(). Complete invocation with g_subprocess_communicate_utf8_finish(). Self Input data, or %NULL Cancellable Callback User data Complete an invocation of g_subprocess_communicate_utf8_async(). Self Result Return location for stdout data Return location for stderr data Use an operating-system specific method to attempt an immediate, forceful termination of the process. There is no mechanism to determine whether or not the request itself was successful; however, you can use g_subprocess_wait() to monitor the status of the process after calling this function. On Unix, this function sends %SIGKILL. a #GSubprocess Check the exit status of the subprocess, given that it exited normally. This is the value passed to the exit() system call or the return value from main. This is equivalent to the system WEXITSTATUS macro. It is an error to call this function before g_subprocess_wait() and unless g_subprocess_get_if_exited() returned %TRUE. the exit status a #GSubprocess On UNIX, returns the process ID as a decimal string. On Windows, returns the result of GetProcessId() also as a string. If the subprocess has terminated, this will return %NULL. the subprocess identifier, or %NULL if the subprocess has terminated a #GSubprocess Check if the given subprocess exited normally (ie: by way of exit() or return from main()). This is equivalent to the system WIFEXITED macro. It is an error to call this function before g_subprocess_wait() has returned. %TRUE if the case of a normal exit a #GSubprocess Check if the given subprocess terminated in response to a signal. This is equivalent to the system WIFSIGNALED macro. It is an error to call this function before g_subprocess_wait() has returned. %TRUE if the case of termination due to a signal a #GSubprocess Gets the raw status code of the process, as from waitpid(). This value has no particular meaning, but it can be used with the macros defined by the system headers such as WIFEXITED. It can also be used with g_spawn_check_wait_status(). It is more likely that you want to use g_subprocess_get_if_exited() followed by g_subprocess_get_exit_status(). It is an error to call this function before g_subprocess_wait() has returned. the (meaningless) waitpid() exit status from the kernel a #GSubprocess Gets the #GInputStream from which to read the stderr output of @subprocess. The process must have been created with %G_SUBPROCESS_FLAGS_STDERR_PIPE, otherwise %NULL will be returned. the stderr pipe a #GSubprocess Gets the #GOutputStream that you can write to in order to give data to the stdin of @subprocess. The process must have been created with %G_SUBPROCESS_FLAGS_STDIN_PIPE and not %G_SUBPROCESS_FLAGS_STDIN_INHERIT, otherwise %NULL will be returned. the stdout pipe a #GSubprocess Gets the #GInputStream from which to read the stdout output of @subprocess. The process must have been created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, otherwise %NULL will be returned. the stdout pipe a #GSubprocess Checks if the process was "successful". A process is considered successful if it exited cleanly with an exit status of 0, either by way of the exit() system call or return from main(). It is an error to call this function before g_subprocess_wait() has returned. %TRUE if the process exited cleanly with a exit status of 0 a #GSubprocess Get the signal number that caused the subprocess to terminate, given that it terminated due to a signal. This is equivalent to the system WTERMSIG macro. It is an error to call this function before g_subprocess_wait() and unless g_subprocess_get_if_signaled() returned %TRUE. the signal causing termination a #GSubprocess Sends the UNIX signal @signal_num to the subprocess, if it is still running. This API is race-free. If the subprocess has terminated, it will not be signalled. This API is not available on Windows. a #GSubprocess the signal number to send Synchronously wait for the subprocess to terminate. After the process terminates you can query its exit status with functions such as g_subprocess_get_if_exited() and g_subprocess_get_exit_status(). This function does not fail in the case of the subprocess having abnormal termination. See g_subprocess_wait_check() for that. Cancelling @cancellable doesn't kill the subprocess. Call g_subprocess_force_exit() if it is desirable. %TRUE on success, %FALSE if @cancellable was cancelled a #GSubprocess a #GCancellable Wait for the subprocess to terminate. This is the asynchronous version of g_subprocess_wait(). a #GSubprocess a #GCancellable, or %NULL a #GAsyncReadyCallback to call when the operation is complete user_data for @callback Combines g_subprocess_wait() with g_spawn_check_wait_status(). %TRUE on success, %FALSE if process exited abnormally, or @cancellable was cancelled a #GSubprocess a #GCancellable Combines g_subprocess_wait_async() with g_spawn_check_wait_status(). This is the asynchronous version of g_subprocess_wait_check(). a #GSubprocess a #GCancellable, or %NULL a #GAsyncReadyCallback to call when the operation is complete user_data for @callback Collects the result of a previous call to g_subprocess_wait_check_async(). %TRUE if successful, or %FALSE with @error set a #GSubprocess the #GAsyncResult passed to your #GAsyncReadyCallback Collects the result of a previous call to g_subprocess_wait_async(). %TRUE if successful, or %FALSE with @error set a #GSubprocess the #GAsyncResult passed to your #GAsyncReadyCallback Argument vector. Subprocess flags. Flags to define the behaviour of a #GSubprocess. Note that the default for stdin is to redirect from `/dev/null`. For stdout and stderr the default are for them to inherit the corresponding descriptor from the calling process. Note that it is a programmer error to mix 'incompatible' flags. For example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and %G_SUBPROCESS_FLAGS_STDOUT_SILENCE. No flags. create a pipe for the stdin of the spawned process that can be accessed with g_subprocess_get_stdin_pipe(). stdin is inherited from the calling process. create a pipe for the stdout of the spawned process that can be accessed with g_subprocess_get_stdout_pipe(). silence the stdout of the spawned process (ie: redirect to `/dev/null`). create a pipe for the stderr of the spawned process that can be accessed with g_subprocess_get_stderr_pipe(). silence the stderr of the spawned process (ie: redirect to `/dev/null`). merge the stderr of the spawned process with whatever the stdout happens to be. This is a good way of directing both streams to a common log file, for example. spawned processes will inherit the file descriptors of their parent, unless those descriptors have been explicitly marked as close-on-exec. This flag has no effect over the "standard" file descriptors (stdin, stdout, stderr). if path searching is needed when spawning the subprocess, use the `PATH` in the launcher environment. (Since: 2.72) This class contains a set of options for launching child processes, such as where its standard input and output will be directed, the argument list, the environment, and more. While the [class@Gio.Subprocess] class has high level functions covering popular cases, use of this class allows access to more advanced options. It can also be used to launch multiple subprocesses with a similar configuration. Creates a new #GSubprocessLauncher. The launcher is created with the default options. A copy of the environment of the calling process is made at the time of this call and will be used as the environment that the process is launched in. #GSubprocessFlags Closes all the file descriptors previously passed to the object with g_subprocess_launcher_take_fd(), g_subprocess_launcher_take_stderr_fd(), etc. After calling this method, any subsequent calls to g_subprocess_launcher_spawn() or g_subprocess_launcher_spawnv() will return %G_IO_ERROR_CLOSED. This method is idempotent if called more than once. This function is called automatically when the #GSubprocessLauncher is disposed, but is provided separately so that garbage collected language bindings can call it earlier to guarantee when FDs are closed. a #GSubprocessLauncher Returns the value of the environment variable @variable in the environment of processes launched from this launcher. On UNIX, the returned string can be an arbitrary byte string. On Windows, it will be UTF-8. the value of the environment variable, %NULL if unset a #GSubprocessLauncher the environment variable to get Sets up a child setup function. The child setup function will be called after fork() but before exec() on the child's side. @destroy_notify will not be automatically called on the child's side of the fork(). It will only be called when the last reference on the #GSubprocessLauncher is dropped or when a new child setup function is given. %NULL can be given as @child_setup to disable the functionality. Child setup functions are only available on UNIX. a #GSubprocessLauncher a #GSpawnChildSetupFunc to use as the child setup function user data for @child_setup a #GDestroyNotify for @user_data Sets the current working directory that processes will be launched with. By default processes are launched with the current working directory of the launching process at the time of launch. a #GSubprocessLauncher the cwd for launched processes Replace the entire environment of processes launched from this launcher with the given 'environ' variable. Typically you will build this variable by using g_listenv() to copy the process 'environ' and using the functions g_environ_setenv(), g_environ_unsetenv(), etc. As an alternative, you can use g_subprocess_launcher_setenv(), g_subprocess_launcher_unsetenv(), etc. Pass an empty array to set an empty environment. Pass %NULL to inherit the parent process’ environment. As of GLib 2.54, the parent process’ environment will be copied when g_subprocess_launcher_set_environ() is called. Previously, it was copied when the subprocess was executed. This means the copied environment may now be modified (using g_subprocess_launcher_setenv(), etc.) before launching the subprocess. On UNIX, all strings in this array can be arbitrary byte strings. On Windows, they should be in UTF-8. a #GSubprocessLauncher the replacement environment Sets the flags on the launcher. The default flags are %G_SUBPROCESS_FLAGS_NONE. You may not set flags that specify conflicting options for how to handle a particular stdio stream (eg: specifying both %G_SUBPROCESS_FLAGS_STDIN_PIPE and %G_SUBPROCESS_FLAGS_STDIN_INHERIT). You may also not set a flag that conflicts with a previous call to a function like g_subprocess_launcher_set_stdin_file_path() or g_subprocess_launcher_take_stdout_fd(). a #GSubprocessLauncher #GSubprocessFlags Sets the file path to use as the stderr for spawned processes. If @path is %NULL then any previously given path is unset. The file will be created or truncated when the process is spawned, as would be the case if using '2>' at the shell. If you want to send both stdout and stderr to the same file then use %G_SUBPROCESS_FLAGS_STDERR_MERGE. You may not set a stderr file path if a stderr fd is already set or if the launcher flags contain any flags directing stderr elsewhere. This feature is only available on UNIX. a #GSubprocessLauncher a filename or %NULL Sets the file path to use as the stdin for spawned processes. If @path is %NULL then any previously given path is unset. The file must exist or spawning the process will fail. You may not set a stdin file path if a stdin fd is already set or if the launcher flags contain any flags directing stdin elsewhere. This feature is only available on UNIX. a #GSubprocessLauncher a filename or %NULL Sets the file path to use as the stdout for spawned processes. If @path is %NULL then any previously given path is unset. The file will be created or truncated when the process is spawned, as would be the case if using '>' at the shell. You may not set a stdout file path if a stdout fd is already set or if the launcher flags contain any flags directing stdout elsewhere. This feature is only available on UNIX. a #GSubprocessLauncher a filename or %NULL Sets the environment variable @variable in the environment of processes launched from this launcher. On UNIX, both the variable's name and value can be arbitrary byte strings, except that the variable's name cannot contain '='. On Windows, they should be in UTF-8. a #GSubprocessLauncher the environment variable to set, must not contain '=' the new value for the variable whether to change the variable if it already exists Creates a #GSubprocess given a provided varargs list of arguments. A new #GSubprocess, or %NULL on error (and @error will be set) a #GSubprocessLauncher Error Command line arguments Continued arguments, %NULL terminated Creates a #GSubprocess given a provided array of arguments. A new #GSubprocess, or %NULL on error (and @error will be set) a #GSubprocessLauncher Command line arguments Transfer an arbitrary file descriptor from parent process to the child. This function takes ownership of the @source_fd; it will be closed in the parent when @self is freed. By default, all file descriptors from the parent will be closed. This function allows you to create (for example) a custom `pipe()` or `socketpair()` before launching the process, and choose the target descriptor in the child. An example use case is GNUPG, which has a command line argument `--passphrase-fd` providing a file descriptor number where it expects the passphrase to be written. a #GSubprocessLauncher File descriptor in parent process Target descriptor for child process Sets the file descriptor to use as the stderr for spawned processes. If @fd is -1 then any previously given fd is unset. Note that the default behaviour is to pass stderr through to the stderr of the parent process. The passed @fd belongs to the #GSubprocessLauncher. It will be automatically closed when the launcher is finalized. The file descriptor will also be closed on the child side when executing the spawned process. You may not set a stderr fd if a stderr file path is already set or if the launcher flags contain any flags directing stderr elsewhere. This feature is only available on UNIX. a #GSubprocessLauncher a file descriptor, or -1 Sets the file descriptor to use as the stdin for spawned processes. If @fd is -1 then any previously given fd is unset. Note that if your intention is to have the stdin of the calling process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT is a better way to go about doing that. The passed @fd is noted but will not be touched in the current process. It is therefore necessary that it be kept open by the caller until the subprocess is spawned. The file descriptor will also not be explicitly closed on the child side, so it must be marked O_CLOEXEC if that's what you want. You may not set a stdin fd if a stdin file path is already set or if the launcher flags contain any flags directing stdin elsewhere. This feature is only available on UNIX. a #GSubprocessLauncher a file descriptor, or -1 Sets the file descriptor to use as the stdout for spawned processes. If @fd is -1 then any previously given fd is unset. Note that the default behaviour is to pass stdout through to the stdout of the parent process. The passed @fd is noted but will not be touched in the current process. It is therefore necessary that it be kept open by the caller until the subprocess is spawned. The file descriptor will also not be explicitly closed on the child side, so it must be marked O_CLOEXEC if that's what you want. You may not set a stdout fd if a stdout file path is already set or if the launcher flags contain any flags directing stdout elsewhere. This feature is only available on UNIX. a #GSubprocessLauncher a file descriptor, or -1 Removes the environment variable @variable from the environment of processes launched from this launcher. On UNIX, the variable's name can be an arbitrary byte string not containing '='. On Windows, it should be in UTF-8. a #GSubprocessLauncher the environment variable to unset, must not contain '=' [flags@Gio.SubprocessFlags] for launched processes. Extension point for TLS functionality via #GTlsBackend. See [Extending GIO](overview.html#extending-gio). The purpose used to verify the client certificate in a TLS connection. Used by TLS servers. The purpose used to verify the server certificate in a TLS connection. This is the most common purpose in use. Used by TLS clients. A `GTask` represents and manages a cancellable ‘task’. ## Asynchronous operations The most common usage of `GTask` is as a [iface@Gio.AsyncResult], to manage data during an asynchronous operation. You call [ctor@Gio.Task.new] in the ‘start’ method, followed by [method@Gio.Task.set_task_data] and the like if you need to keep some additional data associated with the task, and then pass the task object around through your asynchronous operation. Eventually, you will call a method such as [method@Gio.Task.return_pointer] or [method@Gio.Task.return_error], which will save the value you give it and then invoke the task’s callback function in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) where it was created (waiting until the next iteration of the main loop first, if necessary). The caller will pass the `GTask` back to the operation’s finish function (as a [iface@Gio.AsyncResult]), and you can use [method@Gio.Task.propagate_pointer] or the like to extract the return value. Using `GTask` requires the thread-default [struct@GLib.MainContext] from when the `GTask` was constructed to be running at least until the task has completed and its data has been freed. If a `GTask` has been constructed and its callback set, it is an error to not call `g_task_return_*()` on it. GLib will warn at runtime if this happens (since 2.76). Here is an example for using `GTask` as a [iface@Gio.AsyncResult]: ```c typedef struct { CakeFrostingType frosting; char *message; } DecorationData; static void decoration_data_free (DecorationData *decoration) { g_free (decoration->message); g_slice_free (DecorationData, decoration); } static void baked_cb (Cake *cake, gpointer user_data) { GTask *task = user_data; DecorationData *decoration = g_task_get_task_data (task); GError *error = NULL; if (cake == NULL) { g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, "Go to the supermarket"); g_object_unref (task); return; } if (!cake_decorate (cake, decoration->frosting, decoration->message, &error)) { g_object_unref (cake); // g_task_return_error() takes ownership of error g_task_return_error (task, error); g_object_unref (task); return; } g_task_return_pointer (task, cake, g_object_unref); g_object_unref (task); } void baker_bake_cake_async (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { GTask *task; DecorationData *decoration; Cake *cake; task = g_task_new (self, cancellable, callback, user_data); if (radius < 3) { g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL, "%ucm radius cakes are silly", radius); g_object_unref (task); return; } cake = _baker_get_cached_cake (self, radius, flavor, frosting, message); if (cake != NULL) { // _baker_get_cached_cake() returns a reffed cake g_task_return_pointer (task, cake, g_object_unref); g_object_unref (task); return; } decoration = g_slice_new (DecorationData); decoration->frosting = frosting; decoration->message = g_strdup (message); g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free); _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); } Cake * baker_bake_cake_finish (Baker *self, GAsyncResult *result, GError **error) { g_return_val_if_fail (g_task_is_valid (result, self), NULL); return g_task_propagate_pointer (G_TASK (result), error); } ``` ## Chained asynchronous operations `GTask` also tries to simplify asynchronous operations that internally chain together several smaller asynchronous operations. [method@Gio.Task.get_cancellable], [method@Gio.Task.get_context], and [method@Gio.Task.get_priority] allow you to get back the task’s [class@Gio.Cancellable], [struct@GLib.MainContext], and [I/O priority](iface.AsyncResult.html#io-priority) when starting a new subtask, so you don’t have to keep track of them yourself. [method@Gio.Task.attach_source] simplifies the case of waiting for a source to fire (automatically using the correct [struct@GLib.MainContext] and priority). Here is an example for chained asynchronous operations: ```c typedef struct { Cake *cake; CakeFrostingType frosting; char *message; } BakingData; static void decoration_data_free (BakingData *bd) { if (bd->cake) g_object_unref (bd->cake); g_free (bd->message); g_slice_free (BakingData, bd); } static void decorated_cb (Cake *cake, GAsyncResult *result, gpointer user_data) { GTask *task = user_data; GError *error = NULL; if (!cake_decorate_finish (cake, result, &error)) { g_object_unref (cake); g_task_return_error (task, error); g_object_unref (task); return; } // baking_data_free() will drop its ref on the cake, so we have to // take another here to give to the caller. g_task_return_pointer (task, g_object_ref (cake), g_object_unref); g_object_unref (task); } static gboolean decorator_ready (gpointer user_data) { GTask *task = user_data; BakingData *bd = g_task_get_task_data (task); cake_decorate_async (bd->cake, bd->frosting, bd->message, g_task_get_cancellable (task), decorated_cb, task); return G_SOURCE_REMOVE; } static void baked_cb (Cake *cake, gpointer user_data) { GTask *task = user_data; BakingData *bd = g_task_get_task_data (task); GError *error = NULL; if (cake == NULL) { g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, "Go to the supermarket"); g_object_unref (task); return; } bd->cake = cake; // Bail out now if the user has already cancelled if (g_task_return_error_if_cancelled (task)) { g_object_unref (task); return; } if (cake_decorator_available (cake)) decorator_ready (task); else { GSource *source; source = cake_decorator_wait_source_new (cake); // Attach @source to @task’s GMainContext and have it call // decorator_ready() when it is ready. g_task_attach_source (task, source, decorator_ready); g_source_unref (source); } } void baker_bake_cake_async (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, gint priority, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { GTask *task; BakingData *bd; task = g_task_new (self, cancellable, callback, user_data); g_task_set_priority (task, priority); bd = g_slice_new0 (BakingData); bd->frosting = frosting; bd->message = g_strdup (message); g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free); _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); } Cake * baker_bake_cake_finish (Baker *self, GAsyncResult *result, GError **error) { g_return_val_if_fail (g_task_is_valid (result, self), NULL); return g_task_propagate_pointer (G_TASK (result), error); } ``` ## Asynchronous operations from synchronous ones You can use [method@Gio.Task.run_in_thread] to turn a synchronous operation into an asynchronous one, by running it in a thread. When it completes, the result will be dispatched to the thread-default main context (see [method@GLib.MainContext.push_thread_default]) where the `GTask` was created. Running a task in a thread: ```c typedef struct { guint radius; CakeFlavor flavor; CakeFrostingType frosting; char *message; } CakeData; static void cake_data_free (CakeData *cake_data) { g_free (cake_data->message); g_slice_free (CakeData, cake_data); } static void bake_cake_thread (GTask *task, gpointer source_object, gpointer task_data, GCancellable *cancellable) { Baker *self = source_object; CakeData *cake_data = task_data; Cake *cake; GError *error = NULL; cake = bake_cake (baker, cake_data->radius, cake_data->flavor, cake_data->frosting, cake_data->message, cancellable, &error); if (cake) g_task_return_pointer (task, cake, g_object_unref); else g_task_return_error (task, error); } void baker_bake_cake_async (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { CakeData *cake_data; GTask *task; cake_data = g_slice_new (CakeData); cake_data->radius = radius; cake_data->flavor = flavor; cake_data->frosting = frosting; cake_data->message = g_strdup (message); task = g_task_new (self, cancellable, callback, user_data); g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); g_task_run_in_thread (task, bake_cake_thread); g_object_unref (task); } Cake * baker_bake_cake_finish (Baker *self, GAsyncResult *result, GError **error) { g_return_val_if_fail (g_task_is_valid (result, self), NULL); return g_task_propagate_pointer (G_TASK (result), error); } ``` ## Adding cancellability to uncancellable tasks Finally, [method@Gio.Task.run_in_thread] and [method@Gio.Task.run_in_thread_sync] can be used to turn an uncancellable operation into a cancellable one. If you call [method@Gio.Task.set_return_on_cancel], passing `TRUE`, then if the task’s [class@Gio.Cancellable] is cancelled, it will return control back to the caller immediately, while allowing the task thread to continue running in the background (and simply discarding its result when it finally does finish). Provided that the task thread is careful about how it uses locks and other externally-visible resources, this allows you to make ‘GLib-friendly’ asynchronous and cancellable synchronous variants of blocking APIs. Cancelling a task: ```c static void bake_cake_thread (GTask *task, gpointer source_object, gpointer task_data, GCancellable *cancellable) { Baker *self = source_object; CakeData *cake_data = task_data; Cake *cake; GError *error = NULL; cake = bake_cake (baker, cake_data->radius, cake_data->flavor, cake_data->frosting, cake_data->message, &error); if (error) { g_task_return_error (task, error); return; } // If the task has already been cancelled, then we don’t want to add // the cake to the cake cache. Likewise, we don’t want to have the // task get cancelled in the middle of updating the cache. // g_task_set_return_on_cancel() will return %TRUE here if it managed // to disable return-on-cancel, or %FALSE if the task was cancelled // before it could. if (g_task_set_return_on_cancel (task, FALSE)) { // If the caller cancels at this point, their // GAsyncReadyCallback won’t be invoked until we return, // so we don’t have to worry that this code will run at // the same time as that code does. But if there were // other functions that might look at the cake cache, // then we’d probably need a GMutex here as well. baker_add_cake_to_cache (baker, cake); g_task_return_pointer (task, cake, g_object_unref); } } void baker_bake_cake_async (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { CakeData *cake_data; GTask *task; cake_data = g_slice_new (CakeData); ... task = g_task_new (self, cancellable, callback, user_data); g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); g_task_set_return_on_cancel (task, TRUE); g_task_run_in_thread (task, bake_cake_thread); } Cake * baker_bake_cake_sync (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GError **error) { CakeData *cake_data; GTask *task; Cake *cake; cake_data = g_slice_new (CakeData); ... task = g_task_new (self, cancellable, NULL, NULL); g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); g_task_set_return_on_cancel (task, TRUE); g_task_run_in_thread_sync (task, bake_cake_thread); cake = g_task_propagate_pointer (task, error); g_object_unref (task); return cake; } ``` ## Porting from [class@Gio.SimpleAsyncResult] `GTask`’s API attempts to be simpler than [class@Gio.SimpleAsyncResult]’s in several ways: - You can save task-specific data with [method@Gio.Task.set_task_data], and retrieve it later with [method@Gio.Task.get_task_data]. This replaces the abuse of [method@Gio.SimpleAsyncResult.set_op_res_gpointer] for the same purpose with [class@Gio.SimpleAsyncResult]. - In addition to the task data, `GTask` also keeps track of the [priority](iface.AsyncResult.html#io-priority), [class@Gio.Cancellable], and [struct@GLib.MainContext] associated with the task, so tasks that consist of a chain of simpler asynchronous operations will have easy access to those values when starting each sub-task. - [method@Gio.Task.return_error_if_cancelled] provides simplified handling for cancellation. In addition, cancellation overrides any other `GTask` return value by default, like [class@Gio.SimpleAsyncResult] does when [method@Gio.SimpleAsyncResult.set_check_cancellable] is called. (You can use [method@Gio.Task.set_check_cancellable] to turn off that behavior.) On the other hand, [method@Gio.Task.run_in_thread] guarantees that it will always run your `task_func`, even if the task’s [class@Gio.Cancellable] is already cancelled before the task gets a chance to run; you can start your `task_func` with a [method@Gio.Task.return_error_if_cancelled] check if you need the old behavior. - The ‘return’ methods (eg, [method@Gio.Task.return_pointer]) automatically cause the task to be ‘completed’ as well, and there is no need to worry about the ‘complete’ vs ‘complete in idle’ distinction. (`GTask` automatically figures out whether the task’s callback can be invoked directly, or if it needs to be sent to another [struct@GLib.MainContext], or delayed until the next iteration of the current [struct@GLib.MainContext].) - The ‘finish’ functions for `GTask` based operations are generally much simpler than [class@Gio.SimpleAsyncResult] ones, normally consisting of only a single call to [method@Gio.Task.propagate_pointer] or the like. Since [method@Gio.Task.propagate_pointer] ‘steals’ the return value from the `GTask`, it is not necessary to juggle pointers around to prevent it from being freed twice. - With [class@Gio.SimpleAsyncResult], it was common to call [method@Gio.SimpleAsyncResult.propagate_error] from the `_finish()` wrapper function, and have virtual method implementations only deal with successful returns. This behavior is deprecated, because it makes it difficult for a subclass to chain to a parent class’s async methods. Instead, the wrapper function should just be a simple wrapper, and the virtual method should call an appropriate `g_task_propagate_` function. Note that wrapper methods can now use [method@Gio.AsyncResult.legacy_propagate_error] to do old-style [class@Gio.SimpleAsyncResult] error-returning behavior, and [method@Gio.AsyncResult.is_tagged] to check if a result is tagged as having come from the `_async()` wrapper function (for ‘short-circuit’ results, such as when passing `0` to [method@Gio.InputStream.read_async]). ## Thread-safety considerations Due to some infelicities in the API design, there is a thread-safety concern that users of `GTask` have to be aware of: If the `main` thread drops its last reference to the source object or the task data before the task is finalized, then the finalizers of these objects may be called on the worker thread. This is a problem if the finalizers use non-threadsafe API, and can lead to hard-to-debug crashes. Possible workarounds include: - Clear task data in a signal handler for `notify::completed` - Keep iterating a main context in the main thread and defer dropping the reference to the source object to that main context when the task is finalized Creates a #GTask acting on @source_object, which will eventually be used to invoke @callback in the current thread-default main context (see [method@GLib.MainContext.push_thread_default]). Call this in the "start" method of your asynchronous method, and pass the #GTask around throughout the asynchronous operation. You can use g_task_set_task_data() to attach task-specific data to the object, which you can retrieve later via g_task_get_task_data(). By default, if @cancellable is cancelled, then the return value of the task will always be %G_IO_ERROR_CANCELLED, even if the task had already completed before the cancellation. This allows for simplified handling in cases where cancellation may imply that other objects that the task depends on have been destroyed. If you do not want this behavior, you can use g_task_set_check_cancellable() to change it. a #GTask. the #GObject that owns this task, or %NULL. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback. user data passed to @callback. Checks that @result is a #GTask, and that @source_object is its source object (or that @source_object is %NULL and @result has no source object). This can be used in g_return_if_fail() checks. %TRUE if @result and @source_object are valid, %FALSE if not A #GAsyncResult the source object expected to be associated with the task Creates a #GTask and then immediately calls g_task_return_error() on it. Use this in the wrapper function of an asynchronous method when you want to avoid even calling the virtual method. You can then use g_async_result_is_tagged() in the finish method wrapper to check if the result there is tagged as having been created by the wrapper method, and deal with it appropriately if so. See also g_task_report_new_error(). the #GObject that owns this task, or %NULL. a #GAsyncReadyCallback. user data passed to @callback. an opaque pointer indicating the source of this task error to report Creates a #GTask and then immediately calls g_task_return_new_error() on it. Use this in the wrapper function of an asynchronous method when you want to avoid even calling the virtual method. You can then use g_async_result_is_tagged() in the finish method wrapper to check if the result there is tagged as having been created by the wrapper method, and deal with it appropriately if so. See also g_task_report_error(). the #GObject that owns this task, or %NULL. a #GAsyncReadyCallback. user data passed to @callback. an opaque pointer indicating the source of this task a #GQuark. an error code. a string with format characters. a list of values to insert into @format. A utility function for dealing with async operations where you need to wait for a #GSource to trigger. Attaches @source to @task's #GMainContext with @task's [priority](iface.AsyncResult.html#io-priority), and sets @source's callback to @callback, with @task as the callback's `user_data`. It will set the @source’s name to the task’s name (as set with g_task_set_name()), if one has been set on the task and the source doesn’t yet have a name. This takes a reference on @task until @source is destroyed. a #GTask the source to attach the callback to invoke when @source triggers Gets @task's #GCancellable @task's #GCancellable a #GTask Gets @task's check-cancellable flag. See g_task_set_check_cancellable() for more details. the #GTask Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after the task’s callback is invoked, and will return %FALSE if called from inside the callback. %TRUE if the task has completed, %FALSE otherwise. a #GTask. Gets the #GMainContext that @task will return its result in (that is, the context that was the thread-default main context (see [method@GLib.MainContext.push_thread_default]) at the point when @task was created). This will always return a non-%NULL value, even if the task's context is the default #GMainContext. @task's #GMainContext a #GTask Gets @task’s name. See g_task_set_name(). @task’s name, or %NULL a #GTask Gets @task's priority @task's priority a #GTask Gets @task's return-on-cancel flag. See g_task_set_return_on_cancel() for more details. the #GTask Gets the source object from @task. Like g_async_result_get_source_object(), but does not ref the object. @task's source object, or %NULL a #GTask Gets @task's source tag. See g_task_set_source_tag(). @task's source tag a #GTask Gets @task's `task_data`. @task's `task_data`. a #GTask Tests if @task resulted in an error. %TRUE if the task resulted in an error, %FALSE otherwise. a #GTask. Gets the result of @task as a #gboolean. If the task resulted in an error, or was cancelled, then this will instead return %FALSE and set @error. Since this method transfers ownership of the return value (or error) to the caller, you may only call it once. the task result, or %FALSE on error a #GTask. Gets the result of @task as an integer (#gssize). If the task resulted in an error, or was cancelled, then this will instead return -1 and set @error. Since this method transfers ownership of the return value (or error) to the caller, you may only call it once. the task result, or -1 on error a #GTask. Gets the result of @task as a pointer, and transfers ownership of that value to the caller. If the task resulted in an error, or was cancelled, then this will instead return %NULL and set @error. Since this method transfers ownership of the return value (or error) to the caller, you may only call it once. the task result, or %NULL on error a #GTask Gets the result of @task as a #GValue, and transfers ownership of that value to the caller. As with g_task_return_value(), this is a generic low-level method; g_task_propagate_pointer() and the like will usually be more useful for C code. If the task resulted in an error, or was cancelled, then this will instead set @error and return %FALSE. Since this method transfers ownership of the return value (or error) to the caller, you may only call it once. %TRUE if @task succeeded, %FALSE on error. a #GTask return location for the #GValue Sets @task's result to @result and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). a #GTask. the #gboolean result of a task function. Sets @task's result to @error (which @task assumes ownership of) and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). Note that since the task takes ownership of @error, and since the task may be completed before returning from g_task_return_error(), you cannot assume that @error is still valid after calling this. Call g_error_copy() on the error if you need to keep a local copy as well. See also [method@Gio.Task.return_new_error], [method@Gio.Task.return_new_error_literal]. a #GTask. the #GError result of a task function. Checks if @task's #GCancellable has been cancelled, and if so, sets @task's error accordingly and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). %TRUE if @task has been cancelled, %FALSE if not a #GTask Sets @task's result to @result and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). a #GTask. the integer (#gssize) result of a task function. Sets @task's result to a new #GError created from @domain, @code, @format, and the remaining arguments, and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). See also g_task_return_error(). a #GTask. a #GQuark. an error code. a string with format characters. a list of values to insert into @format. Sets @task’s result to a new [type@GLib.Error] created from @domain, @code, @message and completes the task. See [method@Gio.Task.return_pointer] for more discussion of exactly what ‘completing the task’ means. See also [method@Gio.Task.return_new_error]. a #GTask. a #GQuark. an error code. an error message Sets @task's result to @result and completes the task. If @result is not %NULL, then @result_destroy will be used to free @result if the caller does not take ownership of it with g_task_propagate_pointer(). "Completes the task" means that for an ordinary asynchronous task it will either invoke the task's callback, or else queue that callback to be invoked in the proper #GMainContext, or in the next iteration of the current #GMainContext. For a task run via g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this method will save @result to be returned to the caller later, but the task will not actually be completed until the #GTaskThreadFunc exits. Note that since the task may be completed before returning from g_task_return_pointer(), you cannot assume that @result is still valid after calling this, unless you are still holding another reference on it. a #GTask the pointer result of a task function a #GDestroyNotify function. Sets @task's result to @error (which @task assumes ownership of), with the message prefixed according to @format, and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). Note that since the task takes ownership of @error, and since the task may be completed before returning from g_task_return_prefixed_error(), you cannot assume that @error is still valid after calling this. Call g_error_copy() on the error if you need to keep a local copy as well. See also g_task_return_error(), g_prefix_error(). a #GTask. the #GError result of a task function. a string with format characters. a list of values to insert into @format. Sets @task's result to @result (by copying it) and completes the task. If @result is %NULL then a #GValue of type %G_TYPE_POINTER with a value of %NULL will be used for the result. This is a very generic low-level method intended primarily for use by language bindings; for C code, g_task_return_pointer() and the like will normally be much easier to use. a #GTask the #GValue result of a task function Runs @task_func in another thread. When @task_func returns, @task's #GAsyncReadyCallback will be invoked in @task's #GMainContext. This takes a ref on @task until the task completes. See #GTaskThreadFunc for more details about how @task_func is handled. Although GLib currently rate-limits the tasks queued via g_task_run_in_thread(), you should not assume that it will always do this. If you have a very large number of tasks to run (several tens of tasks), but don't want them to all run at once, you should only queue a limited number of them (around ten) at a time. Be aware that if your task depends on other tasks to complete, use of this function could lead to a livelock if the other tasks also use this function and enough of them (around 10) execute in a dependency chain, as that will exhaust the thread pool. If this situation is possible, consider using a separate worker thread or thread pool explicitly, rather than using g_task_run_in_thread(). a #GTask a #GTaskThreadFunc Runs @task_func in another thread, and waits for it to return or be cancelled. You can use g_task_propagate_pointer(), etc, afterward to get the result of @task_func. See #GTaskThreadFunc for more details about how @task_func is handled. Normally this is used with tasks created with a %NULL `callback`, but note that even if the task does have a callback, it will not be invoked when @task_func returns. #GTask:completed will be set to %TRUE just before this function returns. Although GLib currently rate-limits the tasks queued via g_task_run_in_thread_sync(), you should not assume that it will always do this. If you have a very large number of tasks to run, but don't want them to all run at once, you should only queue a limited number of them at a time. a #GTask a #GTaskThreadFunc Sets or clears @task's check-cancellable flag. If this is %TRUE (the default), then g_task_propagate_pointer(), etc, and g_task_had_error() will check the task's #GCancellable first, and if it has been cancelled, then they will consider the task to have returned an "Operation was cancelled" error (%G_IO_ERROR_CANCELLED), regardless of any other error or return value the task may have had. If @check_cancellable is %FALSE, then the #GTask will not check the cancellable itself, and it is up to @task's owner to do this (eg, via g_task_return_error_if_cancelled()). If you are using g_task_set_return_on_cancel() as well, then you must leave check-cancellable set %TRUE. the #GTask whether #GTask will check the state of its #GCancellable for you. Sets @task’s name, used in debugging and profiling. The name defaults to %NULL. The task name should describe in a human readable way what the task does. For example, ‘Open file’ or ‘Connect to network host’. It is used to set the name of the #GSource used for idle completion of the task. This function may only be called before the @task is first used in a thread other than the one it was constructed in. a #GTask a human readable name for the task, or %NULL to unset it Sets @task's priority. If you do not call this, it will default to %G_PRIORITY_DEFAULT. This will affect the priority of #GSources created with g_task_attach_source() and the scheduling of tasks run in threads, and can also be explicitly retrieved later via g_task_get_priority(). the #GTask the [priority](iface.AsyncResult.html#io-priority) of the request Sets or clears @task's return-on-cancel flag. This is only meaningful for tasks run via g_task_run_in_thread() or g_task_run_in_thread_sync(). If @return_on_cancel is %TRUE, then cancelling @task's #GCancellable will immediately cause it to return, as though the task's #GTaskThreadFunc had called g_task_return_error_if_cancelled() and then returned. This allows you to create a cancellable wrapper around an uninterruptible function. The #GTaskThreadFunc just needs to be careful that it does not modify any externally-visible state after it has been cancelled. To do that, the thread should call g_task_set_return_on_cancel() again to (atomically) set return-on-cancel %FALSE before making externally-visible changes; if the task gets cancelled before the return-on-cancel flag could be changed, g_task_set_return_on_cancel() will indicate this by returning %FALSE. You can disable and re-enable this flag multiple times if you wish. If the task's #GCancellable is cancelled while return-on-cancel is %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE again will cause the task to be cancelled at that point. If the task's #GCancellable is already cancelled before you call g_task_run_in_thread()/g_task_run_in_thread_sync(), then the #GTaskThreadFunc will still be run (for consistency), but the task will also be completed right away. %TRUE if @task's return-on-cancel flag was changed to match @return_on_cancel. %FALSE if @task has already been cancelled. the #GTask whether the task returns automatically when it is cancelled. Sets @task's source tag. You can use this to tag a task return value with a particular pointer (usually a pointer to the function doing the tagging) and then later check it using g_task_get_source_tag() (or g_async_result_is_tagged()) in the task's "finish" function, to figure out if the response came from a particular place. A macro wrapper around this function will automatically set the task’s name to the string form of @source_tag if it’s not already set, for convenience. the #GTask an opaque pointer indicating the source of this task Sets @task’s name, used in debugging and profiling. This is a variant of g_task_set_name() that avoids copying @name. This function is called automatically by [method@Gio.Task.set_source_tag] unless a name is set. a #GTask a human readable name for the task. Must be a string literal Sets @task's task data (freeing the existing task data, if any). the #GTask task-specific data #GDestroyNotify for @task_data Whether the task has completed, meaning its callback (if set) has been invoked. This can only happen after g_task_return_pointer(), g_task_return_error() or one of the other return functions have been called on the task. However, it is not guaranteed to happen immediately after those functions are called, as the task’s callback may need to be scheduled to run in a different thread. That means it is **not safe** to use this property to track whether a return function has been called on the #GTask. Callers must do that tracking themselves, typically by linking the lifetime of the #GTask to the control flow of their code. This property is guaranteed to change from %FALSE to %TRUE exactly once. The #GObject::notify signal for this change is emitted in the same main context as the task’s callback, immediately after that callback is invoked. The prototype for a task function to be run in a thread via g_task_run_in_thread() or g_task_run_in_thread_sync(). If the return-on-cancel flag is set on @task, and @cancellable gets cancelled, then the #GTask will be completed immediately (as though g_task_return_error_if_cancelled() had been called), without waiting for the task function to complete. However, the task function will continue running in its thread in the background. The function therefore needs to be careful about how it uses externally-visible state in this case. See g_task_set_return_on_cancel() for more details. Other than in that case, @task will be completed when the #GTaskThreadFunc returns, not when it calls a `g_task_return_` function. the #GTask @task's source object @task's task data @task's #GCancellable, or %NULL This is the subclass of [class@Gio.SocketConnection] that is created for TCP/IP sockets. Checks if graceful disconnects are used. See g_tcp_connection_set_graceful_disconnect(). %TRUE if graceful disconnect is used on close, %FALSE otherwise a #GTcpConnection This enables graceful disconnects on close. A graceful disconnect means that we signal the receiving end that the connection is terminated and wait for it to close the connection before closing the connection. A graceful disconnect means that we can be sure that we successfully sent all the outstanding data to the other end, or get an error reported. However, it also means we have to wait for all the data to reach the other side and for it to acknowledge this by closing the socket, which may take a while. For this reason it is disabled by default. a #GTcpConnection Whether to do graceful disconnects or not Whether [method@Gio.IOStream.close] does a graceful disconnect. A `GTcpWrapperConnection` can be used to wrap a [class@Gio.IOStream] that is based on a [class@Gio.Socket], but which is not actually a [class@Gio.SocketConnection]. This is used by [class@Gio.SocketClient] so that it can always return a [class@Gio.SocketConnection], even when the connection it has actually created is not directly a [class@Gio.SocketConnection]. Wraps @base_io_stream and @socket together as a #GSocketConnection. the new #GSocketConnection. the #GIOStream to wrap the #GSocket associated with @base_io_stream Gets @conn's base #GIOStream @conn's base #GIOStream a #GTcpWrapperConnection The wrapped [class@Gio.IOStream]. A helper class for testing code which uses D-Bus without touching the user’s session bus. Note that `GTestDBus` modifies the user’s environment, calling [`setenv()`](man:setenv(3)). This is not thread-safe, so all `GTestDBus` calls should be completed before threads are spawned, or should have appropriate locking to ensure no access conflicts to environment variables shared between `GTestDBus` and other threads. ## Creating unit tests using `GTestDBus` Testing of D-Bus services can be tricky because normally we only ever run D-Bus services over an existing instance of the D-Bus daemon thus we usually don’t activate D-Bus services that are not yet installed into the target system. The `GTestDBus` object makes this easier for us by taking care of the lower level tasks such as running a private D-Bus daemon and looking up uninstalled services in customizable locations, typically in your source code tree. The first thing you will need is a separate service description file for the D-Bus daemon. Typically a `services` subdirectory of your `tests` directory is a good place to put this file. The service file should list your service along with an absolute path to the uninstalled service executable in your source tree. Using autotools we would achieve this by adding a file such as `my-server.service.in` in the services directory and have it processed by configure. ``` [D-BUS Service] Name=org.gtk.GDBus.Examples.ObjectManager Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server ``` You will also need to indicate this service directory in your test fixtures, so you will need to pass the path while compiling your test cases. Typically this is done with autotools with an added preprocessor flag specified to compile your tests such as: ``` -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" ``` Once you have a service definition file which is local to your source tree, you can proceed to set up a GTest fixture using the `GTestDBus` scaffolding. An example of a test fixture for D-Bus services can be found here: [gdbus-test-fixture.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-test-fixture.c) Note that these examples only deal with isolating the D-Bus aspect of your service. To successfully run isolated unit tests on your service you may need some additional modifications to your test case fixture. For example; if your service uses [class@Gio.Settings] and installs a schema then it is important that your test service not load the schema in the ordinary installed location (chances are that your service and schema files are not yet installed, or worse; there is an older version of the schema file sitting in the install location). Most of the time we can work around these obstacles using the environment. Since the environment is inherited by the D-Bus daemon created by `GTestDBus` and then in turn inherited by any services the D-Bus daemon activates, using the setup routine for your fixture is a practical place to help sandbox your runtime environment. For the rather typical GSettings case we can work around this by setting `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas in the above `fixture_setup()` routine. The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved by compiling the schemas locally as a step before running test cases, an autotools setup might do the following in the directory holding schemas: ``` all-am: $(GLIB_COMPILE_SCHEMAS) . CLEANFILES += gschemas.compiled ``` Create a new #GTestDBus object. a new #GTestDBus. a #GTestDBusFlags Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test won't use user's session bus. This is useful for unit tests that want to verify behaviour when no session bus is running. It is not necessary to call this if unit test already calls g_test_dbus_up() before acquiring the session bus. Add a path where dbus-daemon will look up .service files. This can't be called after g_test_dbus_up(). a #GTestDBus path to a directory containing .service files Stop the session bus started by g_test_dbus_up(). This will wait for the singleton returned by g_bus_get() or g_bus_get_sync() to be destroyed. This is done to ensure that the next unit test won't get a leaked singleton from this test. a #GTestDBus Get the address on which dbus-daemon is running. If g_test_dbus_up() has not been called yet, %NULL is returned. This can be used with g_dbus_connection_new_for_address(). the address of the bus, or %NULL. a #GTestDBus Get the flags of the #GTestDBus object. the value of #GTestDBus:flags property a #GTestDBus Stop the session bus started by g_test_dbus_up(). Unlike g_test_dbus_down(), this won't verify the #GDBusConnection singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit tests wanting to verify behaviour after the session bus has been stopped can use this function but should still call g_test_dbus_down() when done. a #GTestDBus Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this call, it is safe for unit tests to start sending messages on the session bus. If this function is called from setup callback of g_test_add(), g_test_dbus_down() must be called in its teardown callback. If this function is called from unit test's main(), then g_test_dbus_down() must be called after g_test_run(). a #GTestDBus #GTestDBusFlags specifying the behaviour of the D-Bus session. Flags to define future #GTestDBus behaviour. No flags. `GThemedIcon` is an implementation of [iface@Gio.Icon] that supports icon themes. `GThemedIcon` contains a list of all of the icons present in an icon theme, so that icons can be looked up quickly. `GThemedIcon` does not provide actual pixmaps for icons, just the icon names. Ideally something like [method@Gtk.IconTheme.choose_icon] should be used to resolve the list of names so that fallback icons work nicely with themes that inherit other themes. Creates a new themed icon for @iconname. a new #GThemedIcon. a string containing an icon name. Creates a new themed icon for @iconnames. a new #GThemedIcon an array of strings containing icon names. the length of the @iconnames array, or -1 if @iconnames is %NULL-terminated Creates a new themed icon for @iconname, and all the names that can be created by shortening @iconname at '-' characters. In the following example, @icon1 and @icon2 are equivalent: |[<!-- language="C" --> const char *names[] = { "gnome-dev-cdrom-audio", "gnome-dev-cdrom", "gnome-dev", "gnome" }; icon1 = g_themed_icon_new_from_names (names, 4); icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio"); ]| a new #GThemedIcon. a string containing an icon name Append a name to the list of icons from within @icon. Note that doing so invalidates the hash computed by prior calls to g_icon_hash(). a #GThemedIcon name of icon to append to list of icons from within @icon. Gets the names of icons from within @icon. a list of icon names. a #GThemedIcon. Prepend a name to the list of icons from within @icon. Note that doing so invalidates the hash computed by prior calls to g_icon_hash(). a #GThemedIcon name of icon to prepend to list of icons from within @icon. The icon name. A %NULL-terminated array of icon names. Whether to use the default fallbacks found by shortening the icon name at '-' characters. If the "names" array has more than one element, ignores any past the first. For example, if the icon name was "gnome-dev-cdrom-audio", the array would become |[<!-- language="C" --> { "gnome-dev-cdrom-audio", "gnome-dev-cdrom", "gnome-dev", "gnome", NULL }; ]| #GThreadedResolver is an implementation of #GResolver which calls the libc lookup functions in threads to allow them to run asynchronously. A `GThreadedSocketService` is a simple subclass of [class@Gio.SocketService] that handles incoming connections by creating a worker thread and dispatching the connection to it by emitting the [signal@Gio.ThreadedSocketService::run signal] in the new thread. The signal handler may perform blocking I/O and need not return until the connection is closed. The service is implemented using a thread pool, so there is a limited amount of threads available to serve incoming requests. The service automatically stops the [class@Gio.SocketService] from accepting new connections when all threads are busy. As with [class@Gio.SocketService], you may connect to [signal@Gio.ThreadedSocketService::run], or subclass and override the default handler. Creates a new #GThreadedSocketService with no listeners. Listeners must be added with one of the #GSocketListener "add" methods. a new #GSocketService. the maximal number of threads to execute concurrently handling incoming clients, -1 means no limit The maximum number of threads handling clients for this service. The ::run signal is emitted in a worker thread in response to an incoming connection. This thread is dedicated to handling @connection and may perform blocking IO. The signal handler need not return until the connection is closed. %TRUE to stop further signal handlers from being called a new #GSocketConnection object. the source_object passed to g_socket_listener_add_address(). The client authentication mode for a #GTlsServerConnection. client authentication not required client authentication is requested client authentication is required TLS (Transport Layer Security, aka SSL) and DTLS backend. This is an internal type used to coordinate the different classes implemented by a TLS backend. Gets the default #GTlsBackend for the system. a #GTlsBackend, which will be a dummy object if no TLS backend is available Gets the default #GTlsDatabase used to verify TLS connections. the default database, which should be unreffed when done. the #GTlsBackend Checks if DTLS is supported. DTLS support may not be available even if TLS support is available, and vice-versa. whether DTLS is supported the #GTlsBackend Checks if TLS is supported; if this returns %FALSE for the default #GTlsBackend, it means no "real" TLS backend is available. whether or not TLS is supported the #GTlsBackend Gets the #GType of @backend's #GTlsCertificate implementation. the #GType of @backend's #GTlsCertificate implementation. the #GTlsBackend Gets the #GType of @backend's #GTlsClientConnection implementation. the #GType of @backend's #GTlsClientConnection implementation. the #GTlsBackend Gets the default #GTlsDatabase used to verify TLS connections. the default database, which should be unreffed when done. the #GTlsBackend Gets the #GType of @backend’s #GDtlsClientConnection implementation. the #GType of @backend’s #GDtlsClientConnection implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. the #GTlsBackend Gets the #GType of @backend’s #GDtlsServerConnection implementation. the #GType of @backend’s #GDtlsServerConnection implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. the #GTlsBackend Gets the #GType of @backend's #GTlsFileDatabase implementation. the #GType of backend's #GTlsFileDatabase implementation. the #GTlsBackend Gets the #GType of @backend's #GTlsServerConnection implementation. the #GType of @backend's #GTlsServerConnection implementation. the #GTlsBackend Set the default #GTlsDatabase used to verify TLS connections Any subsequent call to g_tls_backend_get_default_database() will return the database set in this call. Existing databases and connections are not modified. Setting a %NULL default database will reset to using the system default database as if g_tls_backend_set_default_database() had never been called. the #GTlsBackend the #GTlsDatabase Checks if DTLS is supported. DTLS support may not be available even if TLS support is available, and vice-versa. whether DTLS is supported the #GTlsBackend Checks if TLS is supported; if this returns %FALSE for the default #GTlsBackend, it means no "real" TLS backend is available. whether or not TLS is supported the #GTlsBackend Provides an interface for describing TLS-related types. The parent interface. returns whether the backend supports TLS. whether or not TLS is supported the #GTlsBackend returns the #GTlsCertificate implementation type returns the #GTlsClientConnection implementation type returns the #GTlsServerConnection implementation type returns the #GTlsFileDatabase implementation type. returns a default #GTlsDatabase instance. the default database, which should be unreffed when done. the #GTlsBackend returns whether the backend supports DTLS whether DTLS is supported the #GTlsBackend returns the #GDtlsClientConnection implementation type returns the #GDtlsServerConnection implementation type A certificate used for TLS authentication and encryption. This can represent either a certificate only (eg, the certificate received by a client from a server), or the combination of a certificate and a private key (which is needed when acting as a [iface@Gio.TlsServerConnection]). Creates a #GTlsCertificate from the data in @file. As of 2.72, if the filename ends in `.p12` or `.pfx` the data is loaded by g_tls_certificate_new_from_pkcs12() otherwise it is loaded by g_tls_certificate_new_from_pem(). See those functions for exact details. If @file cannot be read or parsed, the function will return %NULL and set @error. the new certificate, or %NULL on error file containing a certificate to import Creates a #GTlsCertificate from the data in @file. If @file cannot be read or parsed, the function will return %NULL and set @error. Any unknown file types will error with %G_IO_ERROR_NOT_SUPPORTED. Currently only `.p12` and `.pfx` files are supported. See g_tls_certificate_new_from_pkcs12() for more details. the new certificate, or %NULL on error file containing a certificate to import password for PKCS #12 files Creates a #GTlsCertificate from the PEM-encoded data in @cert_file and @key_file. The returned certificate will be the first certificate found in @cert_file. As of GLib 2.44, if @cert_file contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the #GTlsCertificate:issuer property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned. If either file cannot be read or parsed, the function will return %NULL and set @error. Otherwise, this behaves like g_tls_certificate_new_from_pem(). the new certificate, or %NULL on error file containing one or more PEM-encoded certificates to import file containing a PEM-encoded private key to import Creates a #GTlsCertificate from the PEM-encoded data in @data. If @data includes both a certificate and a private key, then the returned certificate will include the private key data as well. (See the #GTlsCertificate:private-key-pem property for information about supported formats.) The returned certificate will be the first certificate found in @data. As of GLib 2.44, if @data contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the #GTlsCertificate:issuer property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned. the new certificate, or %NULL if @data is invalid PEM-encoded certificate data the length of @data, or -1 if it's 0-terminated. Creates a #GTlsCertificate from a [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) URI. An example @pkcs11_uri would be `pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01` Where the token’s layout is: |[ Object 0: URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=private%20key;type=private Type: Private key (RSA-2048) ID: 01 Object 1: URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=Certificate%20for%20Authentication;type=cert Type: X.509 Certificate (RSA-2048) ID: 01 ]| In this case the certificate and private key would both be detected and used as expected. @pkcs_uri may also just reference an X.509 certificate object and then optionally @private_key_pkcs11_uri allows using a private key exposed under a different URI. Note that the private key is not accessed until usage and may fail or require a PIN later. the new certificate, or %NULL on error A PKCS \#11 URI A PKCS \#11 URI Creates a #GTlsCertificate from the data in @data. It must contain a certificate and matching private key. If extra certificates are included they will be verified as a chain and the #GTlsCertificate:issuer property will be set. All other data will be ignored. You can pass as single password for all of the data which will be used both for the PKCS #12 container as well as encrypted private keys. If decryption fails it will error with %G_TLS_ERROR_BAD_CERTIFICATE_PASSWORD. This constructor requires support in the current #GTlsBackend. If support is missing it will error with %G_IO_ERROR_NOT_SUPPORTED. Other parsing failures will error with %G_TLS_ERROR_BAD_CERTIFICATE. the new certificate, or %NULL if @data is invalid DER-encoded PKCS #12 format certificate data the length of @data optional password for encrypted certificate data Creates one or more #GTlsCertificates from the PEM-encoded data in @file. If @file cannot be read or parsed, the function will return %NULL and set @error. If @file does not contain any PEM-encoded certificates, this will return an empty list and not set @error. a #GList containing #GTlsCertificate objects. You must free the list and its contents when you are done with it. file containing PEM-encoded certificates to import This verifies @cert and returns a set of #GTlsCertificateFlags indicating any problems found with it. This can be used to verify a certificate outside the context of making a connection, or to check a certificate against a CA that is not part of the system CA database. If @cert is valid, %G_TLS_CERTIFICATE_NO_FLAGS is returned. If @identity is not %NULL, @cert's name(s) will be compared against it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return value if it does not match. If @identity is %NULL, that bit will never be set in the return value. If @trusted_ca is not %NULL, then @cert (or one of the certificates in its chain) must be signed by it, or else %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If @trusted_ca is %NULL, that bit will never be set in the return value. GLib guarantees that if certificate verification fails, at least one error will be set in the return value, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Because TLS session context is not used, #GTlsCertificate may not perform as many checks on the certificates as #GTlsConnection would. For example, certificate constraints may not be honored, and revocation checks may not be performed. The best way to verify TLS certificates used by a TLS connection is to let #GTlsConnection handle the verification. the appropriate #GTlsCertificateFlags a #GTlsCertificate the expected peer identity the certificate of a trusted authority Gets the value of #GTlsCertificate:dns-names. A #GPtrArray of #GBytes elements, or %NULL if it's not available. a #GTlsCertificate Gets the value of #GTlsCertificate:ip-addresses. A #GPtrArray of #GInetAddress elements, or %NULL if it's not available. a #GTlsCertificate Gets the #GTlsCertificate representing @cert's issuer, if known The certificate of @cert's issuer, or %NULL if @cert is self-signed or signed with an unknown certificate. a #GTlsCertificate Returns the issuer name from the certificate. The issuer name, or %NULL if it's not available. a #GTlsCertificate Returns the time at which the certificate became or will become invalid. The not-valid-after date, or %NULL if it's not available. a #GTlsCertificate Returns the time at which the certificate became or will become valid. The not-valid-before date, or %NULL if it's not available. a #GTlsCertificate Returns the subject name from the certificate. The subject name, or %NULL if it's not available. a #GTlsCertificate Check if two #GTlsCertificate objects represent the same certificate. The raw DER byte data of the two certificates are checked for equality. This has the effect that two certificates may compare equal even if their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or #GTlsCertificate:private-key-pem properties differ. whether the same or not first certificate to compare second certificate to compare This verifies @cert and returns a set of #GTlsCertificateFlags indicating any problems found with it. This can be used to verify a certificate outside the context of making a connection, or to check a certificate against a CA that is not part of the system CA database. If @cert is valid, %G_TLS_CERTIFICATE_NO_FLAGS is returned. If @identity is not %NULL, @cert's name(s) will be compared against it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return value if it does not match. If @identity is %NULL, that bit will never be set in the return value. If @trusted_ca is not %NULL, then @cert (or one of the certificates in its chain) must be signed by it, or else %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If @trusted_ca is %NULL, that bit will never be set in the return value. GLib guarantees that if certificate verification fails, at least one error will be set in the return value, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Because TLS session context is not used, #GTlsCertificate may not perform as many checks on the certificates as #GTlsConnection would. For example, certificate constraints may not be honored, and revocation checks may not be performed. The best way to verify TLS certificates used by a TLS connection is to let #GTlsConnection handle the verification. the appropriate #GTlsCertificateFlags a #GTlsCertificate the expected peer identity the certificate of a trusted authority The DER (binary) encoded representation of the certificate. This property and the #GTlsCertificate:certificate-pem property represent the same data, just in different forms. The PEM (ASCII) encoded representation of the certificate. This property and the #GTlsCertificate:certificate property represent the same data, just in different forms. The DNS names from the certificate's Subject Alternative Names (SANs), %NULL if unavailable. The IP addresses from the certificate's Subject Alternative Names (SANs), %NULL if unavailable. A #GTlsCertificate representing the entity that issued this certificate. If %NULL, this means that the certificate is either self-signed, or else the certificate of the issuer is not available. Beware the issuer certificate may not be the same as the certificate that would actually be used to construct a valid certification path during certificate verification. [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains why an issuer certificate cannot be naively assumed to be part of the the certification path (though GLib's TLS backends may not follow the path building strategies outlined in this RFC). Due to the complexity of certification path building, GLib does not provide any way to know which certification path will actually be used. Accordingly, this property cannot be used to make security-related decisions. Only GLib itself should make security decisions about TLS certificates. The issuer from the certificate, %NULL if unavailable. The time at which this cert is no longer valid, %NULL if unavailable. The time at which this cert is considered to be valid, %NULL if unavailable. An optional password used when constructed with GTlsCertificate:pkcs12-data. A URI referencing the [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) objects containing an X.509 certificate and optionally a private key. If %NULL, the certificate is either not backed by PKCS \#11 or the #GTlsBackend does not support PKCS \#11. The PKCS #12 formatted data used to construct the object. See also: g_tls_certificate_new_from_pkcs12() The DER (binary) encoded representation of the certificate's private key, in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017) or unencrypted [PKCS \#8 format.](https://datatracker.ietf.org/doc/html/rfc5208) PKCS \#8 format is supported since 2.32; earlier releases only support PKCS \#1. You can use the `openssl rsa` tool to convert PKCS \#8 keys to PKCS \#1. This property (or the #GTlsCertificate:private-key-pem property) can be set when constructing a key (for example, from a file). Since GLib 2.70, it is now also readable; however, be aware that if the private key is backed by a PKCS \#11 URI – for example, if it is stored on a smartcard – then this property will be %NULL. If so, the private key must be referenced via its PKCS \#11 URI, #GTlsCertificate:private-key-pkcs11-uri. You must check both properties to see if the certificate really has a private key. When this property is read, the output format will be unencrypted PKCS \#8. The PEM (ASCII) encoded representation of the certificate's private key in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017) ("`BEGIN RSA PRIVATE KEY`") or unencrypted [PKCS \#8 format](https://datatracker.ietf.org/doc/html/rfc5208) ("`BEGIN PRIVATE KEY`"). PKCS \#8 format is supported since 2.32; earlier releases only support PKCS \#1. You can use the `openssl rsa` tool to convert PKCS \#8 keys to PKCS \#1. This property (or the #GTlsCertificate:private-key property) can be set when constructing a key (for example, from a file). Since GLib 2.70, it is now also readable; however, be aware that if the private key is backed by a PKCS \#11 URI - for example, if it is stored on a smartcard - then this property will be %NULL. If so, the private key must be referenced via its PKCS \#11 URI, #GTlsCertificate:private-key-pkcs11-uri. You must check both properties to see if the certificate really has a private key. When this property is read, the output format will be unencrypted PKCS \#8. A URI referencing a [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) object containing a private key. The subject from the cert, %NULL if unavailable. the appropriate #GTlsCertificateFlags a #GTlsCertificate the expected peer identity the certificate of a trusted authority A set of flags describing TLS certification validation. This can be used to describe why a particular certificate was rejected (for example, in #GTlsConnection::accept-certificate). GLib guarantees that if certificate verification fails, at least one flag will be set, but it does not guarantee that all possible flags will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. No flags set. Since: 2.74 The signing certificate authority is not known. The certificate does not match the expected identity of the site that it was retrieved from. The certificate's activation time is still in the future The certificate has expired The certificate has been revoked according to the #GTlsConnection's certificate revocation list. The certificate's algorithm is considered insecure. Some other error occurred validating the certificate the combination of all of the above flags Flags for g_tls_interaction_request_certificate(), g_tls_interaction_request_certificate_async(), and g_tls_interaction_invoke_request_certificate(). No flags An error code used with %G_TLS_CHANNEL_BINDING_ERROR in a #GError to indicate a TLS channel binding retrieval error. Either entire binding retrieval facility or specific binding type is not implemented in the TLS backend. The handshake is not yet complete on the connection which is a strong requirement for any existing binding type. Handshake is complete but binding data is not available. That normally indicates the TLS implementation failed to provide the binding data. For example, some implementations do not provide a peer certificate for resumed connections. Binding type is not supported on the current connection. This error could be triggered when requesting `tls-server-end-point` binding data for a certificate which has no hash function or uses multiple hash functions. Any other backend error preventing binding data retrieval. Gets the TLS channel binding error quark. a #GQuark. The type of TLS channel binding data to retrieve from #GTlsConnection or #GDtlsConnection, as documented by RFC 5929 or RFC 9266. The [`tls-unique-for-telnet`](https://tools.ietf.org/html/rfc5929#section-5) binding type is not currently implemented. [`tls-unique`](https://tools.ietf.org/html/rfc5929#section-3) binding type [`tls-server-end-point`](https://tools.ietf.org/html/rfc5929#section-4) binding type [`tls-exporter`](https://www.rfc-editor.org/rfc/rfc9266.html) binding type. Since: 2.74 `GTlsClientConnection` is the client-side subclass of [class@Gio.TlsConnection], representing a client-side TLS connection. Creates a new #GTlsClientConnection wrapping @base_io_stream (which must have pollable input and output streams) which is assumed to communicate with the server identified by @server_identity. See the documentation for #GTlsConnection:base-io-stream for restrictions on when application code can run operations on the @base_io_stream after this function has returned. the new #GTlsClientConnection, or %NULL on error the #GIOStream to wrap the expected identity of the server Possibly copies session state from one connection to another, for use in TLS session resumption. This is not normally needed, but may be used when the same session needs to be used between different endpoints, as is required by some protocols, such as FTP over TLS. @source should have already completed a handshake and, since TLS 1.3, it should have been used to read data at least once. @conn should not have completed a handshake. It is not possible to know whether a call to this function will actually do anything. Because session resumption is normally used only for performance benefit, the TLS backend might not implement this function. Even if implemented, it may not actually succeed in allowing @conn to resume @source's TLS session, because the server may not have sent a session resumption token to @source, or it may refuse to accept the token from @conn. There is no way to know whether a call to this function is actually successful. Using this function is not required to benefit from session resumption. If the TLS backend supports session resumption, the session will be resumed automatically if it is possible to do so without weakening the privacy guarantees normally provided by TLS, without need to call this function. For example, with TLS 1.3, a session ticket will be automatically copied from any #GTlsClientConnection that has previously received session tickets from the server, provided a ticket is available that has not previously been used for session resumption, since session ticket reuse would be a privacy weakness. Using this function causes the ticket to be copied without regard for privacy considerations. a #GTlsClientConnection a #GTlsClientConnection Possibly copies session state from one connection to another, for use in TLS session resumption. This is not normally needed, but may be used when the same session needs to be used between different endpoints, as is required by some protocols, such as FTP over TLS. @source should have already completed a handshake and, since TLS 1.3, it should have been used to read data at least once. @conn should not have completed a handshake. It is not possible to know whether a call to this function will actually do anything. Because session resumption is normally used only for performance benefit, the TLS backend might not implement this function. Even if implemented, it may not actually succeed in allowing @conn to resume @source's TLS session, because the server may not have sent a session resumption token to @source, or it may refuse to accept the token from @conn. There is no way to know whether a call to this function is actually successful. Using this function is not required to benefit from session resumption. If the TLS backend supports session resumption, the session will be resumed automatically if it is possible to do so without weakening the privacy guarantees normally provided by TLS, without need to call this function. For example, with TLS 1.3, a session ticket will be automatically copied from any #GTlsClientConnection that has previously received session tickets from the server, provided a ticket is available that has not previously been used for session resumption, since session ticket reuse would be a privacy weakness. Using this function causes the ticket to be copied without regard for privacy considerations. a #GTlsClientConnection a #GTlsClientConnection Gets the list of distinguished names of the Certificate Authorities that the server will accept certificates from. This will be set during the TLS handshake if the server requests a certificate. Otherwise, it will be %NULL. Each item in the list is a #GByteArray which contains the complete subject DN of the certificate authority. the list of CA DNs. You should unref each element with g_byte_array_unref() and then the free the list with g_list_free(). the #GTlsClientConnection Gets @conn's expected server identity a #GSocketConnectable describing the expected server identity, or %NULL if the expected identity is not known. the #GTlsClientConnection SSL 3.0 is no longer supported. See g_tls_client_connection_set_use_ssl3() for details. SSL 3.0 is insecure. %FALSE the #GTlsClientConnection Gets @conn's validation flags This function does not work as originally designed and is impossible to use correctly. See #GTlsClientConnection:validation-flags for more information. Do not attempt to ignore validation errors. the validation flags the #GTlsClientConnection Sets @conn's expected server identity, which is used both to tell servers on virtual hosts which certificate to present, and also to let @conn know what name to look for in the certificate when performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. the #GTlsClientConnection a #GSocketConnectable describing the expected server identity Since GLib 2.42.1, SSL 3.0 is no longer supported. From GLib 2.42.1 through GLib 2.62, this function could be used to force use of TLS 1.0, the lowest-supported TLS protocol version at the time. In the past, this was needed to connect to broken TLS servers that exhibited protocol version intolerance. Such servers are no longer common, and using TLS 1.0 is no longer considered acceptable. Since GLib 2.64, this function does nothing. SSL 3.0 is insecure. the #GTlsClientConnection a #gboolean, ignored Sets @conn's validation flags, to override the default set of checks performed when validating a server certificate. By default, %G_TLS_CERTIFICATE_VALIDATE_ALL is used. This function does not work as originally designed and is impossible to use correctly. See #GTlsClientConnection:validation-flags for more information. Do not attempt to ignore validation errors. the #GTlsClientConnection the #GTlsCertificateFlags to use A list of the distinguished names of the Certificate Authorities that the server will accept client certificates signed by. If the server requests a client certificate during the handshake, then this property will be set after the handshake completes. Each item in the list is a #GByteArray which contains the complete subject DN of the certificate authority. A #GSocketConnectable describing the identity of the server that is expected on the other end of the connection. If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in #GTlsClientConnection:validation-flags, this object will be used to determine the expected identify of the remote end of the connection; if #GTlsClientConnection:server-identity is not set, or does not match the identity presented by the server, then the %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail. In addition to its use in verifying the server certificate, this is also used to give a hint to the server about what certificate we expect, which is useful for servers that serve virtual hosts. SSL 3.0 is no longer supported. See g_tls_client_connection_set_use_ssl3() for details. SSL 3.0 is insecure. What steps to perform when validating a certificate received from a server. Server certificates that fail to validate in any of the ways indicated here will be rejected unless the application overrides the default via #GTlsConnection::accept-certificate. GLib guarantees that if certificate verification fails, at least one flag will be set, but it does not guarantee that all possible flags will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Therefore, there is no safe way to use this property. This is not a horrible problem, though, because you should not be attempting to ignore validation errors anyway. If you really must ignore TLS certificate errors, connect to #GTlsConnection::accept-certificate. Do not attempt to ignore validation errors. vtable for a #GTlsClientConnection implementation. The parent interface. Copies session state from one #GTlsClientConnection to another. a #GTlsClientConnection a #GTlsClientConnection `GTlsConnection` is the base TLS connection class type, which wraps a [class@Gio.IOStream] and provides TLS encryption on top of it. Its subclasses, [iface@Gio.TlsClientConnection] and [iface@Gio.TlsServerConnection], implement client-side and server-side TLS, respectively. For DTLS (Datagram TLS) support, see [iface@Gio.DtlsConnection]. Check whether to accept a certificate. Retrieve TLS channel binding data (Since: 2.66) Gets the name of the application-layer protocol negotiated during the handshake. If the peer did not use the ALPN extension, or did not advertise a protocol that matched one of @conn's protocols, or the TLS backend does not support ALPN, then this will be %NULL. See g_tls_connection_set_advertised_protocols(). the negotiated protocol, or %NULL a #GTlsConnection Attempts a TLS handshake on @conn. On the client side, it is never necessary to call this method; although the connection needs to perform a handshake after connecting (or after sending a "STARTTLS"-type command), #GTlsConnection will handle this for you automatically when you try to send or receive data on the connection. You can call g_tls_connection_handshake() manually if you want to know whether the initial handshake succeeded or failed (as opposed to just immediately trying to use @conn to read or write, in which case, if it fails, it may not be possible to tell if it failed before or after completing the handshake), but beware that servers may reject client authentication after the handshake has completed, so a successful handshake does not indicate the connection will be usable. Likewise, on the server side, although a handshake is necessary at the beginning of the communication, you do not need to call this function explicitly unless you want clearer error reporting. Previously, calling g_tls_connection_handshake() after the initial handshake would trigger a rehandshake; however, this usage was deprecated in GLib 2.60 because rehandshaking was removed from the TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after the initial handshake will no longer do anything. When using a #GTlsConnection created by #GSocketClient, the #GSocketClient performs the initial handshake, so calling this function manually is not recommended. #GTlsConnection::accept_certificate may be emitted during the handshake. success or failure a #GTlsConnection a #GCancellable, or %NULL Asynchronously performs a TLS handshake on @conn. See g_tls_connection_handshake() for more information. a #GTlsConnection the [I/O priority](iface.AsyncResult.html#io-priority) of the request a #GCancellable, or %NULL callback to call when the handshake is complete the data to pass to the callback function Finish an asynchronous TLS handshake operation. See g_tls_connection_handshake() for more information. %TRUE on success, %FALSE on failure, in which case @error will be set. a #GTlsConnection a #GAsyncResult. Used by #GTlsConnection implementations to emit the #GTlsConnection::accept-certificate signal. %TRUE if one of the signal handlers has returned %TRUE to accept @peer_cert a #GTlsConnection the peer's #GTlsCertificate the problems with @peer_cert Gets @conn's certificate, as set by g_tls_connection_set_certificate(). @conn's certificate, or %NULL a #GTlsConnection Query the TLS backend for TLS channel binding data of @type for @conn. This call retrieves TLS channel binding data as specified in RFC [5056](https://tools.ietf.org/html/rfc5056), RFC [5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The binding data is returned in @data. The @data is resized by the callee using #GByteArray buffer management and will be freed when the @data is destroyed by g_byte_array_unref(). If @data is %NULL, it will only check whether TLS backend is able to fetch the data (e.g. whether @type is supported by the TLS backend). It does not guarantee that the data will be available though. That could happen if TLS connection does not support @type or the binding data is not available yet due to additional negotiation or input required. %TRUE on success, %FALSE otherwise a #GTlsConnection #GTlsChannelBindingType type of data to fetch #GByteArray is filled with the binding data, or %NULL Returns the name of the current TLS ciphersuite, or %NULL if the connection has not handshaked or has been closed. Beware that the TLS backend may use any of multiple different naming conventions, because OpenSSL and GnuTLS have their own ciphersuite naming conventions that are different from each other and different from the standard, IANA- registered ciphersuite names. The ciphersuite name is intended to be displayed to the user for informative purposes only, and parsing it is not recommended. The name of the current TLS ciphersuite, or %NULL a #GTlsConnection Gets the certificate database that @conn uses to verify peer certificates. See g_tls_connection_set_database(). the certificate database that @conn uses or %NULL a #GTlsConnection Get the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. If %NULL is returned, then no user interaction will occur for this connection. The interaction object. a connection Gets the name of the application-layer protocol negotiated during the handshake. If the peer did not use the ALPN extension, or did not advertise a protocol that matched one of @conn's protocols, or the TLS backend does not support ALPN, then this will be %NULL. See g_tls_connection_set_advertised_protocols(). the negotiated protocol, or %NULL a #GTlsConnection Gets @conn's peer's certificate after the handshake has completed or failed. (It is not set during the emission of #GTlsConnection::accept-certificate.) @conn's peer's certificate, or %NULL a #GTlsConnection Gets the errors associated with validating @conn's peer's certificate, after the handshake has completed or failed. (It is not set during the emission of #GTlsConnection::accept-certificate.) See #GTlsConnection:peer-certificate-errors for more information. @conn's peer's certificate errors a #GTlsConnection Returns the current TLS protocol version, which may be %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or has been closed, or if the TLS backend has implemented a protocol version that is not a recognized #GTlsProtocolVersion. The current TLS protocol version a #GTlsConnection Gets @conn rehandshaking mode. See g_tls_connection_set_rehandshake_mode() for details. Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. %G_TLS_REHANDSHAKE_SAFELY a #GTlsConnection Tests whether or not @conn expects a proper TLS close notification when the connection is closed. See g_tls_connection_set_require_close_notify() for details. %TRUE if @conn requires a proper TLS close notification. a #GTlsConnection Gets whether @conn uses the system certificate database to verify peer certificates. See g_tls_connection_set_use_system_certdb(). Use g_tls_connection_get_database() instead whether @conn uses the system certificate database a #GTlsConnection Attempts a TLS handshake on @conn. On the client side, it is never necessary to call this method; although the connection needs to perform a handshake after connecting (or after sending a "STARTTLS"-type command), #GTlsConnection will handle this for you automatically when you try to send or receive data on the connection. You can call g_tls_connection_handshake() manually if you want to know whether the initial handshake succeeded or failed (as opposed to just immediately trying to use @conn to read or write, in which case, if it fails, it may not be possible to tell if it failed before or after completing the handshake), but beware that servers may reject client authentication after the handshake has completed, so a successful handshake does not indicate the connection will be usable. Likewise, on the server side, although a handshake is necessary at the beginning of the communication, you do not need to call this function explicitly unless you want clearer error reporting. Previously, calling g_tls_connection_handshake() after the initial handshake would trigger a rehandshake; however, this usage was deprecated in GLib 2.60 because rehandshaking was removed from the TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after the initial handshake will no longer do anything. When using a #GTlsConnection created by #GSocketClient, the #GSocketClient performs the initial handshake, so calling this function manually is not recommended. #GTlsConnection::accept_certificate may be emitted during the handshake. success or failure a #GTlsConnection a #GCancellable, or %NULL Asynchronously performs a TLS handshake on @conn. See g_tls_connection_handshake() for more information. a #GTlsConnection the [I/O priority](iface.AsyncResult.html#io-priority) of the request a #GCancellable, or %NULL callback to call when the handshake is complete the data to pass to the callback function Finish an asynchronous TLS handshake operation. See g_tls_connection_handshake() for more information. %TRUE on success, %FALSE on failure, in which case @error will be set. a #GTlsConnection a #GAsyncResult. Sets the list of application-layer protocols to advertise that the caller is willing to speak on this connection. The Application-Layer Protocol Negotiation (ALPN) extension will be used to negotiate a compatible protocol with the peer; use g_tls_connection_get_negotiated_protocol() to find the negotiated protocol after the handshake. Specifying %NULL for the the value of @protocols will disable ALPN negotiation. See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) for a list of registered protocol IDs. a #GTlsConnection a %NULL-terminated array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL This sets the certificate that @conn will present to its peer during the TLS handshake. For a #GTlsServerConnection, it is mandatory to set this, and that will normally be done at construct time. For a #GTlsClientConnection, this is optional. If a handshake fails with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server requires a certificate, and if you try connecting again, you should call this method first. You can call g_tls_client_connection_get_accepted_cas() on the failed connection to get a list of Certificate Authorities that the server will accept certificates from. (It is also possible that a server will allow the connection with or without a certificate; in that case, if you don't provide a certificate, you can tell that the server requested one by the fact that g_tls_client_connection_get_accepted_cas() will return non-%NULL.) a #GTlsConnection the certificate to use for @conn Sets the certificate database that is used to verify peer certificates. This is set to the default database by default. See g_tls_backend_get_default_database(). If set to %NULL, then peer certificate validation will always set the %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning #GTlsConnection::accept-certificate will always be emitted on client-side connections, unless that bit is not set in #GTlsClientConnection:validation-flags). There are nonintuitive security implications when using a non-default database. See #GTlsConnection:database for details. a #GTlsConnection a #GTlsDatabase Set the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. The @interaction argument will normally be a derived subclass of #GTlsInteraction. %NULL can also be provided if no user interaction should occur for this connection. a connection an interaction object, or %NULL Since GLib 2.64, changing the rehandshake mode is no longer supported and will have no effect. With TLS 1.3, rehandshaking has been removed from the TLS protocol, replaced by separate post-handshake authentication and rekey operations. Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. a #GTlsConnection the rehandshaking mode Sets whether or not @conn expects a proper TLS close notification before the connection is closed. If this is %TRUE (the default), then @conn will expect to receive a TLS close notification from its peer before the connection is closed, and will return a %G_TLS_ERROR_EOF error if the connection is closed without proper notification (since this may indicate a network error, or man-in-the-middle attack). In some protocols, the application will know whether or not the connection was closed cleanly based on application-level data (because the application-level data includes a length field, or is somehow self-delimiting); in this case, the close notify is redundant and sometimes omitted. (TLS 1.1 explicitly allows this; in TLS 1.0 it is technically an error, but often done anyway.) You can use g_tls_connection_set_require_close_notify() to tell @conn to allow an "unannounced" connection close, in which case the close will show up as a 0-length read, as in a non-TLS #GSocketConnection, and it is up to the application to check that the data has been fully received. Note that this only affects the behavior when the peer closes the connection; when the application calls g_io_stream_close() itself on @conn, this will send a close notification regardless of the setting of this property. If you explicitly want to do an unclean close, you can close @conn's #GTlsConnection:base-io-stream rather than closing @conn itself, but note that this may only be done when no other operations are pending on @conn or the base I/O stream. a #GTlsConnection whether or not to require close notification Sets whether @conn uses the system certificate database to verify peer certificates. This is %TRUE by default. If set to %FALSE, then peer certificate validation will always set the %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning #GTlsConnection::accept-certificate will always be emitted on client-side connections, unless that bit is not set in #GTlsClientConnection:validation-flags). Use g_tls_connection_set_database() instead a #GTlsConnection whether to use the system certificate database The list of application-layer protocols that the connection advertises that it is willing to speak. See g_tls_connection_set_advertised_protocols(). The #GIOStream that the connection wraps. The connection holds a reference to this stream, and may run operations on the stream from other threads throughout its lifetime. Consequently, after the #GIOStream has been constructed, application code may only run its own operations on this stream when no #GIOStream operations are running. The connection's certificate; see g_tls_connection_set_certificate(). The name of the TLS ciphersuite in use. See g_tls_connection_get_ciphersuite_name(). The certificate database to use when verifying this TLS connection. If no certificate database is set, then the default database will be used. See g_tls_backend_get_default_database(). When using a non-default database, #GTlsConnection must fall back to using the #GTlsDatabase to perform certificate verification using g_tls_database_verify_chain(), which means certificate verification will not be able to make use of TLS session context. This may be less secure. For example, if you create your own #GTlsDatabase that just wraps the default #GTlsDatabase, you might expect that you have not changed anything, but this is not true because you may have altered the behavior of #GTlsConnection by causing it to use g_tls_database_verify_chain(). See the documentation of g_tls_database_verify_chain() for more details on specific security checks that may not be performed. Accordingly, setting a non-default database is discouraged except for specialty applications with unusual security requirements. A #GTlsInteraction object to be used when the connection or certificate database need to interact with the user. This will be used to prompt the user for passwords where necessary. The application-layer protocol negotiated during the TLS handshake. See g_tls_connection_get_negotiated_protocol(). The connection's peer's certificate, after the TLS handshake has completed or failed. Note in particular that this is not yet set during the emission of #GTlsConnection::accept-certificate. (You can watch for a #GObject::notify signal on this property to detect when a handshake has occurred.) The errors noticed while verifying #GTlsConnection:peer-certificate. Normally this should be 0, but it may not be if #GTlsClientConnection:validation-flags is not %G_TLS_CERTIFICATE_VALIDATE_ALL, or if #GTlsConnection::accept-certificate overrode the default behavior. GLib guarantees that if certificate verification fails, at least one error will be set, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. The TLS protocol version in use. See g_tls_connection_get_protocol_version(). The rehandshaking mode. See g_tls_connection_set_rehandshake_mode(). The rehandshake mode is ignored. Whether or not proper TLS close notification is required. See g_tls_connection_set_require_close_notify(). Whether or not the system certificate database will be used to verify peer certificates. See g_tls_connection_set_use_system_certdb(). Use GTlsConnection:database instead Emitted during the TLS handshake after the peer certificate has been received. You can examine @peer_cert's certification path by calling g_tls_certificate_get_issuer() on it. For a client-side connection, @peer_cert is the server's certificate, and the signal will only be emitted if the certificate was not acceptable according to @conn's #GTlsClientConnection:validation_flags. If you would like the certificate to be accepted despite @errors, return %TRUE from the signal handler. Otherwise, if no handler accepts the certificate, the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE. GLib guarantees that if certificate verification fails, this signal will be emitted with at least one error will be set in @errors, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to ignore %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. For a server-side connection, @peer_cert is the certificate presented by the client, if this was requested via the server's #GTlsServerConnection:authentication_mode. On the server side, the signal is always emitted when the client presents a certificate, and the certificate will only be accepted if a handler returns %TRUE. Note that if this signal is emitted as part of asynchronous I/O in the main thread, then you should not attempt to interact with the user before returning from the signal handler. If you want to let the user decide whether or not to accept the certificate, you would have to return %FALSE from the signal handler on the first attempt, and then after the connection attempt returns a %G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and if the user decides to accept the certificate, remember that fact, create a new connection, and return %TRUE from the signal handler the next time. If you are doing I/O in another thread, you do not need to worry about this, and can simply block in the signal handler until the UI thread returns an answer. %TRUE to accept @peer_cert (which will also immediately end the signal emission). %FALSE to allow the signal emission to continue, which will cause the handshake to fail if no one else overrides it. the peer's #GTlsCertificate the problems with @peer_cert. The class structure for the #GTlsConnection type. The parent class. Check whether to accept a certificate. Perform a handshake operation. success or failure a #GTlsConnection a #GCancellable, or %NULL Start an asynchronous handshake operation. a #GTlsConnection the [I/O priority](iface.AsyncResult.html#io-priority) of the request a #GCancellable, or %NULL callback to call when the handshake is complete the data to pass to the callback function Finish an asynchronous handshake operation. %TRUE on success, %FALSE on failure, in which case @error will be set. a #GTlsConnection a #GAsyncResult. Retrieve TLS channel binding data (Since: 2.66) Get ALPN-negotiated protocol (Since: 2.70) the negotiated protocol, or %NULL a #GTlsConnection `GTlsDatabase` is used to look up certificates and other information from a certificate or key store. It is an abstract base class which TLS library specific subtypes override. A `GTlsDatabase` may be accessed from multiple threads by the TLS backend. All implementations are required to be fully thread-safe. Most common client applications will not directly interact with `GTlsDatabase`. It is used internally by [class@Gio.TlsConnection]. Create a handle string for the certificate. The database will only be able to create a handle for certificates that originate from the database. In cases where the database cannot create a handle for a certificate, %NULL will be returned. This handle should be stable across various instances of the application, and between applications. If a certificate is modified in the database, then it is not guaranteed that this handle will continue to point to it. a newly allocated string containing the handle. a #GTlsDatabase certificate for which to create a handle. Look up a certificate by its handle. The handle should have been created by calling g_tls_database_create_certificate_handle() on a #GTlsDatabase object of the same TLS backend. The handle is designed to remain valid across instantiations of the database. If the handle is no longer valid, or does not point to a certificate in this database, then %NULL will be returned. This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform the lookup operation asynchronously. a newly allocated #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase a certificate handle used to interact with the user if necessary Flags which affect the lookup. a #GCancellable, or %NULL Asynchronously look up a certificate by its handle in the database. See g_tls_database_lookup_certificate_for_handle() for more information. a #GTlsDatabase a certificate handle used to interact with the user if necessary Flags which affect the lookup. a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Finish an asynchronous lookup of a certificate by its handle. See g_tls_database_lookup_certificate_for_handle() for more information. If the handle is no longer valid, or does not point to a certificate in this database, then %NULL will be returned. a newly allocated #GTlsCertificate object. Use g_object_unref() to release the certificate. a #GTlsDatabase a #GAsyncResult. Look up the issuer of @certificate in the database. The #GTlsCertificate:issuer property of @certificate is not modified, and the two certificates are not hooked into a chain. This function can block. Use g_tls_database_lookup_certificate_issuer_async() to perform the lookup operation asynchronously. Beware this function cannot be used to build certification paths. The issuer certificate returned by this function may not be the same as the certificate that would actually be used to construct a valid certification path during certificate verification. [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains why an issuer certificate cannot be naively assumed to be part of the the certification path (though GLib's TLS backends may not follow the path building strategies outlined in this RFC). Due to the complexity of certification path building, GLib does not provide any way to know which certification path will actually be used when verifying a TLS certificate. Accordingly, this function cannot be used to make security-related decisions. Only GLib itself should make security decisions about TLS certificates. a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase a #GTlsCertificate used to interact with the user if necessary flags which affect the lookup operation a #GCancellable, or %NULL Asynchronously look up the issuer of @certificate in the database. See g_tls_database_lookup_certificate_issuer() for more information. a #GTlsDatabase a #GTlsCertificate used to interact with the user if necessary flags which affect the lookup operation a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Finish an asynchronous lookup issuer operation. See g_tls_database_lookup_certificate_issuer() for more information. a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase a #GAsyncResult. Look up certificates issued by this issuer in the database. This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform the lookup operation asynchronously. a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. used to interact with the user if necessary Flags which affect the lookup operation. a #GCancellable, or %NULL Asynchronously look up certificates issued by this issuer in the database. See g_tls_database_lookup_certificates_issued_by() for more information. The database may choose to hold a reference to the issuer byte array for the duration of this asynchronous operation. The byte array should not be modified during this time. a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. used to interact with the user if necessary Flags which affect the lookup operation. a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Finish an asynchronous lookup of certificates. See g_tls_database_lookup_certificates_issued_by() for more information. a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. a #GTlsDatabase a #GAsyncResult. Determines the validity of a certificate chain, outside the context of a TLS session. @chain is a chain of #GTlsCertificate objects each pointing to the next certificate in the chain by its #GTlsCertificate:issuer property. @purpose describes the purpose (or usage) for which the certificate is being used. Typically @purpose will be set to %G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER which means that the certificate is being used to authenticate a server (and we are acting as the client). The @identity is used to ensure the server certificate is valid for the expected peer identity. If the identity does not match the certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return value. If @identity is %NULL, that bit will never be set in the return value. The peer identity may also be used to check for pinned certificates (trust exceptions) in the database. These may override the normal verification process on a host-by-host basis. Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be used. If @chain is found to be valid, then the return value will be 0. If @chain is found to be invalid, then the return value will indicate at least one problem found. If the function is unable to determine whether @chain is valid (for example, because @cancellable is triggered before it completes) then the return value will be %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set accordingly. @error is not set when @chain is successfully analyzed but found to be invalid. GLib guarantees that if certificate verification fails, at least one error will be set in the return value, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Prior to GLib 2.48, GLib's default TLS backend modified @chain to represent the certification path built by #GTlsDatabase during certificate verification by adjusting the #GTlsCertificate:issuer property of each certificate in @chain. Since GLib 2.48, this no longer occurs, so you cannot rely on #GTlsCertificate:issuer to represent the actual certification path used during certificate verification. Because TLS session context is not used, #GTlsDatabase may not perform as many checks on the certificates as #GTlsConnection would. For example, certificate constraints may not be honored, and revocation checks may not be performed. The best way to verify TLS certificates used by a TLS connection is to let #GTlsConnection handle the verification. The TLS backend may attempt to look up and add missing certificates to the chain. This may involve HTTP requests to download missing certificates. This function can block. Use g_tls_database_verify_chain_async() to perform the verification operation asynchronously. the appropriate #GTlsCertificateFlags which represents the result of verification. a #GTlsDatabase a #GTlsCertificate chain the purpose that this certificate chain will be used for. the expected peer identity used to interact with the user if necessary additional verify flags a #GCancellable, or %NULL Asynchronously determines the validity of a certificate chain after looking up and adding any missing certificates to the chain. See g_tls_database_verify_chain() for more information. a #GTlsDatabase a #GTlsCertificate chain the purpose that this certificate chain will be used for. the expected peer identity used to interact with the user if necessary additional verify flags a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Finish an asynchronous verify chain operation. See g_tls_database_verify_chain() for more information. If @chain is found to be valid, then the return value will be 0. If @chain is found to be invalid, then the return value will indicate the problems found. If the function is unable to determine whether @chain is valid or not (eg, because @cancellable is triggered before it completes) then the return value will be %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set accordingly. @error is not set when @chain is successfully analyzed but found to be invalid. the appropriate #GTlsCertificateFlags which represents the result of verification. a #GTlsDatabase a #GAsyncResult. Create a handle string for the certificate. The database will only be able to create a handle for certificates that originate from the database. In cases where the database cannot create a handle for a certificate, %NULL will be returned. This handle should be stable across various instances of the application, and between applications. If a certificate is modified in the database, then it is not guaranteed that this handle will continue to point to it. a newly allocated string containing the handle. a #GTlsDatabase certificate for which to create a handle. Look up a certificate by its handle. The handle should have been created by calling g_tls_database_create_certificate_handle() on a #GTlsDatabase object of the same TLS backend. The handle is designed to remain valid across instantiations of the database. If the handle is no longer valid, or does not point to a certificate in this database, then %NULL will be returned. This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform the lookup operation asynchronously. a newly allocated #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase a certificate handle used to interact with the user if necessary Flags which affect the lookup. a #GCancellable, or %NULL Asynchronously look up a certificate by its handle in the database. See g_tls_database_lookup_certificate_for_handle() for more information. a #GTlsDatabase a certificate handle used to interact with the user if necessary Flags which affect the lookup. a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Finish an asynchronous lookup of a certificate by its handle. See g_tls_database_lookup_certificate_for_handle() for more information. If the handle is no longer valid, or does not point to a certificate in this database, then %NULL will be returned. a newly allocated #GTlsCertificate object. Use g_object_unref() to release the certificate. a #GTlsDatabase a #GAsyncResult. Look up the issuer of @certificate in the database. The #GTlsCertificate:issuer property of @certificate is not modified, and the two certificates are not hooked into a chain. This function can block. Use g_tls_database_lookup_certificate_issuer_async() to perform the lookup operation asynchronously. Beware this function cannot be used to build certification paths. The issuer certificate returned by this function may not be the same as the certificate that would actually be used to construct a valid certification path during certificate verification. [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains why an issuer certificate cannot be naively assumed to be part of the the certification path (though GLib's TLS backends may not follow the path building strategies outlined in this RFC). Due to the complexity of certification path building, GLib does not provide any way to know which certification path will actually be used when verifying a TLS certificate. Accordingly, this function cannot be used to make security-related decisions. Only GLib itself should make security decisions about TLS certificates. a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase a #GTlsCertificate used to interact with the user if necessary flags which affect the lookup operation a #GCancellable, or %NULL Asynchronously look up the issuer of @certificate in the database. See g_tls_database_lookup_certificate_issuer() for more information. a #GTlsDatabase a #GTlsCertificate used to interact with the user if necessary flags which affect the lookup operation a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Finish an asynchronous lookup issuer operation. See g_tls_database_lookup_certificate_issuer() for more information. a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase a #GAsyncResult. Look up certificates issued by this issuer in the database. This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform the lookup operation asynchronously. a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. used to interact with the user if necessary Flags which affect the lookup operation. a #GCancellable, or %NULL Asynchronously look up certificates issued by this issuer in the database. See g_tls_database_lookup_certificates_issued_by() for more information. The database may choose to hold a reference to the issuer byte array for the duration of this asynchronous operation. The byte array should not be modified during this time. a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. used to interact with the user if necessary Flags which affect the lookup operation. a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Finish an asynchronous lookup of certificates. See g_tls_database_lookup_certificates_issued_by() for more information. a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. a #GTlsDatabase a #GAsyncResult. Determines the validity of a certificate chain, outside the context of a TLS session. @chain is a chain of #GTlsCertificate objects each pointing to the next certificate in the chain by its #GTlsCertificate:issuer property. @purpose describes the purpose (or usage) for which the certificate is being used. Typically @purpose will be set to %G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER which means that the certificate is being used to authenticate a server (and we are acting as the client). The @identity is used to ensure the server certificate is valid for the expected peer identity. If the identity does not match the certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return value. If @identity is %NULL, that bit will never be set in the return value. The peer identity may also be used to check for pinned certificates (trust exceptions) in the database. These may override the normal verification process on a host-by-host basis. Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be used. If @chain is found to be valid, then the return value will be 0. If @chain is found to be invalid, then the return value will indicate at least one problem found. If the function is unable to determine whether @chain is valid (for example, because @cancellable is triggered before it completes) then the return value will be %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set accordingly. @error is not set when @chain is successfully analyzed but found to be invalid. GLib guarantees that if certificate verification fails, at least one error will be set in the return value, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Prior to GLib 2.48, GLib's default TLS backend modified @chain to represent the certification path built by #GTlsDatabase during certificate verification by adjusting the #GTlsCertificate:issuer property of each certificate in @chain. Since GLib 2.48, this no longer occurs, so you cannot rely on #GTlsCertificate:issuer to represent the actual certification path used during certificate verification. Because TLS session context is not used, #GTlsDatabase may not perform as many checks on the certificates as #GTlsConnection would. For example, certificate constraints may not be honored, and revocation checks may not be performed. The best way to verify TLS certificates used by a TLS connection is to let #GTlsConnection handle the verification. The TLS backend may attempt to look up and add missing certificates to the chain. This may involve HTTP requests to download missing certificates. This function can block. Use g_tls_database_verify_chain_async() to perform the verification operation asynchronously. the appropriate #GTlsCertificateFlags which represents the result of verification. a #GTlsDatabase a #GTlsCertificate chain the purpose that this certificate chain will be used for. the expected peer identity used to interact with the user if necessary additional verify flags a #GCancellable, or %NULL Asynchronously determines the validity of a certificate chain after looking up and adding any missing certificates to the chain. See g_tls_database_verify_chain() for more information. a #GTlsDatabase a #GTlsCertificate chain the purpose that this certificate chain will be used for. the expected peer identity used to interact with the user if necessary additional verify flags a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Finish an asynchronous verify chain operation. See g_tls_database_verify_chain() for more information. If @chain is found to be valid, then the return value will be 0. If @chain is found to be invalid, then the return value will indicate the problems found. If the function is unable to determine whether @chain is valid or not (eg, because @cancellable is triggered before it completes) then the return value will be %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set accordingly. @error is not set when @chain is successfully analyzed but found to be invalid. the appropriate #GTlsCertificateFlags which represents the result of verification. a #GTlsDatabase a #GAsyncResult. The class for #GTlsDatabase. Derived classes should implement the various virtual methods. _async and _finish methods have a default implementation that runs the corresponding sync method in a thread. Virtual method implementing g_tls_database_verify_chain(). the appropriate #GTlsCertificateFlags which represents the result of verification. a #GTlsDatabase a #GTlsCertificate chain the purpose that this certificate chain will be used for. the expected peer identity used to interact with the user if necessary additional verify flags a #GCancellable, or %NULL Virtual method implementing g_tls_database_verify_chain_async(). a #GTlsDatabase a #GTlsCertificate chain the purpose that this certificate chain will be used for. the expected peer identity used to interact with the user if necessary additional verify flags a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Virtual method implementing g_tls_database_verify_chain_finish(). the appropriate #GTlsCertificateFlags which represents the result of verification. a #GTlsDatabase a #GAsyncResult. Virtual method implementing g_tls_database_create_certificate_handle(). a newly allocated string containing the handle. a #GTlsDatabase certificate for which to create a handle. Virtual method implementing g_tls_database_lookup_certificate_for_handle(). a newly allocated #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase a certificate handle used to interact with the user if necessary Flags which affect the lookup. a #GCancellable, or %NULL Virtual method implementing g_tls_database_lookup_certificate_for_handle_async(). a #GTlsDatabase a certificate handle used to interact with the user if necessary Flags which affect the lookup. a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Virtual method implementing g_tls_database_lookup_certificate_for_handle_finish(). a newly allocated #GTlsCertificate object. Use g_object_unref() to release the certificate. a #GTlsDatabase a #GAsyncResult. Virtual method implementing g_tls_database_lookup_certificate_issuer(). a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase a #GTlsCertificate used to interact with the user if necessary flags which affect the lookup operation a #GCancellable, or %NULL Virtual method implementing g_tls_database_lookup_certificate_issuer_async(). a #GTlsDatabase a #GTlsCertificate used to interact with the user if necessary flags which affect the lookup operation a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Virtual method implementing g_tls_database_lookup_certificate_issuer_finish(). a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase a #GAsyncResult. Virtual method implementing g_tls_database_lookup_certificates_issued_by(). a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. used to interact with the user if necessary Flags which affect the lookup operation. a #GCancellable, or %NULL Virtual method implementing g_tls_database_lookup_certificates_issued_by_async(). a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. used to interact with the user if necessary Flags which affect the lookup operation. a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Virtual method implementing g_tls_database_lookup_certificates_issued_by_finish(). a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. a #GTlsDatabase a #GAsyncResult. Flags for g_tls_database_lookup_certificate_for_handle(), g_tls_database_lookup_certificate_issuer(), and g_tls_database_lookup_certificates_issued_by(). No lookup flags Restrict lookup to certificates that have a private key. Flags for g_tls_database_verify_chain(). No verification flags An error code used with %G_TLS_ERROR in a #GError returned from a TLS-related routine. No TLS provider is available Miscellaneous TLS error The certificate presented could not be parsed or failed validation. The TLS handshake failed because the peer does not seem to be a TLS server. The TLS handshake failed because the peer's certificate was not acceptable. The TLS handshake failed because the server requested a client-side certificate, but none was provided. See g_tls_connection_set_certificate(). The TLS connection was closed without proper notice, which may indicate an attack. See g_tls_connection_set_require_close_notify(). The TLS handshake failed because the client sent the fallback SCSV, indicating a protocol downgrade attack. Since: 2.60 The certificate failed to load because a password was incorrect. Since: 2.72 Gets the TLS error quark. a #GQuark. `GTlsFileDatabase` is implemented by [class@Gio.TlsDatabase] objects which load their certificate information from a file. It is an interface which TLS library specific subtypes implement. Creates a new #GTlsFileDatabase which uses anchor certificate authorities in @anchors to verify certificate chains. The certificates in @anchors must be PEM encoded. the new #GTlsFileDatabase, or %NULL on error filename of anchor certificate authorities. The path to a file containing PEM encoded certificate authority root anchors. The certificates in this file will be treated as root authorities for the purpose of verifying other certificates via the g_tls_database_verify_chain() operation. Provides an interface for #GTlsFileDatabase implementations. The parent interface. `GTlsInteraction` provides a mechanism for the TLS connection and database code to interact with the user. It can be used to ask the user for passwords. To use a `GTlsInteraction` with a TLS connection use [method@Gio.TlsConnection.set_interaction]. Callers should instantiate a derived class that implements the various interaction methods to show the required dialogs. Callers should use the 'invoke' functions like [method@Gio.TlsInteraction.invoke_ask_password] to run interaction methods. These functions make sure that the interaction is invoked in the main loop and not in the current thread, if the current thread is not running the main loop. Derived classes can choose to implement whichever interactions methods they’d like to support by overriding those virtual methods in their class initialization function. Any interactions not implemented will return `G_TLS_INTERACTION_UNHANDLED`. If a derived class implements an async method, it must also implement the corresponding finish method. Run synchronous interaction to ask the user for a password. In general, g_tls_interaction_invoke_ask_password() should be used instead of this function. Derived subclasses usually implement a password prompt, although they may also choose to provide a password from elsewhere. The @password value will be filled in and then @callback will be called. Alternatively the user may abort this password request, which will usually abort the TLS connection. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. The status of the ask password interaction. a #GTlsInteraction object a #GTlsPassword object an optional #GCancellable cancellation object Run asynchronous interaction to ask the user for a password. In general, g_tls_interaction_invoke_ask_password() should be used instead of this function. Derived subclasses usually implement a password prompt, although they may also choose to provide a password from elsewhere. The @password value will be filled in and then @callback will be called. Alternatively the user may abort this password request, which will usually abort the TLS connection. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. Certain implementations may not support immediate cancellation. a #GTlsInteraction object a #GTlsPassword object an optional #GCancellable cancellation object will be called when the interaction completes data to pass to the @callback Complete an ask password user interaction request. This should be once the g_tls_interaction_ask_password_async() completion callback is called. If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed to g_tls_interaction_ask_password() will have its password filled in. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. The status of the ask password interaction. a #GTlsInteraction object the result passed to the callback Run synchronous interaction to ask the user to choose a certificate to use with the connection. In general, g_tls_interaction_invoke_request_certificate() should be used instead of this function. Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. Alternatively the user may abort this certificate request, which will usually abort the TLS connection. If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection passed to g_tls_interaction_request_certificate() will have had its #GTlsConnection:certificate filled in. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. The status of the request certificate interaction. a #GTlsInteraction object a #GTlsConnection object flags providing more information about the request an optional #GCancellable cancellation object Run asynchronous interaction to ask the user for a certificate to use with the connection. In general, g_tls_interaction_invoke_request_certificate() should be used instead of this function. Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. @callback will be called when the operation completes. Alternatively the user may abort this certificate request, which will usually abort the TLS connection. a #GTlsInteraction object a #GTlsConnection object flags providing more information about the request an optional #GCancellable cancellation object will be called when the interaction completes data to pass to the @callback Complete a request certificate user interaction request. This should be once the g_tls_interaction_request_certificate_async() completion callback is called. If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection passed to g_tls_interaction_request_certificate_async() will have had its #GTlsConnection:certificate filled in. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. The status of the request certificate interaction. a #GTlsInteraction object the result passed to the callback Run synchronous interaction to ask the user for a password. In general, g_tls_interaction_invoke_ask_password() should be used instead of this function. Derived subclasses usually implement a password prompt, although they may also choose to provide a password from elsewhere. The @password value will be filled in and then @callback will be called. Alternatively the user may abort this password request, which will usually abort the TLS connection. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. The status of the ask password interaction. a #GTlsInteraction object a #GTlsPassword object an optional #GCancellable cancellation object Run asynchronous interaction to ask the user for a password. In general, g_tls_interaction_invoke_ask_password() should be used instead of this function. Derived subclasses usually implement a password prompt, although they may also choose to provide a password from elsewhere. The @password value will be filled in and then @callback will be called. Alternatively the user may abort this password request, which will usually abort the TLS connection. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. Certain implementations may not support immediate cancellation. a #GTlsInteraction object a #GTlsPassword object an optional #GCancellable cancellation object will be called when the interaction completes data to pass to the @callback Complete an ask password user interaction request. This should be once the g_tls_interaction_ask_password_async() completion callback is called. If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed to g_tls_interaction_ask_password() will have its password filled in. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. The status of the ask password interaction. a #GTlsInteraction object the result passed to the callback Invoke the interaction to ask the user for a password. It invokes this interaction in the main loop, specifically the #GMainContext returned by g_main_context_get_thread_default() when the interaction is created. This is called by called by #GTlsConnection or #GTlsDatabase to ask the user for a password. Derived subclasses usually implement a password prompt, although they may also choose to provide a password from elsewhere. The @password value will be filled in and then @callback will be called. Alternatively the user may abort this password request, which will usually abort the TLS connection. The implementation can either be a synchronous (eg: modal dialog) or an asynchronous one (eg: modeless dialog). This function will take care of calling which ever one correctly. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. The status of the ask password interaction. a #GTlsInteraction object a #GTlsPassword object an optional #GCancellable cancellation object Invoke the interaction to ask the user to choose a certificate to use with the connection. It invokes this interaction in the main loop, specifically the #GMainContext returned by g_main_context_get_thread_default() when the interaction is created. This is called by called by #GTlsConnection when the peer requests a certificate during the handshake. Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. Alternatively the user may abort this certificate request, which may or may not abort the TLS connection. The implementation can either be a synchronous (eg: modal dialog) or an asynchronous one (eg: modeless dialog). This function will take care of calling which ever one correctly. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. The status of the certificate request interaction. a #GTlsInteraction object a #GTlsConnection object flags providing more information about the request an optional #GCancellable cancellation object Run synchronous interaction to ask the user to choose a certificate to use with the connection. In general, g_tls_interaction_invoke_request_certificate() should be used instead of this function. Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. Alternatively the user may abort this certificate request, which will usually abort the TLS connection. If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection passed to g_tls_interaction_request_certificate() will have had its #GTlsConnection:certificate filled in. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. The status of the request certificate interaction. a #GTlsInteraction object a #GTlsConnection object flags providing more information about the request an optional #GCancellable cancellation object Run asynchronous interaction to ask the user for a certificate to use with the connection. In general, g_tls_interaction_invoke_request_certificate() should be used instead of this function. Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. @callback will be called when the operation completes. Alternatively the user may abort this certificate request, which will usually abort the TLS connection. a #GTlsInteraction object a #GTlsConnection object flags providing more information about the request an optional #GCancellable cancellation object will be called when the interaction completes data to pass to the @callback Complete a request certificate user interaction request. This should be once the g_tls_interaction_request_certificate_async() completion callback is called. If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection passed to g_tls_interaction_request_certificate_async() will have had its #GTlsConnection:certificate filled in. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. The status of the request certificate interaction. a #GTlsInteraction object the result passed to the callback The class for #GTlsInteraction. Derived classes implement the various virtual interaction methods to handle TLS interactions. Derived classes can choose to implement whichever interactions methods they'd like to support by overriding those virtual methods in their class initialization function. If a derived class implements an async method, it must also implement the corresponding finish method. The synchronous interaction methods should implement to display modal dialogs, and the asynchronous methods to display modeless dialogs. If the user cancels an interaction, then the result should be %G_TLS_INTERACTION_FAILED and the error should be set with a domain of %G_IO_ERROR and code of %G_IO_ERROR_CANCELLED. ask for a password synchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the password argument should have been filled in by using g_tls_password_set_value() or a similar function. The status of the ask password interaction. a #GTlsInteraction object a #GTlsPassword object an optional #GCancellable cancellation object ask for a password asynchronously. a #GTlsInteraction object a #GTlsPassword object an optional #GCancellable cancellation object will be called when the interaction completes data to pass to the @callback complete operation to ask for a password asynchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the password argument of the async method should have been filled in by using g_tls_password_set_value() or a similar function. The status of the ask password interaction. a #GTlsInteraction object the result passed to the callback ask for a certificate synchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the connection argument should have been filled in by using g_tls_connection_set_certificate(). The status of the request certificate interaction. a #GTlsInteraction object a #GTlsConnection object flags providing more information about the request an optional #GCancellable cancellation object ask for a certificate asynchronously. a #GTlsInteraction object a #GTlsConnection object flags providing more information about the request an optional #GCancellable cancellation object will be called when the interaction completes data to pass to the @callback complete operation to ask for a certificate asynchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the connection argument of the async method should have been filled in by using g_tls_connection_set_certificate(). The status of the request certificate interaction. a #GTlsInteraction object the result passed to the callback #GTlsInteractionResult is returned by various functions in #GTlsInteraction when finishing an interaction request. The interaction was unhandled (i.e. not implemented). The interaction completed, and resulting data is available. The interaction has failed, or was cancelled. and the operation should be aborted. An abstract interface representing a password used in TLS. Often used in user interaction such as unlocking a key storage token. Create a new #GTlsPassword object. The newly allocated password object the password flags description of what the password is for virtual method for g_tls_password_get_warning() if no value has been set using g_tls_password_set_warning() Get the password value. If @length is not %NULL then it will be filled in with the length of the password value. (Note that the password value is not nul-terminated, so you can only pass %NULL for @length in contexts where you know the password will have a certain fixed length.) The password value (owned by the password object). a #GTlsPassword object location to place the length of the password. Provide the value for this password. The @value will be owned by the password object, and later freed using the @destroy function callback. Specify the @length, for a non-nul-terminated password. Pass -1 as @length if using a nul-terminated password, and @length will be calculated automatically. (Note that the terminating nul is not considered part of the password in this case.) a #GTlsPassword object the value for the password the length of the password, or -1 a function to use to free the password. Get a description string about what the password will be used for. The description of the password. a #GTlsPassword object Get flags about the password. The flags about the password. a #GTlsPassword object Get the password value. If @length is not %NULL then it will be filled in with the length of the password value. (Note that the password value is not nul-terminated, so you can only pass %NULL for @length in contexts where you know the password will have a certain fixed length.) The password value (owned by the password object). a #GTlsPassword object location to place the length of the password. Get a user readable translated warning. Usually this warning is a representation of the password flags returned from g_tls_password_get_flags(). The warning. a #GTlsPassword object Set a description string about what the password will be used for. a #GTlsPassword object The description of the password Set flags about the password. a #GTlsPassword object The flags about the password Set the value for this password. The @value will be copied by the password object. Specify the @length, for a non-nul-terminated password. Pass -1 as @length if using a nul-terminated password, and @length will be calculated automatically. (Note that the terminating nul is not considered part of the password in this case.) a #GTlsPassword object the new password value the length of the password, or -1 Provide the value for this password. The @value will be owned by the password object, and later freed using the @destroy function callback. Specify the @length, for a non-nul-terminated password. Pass -1 as @length if using a nul-terminated password, and @length will be calculated automatically. (Note that the terminating nul is not considered part of the password in this case.) a #GTlsPassword object the value for the password the length of the password, or -1 a function to use to free the password. Set a user readable translated warning. Usually this warning is a representation of the password flags returned from g_tls_password_get_flags(). a #GTlsPassword object The user readable warning Description of what the password is for. Flags about the password. Warning about the password. Class structure for #GTlsPassword. virtual method for g_tls_password_get_value() The password value (owned by the password object). a #GTlsPassword object location to place the length of the password. virtual method for g_tls_password_set_value() a #GTlsPassword object the value for the password the length of the password, or -1 a function to use to free the password. virtual method for g_tls_password_get_warning() if no value has been set using g_tls_password_set_warning() Various flags for the password. No flags The password was wrong, and the user should retry. Hint to the user that the password has been wrong many times, and the user may not have many chances left. Hint to the user that this is the last try to get this password right. For PKCS #11, the user PIN is required. Since: 2.70. For PKCS #11, the security officer PIN is required. Since: 2.70. For PKCS #11, the context-specific PIN is required. Since: 2.70. The TLS or DTLS protocol version used by a #GTlsConnection or #GDtlsConnection. The integer values of these versions are sequential to ensure newer known protocol versions compare greater than older known versions. Any known DTLS protocol version will compare greater than any SSL or TLS protocol version. The protocol version may be %G_TLS_PROTOCOL_VERSION_UNKNOWN if the TLS backend supports a newer protocol version that GLib does not yet know about. This means that it's possible for an unknown DTLS protocol version to compare less than the TLS protocol versions. No protocol version or unknown protocol version SSL 3.0, which is insecure and should not be used TLS 1.0, which is insecure and should not be used TLS 1.1, which is insecure and should not be used TLS 1.2, defined by [RFC 5246](https://datatracker.ietf.org/doc/html/rfc5246) TLS 1.3, defined by [RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446) DTLS 1.0, which is insecure and should not be used DTLS 1.2, defined by [RFC 6347](https://datatracker.ietf.org/doc/html/rfc6347) When to allow rehandshaking. See g_tls_connection_set_rehandshake_mode(). Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. Never allow rehandshaking Allow safe rehandshaking only Allow unsafe rehandshaking `GTlsServerConnection` is the server-side subclass of [class@Gio.TlsConnection], representing a server-side TLS connection. Creates a new #GTlsServerConnection wrapping @base_io_stream (which must have pollable input and output streams). See the documentation for #GTlsConnection:base-io-stream for restrictions on when application code can run operations on the @base_io_stream after this function has returned. the new #GTlsServerConnection, or %NULL on error the #GIOStream to wrap the default server certificate, or %NULL The #GTlsAuthenticationMode for the server. This can be changed before calling g_tls_connection_handshake() if you want to rehandshake with a different mode from the initial handshake. vtable for a #GTlsServerConnection implementation. The parent interface. This is the subclass of [class@Gio.SocketConnection] that is created for UNIX domain sockets. It contains functions to do some of the UNIX socket specific functionality like passing file descriptors. Since GLib 2.72, `GUnixConnection` is available on all platforms. It requires underlying system support (such as Windows 10 with `AF_UNIX`) at run time. Before GLib 2.72, `<gio/gunixconnection.h>` belonged to the UNIX-specific GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when using it. This is no longer necessary since GLib 2.72. Receives credentials from the sending end of the connection. The sending end has to call g_unix_connection_send_credentials() (or similar) for this to work. As well as reading the credentials this also reads (and discards) a single byte from the stream, as this is required for credentials passing to work on some implementations. This method can be expected to be available on the following platforms: - Linux since GLib 2.26 - FreeBSD since GLib 2.26 - GNU/kFreeBSD since GLib 2.36 - Solaris, Illumos and OpenSolaris since GLib 2.40 - GNU/Hurd since GLib 2.40 Other ways to exchange credentials with a foreign peer includes the #GUnixCredentialsMessage type and g_socket_get_credentials() function. Received credentials on success (free with g_object_unref()), %NULL if @error is set. A #GUnixConnection. A #GCancellable or %NULL. Asynchronously receive credentials. For more details, see g_unix_connection_receive_credentials() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_unix_connection_receive_credentials_finish() to get the result of the operation. A #GUnixConnection. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous receive credentials operation started with g_unix_connection_receive_credentials_async(). a #GCredentials, or %NULL on error. Free the returned object with g_object_unref(). A #GUnixConnection. a #GAsyncResult. Receives a file descriptor from the sending end of the connection. The sending end has to call g_unix_connection_send_fd() for this to work. As well as reading the fd this also reads a single byte from the stream, as this is required for fd passing to work on some implementations. a file descriptor on success, -1 on error. a #GUnixConnection optional #GCancellable object, %NULL to ignore Passes the credentials of the current user the receiving side of the connection. The receiving end has to call g_unix_connection_receive_credentials() (or similar) to accept the credentials. As well as sending the credentials this also writes a single NUL byte to the stream, as this is required for credentials passing to work on some implementations. This method can be expected to be available on the following platforms: - Linux since GLib 2.26 - FreeBSD since GLib 2.26 - GNU/kFreeBSD since GLib 2.36 - Solaris, Illumos and OpenSolaris since GLib 2.40 - GNU/Hurd since GLib 2.40 Other ways to exchange credentials with a foreign peer includes the #GUnixCredentialsMessage type and g_socket_get_credentials() function. %TRUE on success, %FALSE if @error is set. A #GUnixConnection. A #GCancellable or %NULL. Asynchronously send credentials. For more details, see g_unix_connection_send_credentials() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_unix_connection_send_credentials_finish() to get the result of the operation. A #GUnixConnection. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous send credentials operation started with g_unix_connection_send_credentials_async(). %TRUE if the operation was successful, otherwise %FALSE. A #GUnixConnection. a #GAsyncResult. Passes a file descriptor to the receiving side of the connection. The receiving end has to call g_unix_connection_receive_fd() to accept the file descriptor. As well as sending the fd this also writes a single byte to the stream, as this is required for fd passing to work on some implementations. a %TRUE on success, %NULL on error. a #GUnixConnection a file descriptor optional #GCancellable object, %NULL to ignore. This [class@Gio.SocketControlMessage] contains a [class@Gio.Credentials] instance. It may be sent using [method@Gio.Socket.send_message] and received using [method@Gio.Socket.receive_message] over UNIX sockets (ie: sockets in the `G_SOCKET_FAMILY_UNIX` family). For an easier way to send and receive credentials over stream-oriented UNIX sockets, see [method@Gio.UnixConnection.send_credentials] and [method@Gio.UnixConnection.receive_credentials]. To receive credentials of a foreign process connected to a socket, use [method@Gio.Socket.get_credentials]. Since GLib 2.72, `GUnixCredentialMessage` is available on all platforms. It requires underlying system support (such as Windows 10 with `AF_UNIX`) at run time. Before GLib 2.72, `<gio/gunixcredentialsmessage.h>` belonged to the UNIX-specific GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when using it. This is no longer necessary since GLib 2.72. Creates a new #GUnixCredentialsMessage with credentials matching the current processes. a new #GUnixCredentialsMessage Creates a new #GUnixCredentialsMessage holding @credentials. a new #GUnixCredentialsMessage A #GCredentials object. Checks if passing #GCredentials on a #GSocket is supported on this platform. %TRUE if supported, %FALSE otherwise Gets the credentials stored in @message. A #GCredentials instance. Do not free, it is owned by @message. A #GUnixCredentialsMessage. The credentials stored in the message. Class structure for #GUnixCredentialsMessage. A `GUnixFDList` contains a list of file descriptors. It owns the file descriptors that it contains, closing them when finalized. It may be wrapped in a [`GUnixFDMessage`](../gio-unix/class.UnixFDMessage.html) and sent over a [class@Gio.Socket] in the `G_SOCKET_FAMILY_UNIX` family by using [method@Gio.Socket.send_message] and received using [method@Gio.Socket.receive_message]. Before 2.74, `<gio/gunixfdlist.h>` belonged to the UNIX-specific GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when using it. Since 2.74, the API is available for Windows. Creates a new #GUnixFDList containing no file descriptors. a new #GUnixFDList Creates a new #GUnixFDList containing the file descriptors given in @fds. The file descriptors become the property of the new list and may no longer be used by the caller. The array itself is owned by the caller. Each file descriptor in the array should be set to close-on-exec. If @n_fds is -1 then @fds must be terminated with -1. a new #GUnixFDList the initial list of file descriptors the length of #fds, or -1 Adds a file descriptor to @list. The file descriptor is duplicated using dup(). You keep your copy of the descriptor and the copy contained in @list will be closed when @list is finalized. A possible cause of failure is exceeding the per-process or system-wide file descriptor limit. The index of the file descriptor in the list is returned. If you use this index with g_unix_fd_list_get() then you will receive back a duplicated copy of the same file descriptor. the index of the appended fd in case of success, else -1 (and @error is set) a #GUnixFDList a valid open file descriptor Gets a file descriptor out of @list. @index_ specifies the index of the file descriptor to get. It is a programmer error for @index_ to be out of range; see g_unix_fd_list_get_length(). The file descriptor is duplicated using dup() and set as close-on-exec before being returned. You must call close() on it when you are done. A possible cause of failure is exceeding the per-process or system-wide file descriptor limit. the file descriptor, or -1 in case of error a #GUnixFDList the index into the list Gets the length of @list (ie: the number of file descriptors contained within). the length of @list a #GUnixFDList Returns the array of file descriptors that is contained in this object. After this call, the descriptors remain the property of @list. The caller must not close them and must not free the array. The array is valid only until @list is changed in any way. If @length is non-%NULL then it is set to the number of file descriptors in the returned array. The returned array is also terminated with -1. This function never returns %NULL. In case there are no file descriptors contained in @list, an empty array is returned. an array of file descriptors a #GUnixFDList pointer to the length of the returned array, or %NULL Returns the array of file descriptors that is contained in this object. After this call, the descriptors are no longer contained in @list. Further calls will return an empty list (unless more descriptors have been added). The return result of this function must be freed with g_free(). The caller is also responsible for closing all of the file descriptors. The file descriptors in the array are set to close-on-exec. If @length is non-%NULL then it is set to the number of file descriptors in the returned array. The returned array is also terminated with -1. This function never returns %NULL. In case there are no file descriptors contained in @list, an empty array is returned. an array of file descriptors a #GUnixFDList pointer to the length of the returned array, or %NULL Support for UNIX-domain (also known as local) sockets, corresponding to `struct sockaddr_un`. UNIX domain sockets are generally visible in the filesystem. However, some systems support abstract socket names which are not visible in the filesystem and not affected by the filesystem permissions, visibility, etc. Currently this is only supported under Linux. If you attempt to use abstract sockets on other systems, function calls may return `G_IO_ERROR_NOT_SUPPORTED` errors. You can use [func@Gio.UnixSocketAddress.abstract_names_supported] to see if abstract names are supported. Since GLib 2.72, `GUnixSocketAddress` is available on all platforms. It requires underlying system support (such as Windows 10 with `AF_UNIX`) at run time. Before GLib 2.72, `<gio/gunixsocketaddress.h>` belonged to the UNIX-specific GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when using it. This is no longer necessary since GLib 2.72. Creates a new #GUnixSocketAddress for @path. To create abstract socket addresses, on systems that support that, use g_unix_socket_address_new_abstract(). a new #GUnixSocketAddress the socket path Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED #GUnixSocketAddress for @path. Use g_unix_socket_address_new_with_type(). a new #GUnixSocketAddress the abstract name the length of @path, or -1 Creates a new #GUnixSocketAddress of type @type with name @path. If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to calling g_unix_socket_address_new(). If @type is %G_UNIX_SOCKET_ADDRESS_ANONYMOUS, @path and @path_len will be ignored. If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len bytes of @path will be copied to the socket's path, and only those bytes will be considered part of the name. (If @path_len is -1, then @path is assumed to be NUL-terminated.) For example, if @path was "test", then calling g_socket_address_get_native_size() on the returned socket would return 7 (2 bytes of overhead, 1 byte for the abstract-socket indicator byte, and 4 bytes for the name "test"). If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then @path_len bytes of @path will be copied to the socket's path, the rest of the path will be padded with 0 bytes, and the entire zero-padded buffer will be considered the name. (As above, if @path_len is -1, then @path is assumed to be NUL-terminated.) In this case, g_socket_address_get_native_size() will always return the full size of a `struct sockaddr_un`, although g_unix_socket_address_get_path_len() will still return just the length of @path. %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course, when connecting to a server created by another process, you must use the appropriate type corresponding to how that process created its listening socket. a new #GUnixSocketAddress the name the length of @path, or -1 a #GUnixSocketAddressType Checks if abstract UNIX domain socket names are supported. %TRUE if supported, %FALSE otherwise Gets @address's type. a #GUnixSocketAddressType a #GInetSocketAddress Tests if @address is abstract. Use g_unix_socket_address_get_address_type() %TRUE if the address is abstract, %FALSE otherwise a #GInetSocketAddress Gets @address's path, or for abstract sockets the "name". Guaranteed to be zero-terminated, but an abstract socket may contain embedded zeros, and thus you should use g_unix_socket_address_get_path_len() to get the true length of this string. the path for @address a #GInetSocketAddress Gets the length of @address's path. For details, see g_unix_socket_address_get_path(). the length of the path a #GInetSocketAddress Whether or not this is an abstract address Use #GUnixSocketAddress:address-type, which distinguishes between zero-padded and non-zero-padded abstract addresses. The type of Unix socket address. Unix socket path. Unix socket path, as a byte array. The type of name used by a #GUnixSocketAddress. %G_UNIX_SOCKET_ADDRESS_PATH indicates a traditional unix domain socket bound to a filesystem path. %G_UNIX_SOCKET_ADDRESS_ANONYMOUS indicates a socket not bound to any name (eg, a client-side socket, or a socket created with socketpair()). For abstract sockets, there are two incompatible ways of naming them; the man pages suggest using the entire `struct sockaddr_un` as the name, padding the unused parts of the %sun_path field with zeroes; this corresponds to %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED. However, many programs instead just use a portion of %sun_path, and pass an appropriate smaller length to bind() or connect(). This is %G_UNIX_SOCKET_ADDRESS_ABSTRACT. invalid anonymous a filesystem path an abstract name an abstract name, 0-padded to the full length of a unix socket name Extension point for #GVfs functionality. See [Extending GIO](overview.html#extending-gio). The string used to obtain the volume class with g_volume_get_identifier(). Known volume classes include `device`, `network`, and `loop`. Other classes may be added in the future. This is intended to be used by applications to classify #GVolume instances into different sections - for example a file manager or file chooser can use this information to show `network` volumes under a "Network" heading and `device` volumes under a "Devices" heading. The string used to obtain a Hal UDI with g_volume_get_identifier(). Do not use, HAL is deprecated. The string used to obtain a filesystem label with g_volume_get_identifier(). The string used to obtain a NFS mount with g_volume_get_identifier(). The string used to obtain a Unix device path with g_volume_get_identifier(). The string used to obtain a UUID with g_volume_get_identifier(). Extension point for volume monitor functionality. See [Extending GIO](overview.html#extending-gio). Entry point for using GIO functionality. Gets the default #GVfs for the system. a #GVfs, which will be the local file system #GVfs if no other implementation is available. Gets the local #GVfs for the system. a #GVfs. Gets a #GFile for @path. a #GFile. Free the returned object with g_object_unref(). a #GVfs. a string containing a VFS path. Gets a #GFile for @uri. This operation never fails, but the returned object might not support any I/O operation if the URI is malformed or if the URI scheme is not supported. a #GFile. Free the returned object with g_object_unref(). a#GVfs. a string containing a URI Gets a list of URI schemes supported by @vfs. a %NULL-terminated array of strings. The returned array belongs to GIO and must not be freed or modified. a #GVfs. Checks if the VFS is active. %TRUE if construction of the @vfs was successful and it is now active. a #GVfs. This operation never fails, but the returned object might not support any I/O operations if the @parse_name cannot be parsed by the #GVfs module. a #GFile for the given @parse_name. Free the returned object with g_object_unref(). a #GVfs. a string to be parsed by the VFS module. Gets a #GFile for @path. a #GFile. Free the returned object with g_object_unref(). a #GVfs. a string containing a VFS path. Gets a #GFile for @uri. This operation never fails, but the returned object might not support any I/O operation if the URI is malformed or if the URI scheme is not supported. a #GFile. Free the returned object with g_object_unref(). a#GVfs. a string containing a URI Gets a list of URI schemes supported by @vfs. a %NULL-terminated array of strings. The returned array belongs to GIO and must not be freed or modified. a #GVfs. Checks if the VFS is active. %TRUE if construction of the @vfs was successful and it is now active. a #GVfs. This operation never fails, but the returned object might not support any I/O operations if the @parse_name cannot be parsed by the #GVfs module. a #GFile for the given @parse_name. Free the returned object with g_object_unref(). a #GVfs. a string to be parsed by the VFS module. Registers @uri_func and @parse_name_func as the #GFile URI and parse name lookup functions for URIs with a scheme matching @scheme. Note that @scheme is registered only within the running application, as opposed to desktop-wide as it happens with GVfs backends. When a #GFile is requested with an URI containing @scheme (e.g. through g_file_new_for_uri()), @uri_func will be called to allow a custom constructor. The implementation of @uri_func should not be blocking, and must not call g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme(). When g_file_parse_name() is called with a parse name obtained from such file, @parse_name_func will be called to allow the #GFile to be created again. In that case, it's responsibility of @parse_name_func to make sure the parse name matches what the custom #GFile implementation returned when g_file_get_parse_name() was previously called. The implementation of @parse_name_func should not be blocking, and must not call g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme(). It's an error to call this function twice with the same scheme. To unregister a custom URI scheme, use g_vfs_unregister_uri_scheme(). %TRUE if @scheme was successfully registered, or %FALSE if a handler for @scheme already exists. a #GVfs an URI scheme, e.g. "http" a #GVfsFileLookupFunc custom data passed to be passed to @uri_func, or %NULL function to be called when unregistering the URI scheme, or when @vfs is disposed, to free the resources used by the URI lookup function a #GVfsFileLookupFunc custom data passed to be passed to @parse_name_func, or %NULL function to be called when unregistering the URI scheme, or when @vfs is disposed, to free the resources used by the parse name lookup function Unregisters the URI handler for @scheme previously registered with g_vfs_register_uri_scheme(). %TRUE if @scheme was successfully unregistered, or %FALSE if a handler for @scheme does not exist. a #GVfs an URI scheme, e.g. "http" %TRUE if construction of the @vfs was successful and it is now active. a #GVfs. a #GFile. Free the returned object with g_object_unref(). a #GVfs. a string containing a VFS path. a #GFile. Free the returned object with g_object_unref(). a#GVfs. a string containing a URI a %NULL-terminated array of strings. The returned array belongs to GIO and must not be freed or modified. a #GVfs. a #GFile for the given @parse_name. Free the returned object with g_object_unref(). a #GVfs. a string to be parsed by the VFS module. This function type is used by g_vfs_register_uri_scheme() to make it possible for a client to associate a URI scheme to a different #GFile implementation. The client should return a reference to the new file that has been created for @uri, or %NULL to continue with the default implementation. a #GFile for @identifier. a #GVfs the identifier to look up a #GFile for. This can either be a URI or a parse name as returned by g_file_get_parse_name() user data passed to the function, or %NULL The `GVolume` interface represents user-visible objects that can be mounted. For example, a file system partition on a USB flash drive, or an optical disc inserted into a disc drive. If a `GVolume` is currently mounted, the corresponding [iface@Gio.Mount] can be retrieved using [method@Gio.Volume.get_mount]. Mounting a `GVolume` instance is an asynchronous operation. For more information about asynchronous operations, see [iface@Gio.AsyncResult] and [class@Gio.Task]. To mount a `GVolume`, first call [method@Gio.Volume.mount] with (at least) the `GVolume` instance, optionally a [class@Gio.MountOperation] object and a [type@Gio.AsyncReadyCallback]. Typically, one will only want to pass `NULL` for the [class@Gio.MountOperation] if automounting all volumes when a desktop session starts since it’s not desirable to put up a lot of dialogs asking for credentials. The callback will be fired when the operation has resolved (either with success or failure), and a [iface@Gio.AsyncResult] instance will be passed to the callback. That callback should then call [method@Gio.Volume.mount_finish] with the `GVolume` instance and the [iface@Gio.AsyncResult] data to see if the operation was completed successfully. If a [type@GLib.Error] is present when [method@Gio.Volume.mount_finish] is called, then it will be filled with any error information. Note, when [porting from GnomeVFS](migrating-gnome-vfs.html), `GVolume` is the moral equivalent of `GnomeVFSDrive`. ## Volume Identifiers It is sometimes necessary to directly access the underlying operating system object behind a volume (e.g. for passing a volume to an application via the command line). For this purpose, GIO allows to obtain an ‘identifier’ for the volume. There can be different kinds of identifiers, such as Hal UDIs, filesystem labels, traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined strings as names for the different kinds of identifiers: `G_VOLUME_IDENTIFIER_KIND_UUID`, `G_VOLUME_IDENTIFIER_KIND_LABEL`, etc. Use [method@Gio.Volume.get_identifier] to obtain an identifier for a volume. Note that `G_VOLUME_IDENTIFIER_KIND_HAL_UDI` will only be available when the GVFS hal volume monitor is in use. Other volume monitors will generally be able to provide the `G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE` identifier, which can be used to obtain a hal device by means of `libhal_manager_find_device_string_match()`. Checks if a volume can be ejected. %TRUE if the @volume can be ejected. %FALSE otherwise a #GVolume Checks if a volume can be mounted. %TRUE if the @volume can be mounted. %FALSE otherwise a #GVolume Changed signal that is emitted when the volume's state has changed. Ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_finish() with the @volume and #GAsyncResult returned in the @callback. Use g_volume_eject_with_operation() instead. a #GVolume flags affecting the unmount if required for eject optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback, or %NULL user data that gets passed to @callback Finishes ejecting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Use g_volume_eject_with_operation_finish() instead. %TRUE, %FALSE if operation failed pointer to a #GVolume a #GAsyncResult Ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_with_operation_finish() with the @volume and #GAsyncResult data returned in the @callback. a #GVolume flags affecting the unmount if required for eject a #GMountOperation or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback, or %NULL user data passed to @callback Finishes ejecting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. %TRUE if the volume was successfully ejected. %FALSE otherwise a #GVolume a #GAsyncResult Gets the kinds of [identifiers](#volume-identifiers) that @volume has. Use g_volume_get_identifier() to obtain the identifiers themselves. a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. a #GVolume Gets the activation root for a #GVolume if it is known ahead of mount time. Returns %NULL otherwise. If not %NULL and if @volume is mounted, then the result of g_mount_get_root() on the #GMount object obtained from g_volume_get_mount() will always either be equal or a prefix of what this function returns. In other words, in code |[<!-- language="C" --> GMount *mount; GFile *mount_root GFile *volume_activation_root; mount = g_volume_get_mount (volume); // mounted, so never NULL mount_root = g_mount_get_root (mount); volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL ]| then the expression |[<!-- language="C" --> (g_file_has_prefix (volume_activation_root, mount_root) || g_file_equal (volume_activation_root, mount_root)) ]| will always be %TRUE. Activation roots are typically used in #GVolumeMonitor implementations to find the underlying mount to shadow, see g_mount_is_shadowed() for more details. the activation root of @volume or %NULL. Use g_object_unref() to free. a #GVolume Gets the drive for the @volume. a #GDrive or %NULL if @volume is not associated with a drive. The returned object should be unreffed with g_object_unref() when no longer needed. a #GVolume Gets the icon for @volume. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. a #GVolume Gets the identifier of the given kind for @volume. See the [introduction](#volume-identifiers) for more information about volume identifiers. a newly allocated string containing the requested identifier, or %NULL if the #GVolume doesn't have this kind of identifier a #GVolume the kind of identifier to return Gets the mount for the @volume. a #GMount or %NULL if @volume isn't mounted. The returned object should be unreffed with g_object_unref() when no longer needed. a #GVolume Gets the name of @volume. the name for the given @volume. The returned string should be freed with g_free() when no longer needed. a #GVolume Gets the sort key for @volume, if any. Sorting key for @volume or %NULL if no such key is available a #GVolume Gets the symbolic icon for @volume. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. a #GVolume Gets the UUID for the @volume. The reference is typically based on the file system UUID for the volume in question and should be considered an opaque string. Returns %NULL if there is no UUID available. the UUID for @volume or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. a #GVolume Finishes mounting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. If the mount operation succeeded, g_volume_get_mount() on @volume is guaranteed to return the mount right after calling this function; there's no need to listen for the 'mount-added' signal on #GVolumeMonitor. %TRUE, %FALSE if operation failed a #GVolume a #GAsyncResult Mounts a volume. This is an asynchronous operation, and is finished by calling g_volume_mount_finish() with the @volume and #GAsyncResult returned in the @callback. a #GVolume flags affecting the operation a #GMountOperation or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback, or %NULL user data that gets passed to @callback The removed signal that is emitted when the #GVolume have been removed. If the recipient is holding references to the object they should release them so the object can be finalized. Returns whether the volume should be automatically mounted. %TRUE if the volume should be automatically mounted a #GVolume Checks if a volume can be ejected. %TRUE if the @volume can be ejected. %FALSE otherwise a #GVolume Checks if a volume can be mounted. %TRUE if the @volume can be mounted. %FALSE otherwise a #GVolume Ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_finish() with the @volume and #GAsyncResult returned in the @callback. Use g_volume_eject_with_operation() instead. a #GVolume flags affecting the unmount if required for eject optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback, or %NULL user data that gets passed to @callback Finishes ejecting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Use g_volume_eject_with_operation_finish() instead. %TRUE, %FALSE if operation failed pointer to a #GVolume a #GAsyncResult Ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_with_operation_finish() with the @volume and #GAsyncResult data returned in the @callback. a #GVolume flags affecting the unmount if required for eject a #GMountOperation or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback, or %NULL user data passed to @callback Finishes ejecting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. %TRUE if the volume was successfully ejected. %FALSE otherwise a #GVolume a #GAsyncResult Gets the kinds of [identifiers](#volume-identifiers) that @volume has. Use g_volume_get_identifier() to obtain the identifiers themselves. a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. a #GVolume Gets the activation root for a #GVolume if it is known ahead of mount time. Returns %NULL otherwise. If not %NULL and if @volume is mounted, then the result of g_mount_get_root() on the #GMount object obtained from g_volume_get_mount() will always either be equal or a prefix of what this function returns. In other words, in code |[<!-- language="C" --> GMount *mount; GFile *mount_root GFile *volume_activation_root; mount = g_volume_get_mount (volume); // mounted, so never NULL mount_root = g_mount_get_root (mount); volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL ]| then the expression |[<!-- language="C" --> (g_file_has_prefix (volume_activation_root, mount_root) || g_file_equal (volume_activation_root, mount_root)) ]| will always be %TRUE. Activation roots are typically used in #GVolumeMonitor implementations to find the underlying mount to shadow, see g_mount_is_shadowed() for more details. the activation root of @volume or %NULL. Use g_object_unref() to free. a #GVolume Gets the drive for the @volume. a #GDrive or %NULL if @volume is not associated with a drive. The returned object should be unreffed with g_object_unref() when no longer needed. a #GVolume Gets the icon for @volume. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. a #GVolume Gets the identifier of the given kind for @volume. See the [introduction](#volume-identifiers) for more information about volume identifiers. a newly allocated string containing the requested identifier, or %NULL if the #GVolume doesn't have this kind of identifier a #GVolume the kind of identifier to return Gets the mount for the @volume. a #GMount or %NULL if @volume isn't mounted. The returned object should be unreffed with g_object_unref() when no longer needed. a #GVolume Gets the name of @volume. the name for the given @volume. The returned string should be freed with g_free() when no longer needed. a #GVolume Gets the sort key for @volume, if any. Sorting key for @volume or %NULL if no such key is available a #GVolume Gets the symbolic icon for @volume. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. a #GVolume Gets the UUID for the @volume. The reference is typically based on the file system UUID for the volume in question and should be considered an opaque string. Returns %NULL if there is no UUID available. the UUID for @volume or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. a #GVolume Mounts a volume. This is an asynchronous operation, and is finished by calling g_volume_mount_finish() with the @volume and #GAsyncResult returned in the @callback. a #GVolume flags affecting the operation a #GMountOperation or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback, or %NULL user data that gets passed to @callback Finishes mounting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. If the mount operation succeeded, g_volume_get_mount() on @volume is guaranteed to return the mount right after calling this function; there's no need to listen for the 'mount-added' signal on #GVolumeMonitor. %TRUE, %FALSE if operation failed a #GVolume a #GAsyncResult Returns whether the volume should be automatically mounted. %TRUE if the volume should be automatically mounted a #GVolume Emitted when the volume has been changed. This signal is emitted when the #GVolume have been removed. If the recipient is holding references to the object they should release them so the object can be finalized. Interface for implementing operations for mountable volumes. The parent interface. Changed signal that is emitted when the volume's state has changed. The removed signal that is emitted when the #GVolume have been removed. If the recipient is holding references to the object they should release them so the object can be finalized. Gets a string containing the name of the #GVolume. the name for the given @volume. The returned string should be freed with g_free() when no longer needed. a #GVolume Gets a #GIcon for the #GVolume. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. a #GVolume Gets the UUID for the #GVolume. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available. the UUID for @volume or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. a #GVolume Gets a #GDrive the volume is located on. Returns %NULL if the #GVolume is not associated with a #GDrive. a #GDrive or %NULL if @volume is not associated with a drive. The returned object should be unreffed with g_object_unref() when no longer needed. a #GVolume Gets a #GMount representing the mounted volume. Returns %NULL if the #GVolume is not mounted. a #GMount or %NULL if @volume isn't mounted. The returned object should be unreffed with g_object_unref() when no longer needed. a #GVolume Returns %TRUE if the #GVolume can be mounted. %TRUE if the @volume can be mounted. %FALSE otherwise a #GVolume Checks if a #GVolume can be ejected. %TRUE if the @volume can be ejected. %FALSE otherwise a #GVolume Mounts a given #GVolume. #GVolume implementations must emit the #GMountOperation::aborted signal before completing a mount operation that is aborted while awaiting input from the user through a #GMountOperation instance. a #GVolume flags affecting the operation a #GMountOperation or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback, or %NULL user data that gets passed to @callback Finishes a mount operation. %TRUE, %FALSE if operation failed a #GVolume a #GAsyncResult Ejects a given #GVolume. a #GVolume flags affecting the unmount if required for eject optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback, or %NULL user data that gets passed to @callback Finishes an eject operation. %TRUE, %FALSE if operation failed pointer to a #GVolume a #GAsyncResult Returns the [identifier](#volume-identifiers) of the given kind, or %NULL if the #GVolume doesn't have one. a newly allocated string containing the requested identifier, or %NULL if the #GVolume doesn't have this kind of identifier a #GVolume the kind of identifier to return Returns an array strings listing the kinds of [identifiers](#volume-identifiers) which the #GVolume has. a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. a #GVolume Returns %TRUE if the #GVolume should be automatically mounted. %TRUE if the volume should be automatically mounted a #GVolume Returns the activation root for the #GVolume if it is known in advance or %NULL if it is not known. the activation root of @volume or %NULL. Use g_object_unref() to free. a #GVolume Starts ejecting a #GVolume using a #GMountOperation. Since 2.22. a #GVolume flags affecting the unmount if required for eject a #GMountOperation or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback, or %NULL user data passed to @callback Finishes an eject operation using a #GMountOperation. Since 2.22. %TRUE if the volume was successfully ejected. %FALSE otherwise a #GVolume a #GAsyncResult Gets a key used for sorting #GVolume instance or %NULL if no such key exists. Since 2.32. Sorting key for @volume or %NULL if no such key is available a #GVolume Gets a symbolic #GIcon for the #GVolume. Since 2.34. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. a #GVolume `GVolumeMonitor` is for listing the user interesting devices and volumes on the computer. In other words, what a file selector or file manager would show in a sidebar. `GVolumeMonitor` is not thread-default-context aware (see [method@GLib.MainContext.push_thread_default]), and so should not be used other than from the main thread, with no thread-default-context active. In order to receive updates about volumes and mounts monitored through GVFS, a main loop must be running. This function should be called by any #GVolumeMonitor implementation when a new #GMount object is created that is not associated with a #GVolume object. It must be called just before emitting the @mount_added signal. If the return value is not %NULL, the caller must associate the returned #GVolume object with the #GMount. This involves returning it in its g_mount_get_volume() implementation. The caller must also listen for the "removed" signal on the returned object and give up its reference when handling that signal Similarly, if implementing g_volume_monitor_adopt_orphan_mount(), the implementor must take a reference to @mount and return it in its g_volume_get_mount() implemented. Also, the implementor must listen for the "unmounted" signal on @mount and give up its reference upon handling that signal. There are two main use cases for this function. One is when implementing a user space file system driver that reads blocks of a block device that is already represented by the native volume monitor (for example a CD Audio file system driver). Such a driver will generate its own #GMount object that needs to be associated with the #GVolume object that represents the volume. The other is for implementing a #GVolumeMonitor whose sole purpose is to return #GVolume objects representing entries in the users "favorite servers" list or similar. Instead of using this function, #GVolumeMonitor implementations should instead create shadow mounts with the URI of the mount they intend to adopt. See the proxy volume monitor in gvfs for an example of this. Also see g_mount_is_shadowed(), g_mount_shadow() and g_mount_unshadow() functions. the #GVolume object that is the parent for @mount or %NULL if no wants to adopt the #GMount. a #GMount object to find a parent for Gets the volume monitor used by gio. a reference to the #GVolumeMonitor used by gio. Call g_object_unref() when done with it, after disconnecting any signal handlers. Gets a list of drives connected to the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). a #GList of connected #GDrive objects. a #GVolumeMonitor. Finds a #GMount object by its UUID (see g_mount_get_uuid()) a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref(). a #GVolumeMonitor. the UUID to look for Gets a list of the mounts on the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). a #GList of #GMount objects. a #GVolumeMonitor. Finds a #GVolume object by its UUID (see g_volume_get_uuid()) a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref(). a #GVolumeMonitor. the UUID to look for Gets a list of the volumes on the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). a #GList of #GVolume objects. a #GVolumeMonitor. Gets a list of drives connected to the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). a #GList of connected #GDrive objects. a #GVolumeMonitor. Finds a #GMount object by its UUID (see g_mount_get_uuid()) a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref(). a #GVolumeMonitor. the UUID to look for Gets a list of the mounts on the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). a #GList of #GMount objects. a #GVolumeMonitor. Finds a #GVolume object by its UUID (see g_volume_get_uuid()) a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref(). a #GVolumeMonitor. the UUID to look for Gets a list of the volumes on the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). a #GList of #GVolume objects. a #GVolumeMonitor. Emitted when a drive changes. the drive that changed Emitted when a drive is connected to the system. a #GDrive that was connected. Emitted when a drive is disconnected from the system. a #GDrive that was disconnected. Emitted when the eject button is pressed on @drive. the drive where the eject button was pressed Emitted when the stop button is pressed on @drive. the drive where the stop button was pressed Emitted when a mount is added. a #GMount that was added. Emitted when a mount changes. a #GMount that changed. May be emitted when a mount is about to be removed. This signal depends on the backend and is only emitted if GIO was used to unmount. a #GMount that is being unmounted. Emitted when a mount is removed. a #GMount that was removed. Emitted when a mountable volume is added to the system. a #GVolume that was added. Emitted when mountable volume is changed. a #GVolume that changed. Emitted when a mountable volume is removed from the system. a #GVolume that was removed. a #GList of connected #GDrive objects. a #GVolumeMonitor. a #GList of #GVolume objects. a #GVolumeMonitor. a #GList of #GMount objects. a #GVolumeMonitor. a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref(). a #GVolumeMonitor. the UUID to look for a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref(). a #GVolumeMonitor. the UUID to look for `GZlibCompressor` is an implementation of [iface@Gio.Converter] that compresses data using zlib. Creates a compressor. a new [class@Gio.ZlibCompressor] the format to use for the compressed data compression level (`0`-`9`), `-1` for default Gets the [property@Gio.ZlibCompressor:file-info] property. file info for the gzip header, if set a compressor Gets the [property@Gio.ZlibCompressor:os] property. the previously set OS value, or `-1` if unset a compressor Sets the [property@Gio.ZlibCompressor:file-info] property. Note: it is an error to call this function while a compression is in progress; it may only be called immediately after creation of @compressor, or after resetting it with [method@Gio.Converter.reset]. a compressor file info for the gzip header Sets the [property@Gio.ZlibCompressor:os] property. Note: it is an error to call this function while a compression is in progress; it may only be called immediately after creation of @compressor, or after resetting it with [method@Gio.Converter.reset]. a compressor the OS code to use, or `-1` to unset A [class@Gio.FileInfo] containing file information to put into the gzip header. The file name and modification time from the file info will be used. This will only be used if non-`NULL` and [property@Gio.ZlibCompressor:format] is [enum@Gio.ZlibCompressorFormat.GZIP]. The format of the compressed data. The level of compression from `0` (no compression) to `9` (most compression). `-1` for the default level. The OS code of the gzip header. This will be used if set to a non-negative value, and if [property@Gio.ZlibCompressor:format] is [enum@Gio.ZlibCompressorFormat.GZIP], the compressor will set the OS code of the gzip header to this value. If the value is unset, zlib will set the OS code depending on the platform. This may be undesirable when reproducible output is desired. In that case setting the OS code to `3` (for Unix) is recommended. Used to select the type of data format to use for #GZlibDecompressor and #GZlibCompressor. deflate compression with zlib header gzip file format deflate compression with no header `GZlibDecompressor` is an implementation of [iface@Gio.Converter] that decompresses data compressed with zlib. Creates a new decompressor. a new [class@Gio.ZlibDecompressor] the format to use for the compressed data Gets the [property@Gio.ZlibDecompressor:file-info] property. file info from the gzip header, if available a #GZlibDecompressor A [class@Gio.FileInfo] containing the information found in the gzip header of the data stream processed. This will be `NULL` if the header was not yet fully processed, is not present at all, or the compressor’s [property@Gio.ZlibDecompressor:format] property is not [enum@Gio.ZlibCompressorFormat.GZIP]. The format of the compressed data. Checks if @action_name is valid. @action_name is valid if it consists only of alphanumeric characters, plus `-` and `.`. The empty string is not a valid action name. It is an error to call this function with a non-UTF-8 @action_name. @action_name must not be `NULL`. `TRUE` if @action_name is valid a potential action name Parses a detailed action name into its separate name and target components. Detailed action names can have three formats. The first format is used to represent an action name with no target value and consists of just an action name containing no whitespace nor the characters `:`, `(` or `)`. For example: `app.action`. The second format is used to represent an action with a target value that is a non-empty string consisting only of alphanumerics, plus `-` and `.`. In that case, the action name and target value are separated by a double colon (`::`). For example: `app.action::target`. The third format is used to represent an action with any type of target value, including strings. The target value follows the action name, surrounded in parens. For example: `app.action(42)`. The target value is parsed using [func@GLib.Variant.parse]. If a tuple-typed value is desired, it must be specified in the same way, resulting in two sets of parens, for example: `app.action((1,2,3))`. A string target can be specified this way as well: `app.action('target')`. For strings, this third format must be used if target value is empty or contains characters other than alphanumerics, `-` and `.`. If this function returns `TRUE`, a non-`NULL` value is guaranteed to be returned in @action_name (if a pointer is passed in). A `NULL` value may still be returned in @target_value, as the @detailed_name may not contain a target. If returned, the [type@GLib.Variant] in @target_value is guaranteed to not be floating. `TRUE` if successful, else `FALSE` with @error set a detailed action name the action name the target value, or `NULL` for no target Formats a detailed action name from @action_name and @target_value. It is an error to call this function with an invalid action name. This function is the opposite of [func@Gio.Action.parse_detailed_name]. It will produce a string that can be parsed back to the @action_name and @target_value by that function. See that function for the types of strings that will be printed by this function. a detailed format string a valid action name a [type@GLib.Variant] target value, or `NULL` Creates a new [iface@Gio.AppInfo] from the given information. Note that for @commandline, the quoting rules of the `Exec` key of the [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) are applied. For example, if the @commandline contains percent-encoded URIs, the percent-character must be doubled in order to prevent it from being swallowed by `Exec` key unquoting. See [the specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s07.html) for exact quoting rules. new [iface@Gio.AppInfo] for given command. the command line to use the application name, or `NULL` to use @commandline flags that can specify details of the created [iface@Gio.AppInfo] Gets a list of all of the applications currently registered on this system. For desktop files, this includes applications that have [`NoDisplay=true`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) set or are excluded from display by means of [`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) or [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin). See [method@Gio.AppInfo.should_show]. The returned list does not include applications which have the [`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) set. a newly allocated list of references to [iface@Gio.AppInfo]s. Gets a list of all [iface@Gio.AppInfo]s for a given content type, including the recommended and fallback [iface@Gio.AppInfo]s. See [func@Gio.AppInfo.get_recommended_for_type] and [func@Gio.AppInfo.get_fallback_for_type]. list of [iface@Gio.AppInfo]s for given @content_type. the content type to find a [iface@Gio.AppInfo] for Gets the default [iface@Gio.AppInfo] for a given content type. [iface@Gio.AppInfo] for given @content_type or `NULL` on error. the content type to find a [iface@Gio.AppInfo] for if `TRUE`, the [iface@Gio.AppInfo] is expected to support URIs Asynchronously gets the default [iface@Gio.AppInfo] for a given content type. the content type to find a [iface@Gio.AppInfo] for if `TRUE`, the [iface@Gio.AppInfo] is expected to support URIs a [class@Gio.Cancellable] a [type@Gio.AsyncReadyCallback] to call when the request is done data to pass to @callback Finishes a default [iface@Gio.AppInfo] lookup started by [func@Gio.AppInfo.get_default_for_type_async]. If no #[iface@Gio.AppInfo] is found, then @error will be set to [error@Gio.IOErrorEnum.NOT_FOUND]. [iface@Gio.AppInfo] for given @content_type or `NULL` on error. the async result Gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part of the URI, up to but not including the `:`. For example, `http`, `ftp` or `sip`. [iface@Gio.AppInfo] for given @uri_scheme or `NULL` on error. a string containing a URI scheme. Asynchronously gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part of the URI, up to but not including the `:`, e.g. `http`, `ftp` or `sip`. a string containing a URI scheme. a [class@Gio.Cancellable] a [type@Gio.AsyncReadyCallback] to call when the request is done data to pass to @callback Finishes a default [iface@Gio.AppInfo] lookup started by [func@Gio.AppInfo.get_default_for_uri_scheme_async]. If no [iface@Gio.AppInfo] is found, then @error will be set to [error@Gio.IOErrorEnum.NOT_FOUND]. [iface@Gio.AppInfo] for given @uri_scheme or `NULL` on error. the async result Gets a list of fallback [iface@Gio.AppInfo]s for a given content type, i.e. those applications which claim to support the given content type by MIME type subclassing and not directly. list of [iface@Gio.AppInfo]s for given @content_type or `NULL` on error. the content type to find a [iface@Gio.AppInfo] for Gets a list of recommended [iface@Gio.AppInfo]s for a given content type, i.e. those applications which claim to support the given content type exactly, and not by MIME type subclassing. Note that the first application of the list is the last used one, i.e. the last one for which [method@Gio.AppInfo.set_as_last_used_for_type] has been called. list of [iface@Gio.AppInfo]s for given @content_type or `NULL` on error. the content type to find a [iface@Gio.AppInfo] for Utility function that launches the default application registered to handle the specified uri. Synchronous I/O is done on the uri to detect the type of the file if required. The D-Bus–activated applications don’t have to be started if your application terminates too soon after this function. To prevent this, use [func@Gio.AppInfo.launch_default_for_uri_async] instead. `TRUE` on success, `FALSE` on error. the uri to show optional launch context Async version of [func@Gio.AppInfo.launch_default_for_uri]. This version is useful if you are interested in receiving error information in the case where the application is sandboxed and the portal may present an application chooser dialog to the user. This is also useful if you want to be sure that the D-Bus–activated applications are really started before termination and if you are interested in receiving error information from their activation. the uri to show optional launch context a [class@Gio.Cancellable] a [type@Gio.AsyncReadyCallback] to call when the request is done data to pass to @callback Finishes an asynchronous launch-default-for-uri operation. `TRUE` if the launch was successful, `FALSE` if @error is set the async result Removes all changes to the type associations done by [method@Gio.AppInfo.set_as_default_for_type], [method@Gio.AppInfo.set_as_default_for_extension], [method@Gio.AppInfo.add_supports_type] or [method@Gio.AppInfo.remove_supports_type]. a content type Helper function for constructing #GAsyncInitable object. This is similar to g_object_newv() but also initializes the object asynchronously. When the initialization is finished, @callback will be called. You can then call g_async_initable_new_finish() to get the new object and check for any errors. Use g_object_new_with_properties() and g_async_initable_init_async() instead. See #GParameter for more information. a #GType supporting #GAsyncInitable. the number of parameters in @parameters the parameters to use to construct the object the [I/O priority](iface.AsyncResult.html#io-priority) of the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the initialization is finished the data to pass to callback function Asynchronously connects to the message bus specified by @bus_type. When the operation is finished, @callback will be invoked. You can then call g_bus_get_finish() to get the result of the operation. This is an asynchronous failable function. See g_bus_get_sync() for the synchronous version. a #GBusType a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied the data to pass to @callback Finishes an operation started with g_bus_get(). The returned object is a singleton, that is, shared with other callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the event that you need a private message bus connection, use g_dbus_address_get_for_bus_sync() and g_dbus_connection_new_for_address() with G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT and G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION flags. Note that the returned #GDBusConnection object will (usually) have the #GDBusConnection:exit-on-close property set to %TRUE. a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get() Synchronously connects to the message bus specified by @bus_type. Note that the returned object may shared with other callers, e.g. if two separate parts of a process calls this function with the same @bus_type, they will share the same object. This is a synchronous failable function. See g_bus_get() and g_bus_get_finish() for the asynchronous version. The returned object is a singleton, that is, shared with other callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the event that you need a private message bus connection, use g_dbus_address_get_for_bus_sync() and g_dbus_connection_new_for_address() with G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT and G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION flags. Note that the returned #GDBusConnection object will (usually) have the #GDBusConnection:exit-on-close property set to %TRUE. a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). a #GBusType a #GCancellable or %NULL Requests ownership of @name on the bus specified by @bus_type. It asynchronously calls @name_acquired_handler and @name_lost_handler when the name is acquired and lost, respectively. Callbacks will be invoked in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this function from. You are guaranteed that one of the @name_acquired_handler and @name_lost_handler callbacks will be invoked after calling this function — there are three possible cases: - @name_lost_handler with a `NULL` connection (if a connection to the bus can’t be made). - @bus_acquired_handler then @name_lost_handler (if the name can’t be obtained). - @bus_acquired_handler then @name_acquired_handler (if the name was obtained). When you are done owning the name, call [func@Gio.bus_unown_name] with the owner ID this function returns. If the name is acquired or lost (for example another application could acquire the name if you allow replacement or the application currently owning the name exits), the handlers are also invoked. If the [class@Gio.DBusConnection] that is used for attempting to own the name closes, then @name_lost_handler is invoked since it is no longer possible for other processes to access the process. You cannot use [func@Gio.bus_own_name] several times for the same name (unless interleaved with calls to [func@Gio.bus_unown_name]) — only the first call will work. Another guarantee is that invocations of @name_acquired_handler and @name_lost_handler are guaranteed to alternate; that is, if @name_acquired_handler is invoked then you are guaranteed that the next time one of the handlers is invoked, it will be @name_lost_handler. The reverse is also true. If you plan on exporting objects (using, for example, [method@Gio.DBusConnection.register_object]), note that it is generally too late to export the objects in @name_acquired_handler. Instead, you can do this in @bus_acquired_handler since you are guaranteed that this will run before @name is requested from the bus. This behavior makes it very simple to write applications that want to [own names](dbus-name-owning.html#d-bus-name-owning) and export objects. Simply register objects to be exported in @bus_acquired_handler and unregister the objects (if any) in @name_lost_handler. an identifier (never 0) that can be used with [func@Gio.bus_unown_name] to stop owning the name the type of bus to own a name on the well-known name to own a set of flags with ownership options handler to invoke when connected to the bus of type @bus_type, or `NULL` to ignore handler to invoke when @name is acquired, or `NULL` to ignore handler to invoke when @name is lost, or `NULL` to ignore user data to pass to handlers function for freeing @user_data Like [func@Gio.bus_own_name] but takes a [class@Gio.DBusConnection] instead of a [enum@Gio.BusType]. an identifier (never 0) that can be used with [func@Gio.bus_unown_name] to stop owning the name a bus connection the well-known name to own a set of flags with ownership options handler to invoke when @name is acquired, or `NULL` to ignore handler to invoke when @name is lost, or `NULL` to ignore user data to pass to handlers function for freeing @user_data Version of [func@Gio.bus_own_name_on_connection] using closures instead of callbacks for easier binding in other languages. an identifier (never 0) that can be used with [func@Gio.bus_unown_name] to stop owning the name. a bus connection the well-known name to own a set of flags with ownership options closure to invoke when @name is acquired, or `NULL` to ignore closure to invoke when @name is lost, or `NULL` to ignore Version of [func@Gio.bus_own_name using closures instead of callbacks for easier binding in other languages. an identifier (never 0) that can be used with [func@Gio.bus_unown_name] to stop owning the name. the type of bus to own a name on the well-known name to own a set of flags with ownership options closure to invoke when connected to the bus of type @bus_type, or `NULL` to ignore closure to invoke when @name is acquired, or `NULL` to ignore closure to invoke when @name is lost, or `NULL` to ignore Stops owning a name. Note that there may still be D-Bus traffic to process (relating to owning and unowning the name) in the current thread-default [struct@GLib.MainContext] after this function has returned. You should continue to iterate the [struct@GLib.MainContext] until the [callback@GLib.DestroyNotify] function passed to [func@Gio.bus_own_name] is called, in order to avoid memory leaks through callbacks queued on the [struct@GLib.MainContext] after it’s stopped being iterated. an identifier obtained from [func@Gio.bus_own_name] Stops watching a name. Note that there may still be D-Bus traffic to process (relating to watching and unwatching the name) in the current thread-default #GMainContext after this function has returned. You should continue to iterate the #GMainContext until the #GDestroyNotify function passed to g_bus_watch_name() is called, in order to avoid memory leaks through callbacks queued on the #GMainContext after it’s stopped being iterated. An identifier obtained from g_bus_watch_name() Starts watching @name on the bus specified by @bus_type and calls @name_appeared_handler and @name_vanished_handler when the name is known to have an owner respectively known to lose its owner. Callbacks will be invoked in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this function from. You are guaranteed that one of the handlers will be invoked after calling this function. When you are done watching the name, just call g_bus_unwatch_name() with the watcher id this function returns. If the name vanishes or appears (for example the application owning the name could restart), the handlers are also invoked. If the #GDBusConnection that is used for watching the name disconnects, then @name_vanished_handler is invoked since it is no longer possible to access the name. Another guarantee is that invocations of @name_appeared_handler and @name_vanished_handler are guaranteed to alternate; that is, if @name_appeared_handler is invoked then you are guaranteed that the next time one of the handlers is invoked, it will be @name_vanished_handler. The reverse is also true. This behavior makes it very simple to write applications that want to take action when a certain [name exists](dbus-name-watching.html#d-bus-name-watching). Basically, the application should create object proxies in @name_appeared_handler and destroy them again (if any) in @name_vanished_handler. An identifier (never 0) that can be used with g_bus_unwatch_name() to stop watching the name. The type of bus to watch a name on. The name (well-known or unique) to watch. Flags from the #GBusNameWatcherFlags enumeration. Handler to invoke when @name is known to exist or %NULL. Handler to invoke when @name is known to not exist or %NULL. User data to pass to handlers. Function for freeing @user_data or %NULL. Like g_bus_watch_name() but takes a #GDBusConnection instead of a #GBusType. An identifier (never 0) that can be used with g_bus_unwatch_name() to stop watching the name. A #GDBusConnection. The name (well-known or unique) to watch. Flags from the #GBusNameWatcherFlags enumeration. Handler to invoke when @name is known to exist or %NULL. Handler to invoke when @name is known to not exist or %NULL. User data to pass to handlers. Function for freeing @user_data or %NULL. Version of g_bus_watch_name_on_connection() using closures instead of callbacks for easier binding in other languages. An identifier (never 0) that can be used with g_bus_unwatch_name() to stop watching the name. A #GDBusConnection. The name (well-known or unique) to watch. Flags from the #GBusNameWatcherFlags enumeration. #GClosure to invoke when @name is known to exist or %NULL. #GClosure to invoke when @name is known to not exist or %NULL. Version of g_bus_watch_name() using closures instead of callbacks for easier binding in other languages. An identifier (never 0) that can be used with g_bus_unwatch_name() to stop watching the name. The type of bus to watch a name on. The name (well-known or unique) to watch. Flags from the #GBusNameWatcherFlags enumeration. #GClosure to invoke when @name is known to exist or %NULL. #GClosure to invoke when @name is known to not exist or %NULL. If @subscription_id_pointer points to a nonzero subscription ID, unsubscribe from that D-Bus signal subscription as if via [method@Gio.DBusConnection.signal_unsubscribe]. Also set the value pointed to by @subscription_id_pointer to zero, which signifies it’s no longer a valid subscription ID. This convenience function for C code helps to ensure that each signal subscription is unsubscribed exactly once, similar to [func@GObject.clear_object] and [func@GObject.clear_signal_handler]. A pointer to either a subscription ID obtained from [method@Gio.DBusConnection.signal_subscribe], or zero. The connection from which the subscription ID was obtained. This pointer may be `NULL` or invalid, if the subscription ID is zero. Checks if a content type can be executable. Note that for instance things like text files can be executables (i.e. scripts and batch files). %TRUE if the file type corresponds to a type that can be executable, %FALSE otherwise. a content type string Compares two content types for equality. %TRUE if the two strings are identical or equivalent, %FALSE otherwise. a content type string a content type string Tries to find a content type based on the mime type name. Newly allocated string with content type or %NULL. Free with g_free() a mime type string Gets the human readable description of the content type. a short description of the content type @type. Free the returned string with g_free() a content type string Gets the generic icon name for a content type. See the [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on the generic icon name. the registered generic icon name for the given @type, or %NULL if unknown. Free with g_free() a content type string Gets the icon for a content type. #GIcon corresponding to the content type. Free the returned object with g_object_unref() a content type string Get the list of directories which MIME data is loaded from. See g_content_type_set_mime_dirs() for details. %NULL-terminated list of directories to load MIME data from, including any `mime/` subdirectory, and with the first directory to try listed first Gets the mime type for the content type, if one is registered. the registered mime type for the given @type, or %NULL if unknown; free with g_free(). a content type string Gets the symbolic icon for a content type. symbolic #GIcon corresponding to the content type. Free the returned object with g_object_unref() a content type string Guesses the content type based on example data. If the function is uncertain, @result_uncertain will be set to %TRUE. Either @filename or @data may be %NULL, in which case the guess will be based solely on the other argument. a string indicating a guessed content type for the given data. Free with g_free() a path, or %NULL a stream of data, or %NULL the size of @data return location for the certainty of the result, or %NULL Tries to guess the type of the tree with root @root, by looking at the files it contains. The result is an array of content types, with the best guess coming first. The types returned all have the form x-content/foo, e.g. x-content/audio-cdda (for audio CDs) or x-content/image-dcf (for a camera memory card). See the [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on x-content types. This function is useful in the implementation of g_mount_guess_content_type(). an %NULL-terminated array of zero or more content types. Free with g_strfreev() the root of the tree to guess a type for Determines if @type is a subset of @supertype. %TRUE if @type is a kind of @supertype, %FALSE otherwise. a content type string a content type string Determines if @type is a subset of @mime_type. Convenience wrapper around g_content_type_is_a(). %TRUE if @type is a kind of @mime_type, %FALSE otherwise. a content type string a mime type string Checks if the content type is the generic "unknown" type. On UNIX this is the "application/octet-stream" mimetype, while on win32 it is "*" and on OSX it is a dynamic type or octet-stream. %TRUE if the type is the unknown type. a content type string Set the list of directories used by GIO to load the MIME database. If @dirs is %NULL, the directories used are the default: - the `mime` subdirectory of the directory in `$XDG_DATA_HOME` - the `mime` subdirectory of every directory in `$XDG_DATA_DIRS` This function is intended to be used when writing tests that depend on information stored in the MIME database, in order to control the data. Typically, in case your tests use %G_TEST_OPTION_ISOLATE_DIRS, but they depend on the system’s MIME database, you should call this function with @dirs set to %NULL before calling g_test_init(), for instance: |[<!-- language="C" --> // Load MIME data from the system g_content_type_set_mime_dirs (NULL); // Isolate the environment g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL); … return g_test_run (); ]| %NULL-terminated list of directories to load MIME data from, including any `mime/` subdirectory, and with the first directory to try listed first Gets a list of strings containing all the registered content types known to the system. The list and its data should be freed using `g_list_free_full (list, g_free)`. list of the registered content types Escape @string so it can appear in a D-Bus address as the value part of a key-value pair. For instance, if @string is `/run/bus-for-:0`, this function would return `/run/bus-for-%3A0`, which could be used in a D-Bus address like `unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0`. a copy of @string with all non-optionally-escaped bytes escaped an unescaped string to be included in a D-Bus address as the value in a key-value pair Synchronously looks up the D-Bus address for the well-known message bus instance specified by @bus_type. This may involve using various platform specific mechanisms. The returned address will be in the [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). a valid D-Bus address string for @bus_type or %NULL if @error is set a #GBusType a #GCancellable or %NULL Asynchronously connects to an endpoint specified by @address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation. @address must be in the [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). When the operation is finished, @callback will be invoked. You can then call g_dbus_address_get_stream_finish() to get the result of the operation. This is an asynchronous failable function. See g_dbus_address_get_stream_sync() for the synchronous version. A valid D-Bus address. A #GCancellable or %NULL. A #GAsyncReadyCallback to call when the request is satisfied. Data to pass to @callback. Finishes an operation started with g_dbus_address_get_stream(). A server is not required to set a GUID, so @out_guid may be set to %NULL even on success. A #GIOStream or %NULL if @error is set. A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream(). %NULL or return location to store the GUID extracted from @address, if any. Synchronously connects to an endpoint specified by @address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation. @address must be in the [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). A server is not required to set a GUID, so @out_guid may be set to %NULL even on success. This is a synchronous failable function. See g_dbus_address_get_stream() for the asynchronous version. A #GIOStream or %NULL if @error is set. A valid D-Bus address. %NULL or return location to store the GUID extracted from @address, if any. A #GCancellable or %NULL. Looks up the value of an annotation. The cost of this function is O(n) in number of annotations. The value or %NULL if not found. Do not free, it is owned by @annotations. A %NULL-terminated array of annotations or %NULL. The name of the annotation to look up. Creates a D-Bus error name to use for @error. If @error matches a registered error (see [func@Gio.DBusError.register_error]), the corresponding D-Bus error name will be returned. Otherwise the a name of the form `org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE` will be used. This allows other GDBus applications to map the error on the wire back to a [type@GLib.Error] using [func@Gio.DBusError.new_for_dbus_error]. This function is typically only used in object mappings to put a [type@GLib.Error] on the wire. Regular applications should not use it. a D-Bus error name an error Gets the D-Bus error name used for @error, if any. This function is guaranteed to return a D-Bus error name for all [type@GLib.Error]s returned from functions handling remote method calls (for example, [method@Gio.DBusConnection.call_finish]) unless [func@Gio.DBusError.strip_remote_error] has already been used on @error. an allocated string, or `NULL` if the D-Bus error name could not be found an error Checks if @error represents an error received via D-Bus from a remote peer. If so, use [func@Gio.DBusError.get_remote_error] to get the name of the error. true if @error represents an error from a remote peer; false otherwise an error Creates a [type@GLib.Error] based on the contents of @dbus_error_name and @dbus_error_message. Errors registered with [func@Gio.DBusError.register_error] will be looked up using @dbus_error_name and if a match is found, the error domain and code is used. Applications can use [func@Gio.DBusError.get_remote_error] to recover @dbus_error_name. If a match against a registered error is not found and the D-Bus error name is in a form as returned by [func@Gio.DBusError.encode_gerror] the error domain and code encoded in the name is used to create the [type@GLib.Error]. Also, @dbus_error_name is added to the error message such that it can be recovered with [func@Gio.DBusError.get_remote_error]. Otherwise, a [type@GLib.Error] with the error code [error@Gio.IOErrorEnum.DBUS_ERROR] in the [error@Gio.IOErrorEnum] error domain is returned. Also, @dbus_error_name is added to the error message such that it can be recovered with [func@Gio.DBusError.get_remote_error]. In all three cases, @dbus_error_name can always be recovered from the returned [type@GLib.Error] using the [func@Gio.DBusError.get_remote_error] function (unless [func@Gio.DBusError.strip_remote_error] hasn’t been used on the returned error). This function is typically only used in object mappings to prepare [type@GLib.Error] instances for applications. Regular applications should not use it. an allocated [type@GLib.Error] D-Bus error name D-Bus error message Creates an association mapping between @dbus_error_name and [type@GLib.Error]s specified by @error_domain and @error_code. This is typically done in the function that returns the [type@GLib.Quark] for an error domain. true if the association was created, false if it already exists a [type@GLib.Quark] for an error domain an error code a D-Bus error name Helper function for associating a [type@GLib.Error] error domain with D-Bus error names. While @quark_volatile has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. the error domain name return location for the [type@GLib.Quark] representing the error domain items to register number of items to register Looks for extra information in the error message used to recover the D-Bus error name and strips it if found. If stripped, the message field in @error will correspond exactly to what was received on the wire. This is typically used when presenting errors to the end user. true if information was stripped; false otherwise an error Destroys an association previously set up with [func@Gio.DBusError.register_error]. true if the association was destroyed, false if it wasn’t found a [type@GLib.Quark] for an error domain an error code a D-Bus error name This is a language binding friendly version of g_dbus_escape_object_path_bytestring(). an escaped version of @s. Free with g_free(). the string to escape Escapes @bytes for use in a D-Bus object path component. @bytes is an array of zero or more nonzero bytes in an unspecified encoding, followed by a single zero byte. The escaping method consists of replacing all non-alphanumeric characters (see g_ascii_isalnum()) with their hexadecimal value preceded by an underscore (`_`). For example: `foo.bar.baz` will become `foo_2ebar_2ebaz`. This method is appropriate to use when the input is nearly a valid object path component but is not when your input is far from being a valid object path component. Other escaping algorithms are also valid to use with D-Bus object paths. This can be reversed with g_dbus_unescape_object_path(). an escaped version of @bytes. Free with g_free(). the string of bytes to escape Generate a D-Bus GUID that can be used with e.g. g_dbus_connection_new(). See the [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#uuids) regarding what strings are valid D-Bus GUIDs. The specification refers to these as ‘UUIDs’ whereas GLib (for historical reasons) refers to them as ‘GUIDs’. The terms are interchangeable. Note that D-Bus GUIDs do not follow [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). A valid D-Bus GUID. Free with g_free(). Converts a #GValue to a #GVariant of the type indicated by the @type parameter. The conversion is using the following rules: - `G_TYPE_STRING`: 's', 'o', 'g' or 'ay' - `G_TYPE_STRV`: 'as', 'ao' or 'aay' - `G_TYPE_BOOLEAN`: 'b' - `G_TYPE_UCHAR`: 'y' - `G_TYPE_INT`: 'i', 'n' - `G_TYPE_UINT`: 'u', 'q' - `G_TYPE_INT64`: 'x' - `G_TYPE_UINT64`: 't' - `G_TYPE_DOUBLE`: 'd' - `G_TYPE_VARIANT`: Any #GVariantType This can fail if e.g. @gvalue is of type %G_TYPE_STRING and @type is 'i', i.e. %G_VARIANT_TYPE_INT32. It will also fail for any #GType (including e.g. %G_TYPE_OBJECT and %G_TYPE_BOXED derived-types) not in the table above. Note that if @gvalue is of type %G_TYPE_VARIANT and its value is %NULL, the empty #GVariant instance (never %NULL) for @type is returned (e.g. 0 for scalar types, the empty string for string types, '/' for object path types, the empty array for any array type and so on). See the g_dbus_gvariant_to_gvalue() function for how to convert a #GVariant to a #GValue. A #GVariant (never floating) of #GVariantType @type holding the data from @gvalue or an empty #GVariant in case of failure. Free with g_variant_unref(). A #GValue to convert to a #GVariant A #GVariantType Converts a #GVariant to a #GValue. If @value is floating, it is consumed. The rules specified in the g_dbus_gvalue_to_gvariant() function are used - this function is essentially its reverse form. So, a #GVariant containing any basic or string array type will be converted to a #GValue containing a basic value or string array. Any other #GVariant (handle, variant, tuple, dict entry) will be converted to a #GValue containing that #GVariant. The conversion never fails - a valid #GValue is always returned in @out_gvalue. A #GVariant. Return location pointing to a zero-filled (uninitialized) #GValue. Checks if @string is a [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). This doesn't check if @string is actually supported by #GDBusServer or #GDBusConnection - use g_dbus_is_supported_address() to do more checks. %TRUE if @string is a valid D-Bus address, %FALSE otherwise. A string. Check whether @string is a valid D-Bus error name. This function returns the same result as g_dbus_is_interface_name(), because D-Bus error names are defined to have exactly the same syntax as interface names. %TRUE if valid, %FALSE otherwise. The string to check. Checks if @string is a D-Bus GUID. See the documentation for g_dbus_generate_guid() for more information about the format of a GUID. %TRUE if @string is a GUID, %FALSE otherwise. The string to check. Checks if @string is a valid D-Bus interface name. %TRUE if valid, %FALSE otherwise. The string to check. Checks if @string is a valid D-Bus member (e.g. signal or method) name. %TRUE if valid, %FALSE otherwise. The string to check. Checks if @string is a valid D-Bus bus name (either unique or well-known). %TRUE if valid, %FALSE otherwise. The string to check. Like g_dbus_is_address() but also checks if the library supports the transports in @string and that key/value pairs for each transport are valid. See the specification of the [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). %TRUE if @string is a valid D-Bus address that is supported by this library, %FALSE if @error is set. A string. Checks if @string is a valid D-Bus unique bus name. %TRUE if valid, %FALSE otherwise. The string to check. Unescapes an string that was previously escaped with g_dbus_escape_object_path(). If the string is in a format that could not have been returned by g_dbus_escape_object_path(), this function returns %NULL. Encoding alphanumeric characters which do not need to be encoded is not allowed (e.g `_63` is not valid, the string should contain `c` instead). an unescaped version of @s, or %NULL if @s is not a string returned from g_dbus_escape_object_path(). Free with g_free(). the string to unescape Creates a new #GDtlsClientConnection wrapping @base_socket which is assumed to communicate with the server identified by @server_identity. the new #GDtlsClientConnection, or %NULL on error the #GDatagramBased to wrap the expected identity of the server Creates a new #GDtlsServerConnection wrapping @base_socket. the new #GDtlsServerConnection, or %NULL on error the #GDatagramBased to wrap the default server certificate, or %NULL Constructs a #GFile from a vector of elements using the correct separator for filenames. Using this function is equivalent to calling g_build_filenamev(), followed by g_file_new_for_path() on the result. a new #GFile %NULL-terminated array of strings containing the path elements. Creates a #GFile with the given argument from the command line. The value of @arg can be either a URI, an absolute path or a relative path resolved relative to the current working directory. This operation never fails, but the returned object might not support any I/O operation if @arg points to a malformed path. Note that on Windows, this function expects its argument to be in UTF-8 -- not the system code page. This means that you should not use this function with string from argv as it is passed to main(). g_win32_get_command_line() will return a UTF-8 version of the commandline. #GApplication also uses UTF-8 but g_application_command_line_create_file_for_arg() may be more useful for you there. It is also always possible to use this function with #GOptionContext arguments of type %G_OPTION_ARG_FILENAME. a new #GFile. Free the returned object with g_object_unref(). a command line string Creates a #GFile with the given argument from the command line. This function is similar to g_file_new_for_commandline_arg() except that it allows for passing the current working directory as an argument instead of using the current working directory of the process. This is useful if the commandline argument was given in a context other than the invocation of the current process. See also g_application_command_line_create_file_for_arg(). a new #GFile a command line string the current working directory of the commandline Constructs a #GFile for a given path. This operation never fails, but the returned object might not support any I/O operation if @path is malformed. a new #GFile for the given @path. Free the returned object with g_object_unref(). a string containing a relative or absolute path. The string must be encoded in the glib filename encoding. Constructs a #GFile for a given URI. This operation never fails, but the returned object might not support any I/O operation if @uri is malformed or if the uri type is not supported. a new #GFile for the given @uri. Free the returned object with g_object_unref(). a UTF-8 string containing a URI Opens a file in the preferred directory for temporary files (as returned by g_get_tmp_dir()) and returns a #GFile and #GFileIOStream pointing to it. @tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is %NULL, a default template is used. Unlike the other #GFile constructors, this will return %NULL if a temporary file could not be created. a new #GFile. Free the returned object with g_object_unref(). Template for the file name, as in g_file_open_tmp(), or %NULL for a default template on return, a #GFileIOStream for the created file Asynchronously opens a file in the preferred directory for temporary files (as returned by g_get_tmp_dir()) as g_file_new_tmp(). @tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is %NULL, a default template is used. Template for the file name, as in g_file_open_tmp(), or %NULL for a default template the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is done data to pass to @callback Asynchronously creates a directory in the preferred directory for temporary files (as returned by g_get_tmp_dir()) as g_dir_make_tmp(). @tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is %NULL, a default template is used. Template for the file name, as in g_dir_make_tmp(), or %NULL for a default template the [I/O priority](iface.AsyncResult.html#io-priority) of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is done data to pass to @callback Finishes a temporary directory creation started by g_file_new_tmp_dir_async(). a new #GFile. Free the returned object with g_object_unref(). a #GAsyncResult Finishes a temporary file creation started by g_file_new_tmp_async(). a new #GFile. Free the returned object with g_object_unref(). a #GAsyncResult on return, a #GFileIOStream for the created file Constructs a #GFile with the given @parse_name (i.e. something given by g_file_get_parse_name()). This operation never fails, but the returned object might not support any I/O operation if the @parse_name cannot be parsed. a new #GFile. a file name or path to be parsed Deserializes a #GIcon previously serialized using g_icon_serialize(). a #GIcon, or %NULL when deserialization fails. a #GVariant created with g_icon_serialize() Generate a #GIcon instance from @str. This function can fail if @str is not valid - see g_icon_to_string() for discussion. If your application or library provides one or more #GIcon implementations you need to ensure that each #GType is registered with the type system prior to calling g_icon_new_for_string(). An object implementing the #GIcon interface or %NULL if @error is set. A string obtained via g_icon_to_string(). Helper function for constructing #GInitable object. This is similar to g_object_newv() but also initializes the object and returns %NULL, setting an error on failure. Use g_object_new_with_properties() and g_initable_init() instead. See #GParameter for more information. a newly allocated #GObject, or %NULL on error a #GType supporting #GInitable. the number of parameters in @parameters the parameters to use to construct the object optional #GCancellable object, %NULL to ignore. Converts `errno.h` error codes into GIO error codes. The fallback value %G_IO_ERROR_FAILED is returned for error codes not currently handled (but note that future GLib releases may return a more specific value instead). As `errno` is global and may be modified by intermediate function calls, you should save its value immediately after the call returns, and use the saved value instead of `errno`: |[<!-- language="C" --> int saved_errno; ret = read (blah); saved_errno = errno; g_io_error_from_errno (saved_errno); ]| #GIOErrorEnum value for the given `errno.h` error number Error number as defined in errno.h. Converts #GFileError error codes into GIO error codes. #GIOErrorEnum value for the given #GFileError error value. a #GFileError. Gets the GIO Error Quark. a #GQuark. Registers @type as extension for the extension point with name @extension_point_name. If @type has already been registered as an extension for this extension point, the existing #GIOExtension object is returned. a #GIOExtension object for #GType the name of the extension point the #GType to register as extension the name for the extension the priority for the extension Looks up an existing extension point. the #GIOExtensionPoint, or %NULL if there is no registered extension point with the given name. the name of the extension point Registers an extension point. the new #GIOExtensionPoint. This object is owned by GIO and should not be freed. The name of the extension point Loads all the modules in the specified directory. If don't require all modules to be initialized (and thus registering all gtypes) then you can use g_io_modules_scan_all_in_directory() which allows delayed/lazy loading of modules. a list of #GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call g_type_module_unuse() on all the modules. Free the list with g_list_free(). pathname for a directory containing modules to load. Loads all the modules in the specified directory. If don't require all modules to be initialized (and thus registering all gtypes) then you can use g_io_modules_scan_all_in_directory() which allows delayed/lazy loading of modules. a list of #GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call g_type_module_unuse() on all the modules. Free the list with g_list_free(). pathname for a directory containing modules to load. a scope to use when scanning the modules. Scans all the modules in the specified directory, ensuring that any extension point implemented by a module is registered. This may not actually load and initialize all the types in each module, some modules may be lazily loaded and initialized when an extension point it implements is used with e.g. g_io_extension_point_get_extensions() or g_io_extension_point_get_extension_by_name(). If you need to guarantee that all types are loaded in all the modules, use g_io_modules_load_all_in_directory(). pathname for a directory containing modules to scan. Scans all the modules in the specified directory, ensuring that any extension point implemented by a module is registered. This may not actually load and initialize all the types in each module, some modules may be lazily loaded and initialized when an extension point it implements is used with e.g. g_io_extension_point_get_extensions() or g_io_extension_point_get_extension_by_name(). If you need to guarantee that all types are loaded in all the modules, use g_io_modules_load_all_in_directory(). pathname for a directory containing modules to scan. a scope to use when scanning the modules Cancels all cancellable I/O jobs. A job is cancellable if a #GCancellable was passed into g_io_scheduler_push_job(). You should never call this function, since you don't know how other libraries in your program might be making use of gioscheduler. Schedules the I/O job to run in another thread. @notify will be called on @user_data after @job_func has returned, regardless whether the job was cancelled or has run to completion. If @cancellable is not %NULL, it can be used to cancel the I/O job by calling g_cancellable_cancel() or by calling g_io_scheduler_cancel_all_jobs(). use #GThreadPool or g_task_run_in_thread() a #GIOSchedulerJobFunc. data to pass to @job_func a #GDestroyNotify for @user_data, or %NULL the [I/O priority](iface.AsyncResult.html#io-priority) of the request. optional #GCancellable object, %NULL to ignore. Creates a keyfile-backed [class@Gio.SettingsBackend]. The filename of the keyfile to use is given by @filename. All settings read to or written from the backend must fall under the path given in @root_path (which must start and end with a slash and not contain two consecutive slashes). @root_path may be `"/"`. If @root_group is non-`NULL` then it specifies the name of the keyfile group used for keys that are written directly below @root_path. For example, if @root_path is `"/apps/example/"` and @root_group is `"toplevel"`, then setting the key `"/apps/example/enabled"` to true will cause the following to appear in the keyfile: ``` [toplevel] enabled=true ``` If @root_group is `NULL` then it is not permitted to store keys directly below the @root_path. For keys not stored directly below @root_path (ie: in a sub-path), the name of the subpath (with the final slash stripped) is used as the name of the keyfile group. To continue the example, if `"/apps/example/profiles/default/font-size"` were set to `12` then the following would appear in the keyfile: ``` [profiles/default] font-size=12 ``` The backend will refuse writes (and return writability as being false) for keys outside of @root_path and, in the event that @root_group is `NULL`, also for keys directly under @root_path. Writes will also be refused if the backend detects that it has the inability to rewrite the keyfile (ie: the containing directory is not writable). There is no checking done for your key namespace clashing with the syntax of the key file format. For example, if you have `[` or `]` characters in your path names or `=` in your key names you may be in trouble. The backend reads default values from a keyfile called `defaults` in the directory specified by the `GKeyfileSettingsBackend:defaults-dir` property, and a list of locked keys from a text file with the name `locks` in the same location. a keyfile-backed [class@Gio.SettingsBackend] the filename of the keyfile the path under which all settings keys appear the group name corresponding to @root_path, or `NULL` to disallow storing keys directly beneath @root_path Gets a reference to the default #GMemoryMonitor for the system. a new reference to the default #GMemoryMonitor Creates a memory-backed #GSettingsBackend. This backend allows changes to settings, but does not write them to any backing storage, so the next time you run your application, the memory backend will start out with the default values again. a newly created #GSettingsBackend Gets the default #GNetworkMonitor for the system. a #GNetworkMonitor, which will be a dummy object if no network monitor is available Initializes the platform networking libraries (eg, on Windows, this calls WSAStartup()). GLib will call this itself if it is needed, so you only need to call it if you directly call system networking functions (without calling any GLib networking functions first). Creates a readonly #GSettingsBackend. This backend does not allow changes to settings, so all settings will always have their default values. a newly created #GSettingsBackend Utility method for #GPollableInputStream and #GPollableOutputStream implementations. Creates a new #GSource that expects a callback of type #GPollableSourceFunc. The new source does not actually do anything on its own; use g_source_add_child_source() to add other sources to it to cause it to trigger. the new #GSource. the stream associated with the new source Utility method for #GPollableInputStream and #GPollableOutputStream implementations. Creates a new #GSource, as with g_pollable_source_new(), but also attaching @child_source (with a dummy callback), and @cancellable, if they are non-%NULL. the new #GSource. the stream associated with the new source optional child source to attach optional #GCancellable to attach Tries to read from @stream, as with g_input_stream_read() (if @blocking is %TRUE) or g_pollable_input_stream_read_nonblocking() (if @blocking is %FALSE). This can be used to more easily share code between blocking and non-blocking implementations of a method. If @blocking is %FALSE, then @stream must be a #GPollableInputStream for which g_pollable_input_stream_can_poll() returns %TRUE, or else the behavior is undefined. If @blocking is %TRUE, then @stream does not need to be a #GPollableInputStream. the number of bytes read, or -1 on error. a #GInputStream a buffer to read data into the number of bytes to read whether to do blocking I/O optional #GCancellable object, %NULL to ignore. Tries to write to @stream, as with g_output_stream_write() (if @blocking is %TRUE) or g_pollable_output_stream_write_nonblocking() (if @blocking is %FALSE). This can be used to more easily share code between blocking and non-blocking implementations of a method. If @blocking is %FALSE, then @stream must be a #GPollableOutputStream for which g_pollable_output_stream_can_poll() returns %TRUE or else the behavior is undefined. If @blocking is %TRUE, then @stream does not need to be a #GPollableOutputStream. the number of bytes written, or -1 on error. a #GOutputStream. the buffer containing the data to write. the number of bytes to write whether to do blocking I/O optional #GCancellable object, %NULL to ignore. Tries to write @count bytes to @stream, as with g_output_stream_write_all(), but using g_pollable_stream_write() rather than g_output_stream_write(). On a successful write of @count bytes, %TRUE is returned, and @bytes_written is set to @count. If there is an error during the operation (including %G_IO_ERROR_WOULD_BLOCK in the non-blocking case), %FALSE is returned and @error is set to indicate the error status, @bytes_written is updated to contain the number of bytes written into the stream before the error occurred. As with g_pollable_stream_write(), if @blocking is %FALSE, then @stream must be a #GPollableOutputStream for which g_pollable_output_stream_can_poll() returns %TRUE or else the behavior is undefined. If @blocking is %TRUE, then @stream does not need to be a #GPollableOutputStream. %TRUE on success, %FALSE if there was an error a #GOutputStream. the buffer containing the data to write. the number of bytes to write whether to do blocking I/O location to store the number of bytes that was written to the stream optional #GCancellable object, %NULL to ignore. Gets a reference to the default #GPowerProfileMonitor for the system. a new reference to the default #GPowerProfileMonitor Find the `gio-proxy` extension point for a proxy implementation that supports the specified protocol. return a #GProxy or NULL if protocol is not supported. the proxy protocol name (e.g. http, socks, etc) Gets the default #GProxyResolver for the system. the default #GProxyResolver, which will be a dummy object if no proxy resolver is available Gets the #GResolver Error Quark. a #GQuark. Gets the [struct@Gio.Resource] Error Quark. a [type@GLib.Quark] Loads a binary resource bundle and creates a [struct@Gio.Resource] representation of it, allowing you to query it for data. If you want to use this resource in the global resource namespace you need to register it with [func@Gio.resources_register]. If @filename is empty or the data in it is corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or there is an error in reading it, an error from [ctor@GLib.MappedFile.new] will be returned. a new [struct@Gio.Resource], or `NULL` on error the path of a filename to load, in the GLib filename encoding Returns all the names of children at the specified @path in the set of globally registered resources. The return result is a `NULL` terminated list of strings which should be released with [func@GLib.strfreev]. @lookup_flags controls the behaviour of the lookup. an array of constant strings A path name inside the resource A [flags@Gio.ResourceLookupFlags] Looks for a file at the specified @path in the set of globally registered resources and if found returns information about it. @lookup_flags controls the behaviour of the lookup. `TRUE` if the file was found, `FALSE` if there were errors A path name inside the resource A [flags@Gio.ResourceLookupFlags] a location to place the length of the contents of the file, or `NULL` if the length is not needed a location to place the [flags@Gio.ResourceFlags] about the file, or `NULL` if the flags are not needed Returns whether the specified @path in the set of globally registered resources has children. %TRUE if @patch has children A pathname Looks for a file at the specified @path in the set of globally registered resources and returns a [struct@GLib.Bytes] that lets you directly access the data in memory. The data is always followed by a zero byte, so you can safely use the data as a C string. However, that byte is not included in the size of the [struct@GLib.Bytes]. For uncompressed resource files this is a pointer directly into the resource bundle, which is typically in some read-only data section in the program binary. For compressed files we allocate memory on the heap and automatically uncompress the data. @lookup_flags controls the behaviour of the lookup. [struct@GLib.Bytes] or `NULL` on error A path name inside the resource A [flags@Gio.ResourceLookupFlags] Looks for a file at the specified @path in the set of globally registered resources and returns a [class@Gio.InputStream] that lets you read the data. @lookup_flags controls the behaviour of the lookup. [class@Gio.InputStream] or `NULL` on error A path name inside the resource A [flags@Gio.ResourceLookupFlags] Registers the resource with the process-global set of resources. Once a resource is registered the files in it can be accessed with the global resource lookup functions like [func@Gio.resources_lookup_data]. A [struct@Gio.Resource] Unregisters the resource from the process-global set of resources. A [struct@Gio.Resource] Gets the default system schema source. This function is not required for normal uses of #GSettings but it may be useful to authors of plugin management systems or to those who want to introspect the content of schemas. If no schemas are installed, %NULL will be returned. The returned source may actually consist of multiple schema sources from different directories, depending on which directories were given in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all lookups performed against the default source should probably be done recursively. the default schema source Reports an error in an asynchronous function in an idle function by directly setting the contents of the #GAsyncResult with the given error information. Use g_task_report_error(). a #GObject, or %NULL. a #GAsyncReadyCallback. user data passed to @callback. a #GQuark containing the error domain (usually %G_IO_ERROR). a specific error code. a formatted error reporting string. a list of variables to fill in @format. Reports an error in an idle function. Similar to g_simple_async_report_error_in_idle(), but takes a #GError rather than building a new one. Use g_task_report_error(). a #GObject, or %NULL a #GAsyncReadyCallback. user data passed to @callback. the #GError to report Reports an error in an idle function. Similar to g_simple_async_report_gerror_in_idle(), but takes over the caller's ownership of @error, so the caller does not have to free it any more. Use g_task_report_error(). a #GObject, or %NULL a #GAsyncReadyCallback. user data passed to @callback. the #GError to report Sorts @targets in place according to the algorithm in RFC 2782. the head of the sorted list. a #GList of #GSrvTarget Gets the default #GTlsBackend for the system. a #GTlsBackend, which will be a dummy object if no TLS backend is available Gets the TLS channel binding error quark. a #GQuark. Creates a new #GTlsClientConnection wrapping @base_io_stream (which must have pollable input and output streams) which is assumed to communicate with the server identified by @server_identity. See the documentation for #GTlsConnection:base-io-stream for restrictions on when application code can run operations on the @base_io_stream after this function has returned. the new #GTlsClientConnection, or %NULL on error the #GIOStream to wrap the expected identity of the server Gets the TLS error quark. a #GQuark. Creates a new #GTlsFileDatabase which uses anchor certificate authorities in @anchors to verify certificate chains. The certificates in @anchors must be PEM encoded. the new #GTlsFileDatabase, or %NULL on error filename of anchor certificate authorities. Creates a new #GTlsServerConnection wrapping @base_io_stream (which must have pollable input and output streams). See the documentation for #GTlsConnection:base-io-stream for restrictions on when application code can run operations on the @base_io_stream after this function has returned. the new #GTlsServerConnection, or %NULL on error the #GIOStream to wrap the default server certificate, or %NULL soup3-0.9.0/gir-files/GioUnix-2.0.gir000064400000000000000000004057451046102023000151650ustar 00000000000000 Extension point for default handler to URI association. See [Extending GIO](overview.html#extending-gio). The #GDesktopAppInfoLookup interface is deprecated and unused by GIO. `GDesktopAppInfo` is an implementation of [iface@Gio.AppInfo] based on desktop files. Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file or the `GioUnix-2.0` GIR namespace when using it. Creates a new [class@GioUnix.DesktopAppInfo] based on a desktop file ID. A desktop file ID is the basename of the desktop file, including the `.desktop` extension. GIO is looking for a desktop file with this name in the `applications` subdirectories of the XDG data directories (i.e. the directories specified in the `XDG_DATA_HOME` and `XDG_DATA_DIRS` environment variables). GIO also supports the prefix-to-subdirectory mapping that is described in the [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/) (i.e. a desktop ID of `kde-foo.desktop` will match `/usr/share/applications/kde/foo.desktop`). a new [class@GioUnix.DesktopAppInfo], or `NULL` if no desktop file with that ID exists. the desktop file ID Creates a new [class@GioUnix.DesktopAppInfo]. a new [class@GioUnix.DesktopAppInfo] or `NULL` on error. the path of a desktop file, in the GLib filename encoding Creates a new [class@GioUnix.DesktopAppInfo]. a new [class@GioUnix.DesktopAppInfo] or `NULL` on error. an opened [type@GLib.KeyFile] Gets all applications that implement @interface. An application implements an interface if that interface is listed in the `Implements` line of the desktop file of the application. a list of [class@GioUnix.DesktopAppInfo] objects. the name of the interface Searches desktop files for ones that match @search_string. The return value is an array of strvs. Each strv contains a list of applications that matched @search_string with an equal score. The outer list is sorted by score so that the first strv contains the best-matching applications, and so on. The algorithm for determining matches is undefined and may change at any time. None of the search results are subjected to the normal validation checks performed by [ctor@GioUnix.DesktopAppInfo.new] (for example, checking that the executable referenced by a result exists), and so it is possible for [ctor@GioUnix.DesktopAppInfo.new] to return `NULL` when passed an app ID returned by this function. It is expected that calling code will do this when subsequently creating a [class@GioUnix.DesktopAppInfo] for each result. a list of strvs. Free each item with [func@GLib.strfreev] and free the outer list with [func@GLib.free]. the search string to use Sets the name of the desktop that the application is running in. This is used by [method@Gio.AppInfo.should_show] and [method@GioUnix.DesktopAppInfo.get_show_in] to evaluate the [`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) and [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin) keys. Should be called only once; subsequent calls are ignored. do not use this API. Since 2.42 the value of the `XDG_CURRENT_DESKTOP` environment variable will be used. a string specifying what desktop this is Gets the user-visible display name of the [‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html) specified by @action_name. This corresponds to the `Name` key within the keyfile group for the action. the locale-specific action name a [class@GioUnix.DesktopAppInfo] the name of the action as from [method@GioUnix.DesktopAppInfo.list_actions] Looks up a boolean value in the keyfile backing @info. The @key is looked up in the `Desktop Entry` group. the boolean value, or `FALSE` if the key is not found a [class@GioUnix.DesktopAppInfo] the key to look up Gets the categories from the desktop file. The unparsed [`Categories` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-categories) from the desktop file; i.e. no attempt is made to split it by `;` or validate it. a [class@GioUnix.DesktopAppInfo] When @info was created from a known filename, return it. In some situations such as a [class@GioUnix.DesktopAppInfo] returned from [ctor@GioUnix.DesktopAppInfo.new_from_keyfile], this function will return `NULL`. The full path to the file for @info, or `NULL` if not known. a [class@GioUnix.DesktopAppInfo] Gets the generic name from the desktop file. The value of the [`GenericName` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-genericname) a [class@GioUnix.DesktopAppInfo] A desktop file is hidden if the [`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) in it is set to `True`. `TRUE` if hidden, `FALSE` otherwise. a [class@GioUnix.DesktopAppInfo]. Gets the keywords from the desktop file. The value of the [`Keywords` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-keywords) a [class@GioUnix.DesktopAppInfo] Looks up a localized string value in the keyfile backing @info translated to the current locale. The @key is looked up in the `Desktop Entry` group. a newly allocated string, or `NULL` if the key is not found a [class@GioUnix.DesktopAppInfo] the key to look up Gets the value of the [`NoDisplay` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) which helps determine if the application info should be shown in menus. See `G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY` and [method@Gio.AppInfo.should_show]. The value of the `NoDisplay` key a [class@GioUnix.DesktopAppInfo] Checks if the application info should be shown in menus that list available applications for a specific name of the desktop, based on the [`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) and [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin) keys. @desktop_env should typically be given as `NULL`, in which case the `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want to override the default mechanism then you may specify @desktop_env, but this is not recommended. Note that [method@Gio.AppInfo.should_show] for @info will include this check (with `NULL` for @desktop_env) as well as additional checks. `TRUE` if the @info should be shown in @desktop_env according to the `OnlyShowIn` and `NotShowIn` keys, `FALSE` otherwise. a [class@GioUnix.DesktopAppInfo] a string specifying a desktop name Retrieves the `StartupWMClass` field from @info. This represents the `WM_CLASS` property of the main window of the application, if launched through @info. the startup WM class, or `NULL` if none is set in the desktop file. a [class@GioUnix.DesktopAppInfo] that supports startup notify Looks up a string value in the keyfile backing @info. The @key is looked up in the `Desktop Entry` group. a newly allocated string, or `NULL` if the key is not found a [class@GioUnix.DesktopAppInfo] the key to look up Looks up a string list value in the keyfile backing @info. The @key is looked up in the `Desktop Entry` group. a `NULL`-terminated string array or `NULL` if the specified key cannot be found. The array should be freed with [func@GLib.strfreev]. a [class@GioUnix.DesktopAppInfo] the key to look up return location for the number of returned strings, or `NULL` Returns whether @key exists in the `Desktop Entry` group of the keyfile backing @info. `TRUE` if the @key exists a [class@GioUnix.DesktopAppInfo] the key to look up Activates the named application action. You may only call this function on action names that were returned from [method@GioUnix.DesktopAppInfo.list_actions]. Note that if the main entry of the desktop file indicates that the application supports startup notification, and @launch_context is non-`NULL`, then startup notification will be used when activating the action (and as such, invocation of the action on the receiving side must signal the end of startup notification when it is completed). This is the expected behaviour of applications declaring additional actions, as per the [desktop file specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html). As with [method@Gio.AppInfo.launch] there is no way to detect failures that occur while using this function. a [class@GioUnix.DesktopAppInfo] the name of the action as from [method@GioUnix.DesktopAppInfo.list_actions] a [class@Gio.AppLaunchContext] This function performs the equivalent of [method@Gio.AppInfo.launch_uris], but is intended primarily for operating system components that launch applications. Ordinary applications should use [method@Gio.AppInfo.launch_uris]. If the application is launched via GSpawn, then @spawn_flags, @user_setup and @user_setup_data are used for the call to [func@GLib.spawn_async]. Additionally, @pid_callback (with @pid_callback_data) will be called to inform about the PID of the created process. See [func@GLib.spawn_async_with_pipes] for information on certain parameter conditions that can enable an optimized [`posix_spawn()`](man:posix_spawn(3)) code path to be used. If application launching occurs via some other mechanism (for example, D-Bus activation) then @spawn_flags, @user_setup, @user_setup_data, @pid_callback and @pid_callback_data are ignored. `TRUE` on successful launch, `FALSE` otherwise. a [class@GioUnix.DesktopAppInfo] List of URIs a [class@Gio.AppLaunchContext] [flags@GLib.SpawnFlags], used for each process a [callback@GLib.SpawnChildSetupFunc], used once for each process. User data for @user_setup Callback for child processes User data for @callback Equivalent to [method@GioUnix.DesktopAppInfo.launch_uris_as_manager] but allows you to pass in file descriptors for the stdin, stdout and stderr streams of the launched process. If application launching occurs via some non-spawn mechanism (e.g. D-Bus activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. `TRUE` on successful launch, `FALSE` otherwise. a [class@GioUnix.DesktopAppInfo] List of URIs a [class@Gio.AppLaunchContext] [flags@GLib.SpawnFlags], used for each process a [callback@GLib.SpawnChildSetupFunc], used once for each process. User data for @user_setup Callback for child processes User data for @callback file descriptor to use for child’s stdin, or `-1` file descriptor to use for child’s stdout, or `-1` file descriptor to use for child’s stderr, or `-1` Returns the list of [‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html) supported on the desktop file, as per the desktop file specification. As per the specification, this is the list of actions that are explicitly listed in the `Actions` key of the `Desktop Entry` group. a list of strings, always non-`NULL` a [class@GioUnix.DesktopAppInfo] The origin filename of this [class@GioUnix.DesktopAppInfo] #GDesktopAppInfoLookup is an opaque data structure and can only be accessed using the following functions. The [iface@GioUnix.DesktopAppInfoLookup] interface is deprecated and unused by GIO. Gets the default application for launching applications using this URI scheme for a particular [iface@GioUnix.DesktopAppInfoLookup] implementation. The [iface@GioUnix.DesktopAppInfoLookup] interface and this function is used to implement [func@Gio.AppInfo.get_default_for_uri_scheme] backends in a GIO module. There is no reason for applications to use it directly. Applications should use [func@Gio.AppInfo.get_default_for_uri_scheme]. The [iface@GioUnix.DesktopAppInfoLookup] interface is deprecated and unused by GIO. [iface@Gio.AppInfo] for given @uri_scheme or `NULL` on error. a [iface@GioUnix.DesktopAppInfoLookup] a string containing a URI scheme. Gets the default application for launching applications using this URI scheme for a particular [iface@GioUnix.DesktopAppInfoLookup] implementation. The [iface@GioUnix.DesktopAppInfoLookup] interface and this function is used to implement [func@Gio.AppInfo.get_default_for_uri_scheme] backends in a GIO module. There is no reason for applications to use it directly. Applications should use [func@Gio.AppInfo.get_default_for_uri_scheme]. The [iface@GioUnix.DesktopAppInfoLookup] interface is deprecated and unused by GIO. [iface@Gio.AppInfo] for given @uri_scheme or `NULL` on error. a [iface@GioUnix.DesktopAppInfoLookup] a string containing a URI scheme. Interface that is used by backends to associate default handlers with URI schemes. Virtual method for g_desktop_app_info_lookup_get_default_for_uri_scheme(). [iface@Gio.AppInfo] for given @uri_scheme or `NULL` on error. a [iface@GioUnix.DesktopAppInfoLookup] a string containing a URI scheme. During invocation, g_desktop_app_info_launch_uris_as_manager() may create one or more child processes. This callback is invoked once for each, providing the process ID. a #GDesktopAppInfo Process identifier User data This [class@Gio.SocketControlMessage] contains a [class@Gio.UnixFDList]. It may be sent using [method@Gio.Socket.send_message] and received using [method@Gio.Socket.receive_message] over UNIX sockets (ie: sockets in the `G_SOCKET_FAMILY_UNIX` family). The file descriptors are copied between processes by the kernel. For an easier way to send and receive file descriptors over stream-oriented UNIX sockets, see [method@Gio.UnixConnection.send_fd] and [method@Gio.UnixConnection.receive_fd]. Note that `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file or the `GioUnix-2.0` GIR namespace when using it. Creates a new #GUnixFDMessage containing an empty file descriptor list. a new #GUnixFDMessage Creates a new #GUnixFDMessage containing @list. a new #GUnixFDMessage a #GUnixFDList Adds a file descriptor to @message. The file descriptor is duplicated using dup(). You keep your copy of the descriptor and the copy contained in @message will be closed when @message is finalized. A possible cause of failure is exceeding the per-process or system-wide file descriptor limit. %TRUE in case of success, else %FALSE (and @error is set) a #GUnixFDMessage a valid open file descriptor Gets the #GUnixFDList contained in @message. This function does not return a reference to the caller, but the returned list is valid for the lifetime of @message. the #GUnixFDList from @message a #GUnixFDMessage Returns the array of file descriptors that is contained in this object. After this call, the descriptors are no longer contained in @message. Further calls will return an empty list (unless more descriptors have been added). The return result of this function must be freed with g_free(). The caller is also responsible for closing all of the file descriptors. If @length is non-%NULL then it is set to the number of file descriptors in the returned array. The returned array is also terminated with -1. This function never returns %NULL. In case there are no file descriptors contained in @message, an empty array is returned. an array of file descriptors a #GUnixFDMessage pointer to the length of the returned array, or %NULL The [class@Gio.UnixFDList] object to send with the message. `GFileDescriptorBased` is an interface for file descriptor based IO. It is implemented by streams (implementations of [class@Gio.InputStream] or [class@Gio.OutputStream]) that are based on file descriptors. Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file or the `GioUnix-2.0` GIR namespace when using it. Gets the underlying file descriptor. The file descriptor a #GFileDescriptorBased. Gets the underlying file descriptor. The file descriptor a #GFileDescriptorBased. An interface for file descriptor based io objects. The parent interface. Gets the underlying file descriptor. The file descriptor a #GFileDescriptorBased. `GUnixInputStream` implements [class@Gio.InputStream] for reading from a UNIX file descriptor, including asynchronous operations. (If the file descriptor refers to a socket or pipe, this will use `poll()` to do asynchronous I/O. If it refers to a regular file, it will fall back to doing asynchronous I/O in another thread.) Note that `<gio/gunixinputstream.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file or the `GioUnix-2.0` GIR namespace when using it. Creates a new #GUnixInputStream for the given @fd. If @close_fd is %TRUE, the file descriptor will be closed when the stream is closed. a new #GUnixInputStream a UNIX file descriptor %TRUE to close the file descriptor when done Returns whether the file descriptor of @stream will be closed when the stream is closed. %TRUE if the file descriptor is closed when done a #GUnixInputStream Return the UNIX file descriptor that the stream reads from. The file descriptor of @stream a #GUnixInputStream Sets whether the file descriptor of @stream shall be closed when the stream is closed. a #GUnixInputStream %TRUE to close the file descriptor when done Whether to close the file descriptor when the stream is closed. The file descriptor that the stream reads from. Defines a Unix mount entry (e.g. `/media/cdrom`). This corresponds roughly to a mtab entry. Compares two Unix mounts. `1`, `0` or `-1` if @mount1 is greater than, equal to, or less than @mount2, respectively first [struct@GioUnix.MountEntry] to compare second [struct@GioUnix.MountEntry] to compare Makes a copy of @mount_entry. a new [struct@GioUnix.MountEntry] a [struct@GioUnix.MountEntry] Frees a Unix mount. a [struct@GioUnix.MountEntry] Gets the device path for a Unix mount. a string containing the device path a [struct@GioUnix.MountEntry] Gets the filesystem type for the Unix mount. a string containing the file system type a [struct@GioUnix.MountEntry] Gets the mount path for a Unix mount. the mount path for @mount_entry a [struct@GioUnix.MountEntry] to get the mount path for Gets a comma separated list of mount options for the Unix mount. For example: `rw,relatime,seclabel,data=ordered`. This is similar to [method@GioUnix.MountPoint.get_options], but it takes a [struct@GioUnix.MountEntry] as an argument. a string containing the options, or `NULL` if not available. a [struct@GioUnix.MountEntry] Gets the root of the mount within the filesystem. This is useful e.g. for mounts created by bind operation, or btrfs subvolumes. For example, the root path is equal to `/` for a mount created by `mount /dev/sda1 /mnt/foo` and `/bar` for `mount --bind /mnt/foo/bar /mnt/bar`. a string containing the root, or `NULL` if not supported a [struct@GioUnix.MountEntry] Guesses whether a Unix mount entry can be ejected. true if @mount_entry is deemed to be ejectable; false otherwise a [struct@GioUnix.MountEntry] Guesses the icon of a Unix mount entry. a [iface@Gio.Icon] a [struct@GioUnix.MountEntry] Guesses the name of a Unix mount entry. The result is a translated string. a newly allocated translated string a [struct@GioUnix.MountEntry] Guesses whether a Unix mount entry should be displayed in the UI. true if @mount_entry is deemed to be displayable; false otherwise a [struct@GioUnix.MountEntry] Guesses the symbolic icon of a Unix mount entry. a [iface@Gio.Icon] a [struct@GioUnix.MountEntry] Checks if a Unix mount is mounted read only. true if @mount_entry is read only; false otherwise a [struct@GioUnix.MountEntry] Checks if a Unix mount is a system mount. This is the Boolean OR of [func@GioUnix.is_system_fs_type], [func@GioUnix.is_system_device_path] and [func@GioUnix.is_mount_path_system_internal] on @mount_entry’s properties. The definition of what a ‘system’ mount entry is may change over time as new file system types and device paths are ignored. true if the Unix mount is for a system path; false otherwise a [struct@GioUnix.MountEntry] Gets a [struct@GioUnix.MountEntry] for a given mount path. If @time_read is set, it will be filled with a Unix timestamp for checking if the mounts have changed since with [func@GioUnix.mount_entries_changed_since]. If more mounts have the same mount path, the last matching mount is returned. This will return `NULL` if there is no mount point at @mount_path. a [struct@GioUnix.MountEntry] path for a possible Unix mount return location for a timestamp Gets a [struct@GioUnix.MountEntry] for a given file path. If @time_read is set, it will be filled with a Unix timestamp for checking if the mounts have changed since with [func@GioUnix.mount_entries_changed_since]. If more mounts have the same mount path, the last matching mount is returned. This will return `NULL` if looking up the mount entry fails, if @file_path doesn’t exist or there is an I/O error. a [struct@GioUnix.MountEntry] file path on some Unix mount return location for a timestamp Watches for changes to the set of mount entries and mount points in the system. Connect to the [signal@GioUnix.MountMonitor::mounts-changed] signal to be notified of changes to the [struct@GioUnix.MountEntry] list. Connect to the [signal@GioUnix.MountMonitor::mountpoints-changed] signal to be notified of changes to the [struct@GioUnix.MountPoint] list. Deprecated alias for [func@GioUnix.MountMonitor.get]. This function was never a true constructor, which is why it was renamed. Use [func@GioUnix.MountMonitor.get] instead. a [class@GioUnix.MountMonitor] Gets the [class@GioUnix.MountMonitor] for the current thread-default main context. The mount monitor can be used to monitor for changes to the list of mounted filesystems as well as the list of mount points (ie: fstab entries). You must only call [method@GObject.Object.unref] on the return value from under the same main context as you called this function. the [class@GioUnix.MountMonitor] This function does nothing. Before 2.44, this was a partially-effective way of controlling the rate at which events would be reported under some uncommon circumstances. Since @mount_monitor is a singleton, it also meant that calling this function would have side effects for other users of the monitor. This function does nothing. Don’t call it. a [class@GioUnix.MountMonitor] a integer with the limit (in milliseconds) to poll for changes Emitted when the Unix mount points have changed. Emitted when the Unix mount entries have changed. Defines a Unix mount point (e.g. `/dev`). This corresponds roughly to a fstab entry. Compares two Unix mount points. `1`, `0` or `-1` if @mount1 is greater than, equal to, or less than @mount2, respectively a [struct@GioUnix.MountPoint] a [struct@GioUnix.MountPoint] Makes a copy of @mount_point. a new [struct@GioUnix.MountPoint] a [struct@GioUnix.MountPoint] Frees a Unix mount point. Unix mount point to free. Gets the device path for a Unix mount point. a string containing the device path a [struct@GioUnix.MountPoint] Gets the file system type for the mount point. a string containing the file system type a [struct@GioUnix.MountPoint] Gets the mount path for a Unix mount point. a string containing the mount path a [struct@GioUnix.MountPoint] Gets the options for the mount point. a string containing the options a [struct@GioUnix.MountPoint] Guesses whether a Unix mount point can be ejected. true if @mount_point is deemed to be ejectable; false otherwise a [struct@GioUnix.MountPoint] Guesses the icon of a Unix mount point. a [iface@Gio.Icon] a [struct@GioUnix.MountPoint] Guesses the name of a Unix mount point. The result is a translated string. a newly allocated translated string a [struct@GioUnix.MountPoint] Guesses the symbolic icon of a Unix mount point. a [iface@Gio.Icon] a [struct@GioUnix.MountPoint] Checks if a Unix mount point is a loopback device. true if the mount point is a loopback device; false otherwise a [struct@GioUnix.MountPoint] Checks if a Unix mount point is read only. true if a mount point is read only; false otherwise a [struct@GioUnix.MountPoint] Checks if a Unix mount point is mountable by the user. true if the mount point is user mountable; false otherwise a [struct@GioUnix.MountPoint] Gets a [struct@GioUnix.MountPoint] for a given mount path. If @time_read is set, it will be filled with a Unix timestamp for checking if the mount points have changed since with [func@GioUnix.mount_points_changed_since]. If more mount points have the same mount path, the last matching mount point is returned. a [struct@GioUnix.MountPoint], or `NULL` if no match is found path for a possible Unix mount point return location for a timestamp `GUnixOutputStream` implements [class@Gio.OutputStream] for writing to a UNIX file descriptor, including asynchronous operations. (If the file descriptor refers to a socket or pipe, this will use `poll()` to do asynchronous I/O. If it refers to a regular file, it will fall back to doing asynchronous I/O in another thread.) Note that `<gio/gunixoutputstream.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file file or the `GioUnix-2.0` GIR namespace when using it. Creates a new #GUnixOutputStream for the given @fd. If @close_fd, is %TRUE, the file descriptor will be closed when the output stream is destroyed. a new #GOutputStream a UNIX file descriptor %TRUE to close the file descriptor when done Returns whether the file descriptor of @stream will be closed when the stream is closed. %TRUE if the file descriptor is closed when done a #GUnixOutputStream Return the UNIX file descriptor that the stream writes to. The file descriptor of @stream a #GUnixOutputStream Sets whether the file descriptor of @stream shall be closed when the stream is closed. a #GUnixOutputStream %TRUE to close the file descriptor when done Whether to close the file descriptor when the stream is closed. The file descriptor that the stream writes to. Determines if @mount_path is considered an implementation of the OS. This is primarily used for hiding mountable and mounted volumes that only are used in the OS and has little to no relevance to the casual user. true if @mount_path is considered an implementation detail of the OS; false otherwise a mount path, e.g. `/media/disk` or `/usr` Determines if @device_path is considered a block device path which is only used in implementation of the OS. This is primarily used for hiding mounted volumes that are intended as APIs for programs to read, and system administrators at a shell; rather than something that should, for example, appear in a GUI. For example, the Linux `/proc` filesystem. The list of device paths considered ‘system’ ones may change over time. true if @device_path is considered an implementation detail of the OS; false otherwise a device path, e.g. `/dev/loop0` or `nfsd` Determines if @fs_type is considered a type of file system which is only used in implementation of the OS. This is primarily used for hiding mounted volumes that are intended as APIs for programs to read, and system administrators at a shell; rather than something that should, for example, appear in a GUI. For example, the Linux `/proc` filesystem. The list of file system types considered ‘system’ ones may change over time. true if @fs_type is considered an implementation detail of the OS; false otherwise a file system type, e.g. `procfs` or `tmpfs` Gets a [struct@GioUnix.MountEntry] for a given mount path. If @time_read is set, it will be filled with a Unix timestamp for checking if the mounts have changed since with [func@GioUnix.mount_entries_changed_since]. If more mounts have the same mount path, the last matching mount is returned. This will return `NULL` if there is no mount point at @mount_path. Use [func@GioUnix.MountEntry.at] instead. a [struct@GioUnix.MountEntry] path for a possible Unix mount return location for a timestamp Compares two Unix mounts. Use [method@GioUnix.MountEntry.compare] instead. `1`, `0` or `-1` if @mount1 is greater than, equal to, or less than @mount2, respectively first [struct@GioUnix.MountEntry] to compare second [struct@GioUnix.MountEntry] to compare Makes a copy of @mount_entry. Use [method@GioUnix.MountEntry.copy] instead. a new [struct@GioUnix.MountEntry] a [struct@GioUnix.MountEntry] Checks if the Unix mounts have changed since a given Unix time. This can only work reliably if a [class@GioUnix.MountMonitor] is running in the process, otherwise changes in the mount entries file (such as `/proc/self/mountinfo` on Linux) cannot be detected and, as a result, this function has to conservatively always return `TRUE`. It is more efficient to use [signal@GioUnix.MountMonitor::mounts-changed] to be signalled of changes to the mount entries, rather than polling using this function. This function is more appropriate for infrequently determining cache validity. true if the mounts have changed since @time; false otherwise Since 2.84 a timestamp Gets a list of [struct@GioUnix.MountEntry] instances representing the Unix mounts. If @time_read is set, it will be filled with the mount timestamp, allowing for checking if the mounts have changed with [func@GioUnix.mount_entries_changed_since]. a list of the Unix mounts return location for a timestamp Gets an array of [struct@GioUnix.MountEntry]s containing the Unix mounts listed in @table_path. This is a generalized version of [func@GioUnix.mount_entries_get], mainly intended for internal testing use. Note that [func@GioUnix.mount_entries_get] may parse multiple hierarchical table files, so this function is not a direct superset of its functionality. If there is an error reading or parsing the file, `NULL` will be returned and both out parameters will be set to `0`. mount entries, or `NULL` if there was an error loading them path to the mounts table file (for example `/proc/self/mountinfo`) return location for the modification time of @table_path return location for the number of mount entries returned Gets a [struct@GioUnix.MountEntry] for a given mount path. If @time_read is set, it will be filled with a Unix timestamp for checking if the mounts have changed since with [func@GioUnix.mount_entries_changed_since]. If more mounts have the same mount path, the last matching mount is returned. This will return `NULL` if there is no mount point at @mount_path. a [struct@GioUnix.MountEntry] path for a possible Unix mount return location for a timestamp Gets a [struct@GioUnix.MountEntry] for a given file path. If @time_read is set, it will be filled with a Unix timestamp for checking if the mounts have changed since with [func@GioUnix.mount_entries_changed_since]. If more mounts have the same mount path, the last matching mount is returned. This will return `NULL` if looking up the mount entry fails, if @file_path doesn’t exist or there is an I/O error. a [struct@GioUnix.MountEntry] file path on some Unix mount return location for a timestamp Gets a [struct@GioUnix.MountEntry] for a given file path. If @time_read is set, it will be filled with a Unix timestamp for checking if the mounts have changed since with [func@GioUnix.mount_entries_changed_since]. If more mounts have the same mount path, the last matching mount is returned. This will return `NULL` if looking up the mount entry fails, if @file_path doesn’t exist or there is an I/O error. Use [func@GioUnix.MountEntry.for] instead. a [struct@GioUnix.MountEntry] file path on some Unix mount return location for a timestamp Frees a Unix mount. Use [method@GioUnix.MountEntry.free] instead. a [struct@GioUnix.MountEntry] Gets the device path for a Unix mount. Use [method@GioUnix.MountEntry.get_device_path] instead. a string containing the device path a [struct@GioUnix.MountEntry] Gets the filesystem type for the Unix mount. Use [method@GioUnix.MountEntry.get_fs_type] instead. a string containing the file system type a [struct@GioUnix.MountEntry] Gets the mount path for a Unix mount. Use [method@GioUnix.MountEntry.get_mount_path] instead. the mount path for @mount_entry a [struct@GioUnix.MountEntry] to get the mount path for Gets a comma separated list of mount options for the Unix mount. For example: `rw,relatime,seclabel,data=ordered`. This is similar to [method@GioUnix.MountPoint.get_options], but it takes a [struct@GioUnix.MountEntry] as an argument. Use [method@GioUnix.MountEntry.get_options] instead. a string containing the options, or `NULL` if not available. a [struct@GioUnix.MountEntry] Gets the root of the mount within the filesystem. This is useful e.g. for mounts created by bind operation, or btrfs subvolumes. For example, the root path is equal to `/` for a mount created by `mount /dev/sda1 /mnt/foo` and `/bar` for `mount --bind /mnt/foo/bar /mnt/bar`. Use [method@GioUnix.MountEntry.get_root_path] instead. a string containing the root, or `NULL` if not supported a [struct@GioUnix.MountEntry] Guesses whether a Unix mount entry can be ejected. Use [method@GioUnix.MountEntry.guess_can_eject] instead. true if @mount_entry is deemed to be ejectable; false otherwise a [struct@GioUnix.MountEntry] Guesses the icon of a Unix mount entry. Use [method@GioUnix.MountEntry.guess_icon] instead. a [iface@Gio.Icon] a [struct@GioUnix.MountEntry] Guesses the name of a Unix mount entry. The result is a translated string. Use [method@GioUnix.MountEntry.guess_name] instead. a newly allocated translated string a [struct@GioUnix.MountEntry] Guesses whether a Unix mount entry should be displayed in the UI. Use [method@GioUnix.MountEntry.guess_should_display] instead. true if @mount_entry is deemed to be displayable; false otherwise a [struct@GioUnix.MountEntry] Guesses the symbolic icon of a Unix mount entry. Use [method@GioUnix.MountEntry.guess_symbolic_icon] instead. a [iface@Gio.Icon] a [struct@GioUnix.MountEntry] Checks if a Unix mount is mounted read only. Use [method@GioUnix.MountEntry.is_readonly] instead. true if @mount_entry is read only; false otherwise a [struct@GioUnix.MountEntry] Checks if a Unix mount is a system mount. This is the Boolean OR of [func@GioUnix.is_system_fs_type], [func@GioUnix.is_system_device_path] and [func@GioUnix.is_mount_path_system_internal] on @mount_entry’s properties. The definition of what a ‘system’ mount entry is may change over time as new file system types and device paths are ignored. Use [method@GioUnix.MountEntry.is_system_internal] instead. true if the Unix mount is for a system path; false otherwise a [struct@GioUnix.MountEntry] Gets a [struct@GioUnix.MountPoint] for a given mount path. If @time_read is set, it will be filled with a Unix timestamp for checking if the mount points have changed since with [func@GioUnix.mount_points_changed_since]. If more mount points have the same mount path, the last matching mount point is returned. a [struct@GioUnix.MountPoint], or `NULL` if no match is found path for a possible Unix mount point return location for a timestamp Checks if the Unix mount points have changed since a given Unix time. Unlike [func@GioUnix.mount_entries_changed_since], this function can work reliably without a [class@GioUnix.MountMonitor] running, as it accesses the static mount point information (such as `/etc/fstab` on Linux), which has a valid modification time. It is more efficient to use [signal@GioUnix.MountMonitor::mountpoints-changed] to be signalled of changes to the mount points, rather than polling using this function. This function is more appropriate for infrequently determining cache validity. true if the mount points have changed since @time; false otherwise a timestamp Gets a list of [struct@GioUnix.MountPoint] instances representing the Unix mount points. If @time_read is set, it will be filled with the mount timestamp, allowing for checking if the mounts have changed with [func@GioUnix.mount_points_changed_since]. a list of the Unix mount points return location for a timestamp Gets an array of [struct@GioUnix.MountPoint]s containing the Unix mount points listed in @table_path. This is a generalized version of [func@GioUnix.mount_points_get], mainly intended for internal testing use. Note that [func@GioUnix.mount_points_get] may parse multiple hierarchical table files, so this function is not a direct superset of its functionality. If there is an error reading or parsing the file, `NULL` will be returned and both out parameters will be set to `0`. mount points, or `NULL` if there was an error loading them path to the mount points table file (for example `/etc/fstab`) return location for the modification time of @table_path return location for the number of mount points returned Checks if the Unix mounts have changed since a given Unix time. Use [func@GioUnix.mount_entries_changed_since] instead. true if the mounts have changed since @time; false otherwise a timestamp Gets a list of [struct@GioUnix.MountEntry] instances representing the Unix mounts. If @time_read is set, it will be filled with the mount timestamp, allowing for checking if the mounts have changed with [func@GioUnix.mount_entries_changed_since]. Use [func@GioUnix.mount_entries_get] instead. a list of the Unix mounts return location for a timestamp Gets an array of [struct@GioUnix.MountEntry]s containing the Unix mounts listed in @table_path. This is a generalized version of [func@GioUnix.mount_entries_get], mainly intended for internal testing use. Note that [func@GioUnix.mount_entries_get] may parse multiple hierarchical table files, so this function is not a direct superset of its functionality. If there is an error reading or parsing the file, `NULL` will be returned and both out parameters will be set to `0`. Use [func@GioUnix.mount_entries_get_from_file] instead. mount entries, or `NULL` if there was an error loading them path to the mounts table file (for example `/proc/self/mountinfo`) return location for the modification time of @table_path return location for the number of mount entries returned soup3-0.9.0/gir-files/GioWin32-2.0.gir000064400000000000000000000444451046102023000151400ustar 00000000000000 `GWin32InputStream` implements [class@Gio.InputStream] for reading from a Windows file handle. Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file when using it. Creates a new #GWin32InputStream for the given @handle. If @close_handle is %TRUE, the handle will be closed when the stream is closed. Note that "handle" here means a Win32 HANDLE, not a "file descriptor" as used in the Windows C libraries. a new #GWin32InputStream a Win32 file handle %TRUE to close the handle when done Returns whether the handle of @stream will be closed when the stream is closed. %TRUE if the handle is closed when done a #GWin32InputStream Return the Windows file handle that the stream reads from. The file handle of @stream a #GWin32InputStream Sets whether the handle of @stream shall be closed when the stream is closed. a #GWin32InputStream %TRUE to close the handle when done Whether to close the file handle when the stream is closed. The handle that the stream reads from. `GWin32OutputStream` implements [class@Gio.OutputStream] for writing to a Windows file handle. Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file when using it. Creates a new #GWin32OutputStream for the given @handle. If @close_handle, is %TRUE, the handle will be closed when the output stream is destroyed. a new #GOutputStream a Win32 file handle %TRUE to close the handle when done Returns whether the handle of @stream will be closed when the stream is closed. %TRUE if the handle is closed when done a #GWin32OutputStream Return the Windows handle that the stream writes to. The handle descriptor of @stream a #GWin32OutputStream Sets whether the handle of @stream shall be closed when the stream is closed. a #GWin32OutputStream %TRUE to close the handle when done Whether to close the file handle when the stream is closed. The file handle that the stream writes to. If @registry_key is %NULL then the default path `HKEY_CURRENT_USER\Software\GSettings` is used. a registry-backed #GSettingsBackend the path to the registry key where settings are stored, or %NULL. soup3-0.9.0/gir-files/Graphene-1.0.gir000064400000000000000000016050611046102023000153250ustar 00000000000000 A 3D box, described as the volume between a minimum and a maximum vertices. Allocates a new #graphene_box_t. The contents of the returned structure are undefined. the newly allocated #graphene_box_t structure. Use graphene_box_free() to free the resources allocated by this function Checks whether the #graphene_box_t @a contains the given #graphene_box_t @b. `true` if the box is contained in the given box a #graphene_box_t a #graphene_box_t Checks whether @box contains the given @point. `true` if the point is contained in the given box a #graphene_box_t the coordinates to check Checks whether the two given boxes are equal. `true` if the boxes are equal a #graphene_box_t a #graphene_box_t Expands the dimensions of @box to include the coordinates at @point. a #graphene_box_t the coordinates of the point to include return location for the expanded box Expands the dimensions of @box by the given @scalar value. If @scalar is positive, the #graphene_box_t will grow; if @scalar is negative, the #graphene_box_t will shrink. a #graphene_box_t a scalar value return location for the expanded box Expands the dimensions of @box to include the coordinates of the given vector. a #graphene_box_t the coordinates of the point to include, as a #graphene_vec3_t return location for the expanded box Frees the resources allocated by graphene_box_alloc(). a #graphene_box_t Computes the bounding #graphene_sphere_t capable of containing the given #graphene_box_t. a #graphene_box_t return location for the bounding sphere Retrieves the coordinates of the center of a #graphene_box_t. a #graphene_box_t return location for the coordinates of the center Retrieves the size of the @box on the Z axis. the depth of the box a #graphene_box_t Retrieves the size of the @box on the Y axis. the height of the box a #graphene_box_t Retrieves the coordinates of the maximum point of the given #graphene_box_t. a #graphene_box_t return location for the maximum point Retrieves the coordinates of the minimum point of the given #graphene_box_t. a #graphene_box_t return location for the minimum point Retrieves the coordinates of the minimum and maximum points of the given #graphene_box_t a #graphene_box_t return location for the minimum point return location for the maximum point Retrieves the size of the box on all three axes, and stores it into the given @size vector. a #graphene_box_t return location for the size Computes the vertices of the given #graphene_box_t. a #graphene_box_t return location for an array of 8 #graphene_vec3_t Retrieves the size of the @box on the X axis. the width of the box a #graphene_box_t Initializes the given #graphene_box_t with two vertices. the initialized #graphene_box_t the #graphene_box_t to initialize the coordinates of the minimum vertex the coordinates of the maximum vertex Initializes the given #graphene_box_t with the vertices of another #graphene_box_t. the initialized #graphene_box_t the #graphene_box_t to initialize a #graphene_box_t Initializes the given #graphene_box_t with the given array of vertices. If @n_points is 0, the returned box is initialized with graphene_box_empty(). the initialized #graphene_box_t the #graphene_box_t to initialize the number #graphene_point3d_t in the @points array an array of #graphene_point3d_t Initializes the given #graphene_box_t with two vertices stored inside #graphene_vec3_t. the initialized #graphene_box_t the #graphene_box_t to initialize the coordinates of the minimum vertex the coordinates of the maximum vertex Initializes the given #graphene_box_t with the given array of vertices. If @n_vectors is 0, the returned box is initialized with graphene_box_empty(). the initialized #graphene_box_t the #graphene_box_t to initialize the number #graphene_point3d_t in the @vectors array an array of #graphene_vec3_t Intersects the two given #graphene_box_t. If the two boxes do not intersect, @res will contain a degenerate box initialized with graphene_box_empty(). true if the two boxes intersect a #graphene_box_t a #graphene_box_t return location for the result Unions the two given #graphene_box_t. a #graphene_box_t the box to union to @a return location for the result A degenerate #graphene_box_t that can only be expanded. The returned value is owned by Graphene and should not be modified or freed. a #graphene_box_t A degenerate #graphene_box_t that cannot be expanded. The returned value is owned by Graphene and should not be modified or freed. a #graphene_box_t A #graphene_box_t with the minimum vertex set at (-1, -1, -1) and the maximum vertex set at (0, 0, 0). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box_t A #graphene_box_t with the minimum vertex set at (0, 0, 0) and the maximum vertex set at (1, 1, 1). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box_t A #graphene_box_t with the minimum vertex set at (-1, -1, -1) and the maximum vertex set at (1, 1, 1). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box_t A #graphene_box_t with both the minimum and maximum vertices set at (0, 0, 0). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box_t A 2D box, described as the axis-aligned area between a minimum and a maximum vertices lying on the same plane. Allocates a new #graphene_box2d_t. The contents of the returned structure are undefined. the newly allocated #graphene_box2d_t structure. Use graphene_box2d_free() to free the resources allocated by this function Checks whether the #graphene_box2d_t @a contains the given #graphene_box2d_t @b. `true` if the box is contained in the given box a #graphene_box2d_t a #graphene_box2d_t Checks whether @box contains the given @point. `true` if the point is contained in the given box a #graphene_box2d_t the coordinates to check Checks whether @box contains the given @rect. `true` if the rectangle is contained in the given box a #graphene_box2d_t the rectangle to check Checks whether the two given boxes are equal. `true` if the boxes are equal a #graphene_box2d_t a #graphene_box2d_t Expands the dimensions of @box to include the coordinates at @point. a #graphene_box2d_t the coordinates of the point to include return location for the expanded box Expands the dimensions of @box by the given @scalar value. If @scalar is positive, the #graphene_box2d_t will grow; if @scalar is negative, the #graphene_box2d_t will shrink. a #graphene_box2d_t a scalar value return location for the expanded box Expands the dimensions of @box to include the coordinates of the given vector. a #graphene_box2d_t the coordinates of the point to include, as a #graphene_vec2_t return location for the expanded box Frees the resources allocated by graphene_box2d_alloc(). a #graphene_box2d_t Retrieves the coordinates of the center of a #graphene_box2d_t. a #graphene_box2d_t return location for the coordinates of the center Retrieves the size of the @box on the Y axis. the height of the box a #graphene_box2d_t Retrieves the coordinates of the maximum point of the given #graphene_box2d_t. a #graphene_box2d_t return location for the maximum point Retrieves the coordinates of the minimum point of the given #graphene_box2d_t. a #graphene_box2d_t return location for the minimum point Retrieves the coordinates of the minimum and maximum points of the given #graphene_box2d_t. a #graphene_box2d_t return location for the minimum point return location for the maximum point Retrieves the size of the box on all three axes, and stores it into the given @size vector. a #graphene_box2d_t return location for the size Computes the vertices of the given #graphene_box2d_t. a #graphene_box2d_t return location for an array of 4 #graphene_vec2_t Retrieves the size of the @box on the X axis. the width of the box a #graphene_box2d_t Initializes the given #graphene_box2d_t with two vertices. the initialized #graphene_box2d_t the #graphene_box2d_t to initialize the coordinates of the minimum vertex the coordinates of the maximum vertex Initializes the given #graphene_box2d_t with the vertices of another #graphene_box2d_t. the initialized #graphene_box2d_t the #graphene_box2d_t to initialize a #graphene_box2d_t Initializes the given #graphene_box2d_t with the given array of vertices. If @n_points is 0, the returned box is initialized with graphene_box2d_empty(). the initialized #graphene_box2d_t the #graphene_box2d_t to initialize the number #graphene_point_t in the @points array an array of #graphene_point_t Initializes the given #graphene_box2d_t with the origin and size of a #graphene_rect_t. the initialized #graphene_box2d_t the #graphene_box2d_t to initialize a #graphene_rect_t Initializes the given #graphene_box2d_t with two vertices stored inside #graphene_vec2_t. the initialized #graphene_box2d_t the #graphene_box2d_t to initialize the coordinates of the minimum vertex the coordinates of the maximum vertex Initializes the given #graphene_box2d_t with the given array of vertices. If @n_vectors is 0, the returned box is initialized with graphene_box2d_empty(). the initialized #graphene_box2d_t the #graphene_box2d_t to initialize the number #graphene_vec2_t in the @vectors array an array of #graphene_vec2_t Intersects the two given #graphene_box2d_t. If the two boxes do not intersect, @res will contain a degenerate box initialized with graphene_box2d_empty(). true if the two boxes intersect a #graphene_box2d_t a #graphene_box2d_t return location for the result Checks whether two boxes intersect. See also: graphene_box2d_intersection() true if the boxes intersect, and false otherwise a #graphene_box2d_t a #graphene_box2d_t Applies a scale and an offset to the vertices of the given box. If @scale is %NULL, the box will be scaled by (1.0, 1.0). If @offset is %NULL, the box will be offset by (0.0, 0.0). a #graphene_box2d_t a vector with two scaling factors to be applied to the box the offset to apply to the box the transformed box Stores the minimum and maximum vertices of the given #graphene_box2d_t into an array. The array layout is: - min_x - min_y - max_x - max_y a #graphene_box2d_t return location for an array of floating point values with at least 4 elements Stores the minimum and maximum vertices of the given #graphene_box2d_t into a rectangle of equivalent origin and size. a #graphene_box2d_t the rectangle to initialize Unions the two given #graphene_box2d_t. a #graphene_box2d_t the box to union to @a return location for the result A degenerate #graphene_box2d_t that can only be expanded. The returned value is owned by Graphene and should not be modified or freed. a #graphene_box2d_t A degenerate #graphene_box2d_t that cannot be expanded. The returned value is owned by Graphene and should not be modified or freed. a #graphene_box2d_t A #graphene_box2d_t with the minimum vertex set at (-1, -1) and the maximum vertex set at (0, 0). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box2d_t A #graphene_box2d_t with the minimum vertex set at (0, 0) and the maximum vertex set at (1, 1). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box2d_t A #graphene_box2d_t with the minimum vertex set at (-1, -1) and the maximum vertex set at (1, 1). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box2d_t A #graphene_box2d_t with both the minimum and maximum vertices set at (0, 0). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box2d_t Encodes the given components into a value that can be used for version checks. a major version a minor version a micro version Describe a rotation using Euler angles. The contents of the #graphene_euler_t structure are private and should never be accessed directly. Allocates a new #graphene_euler_t. The contents of the returned structure are undefined. the newly allocated #graphene_euler_t Checks if two #graphene_euler_t are equal. `true` if the two #graphene_euler_t are equal a #graphene_euler_t a #graphene_euler_t Frees the resources allocated by graphene_euler_alloc(). a #graphene_euler_t Retrieves the first component of the Euler angle vector, depending on the order of rotation. See also: graphene_euler_get_x() the first component of the Euler angle vector, in radians a #graphene_euler_t Retrieves the second component of the Euler angle vector, depending on the order of rotation. See also: graphene_euler_get_y() the second component of the Euler angle vector, in radians a #graphene_euler_t Retrieves the third component of the Euler angle vector, depending on the order of rotation. See also: graphene_euler_get_z() the third component of the Euler angle vector, in radians a #graphene_euler_t Retrieves the order used to apply the rotations described in the #graphene_euler_t structure, when converting to and from other structures, like #graphene_quaternion_t and #graphene_matrix_t. This function does not return the %GRAPHENE_EULER_ORDER_DEFAULT enumeration value; it will return the effective order of rotation instead. the order used to apply the rotations a #graphene_euler_t Retrieves the rotation angle on the X axis, in degrees. the rotation angle a #graphene_euler_t Retrieves the rotation angle on the Y axis, in degrees. the rotation angle a #graphene_euler_t Retrieves the rotation angle on the Z axis, in degrees. the rotation angle a #graphene_euler_t Initializes a #graphene_euler_t using the given angles. The order of the rotations is %GRAPHENE_EULER_ORDER_DEFAULT. the initialized #graphene_euler_t the #graphene_euler_t to initialize rotation angle on the X axis, in degrees rotation angle on the Y axis, in degrees rotation angle on the Z axis, in degrees Initializes a #graphene_euler_t using the angles and order of another #graphene_euler_t. If the #graphene_euler_t @src is %NULL, this function is equivalent to calling graphene_euler_init() with all angles set to 0. the initialized #graphene_euler_t the #graphene_euler_t to initialize a #graphene_euler_t Initializes a #graphene_euler_t using the given rotation matrix. If the #graphene_matrix_t @m is %NULL, the #graphene_euler_t will be initialized with all angles set to 0. the initialized #graphene_euler_t the #graphene_euler_t to initialize a rotation matrix the order used to apply the rotations Initializes a #graphene_euler_t using the given normalized quaternion. If the #graphene_quaternion_t @q is %NULL, the #graphene_euler_t will be initialized with all angles set to 0. the initialized #graphene_euler_t a #graphene_euler_t a normalized #graphene_quaternion_t the order used to apply the rotations Initializes a #graphene_euler_t using the given angles and order of rotation. the initialized #graphene_euler_t the #graphene_euler_t to initialize rotation angle on the X axis, in radians rotation angle on the Y axis, in radians rotation angle on the Z axis, in radians order of rotations Initializes a #graphene_euler_t using the angles contained in a #graphene_vec3_t. If the #graphene_vec3_t @v is %NULL, the #graphene_euler_t will be initialized with all angles set to 0. the initialized #graphene_euler_t the #graphene_euler_t to initialize a #graphene_vec3_t containing the rotation angles in degrees the order used to apply the rotations Initializes a #graphene_euler_t with the given angles and @order. the initialized #graphene_euler_t the #graphene_euler_t to initialize rotation angle on the X axis, in degrees rotation angle on the Y axis, in degrees rotation angle on the Z axis, in degrees the order used to apply the rotations Reorders a #graphene_euler_t using @order. This function is equivalent to creating a #graphene_quaternion_t from the given #graphene_euler_t, and then converting the quaternion into another #graphene_euler_t. a #graphene_euler_t the new order return location for the reordered #graphene_euler_t Converts a #graphene_euler_t into a transformation matrix expressing the extrinsic composition of rotations described by the Euler angles. The rotations are applied over the reference frame axes in the order associated with the #graphene_euler_t; for instance, if the order used to initialize @e is %GRAPHENE_EULER_ORDER_XYZ: * the first rotation moves the body around the X axis with an angle φ * the second rotation moves the body around the Y axis with an angle of ϑ * the third rotation moves the body around the Z axis with an angle of ψ The rotation sign convention is right-handed, to preserve compatibility between Euler-based, quaternion-based, and angle-axis-based rotations. a #graphene_euler_t return location for a #graphene_matrix_t Converts a #graphene_euler_t into a #graphene_quaternion_t. a #graphene_euler_t return location for a #graphene_quaternion_t Retrieves the angles of a #graphene_euler_t and initializes a #graphene_vec3_t with them. a #graphene_euler_t return location for a #graphene_vec3_t Specify the order of the rotations on each axis. The %GRAPHENE_EULER_ORDER_DEFAULT value is special, and is used as an alias for one of the other orders. Rotate in the default order; the default order is one of the following enumeration values Rotate in the X, Y, and Z order. Deprecated in Graphene 1.10, it's an alias for %GRAPHENE_EULER_ORDER_SXYZ Rotate in the Y, Z, and X order. Deprecated in Graphene 1.10, it's an alias for %GRAPHENE_EULER_ORDER_SYZX Rotate in the Z, X, and Y order. Deprecated in Graphene 1.10, it's an alias for %GRAPHENE_EULER_ORDER_SZXY Rotate in the X, Z, and Y order. Deprecated in Graphene 1.10, it's an alias for %GRAPHENE_EULER_ORDER_SXZY Rotate in the Y, X, and Z order. Deprecated in Graphene 1.10, it's an alias for %GRAPHENE_EULER_ORDER_SYXZ Rotate in the Z, Y, and X order. Deprecated in Graphene 1.10, it's an alias for %GRAPHENE_EULER_ORDER_SZYX Defines a static rotation along the X, Y, and Z axes (Since: 1.10) Defines a static rotation along the X, Y, and X axes (Since: 1.10) Defines a static rotation along the X, Z, and Y axes (Since: 1.10) Defines a static rotation along the X, Z, and X axes (Since: 1.10) Defines a static rotation along the Y, Z, and X axes (Since: 1.10) Defines a static rotation along the Y, Z, and Y axes (Since: 1.10) Defines a static rotation along the Y, X, and Z axes (Since: 1.10) Defines a static rotation along the Y, X, and Y axes (Since: 1.10) Defines a static rotation along the Z, X, and Y axes (Since: 1.10) Defines a static rotation along the Z, X, and Z axes (Since: 1.10) Defines a static rotation along the Z, Y, and X axes (Since: 1.10) Defines a static rotation along the Z, Y, and Z axes (Since: 1.10) Defines a relative rotation along the Z, Y, and X axes (Since: 1.10) Defines a relative rotation along the X, Y, and X axes (Since: 1.10) Defines a relative rotation along the Y, Z, and X axes (Since: 1.10) Defines a relative rotation along the X, Z, and X axes (Since: 1.10) Defines a relative rotation along the X, Z, and Y axes (Since: 1.10) Defines a relative rotation along the Y, Z, and Y axes (Since: 1.10) Defines a relative rotation along the Z, X, and Y axes (Since: 1.10) Defines a relative rotation along the Y, X, and Y axes (Since: 1.10) Defines a relative rotation along the Y, X, and Z axes (Since: 1.10) Defines a relative rotation along the Z, X, and Z axes (Since: 1.10) Defines a relative rotation along the X, Y, and Z axes (Since: 1.10) Defines a relative rotation along the Z, Y, and Z axes (Since: 1.10) A 3D volume delimited by 2D clip planes. The contents of the `graphene_frustum_t` are private, and should not be modified directly. Allocates a new #graphene_frustum_t structure. The contents of the returned structure are undefined. the newly allocated #graphene_frustum_t structure. Use graphene_frustum_free() to free the resources allocated by this function. Checks whether a point is inside the volume defined by the given #graphene_frustum_t. `true` if the point is inside the frustum a #graphene_frustum_t a #graphene_point3d_t Checks whether the two given #graphene_frustum_t are equal. `true` if the given frustums are equal a #graphene_frustum_t a #graphene_frustum_t Frees the resources allocated by graphene_frustum_alloc(). a #graphene_frustum_t Retrieves the planes that define the given #graphene_frustum_t. a #graphene_frustum_t return location for an array of 6 #graphene_plane_t Initializes the given #graphene_frustum_t using the provided clipping planes. the initialized frustum the #graphene_frustum_t to initialize a clipping plane a clipping plane a clipping plane a clipping plane a clipping plane a clipping plane Initializes the given #graphene_frustum_t using the clipping planes of another #graphene_frustum_t. the initialized frustum the #graphene_frustum_t to initialize a #graphene_frustum_t Initializes a #graphene_frustum_t using the given @matrix. the initialized frustum a #graphene_frustum_t a #graphene_matrix_t Checks whether the given @box intersects a plane of a #graphene_frustum_t. `true` if the box intersects the frustum a #graphene_frustum_t a #graphene_box_t Checks whether the given @sphere intersects a plane of a #graphene_frustum_t. `true` if the sphere intersects the frustum a #graphene_frustum_t a #graphene_sphere_t A structure capable of holding a 4x4 matrix. The contents of the #graphene_matrix_t structure are private and should never be accessed directly. Allocates a new #graphene_matrix_t. the newly allocated matrix Decomposes a transformation matrix into its component transformations. The algorithm for decomposing a matrix is taken from the [CSS3 Transforms specification](http://dev.w3.org/csswg/css-transforms/); specifically, the decomposition code is based on the equivalent code published in "Graphics Gems II", edited by Jim Arvo, and [available online](http://web.archive.org/web/20150512160205/http://tog.acm.org/resources/GraphicsGems/gemsii/unmatrix.c). `true` if the matrix could be decomposed a #graphene_matrix_t the translation vector the scale vector the rotation quaternion the shear vector the perspective vector Computes the determinant of the given matrix. the value of the determinant a #graphene_matrix_t Checks whether the two given #graphene_matrix_t matrices are equal. `true` if the two matrices are equal, and `false` otherwise a #graphene_matrix_t a #graphene_matrix_t Checks whether the two given #graphene_matrix_t matrices are byte-by-byte equal. While this function is faster than graphene_matrix_equal(), it can also return false negatives, so it should be used in conjuction with either graphene_matrix_equal() or graphene_matrix_near(). For instance: |[<!-- language="C" --> if (graphene_matrix_equal_fast (a, b)) { // matrices are definitely the same } else { if (graphene_matrix_equal (a, b)) // matrices contain the same values within an epsilon of FLT_EPSILON else if (graphene_matrix_near (a, b, 0.0001)) // matrices contain the same values within an epsilon of 0.0001 else // matrices are not equal } ]| `true` if the matrices are equal. and `false` otherwise a #graphene_matrix_t a #graphene_matrix_t Frees the resources allocated by graphene_matrix_alloc(). a #graphene_matrix_t Retrieves the given row vector at @index_ inside a matrix. a #graphene_matrix_t the index of the row vector, between 0 and 3 return location for the #graphene_vec4_t that is used to store the row vector Retrieves the value at the given @row and @col index. the value at the given indices a #graphene_matrix_t the row index the column index Retrieves the scaling factor on the X axis in @m. the value of the scaling factor a #graphene_matrix_t Retrieves the translation component on the X axis from @m. the translation component a #graphene_matrix_t Retrieves the scaling factor on the Y axis in @m. the value of the scaling factor a #graphene_matrix_t Retrieves the translation component on the Y axis from @m. the translation component a #graphene_matrix_t Retrieves the scaling factor on the Z axis in @m. the value of the scaling factor a #graphene_matrix_t Retrieves the translation component on the Z axis from @m. the translation component a #graphene_matrix_t Initializes a #graphene_matrix_t from the values of an affine transformation matrix. The arguments map to the following matrix layout: |[<!-- language="plain" --> ⎛ xx yx ⎞ ⎛ a b 0 ⎞ ⎜ xy yy ⎟ = ⎜ c d 0 ⎟ ⎝ x0 y0 ⎠ ⎝ tx ty 1 ⎠ ]| This function can be used to convert between an affine matrix type from other libraries and a #graphene_matrix_t. the initialized matrix a #graphene_matrix_t the xx member the yx member the xy member the yy member the x0 member the y0 member Initializes a #graphene_matrix_t with the given array of floating point values. the initialized matrix a #graphene_matrix_t an array of at least 16 floating point values Initializes a #graphene_matrix_t using the values of the given matrix. the initialized matrix a #graphene_matrix_t a #graphene_matrix_t Initializes a #graphene_matrix_t with the given four row vectors. the initialized matrix a #graphene_matrix_t the first row vector the second row vector the third row vector the fourth row vector Initializes a #graphene_matrix_t compatible with #graphene_frustum_t. See also: graphene_frustum_init_from_matrix() the initialized matrix a #graphene_matrix_t distance of the left clipping plane distance of the right clipping plane distance of the bottom clipping plane distance of the top clipping plane distance of the near clipping plane distance of the far clipping plane Initializes a #graphene_matrix_t with the identity matrix. the initialized matrix a #graphene_matrix_t Initializes a #graphene_matrix_t so that it positions the "camera" at the given @eye coordinates towards an object at the @center coordinates. The top of the camera is aligned to the direction of the @up vector. Before the transform, the camera is assumed to be placed at the origin, looking towards the negative Z axis, with the top side of the camera facing in the direction of the Y axis and the right side in the direction of the X axis. In theory, one could use @m to transform a model of such a camera into world-space. However, it is more common to use the inverse of @m to transform another object from world coordinates to the view coordinates of the camera. Typically you would then apply the camera projection transform to get from view to screen coordinates. the initialized matrix a #graphene_matrix_t the vector describing the position to look from the vector describing the position to look at the vector describing the world's upward direction; usually, this is the graphene_vec3_y_axis() vector Initializes a #graphene_matrix_t with an orthographic projection. the initialized matrix a #graphene_matrix_t the left edge of the clipping plane the right edge of the clipping plane the top edge of the clipping plane the bottom edge of the clipping plane the distance of the near clipping plane the distance of the far clipping plane Initializes a #graphene_matrix_t with a perspective projection. the initialized matrix a #graphene_matrix_t the field of view angle, in degrees the aspect value the near Z plane the far Z plane Initializes @m to represent a rotation of @angle degrees on the axis represented by the @axis vector. the initialized matrix a #graphene_matrix_t the rotation angle, in degrees the axis vector as a #graphene_vec3_t Initializes a #graphene_matrix_t with the given scaling factors. the initialized matrix a #graphene_matrix_t the scale factor on the X axis the scale factor on the Y axis the scale factor on the Z axis Initializes a #graphene_matrix_t with a skew transformation with the given factors. the initialized matrix a #graphene_matrix_t skew factor, in radians, on the X axis skew factor, in radians, on the Y axis Initializes a #graphene_matrix_t with a translation to the given coordinates. the initialized matrix a #graphene_matrix_t the translation coordinates Linearly interpolates the two given #graphene_matrix_t by interpolating the decomposed transformations separately. If either matrix cannot be reduced to their transformations then the interpolation cannot be performed, and this function will return an identity matrix. a #graphene_matrix_t a #graphene_matrix_t the linear interpolation factor return location for the interpolated matrix Inverts the given matrix. `true` if the matrix is invertible a #graphene_matrix_t return location for the inverse matrix Checks whether the given #graphene_matrix_t is compatible with an a 2D affine transformation matrix. `true` if the matrix is compatible with an affine transformation matrix a #graphene_matrix_t Checks whether a #graphene_matrix_t has a visible back face. `true` if the back face of the matrix is visible a #graphene_matrix_t Checks whether the given #graphene_matrix_t is the identity matrix. `true` if the matrix is the identity matrix a #graphene_matrix_t Checks whether a matrix is singular. `true` if the matrix is singular a #graphene_matrix_t Multiplies two #graphene_matrix_t. Matrix multiplication is not commutative in general; the order of the factors matters. The product of this multiplication is (@a × @b) a #graphene_matrix_t a #graphene_matrix_t return location for the matrix result Compares the two given #graphene_matrix_t matrices and checks whether their values are within the given @epsilon of each other. `true` if the two matrices are near each other, and `false` otherwise a #graphene_matrix_t a #graphene_matrix_t the threshold between the two matrices Normalizes the given #graphene_matrix_t. a #graphene_matrix_t return location for the normalized matrix Applies a perspective of @depth to the matrix. a #graphene_matrix_t the depth of the perspective return location for the perspective matrix Prints the contents of a matrix to the standard error stream. This function is only useful for debugging; there are no guarantees made on the format of the output. The matrix to print Projects a #graphene_point_t using the matrix @m. a #graphene_matrix_t a #graphene_point_t return location for the projected point Projects all corners of a #graphene_rect_t using the given matrix. See also: graphene_matrix_project_point() a #graphene_matrix_t a #graphene_rect_t return location for the projected rectangle Projects a #graphene_rect_t using the given matrix. The resulting rectangle is the axis aligned bounding rectangle capable of fully containing the projected rectangle. a #graphene_matrix_t a #graphene_rect_t return location for the projected rectangle Adds a rotation transformation to @m, using the given @angle and @axis vector. This is the equivalent of calling graphene_matrix_init_rotate() and then multiplying the matrix @m with the rotation matrix. a #graphene_matrix_t the rotation angle, in degrees the rotation axis, as a #graphene_vec3_t Adds a rotation transformation to @m, using the given #graphene_euler_t. a #graphene_matrix_t a rotation described by a #graphene_euler_t Adds a rotation transformation to @m, using the given #graphene_quaternion_t. This is the equivalent of calling graphene_quaternion_to_matrix() and then multiplying @m with the rotation matrix. a #graphene_matrix_t a rotation described by a #graphene_quaternion_t Adds a rotation transformation around the X axis to @m, using the given @angle. See also: graphene_matrix_rotate() a #graphene_matrix_t the rotation angle, in degrees Adds a rotation transformation around the Y axis to @m, using the given @angle. See also: graphene_matrix_rotate() a #graphene_matrix_t the rotation angle, in degrees Adds a rotation transformation around the Z axis to @m, using the given @angle. See also: graphene_matrix_rotate() a #graphene_matrix_t the rotation angle, in degrees Adds a scaling transformation to @m, using the three given factors. This is the equivalent of calling graphene_matrix_init_scale() and then multiplying the matrix @m with the scale matrix. a #graphene_matrix_t scaling factor on the X axis scaling factor on the Y axis scaling factor on the Z axis Adds a skew of @factor on the X and Y axis to the given matrix. a #graphene_matrix_t skew factor Adds a skew of @factor on the X and Z axis to the given matrix. a #graphene_matrix_t skew factor Adds a skew of @factor on the Y and Z axis to the given matrix. a #graphene_matrix_t skew factor Converts a #graphene_matrix_t to an affine transformation matrix, if the given matrix is compatible. The returned values have the following layout: |[<!-- language="plain" --> ⎛ xx yx ⎞ ⎛ a b 0 ⎞ ⎜ xy yy ⎟ = ⎜ c d 0 ⎟ ⎝ x0 y0 ⎠ ⎝ tx ty 1 ⎠ ]| This function can be used to convert between a #graphene_matrix_t and an affine matrix type from other libraries. `true` if the matrix is compatible with an affine transformation matrix a #graphene_matrix_t return location for the xx member return location for the yx member return location for the xy member return location for the yy member return location for the x0 member return location for the y0 member Converts a #graphene_matrix_t to an array of floating point values. a #graphene_matrix_t return location for an array of floating point values. The array must be capable of holding at least 16 values. Transforms each corner of a #graphene_rect_t using the given matrix @m. The result is the axis aligned bounding rectangle containing the coplanar quadrilateral. See also: graphene_matrix_transform_point() a #graphene_matrix_t a #graphene_rect_t return location for the bounds of the transformed rectangle Transforms the vertices of a #graphene_box_t using the given matrix @m. The result is the axis aligned bounding box containing the transformed vertices. a #graphene_matrix_t a #graphene_box_t return location for the bounds of the transformed box Transforms the given #graphene_point_t using the matrix @m. Unlike graphene_matrix_transform_vec3(), this function will take into account the fourth row vector of the #graphene_matrix_t when computing the dot product of each row vector of the matrix. See also: graphene_simd4x4f_point3_mul() a #graphene_matrix_t a #graphene_point_t return location for the transformed #graphene_point_t Transforms the given #graphene_point3d_t using the matrix @m. Unlike graphene_matrix_transform_vec3(), this function will take into account the fourth row vector of the #graphene_matrix_t when computing the dot product of each row vector of the matrix. See also: graphene_simd4x4f_point3_mul() a #graphene_matrix_t a #graphene_point3d_t return location for the result Transform a #graphene_ray_t using the given matrix @m. a #graphene_matrix_t a #graphene_ray_t return location for the transformed ray Transforms each corner of a #graphene_rect_t using the given matrix @m. The result is a coplanar quadrilateral. See also: graphene_matrix_transform_point() a #graphene_matrix_t a #graphene_rect_t return location for the transformed quad Transforms a #graphene_sphere_t using the given matrix @m. The result is the bounding sphere containing the transformed sphere. a #graphene_matrix_t a #graphene_sphere_t return location for the bounds of the transformed sphere Transforms the given #graphene_vec3_t using the matrix @m. This function will multiply the X, Y, and Z row vectors of the matrix @m with the corresponding components of the vector @v. The W row vector will be ignored. See also: graphene_simd4x4f_vec3_mul() a #graphene_matrix_t a #graphene_vec3_t return location for a #graphene_vec3_t Transforms the given #graphene_vec4_t using the matrix @m. See also: graphene_simd4x4f_vec4_mul() a #graphene_matrix_t a #graphene_vec4_t return location for a #graphene_vec4_t Adds a translation transformation to @m using the coordinates of the given #graphene_point3d_t. This is the equivalent of calling graphene_matrix_init_translate() and then multiplying @m with the translation matrix. a #graphene_matrix_t a #graphene_point3d_t Transposes the given matrix. a #graphene_matrix_t return location for the transposed matrix Unprojects the given @point using the @projection matrix and a @modelview matrix. a #graphene_matrix_t for the projection matrix a #graphene_matrix_t for the modelview matrix; this is the inverse of the modelview used when projecting the point a #graphene_point3d_t with the coordinates of the point return location for the unprojected point Undoes the transformation on the corners of a #graphene_rect_t using the given matrix, within the given axis aligned rectangular @bounds. a #graphene_matrix_t a #graphene_rect_t the bounds of the transformation return location for the untransformed rectangle Undoes the transformation of a #graphene_point_t using the given matrix, within the given axis aligned rectangular @bounds. `true` if the point was successfully untransformed a #graphene_matrix_t a #graphene_point_t the bounds of the transformation return location for the untransformed point Initializes a #graphene_point3d_t to the given coordinates when declaring it. the X coordinate the Y coordinate the Z coordinate Initializes a #graphene_point_t with the given coordinates when declaring it, e.g: |[<!-- language="C" --> graphene_point_t p = GRAPHENE_POINT_INIT (10.f, 10.f); ]| the X coordinate the Y coordinate A 2D plane that extends infinitely in a 3D volume. The contents of the `graphene_plane_t` are private, and should not be modified directly. Allocates a new #graphene_plane_t structure. The contents of the returned structure are undefined. the newly allocated #graphene_plane_t. Use graphene_plane_free() to free the resources allocated by this function Computes the distance of @point from a #graphene_plane_t. the distance of the given #graphene_point3d_t from the plane a #graphene_plane_t a #graphene_point3d_t Checks whether the two given #graphene_plane_t are equal. `true` if the given planes are equal a #graphene_plane_t a #graphene_plane_t Frees the resources allocated by graphene_plane_alloc(). a #graphene_plane_t Retrieves the distance along the normal vector of the given #graphene_plane_t from the origin. the constant value of the plane a #graphene_plane_t Retrieves the normal vector pointing towards the origin of the given #graphene_plane_t. a #graphene_plane_t return location for the normal vector Initializes the given #graphene_plane_t using the given @normal vector and @constant values. the initialized plane the #graphene_plane_t to initialize a unit length normal vector defining the plane pointing towards the origin; if unset, we use the X axis by default the distance from the origin to the plane along the normal vector; the sign determines the half-space occupied by the plane Initializes the given #graphene_plane_t using the normal vector and constant of another #graphene_plane_t. the initialized plane the #graphene_plane_t to initialize a #graphene_plane_t Initializes the given #graphene_plane_t using the given normal vector and an arbitrary co-planar point. the initialized plane the #graphene_plane_t to initialize a normal vector defining the plane pointing towards the origin a #graphene_point3d_t Initializes the given #graphene_plane_t using the 3 provided co-planar points. The winding order is counter-clockwise, and determines which direction the normal vector will point. the initialized plane the #graphene_plane_t to initialize a #graphene_point3d_t a #graphene_point3d_t a #graphene_point3d_t Initializes the given #graphene_plane_t using the components of the given #graphene_vec4_t vector. the initialized plane the #graphene_plane_t to initialize a #graphene_vec4_t containing the normal vector in its first three components, and the distance in its fourth component Negates the normal vector and constant of a #graphene_plane_t, effectively mirroring the plane across the origin. a #graphene_plane_t return location for the negated plane Normalizes the vector of the given #graphene_plane_t, and adjusts the constant accordingly. a #graphene_plane_t return location for the normalized plane Transforms a #graphene_plane_t @p using the given @matrix and @normal_matrix. If @normal_matrix is %NULL, a transformation matrix for the plane normal will be computed from @matrix. If you are transforming multiple planes using the same @matrix it's recommended to compute the normal matrix beforehand to avoid incurring in the cost of recomputing it every time. a #graphene_plane_t a #graphene_matrix_t a #graphene_matrix_t the transformed plane A point with two coordinates. the X coordinate of the point the Y coordinate of the point Allocates a new #graphene_point_t structure. The coordinates of the returned point are (0, 0). It's possible to chain this function with graphene_point_init() or graphene_point_init_from_point(), e.g.: |[<!-- language="C" --> graphene_point_t * point_new (float x, float y) { return graphene_point_init (graphene_point_alloc (), x, y); } graphene_point_t * point_copy (const graphene_point_t *p) { return graphene_point_init_from_point (graphene_point_alloc (), p); } ]| the newly allocated #graphene_point_t. Use graphene_point_free() to free the resources allocated by this function. Computes the distance between @a and @b. the distance between the two points a #graphene_point_t a #graphene_point_t distance component on the X axis distance component on the Y axis Computes the squared distance between @a and @b. the distance between the two points, squared a #graphene_point_t a #graphene_point_t Checks if the two points @a and @b point to the same coordinates. This function accounts for floating point fluctuations; if you want to control the fuzziness of the match, you can use graphene_point_near() instead. `true` if the points have the same coordinates a #graphene_point_t a #graphene_point_t Frees the resources allocated by graphene_point_alloc(). a #graphene_point_t Initializes @p to the given @x and @y coordinates. It's safe to call this function multiple times. the initialized point a #graphene_point_t the X coordinate the Y coordinate Initializes @p with the same coordinates of @src. the initialized point a #graphene_point_t the #graphene_point_t to use Initializes @p with the coordinates inside the given #graphene_vec2_t. the initialized point the #graphene_point_t to initialize a #graphene_vec2_t Linearly interpolates the coordinates of @a and @b using the given @factor. a #graphene_point_t a #graphene_point_t the linear interpolation factor return location for the interpolated point Checks whether the two points @a and @b are within the threshold of @epsilon. `true` if the distance is within @epsilon a #graphene_point_t a #graphene_point_t threshold between the two points Stores the coordinates of the given #graphene_point_t into a #graphene_vec2_t. a #graphene_point_t return location for the vertex Returns a point fixed at (0, 0). a fixed point A point with three components: X, Y, and Z. the X coordinate the Y coordinate the Z coordinate Allocates a #graphene_point3d_t structure. the newly allocated structure. Use graphene_point3d_free() to free the resources allocated by this function. Computes the cross product of the two given #graphene_point3d_t. a #graphene_point3d_t a #graphene_point3d_t return location for the cross product Computes the distance between the two given #graphene_point3d_t. the distance between two points a #graphene_point3d_t a #graphene_point3d_t return location for the distance components on the X, Y, and Z axis Computes the dot product of the two given #graphene_point3d_t. the value of the dot product a #graphene_point3d_t a #graphene_point3d_t Checks whether two given points are equal. `true` if the points are equal a #graphene_point3d_t a #graphene_point3d_t Frees the resources allocated via graphene_point3d_alloc(). a #graphene_point3d_t Initializes a #graphene_point3d_t with the given coordinates. the initialized #graphene_point3d_t the #graphene_point3d_t to initialize the X coordinate of the point the Y coordinate of the point the Z coordinate of the point Initializes a #graphene_point3d_t using the coordinates of another #graphene_point3d_t. the initialized point a #graphene_point3d_t a #graphene_point3d_t Initializes a #graphene_point3d_t using the components of a #graphene_vec3_t. the initialized #graphene_point3d_t a #graphene_point3d_t a #graphene_vec3_t Linearly interpolates each component of @a and @b using the provided @factor, and places the result in @res. a #graphene_point3d_t a #graphene_point3d_t the interpolation factor the return location for the interpolated #graphene_point3d_t Computes the length of the vector represented by the coordinates of the given #graphene_point3d_t. the length of the vector represented by the point a #graphene_point3d_t Checks whether the two points are near each other, within an @epsilon factor. `true` if the points are near each other a #graphene_point3d_t a #graphene_point3d_t fuzzyness factor Computes the normalization of the vector represented by the coordinates of the given #graphene_point3d_t. a #graphene_point3d_t return location for the normalized #graphene_point3d_t Normalizes the coordinates of a #graphene_point3d_t using the given viewport and clipping planes. The coordinates of the resulting #graphene_point3d_t will be in the [ -1, 1 ] range. a #graphene_point3d_t a #graphene_rect_t representing a viewport the coordinate of the near clipping plane, or 0 for the default near clipping plane the coordinate of the far clipping plane, or 1 for the default far clipping plane the return location for the normalized #graphene_point3d_t Scales the coordinates of the given #graphene_point3d_t by the given @factor. a #graphene_point3d_t the scaling factor return location for the scaled point Stores the coordinates of a #graphene_point3d_t into a #graphene_vec3_t. a #graphene_point3d_t return location for a #graphene_vec3_t Retrieves a constant point with all three coordinates set to 0. a zero point A 4 vertex quadrilateral, as represented by four #graphene_point_t. The contents of a #graphene_quad_t are private and should never be accessed directly. Allocates a new #graphene_quad_t instance. The contents of the returned instance are undefined. the newly created #graphene_quad_t instance Computes the bounding rectangle of @q and places it into @r. a #graphene_quad_t return location for a #graphene_rect_t Checks if the given #graphene_quad_t contains the given #graphene_point_t. `true` if the point is inside the #graphene_quad_t a #graphene_quad_t a #graphene_point_t Frees the resources allocated by graphene_quad_alloc() a #graphene_quad_t Retrieves the point of a #graphene_quad_t at the given index. a #graphene_point_t a #graphene_quad_t the index of the point to retrieve Initializes a #graphene_quad_t with the given points. the initialized #graphene_quad_t the #graphene_quad_t to initialize the first point of the quadrilateral the second point of the quadrilateral the third point of the quadrilateral the fourth point of the quadrilateral Initializes a #graphene_quad_t using an array of points. the initialized #graphene_quad_t the #graphene_quad_t to initialize an array of 4 #graphene_point_t Initializes a #graphene_quad_t using the four corners of the given #graphene_rect_t. the initialized #graphene_quad_t the #graphene_quad_t to initialize a #graphene_rect_t A quaternion. The contents of the #graphene_quaternion_t structure are private and should never be accessed directly. Allocates a new #graphene_quaternion_t. The contents of the returned value are undefined. the newly allocated #graphene_quaternion_t Adds two #graphene_quaternion_t @a and @b. a #graphene_quaternion_t a #graphene_quaternion_t the result of the operation Computes the dot product of two #graphene_quaternion_t. the value of the dot products a #graphene_quaternion_t a #graphene_quaternion_t Checks whether the given quaternions are equal. `true` if the quaternions are equal a #graphene_quaternion_t a #graphene_quaternion_t Releases the resources allocated by graphene_quaternion_alloc(). a #graphene_quaternion_t Initializes a #graphene_quaternion_t using the given four values. the initialized quaternion a #graphene_quaternion_t the first component of the quaternion the second component of the quaternion the third component of the quaternion the fourth component of the quaternion Initializes a #graphene_quaternion_t using an @angle on a specific @axis. the initialized quaternion a #graphene_quaternion_t the rotation on a given axis, in degrees the axis of rotation, expressed as a vector Initializes a #graphene_quaternion_t using the values of the [Euler angles](http://en.wikipedia.org/wiki/Euler_angles) on each axis. See also: graphene_quaternion_init_from_euler() the initialized quaternion a #graphene_quaternion_t rotation angle on the X axis (yaw), in degrees rotation angle on the Y axis (pitch), in degrees rotation angle on the Z axis (roll), in degrees Initializes a #graphene_quaternion_t using the given #graphene_euler_t. the initialized #graphene_quaternion_t the #graphene_quaternion_t to initialize a #graphene_euler_t Initializes a #graphene_quaternion_t using the rotation components of a transformation matrix. the initialized quaternion a #graphene_quaternion_t a #graphene_matrix_t Initializes a #graphene_quaternion_t with the values from @src. the initialized quaternion a #graphene_quaternion_t a #graphene_quaternion_t Initializes a #graphene_quaternion_t using the values of the [Euler angles](http://en.wikipedia.org/wiki/Euler_angles) on each axis. See also: graphene_quaternion_init_from_euler() the initialized quaternion a #graphene_quaternion_t rotation angle on the X axis (yaw), in radians rotation angle on the Y axis (pitch), in radians rotation angle on the Z axis (roll), in radians Initializes a #graphene_quaternion_t with the values from @src. the initialized quaternion a #graphene_quaternion_t a #graphene_vec4_t Initializes a #graphene_quaternion_t using the identity transformation. the initialized quaternion a #graphene_quaternion_t Inverts a #graphene_quaternion_t, and returns the conjugate quaternion of @q. a #graphene_quaternion_t return location for the inverted quaternion Multiplies two #graphene_quaternion_t @a and @b. a #graphene_quaternion_t a #graphene_quaternion_t the result of the operation Normalizes a #graphene_quaternion_t. a #graphene_quaternion_t return location for the normalized quaternion Scales all the elements of a #graphene_quaternion_t @q using the given scalar factor. a #graphene_quaternion_t a scaling factor the result of the operation Interpolates between the two given quaternions using a spherical linear interpolation, or [SLERP](http://en.wikipedia.org/wiki/Slerp), using the given interpolation @factor. a #graphene_quaternion_t a #graphene_quaternion_t the linear interpolation factor return location for the interpolated quaternion Converts a quaternion into an @angle, @axis pair. a #graphene_quaternion_t return location for the angle, in degrees return location for the rotation axis Converts a #graphene_quaternion_t to its corresponding rotations on the [Euler angles](http://en.wikipedia.org/wiki/Euler_angles) on each axis. a #graphene_quaternion_t return location for the rotation angle on the X axis (yaw), in degrees return location for the rotation angle on the Y axis (pitch), in degrees return location for the rotation angle on the Z axis (roll), in degrees Converts a quaternion into a transformation matrix expressing the rotation defined by the #graphene_quaternion_t. a #graphene_quaternion_t a #graphene_matrix_t Converts a #graphene_quaternion_t to its corresponding rotations on the [Euler angles](http://en.wikipedia.org/wiki/Euler_angles) on each axis. a #graphene_quaternion_t return location for the rotation angle on the X axis (yaw), in radians return location for the rotation angle on the Y axis (pitch), in radians return location for the rotation angle on the Z axis (roll), in radians Copies the components of a #graphene_quaternion_t into a #graphene_vec4_t. a #graphene_quaternion_t return location for a #graphene_vec4_t Initializes a #graphene_rect_t when declaring it. the X coordinate of the origin the Y coordinate of the origin the width the height A ray emitted from an origin in a given direction. The contents of the `graphene_ray_t` structure are private, and should not be modified directly. Allocates a new #graphene_ray_t structure. The contents of the returned structure are undefined. the newly allocated #graphene_ray_t. Use graphene_ray_free() to free the resources allocated by this function Checks whether the two given #graphene_ray_t are equal. `true` if the given rays are equal a #graphene_ray_t a #graphene_ray_t Frees the resources allocated by graphene_ray_alloc(). a #graphene_ray_t Computes the point on the given #graphene_ray_t that is closest to the given point @p. a #graphene_ray_t a #graphene_point3d_t return location for the closest point3d Retrieves the direction of the given #graphene_ray_t. a #graphene_ray_t return location for the direction Computes the distance of the origin of the given #graphene_ray_t from the given plane. If the ray does not intersect the plane, this function returns `INFINITY`. the distance of the origin of the ray from the plane a #graphene_ray_t a #graphene_plane_t Computes the distance of the closest approach between the given #graphene_ray_t @r and the point @p. The closest approach to a ray from a point is the distance between the point and the projection of the point on the ray itself. the distance of the point a #graphene_ray_t a #graphene_point3d_t Retrieves the origin of the given #graphene_ray_t. a #graphene_ray_t return location for the origin Retrieves the coordinates of a point at the distance @t along the given #graphene_ray_t. a #graphene_ray_t the distance along the ray return location for the position Initializes the given #graphene_ray_t using the given @origin and @direction values. the initialized ray the #graphene_ray_t to initialize the origin of the ray the direction vector Initializes the given #graphene_ray_t using the origin and direction values of another #graphene_ray_t. the initialized ray the #graphene_ray_t to initialize a #graphene_ray_t Initializes the given #graphene_ray_t using the given vectors. the initialized ray the #graphene_ray_t to initialize a #graphene_vec3_t a #graphene_vec3_t Intersects the given #graphene_ray_t @r with the given #graphene_box_t @b. the type of intersection a #graphene_ray_t a #graphene_box_t the distance of the point on the ray that intersects the box Intersects the given #graphene_ray_t @r with the given #graphene_sphere_t @s. the type of intersection a #graphene_ray_t a #graphene_sphere_t the distance of the point on the ray that intersects the sphere Intersects the given #graphene_ray_t @r with the given #graphene_triangle_t @t. the type of intersection a #graphene_ray_t a #graphene_triangle_t the distance of the point on the ray that intersects the triangle Checks whether the given #graphene_ray_t @r intersects the given #graphene_box_t @b. See also: graphene_ray_intersect_box() `true` if the ray intersects the box a #graphene_ray_t a #graphene_box_t Checks if the given #graphene_ray_t @r intersects the given #graphene_sphere_t @s. See also: graphene_ray_intersect_sphere() `true` if the ray intersects the sphere a #graphene_ray_t a #graphene_sphere_t Checks whether the given #graphene_ray_t @r intersects the given #graphene_triangle_t @b. See also: graphene_ray_intersect_triangle() `true` if the ray intersects the triangle a #graphene_ray_t a #graphene_triangle_t The type of intersection. No intersection The ray is entering the intersected object The ray is leaving the intersected object The location and size of a rectangle region. The width and height of a #graphene_rect_t can be negative; for instance, a #graphene_rect_t with an origin of [ 0, 0 ] and a size of [ 10, 10 ] is equivalent to a #graphene_rect_t with an origin of [ 10, 10 ] and a size of [ -10, -10 ]. Application code can normalize rectangles using graphene_rect_normalize(); this function will ensure that the width and height of a rectangle are positive values. All functions taking a #graphene_rect_t as an argument will internally operate on a normalized copy; all functions returning a #graphene_rect_t will always return a normalized rectangle. the coordinates of the origin of the rectangle the size of the rectangle Checks whether a #graphene_rect_t contains the given coordinates. `true` if the rectangle contains the point a #graphene_rect_t a #graphene_point_t Checks whether a #graphene_rect_t fully contains the given rectangle. `true` if the rectangle @a fully contains @b a #graphene_rect_t a #graphene_rect_t Checks whether the two given rectangle are equal. `true` if the rectangles are equal a #graphene_rect_t a #graphene_rect_t Expands a #graphene_rect_t to contain the given #graphene_point_t. a #graphene_rect_t a #graphene_point_t return location for the expanded rectangle Frees the resources allocated by graphene_rect_alloc(). a #graphene_rect_t Compute the area of given normalized rectangle. the area of the normalized rectangle a #graphene_rect_t Retrieves the coordinates of the bottom-left corner of the given rectangle. a #graphene_rect_t return location for a #graphene_point_t Retrieves the coordinates of the bottom-right corner of the given rectangle. a #graphene_rect_t return location for a #graphene_point_t Retrieves the coordinates of the center of the given rectangle. a #graphene_rect_t return location for a #graphene_point_t Retrieves the normalized height of the given rectangle. the normalized height of the rectangle a #graphene_rect_t Retrieves the coordinates of the top-left corner of the given rectangle. a #graphene_rect_t return location for a #graphene_point_t Retrieves the coordinates of the top-right corner of the given rectangle. a #graphene_rect_t return location for a #graphene_point_t Computes the four vertices of a #graphene_rect_t. a #graphene_rect_t return location for an array of 4 #graphene_vec2_t Retrieves the normalized width of the given rectangle. the normalized width of the rectangle a #graphene_rect_t Retrieves the normalized X coordinate of the origin of the given rectangle. the normalized X coordinate of the rectangle a #graphene_rect_t Retrieves the normalized Y coordinate of the origin of the given rectangle. the normalized Y coordinate of the rectangle a #graphene_rect_t Initializes the given #graphene_rect_t with the given values. This function will implicitly normalize the #graphene_rect_t before returning. the initialized rectangle a #graphene_rect_t the X coordinate of the @graphene_rect_t.origin the Y coordinate of the @graphene_rect_t.origin the width of the @graphene_rect_t.size the height of the @graphene_rect_t.size Initializes @r using the given @src rectangle. This function will implicitly normalize the #graphene_rect_t before returning. the initialized rectangle a #graphene_rect_t a #graphene_rect_t Changes the given rectangle to be smaller, or larger depending on the given inset parameters. To create an inset rectangle, use positive @d_x or @d_y values; to create a larger, encompassing rectangle, use negative @d_x or @d_y values. The origin of the rectangle is offset by @d_x and @d_y, while the size is adjusted by `(2 * @d_x, 2 * @d_y)`. If @d_x and @d_y are positive values, the size of the rectangle is decreased; if @d_x and @d_y are negative values, the size of the rectangle is increased. If the size of the resulting inset rectangle has a negative width or height then the size will be set to zero. the inset rectangle a #graphene_rect_t the horizontal inset the vertical inset Changes the given rectangle to be smaller, or larger depending on the given inset parameters. To create an inset rectangle, use positive @d_x or @d_y values; to create a larger, encompassing rectangle, use negative @d_x or @d_y values. The origin of the rectangle is offset by @d_x and @d_y, while the size is adjusted by `(2 * @d_x, 2 * @d_y)`. If @d_x and @d_y are positive values, the size of the rectangle is decreased; if @d_x and @d_y are negative values, the size of the rectangle is increased. If the size of the resulting inset rectangle has a negative width or height then the size will be set to zero. a #graphene_rect_t the horizontal inset the vertical inset return location for the inset rectangle Linearly interpolates the origin and size of the two given rectangles. a #graphene_rect_t a #graphene_rect_t the linear interpolation factor return location for the interpolated rectangle Computes the intersection of the two given rectangles. ![](rectangle-intersection.png) The intersection in the image above is the blue outline. If the two rectangles do not intersect, @res will contain a degenerate rectangle with origin in (0, 0) and a size of 0. `true` if the two rectangles intersect a #graphene_rect_t a #graphene_rect_t return location for a #graphene_rect_t Normalizes the passed rectangle. This function ensures that the size of the rectangle is made of positive values, and that the origin is the top-left corner of the rectangle. the normalized rectangle a #graphene_rect_t Normalizes the passed rectangle. This function ensures that the size of the rectangle is made of positive values, and that the origin is in the top-left corner of the rectangle. a #graphene_rect_t the return location for the normalized rectangle Offsets the origin by @d_x and @d_y. The size of the rectangle is unchanged. the offset rectangle a #graphene_rect_t the horizontal offset the vertical offset Offsets the origin of the given rectangle by @d_x and @d_y. The size of the rectangle is left unchanged. a #graphene_rect_t the horizontal offset the vertical offset return location for the offset rectangle Rounds the origin and size of the given rectangle to their nearest integer values; the rounding is guaranteed to be large enough to have an area bigger or equal to the original rectangle, but might not fully contain its extents. Use graphene_rect_round_extents() in case you need to round to a rectangle that covers fully the original one. This function is the equivalent of calling `floor` on the coordinates of the origin, and `ceil` on the size. Use graphene_rect_round_extents() instead a #graphene_rect_t return location for the rounded rectangle Rounds the origin of the given rectangle to its nearest integer value and and recompute the size so that the rectangle is large enough to contain all the conrners of the original rectangle. This function is the equivalent of calling `floor` on the coordinates of the origin, and recomputing the size calling `ceil` on the bottom-right coordinates. If you want to be sure that the rounded rectangle completely covers the area that was covered by the original rectangle — i.e. you want to cover the area including all its corners — this function will make sure that the size is recomputed taking into account the ceiling of the coordinates of the bottom-right corner. If the difference between the original coordinates and the coordinates of the rounded rectangle is greater than the difference between the original size and and the rounded size, then the move of the origin would not be compensated by a move in the anti-origin, leaving the corners of the original rectangle outside the rounded one. a #graphene_rect_t return location for the rectangle with rounded extents Rounds the origin and the size of the given rectangle to their nearest integer values; the rounding is guaranteed to be large enough to contain the original rectangle. Use graphene_rect_round() instead the pixel-aligned rectangle. a #graphene_rect_t Scales the size and origin of a rectangle horizontaly by @s_h, and vertically by @s_v. The result @res is normalized. a #graphene_rect_t horizontal scale factor vertical scale factor return location for the scaled rectangle Computes the union of the two given rectangles. ![](rectangle-union.png) The union in the image above is the blue outline. a #graphene_rect_t a #graphene_rect_t return location for a #graphene_rect_t Allocates a new #graphene_rect_t. The contents of the returned rectangle are undefined. the newly allocated rectangle Returns a degenerate rectangle with origin fixed at (0, 0) and a size of 0, 0. a fixed rectangle Initializes a #graphene_size_t with the given sizes when declaring it, e.g.: |[<!-- language="C" --> graphene_size_t size = GRAPHENE_SIZE_INIT (100.f, 100.f); ]| the width the height A size. the width the height Allocates a new #graphene_size_t. The contents of the returned value are undefined. the newly allocated #graphene_size_t Checks whether the two give #graphene_size_t are equal. `true` if the sizes are equal a #graphene_size_t a #graphene_size_t Frees the resources allocated by graphene_size_alloc(). a #graphene_size_t Initializes a #graphene_size_t using the given @width and @height. the initialized #graphene_size_t a #graphene_size_t the width the height Initializes a #graphene_size_t using the width and height of the given @src. the initialized #graphene_size_t a #graphene_size_t a #graphene_size_t Linearly interpolates the two given #graphene_size_t using the given interpolation @factor. a #graphene_size_t a #graphene_size_t the linear interpolation factor return location for the interpolated size Scales the components of a #graphene_size_t using the given @factor. a #graphene_size_t the scaling factor return location for the scaled size A constant pointer to a zero #graphene_size_t, useful for equality checks and interpolations. a constant size A sphere, represented by its center and radius. Allocates a new #graphene_sphere_t. The contents of the newly allocated structure are undefined. the newly allocated #graphene_sphere_t. Use graphene_sphere_free() to free the resources allocated by this function Checks whether the given @point is contained in the volume of a #graphene_sphere_t. `true` if the sphere contains the point a #graphene_sphere_t a #graphene_point3d_t Computes the distance of the given @point from the surface of a #graphene_sphere_t. the distance of the point a #graphene_sphere_t a #graphene_point3d_t Checks whether two #graphene_sphere_t are equal. `true` if the spheres are equal a #graphene_sphere_t a #graphene_sphere_t Frees the resources allocated by graphene_sphere_alloc(). a #graphene_sphere_t Computes the bounding box capable of containing the given #graphene_sphere_t. a #graphene_sphere_t return location for the bounding box Retrieves the coordinates of the center of a #graphene_sphere_t. a #graphene_sphere_t return location for the coordinates of the center Retrieves the radius of a #graphene_sphere_t. a #graphene_sphere_t Initializes the given #graphene_sphere_t with the given @center and @radius. the initialized #graphene_sphere_t the #graphene_sphere_t to initialize the coordinates of the center of the sphere, or %NULL for a center in (0, 0, 0) the radius of the sphere Initializes the given #graphene_sphere_t using the given array of 3D coordinates so that the sphere includes them. The center of the sphere can either be specified, or will be center of the 3D volume that encompasses all @points. the initialized #graphene_sphere_t the #graphene_sphere_t to initialize the number of #graphene_point3d_t in the @points array an array of #graphene_point3d_t the center of the sphere Initializes the given #graphene_sphere_t using the given array of 3D coordinates so that the sphere includes them. The center of the sphere can either be specified, or will be center of the 3D volume that encompasses all @vectors. the initialized #graphene_sphere_t the #graphene_sphere_t to initialize the number of #graphene_vec3_t in the @vectors array an array of #graphene_vec3_t the center of the sphere Checks whether the sphere has a zero radius. `true` if the sphere is empty a #graphene_sphere_t Translates the center of the given #graphene_sphere_t using the @point coordinates as the delta of the translation. a #graphene_sphere_t the coordinates of the translation return location for the translated sphere A triangle. Allocates a new #graphene_triangle_t. The contents of the returned structure are undefined. the newly allocated #graphene_triangle_t structure. Use graphene_triangle_free() to free the resources allocated by this function Checks whether the given triangle @t contains the point @p. `true` if the point is inside the triangle a #graphene_triangle_t a #graphene_point3d_t Checks whether the two given #graphene_triangle_t are equal. `true` if the triangles are equal a #graphene_triangle_t a #graphene_triangle_t Frees the resources allocated by graphene_triangle_alloc(). a #graphene_triangle_t Computes the area of the given #graphene_triangle_t. the area of the triangle a #graphene_triangle_t Computes the [barycentric coordinates](http://en.wikipedia.org/wiki/Barycentric_coordinate_system) of the given point @p. The point @p must lie on the same plane as the triangle @t; if the point is not coplanar, the result of this function is undefined. If we place the origin in the coordinates of the triangle's A point, the barycentric coordinates are `u`, which is on the AC vector; and `v` which is on the AB vector: ![](triangle-barycentric.png) The returned #graphene_vec2_t contains the following values, in order: - `res.x = u` - `res.y = v` `true` if the barycentric coordinates are valid a #graphene_triangle_t a #graphene_point3d_t return location for the vector with the barycentric coordinates Computes the bounding box of the given #graphene_triangle_t. a #graphene_triangle_t return location for the box Computes the coordinates of the midpoint of the given #graphene_triangle_t. The midpoint G is the [centroid](https://en.wikipedia.org/wiki/Centroid#Triangle_centroid) of the triangle, i.e. the intersection of its medians. a #graphene_triangle_t return location for the coordinates of the midpoint Computes the normal vector of the given #graphene_triangle_t. a #graphene_triangle_t return location for the normal vector Computes the plane based on the vertices of the given #graphene_triangle_t. a #graphene_triangle_t return location for the plane Retrieves the three vertices of the given #graphene_triangle_t and returns their coordinates as #graphene_point3d_t. a #graphene_triangle_t return location for the coordinates of the first vertex return location for the coordinates of the second vertex return location for the coordinates of the third vertex Computes the UV coordinates of the given point @p. The point @p must lie on the same plane as the triangle @t; if the point is not coplanar, the result of this function is undefined. If @p is %NULL, the point will be set in (0, 0, 0). The UV coordinates will be placed in the @res vector: - `res.x = u` - `res.y = v` See also: graphene_triangle_get_barycoords() `true` if the coordinates are valid a #graphene_triangle_t a #graphene_point3d_t the UV coordinates of the first point the UV coordinates of the second point the UV coordinates of the third point a vector containing the UV coordinates of the given point @p Retrieves the three vertices of the given #graphene_triangle_t. a #graphene_triangle_t return location for the first vertex return location for the second vertex return location for the third vertex Initializes a #graphene_triangle_t using the three given arrays of floating point values, each representing the coordinates of a point in 3D space. the initialized #graphene_triangle_t the #graphene_triangle_t to initialize an array of 3 floating point values an array of 3 floating point values an array of 3 floating point values Initializes a #graphene_triangle_t using the three given 3D points. the initialized #graphene_triangle_t the #graphene_triangle_t to initialize a #graphene_point3d_t a #graphene_point3d_t a #graphene_point3d_t Initializes a #graphene_triangle_t using the three given vectors. the initialized #graphene_triangle_t the #graphene_triangle_t to initialize a #graphene_vec3_t a #graphene_vec3_t a #graphene_vec3_t Evaluates to the number of components of a #graphene_vec2_t. This symbol is useful when declaring a C array of floating point values to be used with graphene_vec2_init_from_float() and graphene_vec2_to_float(), e.g. |[ float v[GRAPHENE_VEC2_LEN]; // vec is defined elsewhere graphene_vec2_to_float (&vec, v); for (int i = 0; i < GRAPHENE_VEC2_LEN; i++) fprintf (stdout, "component %d: %g\n", i, v[i]); ]| Evaluates to the number of components of a #graphene_vec3_t. This symbol is useful when declaring a C array of floating point values to be used with graphene_vec3_init_from_float() and graphene_vec3_to_float(), e.g. |[ float v[GRAPHENE_VEC3_LEN]; // vec is defined elsewhere graphene_vec3_to_float (&vec, v); for (int i = 0; i < GRAPHENE_VEC2_LEN; i++) fprintf (stdout, "component %d: %g\n", i, v[i]); ]| Evaluates to the number of components of a #graphene_vec4_t. This symbol is useful when declaring a C array of floating point values to be used with graphene_vec4_init_from_float() and graphene_vec4_to_float(), e.g. |[ float v[GRAPHENE_VEC4_LEN]; // vec is defined elsewhere graphene_vec4_to_float (&vec, v); for (int i = 0; i < GRAPHENE_VEC4_LEN; i++) fprintf (stdout, "component %d: %g\n", i, v[i]); ]| A structure capable of holding a vector with two dimensions, x and y. The contents of the #graphene_vec2_t structure are private and should never be accessed directly. Allocates a new #graphene_vec2_t structure. The contents of the returned structure are undefined. Use graphene_vec2_init() to initialize the vector. the newly allocated #graphene_vec2_t structure. Use graphene_vec2_free() to free the resources allocated by this function. Adds each component of the two passed vectors and places each result into the components of @res. a #graphene_vec2_t a #graphene_vec2_t return location for the result Divides each component of the first operand @a by the corresponding component of the second operand @b, and places the results into the vector @res. a #graphene_vec2_t a #graphene_vec2_t return location for the result Computes the dot product of the two given vectors. the dot product of the vectors a #graphene_vec2_t a #graphene_vec2_t Checks whether the two given #graphene_vec2_t are equal. `true` if the two vectors are equal, and false otherwise a #graphene_vec2_t a #graphene_vec2_t Frees the resources allocated by @v a #graphene_vec2_t Retrieves the X component of the #graphene_vec2_t. the value of the X component a #graphene_vec2_t Retrieves the Y component of the #graphene_vec2_t. the value of the Y component a #graphene_vec2_t Initializes a #graphene_vec2_t using the given values. This function can be called multiple times. the initialized vector a #graphene_vec2_t the X field of the vector the Y field of the vector Initializes @v with the contents of the given array. the initialized vector a #graphene_vec2_t an array of floating point values with at least two elements Copies the contents of @src into @v. the initialized vector a #graphene_vec2_t a #graphene_vec2_t Linearly interpolates @v1 and @v2 using the given @factor. a #graphene_vec2_t a #graphene_vec2_t the interpolation factor the interpolated vector Computes the length of the given vector. the length of the vector a #graphene_vec2_t Compares the two given vectors and places the maximum values of each component into @res. a #graphene_vec2_t a #graphene_vec2_t the resulting vector Compares the two given vectors and places the minimum values of each component into @res. a #graphene_vec2_t a #graphene_vec2_t the resulting vector Multiplies each component of the two passed vectors and places each result into the components of @res. a #graphene_vec2_t a #graphene_vec2_t return location for the result Compares the two given #graphene_vec2_t vectors and checks whether their values are within the given @epsilon. `true` if the two vectors are near each other a #graphene_vec2_t a #graphene_vec2_t the threshold between the two vectors Negates the given #graphene_vec2_t. a #graphene_vec2_t return location for the result vector Computes the normalized vector for the given vector @v. a #graphene_vec2_t return location for the normalized vector Multiplies all components of the given vector with the given scalar @factor. a #graphene_vec2_t the scalar factor return location for the result vector Subtracts from each component of the first operand @a the corresponding component of the second operand @b and places each result into the components of @res. a #graphene_vec2_t a #graphene_vec2_t return location for the result Stores the components of @v into an array. a #graphene_vec2_t return location for an array of floating point values with at least 2 elements Retrieves a constant vector with (1, 1) components. the one vector Retrieves a constant vector with (1, 0) components. the X axis vector Retrieves a constant vector with (0, 1) components. the Y axis vector Retrieves a constant vector with (0, 0) components. the zero vector A structure capable of holding a vector with three dimensions: x, y, and z. The contents of the #graphene_vec3_t structure are private and should never be accessed directly. Allocates a new #graphene_vec3_t structure. The contents of the returned structure are undefined. Use graphene_vec3_init() to initialize the vector. the newly allocated #graphene_vec3_t structure. Use graphene_vec3_free() to free the resources allocated by this function. Adds each component of the two given vectors. a #graphene_vec3_t a #graphene_vec3_t return location for the resulting vector Computes the cross product of the two given vectors. a #graphene_vec3_t a #graphene_vec3_t return location for the resulting vector Divides each component of the first operand @a by the corresponding component of the second operand @b, and places the results into the vector @res. a #graphene_vec3_t a #graphene_vec3_t return location for the resulting vector Computes the dot product of the two given vectors. the value of the dot product a #graphene_vec3_t a #graphene_vec3_t Checks whether the two given #graphene_vec3_t are equal. `true` if the two vectors are equal, and false otherwise a #graphene_vec3_t a #graphene_vec3_t Frees the resources allocated by @v a #graphene_vec3_t Retrieves the first component of the given vector @v. the value of the first component of the vector a #graphene_vec3_t Creates a #graphene_vec2_t that contains the first and second components of the given #graphene_vec3_t. a #graphene_vec3_t return location for a #graphene_vec2_t Creates a #graphene_vec3_t that contains the first two components of the given #graphene_vec3_t, and the third component set to 0. a #graphene_vec3_t return location for a #graphene_vec3_t Converts a #graphene_vec3_t in a #graphene_vec4_t using 0.0 as the value for the fourth component of the resulting vector. a #graphene_vec3_t return location for the vector Converts a #graphene_vec3_t in a #graphene_vec4_t using 1.0 as the value for the fourth component of the resulting vector. a #graphene_vec3_t return location for the vector Converts a #graphene_vec3_t in a #graphene_vec4_t using @w as the value of the fourth component of the resulting vector. a #graphene_vec3_t the value of the W component return location for the vector Retrieves the second component of the given vector @v. the value of the second component of the vector a #graphene_vec3_t Retrieves the third component of the given vector @v. the value of the third component of the vector a #graphene_vec3_t Initializes a #graphene_vec3_t using the given values. This function can be called multiple times. a pointer to the initialized vector a #graphene_vec3_t the X field of the vector the Y field of the vector the Z field of the vector Initializes a #graphene_vec3_t with the values from an array. the initialized vector a #graphene_vec3_t an array of 3 floating point values Initializes a #graphene_vec3_t with the values of another #graphene_vec3_t. the initialized vector a #graphene_vec3_t a #graphene_vec3_t Linearly interpolates @v1 and @v2 using the given @factor. a #graphene_vec3_t a #graphene_vec3_t the interpolation factor the interpolated vector Retrieves the length of the given vector @v. the value of the length of the vector a #graphene_vec3_t Compares each component of the two given vectors and creates a vector that contains the maximum values. a #graphene_vec3_t a #graphene_vec3_t return location for the result vector Compares each component of the two given vectors and creates a vector that contains the minimum values. a #graphene_vec3_t a #graphene_vec3_t return location for the result vector Multiplies each component of the two given vectors. a #graphene_vec3_t a #graphene_vec3_t return location for the resulting vector Compares the two given #graphene_vec3_t vectors and checks whether their values are within the given @epsilon. `true` if the two vectors are near each other a #graphene_vec3_t a #graphene_vec3_t the threshold between the two vectors Negates the given #graphene_vec3_t. a #graphene_vec3_t return location for the result vector Normalizes the given #graphene_vec3_t. a #graphene_vec3_t return location for the normalized vector Multiplies all components of the given vector with the given scalar @factor. a #graphene_vec3_t the scalar factor return location for the result vector Subtracts from each component of the first operand @a the corresponding component of the second operand @b and places each result into the components of @res. a #graphene_vec3_t a #graphene_vec3_t return location for the resulting vector Copies the components of a #graphene_vec3_t into the given array. a #graphene_vec3_t return location for an array of floating point values Provides a constant pointer to a vector with three components, all sets to 1. a constant vector Provides a constant pointer to a vector with three components with values set to (1, 0, 0). a constant vector Provides a constant pointer to a vector with three components with values set to (0, 1, 0). a constant vector Provides a constant pointer to a vector with three components with values set to (0, 0, 1). a constant vector Provides a constant pointer to a vector with three components, all sets to 0. a constant vector A structure capable of holding a vector with four dimensions: x, y, z, and w. The contents of the #graphene_vec4_t structure are private and should never be accessed directly. Allocates a new #graphene_vec4_t structure. The contents of the returned structure are undefined. Use graphene_vec4_init() to initialize the vector. the newly allocated #graphene_vec4_t structure. Use graphene_vec4_free() to free the resources allocated by this function. Adds each component of the two given vectors. a #graphene_vec4_t a #graphene_vec4_t return location for the resulting vector Divides each component of the first operand @a by the corresponding component of the second operand @b, and places the results into the vector @res. a #graphene_vec4_t a #graphene_vec4_t return location for the resulting vector Computes the dot product of the two given vectors. the value of the dot product a #graphene_vec4_t a #graphene_vec4_t Checks whether the two given #graphene_vec4_t are equal. `true` if the two vectors are equal, and false otherwise a #graphene_vec4_t a #graphene_vec4_t Frees the resources allocated by @v a #graphene_vec4_t Retrieves the value of the fourth component of the given #graphene_vec4_t. the value of the fourth component a #graphene_vec4_t Retrieves the value of the first component of the given #graphene_vec4_t. the value of the first component a #graphene_vec4_t Creates a #graphene_vec2_t that contains the first two components of the given #graphene_vec4_t. a #graphene_vec4_t return location for a #graphene_vec2_t Creates a #graphene_vec3_t that contains the first three components of the given #graphene_vec4_t. a #graphene_vec4_t return location for a graphene_vec3_t Retrieves the value of the second component of the given #graphene_vec4_t. the value of the second component a #graphene_vec4_t Retrieves the value of the third component of the given #graphene_vec4_t. the value of the third component a #graphene_vec4_t Initializes a #graphene_vec4_t using the given values. This function can be called multiple times. a pointer to the initialized vector a #graphene_vec4_t the X field of the vector the Y field of the vector the Z field of the vector the W field of the vector Initializes a #graphene_vec4_t with the values inside the given array. the initialized vector a #graphene_vec4_t an array of four floating point values Initializes a #graphene_vec4_t using the components of a #graphene_vec2_t and the values of @z and @w. the initialized vector a #graphene_vec4_t a #graphene_vec2_t the value for the third component of @v the value for the fourth component of @v Initializes a #graphene_vec4_t using the components of a #graphene_vec3_t and the value of @w. the initialized vector a #graphene_vec4_t a #graphene_vec3_t the value for the fourth component of @v Initializes a #graphene_vec4_t using the components of another #graphene_vec4_t. the initialized vector a #graphene_vec4_t a #graphene_vec4_t Linearly interpolates @v1 and @v2 using the given @factor. a #graphene_vec4_t a #graphene_vec4_t the interpolation factor the interpolated vector Computes the length of the given #graphene_vec4_t. the length of the vector a #graphene_vec4_t Compares each component of the two given vectors and creates a vector that contains the maximum values. a #graphene_vec4_t a #graphene_vec4_t return location for the result vector Compares each component of the two given vectors and creates a vector that contains the minimum values. a #graphene_vec4_t a #graphene_vec4_t return location for the result vector Multiplies each component of the two given vectors. a #graphene_vec4_t a #graphene_vec4_t return location for the resulting vector Compares the two given #graphene_vec4_t vectors and checks whether their values are within the given @epsilon. `true` if the two vectors are near each other a #graphene_vec4_t a #graphene_vec4_t the threshold between the two vectors Negates the given #graphene_vec4_t. a #graphene_vec4_t return location for the result vector Normalizes the given #graphene_vec4_t. a #graphene_vec4_t return location for the normalized vector Multiplies all components of the given vector with the given scalar @factor. a #graphene_vec4_t the scalar factor return location for the result vector Subtracts from each component of the first operand @a the corresponding component of the second operand @b and places each result into the components of @res. a #graphene_vec4_t a #graphene_vec4_t return location for the resulting vector Stores the components of the given #graphene_vec4_t into an array of floating point values. a #graphene_vec4_t return location for an array of floating point values Retrieves a pointer to a #graphene_vec4_t with all its components set to 1. a constant vector Retrieves a pointer to a #graphene_vec4_t with its components set to (0, 0, 0, 1). a constant vector Retrieves a pointer to a #graphene_vec4_t with its components set to (1, 0, 0, 0). a constant vector Retrieves a pointer to a #graphene_vec4_t with its components set to (0, 1, 0, 0). a constant vector Retrieves a pointer to a #graphene_vec4_t with its components set to (0, 0, 1, 0). a constant vector Retrieves a pointer to a #graphene_vec4_t with all its components set to 0. a constant vector A degenerate #graphene_box2d_t that can only be expanded. The returned value is owned by Graphene and should not be modified or freed. a #graphene_box2d_t A degenerate #graphene_box2d_t that cannot be expanded. The returned value is owned by Graphene and should not be modified or freed. a #graphene_box2d_t A #graphene_box2d_t with the minimum vertex set at (-1, -1) and the maximum vertex set at (0, 0). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box2d_t A #graphene_box2d_t with the minimum vertex set at (0, 0) and the maximum vertex set at (1, 1). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box2d_t A #graphene_box2d_t with the minimum vertex set at (-1, -1) and the maximum vertex set at (1, 1). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box2d_t A #graphene_box2d_t with both the minimum and maximum vertices set at (0, 0). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box2d_t A degenerate #graphene_box_t that can only be expanded. The returned value is owned by Graphene and should not be modified or freed. a #graphene_box_t A degenerate #graphene_box_t that cannot be expanded. The returned value is owned by Graphene and should not be modified or freed. a #graphene_box_t A #graphene_box_t with the minimum vertex set at (-1, -1, -1) and the maximum vertex set at (0, 0, 0). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box_t A #graphene_box_t with the minimum vertex set at (0, 0, 0) and the maximum vertex set at (1, 1, 1). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box_t A #graphene_box_t with the minimum vertex set at (-1, -1, -1) and the maximum vertex set at (1, 1, 1). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box_t A #graphene_box_t with both the minimum and maximum vertices set at (0, 0, 0). The returned value is owned by Graphene and should not be modified or freed. a #graphene_box_t #graphene_box_t provides a representation of an axis aligned minimum bounding box using the coordinates of its minimum and maximum vertices. #graphene_box2d_t provides a representation of an axis aligned minimum bounding box in two dimensions using the coordinates of its minimum and maximum vertices. #graphene_box2d_t is available since Graphene 1.2. The #graphene_euler_t structure defines a rotation along three axes using three angles. It also optionally can describe the order of the rotations. [Euler's rotation theorem](https://en.wikipedia.org/wiki/Euler%27s_rotation_theorem) states that, in three-dimensional space, any displacement of a rigid body such that a point on the rigid body remains fixed, is equivalent to a single rotation about some axis that runs through the fixed point. The angles on each axis can be placed in a vector of three components—α, β, and γ—called the *Euler angle vector*. Each rotation described by these components results in a rotation matrix: |[ rot(α) = A rot(β) = B rot(γ) = G ]| The resulting rotation matrix expressed by the Euler angle vector is given by the product of each rotation matrix: |[ G × B × A = R ]| In order to specify the meaning of an Euler angle vector, we need to assign each axis of rotation to the corresponding α, β, and γ components, for instance X, Y, and Z. Additionally, we need to specify whether the rotations move the axes as they are applied, also known as intrinsic, or relative rotations; or if the axes stay fixed and the vectors move within the axis frame, also known as extrinsic, or static rotations. For instance, a static rotation alongside the ZYX axes will be interpreted as relative to extrinsic coordinate axes, and be performed, in order, about the Z, Y, and finally X axis. A relative rotation alongside the ZXZ axes will be interpreted as relative to intrinsic coordinate axes, and be performed, in order, about the Z axis, about the rotated X axis, and finally about the rotated Z axis. Finally, we need to define the direction of the rotation, or the handedness of the coordinate system. In the case of Graphene, the direction is given by the right-hand rule, which means all rotations are counterclockwise. Rotations described Euler angles are typically immediately understandable, compared to rotations expressed using quaternions, but they are susceptible of ["Gimbal lock"](http://en.wikipedia.org/wiki/Gimbal_lock) — the loss of one degree of freedom caused by two axis on the same plane. You typically should use #graphene_euler_t to expose rotation angles in your API, or to store them, but use #graphene_quaternion_t to apply rotations to modelview matrices, or interpolate between initial and final rotation transformations. For more information, see: - http://en.wikipedia.org/wiki/Rotation_matrix - http://en.wikipedia.org/wiki/Euler_angles - http://mathworld.wolfram.com/EulerAngles.html - "Representing Attitude with Euler Angles and Quaternions: A Reference" by James Diebel, 2006 - "Graphics Gems IV", edited by Paul Heckbert, Academic Press, 1994. See also: #graphene_quaternion_t. A #graphene_frustum_t represents a volume of space delimited by planes. It is usually employed to represent the field of view of a camera, and can be used to determine whether an object falls within that view, to efficiently remove invisible objects from the render process. Graphene optionally provides information for using its own types with GObject properties and signals. ## Using Graphene with GObject In order to discover at compile time if Graphene exposes type information for the GType type system, you need to check if the `graphene-gobject-1.0` pkg-config file exists. If you're using Meson to build your project, you can use a typical `dependency()` object, for instance: |[<!-- language="plain" --> graphene_dep = dependency('graphene-gobject-1.0') ]| If you're using Autotools to build your project, you can use the `PKG_CHECK_EXISTS` m4 macro, for instance: |[<!-- language="plain" --> PKG_CHECK_EXISTS([graphene-gobject-1.0], [action-if-found], [action-if-not-found] ]| All the types provided by Graphene are boxed types, which means you will have to use the #GBoxed API when dealing with #GValue, #GParamSpec, and signal marshallers. For instance, to install a property in a #GObject class that uses #graphene_rect_t, you can use: |[<!-- language="C" --> g_object_class_install_property (object_class, PROP_BOUNDS, g_param_spec_boxed ("bounds", "Bounds", "Bounds of an object", GRAPHENE_TYPE_RECT, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); ]| You'll then need to use g_value_set_boxed() and g_value_get_boxed() in order to access the #graphene_rect_t pointer from the #GValue data structure. Whereas for creating a new signal that has a #graphene_point_t parameter you can use: |[<!-- language="C" --> signals[HIT_TEST] = g_signal_new ("hit-test", G_TYPE_FROM_CLASS (object_class), G_SIGNAL_RUN_LAST, 0, g_signal_accumulator_true_handled, NULL, marshal_BOOLEAN__BOXED, G_TYPE_BOOLEAN, 1, GRAPHENE_TYPE_POINT); ]| ## Using Graphene via GObject introspection When using Graphene with another language than C, the GObject Introspection bindings change the type names to the CamelCase version of the C name, minus the `_t` suffix; for instance: * #graphene_point_t becomes `GraphenePoint` * #graphene_point3d_t becomes `GraphenePoint3D` * #graphene_rect_t becomes `GrapheneRect` * #graphene_matrix_t becomes `GrapheneMatrix` There is no direct access for the low level #graphene_simd4f_t and #graphene_simd4x4f_t SIMD types. #graphene_matrix_t is a type that provides a 4x4 square matrix, useful for representing 3D transformations. The matrix is treated as row-major, i.e. it has four vectors (x, y, z, and w) representing rows, and elements of each vector are a column: |[<!-- language="plain" --> ⎡ m.x ⎤ ⎛ x.x x.y x.z x.w ⎞ ⎜ m.y ⎟ -\ ⎜ y.x y.y y.z y.w ⎟ ⎜ m.z ⎟ -/ ⎜ z.x z.y z.z z.w ⎟ ⎣ m.w ⎦ ⎝ w.x w.y w.z w.w ⎠ ]| It is possible to easily convert a #graphene_matrix_t to and from an array of floating point values that can be used with other libraries. The contents of a #graphene_matrix_t are private, and direct access is not possible. You can modify and read the contents of a #graphene_matrix_t only through the provided API. # Conventions # {#conventions} Graphene uses left-multiplication for all its operations on vectors and matrices; in other words, given a matrix `A` and a vector `b`, the result of a multiplication is going to be: |[ res = b × A ]| Multiplying two matrices, on the other hand, will use right-multiplication; given two matrices `A` and `B`, the result of the multiplication is going to be |[ res = A × B ]| as the implementation will multiply each row vector of matrix `A` with the matrix `B` to obtain the new row vectors of the result matrix: |[ res = ⎡ A.x × B ⎤ ⎜ A.y × B ⎟ ⎜ A.z × B ⎟ ⎣ A.w × B ⎦ ]| For more information, see the documentation for #graphene_simd4x4f_t, especially the following functions: - graphene_simd4x4f_vec4_mul() - graphene_simd4x4f_vec3_mul() - graphene_simd4x4f_point3_mul() - graphene_simd4x4f_matrix_mul() #graphene_plane_t is a structure representing a plane that extends infinitely in 3D space, described using the [Hessian normal form](http://mathworld.wolfram.com/HessianNormalForm.html) of a unit length normal vector pointing towards the origin, and a constant distance from the origin along the normal vector. #graphene_point_t is a data structure capable of describing a point with two coordinates: * @graphene_point_t.x * @graphene_point_t.y #graphene_point3d_t is a data structure capable of describing a point with three coordinates: * @graphene_point3d_t.x * @graphene_point3d_t.y * @graphene_point3d_t.z A #graphene_quad_t represents a coplanar, four vertex quadrilateral shape. Quaternions are a mathematical entity that can be used to represent rotation transformations in 3D space; unlike the usual Euler representation with roll, pitch, and yaw, quaternions do not suffer from the so-called ["Gimbal Lock"](http://en.wikipedia.org/wiki/Gimbal_lock) problem. See also: #graphene_euler_t #graphene_ray_t is a structure representing a ray emitted by an origin, identified by a point in 3D space, in a given direction, identified by a vector with 3 components. A common use of #graphene_ray_t is ray-casting to find which objects in a 3D scene are under the coordinates of the pointer. #graphene_rect_t is a type representing a rectangle through an origin #graphene_point_t point and a #graphene_size_t size. ![](rectangle.png) Operations on a #graphene_rect_t will normalize the rectangle, to ensure that the origin is always the top-left corner of the rectangle and that the size is always positive. #graphene_size_t represents a size composed of a @graphene_size_t.width by a @graphene_size_t.height. #graphene_sphere_t provides a representation of a sphere using its center and radius. #graphene_triangle_t represents a triangle in 3D space. Graphene has three vector types, distinguished by their length: 1. #graphene_vec2_t, which holds 2 components x and y 2. #graphene_vec3_t, which holds 3 components x, y, and z 3. #graphene_vec4_t, which holds 4 components x, y, z, and w Each vector type should be treated as an opaque data type. Retrieves a constant point with all three coordinates set to 0. a zero point Returns a point fixed at (0, 0). a fixed point Allocates a new #graphene_rect_t. The contents of the returned rectangle are undefined. the newly allocated rectangle Returns a degenerate rectangle with origin fixed at (0, 0) and a size of 0, 0. a fixed rectangle A constant pointer to a zero #graphene_size_t, useful for equality checks and interpolations. a constant size Retrieves a constant vector with (1, 1) components. the one vector Retrieves a constant vector with (1, 0) components. the X axis vector Retrieves a constant vector with (0, 1) components. the Y axis vector Retrieves a constant vector with (0, 0) components. the zero vector Provides a constant pointer to a vector with three components, all sets to 1. a constant vector Provides a constant pointer to a vector with three components with values set to (1, 0, 0). a constant vector Provides a constant pointer to a vector with three components with values set to (0, 1, 0). a constant vector Provides a constant pointer to a vector with three components with values set to (0, 0, 1). a constant vector Provides a constant pointer to a vector with three components, all sets to 0. a constant vector Retrieves a pointer to a #graphene_vec4_t with all its components set to 1. a constant vector Retrieves a pointer to a #graphene_vec4_t with its components set to (0, 0, 0, 1). a constant vector Retrieves a pointer to a #graphene_vec4_t with its components set to (1, 0, 0, 0). a constant vector Retrieves a pointer to a #graphene_vec4_t with its components set to (0, 1, 0, 0). a constant vector Retrieves a pointer to a #graphene_vec4_t with its components set to (0, 0, 1, 0). a constant vector Retrieves a pointer to a #graphene_vec4_t with all its components set to 0. a constant vector soup3-0.9.0/gir-files/Gsk-4.0.gir000064400000000000000000015146731046102023000143330ustar 00000000000000 The blend modes available for render nodes. The implementation of each blend mode is deferred to the rendering pipeline. See <https://www.w3.org/TR/compositing-1/#blending> for more information on blending and blend modes. The default blend mode, which specifies no blending The source color is multiplied by the destination and replaces the destination Multiplies the complements of the destination and source color values, then complements the result. Multiplies or screens the colors, depending on the destination color value. This is the inverse of hard-list Selects the darker of the destination and source colors Selects the lighter of the destination and source colors Brightens the destination color to reflect the source color Darkens the destination color to reflect the source color Multiplies or screens the colors, depending on the source color value Darkens or lightens the colors, depending on the source color value Subtracts the darker of the two constituent colors from the lighter color Produces an effect similar to that of the difference mode but lower in contrast Creates a color with the hue and saturation of the source color and the luminosity of the destination color Creates a color with the hue of the source color and the saturation and luminosity of the destination color Creates a color with the saturation of the source color and the hue and luminosity of the destination color Creates a color with the luminosity of the source color and the hue and saturation of the destination color A render node applying a blending function between its two child nodes. Creates a `GskRenderNode` that will use @blend_mode to blend the @top node onto the @bottom node. A new `GskRenderNode` The bottom node to be drawn The node to be blended onto the @bottom node The blend mode to use Retrieves the blend mode used by @node. the blend mode a blending `GskRenderNode` Retrieves the bottom `GskRenderNode` child of the @node. the bottom child node a blending `GskRenderNode` Retrieves the top `GskRenderNode` child of the @node. the top child node a blending `GskRenderNode` A render node applying a blur effect to its single child. Creates a render node that blurs the child. a new `GskRenderNode` the child node to blur the blur radius. Must be positive Retrieves the child `GskRenderNode` of the blur @node. the blurred child node a blur `GskRenderNode` Retrieves the blur radius of the @node. the blur radius a blur `GskRenderNode` A render node for a border. Creates a `GskRenderNode` that will stroke a border rectangle inside the given @outline. The 4 sides of the border can have different widths and colors. A new `GskRenderNode` a `GskRoundedRect` describing the outline of the border the stroke width of the border on the top, right, bottom and left side respectively. the color used on the top, right, bottom and left side. Retrieves the colors of the border. an array of 4 `GdkRGBA` structs for the top, right, bottom and left color of the border a `GskRenderNode` for a border Retrieves the outline of the border. the outline of the border a `GskRenderNode` for a border Retrieves the stroke widths of the border. an array of 4 floats for the top, right, bottom and left stroke width of the border, respectively a `GskRenderNode` for a border A Broadway based renderer. See [class@Gsk.Renderer]. Creates a new Broadway renderer. The Broadway renderer is the default renderer for the broadway backend. It will only work with broadway surfaces, otherwise it will fail the call to gsk_renderer_realize(). This function is only available when GTK was compiled with Broadway support. Broadway will be retired in GTK 5 a new Broadway renderer. A render node for a Cairo surface. Creates a `GskRenderNode` that will render a cairo surface into the area given by @bounds. You can draw to the cairo surface using [method@Gsk.CairoNode.get_draw_context]. A new `GskRenderNode` the rectangle to render to Creates a Cairo context for drawing using the surface associated to the render node. If no surface exists yet, a surface will be created optimized for rendering to @renderer. a Cairo context used for drawing; use cairo_destroy() when done drawing a `GskRenderNode` for a Cairo surface Retrieves the Cairo surface used by the render node. a Cairo surface a `GskRenderNode` for a Cairo surface Renders a GSK rendernode tree with cairo. Since it is using cairo, this renderer cannot support 3D transformations. Creates a new Cairo renderer. The Cairo renderer is the fallback renderer drawing in ways similar to how GTK 3 drew its content. Its primary use is as comparison tool. The Cairo renderer is incomplete. It cannot render 3D transformed content and will instead render an error marker. Its usage should be avoided. a new Cairo renderer. A render node applying a rectangular clip to its single child node. Creates a `GskRenderNode` that will clip the @child to the area given by @clip. A new `GskRenderNode` The node to draw The clip to apply Gets the child node that is getting clipped by the given @node. The child that is getting clipped a clip @GskRenderNode Retrieves the clip rectangle for @node. a clip rectangle a `GskClipNode` A render node controlling the color matrix of its single child node. Creates a `GskRenderNode` that will drawn the @child with @color_matrix. In particular, the node will transform colors by applying pixel = transpose(color_matrix) * pixel + color_offset for every pixel. The transformation operates on unpremultiplied colors, with color components ordered R, G, B, A. A new `GskRenderNode` The node to draw The matrix to apply Values to add to the color Gets the child node that is getting its colors modified by the given @node. The child that is getting its colors modified a color matrix `GskRenderNode` Retrieves the color matrix used by the @node. a 4x4 color matrix a color matrix `GskRenderNode` Retrieves the color offset used by the @node. a color vector a color matrix `GskRenderNode` A render node for a solid color. Creates a `GskRenderNode` that will render the color specified by @rgba into the area given by @bounds. A new `GskRenderNode` a `GdkRGBA` specifying a color the rectangle to render the color into Retrieves the color of the given @node. The value returned by this function will not be correct if the render node was created for a non-sRGB color. the color of the node a `GskRenderNode` A color stop in a gradient node. the offset of the color stop the color at the given offset Specifies a transfer function for a color component to be applied while rendering. The available functions include linear, piecewise-linear, gamma and step functions. Note that the transfer function is applied to un-premultiplied values, and all results are clamped to the [0, 1] range. Creates a new component transfer that applies a step function. The new value is computed as C' = values[k] where k is the smallest value such that k / n <= C < (k + 1) / n <figure> <picture> <source srcset="discrete-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Component transfer: discrete" src="discrete-light.png"> </picture> </figure> a new `GskComponentTransfer` Number of values Values Creates a new component transfer that applies a gamma transform. The new value is computed as C' = amp * pow (C, exp) + ofs <figure> <picture> <source srcset="gamma-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Component transfer: gamma" src="gamma-light.png"> </picture> </figure> a new `GskComponentTransfer` Amplitude Exponent Offset Creates a new component transfer that doesn't change the component value. <figure> <picture> <source srcset="identity-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Component transfer: identity" src="identity-light.png"> </picture> </figure> a new `GskComponentTransfer` Creates a new component transfer that limits the values of the component to `n` levels. The new value is computed as C' = (floor (C * n) + 0.5) / n <figure> <picture> <source srcset="levels-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Component transfer: levels" src="levels-light.png"> </picture> </figure> a new `GskComponentTransfer` Number of levels Creates a new component transfer that applies a linear transform. The new value is computed as C' = C * m + b <figure> <picture> <source srcset="linear-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Component transfer: linear" src="linear-light.png"> </picture> </figure> a new `GskComponentTransfer` Slope Offset Creates a new component transfer that applies a piecewise linear function. The new value is computed as C' = values[k] + (C - k / (n - 1)) * n * (values[k + 1] - values[k]) where k is the smallest value such that k / (n - 1) <= C < (k + 1) / (n - 1) <figure> <picture> <source srcset="table-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Component transfer: table" src="table-light.png"> </picture> </figure> a new `GskComponentTransfer` Number of values Values Creates a copy of @other. a newly allocated copy of @other a component transfer Frees a component transfer. a component transfer Compares two component transfers for equality. true if @self and @other are equal a component transfer another component transfer A render node for applying a `GskComponentTransfer` for each color component of the child node. Creates a render node that will apply component transfers to a child node. A new `GskRenderNode` The child to apply component transfers to transfer for the red component transfer for the green component transfer for the blue component transfer for the alpha component Gets the child node that is getting drawn by the given @node. the child `GskRenderNode` a component transfer `GskRenderNode` Gets the component transfer for one of the components. the `GskComponentTransfer` a component transfer `GskRenderNode` the component to get the transfer for A render node that uses Porter/Duff compositing operators to combine its child with the background. Creates a `GskRenderNode` that will composite the child onto the background with the given operator wherever the mask is set. Note that various operations can modify the background outside of the child's bounds, so the mask may cause visual changes outside of the child. A new `GskRenderNode` The child to composite The mask where the compositing will apply The compositing operator Gets the child node that is getting composited by the given @node. the child `GskRenderNode` a composite `GskRenderNode` Gets the mask node that describes the region where the compositing applies. the mask `GskRenderNode` a composite `GskRenderNode` Gets the compositing operator used by this node. The compositing operator a composite `GskRenderNode` A render node for a conic gradient. Creates a `GskRenderNode` that draws a conic gradient. The conic gradient starts around @center in the direction of @rotation. A rotation of 0 means that the gradient points up. Color stops are then added clockwise. A new `GskRenderNode` the bounds of the node the center of the gradient the rotation of the gradient in degrees a pointer to an array of `GskColorStop` defining the gradient. The offsets of all color stops must be increasing. The first stop's offset must be >= 0 and the last stop's offset must be <= 1. the number of elements in @color_stops Retrieves the angle for the gradient in radians, normalized in [0, 2 * PI]. The angle is starting at the top and going clockwise, as expressed in the css specification: angle = 90 - gsk_conic_gradient_node_get_rotation() the angle for the gradient a `GskRenderNode` for a conic gradient Retrieves the center pointer for the gradient. the center point for the gradient a `GskRenderNode` for a conic gradient Retrieves the color stops in the gradient. the color stops in the gradient a `GskRenderNode` for a conic gradient the number of color stops in the returned array Retrieves the number of color stops in the gradient. the number of color stops a `GskRenderNode` for a conic gradient Retrieves the rotation for the gradient in degrees. the rotation for the gradient a `GskRenderNode` for a conic gradient A render node that can contain other render nodes. Creates a new `GskRenderNode` instance for holding the given @children. The new node will acquire a reference to each of the children. the new `GskRenderNode` The children of the node Number of children in the @children array Gets one of the children of @container. the @idx'th child of @container a container `GskRenderNode` the position of the child to get Retrieves the number of direct children of @node. the number of children of the `GskRenderNode` a container `GskRenderNode` A render node that copies the current state of the rendering canvas so a [class@Gsk.PasteNode] can draw it. Creates a `GskRenderNode` that copies the current rendering canvas for playback by paste nodes that are part of the child. A new `GskRenderNode` The child Gets the child node that is getting drawn by the given @node. the child `GskRenderNode` a copy `GskRenderNode` The corner indices used by `GskRoundedRect`. The top left corner The top right corner The bottom right corner The bottom left corner A render node cross fading between two child nodes. Creates a `GskRenderNode` that will do a cross-fade between @start and @end. A new `GskRenderNode` The start node to be drawn The node to be cross_fadeed onto the @start node How far the fade has progressed from start to end. The value will be clamped to the range [0 ... 1] Retrieves the child `GskRenderNode` at the end of the cross-fade. a `GskRenderNode` a cross-fading `GskRenderNode` Retrieves the progress value of the cross fade. the progress value, between 0 and 1 a cross-fading `GskRenderNode` Retrieves the child `GskRenderNode` at the beginning of the cross-fade. a `GskRenderNode` a cross-fading `GskRenderNode` A render node that emits a debugging message when drawing its child node. Creates a `GskRenderNode` that will add debug information about the given @child. Adding this node has no visual effect. A new `GskRenderNode` The child to add debug info for The debug message Gets the child node that is getting drawn by the given @node. the child `GskRenderNode` a debug `GskRenderNode` Gets the debug message that was set on this node The debug message a debug `GskRenderNode` A render node filling the area given by [struct@Gsk.Path] and [enum@Gsk.FillRule] with the child node. Creates a `GskRenderNode` that will fill the @child in the area given by @path and @fill_rule. A new `GskRenderNode` The node to fill the area with The path describing the area to fill The fill rule to use Gets the child node that is getting drawn by the given @node. The child that is getting drawn a fill `GskRenderNode` Retrieves the fill rule used to determine how the path is filled. a `GskFillRule` a fill `GskRenderNode` Retrieves the path used to describe the area filled with the contents of the @node. a `GskPath` a fill `GskRenderNode` Specifies how paths are filled. Whether or not a point is included in the fill is determined by taking a ray from that point to infinity and looking at intersections with the path. The ray can be in any direction, as long as it doesn't pass through the end point of a segment or have a tricky intersection such as intersecting tangent to the path. (Note that filling is not actually implemented in this way. This is just a description of the rule that is applied.) New entries may be added in future versions. If the path crosses the ray from left-to-right, counts +1. If the path crosses the ray from right to left, counts -1. (Left and right are determined from the perspective of looking along the ray from the starting point.) If the total count is non-zero, the point will be filled. Counts the total number of intersections, without regard to the orientation of the contour. If the total number of intersections is odd, the point will be filled. Renders a GSK rendernode tree with OpenGL. See [class@Gsk.Renderer]. Creates an instance of the GL renderer. a GL renderer Implements a fragment shader using GLSL. A fragment shader gets the coordinates being rendered as input and produces the pixel values for that particular pixel. Additionally, the shader can declare a set of other input arguments, called uniforms (as they are uniform over all the calls to your shader in each instance of use). A shader can also receive up to 4 textures that it can use as input when producing the pixel data. `GskGLShader` is usually used with gtk_snapshot_push_gl_shader() to produce a [class@Gsk.GLShaderNode] in the rendering hierarchy, and then its input textures are constructed by rendering the child nodes to textures before rendering the shader node itself. (You can pass texture nodes as children if you want to directly use a texture as input). The actual shader code is GLSL code that gets combined with some other code into the fragment shader. Since the exact capabilities of the GPU driver differs between different OpenGL drivers and hardware, GTK adds some defines that you can use to ensure your GLSL code runs on as many drivers as it can. If the OpenGL driver is GLES, then the shader language version is set to 100, and GSK_GLES will be defined in the shader. Otherwise, if the OpenGL driver does not support the 3.2 core profile, then the shader will run with language version 110 for GL2 and 130 for GL3, and GSK_LEGACY will be defined in the shader. If the OpenGL driver supports the 3.2 code profile, it will be used, the shader language version is set to 150, and GSK_GL3 will be defined in the shader. The main function the shader must implement is: ```glsl void mainImage(out vec4 fragColor, in vec2 fragCoord, in vec2 resolution, in vec2 uv) ``` Where the input @fragCoord is the coordinate of the pixel we're currently rendering, relative to the boundary rectangle that was specified in the `GskGLShaderNode`, and @resolution is the width and height of that rectangle. This is in the typical GTK coordinate system with the origin in the top left. @uv contains the u and v coordinates that can be used to index a texture at the corresponding point. These coordinates are in the [0..1]x[0..1] region, with 0, 0 being in the lower left corder (which is typical for OpenGL). The output @fragColor should be a RGBA color (with premultiplied alpha) that will be used as the output for the specified pixel location. Note that this output will be automatically clipped to the clip region of the glshader node. In addition to the function arguments the shader can define up to 4 uniforms for textures which must be called u_textureN (i.e. u_texture1 to u_texture4) as well as any custom uniforms you want of types int, uint, bool, float, vec2, vec3 or vec4. All textures sources contain premultiplied alpha colors, but if some there are outer sources of colors there is a gsk_premultiply() helper to compute premultiplication when needed. Note that GTK parses the uniform declarations, so each uniform has to be on a line by itself with no other code, like so: ```glsl uniform float u_time; uniform vec3 u_color; uniform sampler2D u_texture1; uniform sampler2D u_texture2; ``` GTK uses the "gsk" namespace in the symbols it uses in the shader, so your code should not use any symbols with the prefix gsk or GSK. There are some helper functions declared that you can use: ```glsl vec4 GskTexture(sampler2D sampler, vec2 texCoords); ``` This samples a texture (e.g. u_texture1) at the specified coordinates, and contains some helper ifdefs to ensure that it works on all OpenGL versions. You can compile the shader yourself using [method@Gsk.GLShader.compile], otherwise the GSK renderer will do it when it handling the glshader node. If errors occurs, the returned @error will include the glsl sources, so you can see what GSK was passing to the compiler. You can also set GSK_DEBUG=shaders in the environment to see the sources and other relevant information about all shaders that GSK is handling. # An example shader ```glsl uniform float position; uniform sampler2D u_texture1; uniform sampler2D u_texture2; void mainImage(out vec4 fragColor, in vec2 fragCoord, in vec2 resolution, in vec2 uv) { vec4 source1 = GskTexture(u_texture1, uv); vec4 source2 = GskTexture(u_texture2, uv); fragColor = position * source1 + (1.0 - position) * source2; } ``` This feature was deprecated in GTK 4.16 after the new rendering infrastructure introduced in 4.14 did not support it. The lack of Vulkan integration would have made it a very hard feature to support. If you want to use OpenGL directly, you should look at [GtkGLArea](../gtk4/class.GLArea.html), which uses a different approach and is still well-supported. Creates a `GskGLShader` that will render pixels using the specified code. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. A new `GskGLShader` GLSL sourcecode for the shader, as a `GBytes` Creates a `GskGLShader` that will render pixels using the specified code. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. A new `GskGLShader` path to a resource that contains the GLSL sourcecode for the shader Tries to compile the @shader for the given @renderer. If there is a problem, this function returns %FALSE and reports an error. You should use this function before relying on the shader for rendering and use a fallback with a simpler shader or without shaders if it fails. Note that this will modify the rendering state (for example change the current GL context) and requires the renderer to be set up. This means that the widget has to be realized. Commonly you want to call this from the realize signal of a widget, or during widget snapshot. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. %TRUE on success, %FALSE if an error occurred a `GskGLShader` a `GskRenderer` Looks for a uniform by the name @name, and returns the index of the uniform, or -1 if it was not found. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The index of the uniform, or -1 a `GskGLShader` uniform name Formats the uniform data as needed for feeding the named uniforms values into the shader. The argument list is a list of pairs of names, and values for the types that match the declared uniforms (i.e. double/int/guint/gboolean for primitive values and `graphene_vecN_t *` for vecN uniforms). Any uniforms of the shader that are not included in the argument list are zero-initialized. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. A newly allocated block of data which can be passed to [ctor@Gsk.GLShaderNode.new]. a `GskGLShader` name-Value pairs for the uniforms of @shader, ending with a %NULL name Formats the uniform data as needed for feeding the named uniforms values into the shader. The argument list is a list of pairs of names, and values for the types that match the declared uniforms (i.e. double/int/guint/gboolean for primitive values and `graphene_vecN_t *` for vecN uniforms). It is an error to pass a uniform name that is not declared by the shader. Any uniforms of the shader that are not included in the argument list are zero-initialized. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. A newly allocated block of data which can be passed to [ctor@Gsk.GLShaderNode.new]. a `GskGLShader` name-Value pairs for the uniforms of @shader, ending with a %NULL name Gets the value of the uniform @idx in the @args block. The uniform must be of bool type. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The value a `GskGLShader` uniform arguments index of the uniform Gets the value of the uniform @idx in the @args block. The uniform must be of float type. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The value a `GskGLShader` uniform arguments index of the uniform Gets the value of the uniform @idx in the @args block. The uniform must be of int type. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The value a `GskGLShader` uniform arguments index of the uniform Gets the value of the uniform @idx in the @args block. The uniform must be of uint type. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The value a `GskGLShader` uniform arguments index of the uniform Gets the value of the uniform @idx in the @args block. The uniform must be of vec2 type. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. a `GskGLShader` uniform arguments index of the uniform location to store the uniform value in Gets the value of the uniform @idx in the @args block. The uniform must be of vec3 type. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. a `GskGLShader` uniform arguments index of the uniform location to store the uniform value in Gets the value of the uniform @idx in the @args block. The uniform must be of vec4 type. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. a `GskGLShader` uniform arguments index of the uniform location to store set the uniform value in Get the size of the data block used to specify arguments for this shader. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The size of the data block a `GskGLShader` Returns the number of textures that the shader requires. This can be used to check that the a passed shader works in your usecase. It is determined by looking at the highest u_textureN value that the shader defines. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The number of texture inputs required by @shader a `GskGLShader` Get the number of declared uniforms for this shader. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The number of declared uniforms a `GskGLShader` Gets the resource path for the GLSL sourcecode being used to render this shader. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The resource path for the shader a `GskGLShader` Gets the GLSL sourcecode being used to render this shader. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The source code for the shader a `GskGLShader` Get the name of the declared uniform for this shader at index @idx. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The name of the declared uniform a `GskGLShader` index of the uniform Get the offset into the data block where data for this uniforms is stored. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The data offset a `GskGLShader` index of the uniform Get the type of the declared uniform for this shader at index @idx. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The type of the declared uniform a `GskGLShader` index of the uniform Resource containing the source code for the shader. If the shader source is not coming from a resource, this will be %NULL. The source code for the shader, as a `GBytes`. A render node using a GL shader when drawing its children nodes. Creates a `GskRenderNode` that will render the given @shader into the area given by @bounds. The @args is a block of data to use for uniform input, as per types and offsets defined by the @shader. Normally this is generated by [method@Gsk.GLShader.format_args] or [struct@Gsk.ShaderArgsBuilder]. See [class@Gsk.GLShader] for details about how the shader should be written. All the children will be rendered into textures (if they aren't already `GskTextureNodes`, which will be used directly). These textures will be sent as input to the shader. If the renderer doesn't support GL shaders, or if there is any problem when compiling the shader, then the node will draw pink. You should use [method@Gsk.GLShader.compile] to ensure the @shader will work for the renderer before using it. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. A new `GskRenderNode` the `GskGLShader` the rectangle to render the shader into Arguments for the uniforms array of child nodes, these will be rendered to textures and used as input. Length of @children (currently the GL backend supports up to 4 children) Gets args for the node. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. A `GBytes` with the uniform arguments a `GskRenderNode` for a gl shader Gets one of the children. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. the @idx'th child of @node a `GskRenderNode` for a gl shader the position of the child to get Returns the number of children GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The number of children a `GskRenderNode` for a gl shader Gets shader code for the node. the `GskGLShader` shader a `GskRenderNode` for a gl shader Defines the types of the uniforms that `GskGLShaders` declare. It defines both what the type is called in the GLSL shader code, and what the corresponding C type is on the Gtk side. No type, used for uninitialized or unspecified values. A float uniform A GLSL int / gint32 uniform A GLSL uint / guint32 uniform A GLSL bool / gboolean uniform A GLSL vec2 / graphene_vec2_t uniform A GLSL vec3 / graphene_vec3_t uniform A GLSL vec4 / graphene_vec4_t uniform A render node for an inset shadow. Creates a `GskRenderNode` that will render an inset shadow into the box given by @outline. A new `GskRenderNode` outline of the region containing the shadow color of the shadow horizontal offset of shadow vertical offset of shadow how far the shadow spreads towards the inside how much blur to apply to the shadow Retrieves the blur radius to apply to the shadow. the blur radius, in pixels a `GskRenderNode` for an inset shadow Retrieves the color of the inset shadow. The value returned by this function will not be correct if the render node was created for a non-sRGB color. the color of the shadow a `GskRenderNode` for an inset shadow Retrieves the horizontal offset of the inset shadow. an offset, in pixels a `GskRenderNode` for an inset shadow Retrieves the vertical offset of the inset shadow. an offset, in pixels a `GskRenderNode` for an inset shadow Retrieves the outline rectangle of the inset shadow. a rounded rectangle a `GskRenderNode` for an inset shadow Retrieves how much the shadow spreads inwards. the size of the shadow, in pixels a `GskRenderNode` for an inset shadow These flags describe the types of isolations possible with a [class@Gsk.IsolationNode]. More isolation options may be added in the future. No isolation is defined. If the background should be made available. If the background is not available, future operations will be rendered to a transparent background and added to the existing background later. If copies should be available to paste nodes. If copies are not available, paste nodes can only paste from copies that are made inside the isolated contents. Isolate everything. This will include features that are added in the future. A render node that isolates its child from surrounding rendernodes. Creates a `GskRenderNode` that isolates the drawing operations of the child from surrounding ones. You can express "everything but these flags" in a forward compatible way by using bit math: `GSK_ISOLATION_ALL & ~(GSK_ISOLATION_BACKGROUND | GSK_ISOLATION_COPY_PASTE)` will isolate everything but background and copy/paste. For the available isolations, see [flags@Gsk.Isolation]. A new `GskRenderNode` The child features to isolate Gets the child node that is getting drawn by the given @node. the child `GskRenderNode` an isolation `GskRenderNode` Gets the isolation features that are enforced by this node. the isolation features an isolation `GskRenderNode` Specifies how to render the start and end points of contours or dashes when stroking. The default line cap style is `GSK_LINE_CAP_BUTT`. New entries may be added in future versions. <figure> <picture> <source srcset="caps-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Line Cap Styles" src="caps-light.png"> </picture> <figcaption>GSK_LINE_CAP_BUTT, GSK_LINE_CAP_ROUND, GSK_LINE_CAP_SQUARE</figcaption> </figure> Start and stop the line exactly at the start and end point Use a round ending, the center of the circle is the start or end point use squared ending, the center of the square is the start or end point Specifies how to render the junction of two lines when stroking. The default line join style is `GSK_LINE_JOIN_MITER`. New entries may be added in future versions. <figure> <picture> <source srcset="join-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Line Join Styles" src="join-light.png"> </picture> <figcaption>GSK_LINE_JOINT_MITER, GSK_LINE_JOINT_ROUND, GSK_LINE_JOIN_BEVEL</figcaption> </figure> Use a sharp angled corner Use a round join, the center of the circle is the join point use a cut-off join, the join is cut off at half the line width from the joint point A render node for a linear gradient. Creates a `GskRenderNode` that will create a linear gradient from the given points and color stops, and render that into the area given by @bounds. A new `GskRenderNode` the rectangle to render the linear gradient into the point at which the linear gradient will begin the point at which the linear gradient will finish a pointer to an array of `GskColorStop` defining the gradient. The offsets of all color stops must be increasing. The first stop's offset must be >= 0 and the last stop's offset must be <= 1. the number of elements in @color_stops Retrieves the color stops in the gradient. the color stops in the gradient a `GskRenderNode` for a linear gradient the number of color stops in the returned array Retrieves the final point of the linear gradient. the final point a `GskRenderNode` for a linear gradient Retrieves the number of color stops in the gradient. the number of color stops a `GskRenderNode` for a linear gradient Retrieves the initial point of the linear gradient. the initial point a `GskRenderNode` for a linear gradient The mask modes available for mask nodes. Use the alpha channel of the mask Use the inverted alpha channel of the mask Use the luminance of the mask, multiplied by mask alpha Use the inverted luminance of the mask, multiplied by mask alpha A render node masking one child node with another. Creates a `GskRenderNode` that will mask a given node by another. The @mask_mode determines how the 'mask values' are derived from the colors of the @mask. Applying the mask consists of multiplying the 'mask value' with the alpha of the source. A new `GskRenderNode` The source node to be drawn The node to be used as mask The mask mode to use Retrieves the mask `GskRenderNode` child of the @node. the mask child node a mask `GskRenderNode` Retrieves the mask mode used by @node. the mask mode a blending `GskRenderNode` Retrieves the source `GskRenderNode` child of the @node. the source child node a mask `GskRenderNode` A GL based renderer. See [class@Gsk.Renderer]. Same as gsk_gl_renderer_new(). Use gsk_gl_renderer_new() a GL renderer A render node controlling the opacity of its single child node. Creates a `GskRenderNode` that will drawn the @child with reduced @opacity. A new `GskRenderNode` The node to draw The opacity to apply Gets the child node that is getting opacityed by the given @node. The child that is getting opacityed a `GskRenderNode` for an opacity Gets the transparency factor for an opacity node. the opacity factor a `GskRenderNode` for an opacity A render node for an outset shadow. Creates a `GskRenderNode` that will render an outset shadow around the box given by @outline. A new `GskRenderNode` outline of the region surrounded by shadow color of the shadow horizontal offset of shadow vertical offset of shadow how far the shadow spreads towards the inside how much blur to apply to the shadow Retrieves the blur radius of the shadow. the blur radius, in pixels a `GskRenderNode` for an outset shadow Retrieves the color of the outset shadow. The value returned by this function will not be correct if the render node was created for a non-sRGB color. a color a `GskRenderNode` for an outset shadow Retrieves the horizontal offset of the outset shadow. an offset, in pixels a `GskRenderNode` for an outset shadow Retrieves the vertical offset of the outset shadow. an offset, in pixels a `GskRenderNode` for an outset shadow Retrieves the outline rectangle of the outset shadow. a rounded rectangle a `GskRenderNode` for an outset shadow Retrieves how much the shadow spreads outwards. the size of the shadow, in pixels a `GskRenderNode` for an outset shadow Type of callback that is called when an error occurs during node deserialization. start of the error location end of the error location the error user data A location in a parse buffer. the offset of the location in the parse buffer, as bytes the offset of the location in the parse buffer, as characters the line of the location in the parse buffer the position in the line, as bytes the position in the line, as characters A render node for a paste. Creates a `GskRenderNode` that will paste copied contents. A new `GskRenderNode` the rectangle to render the paste into the index of which copy to paste. This will usually be 0. Retrieves the index of the copy that should be pasted. the index of the copy to paste. a `GskRenderNode` Describes lines and curves that are more complex than simple rectangles. Paths can used for rendering (filling or stroking) and for animations (e.g. as trajectories). `GskPath` is an immutable, opaque, reference-counted struct. After creation, you cannot change the types it represents. Instead, new `GskPath` objects have to be created. The [struct@Gsk.PathBuilder] structure is meant to help in this endeavor. Conceptually, a path consists of zero or more contours (continuous, connected curves), each of which may or may not be closed. Contours are typically constructed from Bézier segments. <picture> <source srcset="path-dark.png" media="(prefers-color-scheme: dark)"> <img alt="A Path" src="path-light.png"> </picture> Returns whether two paths have identical structure. Note that it is possible to construct paths that render identical even though they don't have the same structure. true if @path1 and @path2 have identical structure a path another path Calls @func for every operation of the path. Note that this may only approximate @self, because paths can contain optimizations for various specialized contours, and depending on the @flags, the path may be decomposed into simpler curves than the ones that it contained originally. This function serves two purposes: - When the @flags allow everything, it provides access to the raw, unmodified data of the path. - When the @flags disallow certain operations, it provides an approximation of the path using just the allowed operations. false if @func returned false, true otherwise. a path flags to pass to the foreach function the function to call for operations user data passed to @func Finds intersections between two paths. This function finds intersections between @path1 and @path2, and calls @func for each of them, in increasing order for @path1. If @path2 is not provided or equal to @path1, the function finds non-trivial self-intersections of @path1. When segments of the paths coincide, the callback is called once for the start of the segment, with @GSK_PATH_INTERSECTION_START, and once for the end of the segment, with @GSK_PATH_INTERSECTION_END. Note that other intersections may occur between the start and end of such a segment. If @func returns `FALSE`, the iteration is stopped. `FALSE` if @func returned FALSE`, `TRUE` otherwise. the first path the second path the function to call for intersections user data passed to @func Computes the bounds of the given path. The returned bounds may be larger than necessary, because this function aims to be fast, not accurate. The bounds are guaranteed to contain the path. For accurate bounds, use [method@Gsk.Path.get_tight_bounds]. It is possible that the returned rectangle has 0 width and/or height. This can happen when the path only describes a point or an axis-aligned line. If the path is empty, false is returned and @bounds are set to graphene_rect_zero(). This is different from the case where the path is a single point at the origin, where the @bounds will also be set to the zero rectangle but true will be returned. true if the path has bounds, false if the path is known to be empty and have no bounds a path return location for the bounds Computes the closest point on the path to the given point. If there is no point closer than the given threshold, false is returned. true if @point was set to the closest point on @self, false if no point is closer than @threshold a path the point maximum allowed distance return location for the closest point return location for the distance Gets the end point of the path. An empty path has no points, so false is returned in this case. true if @result was filled a path return location for point Moves @point to the next vertex. An empty path has no points, so false is returned in this case. true if @point was set a path the current point Moves @point to the previous vertex. An empty path has no points, so false is returned in this case. true if @point was set a path the current point Gets the start point of the path. An empty path has no points, so false is returned in this case. true if @result was filled a path return location for point Computes the bounds for stroking the given path with the given parameters. The returned bounds may be larger than necessary, because this function aims to be fast, not accurate. The bounds are guaranteed to contain the area affected by the stroke, including protrusions like miters. true if the path has bounds, false if the path is known to be empty and have no bounds. a path stroke parameters the bounds to fill in Computes the tight bounds of the given path. This function works harder than [method@Gsk.Path.get_bounds] to produce the smallest possible bounds. true if the path has bounds, false if the path is known to be empty and have no bounds a path return location for the bounds Returns whether a point is inside the fill area of a path. Note that this function assumes that filling a contour implicitly closes it. true if @point is inside a path the point to test the fill rule to follow Returns if the path represents a single closed contour. true if the path is closed a path Checks if the path is empty, i.e. contains no lines or curves. true if the path is empty a path Converts the path into a human-readable representation. The string is compatible with (a superset of) [SVG path syntax](https://www.w3.org/TR/SVG11/paths.html#PathData), see [func@Gsk.Path.parse] for a summary of the syntax. a path the string to print into Increases the reference count of a path by one. the passed in `GskPath` a path Appends the path to a cairo context for drawing with Cairo. This may cause some suboptimal conversions to be performed as Cairo does not support all features of `GskPath`. This function does not clear the existing Cairo path. Call cairo_new_path() if you want this. a path a cairo context Converts the path into a human-readable string. You can use this function in a debugger to get a quick overview of the path. This is a wrapper around [method@Gsk.Path.print], see that function for details. a new string for @self a path Decreases the reference count of a path by one. If the resulting reference count is zero, frees the path. a path Constructs a path from a serialized form. The string is expected to be in (a superset of) [SVG path syntax](https://www.w3.org/TR/SVG11/paths.html#PathData), as e.g. produced by [method@Gsk.Path.to_string]. A high-level summary of the syntax: - `M x y` Move to `(x, y)` - `L x y` Add a line from the current point to `(x, y)` - `Q x1 y1 x2 y2` Add a quadratic Bézier from the current point to `(x2, y2)`, with control point `(x1, y1)` - `C x1 y1 x2 y2 x3 y3` Add a cubic Bézier from the current point to `(x3, y3)`, with control points `(x1, y1)` and `(x2, y2)` - `Z` Close the contour by drawing a line back to the start point - `H x` Add a horizontal line from the current point to the given x value - `V y` Add a vertical line from the current point to the given y value - `T x2 y2` Add a quadratic Bézier, using the reflection of the previous segments' control point as control point - `S x2 y2 x3 y3` Add a cubic Bézier, using the reflection of the previous segments' second control point as first control point - `A rx ry r l s x y` Add an elliptical arc from the current point to `(x, y)` with radii rx and ry. See the SVG documentation for how the other parameters influence the arc. - `O x1 y1 x2 y2 w` Add a rational quadratic Bézier from the current point to `(x2, y2)` with control point `(x1, y1)` and weight `w`. All the commands have lowercase variants that interpret coordinates relative to the current point. The `O` command is an extension that is not supported in SVG. a new `GskPath`, or `NULL` if @string could not be parsed a string Constructs `GskPath` objects. A path is constructed like this: ```c GskPath * construct_path (void) { GskPathBuilder *builder; builder = gsk_path_builder_new (); // add contours to the path here return gsk_path_builder_free_to_path (builder); ``` Adding contours to the path can be done in two ways. The easiest option is to use the `gsk_path_builder_add_*` group of functions that add predefined contours to the current path, either common shapes like [method@Gsk.PathBuilder.add_circle] or by adding from other paths like [method@Gsk.PathBuilder.add_path]. The `gsk_path_builder_add_*` methods always add complete contours, and do not use or modify the current point. The other option is to define each line and curve manually with the `gsk_path_builder_*_to` group of functions. You start with a call to [method@Gsk.PathBuilder.move_to] to set the starting point and then use multiple calls to any of the drawing functions to move the pen along the plane. Once you are done, you can call [method@Gsk.PathBuilder.close] to close the path by connecting it back with a line to the starting point. This is similar to how paths are drawn in Cairo. Note that `GskPathBuilder` will reduce the degree of added Bézier curves as much as possible, to simplify rendering. Create a new `GskPathBuilder` object. The resulting builder would create an empty `GskPath`. Use addition functions to add types to it. a new `GskPathBuilder` Adds a Cairo path to the builder. You can use cairo_copy_path() to access the path from a Cairo context. a path builder a path Adds a circle as a new contour. The path is going around the circle in clockwise direction. If @radius is zero, the contour will be a closed point. a path builder the center of the circle the radius of the circle Adds the outlines for the glyphs in @layout to the builder. a path builder the pango layout to add Appends all of @path to the builder. a path builder the path to append Adds a rectangle as a new contour. The path is going around the rectangle in clockwise direction. If the the width or height are 0, the path will be a closed horizontal or vertical line. If both are 0, it'll be a closed dot. a path builder the rectangle to create a path for Appends all of @path to the builder, in reverse order. a path builder the path to append Adds a rounded rectangle as a new contour. The path is going around the rectangle in clockwise direction. a path builder the rounded rect Adds a segment of a path to the builder. If @start is equal to or after @end, the path will first add the segment from @start to the end of the path, and then add the segment from the beginning to @end. If the path is closed, these segments will be connected. Note that this method always adds a path with the given start point and end point. To add a closed path, use [method@Gsk.PathBuilder.add_path]. a path builder the path to take the segment to the point on @path to start at the point on @path to end at Adds an elliptical arc from the current point to @x2, @y2 with @x1, @y1 determining the tangent directions. After this, @x2, @y2 will be the new current point. Note: Two points and their tangents do not determine a unique ellipse, so GSK just picks one. If you need more precise control, use [method@Gsk.PathBuilder.conic_to] or [method@Gsk.PathBuilder.svg_arc_to]. <picture> <source srcset="arc-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Arc To" src="arc-light.png"> </picture> a path builder x coordinate of first control point y coordinate of first control point x coordinate of second control point y coordinate of second control point Ends the current contour with a line back to the start point. Note that this is different from calling [method@Gsk.PathBuilder.line_to] with the start point in that the contour will be closed. A closed contour behaves differently from an open one. When stroking, its start and end point are considered connected, so they will be joined via the line join, and not ended with line caps. a path builder Adds a [conic curve](https://en.wikipedia.org/wiki/Non-uniform_rational_B-spline) from the current point to @x2, @y2 with the given @weight and @x1, @y1 as the control point. The weight determines how strongly the curve is pulled towards the control point. A conic with weight 1 is identical to a quadratic Bézier curve with the same points. Conic curves can be used to draw ellipses and circles. They are also known as rational quadratic Bézier curves. After this, @x2, @y2 will be the new current point. <picture> <source srcset="conic-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Conic To" src="conic-light.png"> </picture> a path builder x coordinate of control point y coordinate of control point x coordinate of the end of the curve y coordinate of the end of the curve weight of the control point, must be greater than zero Adds a [cubic Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve) from the current point to @x3, @y3 with @x1, @y1 and @x2, @y2 as the control points. After this, @x3, @y3 will be the new current point. <picture> <source srcset="cubic-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Cubic To" src="cubic-light.png"> </picture> a path builder x coordinate of first control point y coordinate of first control point x coordinate of second control point y coordinate of second control point x coordinate of the end of the curve y coordinate of the end of the curve Creates a new path from the current state of the builder, and unrefs the builder. the newly created path with all the contours added to the builder a path builder Gets the current point. The current point is used for relative drawing commands and updated after every operation. When the builder is created, the default current point is set to `0, 0`. Note that this is different from cairo, which starts out without a current point. the current point a path builder Implements arc-to according to the HTML Canvas spec. A convenience function that implements the [HTML arc_to](https://html.spec.whatwg.org/multipage/canvas.html#dom-context-2d-arcto-dev) functionality. After this, the current point will be the point where the circle with the given radius touches the line from @x1, @y1 to @x2, @y2. a path builder x coordinate of first control point y coordinate of first control point x coordinate of second control point y coordinate of second control point radius of the circle Draws a line from the current point to @x, @y and makes it the new current point. <picture> <source srcset="line-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Line To" src="line-light.png"> </picture> a path builder x coordinate y coordinate Starts a new contour by placing the pen at @x, @y. If this function is called twice in succession, the first call will result in a contour made up of a single point. The second call will start a new contour. a path builder x coordinate y coordinate Adds a [quadratic Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve) from the current point to @x2, @y2 with @x1, @y1 as the control point. After this, @x2, @y2 will be the new current point. <picture> <source srcset="quad-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Quad To" src="quad-light.png"> </picture> a path builder x coordinate of control point y coordinate of control point x coordinate of the end of the curve y coordinate of the end of the curve Acquires a reference on the given builder. This function is intended primarily for language bindings. `GskPathBuilder` objects should not be kept around. the given path builder with its reference count increased a path builder Adds an elliptical arc from the current point to @x2, @y2 with @x1, @y1 determining the tangent directions. All coordinates are given relative to the current point. This is the relative version of [method@Gsk.PathBuilder.arc_to]. a path builder x coordinate of first control point y coordinate of first control point x coordinate of second control point y coordinate of second control point Adds a [conic curve](https://en.wikipedia.org/wiki/Non-uniform_rational_B-spline) from the current point to @x2, @y2 with the given @weight and @x1, @y1 as the control point. All coordinates are given relative to the current point. This is the relative version of [method@Gsk.PathBuilder.conic_to]. a path builder x offset of control point y offset of control point x offset of the end of the curve y offset of the end of the curve weight of the curve, must be greater than zero Adds a [cubic Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve) from the current point to @x3, @y3 with @x1, @y1 and @x2, @y2 as the control points. All coordinates are given relative to the current point. This is the relative version of [method@Gsk.PathBuilder.cubic_to]. a path builder x offset of first control point y offset of first control point x offset of second control point y offset of second control point x offset of the end of the curve y offset of the end of the curve Implements arc-to according to the HTML Canvas spec. All coordinates are given relative to the current point. This is the relative version of [method@Gsk.PathBuilder.html_arc_to]. a path builder x coordinate of first control point y coordinate of first control point x coordinate of second control point y coordinate of second control point radius of the circle Draws a line from the current point to a point offset from it by @x, @y and makes it the new current point. This is the relative version of [method@Gsk.PathBuilder.line_to]. a path builder x offset y offset Starts a new contour by placing the pen at @x, @y relative to the current point. This is the relative version of [method@Gsk.PathBuilder.move_to]. a path builder x offset y offset Adds a [quadratic Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve) from the current point to @x2, @y2 with @x1, @y1 the control point. All coordinates are given relative to the current point. This is the relative version of [method@Gsk.PathBuilder.quad_to]. a path builder x offset of control point y offset of control point x offset of the end of the curve y offset of the end of the curve Implements arc-to according to the SVG spec. All coordinates are given relative to the current point. This is the relative version of [method@Gsk.PathBuilder.svg_arc_to]. a path builder x radius y radius the rotation of the ellipsis whether to add the large arc whether to sweep in the positive direction x coordinate of the endpoint y coordinate of the endpoint Implements arc-to according to the SVG spec. A convenience function that implements the [SVG arc_to](https://www.w3.org/TR/SVG11/paths.html#PathDataEllipticalArcCommands) functionality. After this, @x, @y will be the new current point. a path builder x radius y radius the rotation of the ellipsis whether to add the large arc whether to sweep in the positive direction x coordinate of the endpoint y coordinate of the endpoint Creates a new path from the given builder. The given `GskPathBuilder` is reset to the initial state once this function returns. Calling this function again on the same builder instance will therefore produce an empty path, not a copy of the same path. This function is intended primarily for language bindings. C code should use [method@Gsk.PathBuilder.free_to_path]. the newly created path with all the contours added to the builder a path builder Releases a reference on the given builder. a path builder Used to pick one of the four tangents at a given point on the path. Note that the directions for @GSK_PATH_FROM_START/@GSK_PATH_TO_END and @GSK_PATH_TO_START/@GSK_PATH_FROM_END will coincide for smooth points. Only sharp turns will exhibit four different directions. <picture> <source srcset="directions-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Path Tangents" src="directions-light.png"> </picture> The tangent in path direction of the incoming side of the path The tangent against path direction of the incoming side of the path The tangent in path direction of the outgoing side of the path The tangent against path direction of the outgoing side of the path Flags that can be passed to gsk_path_foreach() to influence what kinds of operations the path is decomposed into. By default, [method@Gsk.Path.foreach] will only emit a path with all operations flattened to straight lines to allow for maximum compatibility. The only operations emitted will be `GSK_PATH_MOVE`, `GSK_PATH_LINE` and `GSK_PATH_CLOSE`. The default behavior, only allow lines. Allow emission of `GSK_PATH_QUAD` operations Allow emission of `GSK_PATH_CUBIC` operations. Allow emission of `GSK_PATH_CONIC` operations. Type of the callback to iterate through the operations of a path. For each operation, the callback is given the @op itself, the points that the operation is applied to in @pts, and a @weight for conic curves. The @n_pts argument is somewhat redundant, since the number of points can be inferred from the operation. Each contour of the path starts with a @GSK_PATH_MOVE operation. Closed contours end with a @GSK_PATH_CLOSE operation. %TRUE to continue iterating the path, %FALSE to immediately abort and not call the function again. The operation The points of the operation The number of points The weight for conic curves, or unused if not a conic curve The user data provided with the function The values of this enumeration classify intersections between paths. No intersection A normal intersection, where the two paths cross each other The start of a segment where the two paths coincide The end of a segment where the two paths coincide Prototype of the callback to iterate through the intersections of two paths. true to continue iterating, false to stop the iteration and not call the function again the first path the intersection as point on @path1 the second path the intersection as point on @path2 the nature of the intersection user data Performs measurements on paths such as determining the length of the path. Many measuring operations require sampling the path length at intermediate points. Therefore, a `GskPathMeasure` has a tolerance that determines what precision is required for such approximations. A `GskPathMeasure` struct is a reference counted struct and should be treated as opaque. Creates a measure object for the given @path with the default tolerance. a new `GskPathMeasure` representing @path the path to measure Creates a measure object for the given @path and @tolerance. a new `GskPathMeasure` representing @path the path to measure the tolerance for measuring operations Gets the length of the path being measured. The length is cached, so this function does not do any work. the length of the path measured by @self a path measure Returns the path that the measure was created for. the path of @self a path measure Gets the point at the given distance into the path. An empty path has no points, so false is returned in that case. true if @result was set a path measure the distance return location for the point Returns the tolerance that the measure was created with. the tolerance of @self a path measure Increases the reference count of a `GskPathMeasure` by one. the passed in `GskPathMeasure`. a path measure Decreases the reference count of a `GskPathMeasure` by one. If the resulting reference count is zero, frees the object. a path measure Describes the segments of a `GskPath`. More values may be added in the future. A move-to operation, with 1 point describing the target point. A close operation ending the current contour with a line back to the starting point. Two points describe the start and end of the line. A line-to operation, with 2 points describing the start and end point of a straight line. A curve-to operation describing a quadratic Bézier curve with 3 points describing the start point, the control point and the end point of the curve. A curve-to operation describing a cubic Bézier curve with 4 points describing the start point, the two control points and the end point of the curve. A rational quadratic Bézier curve with 3 points describing the start point, control point and end point of the curve. A weight for the curve will be passed, too. Represents a point on a path. It can be queried for properties of the path at that point, such as its tangent or its curvature. To obtain a `GskPathPoint`, use [method@Gsk.Path.get_closest_point], [method@Gsk.Path.get_start_point], [method@Gsk.Path.get_end_point] or [method@Gsk.PathMeasure.get_point]. Note that `GskPathPoint` structs are meant to be stack-allocated, and don't hold a reference to the path object they are obtained from. It is the callers responsibility to keep a reference to the path as long as the `GskPathPoint` is used. Returns whether @point1 is before or after @point2. -1 if @point1 is before @point2, 1 if @point1 is after @point2, 0 if they are equal a path point another path point Copies a path point. the copied point a path point Returns whether the two path points refer to the same location on all paths. Note that the start- and endpoint of a closed contour will compare nonequal according to this definition. Use [method@Gsk.Path.is_closed] to find out if the start- and endpoint of a concrete path refer to the same location. true if @point1 and @point2 are equal a path point another path point Frees a path point copied by [method@Gsk.PathPoint.copy]. a path point Calculates the curvature of the path at the point. Optionally, returns the center of the osculating circle as well. The curvature is the inverse of the radius of the osculating circle. Lines have a curvature of zero (indicating an osculating circle of infinite radius). In this case, the @center is not modified. Circles with a radius of zero have `INFINITY` as curvature Note that certain points on a path may not have a single curvature, such as sharp turns. At such points, there are two curvatures — the (limit of) the curvature of the path going into the point, and the (limit of) the curvature of the path coming out of it. The @direction argument lets you choose which one to get. <picture> <source srcset="curvature-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Osculating circle" src="curvature-light.png"> </picture> the curvature of the path at the given point a path point the path that @point is on the direction for which to return the curvature return location for the center of the osculating circle Returns the distance from the beginning of the path to the point. the distance of @point a point on the path a path measure for the path Gets the position of the point. a path point the path that @point is on Return location for the coordinates of the point Gets the direction of the tangent at a given point. This is a convenience variant of [method@Gsk.PathPoint.get_tangent] that returns the angle between the tangent and the X axis. The angle can e.g. be used in [gtk_snapshot_rotate()](../gtk4/method.Snapshot.rotate.html). the angle between the tangent and the X axis, in degrees a path point the path that @point is on the direction for which to return the rotation Gets the tangent of the path at the point. Note that certain points on a path may not have a single tangent, such as sharp turns. At such points, there are two tangents — the direction of the path going into the point, and the direction coming out of it. The @direction argument lets you choose which one to get. If the path is just a single point (e.g. a circle with radius zero), then the tangent is set to `0, 0`. If you want to orient something in the direction of the path, [method@Gsk.PathPoint.get_rotation] may be more convenient to use. a path point the path that @point is on the direction for which to return the tangent Return location for the tangent at the point GSK_PORTER_DUFF_SOURCE: GSK_PORTER_DUFF_DEST: GSK_PORTER_DUFF_SOURCE_OVER_DEST: GSK_PORTER_DUFF_DEST_OVER_SOURCE: GSK_PORTER_DUFF_SOURCE_IN_DEST: GSK_PORTER_DUFF_DEST_IN_SOURCE: GSK_PORTER_DUFF_SOURCE_OUT_DEST: GSK_PORTER_DUFF_DEST_OUT_SOURCE: GSK_PORTER_DUFF_SOURCE_ATOP_DEST: GSK_PORTER_DUFF_DEST_ATOP_SOURCE: GSK_PORTER_DUFF_XOR: GSK_PORTER_DUFF_CLEAR: The 12 compositing modes defined by the seminal paper by Thomas Porter and Tom Duff. They are used in SVG, PDF and in Cairo with `cairo_operator_t`. Initializes a `GskRoundedRect` when declaring it. All corner sizes will be initialized to 0. the X coordinate of the origin the Y coordinate of the origin the width the height A render node for a radial gradient. Creates a `GskRenderNode` that draws a radial gradient. The radial gradient starts around @center. The size of the gradient is dictated by @hradius in horizontal orientation and by @vradius in vertical orientation. A new `GskRenderNode` the bounds of the node the center of the gradient the horizontal radius the vertical radius a percentage >= 0 that defines the start of the gradient around @center a percentage >= 0 that defines the end of the gradient around @center a pointer to an array of `GskColorStop` defining the gradient. The offsets of all color stops must be increasing. The first stop's offset must be >= 0 and the last stop's offset must be <= 1. the number of elements in @color_stops Retrieves the center pointer for the gradient. the center point for the gradient a `GskRenderNode` for a radial gradient Retrieves the color stops in the gradient. the color stops in the gradient a `GskRenderNode` for a radial gradient the number of color stops in the returned array Retrieves the end value for the gradient. the end value for the gradient a `GskRenderNode` for a radial gradient Retrieves the horizontal radius for the gradient. the horizontal radius for the gradient a `GskRenderNode` for a radial gradient Retrieves the number of color stops in the gradient. the number of color stops a `GskRenderNode` for a radial gradient Retrieves the start value for the gradient. the start value for the gradient a `GskRenderNode` for a radial gradient Retrieves the vertical radius for the gradient. the vertical radius for the gradient a `GskRenderNode` for a radial gradient The basic block in a scene graph to be rendered using [class@Gsk.Renderer]. Each node has a parent, except the top-level node; each node may have children nodes. Each node has an associated drawing surface, which has the size of the rectangle set when creating it. Render nodes are meant to be transient; once they have been associated to a [class@Gsk.Renderer] it's safe to release any reference you have on them. All [class@Gsk.RenderNode]s are immutable, you can only specify their properties during construction. Loads data previously created via [method@Gsk.RenderNode.serialize]. For a discussion of the supported format, see that function. a new render node the bytes containing the data callback on parsing errors user_data for @error_func Draws the contents of a render node on a cairo context. Typically, you'll use this function to implement fallback rendering of render nodes on an intermediate Cairo context, instead of using the drawing context associated to a [class@Gdk.Surface]'s rendering buffer. For advanced nodes that cannot be supported using Cairo, in particular for nodes doing 3D operations, this function may fail. a render node cairo context to draw to Retrieves the boundaries of the @node. The node will not draw outside of its boundaries. a render node return location for the boundaries Gets a list of all children nodes of the rendernode. Keep in mind that for various rendernodes, their children have different semantics, like the mask vs the source of a mask node. If you care about thse semantics, don't use this function, use the specific getters instead. The children the render node the number of items in the returned array Returns the type of the render node. the type of @node a render node Gets an opaque rectangle inside the node that GTK can determine to be fully opaque. There is no guarantee that this is indeed the largest opaque rectangle or that regions outside the rectangle are not opaque. This function is a best effort with that goal. The rectangle will be fully contained in the bounds of the node. true if part or all of the rendernode is opaque, false if no opaque region could be found. a render node return location for the opaque rect Acquires a reference on the given `GskRenderNode`. the render node with an additional reference a render node Serializes the @node for later deserialization via gsk_render_node_deserialize(). No guarantees are made about the format used other than that the same version of GTK will be able to deserialize the result of a call to gsk_render_node_serialize() and gsk_render_node_deserialize() will correctly reject files it cannot open that were created with previous versions of GTK. The intended use of this functions is testing, benchmarking and debugging. The format is not meant as a permanent storage format. a `GBytes` representing the node. a `GskRenderNode` Releases a reference on the given `GskRenderNode`. If the reference was the last, the resources associated to the @node are freed. a render node This function is equivalent to calling [method@Gsk.RenderNode.serialize] followed by [func@GLib.file_set_contents]. See those two functions for details on the arguments. It is mostly intended for use inside a debugger to quickly dump a render node to a file for later inspection. true if saving was successful a render node the file to save it to The type of a node determines what the node is rendering. Error type. No node will ever have this type. A node containing a stack of children A node drawing a `cairo_surface_t` A node drawing a single color rectangle A node drawing a linear gradient A node drawing a repeating linear gradient A node drawing a radial gradient A node drawing a repeating radial gradient A node drawing a conic gradient A node stroking a border around an area A node drawing a `GdkTexture` A node drawing an inset shadow A node drawing an outset shadow A node that renders its child after applying a matrix transform A node that changes the opacity of its child A node that applies a color matrix to every pixel A node that repeats the child's contents A node that clips its child to a rectangular area A node that clips its child to a rounded rectangle A node that draws a shadow below its child A node that blends two children together A node that cross-fades between two children A node containing a glyph string A node that applies a blur Debug information that does not affect the rendering A node that uses OpenGL fragment shaders to render A node drawing a `GdkTexture` scaled and filtered. A node that masks one child with another. A node that fills a path. A node that strokes a path. A node that possibly redirects part of the scene graph to a subsurface. A node that applies some function to each color component. A node that copies the rendering canvas to be pasted later. A node that pastes a previously copied canvas. A node that combines a child with the background using Porter/Duff operations. A node that isolated content of its child from previous content. A node that displaces content according to some mask. A node that combines two child nodes in an arithmetic way. A facility to replay a [class@Gsk.RenderNode] and its children, potentially modifying them. This is a utility tool to walk a rendernode tree. The most powerful way is to provide a function via [method@Gsk.RenderReplay.set_node_filter] to filter each individual node and then run [method@Gsk.RenderReplay.filter_node] on the nodes you want to filter. If you want to just walk the node tree and extract information without any modifications, you can also use [method@Gsk.RenderNode.get_children]. Here is a little example application that redacts text in a node file: ``` #include <gtk/gtk.h> static GskRenderNode * redact_nodes (GskRenderReplay *replay, GskRenderNode *node, gpointer user_data) { GskRenderNode *result; if (gsk_render_node_get_node_type (node) == GSK_TEXT_NODE) { graphene_rect_t bounds; const GdkRGBA *color; gsk_render_node_get_bounds (node, &bounds); color = gsk_text_node_get_color (node); result = gsk_color_node_new (color, &bounds); } else { result = gsk_render_replay_default (replay, node); } return result; } int main (int argc, char *argv[]) { GFile *file; GBytes *bytes; GskRenderNode *result, *node; GskRenderReplay *replay; gtk_init (); if (argc != 3) { g_print ("usage: %s INFILE OUTFILE\n", argv[0]); return 0; } file = g_file_new_for_commandline_arg (argv[1]); bytes = g_file_load_bytes (file, NULL, NULL, NULL); g_object_unref (file); if (bytes == NULL) return 1; node = gsk_render_node_deserialize (bytes, NULL, NULL); g_bytes_unref (bytes); if (node == NULL) return 1; replay = gsk_render_replay_new (); gsk_render_replay_set_node_filter (replay, redact_nodes, NULL, NULL); result = gsk_render_replay_filter_node (replay, node); gsk_render_replay_free (replay); if (!gsk_render_node_write_to_file (result, argv[2], NULL)) return 1; gsk_render_node_unref (result); gsk_render_node_unref (node); return 0; } ``` Creates a new replay object to replay nodes. A new replay object to replay nodes Replays the node using the default method. The default method calls [method@Gsk.RenderReplay.filter_node] on all its child nodes and the filter functions for all its properties. If none of them are changed, it returns the passed in node. Otherwise it constructs a new node with the changed children and properties. It may not be possible to construct a new node when any of the callbacks return NULL. In that case, this function will return NULL, too. The replayed node the replay the node to replay Filters a font using the current filter function. the filtered font the replay The font to filter Replays a node using the replay's filter function. After the replay the node may be unchanged, or it may be removed, which will result in %NULL being returned. If no filter node is set, [method@Gsk.RenderReplay.default] is called instead. The replayed node the replay the node to replay Filters a texture using the current filter function. the filtered texture the replay The texture to filter Frees a `GskRenderReplay`. the replay object to free Sets a filter function to be called by [method@Gsk.RenderReplay.default] for nodes that contain fonts. You can call [method@GskRenderReplay.filter_font] to filter a font yourself. the replay the font filter function user data to pass to @filter destroy notify that will be called to release the user data parameter Sets the function to use as a node filter. This is the most complex function to use for replaying nodes. It can either: * keep the node and just return it unchanged * create a replacement node and return that * discard the node by returning `NULL` * call [method@Gsk.RenderReplay.default] to have the default handler run for this node, which calls your function on its children the function to call to replay nodes user data to pass to @func destroy notify that will be called to release the user data parameter Sets a filter function to be called by [method@Gsk.RenderReplay.default] for nodes that contain textures. You can call [method@GskRenderReplay.filter_texture] to filter a texture yourself. the replay the texture filter function user data to pass to @filter destroy notify that will be called to release the user data parameter A function that filters fonts. The function will be called by the default replay function for all nodes with fonts. They will then generate a node using the returned font. It is valid for the function to return the passed in font if the font shuld not be modified. The filtered font The replay object used to replay the node The font to filter The user data A function to replay a node. The node may be returned unmodified. The node may be discarded by returning %NULL. If you do not want to do any handling yourself, call [method@Gsk.RenderReplay.default] to use the default handler that calls your function on the children of the node. The replayed node The replay object used to replay the node The node to replay The user data A function that filters textures. The function will be called by the default replay function for all nodes with textures. They will then generate a node using the returned texture. It is valid for the function to return the passed in texture if the texture shuld not be modified. The filtered texture The replay object used to replay the node The texture to filter The user data Renders a scene graph defined via a tree of [class@Gsk.RenderNode] instances. Typically you will use a `GskRenderer` instance to repeatedly call [method@Gsk.Renderer.render] to update the contents of its associated [class@Gdk.Surface]. It is necessary to realize a `GskRenderer` instance using [method@Gsk.Renderer.realize] before calling [method@Gsk.Renderer.render], in order to create the appropriate windowing system resources needed to render the scene. Creates an appropriate `GskRenderer` instance for the given surface. If the `GSK_RENDERER` environment variable is set, GSK will try that renderer first, before trying the backend-specific default. The ultimate fallback is the cairo renderer. The renderer will be realized before it is returned. the realized renderer a surface Retrieves the surface that the renderer is associated with. If the renderer has not been realized yet, `NULL` will be returned. the surface a renderer Checks whether the renderer is realized or not. true if the renderer was realized, false otherwise a renderer Creates the resources needed by the renderer. Since GTK 4.6, the surface may be `NULL`, which allows using renderers without having to create a surface. Since GTK 4.14, it is recommended to use [method@Gsk.Renderer.realize_for_display] for this case. Note that it is mandatory to call [method@Gsk.Renderer.unrealize] before destroying the renderer. whether the renderer was successfully realized a renderer the surface that renderer will be used on Creates the resources needed by the renderer. Note that it is mandatory to call [method@Gsk.Renderer.unrealize] before destroying the renderer. whether the renderer was successfully realized a renderer the display that the renderer will be used on Renders the scene graph, described by a tree of `GskRenderNode` instances to the renderer's surface, ensuring that the given region gets redrawn. If the renderer has no associated surface, this function does nothing. Renderers must ensure that changes of the contents given by the @root node as well as the area given by @region are redrawn. They are however free to not redraw any pixel outside of @region if they can guarantee that it didn't change. The renderer will acquire a reference on the `GskRenderNode` tree while the rendering is in progress. a realized renderer the render node to render the `cairo_region_t` that must be redrawn or `NULL` for the whole surface Renders a scene graph, described by a tree of `GskRenderNode` instances, to a texture. The renderer will acquire a reference on the `GskRenderNode` tree while the rendering is in progress. If you want to apply any transformations to @root, you should put it into a transform node and pass that node instead. a texture with the rendered contents of @root a realized renderer the render node to render the section to draw or `NULL` to use @root's bounds Releases all the resources created by [method@Gsk.Renderer.realize]. a renderer Whether the renderer has been associated with a surface or draw context. The surface associated with renderer. A render node repeating its single child node. Creates a `GskRenderNode` that will repeat the drawing of @child across the given @bounds. A new `GskRenderNode` The bounds of the area to be painted The child to repeat The area of the child to repeat or %NULL to use the child's bounds Retrieves the child of @node. a `GskRenderNode` a repeat `GskRenderNode` Retrieves the bounding rectangle of the child of @node. a bounding rectangle a repeat `GskRenderNode` A render node for a repeating linear gradient. Creates a `GskRenderNode` that will create a repeating linear gradient from the given points and color stops, and render that into the area given by @bounds. A new `GskRenderNode` the rectangle to render the linear gradient into the point at which the linear gradient will begin the point at which the linear gradient will finish a pointer to an array of `GskColorStop` defining the gradient. The offsets of all color stops must be increasing. The first stop's offset must be >= 0 and the last stop's offset must be <= 1. the number of elements in @color_stops A render node for a repeating radial gradient. Creates a `GskRenderNode` that draws a repeating radial gradient. The radial gradient starts around @center. The size of the gradient is dictated by @hradius in horizontal orientation and by @vradius in vertical orientation. A new `GskRenderNode` the bounds of the node the center of the gradient the horizontal radius the vertical radius a percentage >= 0 that defines the start of the gradient around @center a percentage >= 0 that defines the end of the gradient around @center a pointer to an array of `GskColorStop` defining the gradient. The offsets of all color stops must be increasing. The first stop's offset must be >= 0 and the last stop's offset must be <= 1. the number of elements in @color_stops A render node applying a rounded rectangle clip to its single child. Creates a `GskRenderNode` that will clip the @child to the area given by @clip. A new `GskRenderNode` The node to draw The clip to apply Gets the child node that is getting clipped by the given @node. The child that is getting clipped a rounded clip `GskRenderNode` Retrieves the rounded rectangle used to clip the contents of the @node. a rounded rectangle a rounded clip `GskRenderNode` A rectangular region with rounded corners. Application code should normalize rectangles using [method@Gsk.RoundedRect.normalize]; this function will ensure that the bounds of the rectangle are normalized and ensure that the corner values are positive and the corners do not overlap. All functions taking a `GskRoundedRect` as an argument will internally operate on a normalized copy; all functions returning a `GskRoundedRect` will always return a normalized one. The algorithm used for normalizing corner sizes is described in [the CSS specification](https://drafts.csswg.org/css-backgrounds-3/#border-radius). the bounds of the rectangle the size of the 4 rounded corners Checks if the given point is inside the rounded rectangle. true if the point is inside the rounded rectangle a rounded rectangle the point to check Checks if the given rectangle is contained inside the rounded rectangle. true if the @rect is fully contained inside the rounded rectangle a rounded rectangle the rectangle to check Initializes a rounded rectangle with the given values. This function will implicitly normalize the rounded rectangle before returning. the initialized rounded rectangle the rounded rectangle to initialize a `graphene_rect_t` describing the bounds the rounding radius of the top left corner the rounding radius of the top right corner the rounding radius of the bottom right corner the rounding radius of the bottom left corner Initializes a rounded rectangle with a copy. This function will not normalize the rounded rectangle, so make sure the source is normalized. the initialized rounded rectangle the rounded rectangle to initialize another rounded rectangle Initializes a rounded rectangle to the given bounds and sets the radius of all four corners equally. the initialized rounded rectangle the rounded rectangle to initialize a `graphene_rect_t` the border radius Checks if part a rectangle is contained inside the rounded rectangle. true if the @rect intersects with the rounded rectangle a rounded rectangle the rectangle to check Checks if all corners of a rounded rectangle are right angles and the rectangle covers all of its bounds. This information can be used to decide if [ctor@Gsk.ClipNode.new] or [ctor@Gsk.RoundedClipNode.new] should be called. true if the rounded rectangle is rectilinear the rounded rectangle to check Normalizes a rounded rectangle. This function will ensure that the bounds of the rounded rectangle are normalized and ensure that the corner values are positive and the corners do not overlap. the normalized rounded rectangle a rounded rectangle Offsets the rounded rectangle's origin by @dx and @dy. The size and corners of the rounded rectangle are unchanged. the offset rounded rectangle a rounded rectangle the horizontal offset the vertical offset Shrinks (or grows) a rounded rectangle by moving the 4 sides according to the offsets given. The corner radii will be changed in a way that tries to keep the center of the corner circle intact. This emulates CSS behavior. This function also works for growing rounded rectangles if you pass negative values for the @top, @right, @bottom or @left. the resized rounded rectangle the rounded rectangle to shrink or grow how far to move the top side downwards how far to move the right side to the left how far to move the bottom side upwards how far to move the left side to the right The filters used when scaling texture data. The actual implementation of each filter is deferred to the rendering pipeline. linear interpolation filter nearest neighbor interpolation filter linear interpolation along each axis, plus mipmap generation, with linear interpolation along the mipmap levels Errors that can happen during (de)serialization. The format can not be identified The version of the data is not understood The given data may not exist in a proper serialization Registers an error quark for [class@Gsk.RenderNode] errors. the error quark Builds the uniforms data for a `GskGLShader`. Allocates a builder that can be used to construct a new uniform data chunk. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. The newly allocated builder, free with [method@Gsk.ShaderArgsBuilder.unref] a `GskGLShader` optional `GBytes` with initial values Creates a new `GBytes` args from the current state of the given @builder, and frees the @builder instance. Any uniforms of the shader that have not been explicitly set on the @builder are zero-initialized. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. the newly allocated buffer with all the args added to @builder a `GskShaderArgsBuilder` Increases the reference count of a `GskShaderArgsBuilder` by one. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. the passed in `GskShaderArgsBuilder` a `GskShaderArgsBuilder` Sets the value of the uniform @idx. The uniform must be of bool type. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. a `GskShaderArgsBuilder` index of the uniform value to set the uniform to Sets the value of the uniform @idx. The uniform must be of float type. a `GskShaderArgsBuilder` index of the uniform value to set the uniform to Sets the value of the uniform @idx. The uniform must be of int type. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. a `GskShaderArgsBuilder` index of the uniform value to set the uniform to Sets the value of the uniform @idx. The uniform must be of uint type. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. a `GskShaderArgsBuilder` index of the uniform value to set the uniform to Sets the value of the uniform @idx. The uniform must be of vec2 type. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. A `GskShaderArgsBuilder` index of the uniform value to set the uniform too Sets the value of the uniform @idx. The uniform must be of vec3 type. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. a `GskShaderArgsBuilder` index of the uniform value to set the uniform too Sets the value of the uniform @idx. The uniform must be of vec4 type. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. a `GskShaderArgsBuilder` index of the uniform value to set the uniform too Creates a new `GBytes` args from the current state of the given @builder. Any uniforms of the shader that have not been explicitly set on the @builder are zero-initialized. The given `GskShaderArgsBuilder` is reset once this function returns; you cannot call this function multiple times on the same @builder instance. This function is intended primarily for bindings. C code should use [method@Gsk.ShaderArgsBuilder.free_to_args]. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. the newly allocated buffer with all the args added to @builder a `GskShaderArgsBuilder` Decreases the reference count of a `GskShaderArgBuilder` by one. If the resulting reference count is zero, frees the builder. GTK's new Vulkan-focused rendering does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) for OpenGL rendering. a `GskShaderArgsBuilder` The shadow parameters in a shadow node. the color of the shadow the horizontal offset of the shadow the vertical offset of the shadow the radius of the shadow A render node drawing one or more shadows behind its single child node. Creates a `GskRenderNode` that will draw a @child with the given @shadows below it. A new `GskRenderNode` The node to draw The shadows to apply number of entries in the @shadows array Retrieves the child `GskRenderNode` of the shadow @node. the child render node a shadow `GskRenderNode` Retrieves the number of shadows in the @node. the number of shadows. a shadow `GskRenderNode` Retrieves the shadow data at the given index @i. the shadow data a shadow `GskRenderNode` the given index Collects the parameters that are needed when stroking a path. Creates a new `GskStroke` with the given @line_width. a new `GskStroke` line width of the stroke. Must be > 0 Creates a copy of a `GskStroke`. a new `GskStroke`. Use [method@Gsk.Stroke.free] to free it the stroke to copy Frees a `GskStroke`. a stroke Gets the dash array in use. the dash array or `NULL` if the dash array is empty a stroke number of elements in the array returned Gets the dash offset. the dash offset a stroke Gets the line cap used. See [enum@Gsk.LineCap] for details. the line cap a stroke Gets the line join used. See [enum@Gsk.LineJoin] for details. the line join a stroke Gets the line width used. the line width a stroke Gets the miter limit. the miter limit a stroke Sets the dash pattern to use. A dash pattern is specified by an array of alternating non-negative values. Each value provides the length of alternate "on" and "off" portions of the stroke. Each "on" segment will have caps applied as if the segment were a separate contour. In particular, it is valid to use an "on" length of 0 with [enum@Gsk.LineCap.round] or [enum@Gsk.LineCap.square] to draw dots or squares along a path. If @n_dash is 0, if all elements in @dash are 0, or if there are negative values in @dash, then dashing is disabled. If @n_dash is 1, an alternating "on" and "off" pattern with the single dash length provided is assumed. If @n_dash is uneven, the dash array will be used with the first element in @dash defining an "on" or "off" in alternating passes through the array. You can specify a starting offset into the dash with [method@Gsk.Stroke.set_dash_offset]. a stroke the array of dashes number of elements in @dash Sets the offset into the dash pattern where dashing should begin. This is an offset into the length of the path, not an index into the array values of the dash array. See [method@Gsk.Stroke.set_dash] for more details on dashing. a stroke offset into the dash pattern Sets the line cap to be used when stroking. See [enum@Gsk.LineCap] for details. a stroke the line cap Sets the line join to be used when stroking. See [enum@Gsk.LineJoin] for details. a stroke the line join to use Sets the line width to be used when stroking. The line width must be >= 0. a stroke width of the line in pixels Sets the miter limit to be used when stroking. The miter limit is the distance from the corner where sharp turns of joins get cut off. The limit is specfied in units of line width and must be non-negative. For joins of type [enum@Gsk.LineJoin.miter] that exceed the miter limit, the join gets rendered as if it was of type [enum@Gsk.LineJoin.bevel]. a stroke the miter limit A helper function that sets the stroke parameters of a cairo context from a `GskStroke`. a stroke the cairo context to configure Checks if two strokes are identical. true if the two strokes are equal, false otherwise the first stroke the second stroke A render node that will fill the area determined by stroking the the given [struct@Gsk.Path] using the [struct@Gsk.Stroke] attributes. Creates a #GskRenderNode that will fill the outline generated by stroking the given @path using the attributes defined in @stroke. The area is filled with @child. GSK aims to follow the SVG semantics for stroking paths. E.g. zero-length contours will get round or square line caps drawn, regardless whether they are closed or not. A new #GskRenderNode The node to stroke the area with The path describing the area to stroke The stroke attributes to use Gets the child node that is getting drawn by the given @node. The child that is getting drawn a stroke #GskRenderNode Retrieves the path that will be stroked with the contents of the @node. a #GskPath a stroke #GskRenderNode Retrieves the stroke attributes used in this @node. a #GskStroke a stroke #GskRenderNode A render node that potentially diverts a part of the scene graph to a subsurface. Creates a `GskRenderNode` that will possibly divert the child node to a subsurface. Note: Since subsurfaces are currently private, these nodes cannot currently be created outside of GTK. See [GtkGraphicsOffload](../gtk4/class.GraphicsOffload.html). A new `GskRenderNode` The child to divert to a subsurface the subsurface to use Gets the subsurface that was set on this node the subsurface a subsurface `GskRenderNode` Gets the child node that is getting drawn by the given @node. the child `GskRenderNode` a subsurface `GskRenderNode` A render node drawing a set of glyphs. Creates a render node that renders the given glyphs. Note that @color may not be used if the font contains color glyphs. a new `GskRenderNode` the `PangoFont` containing the glyphs the `PangoGlyphString` to render the foreground color to render with offset of the baseline Retrieves the color used by the text @node. The value returned by this function will not be correct if the render node was created for a non-sRGB color. the text color a text `GskRenderNode` Returns the font used by the text @node. the font The `GskRenderNode` Retrieves the glyph information in the @node. the glyph information a text `GskRenderNode` the number of glyphs returned Retrieves the number of glyphs in the text node. the number of glyphs a text `GskRenderNode` Retrieves the offset applied to the text. a point with the horizontal and vertical offsets a text `GskRenderNode` Checks whether the text @node has color glyphs. %TRUE if the text node has color glyphs a text `GskRenderNode` A render node for a `GdkTexture`. Creates a `GskRenderNode` that will render the given @texture into the area given by @bounds. Note that GSK applies linear filtering when textures are scaled and transformed. See [class@Gsk.TextureScaleNode] for a way to influence filtering. A new `GskRenderNode` the `GdkTexture` the rectangle to render the texture into Retrieves the `GdkTexture` used when creating this `GskRenderNode`. the `GdkTexture` a `GskRenderNode` of type %GSK_TEXTURE_NODE A render node for a `GdkTexture`, with control over scaling. Creates a node that scales the texture to the size given by the bounds using the filter and then places it at the bounds' position. Note that further scaling and other transformations which are applied to the node will apply linear filtering to the resulting texture, as usual. This node is intended for tight control over scaling applied to a texture, such as in image editors and requires the application to be aware of the whole render tree as further transforms may be applied that conflict with the desired effect of this node. A new `GskRenderNode` the texture to scale the size of the texture to scale to how to scale the texture Retrieves the `GskScalingFilter` used when creating this `GskRenderNode`. the `GskScalingFilter` a `GskRenderNode` of type %GSK_TEXTURE_SCALE_NODE Retrieves the `GdkTexture` used when creating this `GskRenderNode`. the `GdkTexture` a `GskRenderNode` of type %GSK_TEXTURE_SCALE_NODE Describes a 3D transform. Unlike `graphene_matrix_t`, `GskTransform` retains the steps in how a transform was constructed, and allows inspecting them. It is modeled after the way CSS describes transforms. `GskTransform` objects are immutable and cannot be changed after creation. This means code can safely expose them as properties of objects without having to worry about others changing them. Creates a new identity transform. This function is meant to be used by language bindings. For C code, this is equivalent to using `NULL`. A new identity transform Checks two transforms for equality. true if the two transforms perform the same operation the first transform the second transform Returns the category this transform belongs to. The category of the transform a transform Inverts the given transform. If @self is not invertible, `NULL` is returned. Note that inverting `NULL` also returns `NULL`, which is the correct inverse of `NULL`. If you need to differentiate between those cases, you should check @self is not `NULL` before calling this function. This function consumes @self. Use [method@Gsk.Transform.ref] first if you want to keep it around. The inverted transform transform to invert Multiplies @next with the given @matrix. This function consumes @next. Use [method@Gsk.Transform.ref] first if you want to keep it around. The new transform the next transform the matrix to multiply @next with Multiplies @next with the matrix [ xx yx x0; xy yy y0; 0 0 1 ]. The result of calling [method@Gsk.Transform.to_2d] on the returned [struct@Gsk.Transform] should match the input passed to this function. This function consumes @next. Use [method@Gsk.Transform.ref] first if you want to keep it around. The new transform the next transform the xx member the yx member the xy member the yy member the x0 member the y0 member Applies a perspective projection transform. This transform scales points in X and Y based on their Z value, scaling points with positive Z values away from the origin, and those with negative Z values towards the origin. Points on the z=0 plane are unchanged. This function consumes @next. Use [method@Gsk.Transform.ref] first if you want to keep it around. The new transform the next transform distance of the z=0 plane. Lower values give a more flattened pyramid and therefore a more pronounced perspective effect. Converts the transform into a human-readable representation. The result of this function can later be parsed with [func@Gsk.Transform.parse]. a transform The string to print into Acquires a reference on the given transform. the transform with an additional reference a transform Rotates @next by an angle around the Z axis. The rotation happens around the origin point of (0, 0). This function consumes @next. Use [method@Gsk.Transform.ref] first if you want to keep it around. The new transform the next transform the rotation angle, in degrees (clockwise) Rotates @next @angle degrees around @axis. For a rotation in 2D space, use [method@Gsk.Transform.rotate] This function consumes @next. Use [method@Gsk.Transform.ref] first if you want to keep it around. The new transform the next transform the rotation angle, in degrees (clockwise) The rotation axis Scales @next in 2-dimensional space by the given factors. Use [method@Gsk.Transform.scale_3d] to scale in all 3 dimensions. This function consumes @next. Use [method@Gsk.Transform.ref] first if you want to keep it around. The new transform the next transform scaling factor on the X axis scaling factor on the Y axis Scales @next by the given factors. This function consumes @next. Use [method@Gsk.Transform.ref] first if you want to keep it around. The new transform the next transform scaling factor on the X axis scaling factor on the Y axis scaling factor on the Z axis Applies a skew transform. This function consumes @next. Use [method@Gsk.Transform.ref] first if you want to keep it around. The new transform the next transform skew factor, in degrees, on the X axis skew factor, in degrees, on the Y axis Converts a transform to a 2D transformation matrix. @self must be a 2D transformation. If you are not sure, use gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D to check. The returned values are a subset of the full 4x4 matrix that is computed by [method@Gsk.Transform.to_matrix] and have the following layout: ``` | xx yx | | a b 0 | | xy yy | = | c d 0 | | dx dy | | tx ty 1 | ``` This function can be used to convert between a `GskTransform` and a matrix type from other 2D drawing libraries, in particular Cairo. a 2D transform return location for the xx member return location for the yx member return location for the xy member return location for the yy member return location for the x0 member return location for the y0 member Converts a transform to 2D transformation factors. To recreate an equivalent transform from the factors returned by this function, use gsk_transform_skew ( gsk_transform_scale ( gsk_transform_rotate ( gsk_transform_translate (NULL, &GRAPHENE_POINT_INIT (dx, dy)), angle), scale_x, scale_y), skew_x, skew_y) @self must be a 2D transformation. If you are not sure, use gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D to check. a transform return location for the skew factor in the x direction return location for the skew factor in the y direction return location for the scale factor in the x direction return location for the scale factor in the y direction return location for the rotation angle return location for the translation in the x direction return location for the translation in the y direction Converts a transform to 2D affine transformation factors. To recreate an equivalent transform from the factors returned by this function, use gsk_transform_scale ( gsk_transform_translate ( NULL, &GRAPHENE_POINT_T (dx, dy)), sx, sy) @self must be a 2D affine transformation. If you are not sure, use gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D_AFFINE to check. a transform return location for the scale factor in the x direction return location for the scale factor in the y direction return location for the translation in the x direction return location for the translation in the y direction Computes the 4x4 matrix for the transform. The previous value of @out_matrix will be ignored. a transform return location for the matrix Converts the transform into a human-readable string. The resulting string can be parsed with [func@Gsk.Transform.parse]. This is a wrapper around [method@Gsk.Transform.print]. A new string for @self a transform Converts a transform to a translation operation. @self must be a 2D transformation. If you are not sure, use gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D_TRANSLATE to check. a transform return location for the translation in the x direction return location for the translation in the y direction Applies all the operations from @other to @next. This function consumes @next. Use [method@Gsk.Transform.ref] first if you want to keep it around. The new transform transform to apply @other to transform to apply Transforms a rectangle using the given transform. The result is the bounding box containing the coplanar quad. The input and output rect may point to the same rectangle. a transform the rectangle to transform return location for the bounds of the transformed rectangle Transforms a point using the given transform. a transform the point to transform return location for the transformed point Translates @next in 2-dimensional space by @point. This function consumes @next. Use [method@Gsk.Transform.ref] first if you want to keep it around. The new transform the next transform the point to translate the transform by Translates @next by @point. This function consumes @next. Use [method@Gsk.Transform.ref] first if you want to keep it around. The new transform the next transform the point to translate the transform by Releases a reference on the given transform. If the reference was the last, the resources associated to the @self are freed. a transform Parses a given into a transform. Strings printed via [method@Gsk.Transform.to_string] can be read in again successfully using this function. If @string does not describe a valid transform, false is returned and `NULL` is put in @out_transform. true if @string described a valid transform the string to parse return location for the transform The categories of matrices relevant for GSK and GTK. Note that any category includes matrices of all later categories. So if you want to for example check if a matrix is a 2D matrix, `category >= GSK_TRANSFORM_CATEGORY_2D` is the way to do this. Also keep in mind that rounding errors may cause matrices to not conform to their categories. Otherwise, matrix operations done via multiplication will not worsen categories. So for the matrix multiplication `C = A * B`, `category(C) = MIN (category(A), category(B))`. The category of the matrix has not been determined. Analyzing the matrix concluded that it does not fit in any other category. The matrix is a 3D matrix. This means that the w column (the last column) has the values (0, 0, 0, 1). The matrix is a 2D matrix. This is equivalent to graphene_matrix_is_2d() returning %TRUE. In particular, this means that Cairo can deal with the matrix. The matrix is a combination of 2D scale and 2D translation operations. In particular, this means that any rectangle can be transformed exactly using this matrix. The matrix is a 2D translation. The matrix is the identity matrix. A render node applying a `GskTransform` to its single child node. Creates a `GskRenderNode` that will transform the given @child with the given @transform. A new `GskRenderNode` The node to transform The transform to apply Gets the child node that is getting transformed by the given @node. The child that is getting transformed a `GskRenderNode` for a transform Retrieves the `GskTransform` used by the @node. a `GskTransform` a `GskRenderNode` for a transform Evaluates to true if @value was initialized with `GSK_TYPE_RENDER_NODE`. a `GValue` Renders a GSK rendernode tree with Vulkan. This renderer will fail to realize if Vulkan is not supported. Creates a new Vulkan renderer. The Vulkan renderer is a renderer that uses the Vulkan library for rendering. This renderer will fail to realize when GTK was not compiled with Vulkan support. a new Vulkan renderer Compares two component transfers for equality. true if @self and @other are equal a component transfer another component transfer Constructs a path from a serialized form. The string is expected to be in (a superset of) [SVG path syntax](https://www.w3.org/TR/SVG11/paths.html#PathData), as e.g. produced by [method@Gsk.Path.to_string]. A high-level summary of the syntax: - `M x y` Move to `(x, y)` - `L x y` Add a line from the current point to `(x, y)` - `Q x1 y1 x2 y2` Add a quadratic Bézier from the current point to `(x2, y2)`, with control point `(x1, y1)` - `C x1 y1 x2 y2 x3 y3` Add a cubic Bézier from the current point to `(x3, y3)`, with control points `(x1, y1)` and `(x2, y2)` - `Z` Close the contour by drawing a line back to the start point - `H x` Add a horizontal line from the current point to the given x value - `V y` Add a vertical line from the current point to the given y value - `T x2 y2` Add a quadratic Bézier, using the reflection of the previous segments' control point as control point - `S x2 y2 x3 y3` Add a cubic Bézier, using the reflection of the previous segments' second control point as first control point - `A rx ry r l s x y` Add an elliptical arc from the current point to `(x, y)` with radii rx and ry. See the SVG documentation for how the other parameters influence the arc. - `O x1 y1 x2 y2 w` Add a rational quadratic Bézier from the current point to `(x2, y2)` with control point `(x1, y1)` and weight `w`. All the commands have lowercase variants that interpret coordinates relative to the current point. The `O` command is an extension that is not supported in SVG. a new `GskPath`, or `NULL` if @string could not be parsed a string Registers an error quark for [class@Gsk.RenderNode] errors. the error quark Checks if two strokes are identical. true if the two strokes are equal, false otherwise the first stroke the second stroke Parses a given into a transform. Strings printed via [method@Gsk.Transform.to_string] can be read in again successfully using this function. If @string does not describe a valid transform, false is returned and `NULL` is put in @out_transform. true if @string described a valid transform the string to parse return location for the transform Retrieves the render node stored inside a `GValue`, and acquires a reference to it. the render node a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE` Retrieves the render node stored inside a `GValue`. the render node a `GValue` initialized with type `GSK_TYPE_RENDER_NODE` Stores the given render node inside a `GValue`. The [struct@GObject.Value] will acquire a reference to the render node. a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE` a render node Stores the given render node inside a `GValue`. This function transfers the ownership of the render node to the `GValue`. a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE` a render node soup3-0.9.0/gir-files/Gtk-3.0.gir000064400000000000000000341740521046102023000143320ustar 00000000000000 A #GtkAllocation-struct of a widget represents region which has been allocated to the widget by its parent. It is a subregion of its parents allocation. See [GtkWidget’s geometry management section][geometry-management] for more information. The GtkAboutDialog offers a simple way to display information about a program like its logo, name, copyright, website and license. It is also possible to give credits to the authors, documenters, translators and artists who have worked on the program. An about dialog is typically opened when the user selects the `About` option from the `Help` menu. All parts of the dialog are optional. About dialogs often contain links and email addresses. GtkAboutDialog displays these as clickable links. By default, it calls gtk_show_uri_on_window() when a user clicks one. The behaviour can be overridden with the #GtkAboutDialog::activate-link signal. To specify a person with an email address, use a string like "Edgar Allan Poe <edgar\@poe.com>". To specify a website with a title, use a string like "GTK+ team http://www.gtk.org". To make constructing a GtkAboutDialog as convenient as possible, you can use the function gtk_show_about_dialog() which constructs and shows a dialog and keeps it around so that it can be shown again. Note that GTK+ sets a default title of `_("About %s")` on the dialog window (where \%s is replaced by the name of the application, but in order to ensure proper translation of the title, applications should set the title property explicitly when constructing a GtkAboutDialog, as shown in the following example: |[<!-- language="C" --> GdkPixbuf *example_logo = gdk_pixbuf_new_from_file ("./logo.png", NULL); gtk_show_about_dialog (NULL, "program-name", "ExampleCode", "logo", example_logo, "title", _("About ExampleCode"), NULL); ]| It is also possible to show a #GtkAboutDialog like any other #GtkDialog, e.g. using gtk_dialog_run(). In this case, you might need to know that the “Close” button returns the #GTK_RESPONSE_CANCEL response id. Creates a new #GtkAboutDialog. a newly created #GtkAboutDialog Creates a new section in the Credits page. A #GtkAboutDialog The name of the section The people who belong to that section Returns the string which are displayed in the artists tab of the secondary credits dialog. A %NULL-terminated string array containing the artists. The array is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the string which are displayed in the authors tab of the secondary credits dialog. A %NULL-terminated string array containing the authors. The array is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the comments string. The comments. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the copyright string. The copyright string. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the string which are displayed in the documenters tab of the secondary credits dialog. A %NULL-terminated string array containing the documenters. The array is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the license information. The license information. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Retrieves the license set using gtk_about_dialog_set_license_type() a #GtkLicense value a #GtkAboutDialog Returns the pixbuf displayed as logo in the about dialog. the pixbuf displayed as logo. The pixbuf is owned by the about dialog. If you want to keep a reference to it, you have to call g_object_ref() on it. a #GtkAboutDialog Returns the icon name displayed as logo in the about dialog. the icon name displayed as logo. The string is owned by the dialog. If you want to keep a reference to it, you have to call g_strdup() on it. a #GtkAboutDialog Returns the program name displayed in the about dialog. The program name. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the translator credits string which is displayed in the translators tab of the secondary credits dialog. The translator credits string. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the version string. The version string. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the website URL. The website URL. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the label used for the website link. The label used for the website link. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns whether the license text in @about is automatically wrapped. %TRUE if the license text is wrapped a #GtkAboutDialog Sets the strings which are displayed in the artists tab of the secondary credits dialog. a #GtkAboutDialog a %NULL-terminated array of strings Sets the strings which are displayed in the authors tab of the secondary credits dialog. a #GtkAboutDialog a %NULL-terminated array of strings Sets the comments string to display in the about dialog. This should be a short string of one or two lines. a #GtkAboutDialog a comments string Sets the copyright string to display in the about dialog. This should be a short string of one or two lines. a #GtkAboutDialog the copyright string Sets the strings which are displayed in the documenters tab of the secondary credits dialog. a #GtkAboutDialog a %NULL-terminated array of strings Sets the license information to be displayed in the secondary license dialog. If @license is %NULL, the license button is hidden. a #GtkAboutDialog the license information or %NULL Sets the license of the application showing the @about dialog from a list of known licenses. This function overrides the license set using gtk_about_dialog_set_license(). a #GtkAboutDialog the type of license Sets the pixbuf to be displayed as logo in the about dialog. If it is %NULL, the default window icon set with gtk_window_set_default_icon() will be used. a #GtkAboutDialog a #GdkPixbuf, or %NULL Sets the pixbuf to be displayed as logo in the about dialog. If it is %NULL, the default window icon set with gtk_window_set_default_icon() will be used. a #GtkAboutDialog an icon name, or %NULL Sets the name to display in the about dialog. If this is not set, it defaults to g_get_application_name(). a #GtkAboutDialog the program name Sets the translator credits string which is displayed in the translators tab of the secondary credits dialog. The intended use for this string is to display the translator of the language which is currently used in the user interface. Using gettext(), a simple way to achieve that is to mark the string for translation: |[<!-- language="C" --> GtkWidget *about = gtk_about_dialog_new (); gtk_about_dialog_set_translator_credits (GTK_ABOUT_DIALOG (about), _("translator-credits")); ]| It is a good idea to use the customary msgid “translator-credits” for this purpose, since translators will already know the purpose of that msgid, and since #GtkAboutDialog will detect if “translator-credits” is untranslated and hide the tab. a #GtkAboutDialog the translator credits Sets the version string to display in the about dialog. a #GtkAboutDialog the version string Sets the URL to use for the website link. a #GtkAboutDialog a URL string starting with "http://" Sets the label to be used for the website link. a #GtkAboutDialog the label used for the website link Sets whether the license text in @about is automatically wrapped. a #GtkAboutDialog whether to wrap the license The people who contributed artwork to the program, as a %NULL-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. The authors of the program, as a %NULL-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. Comments about the program. This string is displayed in a label in the main dialog, thus it should be a short explanation of the main purpose of the program, not a detailed list of features. Copyright information for the program. The people documenting the program, as a %NULL-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. The license of the program. This string is displayed in a text view in a secondary dialog, therefore it is fine to use a long multi-paragraph text. Note that the text is only wrapped in the text view if the "wrap-license" property is set to %TRUE; otherwise the text itself must contain the intended linebreaks. When setting this property to a non-%NULL value, the #GtkAboutDialog:license-type property is set to %GTK_LICENSE_CUSTOM as a side effect. The license of the program, as a value of the %GtkLicense enumeration. The #GtkAboutDialog will automatically fill out a standard disclaimer and link the user to the appropriate online resource for the license text. If %GTK_LICENSE_UNKNOWN is used, the link used will be the same specified in the #GtkAboutDialog:website property. If %GTK_LICENSE_CUSTOM is used, the current contents of the #GtkAboutDialog:license property are used. For any other #GtkLicense value, the contents of the #GtkAboutDialog:license property are also set by this property as a side effect. A logo for the about box. If it is %NULL, the default window icon set with gtk_window_set_default_icon() will be used. A named icon to use as the logo for the about box. This property overrides the #GtkAboutDialog:logo property. The name of the program. If this is not set, it defaults to g_get_application_name(). Credits to the translators. This string should be marked as translatable. The string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. The version of the program. The URL for the link to the website of the program. This should be a string starting with "http://. The label for the link to the website of the program. Whether to wrap the text in the license dialog. The signal which gets emitted to activate a URI. Applications may connect to it to override the default behaviour, which is to call gtk_show_uri_on_window(). %TRUE if the link has been activated the URI that is activated Accelerator flags used with gtk_accel_group_connect(). Accelerator is visible Accelerator not removable Mask A #GtkAccelGroup represents a group of keyboard accelerators, typically attached to a toplevel #GtkWindow (with gtk_window_add_accel_group()). Usually you won’t need to create a #GtkAccelGroup directly; instead, when using #GtkUIManager, GTK+ automatically sets up the accelerators for your menus in the ui manager’s #GtkAccelGroup. Note that “accelerators” are different from “mnemonics”. Accelerators are shortcuts for activating a menu item; they appear alongside the menu item they’re a shortcut for. For example “Ctrl+Q” might appear alongside the “Quit” menu item. Mnemonics are shortcuts for GUI elements such as text entries or buttons; they appear as underlined characters. See gtk_label_new_with_mnemonic(). Menu items can have both accelerators and mnemonics, of course. Creates a new #GtkAccelGroup. a new #GtkAccelGroup object Finds the #GtkAccelGroup to which @closure is connected; see gtk_accel_group_connect(). the #GtkAccelGroup to which @closure is connected, or %NULL a #GClosure Signal emitted when an entry is added to or removed from the accel group. Finds the first accelerator in @accel_group that matches @accel_key and @accel_mods, and activates it. %TRUE if an accelerator was activated and handled this keypress a #GtkAccelGroup the quark for the accelerator name the #GObject, usually a #GtkWindow, on which to activate the accelerator accelerator keyval from a key event keyboard state mask from a key event Installs an accelerator in this group. When @accel_group is being activated in response to a call to gtk_accel_groups_activate(), @closure will be invoked if the @accel_key and @accel_mods from gtk_accel_groups_activate() match those of this connection. The signature used for the @closure is that of #GtkAccelGroupActivate. Note that, due to implementation details, a single closure can only be connected to one accelerator group. the accelerator group to install an accelerator in key value of the accelerator modifier combination of the accelerator a flag mask to configure this accelerator closure to be executed upon accelerator activation Installs an accelerator in this group, using an accelerator path to look up the appropriate key and modifiers (see gtk_accel_map_add_entry()). When @accel_group is being activated in response to a call to gtk_accel_groups_activate(), @closure will be invoked if the @accel_key and @accel_mods from gtk_accel_groups_activate() match the key and modifiers for the path. The signature used for the @closure is that of #GtkAccelGroupActivate. Note that @accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). the accelerator group to install an accelerator in path used for determining key and modifiers closure to be executed upon accelerator activation Removes an accelerator previously installed through gtk_accel_group_connect(). Since 2.20 @closure can be %NULL. %TRUE if the closure was found and got disconnected the accelerator group to remove an accelerator from the closure to remove from this accelerator group, or %NULL to remove all closures Removes an accelerator previously installed through gtk_accel_group_connect(). %TRUE if there was an accelerator which could be removed, %FALSE otherwise the accelerator group to install an accelerator in key value of the accelerator modifier combination of the accelerator Finds the first entry in an accelerator group for which @find_func returns %TRUE and returns its #GtkAccelKey. the key of the first entry passing @find_func. The key is owned by GTK+ and must not be freed. a #GtkAccelGroup a function to filter the entries of @accel_group with data to pass to @find_func Locks are added and removed using gtk_accel_group_lock() and gtk_accel_group_unlock(). %TRUE if there are 1 or more locks on the @accel_group, %FALSE otherwise. a #GtkAccelGroup Gets a #GdkModifierType representing the mask for this @accel_group. For example, #GDK_CONTROL_MASK, #GDK_SHIFT_MASK, etc. the modifier mask for this accel group. a #GtkAccelGroup Locks the given accelerator group. Locking an acelerator group prevents the accelerators contained within it to be changed during runtime. Refer to gtk_accel_map_change_entry() about runtime accelerator changes. If called more than once, @accel_group remains locked until gtk_accel_group_unlock() has been called an equivalent number of times. a #GtkAccelGroup Queries an accelerator group for all entries matching @accel_key and @accel_mods. an array of @n_entries #GtkAccelGroupEntry elements, or %NULL. The array is owned by GTK+ and must not be freed. the accelerator group to query key value of the accelerator modifier combination of the accelerator location to return the number of entries found, or %NULL Undoes the last call to gtk_accel_group_lock() on this @accel_group. a #GtkAccelGroup The accel-activate signal is an implementation detail of #GtkAccelGroup and not meant to be used by applications. %TRUE if the accelerator was activated the object on which the accelerator was activated the accelerator keyval the modifier combination of the accelerator The accel-changed signal is emitted when an entry is added to or removed from the accel group. Widgets like #GtkAccelLabel which display an associated accelerator should connect to this signal, and rebuild their visual representation if the @accel_closure is theirs. the accelerator keyval the modifier combination of the accelerator the #GClosure of the accelerator The parent class. Signal emitted when an entry is added to or removed from the accel group. The accelerator keyval The accelerator modifiers The accelerator flags The #GtkAccelLabel widget is a subclass of #GtkLabel that also displays an accelerator key on the right of the label text, e.g. “Ctrl+S”. It is commonly used in menus to show the keyboard short-cuts for commands. The accelerator key to display is typically not set explicitly (although it can be, with gtk_accel_label_set_accel()). Instead, the #GtkAccelLabel displays the accelerators which have been added to a particular widget. This widget is set by calling gtk_accel_label_set_accel_widget(). For example, a #GtkMenuItem widget may have an accelerator added to emit the “activate” signal when the “Ctrl+S” key combination is pressed. A #GtkAccelLabel is created and added to the #GtkMenuItem, and gtk_accel_label_set_accel_widget() is called with the #GtkMenuItem as the second argument. The #GtkAccelLabel will now display “Ctrl+S” after its label. Note that creating a #GtkMenuItem with gtk_menu_item_new_with_label() (or one of the similar functions for #GtkCheckMenuItem and #GtkRadioMenuItem) automatically adds a #GtkAccelLabel to the #GtkMenuItem and calls gtk_accel_label_set_accel_widget() to set it up for you. A #GtkAccelLabel will only display accelerators which have %GTK_ACCEL_VISIBLE set (see #GtkAccelFlags). A #GtkAccelLabel can display multiple accelerators and even signal names, though it is almost always used to display just one accelerator key. ## Creating a simple menu item with an accelerator key. |[<!-- language="C" --> GtkWidget *window = gtk_window_new (GTK_WINDOW_TOPLEVEL); GtkWidget *menu = gtk_menu_new (); GtkWidget *save_item; GtkAccelGroup *accel_group; // Create a GtkAccelGroup and add it to the window. accel_group = gtk_accel_group_new (); gtk_window_add_accel_group (GTK_WINDOW (window), accel_group); // Create the menu item using the convenience function. save_item = gtk_menu_item_new_with_label ("Save"); gtk_widget_show (save_item); gtk_container_add (GTK_CONTAINER (menu), save_item); // Now add the accelerator to the GtkMenuItem. Note that since we // called gtk_menu_item_new_with_label() to create the GtkMenuItem // the GtkAccelLabel is automatically set up to display the // GtkMenuItem accelerators. We just need to make sure we use // GTK_ACCEL_VISIBLE here. gtk_widget_add_accelerator (save_item, "activate", accel_group, GDK_KEY_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE); ]| # CSS nodes |[<!-- language="plain" --> label ╰── accelerator ]| Like #GtkLabel, GtkAccelLabel has a main CSS node with the name label. It adds a subnode with name accelerator. Creates a new #GtkAccelLabel. a new #GtkAccelLabel. the label string. Must be non-%NULL. Gets the keyval and modifier mask set with gtk_accel_label_set_accel(). a #GtkAccelLabel return location for the keyval return location for the modifier mask Fetches the widget monitored by this accelerator label. See gtk_accel_label_set_accel_widget(). the object monitored by the accelerator label, or %NULL. a #GtkAccelLabel Returns the width needed to display the accelerator key(s). This is used by menus to align all of the #GtkMenuItem widgets, and shouldn't be needed by applications. the width needed to display the accelerator key(s). a #GtkAccelLabel. Recreates the string representing the accelerator keys. This should not be needed since the string is automatically updated whenever accelerators are added or removed from the associated widget. always returns %FALSE. a #GtkAccelLabel. Manually sets a keyval and modifier mask as the accelerator rendered by @accel_label. If a keyval and modifier are explicitly set then these values are used regardless of any associated accel closure or widget. Providing an @accelerator_key of 0 removes the manual setting. a #GtkAccelLabel a keyval, or 0 the modifier mask for the accel Sets the closure to be monitored by this accelerator label. The closure must be connected to an accelerator group; see gtk_accel_group_connect(). Passing %NULL for @accel_closure will dissociate @accel_label from its current closure, if any. a #GtkAccelLabel the closure to monitor for accelerator changes, or %NULL Sets the widget to be monitored by this accelerator label. Passing %NULL for @accel_widget will dissociate @accel_label from its current widget, if any. a #GtkAccelLabel the widget to be monitored, or %NULL Accelerator maps are used to define runtime configurable accelerators. Functions for manipulating them are are usually used by higher level convenience mechanisms like #GtkUIManager and are thus considered “low-level”. You’ll want to use them if you’re manually creating menus that should have user-configurable accelerators. An accelerator is uniquely defined by: - accelerator path - accelerator key - accelerator modifiers The accelerator path must consist of “<WINDOWTYPE>/Category1/Category2/.../Action”, where WINDOWTYPE should be a unique application-specific identifier that corresponds to the kind of window the accelerator is being used in, e.g. “Gimp-Image”, “Abiword-Document” or “Gnumeric-Settings”. The “Category1/.../Action” portion is most appropriately chosen by the action the accelerator triggers, i.e. for accelerators on menu items, choose the item’s menu path, e.g. “File/Save As”, “Image/View/Zoom” or “Edit/Select All”. So a full valid accelerator path may look like: “<Gimp-Toolbox>/File/Dialogs/Tool Options...”. All accelerators are stored inside one global #GtkAccelMap that can be obtained using gtk_accel_map_get(). See [Monitoring changes][monitoring-changes] for additional details. # Manipulating accelerators New accelerators can be added using gtk_accel_map_add_entry(). To search for specific accelerator, use gtk_accel_map_lookup_entry(). Modifications of existing accelerators should be done using gtk_accel_map_change_entry(). In order to avoid having some accelerators changed, they can be locked using gtk_accel_map_lock_path(). Unlocking is done using gtk_accel_map_unlock_path(). # Saving and loading accelerator maps Accelerator maps can be saved to and loaded from some external resource. For simple saving and loading from file, gtk_accel_map_save() and gtk_accel_map_load() are provided. Saving and loading can also be done by providing file descriptor to gtk_accel_map_save_fd() and gtk_accel_map_load_fd(). # Monitoring changes #GtkAccelMap object is only useful for monitoring changes of accelerators. By connecting to #GtkAccelMap::changed signal, one can monitor changes of all accelerators. It is also possible to monitor only single accelerator path by using it as a detail of the #GtkAccelMap::changed signal. Registers a new accelerator with the global accelerator map. This function should only be called once per @accel_path with the canonical @accel_key and @accel_mods for this path. To change the accelerator during runtime programatically, use gtk_accel_map_change_entry(). Set @accel_key and @accel_mods to 0 to request a removal of the accelerator. Note that @accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). valid accelerator path the accelerator key the accelerator modifiers Adds a filter to the global list of accel path filters. Accel map entries whose accel path matches one of the filters are skipped by gtk_accel_map_foreach(). This function is intended for GTK+ modules that create their own menus, but don’t want them to be saved into the applications accelerator map dump. a pattern (see #GPatternSpec) Changes the @accel_key and @accel_mods currently associated with @accel_path. Due to conflicts with other accelerators, a change may not always be possible, @replace indicates whether other accelerators may be deleted to resolve such conflicts. A change will only occur if all conflicts could be resolved (which might not be the case if conflicting accelerators are locked). Successful changes are indicated by a %TRUE return value. Note that @accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). %TRUE if the accelerator could be changed, %FALSE otherwise a valid accelerator path the new accelerator key the new accelerator modifiers %TRUE if other accelerators may be deleted upon conflicts Loops over the entries in the accelerator map whose accel path doesn’t match any of the filters added with gtk_accel_map_add_filter(), and execute @foreach_func on each. The signature of @foreach_func is that of #GtkAccelMapForeach, the @changed parameter indicates whether this accelerator was changed during runtime (thus, would need saving during an accelerator map dump). data to be passed into @foreach_func function to be executed for each accel map entry which is not filtered out Loops over all entries in the accelerator map, and execute @foreach_func on each. The signature of @foreach_func is that of #GtkAccelMapForeach, the @changed parameter indicates whether this accelerator was changed during runtime (thus, would need saving during an accelerator map dump). data to be passed into @foreach_func function to be executed for each accel map entry Gets the singleton global #GtkAccelMap object. This object is useful only for notification of changes to the accelerator map via the ::changed signal; it isn’t a parameter to the other accelerator map functions. the global #GtkAccelMap object Parses a file previously saved with gtk_accel_map_save() for accelerator specifications, and propagates them accordingly. a file containing accelerator specifications, in the GLib file name encoding Filedescriptor variant of gtk_accel_map_load(). Note that the file descriptor will not be closed by this function. a valid readable file descriptor #GScanner variant of gtk_accel_map_load(). a #GScanner which has already been provided with an input file Locks the given accelerator path. If the accelerator map doesn’t yet contain an entry for @accel_path, a new one is created. Locking an accelerator path prevents its accelerator from being changed during runtime. A locked accelerator path can be unlocked by gtk_accel_map_unlock_path(). Refer to gtk_accel_map_change_entry() for information about runtime accelerator changes. If called more than once, @accel_path remains locked until gtk_accel_map_unlock_path() has been called an equivalent number of times. Note that locking of individual accelerator paths is independent from locking the #GtkAccelGroup containing them. For runtime accelerator changes to be possible, both the accelerator path and its #GtkAccelGroup have to be unlocked. a valid accelerator path Looks up the accelerator entry for @accel_path and fills in @key. %TRUE if @accel_path is known, %FALSE otherwise a valid accelerator path the accelerator key to be filled in (optional) Saves current accelerator specifications (accelerator path, key and modifiers) to @file_name. The file is written in a format suitable to be read back in by gtk_accel_map_load(). the name of the file to contain accelerator specifications, in the GLib file name encoding Filedescriptor variant of gtk_accel_map_save(). Note that the file descriptor will not be closed by this function. a valid writable file descriptor Undoes the last call to gtk_accel_map_lock_path() on this @accel_path. Refer to gtk_accel_map_lock_path() for information about accelerator path locking. a valid accelerator path Notifies of a change in the global accelerator map. The path is also used as the detail for the signal, so it is possible to connect to changed::`accel_path`. the path of the accelerator that changed the key value for the new accelerator the modifier mask for the new accelerator User data passed to gtk_accel_map_foreach() or gtk_accel_map_foreach_unfiltered() Accel path of the current accelerator Key of the current accelerator Modifiers of the current accelerator Changed flag of the accelerator (if %TRUE, accelerator has changed during runtime and would need to be saved during an accelerator dump) The #GtkAccessible class is the base class for accessible implementations for #GtkWidget subclasses. It is a thin wrapper around #AtkObject, which adds facilities for associating a widget with its accessible object. An accessible implementation for a third-party widget should derive from #GtkAccessible and implement the suitable interfaces from ATK, such as #AtkText or #AtkSelection. To establish the connection between the widget class and its corresponding acccessible implementation, override the get_accessible vfunc in #GtkWidgetClass. This function specifies the callback function to be called when the widget corresponding to a GtkAccessible is destroyed. Use gtk_accessible_set_widget() and its vfuncs. a #GtkAccessible This function specifies the callback function to be called when the widget corresponding to a GtkAccessible is destroyed. Use gtk_accessible_set_widget() and its vfuncs. a #GtkAccessible Gets the #GtkWidget corresponding to the #GtkAccessible. The returned widget does not have a reference added, so you do not need to unref it. pointer to the #GtkWidget corresponding to the #GtkAccessible, or %NULL. a #GtkAccessible Sets the #GtkWidget corresponding to the #GtkAccessible. @accessible will not hold a reference to @widget. It is the caller’s responsibility to ensure that when @widget is destroyed, the widget is unset by calling this function again with @widget set to %NULL. a #GtkAccessible a #GtkWidget or %NULL to unset a #GtkAccessible > In GTK+ 3.10, GtkAction has been deprecated. Use #GAction > instead, and associate actions with #GtkActionable widgets. Use > #GMenuModel for creating menus with gtk_menu_new_from_model(). Actions represent operations that the user can be perform, along with some information how it should be presented in the interface. Each action provides methods to create icons, menu items and toolbar items representing itself. As well as the callback that is called when the action gets activated, the following also gets associated with the action: - a name (not translated, for path lookup) - a label (translated, for display) - an accelerator - whether label indicates a stock id - a tooltip (optional, translated) - a toolbar label (optional, shorter than label) The action will also have some state information: - visible (shown/hidden) - sensitive (enabled/disabled) Apart from regular actions, there are [toggle actions][GtkToggleAction], which can be toggled between two states and [radio actions][GtkRadioAction], of which only one in a group can be in the “active” state. Other actions can be implemented as #GtkAction subclasses. Each action can have one or more proxy widgets. To act as an action proxy, widget needs to implement #GtkActivatable interface. Proxies mirror the state of the action and should change when the action’s state changes. Properties that are always mirrored by proxies are #GtkAction:sensitive and #GtkAction:visible. #GtkAction:gicon, #GtkAction:icon-name, #GtkAction:label, #GtkAction:short-label and #GtkAction:stock-id properties are only mirorred if proxy widget has #GtkActivatable:use-action-appearance property set to %TRUE. When the proxy is activated, it should activate its action. Creates a new #GtkAction object. To add the action to a #GtkActionGroup and set the accelerator for the action, call gtk_action_group_add_action_with_accel(). See the [UI Definition section][XML-UI] for information on allowed action names. Use #GAction instead, associating it to a widget with #GtkActionable or creating a #GtkMenu with gtk_menu_new_from_model() a new #GtkAction A unique name for the action the label displayed in menu items and on buttons, or %NULL a tooltip for the action, or %NULL the stock icon to display in widgets representing the action, or %NULL Emits the “activate” signal on the specified action, if it isn't insensitive. This gets called by the proxy widgets when they get activated. It can also be used to manually activate an action. Use g_action_group_activate_action() on a #GAction instead the action object If @action provides a #GtkMenu widget as a submenu for the menu item or the toolbar item it creates, this function returns an instance of that menu. Use #GAction and #GMenuModel instead, and create a #GtkMenu with gtk_menu_new_from_model() the menu item provided by the action, or %NULL. a #GtkAction Creates a menu item widget that proxies for the given action. Use g_menu_item_new() and associate it with a #GAction instead. a menu item connected to the action. the action object Creates a toolbar item widget that proxies for the given action. Use a #GtkToolItem and associate it with a #GAction using gtk_actionable_set_action_name() instead a toolbar item connected to the action. the action object Emits the “activate” signal on the specified action, if it isn't insensitive. This gets called by the proxy widgets when they get activated. It can also be used to manually activate an action. Use g_action_group_activate_action() on a #GAction instead the action object Disable activation signals from the action This is needed when updating the state of your proxy #GtkActivatable widget could result in calling gtk_action_activate(), this is a convenience function to avoid recursing in those cases (updating toggle state for instance). Use g_simple_action_set_enabled() to disable the #GSimpleAction instead a #GtkAction Installs the accelerator for @action if @action has an accel path and group. See gtk_action_set_accel_path() and gtk_action_set_accel_group() Since multiple proxies may independently trigger the installation of the accelerator, the @action counts the number of times this function has been called and doesn’t remove the accelerator until gtk_action_disconnect_accelerator() has been called as many times. Use #GAction and the accelerator group on an associated #GtkMenu instead a #GtkAction This function is intended for use by action implementations to create icons displayed in the proxy widgets. Use g_menu_item_set_icon() to set an icon on a #GMenuItem, or gtk_container_add() to add a #GtkImage to a #GtkButton a widget that displays the icon for this action. the action object the size of the icon (#GtkIconSize) that should be created. If @action provides a #GtkMenu widget as a submenu for the menu item or the toolbar item it creates, this function returns an instance of that menu. Use #GAction and #GMenuModel instead, and create a #GtkMenu with gtk_menu_new_from_model() the menu item provided by the action, or %NULL. a #GtkAction Creates a menu item widget that proxies for the given action. Use g_menu_item_new() and associate it with a #GAction instead. a menu item connected to the action. the action object Creates a toolbar item widget that proxies for the given action. Use a #GtkToolItem and associate it with a #GAction using gtk_actionable_set_action_name() instead a toolbar item connected to the action. the action object Undoes the effect of one call to gtk_action_connect_accelerator(). Use #GAction and the accelerator group on an associated #GtkMenu instead a #GtkAction Returns the accel closure for this action. Use #GAction and #GtkMenu instead, which have no equivalent for getting the accel closure the accel closure for this action. The returned closure is owned by GTK+ and must not be unreffed or modified. the action object Returns the accel path for this action. Use #GAction and the accelerator path on an associated #GtkMenu instead the accel path for this action, or %NULL if none is set. The returned string is owned by GTK+ and must not be freed or modified. the action object Returns whether @action's menu item proxies will always show their image, if available. Use g_menu_item_get_attribute_value() on a #GMenuItem instead %TRUE if the menu item proxies will always show their image a #GtkAction Gets the gicon of @action. Use #GAction instead, and g_menu_item_get_attribute_value() to get an icon from a #GMenuItem associated with a #GAction The action’s #GIcon if one is set. a #GtkAction Gets the icon name of @action. Use #GAction instead, and g_menu_item_get_attribute_value() to get an icon from a #GMenuItem associated with a #GAction the icon name a #GtkAction Checks whether @action is important or not Use #GAction instead, and control and monitor whether labels are shown directly whether @action is important a #GtkAction Gets the label text of @action. Use #GAction instead, and get a label from a menu item with g_menu_item_get_attribute_value(). For #GtkActionable widgets, use the widget-specific API to get a label the label text a #GtkAction Returns the name of the action. Use g_action_get_name() on a #GAction instead the name of the action. The string belongs to GTK+ and should not be freed. the action object Returns the proxy widgets for an action. See also gtk_activatable_get_related_action(). a #GSList of proxy widgets. The list is owned by GTK+ and must not be modified. the action object Returns whether the action itself is sensitive. Note that this doesn’t necessarily mean effective sensitivity. See gtk_action_is_sensitive() for that. Use g_action_get_enabled() on a #GAction instead %TRUE if the action itself is sensitive. the action object Gets the short label text of @action. Use #GAction instead, which has no equivalent of short labels the short label text. a #GtkAction Gets the stock id of @action. Use #GAction instead, which has no equivalent of stock items the stock id a #GtkAction Gets the tooltip text of @action. Use #GAction instead, and get tooltips from associated #GtkActionable widgets with gtk_widget_get_tooltip_text() the tooltip text a #GtkAction Returns whether the action itself is visible. Note that this doesn’t necessarily mean effective visibility. See gtk_action_is_sensitive() for that. Use #GAction instead, and control and monitor the state of #GtkActionable widgets directly %TRUE if the action itself is visible. the action object Checks whether @action is visible when horizontal Use #GAction instead, and control and monitor the visibility of associated widgets and menu items directly whether @action is visible when horizontal a #GtkAction Checks whether @action is visible when horizontal Use #GAction instead, and control and monitor the visibility of associated widgets and menu items directly whether @action is visible when horizontal a #GtkAction Returns whether the action is effectively sensitive. Use g_action_get_enabled() on a #GAction instead %TRUE if the action and its associated action group are both sensitive. the action object Returns whether the action is effectively visible. Use #GAction instead, and control and monitor the state of #GtkActionable widgets directly %TRUE if the action and its associated action group are both visible. the action object Sets the #GtkAccelGroup in which the accelerator for this action will be installed. Use #GAction and the accelerator group on an associated #GtkMenu instead the action object a #GtkAccelGroup or %NULL Sets the accel path for this action. All proxy widgets associated with the action will have this accel path, so that their accelerators are consistent. Note that @accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). Use #GAction and the accelerator path on an associated #GtkMenu instead the action object the accelerator path Sets whether @action's menu item proxies will ignore the #GtkSettings:gtk-menu-images setting and always show their image, if available. Use this if the menu item would be useless or hard to use without their image. Use g_menu_item_set_icon() on a #GMenuItem instead, if the item should have an image a #GtkAction %TRUE if menuitem proxies should always show their image Sets the icon of @action. Use #GAction instead, and g_menu_item_set_icon() to set an icon on a #GMenuItem associated with a #GAction, or gtk_container_add() to add a #GtkImage to a #GtkButton a #GtkAction the #GIcon to set Sets the icon name on @action Use #GAction instead, and g_menu_item_set_icon() to set an icon on a #GMenuItem associated with a #GAction, or gtk_container_add() to add a #GtkImage to a #GtkButton a #GtkAction the icon name to set Sets whether the action is important, this attribute is used primarily by toolbar items to decide whether to show a label or not. Use #GAction instead, and control and monitor whether labels are shown directly the action object %TRUE to make the action important Sets the label of @action. Use #GAction instead, and set a label on a menu item with g_menu_item_set_label(). For #GtkActionable widgets, use the widget-specific API to set a label a #GtkAction the label text to set Sets the :sensitive property of the action to @sensitive. Note that this doesn’t necessarily mean effective sensitivity. See gtk_action_is_sensitive() for that. Use g_simple_action_set_enabled() on a #GSimpleAction instead the action object %TRUE to make the action sensitive Sets a shorter label text on @action. Use #GAction instead, which has no equivalent of short labels a #GtkAction the label text to set Sets the stock id on @action Use #GAction instead, which has no equivalent of stock items a #GtkAction the stock id Sets the tooltip text on @action Use #GAction instead, and set tooltips on associated #GtkActionable widgets with gtk_widget_set_tooltip_text() a #GtkAction the tooltip text Sets the :visible property of the action to @visible. Note that this doesn’t necessarily mean effective visibility. See gtk_action_is_visible() for that. Use #GAction instead, and control and monitor the state of #GtkActionable widgets directly the action object %TRUE to make the action visible Sets whether @action is visible when horizontal Use #GAction instead, and control and monitor the visibility of associated widgets and menu items directly a #GtkAction whether the action is visible horizontally Sets whether @action is visible when vertical Use #GAction instead, and control and monitor the visibility of associated widgets and menu items directly a #GtkAction whether the action is visible vertically Reenable activation signals from the action Use g_simple_action_set_enabled() to enable the #GSimpleAction instead a #GtkAction The GtkActionGroup this GtkAction is associated with, or NULL (for internal use). Lookup the #GAction using g_action_map_lookup_action() instead If %TRUE, the action's menu item proxies will ignore the #GtkSettings:gtk-menu-images setting and always show their image, if available. Use this property if the menu item would be useless or hard to use without their image. There is no corresponding replacement when using #GAction The #GIcon displayed in the #GtkAction. Note that the stock icon is preferred, if the #GtkAction:stock-id property holds the id of an existing stock icon. This is an appearance property and thus only applies if #GtkActivatable:use-action-appearance is %TRUE. Use the "icon" attribute on a #GMenuItem instead When TRUE, empty menu proxies for this action are hidden. There is no corresponding replacement when using #GAction The name of the icon from the icon theme. Note that the stock icon is preferred, if the #GtkAction:stock-id property holds the id of an existing stock icon, and the #GIcon is preferred if the #GtkAction:gicon property is set. This is an appearance property and thus only applies if #GtkActivatable:use-action-appearance is %TRUE. Use the "icon" attribute on a #GMenuItem instead Whether the action is considered important. When TRUE, toolitem proxies for this action show text in GTK_TOOLBAR_BOTH_HORIZ mode. There is no corresponding replacement when using #GAction The label used for menu items and buttons that activate this action. If the label is %NULL, GTK+ uses the stock label specified via the stock-id property. This is an appearance property and thus only applies if #GtkActivatable:use-action-appearance is %TRUE. Use the "label" attribute on #GMenuItem instead A unique name for the action. Use #GAction:name instead Whether the action is enabled. Use #GAction:enabled and #GSimpleAction:enabled instead A shorter label that may be used on toolbar buttons. This is an appearance property and thus only applies if #GtkActivatable:use-action-appearance is %TRUE. There is no corresponding replacement when using #GAction The stock icon displayed in widgets representing this action. This is an appearance property and thus only applies if #GtkActivatable:use-action-appearance is %TRUE. There is no corresponding replacement when using #GAction A tooltip for this action. Use gtk_widget_set_tooltip_text() instead Whether the action is visible. There is no corresponding replacement when using #GAction Whether the toolbar item is visible when the toolbar is in a horizontal orientation. There is no corresponding replacement when using #GAction When %TRUE, toolitem proxies for this action are represented in the toolbar overflow menu. There is no corresponding replacement when using #GAction Whether the toolbar item is visible when the toolbar is in a vertical orientation. There is no corresponding replacement when using #GAction The "activate" signal is emitted when the action is activated. Use #GSimpleAction::activate instead GtkActionBar is designed to present contextual actions. It is expected to be displayed below the content and expand horizontally to fill the area. It allows placing children at the start or the end. In addition, it contains an internal centered box which is centered with respect to the full width of the box, even if the children at either side take up different amounts of space. # CSS nodes GtkActionBar has a single CSS node with name actionbar. Creates a new #GtkActionBar widget. a new #GtkActionBar Retrieves the center bar widget of the bar. the center #GtkWidget or %NULL. a #GtkActionBar Adds @child to @action_bar, packed with reference to the end of the @action_bar. A #GtkActionBar the #GtkWidget to be added to @action_bar Adds @child to @action_bar, packed with reference to the start of the @action_bar. A #GtkActionBar the #GtkWidget to be added to @action_bar Sets the center widget for the #GtkActionBar. a #GtkActionBar a widget to use for the center The parent class. Signal emitted when the action is activated. the action object a menu item connected to the action. the action object a toolbar item connected to the action. the action object the menu item provided by the action, or %NULL. a #GtkAction #GtkActionEntry structs are used with gtk_action_group_add_actions() to construct actions. The name of the action. The stock id for the action, or the name of an icon from the icon theme. The label for the action. This field should typically be marked for translation, see gtk_action_group_set_translation_domain(). If @label is %NULL, the label of the stock item with id @stock_id is used. The accelerator for the action, in the format understood by gtk_accelerator_parse(). The tooltip for the action. This field should typically be marked for translation, see gtk_action_group_set_translation_domain(). The function to call when the action is activated. Actions are organised into groups. An action group is essentially a map from names to #GtkAction objects. All actions that would make sense to use in a particular context should be in a single group. Multiple action groups may be used for a particular user interface. In fact, it is expected that most nontrivial applications will make use of multiple groups. For example, in an application that can edit multiple documents, one group holding global actions (e.g. quit, about, new), and one group per document holding actions that act on that document (eg. save, cut/copy/paste, etc). Each window’s menus would be constructed from a combination of two action groups. ## Accelerators ## {#Action-Accel} Accelerators are handled by the GTK+ accelerator map. All actions are assigned an accelerator path (which normally has the form `<Actions>/group-name/action-name`) and a shortcut is associated with this accelerator path. All menuitems and toolitems take on this accelerator path. The GTK+ accelerator map code makes sure that the correct shortcut is displayed next to the menu item. # GtkActionGroup as GtkBuildable # {#GtkActionGroup-BUILDER-UI} The #GtkActionGroup implementation of the #GtkBuildable interface accepts #GtkAction objects as `<child>` elements in UI definitions. Note that it is probably more common to define actions and action groups in the code, since they are directly related to what the code can do. The GtkActionGroup implementation of the GtkBuildable interface supports a custom `<accelerator>` element, which has attributes named “key“ and “modifiers“ and allows to specify accelerators. This is similar to the `<accelerator>` element of #GtkWidget, the main difference is that it doesn’t allow you to specify a signal. ## A #GtkDialog UI definition fragment. ## |[<!-- language="xml" --> <object class="GtkActionGroup" id="actiongroup"> <child> <object class="GtkAction" id="About"> <property name="name">About</property> <property name="stock_id">gtk-about</property> <signal handler="about_activate" name="activate"/> </object> <accelerator key="F1" modifiers="GDK_CONTROL_MASK | GDK_SHIFT_MASK"/> </child> </object> ]| Creates a new #GtkActionGroup object. The name of the action group is used when associating [keybindings][Action-Accel] with the actions. the new #GtkActionGroup the name of the action group. Looks up an action in the action group by name. the action, or %NULL if no action by that name exists the action group the name of the action Adds an action object to the action group. Note that this function does not set up the accel path of the action, which can lead to problems if a user tries to modify the accelerator of a menuitem associated with the action. Therefore you must either set the accel path yourself with gtk_action_set_accel_path(), or use `gtk_action_group_add_action_with_accel (..., NULL)`. the action group an action Adds an action object to the action group and sets up the accelerator. If @accelerator is %NULL, attempts to use the accelerator associated with the stock_id of the action. Accel paths are set to `<Actions>/group-name/action-name`. the action group the action to add the accelerator for the action, in the format understood by gtk_accelerator_parse(), or "" for no accelerator, or %NULL to use the stock accelerator This is a convenience function to create a number of actions and add them to the action group. The “activate” signals of the actions are connected to the callbacks and their accel paths are set to `<Actions>/group-name/action-name`. the action group an array of action descriptions the number of entries data to pass to the action callbacks This variant of gtk_action_group_add_actions() adds a #GDestroyNotify callback for @user_data. the action group an array of action descriptions the number of entries data to pass to the action callbacks destroy notification callback for @user_data This is a convenience routine to create a group of radio actions and add them to the action group. The “changed” signal of the first radio action is connected to the @on_change callback and the accel paths of the actions are set to `<Actions>/group-name/action-name`. the action group an array of radio action descriptions the number of entries the value of the action to activate initially, or -1 if no action should be activated the callback to connect to the changed signal data to pass to the action callbacks This variant of gtk_action_group_add_radio_actions() adds a #GDestroyNotify callback for @user_data. the action group an array of radio action descriptions the number of entries the value of the action to activate initially, or -1 if no action should be activated the callback to connect to the changed signal data to pass to the action callbacks destroy notification callback for @user_data This is a convenience function to create a number of toggle actions and add them to the action group. The “activate” signals of the actions are connected to the callbacks and their accel paths are set to `<Actions>/group-name/action-name`. the action group an array of toggle action descriptions the number of entries data to pass to the action callbacks This variant of gtk_action_group_add_toggle_actions() adds a #GDestroyNotify callback for @user_data. the action group an array of toggle action descriptions the number of entries data to pass to the action callbacks destroy notification callback for @user_data Gets the accelerator group. the accelerator group associated with this action group or %NULL if there is none. a #GtkActionGroup Looks up an action in the action group by name. the action, or %NULL if no action by that name exists the action group the name of the action Gets the name of the action group. the name of the action group. the action group Returns %TRUE if the group is sensitive. The constituent actions can only be logically sensitive (see gtk_action_is_sensitive()) if they are sensitive (see gtk_action_get_sensitive()) and their group is sensitive. %TRUE if the group is sensitive. the action group Returns %TRUE if the group is visible. The constituent actions can only be logically visible (see gtk_action_is_visible()) if they are visible (see gtk_action_get_visible()) and their group is visible. %TRUE if the group is visible. the action group Lists the actions in the action group. an allocated list of the action objects in the action group the action group Removes an action object from the action group. the action group an action Sets the accelerator group to be used by every action in this group. a #GtkActionGroup a #GtkAccelGroup to set or %NULL Changes the sensitivity of @action_group the action group new sensitivity Sets a function to be used for translating the @label and @tooltip of #GtkActionEntrys added by gtk_action_group_add_actions(). If you’re using gettext(), it is enough to set the translation domain with gtk_action_group_set_translation_domain(). a #GtkActionGroup a #GtkTranslateFunc data to be passed to @func and @notify a #GDestroyNotify function to be called when @action_group is destroyed and when the translation function is changed again Sets the translation domain and uses g_dgettext() for translating the @label and @tooltip of #GtkActionEntrys added by gtk_action_group_add_actions(). If you’re not using gettext() for localization, see gtk_action_group_set_translate_func(). a #GtkActionGroup the translation domain to use for g_dgettext() calls, or %NULL to use the domain set with textdomain() Changes the visible of @action_group. the action group new visiblity Translates a string using the function set with gtk_action_group_set_translate_func(). This is mainly intended for language bindings. the translation of @string a #GtkActionGroup a string The accelerator group the actions of this group should use. A name for the action. Whether the action group is enabled. Whether the action group is visible. The ::connect-proxy signal is emitted after connecting a proxy to an action in the group. Note that the proxy may have been connected to a different action before. This is intended for simple customizations for which a custom action class would be too clumsy, e.g. showing tooltips for menuitems in the statusbar. #GtkUIManager proxies the signal and provides global notification just before any action is connected to a proxy, which is probably more convenient to use. the action the proxy The ::disconnect-proxy signal is emitted after disconnecting a proxy from an action in the group. #GtkUIManager proxies the signal and provides global notification just before any action is connected to a proxy, which is probably more convenient to use. the action the proxy The ::post-activate signal is emitted just after the @action in the @action_group is activated This is intended for #GtkUIManager to proxy the signal and provide global notification just after any action is activated. the action The ::pre-activate signal is emitted just before the @action in the @action_group is activated This is intended for #GtkUIManager to proxy the signal and provide global notification just before any action is activated. the action The parent class. Looks up an action in the action group by name. the action, or %NULL if no action by that name exists the action group the name of the action This interface provides a convenient way of associating widgets with actions on a #GtkApplicationWindow or #GtkApplication. It primarily consists of two properties: #GtkActionable:action-name and #GtkActionable:action-target. There are also some convenience APIs for setting these properties. The action will be looked up in action groups that are found among the widgets ancestors. Most commonly, these will be the actions with the “win.” or “app.” prefix that are associated with the #GtkApplicationWindow or #GtkApplication, but other action groups that are added with gtk_widget_insert_action_group() will be consulted as well. Gets the action name for @actionable. See gtk_actionable_set_action_name() for more information. the action name, or %NULL if none is set a #GtkActionable widget Gets the current target value of @actionable. See gtk_actionable_set_action_target_value() for more information. the current target value a #GtkActionable widget Specifies the name of the action with which this widget should be associated. If @action_name is %NULL then the widget will be unassociated from any previous action. Usually this function is used when the widget is located (or will be located) within the hierarchy of a #GtkApplicationWindow. Names are of the form “win.save” or “app.quit” for actions on the containing #GtkApplicationWindow or its associated #GtkApplication, respectively. This is the same form used for actions in the #GMenu associated with the window. a #GtkActionable widget an action name, or %NULL Sets the target value of an actionable widget. If @target_value is %NULL then the target value is unset. The target value has two purposes. First, it is used as the parameter to activation of the action associated with the #GtkActionable widget. Second, it is used to determine if the widget should be rendered as “active” — the widget is active if the state is equal to the given target. Consider the example of associating a set of buttons with a #GAction with string state in a typical “radio button” situation. Each button will be associated with the same action, but with a different target value for that action. Clicking on a particular button will activate the action with the target of that button, which will typically cause the action’s state to change to that value. Since the action’s state is now equal to the target value of the button, the button will now be rendered as active (and the other buttons, with different targets, rendered inactive). a #GtkActionable widget a #GVariant to set as the target value, or %NULL Gets the action name for @actionable. See gtk_actionable_set_action_name() for more information. the action name, or %NULL if none is set a #GtkActionable widget Gets the current target value of @actionable. See gtk_actionable_set_action_target_value() for more information. the current target value a #GtkActionable widget Specifies the name of the action with which this widget should be associated. If @action_name is %NULL then the widget will be unassociated from any previous action. Usually this function is used when the widget is located (or will be located) within the hierarchy of a #GtkApplicationWindow. Names are of the form “win.save” or “app.quit” for actions on the containing #GtkApplicationWindow or its associated #GtkApplication, respectively. This is the same form used for actions in the #GMenu associated with the window. a #GtkActionable widget an action name, or %NULL Sets the target of an actionable widget. This is a convenience function that calls g_variant_new() for @format_string and uses the result to call gtk_actionable_set_action_target_value(). If you are setting a string-valued target and want to set the action name at the same time, you can use gtk_actionable_set_detailed_action_name (). a #GtkActionable widget a GVariant format string arguments appropriate for @format_string Sets the target value of an actionable widget. If @target_value is %NULL then the target value is unset. The target value has two purposes. First, it is used as the parameter to activation of the action associated with the #GtkActionable widget. Second, it is used to determine if the widget should be rendered as “active” — the widget is active if the state is equal to the given target. Consider the example of associating a set of buttons with a #GAction with string state in a typical “radio button” situation. Each button will be associated with the same action, but with a different target value for that action. Clicking on a particular button will activate the action with the target of that button, which will typically cause the action’s state to change to that value. Since the action’s state is now equal to the target value of the button, the button will now be rendered as active (and the other buttons, with different targets, rendered inactive). a #GtkActionable widget a #GVariant to set as the target value, or %NULL Sets the action-name and associated string target value of an actionable widget. @detailed_action_name is a string in the format accepted by g_action_parse_detailed_name(). (Note that prior to version 3.22.25, this function is only usable for actions with a simple "s" target, and @detailed_action_name must be of the form `"action::target"` where `action` is the action name and `target` is the string to use as the target.) a #GtkActionable widget the detailed action name The interface vtable for #GtkActionable. virtual function for gtk_actionable_get_action_name() the action name, or %NULL if none is set a #GtkActionable widget virtual function for gtk_actionable_set_action_name() a #GtkActionable widget an action name, or %NULL virtual function for gtk_actionable_get_action_target_value() the current target value a #GtkActionable widget virtual function for gtk_actionable_set_action_target_value() a #GtkActionable widget a #GVariant to set as the target value, or %NULL Activatable widgets can be connected to a #GtkAction and reflects the state of its action. A #GtkActivatable can also provide feedback through its action, as they are responsible for activating their related actions. # Implementing GtkActivatable When extending a class that is already #GtkActivatable; it is only necessary to implement the #GtkActivatable->sync_action_properties() and #GtkActivatable->update() methods and chain up to the parent implementation, however when introducing a new #GtkActivatable class; the #GtkActivatable:related-action and #GtkActivatable:use-action-appearance properties need to be handled by the implementor. Handling these properties is mostly a matter of installing the action pointer and boolean flag on your instance, and calling gtk_activatable_do_set_related_action() and gtk_activatable_sync_action_properties() at the appropriate times. ## A class fragment implementing #GtkActivatable |[<!-- language="C" --> enum { ... PROP_ACTIVATABLE_RELATED_ACTION, PROP_ACTIVATABLE_USE_ACTION_APPEARANCE } struct _FooBarPrivate { ... GtkAction *action; gboolean use_action_appearance; }; ... static void foo_bar_activatable_interface_init (GtkActivatableIface *iface); static void foo_bar_activatable_update (GtkActivatable *activatable, GtkAction *action, const gchar *property_name); static void foo_bar_activatable_sync_action_properties (GtkActivatable *activatable, GtkAction *action); ... static void foo_bar_class_init (FooBarClass *klass) { ... g_object_class_override_property (gobject_class, PROP_ACTIVATABLE_RELATED_ACTION, "related-action"); g_object_class_override_property (gobject_class, PROP_ACTIVATABLE_USE_ACTION_APPEARANCE, "use-action-appearance"); ... } static void foo_bar_activatable_interface_init (GtkActivatableIface *iface) { iface->update = foo_bar_activatable_update; iface->sync_action_properties = foo_bar_activatable_sync_action_properties; } ... Break the reference using gtk_activatable_do_set_related_action()... static void foo_bar_dispose (GObject *object) { FooBar *bar = FOO_BAR (object); FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar); ... if (priv->action) { gtk_activatable_do_set_related_action (GTK_ACTIVATABLE (bar), NULL); priv->action = NULL; } G_OBJECT_CLASS (foo_bar_parent_class)->dispose (object); } ... Handle the “related-action” and “use-action-appearance” properties ... static void foo_bar_set_property (GObject *object, guint prop_id, const GValue *value, GParamSpec *pspec) { FooBar *bar = FOO_BAR (object); FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar); switch (prop_id) { ... case PROP_ACTIVATABLE_RELATED_ACTION: foo_bar_set_related_action (bar, g_value_get_object (value)); break; case PROP_ACTIVATABLE_USE_ACTION_APPEARANCE: foo_bar_set_use_action_appearance (bar, g_value_get_boolean (value)); break; default: G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec); break; } } static void foo_bar_get_property (GObject *object, guint prop_id, GValue *value, GParamSpec *pspec) { FooBar *bar = FOO_BAR (object); FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar); switch (prop_id) { ... case PROP_ACTIVATABLE_RELATED_ACTION: g_value_set_object (value, priv->action); break; case PROP_ACTIVATABLE_USE_ACTION_APPEARANCE: g_value_set_boolean (value, priv->use_action_appearance); break; default: G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec); break; } } static void foo_bar_set_use_action_appearance (FooBar *bar, gboolean use_appearance) { FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar); if (priv->use_action_appearance != use_appearance) { priv->use_action_appearance = use_appearance; gtk_activatable_sync_action_properties (GTK_ACTIVATABLE (bar), priv->action); } } ... call gtk_activatable_do_set_related_action() and then assign the action pointer, no need to reference the action here since gtk_activatable_do_set_related_action() already holds a reference here for you... static void foo_bar_set_related_action (FooBar *bar, GtkAction *action) { FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar); if (priv->action == action) return; gtk_activatable_do_set_related_action (GTK_ACTIVATABLE (bar), action); priv->action = action; } ... Selectively reset and update activatable depending on the use-action-appearance property ... static void gtk_button_activatable_sync_action_properties (GtkActivatable *activatable, GtkAction *action) { GtkButtonPrivate *priv = GTK_BUTTON_GET_PRIVATE (activatable); if (!action) return; if (gtk_action_is_visible (action)) gtk_widget_show (GTK_WIDGET (activatable)); else gtk_widget_hide (GTK_WIDGET (activatable)); gtk_widget_set_sensitive (GTK_WIDGET (activatable), gtk_action_is_sensitive (action)); ... if (priv->use_action_appearance) { if (gtk_action_get_stock_id (action)) foo_bar_set_stock (button, gtk_action_get_stock_id (action)); else if (gtk_action_get_label (action)) foo_bar_set_label (button, gtk_action_get_label (action)); ... } } static void foo_bar_activatable_update (GtkActivatable *activatable, GtkAction *action, const gchar *property_name) { FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (activatable); if (strcmp (property_name, "visible") == 0) { if (gtk_action_is_visible (action)) gtk_widget_show (GTK_WIDGET (activatable)); else gtk_widget_hide (GTK_WIDGET (activatable)); } else if (strcmp (property_name, "sensitive") == 0) gtk_widget_set_sensitive (GTK_WIDGET (activatable), gtk_action_is_sensitive (action)); ... if (!priv->use_action_appearance) return; if (strcmp (property_name, "stock-id") == 0) foo_bar_set_stock (button, gtk_action_get_stock_id (action)); else if (strcmp (property_name, "label") == 0) foo_bar_set_label (button, gtk_action_get_label (action)); ... } ]| This is called to update the activatable completely, this is called internally when the #GtkActivatable:related-action property is set or unset and by the implementing class when #GtkActivatable:use-action-appearance changes. a #GtkActivatable the related #GtkAction or %NULL Called to update the activatable when its related action’s properties change. You must check the #GtkActivatable:use-action-appearance property only apply action properties that are meant to effect the appearance accordingly. This is a utility function for #GtkActivatable implementors. When implementing #GtkActivatable you must call this when handling changes of the #GtkActivatable:related-action, and you must also use this to break references in #GObject->dispose(). This function adds a reference to the currently set related action for you, it also makes sure the #GtkActivatable->update() method is called when the related #GtkAction properties change and registers to the action’s proxy list. > Be careful to call this before setting the local > copy of the #GtkAction property, since this function uses > gtk_activatable_get_related_action() to retrieve the > previous action. a #GtkActivatable the #GtkAction to set Gets the related #GtkAction for @activatable. the related #GtkAction if one is set. a #GtkActivatable Gets whether this activatable should reset its layout and appearance when setting the related action or when the action changes appearance. whether @activatable uses its actions appearance. a #GtkActivatable Sets the related action on the @activatable object. > #GtkActivatable implementors need to handle the #GtkActivatable:related-action > property and call gtk_activatable_do_set_related_action() when it changes. a #GtkActivatable the #GtkAction to set Sets whether this activatable should reset its layout and appearance when setting the related action or when the action changes appearance > #GtkActivatable implementors need to handle the > #GtkActivatable:use-action-appearance property and call > gtk_activatable_sync_action_properties() to update @activatable > if needed. a #GtkActivatable whether to use the actions appearance This is called to update the activatable completely, this is called internally when the #GtkActivatable:related-action property is set or unset and by the implementing class when #GtkActivatable:use-action-appearance changes. a #GtkActivatable the related #GtkAction or %NULL The action that this activatable will activate and receive updates from for various states and possibly appearance. > #GtkActivatable implementors need to handle the this property and > call gtk_activatable_do_set_related_action() when it changes. Whether this activatable should reset its layout and appearance when setting the related action or when the action changes appearance. See the #GtkAction documentation directly to find which properties should be ignored by the #GtkActivatable when this property is %FALSE. > #GtkActivatable implementors need to handle this property > and call gtk_activatable_sync_action_properties() on the activatable > widget when it changes. > This method can be called with a %NULL action at times. Called to update the activatable when its related action’s properties change. You must check the #GtkActivatable:use-action-appearance property only apply action properties that are meant to effect the appearance accordingly. Called to update the activatable completely, this is called internally when #GtkActivatable:related-action property is set or unset and by the implementor when #GtkActivatable:use-action-appearance changes. a #GtkActivatable the related #GtkAction or %NULL The #GtkAdjustment object represents a value which has an associated lower and upper bound, together with step and page increments, and a page size. It is used within several GTK+ widgets, including #GtkSpinButton, #GtkViewport, and #GtkRange (which is a base class for #GtkScrollbar and #GtkScale). The #GtkAdjustment object does not update the value itself. Instead it is left up to the owner of the #GtkAdjustment to control the value. Creates a new #GtkAdjustment. a new #GtkAdjustment the initial value the minimum value the maximum value the step increment the page increment the page size Emits a #GtkAdjustment::changed signal from the #GtkAdjustment. This is typically called by the owner of the #GtkAdjustment after it has changed any of the #GtkAdjustment properties other than the value. GTK+ emits #GtkAdjustment::changed itself whenever any of the properties (other than value) change a #GtkAdjustment Emits a #GtkAdjustment::value-changed signal from the #GtkAdjustment. This is typically called by the owner of the #GtkAdjustment after it has changed the #GtkAdjustment:value property. GTK+ emits #GtkAdjustment::value-changed itself whenever the value changes a #GtkAdjustment Emits a #GtkAdjustment::changed signal from the #GtkAdjustment. This is typically called by the owner of the #GtkAdjustment after it has changed any of the #GtkAdjustment properties other than the value. GTK+ emits #GtkAdjustment::changed itself whenever any of the properties (other than value) change a #GtkAdjustment Updates the #GtkAdjustment:value property to ensure that the range between @lower and @upper is in the current page (i.e. between #GtkAdjustment:value and #GtkAdjustment:value + #GtkAdjustment:page-size). If the range is larger than the page size, then only the start of it will be in the current page. A #GtkAdjustment::value-changed signal will be emitted if the value is changed. a #GtkAdjustment the lower value the upper value Sets all properties of the adjustment at once. Use this function to avoid multiple emissions of the #GtkAdjustment::changed signal. See gtk_adjustment_set_lower() for an alternative way of compressing multiple emissions of #GtkAdjustment::changed into one. a #GtkAdjustment the new value the new minimum value the new maximum value the new step increment the new page increment the new page size Retrieves the minimum value of the adjustment. The current minimum value of the adjustment a #GtkAdjustment Gets the smaller of step increment and page increment. the minimum increment of @adjustment a #GtkAdjustment Retrieves the page increment of the adjustment. The current page increment of the adjustment a #GtkAdjustment Retrieves the page size of the adjustment. The current page size of the adjustment a #GtkAdjustment Retrieves the step increment of the adjustment. The current step increment of the adjustment. a #GtkAdjustment Retrieves the maximum value of the adjustment. The current maximum value of the adjustment a #GtkAdjustment Gets the current value of the adjustment. See gtk_adjustment_set_value(). The current value of the adjustment a #GtkAdjustment Sets the minimum value of the adjustment. When setting multiple adjustment properties via their individual setters, multiple #GtkAdjustment::changed signals will be emitted. However, since the emission of the #GtkAdjustment::changed signal is tied to the emission of the #GObject::notify signals of the changed properties, it’s possible to compress the #GtkAdjustment::changed signals into one by calling g_object_freeze_notify() and g_object_thaw_notify() around the calls to the individual setters. Alternatively, using a single g_object_set() for all the properties to change, or using gtk_adjustment_configure() has the same effect of compressing #GtkAdjustment::changed emissions. a #GtkAdjustment the new minimum value Sets the page increment of the adjustment. See gtk_adjustment_set_lower() about how to compress multiple emissions of the #GtkAdjustment::changed signal when setting multiple adjustment properties. a #GtkAdjustment the new page increment Sets the page size of the adjustment. See gtk_adjustment_set_lower() about how to compress multiple emissions of the GtkAdjustment::changed signal when setting multiple adjustment properties. a #GtkAdjustment the new page size Sets the step increment of the adjustment. See gtk_adjustment_set_lower() about how to compress multiple emissions of the #GtkAdjustment::changed signal when setting multiple adjustment properties. a #GtkAdjustment the new step increment Sets the maximum value of the adjustment. Note that values will be restricted by `upper - page-size` if the page-size property is nonzero. See gtk_adjustment_set_lower() about how to compress multiple emissions of the #GtkAdjustment::changed signal when setting multiple adjustment properties. a #GtkAdjustment the new maximum value Sets the #GtkAdjustment value. The value is clamped to lie between #GtkAdjustment:lower and #GtkAdjustment:upper. Note that for adjustments which are used in a #GtkScrollbar, the effective range of allowed values goes from #GtkAdjustment:lower to #GtkAdjustment:upper - #GtkAdjustment:page-size. a #GtkAdjustment the new value Emits a #GtkAdjustment::value-changed signal from the #GtkAdjustment. This is typically called by the owner of the #GtkAdjustment after it has changed the #GtkAdjustment:value property. GTK+ emits #GtkAdjustment::value-changed itself whenever the value changes a #GtkAdjustment The minimum value of the adjustment. The page increment of the adjustment. The page size of the adjustment. Note that the page-size is irrelevant and should be set to zero if the adjustment is used for a simple scalar value, e.g. in a #GtkSpinButton. The step increment of the adjustment. The maximum value of the adjustment. Note that values will be restricted by `upper - page-size` if the page-size property is nonzero. The value of the adjustment. Emitted when one or more of the #GtkAdjustment properties have been changed, other than the #GtkAdjustment:value property. Emitted when the #GtkAdjustment:value property has been changed. a #GtkAdjustment a #GtkAdjustment Controls how a widget deals with extra space in a single (x or y) dimension. Alignment only matters if the widget receives a “too large” allocation, for example if you packed the widget with the #GtkWidget:expand flag inside a #GtkBox, then the widget might get extra space. If you have for example a 16x16 icon inside a 32x32 space, the icon could be scaled and stretched, it could be centered, or it could be positioned to one side of the space. Note that in horizontal context @GTK_ALIGN_START and @GTK_ALIGN_END are interpreted relative to text direction. GTK_ALIGN_BASELINE support for it is optional for containers and widgets, and it is only supported for vertical alignment. When its not supported by a child or a container it is treated as @GTK_ALIGN_FILL. stretch to fill all space if possible, center if no meaningful way to stretch snap to left or top side, leaving space on right or bottom snap to right or bottom side, leaving space on left or top center natural width of widget inside the allocation align the widget according to the baseline. Since 3.10. The #GtkAlignment widget controls the alignment and size of its child widget. It has four settings: xscale, yscale, xalign, and yalign. The scale settings are used to specify how much the child widget should expand to fill the space allocated to the #GtkAlignment. The values can range from 0 (meaning the child doesn’t expand at all) to 1 (meaning the child expands to fill all of the available space). The align settings are used to place the child widget within the available area. The values range from 0 (top or left) to 1 (bottom or right). Of course, if the scale settings are both set to 1, the alignment settings have no effect. GtkAlignment has been deprecated in 3.14 and should not be used in newly-written code. The desired effect can be achieved by using the #GtkWidget:halign, #GtkWidget:valign and #GtkWidget:margin properties on the child widget. Creates a new #GtkAlignment. Use #GtkWidget alignment and margin properties the new #GtkAlignment the horizontal alignment of the child widget, from 0 (left) to 1 (right). the vertical alignment of the child widget, from 0 (top) to 1 (bottom). the amount that the child widget expands horizontally to fill up unused space, from 0 to 1. A value of 0 indicates that the child widget should never expand. A value of 1 indicates that the child widget will expand to fill all of the space allocated for the #GtkAlignment. the amount that the child widget expands vertically to fill up unused space, from 0 to 1. The values are similar to @xscale. Gets the padding on the different sides of the widget. See gtk_alignment_set_padding (). Use #GtkWidget alignment and margin properties a #GtkAlignment location to store the padding for the top of the widget, or %NULL location to store the padding for the bottom of the widget, or %NULL location to store the padding for the left of the widget, or %NULL location to store the padding for the right of the widget, or %NULL Sets the #GtkAlignment values. Use #GtkWidget alignment and margin properties a #GtkAlignment. the horizontal alignment of the child widget, from 0 (left) to 1 (right). the vertical alignment of the child widget, from 0 (top) to 1 (bottom). the amount that the child widget expands horizontally to fill up unused space, from 0 to 1. A value of 0 indicates that the child widget should never expand. A value of 1 indicates that the child widget will expand to fill all of the space allocated for the #GtkAlignment. the amount that the child widget expands vertically to fill up unused space, from 0 to 1. The values are similar to @xscale. Sets the padding on the different sides of the widget. The padding adds blank space to the sides of the widget. For instance, this can be used to indent the child widget towards the right by adding padding on the left. Use #GtkWidget alignment and margin properties a #GtkAlignment the padding at the top of the widget the padding at the bottom of the widget the padding at the left of the widget the padding at the right of the widget. The padding to insert at the bottom of the widget. Use gtk_widget_set_margin_bottom() instead The padding to insert at the left of the widget. Use gtk_widget_set_margin_start() instead The padding to insert at the right of the widget. Use gtk_widget_set_margin_end() instead The padding to insert at the top of the widget. Use gtk_widget_set_margin_top() instead Horizontal position of child in available space. A value of 0.0 will flush the child left (or right, in RTL locales); a value of 1.0 will flush the child right (or left, in RTL locales). Use gtk_widget_set_halign() on the child instead If available horizontal space is bigger than needed, how much of it to use for the child. A value of 0.0 means none; a value of 1.0 means all. Use gtk_widget_set_hexpand() on the child instead Vertical position of child in available space. A value of 0.0 will flush the child to the top; a value of 1.0 will flush the child to the bottom. Use gtk_widget_set_valign() on the child instead If available vertical space is bigger than needed, how much of it to use for the child. A value of 0.0 means none; a value of 1.0 means all. Use gtk_widget_set_vexpand() on the child instead The parent class. #GtkAppChooser is an interface that can be implemented by widgets which allow the user to choose an application (typically for the purpose of opening a file). The main objects that implement this interface are #GtkAppChooserWidget, #GtkAppChooserDialog and #GtkAppChooserButton. Applications are represented by GIO #GAppInfo objects here. GIO has a concept of recommended and fallback applications for a given content type. Recommended applications are those that claim to handle the content type itself, while fallback also includes applications that handle a more generic content type. GIO also knows the default and last-used application for a given content type. The #GtkAppChooserWidget provides detailed control over whether the shown list of applications should include default, recommended or fallback applications. To obtain the application that has been selected in a #GtkAppChooser, use gtk_app_chooser_get_app_info(). Returns the currently selected application. a #GAppInfo for the currently selected application, or %NULL if none is selected. Free with g_object_unref() a #GtkAppChooser Returns the current value of the #GtkAppChooser:content-type property. the content type of @self. Free with g_free() a #GtkAppChooser Reloads the list of applications. a #GtkAppChooser The content type of the #GtkAppChooser object. See [GContentType][gio-GContentType] for more information about content types. The #GtkAppChooserButton is a widget that lets the user select an application. It implements the #GtkAppChooser interface. Initially, a #GtkAppChooserButton selects the first application in its list, which will either be the most-recently used application or, if #GtkAppChooserButton:show-default-item is %TRUE, the default application. The list of applications shown in a #GtkAppChooserButton includes the recommended applications for the given content type. When #GtkAppChooserButton:show-default-item is set, the default application is also included. To let the user chooser other applications, you can set the #GtkAppChooserButton:show-dialog-item property, which allows to open a full #GtkAppChooserDialog. It is possible to add custom items to the list, using gtk_app_chooser_button_append_custom_item(). These items cause the #GtkAppChooserButton::custom-item-activated signal to be emitted when they are selected. To track changes in the selected application, use the #GtkComboBox::changed signal. Creates a new #GtkAppChooserButton for applications that can handle content of the given type. a newly created #GtkAppChooserButton the content type to show applications for Signal emitted when a custom item, previously added with gtk_app_chooser_button_append_custom_item(), is activated from the dropdown menu. Appends a custom item to the list of applications that is shown in the popup; the item name must be unique per-widget. Clients can use the provided name as a detail for the #GtkAppChooserButton::custom-item-activated signal, to add a callback for the activation of a particular custom item in the list. See also gtk_app_chooser_button_append_separator(). a #GtkAppChooserButton the name of the custom item the label for the custom item the icon for the custom item Appends a separator to the list of applications that is shown in the popup. a #GtkAppChooserButton Returns the text to display at the top of the dialog. the text to display at the top of the dialog, or %NULL, in which case a default text is displayed a #GtkAppChooserButton Returns the current value of the #GtkAppChooserButton:show-default-item property. the value of #GtkAppChooserButton:show-default-item a #GtkAppChooserButton Returns the current value of the #GtkAppChooserButton:show-dialog-item property. the value of #GtkAppChooserButton:show-dialog-item a #GtkAppChooserButton Selects a custom item previously added with gtk_app_chooser_button_append_custom_item(). Use gtk_app_chooser_refresh() to bring the selection to its initial state. a #GtkAppChooserButton the name of the custom item Sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text. a #GtkAppChooserButton a string containing Pango markup Sets whether the dropdown menu of this button should show the default application for the given content type at top. a #GtkAppChooserButton the new value for #GtkAppChooserButton:show-default-item Sets whether the dropdown menu of this button should show an entry to trigger a #GtkAppChooserDialog. a #GtkAppChooserButton the new value for #GtkAppChooserButton:show-dialog-item The text to show at the top of the dialog that can be opened from the button. The string may contain Pango markup. The #GtkAppChooserButton:show-default-item property determines whether the dropdown menu should show the default application on top for the provided content type. The #GtkAppChooserButton:show-dialog-item property determines whether the dropdown menu should show an item that triggers a #GtkAppChooserDialog when clicked. Emitted when a custom item, previously added with gtk_app_chooser_button_append_custom_item(), is activated from the dropdown menu. the name of the activated item The parent class. Signal emitted when a custom item, previously added with gtk_app_chooser_button_append_custom_item(), is activated from the dropdown menu. #GtkAppChooserDialog shows a #GtkAppChooserWidget inside a #GtkDialog. Note that #GtkAppChooserDialog does not have any interesting methods of its own. Instead, you should get the embedded #GtkAppChooserWidget using gtk_app_chooser_dialog_get_widget() and call its methods if the generic #GtkAppChooser interface is not sufficient for your needs. To set the heading that is shown above the #GtkAppChooserWidget, use gtk_app_chooser_dialog_set_heading(). Creates a new #GtkAppChooserDialog for the provided #GFile, to allow the user to select an application for it. a newly created #GtkAppChooserDialog a #GtkWindow, or %NULL flags for this dialog a #GFile Creates a new #GtkAppChooserDialog for the provided content type, to allow the user to select an application for it. a newly created #GtkAppChooserDialog a #GtkWindow, or %NULL flags for this dialog a content type string Returns the text to display at the top of the dialog. the text to display at the top of the dialog, or %NULL, in which case a default text is displayed a #GtkAppChooserDialog Returns the #GtkAppChooserWidget of this dialog. the #GtkAppChooserWidget of @self a #GtkAppChooserDialog Sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text. a #GtkAppChooserDialog a string containing Pango markup The GFile used by the #GtkAppChooserDialog. The dialog's #GtkAppChooserWidget content type will be guessed from the file, if present. The text to show at the top of the dialog. The string may contain Pango markup. The parent class. #GtkAppChooserWidget is a widget for selecting applications. It is the main building block for #GtkAppChooserDialog. Most applications only need to use the latter; but you can use this widget as part of a larger widget if you have special needs. #GtkAppChooserWidget offers detailed control over what applications are shown, using the #GtkAppChooserWidget:show-default, #GtkAppChooserWidget:show-recommended, #GtkAppChooserWidget:show-fallback, #GtkAppChooserWidget:show-other and #GtkAppChooserWidget:show-all properties. See the #GtkAppChooser documentation for more information about these groups of applications. To keep track of the selected application, use the #GtkAppChooserWidget::application-selected and #GtkAppChooserWidget::application-activated signals. # CSS nodes GtkAppChooserWidget has a single CSS node with name appchooser. Creates a new #GtkAppChooserWidget for applications that can handle content of the given type. a newly created #GtkAppChooserWidget the content type to show applications for Signal emitted when an application item is activated from the widget’s list. Signal emitted when an application item is selected from the widget’s list. Signal emitted when a context menu is about to popup over an application item. Returns the text that is shown if there are not applications that can handle the content type. the value of #GtkAppChooserWidget:default-text a #GtkAppChooserWidget Returns the current value of the #GtkAppChooserWidget:show-all property. the value of #GtkAppChooserWidget:show-all a #GtkAppChooserWidget Returns the current value of the #GtkAppChooserWidget:show-default property. the value of #GtkAppChooserWidget:show-default a #GtkAppChooserWidget Returns the current value of the #GtkAppChooserWidget:show-fallback property. the value of #GtkAppChooserWidget:show-fallback a #GtkAppChooserWidget Returns the current value of the #GtkAppChooserWidget:show-other property. the value of #GtkAppChooserWidget:show-other a #GtkAppChooserWidget Returns the current value of the #GtkAppChooserWidget:show-recommended property. the value of #GtkAppChooserWidget:show-recommended a #GtkAppChooserWidget Sets the text that is shown if there are not applications that can handle the content type. a #GtkAppChooserWidget the new value for #GtkAppChooserWidget:default-text Sets whether the app chooser should show all applications in a flat list. a #GtkAppChooserWidget the new value for #GtkAppChooserWidget:show-all Sets whether the app chooser should show the default handler for the content type in a separate section. a #GtkAppChooserWidget the new value for #GtkAppChooserWidget:show-default Sets whether the app chooser should show related applications for the content type in a separate section. a #GtkAppChooserWidget the new value for #GtkAppChooserWidget:show-fallback Sets whether the app chooser should show applications which are unrelated to the content type. a #GtkAppChooserWidget the new value for #GtkAppChooserWidget:show-other Sets whether the app chooser should show recommended applications for the content type in a separate section. a #GtkAppChooserWidget the new value for #GtkAppChooserWidget:show-recommended The #GtkAppChooserWidget:default-text property determines the text that appears in the widget when there are no applications for the given content type. See also gtk_app_chooser_widget_set_default_text(). If the #GtkAppChooserWidget:show-all property is %TRUE, the app chooser presents all applications in a single list, without subsections for default, recommended or related applications. The ::show-default property determines whether the app chooser should show the default handler for the content type in a separate section. If %FALSE, the default handler is listed among the recommended applications. The #GtkAppChooserWidget:show-fallback property determines whether the app chooser should show a section for fallback applications. If %FALSE, the fallback applications are listed among the other applications. The #GtkAppChooserWidget:show-other property determines whether the app chooser should show a section for other applications. The #GtkAppChooserWidget:show-recommended property determines whether the app chooser should show a section for recommended applications. If %FALSE, the recommended applications are listed among the other applications. Emitted when an application item is activated from the widget's list. This usually happens when the user double clicks an item, or an item is selected and the user presses one of the keys Space, Shift+Space, Return or Enter. the activated #GAppInfo Emitted when an application item is selected from the widget's list. the selected #GAppInfo Emitted when a context menu is about to popup over an application item. Clients can insert menu items into the provided #GtkMenu object in the callback of this signal; the context menu will be shown over the item if at least one item has been added to the menu. the #GtkMenu to populate the current #GAppInfo The parent class. Signal emitted when an application item is selected from the widget’s list. Signal emitted when an application item is activated from the widget’s list. Signal emitted when a context menu is about to popup over an application item. #GtkApplication is a class that handles many important aspects of a GTK+ application in a convenient fashion, without enforcing a one-size-fits-all application model. Currently, GtkApplication handles GTK+ initialization, application uniqueness, session management, provides some basic scriptability and desktop shell integration by exporting actions and menus and manages a list of toplevel windows whose life-cycle is automatically tied to the life-cycle of your application. While GtkApplication works fine with plain #GtkWindows, it is recommended to use it together with #GtkApplicationWindow. When GDK threads are enabled, GtkApplication will acquire the GDK lock when invoking actions that arrive from other processes. The GDK lock is not touched for local action invocations. In order to have actions invoked in a predictable context it is therefore recommended that the GDK lock be held while invoking actions locally with g_action_group_activate_action(). The same applies to actions associated with #GtkApplicationWindow and to the “activate” and “open” #GApplication methods. ## Automatic resources ## {#automatic-resources} #GtkApplication will automatically load menus from the #GtkBuilder resource located at "gtk/menus.ui", relative to the application's resource base path (see g_application_set_resource_base_path()). The menu with the ID "app-menu" is taken as the application's app menu and the menu with the ID "menubar" is taken as the application's menubar. Additional menus (most interesting submenus) can be named and accessed via gtk_application_get_menu_by_id() which allows for dynamic population of a part of the menu structure. If the resources "gtk/menus-appmenu.ui" or "gtk/menus-traditional.ui" are present then these files will be used in preference, depending on the value of gtk_application_prefers_app_menu(). If the resource "gtk/menus-common.ui" is present it will be loaded as well. This is useful for storing items that are referenced from both "gtk/menus-appmenu.ui" and "gtk/menus-traditional.ui". It is also possible to provide the menus manually using gtk_application_set_app_menu() and gtk_application_set_menubar(). #GtkApplication will also automatically setup an icon search path for the default icon theme by appending "icons" to the resource base path. This allows your application to easily store its icons as resources. See gtk_icon_theme_add_resource_path() for more information. If there is a resource located at "gtk/help-overlay.ui" which defines a #GtkShortcutsWindow with ID "help_overlay" then GtkApplication associates an instance of this shortcuts window with each #GtkApplicationWindow and sets up keyboard accelerators (Control-F1 and Control-?) to open it. To create a menu item that displays the shortcuts window, associate the item with the action win.show-help-overlay. ## A simple application ## {#gtkapplication} [A simple example](https://gitlab.gnome.org/GNOME/gtk/-/blob/gtk-3-24/examples/bp/bloatpad.c) GtkApplication optionally registers with a session manager of the users session (if you set the #GtkApplication:register-session property) and offers various functionality related to the session life-cycle. An application can block various ways to end the session with the gtk_application_inhibit() function. Typical use cases for this kind of inhibiting are long-running, uninterruptible operations, such as burning a CD or performing a disk backup. The session manager may not honor the inhibitor, but it can be expected to inform the user about the negative consequences of ending the session while inhibitors are present. ## See Also ## {#seealso} [HowDoI: Using GtkApplication](https://wiki.gnome.org/HowDoI/GtkApplication), [Getting Started with GTK+: Basics](https://developer.gnome.org/gtk3/stable/gtk-getting-started.html#id-1.2.3.3) Creates a new #GtkApplication instance. When using #GtkApplication, it is not necessary to call gtk_init() manually. It is called as soon as the application gets registered as the primary instance. Concretely, gtk_init() is called in the default handler for the #GApplication::startup signal. Therefore, #GtkApplication subclasses should chain up in their #GApplication::startup handler before using any GTK+ API. Note that commandline arguments are not passed to gtk_init(). All GTK+ functionality that is available via commandline arguments can also be achieved by setting suitable environment variables such as `G_DEBUG`, so this should not be a big problem. If you absolutely must support GTK+ commandline arguments, you can explicitly call gtk_init() before creating the application instance. If non-%NULL, the application ID must be valid. See g_application_id_is_valid(). If no application ID is given then some features (most notably application uniqueness) will be disabled. A null application ID is only allowed with GTK+ 3.6 or later. a new #GtkApplication instance The application ID. the application flags Signal emitted when a #GtkWindow is added to application through gtk_application_add_window(). Signal emitted when a #GtkWindow is removed from application, either as a side-effect of being destroyed or explicitly through gtk_application_remove_window(). Installs an accelerator that will cause the named action to be activated when the key combination specificed by @accelerator is pressed. @accelerator must be a string that can be parsed by gtk_accelerator_parse(), e.g. "<Primary>q" or “<Control><Alt>p”. @action_name must be the name of an action as it would be used in the app menu, i.e. actions that have been added to the application are referred to with an “app.” prefix, and window-specific actions with a “win.” prefix. GtkApplication also extracts accelerators out of “accel” attributes in the #GMenuModels passed to gtk_application_set_app_menu() and gtk_application_set_menubar(), which is usually more convenient than calling this function for each accelerator. Use gtk_application_set_accels_for_action() instead a #GtkApplication accelerator string the name of the action to activate parameter to pass when activating the action, or %NULL if the action does not accept an activation parameter Adds a window to @application. This call can only happen after the @application has started; typically, you should add new application windows in response to the emission of the #GApplication::activate signal. This call is equivalent to setting the #GtkWindow:application property of @window to @application. Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it with gtk_application_remove_window(). GTK+ will keep the @application running as long as it has any windows. a #GtkApplication a #GtkWindow Gets the accelerators that are currently associated with the given action. accelerators for @detailed_action_name, as a %NULL-terminated array. Free with g_strfreev() when no longer needed a #GtkApplication a detailed action name, specifying an action and target to obtain accelerators for Returns the list of actions (possibly empty) that @accel maps to. Each item in the list is a detailed action name in the usual form. This might be useful to discover if an accel already exists in order to prevent installation of a conflicting accelerator (from an accelerator editor or a plugin system, for example). Note that having more than one action per accelerator may not be a bad thing and might make sense in cases where the actions never appear in the same context. In case there are no actions for a given accelerator, an empty array is returned. %NULL is never returned. It is a programmer error to pass an invalid accelerator string. If you are unsure, check it with gtk_accelerator_parse() first. a %NULL-terminated array of actions for @accel a #GtkApplication an accelerator that can be parsed by gtk_accelerator_parse() Gets the “active” window for the application. The active window is the one that was most recently focused (within the application). This window may not have the focus at the moment if another application has it — this is just the most recently-focused window within this application. the active window, or %NULL if there isn't one. a #GtkApplication Returns the menu model that has been set with gtk_application_set_app_menu(). the application menu of @application or %NULL if no application menu has been set. a #GtkApplication Gets a menu from automatically loaded resources. See [Automatic resources][automatic-resources] for more information. Gets the menu with the given id from the automatically loaded resources a #GtkApplication the id of the menu to look up Returns the menu model that has been set with gtk_application_set_menubar(). the menubar for windows of @application a #GtkApplication Returns the #GtkApplicationWindow with the given ID. The ID of a #GtkApplicationWindow can be retrieved with gtk_application_window_get_id(). the window with ID @id, or %NULL if there is no window with this ID a #GtkApplication an identifier number Gets a list of the #GtkWindows associated with @application. The list is sorted by most recently focused window, such that the first element is the currently focused window. (Useful for choosing a parent for a transient window.) The list that is returned should not be modified in any way. It will only remain valid until the next focus change or window creation or deletion. a #GList of #GtkWindow a #GtkApplication Inform the session manager that certain types of actions should be inhibited. This is not guaranteed to work on all platforms and for all types of actions. Applications should invoke this method when they begin an operation that should not be interrupted, such as creating a CD or DVD. The types of actions that may be blocked are specified by the @flags parameter. When the application completes the operation it should call gtk_application_uninhibit() to remove the inhibitor. Note that an application can have multiple inhibitors, and all of them must be individually removed. Inhibitors are also cleared when the application exits. Applications should not expect that they will always be able to block the action. In most cases, users will be given the option to force the action to take place. Reasons should be short and to the point. If @window is given, the session manager may point the user to this window to find out more about why the action is inhibited. A non-zero cookie that is used to uniquely identify this request. It should be used as an argument to gtk_application_uninhibit() in order to remove the request. If the platform does not support inhibiting or the request failed for some reason, 0 is returned. the #GtkApplication a #GtkWindow, or %NULL what types of actions should be inhibited a short, human-readable string that explains why these operations are inhibited Determines if any of the actions specified in @flags are currently inhibited (possibly by another application). Note that this information may not be available (for example when the application is running in a sandbox). %TRUE if any of the actions specified in @flags are inhibited the #GtkApplication what types of actions should be queried Lists the detailed action names which have associated accelerators. See gtk_application_set_accels_for_action(). a %NULL-terminated array of strings, free with g_strfreev() when done a #GtkApplication Determines if the desktop environment in which the application is running would prefer an application menu be shown. If this function returns %TRUE then the application should call gtk_application_set_app_menu() with the contents of an application menu, which will be shown by the desktop environment. If it returns %FALSE then you should consider using an alternate approach, such as a menubar. The value returned by this function is purely advisory and you are free to ignore it. If you call gtk_application_set_app_menu() even if the desktop environment doesn't support app menus, then a fallback will be provided. Applications are similarly free not to set an app menu even if the desktop environment wants to show one. In that case, a fallback will also be created by the desktop environment (GNOME, for example, uses a menu with only a "Quit" item in it). The value returned by this function never changes. Once it returns a particular value, it is guaranteed to always return the same value. You may only call this function after the application has been registered and after the base startup handler has run. You're most likely to want to use this from your own startup handler. It may also make sense to consult this function while constructing UI (in activate, open or an action activation handler) in order to determine if you should show a gear menu or not. This function will return %FALSE on Mac OS and a default app menu will be created automatically with the "usual" contents of that menu typical to most Mac OS applications. If you call gtk_application_set_app_menu() anyway, then this menu will be replaced with your own. %TRUE if you should set an app menu a #GtkApplication Removes an accelerator that has been previously added with gtk_application_add_accelerator(). Use gtk_application_set_accels_for_action() instead a #GtkApplication the name of the action to activate parameter to pass when activating the action, or %NULL if the action does not accept an activation parameter Remove a window from @application. If @window belongs to @application then this call is equivalent to setting the #GtkWindow:application property of @window to %NULL. The application may stop running as a result of a call to this function. a #GtkApplication a #GtkWindow Sets zero or more keyboard accelerators that will trigger the given action. The first item in @accels will be the primary accelerator, which may be displayed in the UI. To remove all accelerators for an action, use an empty, zero-terminated array for @accels. For the @detailed_action_name, see g_action_parse_detailed_name() and g_action_print_detailed_name(). a #GtkApplication a detailed action name, specifying an action and target to associate accelerators with a list of accelerators in the format understood by gtk_accelerator_parse() Sets or unsets the application menu for @application. This can only be done in the primary instance of the application, after it has been registered. #GApplication::startup is a good place to call this. The application menu is a single menu containing items that typically impact the application as a whole, rather than acting on a specific window or document. For example, you would expect to see “Preferences” or “Quit” in an application menu, but not “Save” or “Print”. If supported, the application menu will be rendered by the desktop environment. Use the base #GActionMap interface to add actions, to respond to the user selecting these menu items. a #GtkApplication a #GMenuModel, or %NULL Sets or unsets the menubar for windows of @application. This is a menubar in the traditional sense. This can only be done in the primary instance of the application, after it has been registered. #GApplication::startup is a good place to call this. Depending on the desktop environment, this may appear at the top of each window, or at the top of the screen. In some environments, if both the application menu and the menubar are set, the application menu will be presented as if it were the first item of the menubar. Other environments treat the two as completely separate — for example, the application menu may be rendered by the desktop shell while the menubar (if set) remains in each individual window. Use the base #GActionMap interface to add actions, to respond to the user selecting these menu items. a #GtkApplication a #GMenuModel, or %NULL Removes an inhibitor that has been established with gtk_application_inhibit(). Inhibitors are also cleared when the application exits. the #GtkApplication a cookie that was returned by gtk_application_inhibit() Set this property to %TRUE to register with the session manager. This property is %TRUE if GTK+ believes that the screensaver is currently active. GTK+ only tracks session state (including this) when #GtkApplication::register-session is set to %TRUE. Tracking the screensaver state is supported on Linux. Emitted when the session manager is about to end the session, only if #GtkApplication::register-session is %TRUE. Applications can connect to this signal and call gtk_application_inhibit() with %GTK_APPLICATION_INHIBIT_LOGOUT to delay the end of the session until state has been saved. Emitted when a #GtkWindow is added to @application through gtk_application_add_window(). the newly-added #GtkWindow Emitted when a #GtkWindow is removed from @application, either as a side-effect of being destroyed or explicitly through gtk_application_remove_window(). the #GtkWindow that is being removed The parent class. Signal emitted when a #GtkWindow is added to application through gtk_application_add_window(). Signal emitted when a #GtkWindow is removed from application, either as a side-effect of being destroyed or explicitly through gtk_application_remove_window(). Types of user actions that may be blocked by gtk_application_inhibit(). Inhibit ending the user session by logging out or by shutting down the computer Inhibit user switching Inhibit suspending the session or computer Inhibit the session being marked as idle (and possibly locked) #GtkApplicationWindow is a #GtkWindow subclass that offers some extra functionality for better integration with #GtkApplication features. Notably, it can handle both the application menu as well as the menubar. See gtk_application_set_app_menu() and gtk_application_set_menubar(). This class implements the #GActionGroup and #GActionMap interfaces, to let you add window-specific actions that will be exported by the associated #GtkApplication, together with its application-wide actions. Window-specific actions are prefixed with the “win.” prefix and application-wide actions are prefixed with the “app.” prefix. Actions must be addressed with the prefixed name when referring to them from a #GMenuModel. Note that widgets that are placed inside a #GtkApplicationWindow can also activate these actions, if they implement the #GtkActionable interface. As with #GtkApplication, the GDK lock will be acquired when processing actions arriving from other processes and should therefore be held when activating actions locally (if GDK threads are enabled). The settings #GtkSettings:gtk-shell-shows-app-menu and #GtkSettings:gtk-shell-shows-menubar tell GTK+ whether the desktop environment is showing the application menu and menubar models outside the application as part of the desktop shell. For instance, on OS X, both menus will be displayed remotely; on Windows neither will be. gnome-shell (starting with version 3.4) will display the application menu, but not the menubar. If the desktop environment does not display the menubar, then #GtkApplicationWindow will automatically show a #GtkMenuBar for it. This behaviour can be overridden with the #GtkApplicationWindow:show-menubar property. If the desktop environment does not display the application menu, then it will automatically be included in the menubar or in the windows client-side decorations. ## A GtkApplicationWindow with a menubar |[<!-- language="C" --> GtkApplication *app = gtk_application_new ("org.gtk.test", 0); GtkBuilder *builder = gtk_builder_new_from_string ( "<interface>" " <menu id='menubar'>" " <submenu label='_Edit'>" " <item label='_Copy' action='win.copy'/>" " <item label='_Paste' action='win.paste'/>" " </submenu>" " </menu>" "</interface>", -1); GMenuModel *menubar = G_MENU_MODEL (gtk_builder_get_object (builder, "menubar")); gtk_application_set_menubar (GTK_APPLICATION (app), menubar); g_object_unref (builder); // ... GtkWidget *window = gtk_application_window_new (app); ]| ## Handling fallback yourself [A simple example](https://git.gnome.org/browse/gtk+/tree/examples/sunny.c) The XML format understood by #GtkBuilder for #GMenuModel consists of a toplevel `<menu>` element, which contains one or more `<item>` elements. Each `<item>` element contains `<attribute>` and `<link>` elements with a mandatory name attribute. `<link>` elements have the same content model as `<menu>`. Instead of `<link name="submenu>` or `<link name="section">`, you can use `<submenu>` or `<section>` elements. Attribute values can be translated using gettext, like other #GtkBuilder content. `<attribute>` elements can be marked for translation with a `translatable="yes"` attribute. It is also possible to specify message context and translator comments, using the context and comments attributes. To make use of this, the #GtkBuilder must have been given the gettext domain to use. The following attributes are used when constructing menu items: - "label": a user-visible string to display - "action": the prefixed name of the action to trigger - "target": the parameter to use when activating the action - "icon" and "verb-icon": names of icons that may be displayed - "submenu-action": name of an action that may be used to determine if a submenu can be opened - "hidden-when": a string used to determine when the item will be hidden. Possible values include "action-disabled", "action-missing", "macos-menubar". The following attributes are used when constructing sections: - "label": a user-visible string to use as section heading - "display-hint": a string used to determine special formatting for the section. Possible values include "horizontal-buttons". - "text-direction": a string used to determine the #GtkTextDirection to use when "display-hint" is set to "horizontal-buttons". Possible values include "rtl", "ltr", and "none". The following attributes are used when constructing submenus: - "label": a user-visible string to display - "icon": icon name to display Creates a new #GtkApplicationWindow. a newly created #GtkApplicationWindow a #GtkApplication Gets the #GtkShortcutsWindow that has been set up with a prior call to gtk_application_window_set_help_overlay(). the help overlay associated with @window, or %NULL a #GtkApplicationWindow Returns the unique ID of the window. If the window has not yet been added to a #GtkApplication, returns `0`. the unique ID for @window, or `0` if the window has not yet been added to a #GtkApplication a #GtkApplicationWindow Returns whether the window will display a menubar for the app menu and menubar as needed. %TRUE if @window will display a menubar when needed a #GtkApplicationWindow Associates a shortcuts window with the application window, and sets up an action with the name win.show-help-overlay to present it. @window takes resposibility for destroying @help_overlay. a #GtkApplicationWindow a #GtkShortcutsWindow Sets whether the window will display a menubar for the app menu and menubar as needed. a #GtkApplicationWindow whether to show a menubar when needed If this property is %TRUE, the window will display a menubar that includes the app menu and menubar, unless these are shown by the desktop shell. See gtk_application_set_app_menu() and gtk_application_set_menubar(). If %FALSE, the window will not display a menubar, regardless of whether the desktop shell is showing the menus or not. The parent class. GtkArrow should be used to draw simple arrows that need to point in one of the four cardinal directions (up, down, left, or right). The style of the arrow can be one of shadow in, shadow out, etched in, or etched out. Note that these directions and style types may be amended in versions of GTK+ to come. GtkArrow will fill any space alloted to it, but since it is inherited from #GtkMisc, it can be padded and/or aligned, to fill exactly the space the programmer desires. Arrows are created with a call to gtk_arrow_new(). The direction or style of an arrow can be changed after creation by using gtk_arrow_set(). GtkArrow has been deprecated; you can simply use a #GtkImage with a suitable icon name, such as “pan-down-symbolic“. When replacing GtkArrow by an image, pay attention to the fact that GtkArrow is doing automatic flipping between #GTK_ARROW_LEFT and #GTK_ARROW_RIGHT, depending on the text direction. To get the same effect with an image, use the icon names “pan-start-symbolic“ and “pan-end-symbolic“, which react to the text direction. Creates a new #GtkArrow widget. Use a #GtkImage with a suitable icon. the new #GtkArrow widget. a valid #GtkArrowType. a valid #GtkShadowType. Sets the direction and style of the #GtkArrow, @arrow. Use a #GtkImage with a suitable icon. a widget of type #GtkArrow. a valid #GtkArrowType. a valid #GtkShadowType. Used to specify the placement of scroll arrows in scrolling menus. Place one arrow on each end of the menu. Place both arrows at the top of the menu. Place both arrows at the bottom of the menu. Used to indicate the direction in which an arrow should point. Represents an upward pointing arrow. Represents a downward pointing arrow. Represents a left pointing arrow. Represents a right pointing arrow. No arrow. Since 2.10. The #GtkAspectFrame is useful when you want pack a widget so that it can resize but always retains the same aspect ratio. For instance, one might be drawing a small preview of a larger image. #GtkAspectFrame derives from #GtkFrame, so it can draw a label and a frame around the child. The frame will be “shrink-wrapped” to the size of the child. # CSS nodes GtkAspectFrame uses a CSS node with name frame. Create a new #GtkAspectFrame. the new #GtkAspectFrame. Label text. Horizontal alignment of the child within the allocation of the #GtkAspectFrame. This ranges from 0.0 (left aligned) to 1.0 (right aligned) Vertical alignment of the child within the allocation of the #GtkAspectFrame. This ranges from 0.0 (top aligned) to 1.0 (bottom aligned) The desired aspect ratio. If %TRUE, @ratio is ignored, and the aspect ratio is taken from the requistion of the child. Set parameters for an existing #GtkAspectFrame. a #GtkAspectFrame Horizontal alignment of the child within the allocation of the #GtkAspectFrame. This ranges from 0.0 (left aligned) to 1.0 (right aligned) Vertical alignment of the child within the allocation of the #GtkAspectFrame. This ranges from 0.0 (top aligned) to 1.0 (bottom aligned) The desired aspect ratio. If %TRUE, @ratio is ignored, and the aspect ratio is taken from the requistion of the child. The parent class. A #GtkAssistant is a widget used to represent a generally complex operation splitted in several steps, guiding the user through its pages and controlling the page flow to collect the necessary data. The design of GtkAssistant is that it controls what buttons to show and to make sensitive, based on what it knows about the page sequence and the [type][GtkAssistantPageType] of each page, in addition to state information like the page [completion][gtk-assistant-set-page-complete] and [committed][gtk-assistant-commit] status. If you have a case that doesn’t quite fit in #GtkAssistants way of handling buttons, you can use the #GTK_ASSISTANT_PAGE_CUSTOM page type and handle buttons yourself. # GtkAssistant as GtkBuildable The GtkAssistant implementation of the #GtkBuildable interface exposes the @action_area as internal children with the name “action_area”. To add pages to an assistant in #GtkBuilder, simply add it as a child to the GtkAssistant object, and set its child properties as necessary. # CSS nodes GtkAssistant has a single CSS node with the name assistant. Creates a new #GtkAssistant. a newly created #GtkAssistant Signal emitted when the apply button is clicked. Signal emitted when the cancel button is clicked. Signal emitted either when the close button or last page apply button is clicked. Signal emitted when a new page is set as the assistant’s current page, before making the new page visible. Adds a widget to the action area of a #GtkAssistant. a #GtkAssistant a #GtkWidget Appends a page to the @assistant. the index (starting at 0) of the inserted page a #GtkAssistant a #GtkWidget Erases the visited page history so the back button is not shown on the current page, and removes the cancel button from subsequent pages. Use this when the information provided up to the current page is hereafter deemed permanent and cannot be modified or undone. For example, showing a progress page to track a long-running, unreversible operation after the user has clicked apply on a confirmation page. a #GtkAssistant Returns the page number of the current page. The index (starting from 0) of the current page in the @assistant, or -1 if the @assistant has no pages, or no current page. a #GtkAssistant Returns the number of pages in the @assistant the number of pages in the @assistant a #GtkAssistant Returns the child widget contained in page number @page_num. the child widget, or %NULL if @page_num is out of bounds a #GtkAssistant the index of a page in the @assistant, or -1 to get the last page Gets whether @page is complete. %TRUE if @page is complete. a #GtkAssistant a page of @assistant Gets whether page has padding. %TRUE if @page has padding a #GtkAssistant a page of @assistant Gets the header image for @page. Since GTK+ 3.2, a header is no longer shown; add your header decoration to the page content instead. the header image for @page, or %NULL if there’s no header image for the page a #GtkAssistant a page of @assistant Gets the side image for @page. Since GTK+ 3.2, sidebar images are not shown anymore. the side image for @page, or %NULL if there’s no side image for the page a #GtkAssistant a page of @assistant Gets the title for @page. the title for @page a #GtkAssistant a page of @assistant Gets the page type of @page. the page type of @page a #GtkAssistant a page of @assistant Inserts a page in the @assistant at a given position. the index (starting from 0) of the inserted page a #GtkAssistant a #GtkWidget the index (starting at 0) at which to insert the page, or -1 to append the page to the @assistant Navigate to the next page. It is a programming error to call this function when there is no next page. This function is for use when creating pages of the #GTK_ASSISTANT_PAGE_CUSTOM type. a #GtkAssistant Prepends a page to the @assistant. the index (starting at 0) of the inserted page a #GtkAssistant a #GtkWidget Navigate to the previous visited page. It is a programming error to call this function when no previous page is available. This function is for use when creating pages of the #GTK_ASSISTANT_PAGE_CUSTOM type. a #GtkAssistant Removes a widget from the action area of a #GtkAssistant. a #GtkAssistant a #GtkWidget Removes the @page_num’s page from @assistant. a #GtkAssistant the index of a page in the @assistant, or -1 to remove the last page Switches the page to @page_num. Note that this will only be necessary in custom buttons, as the @assistant flow can be set with gtk_assistant_set_forward_page_func(). a #GtkAssistant index of the page to switch to, starting from 0. If negative, the last page will be used. If greater than the number of pages in the @assistant, nothing will be done. Sets the page forwarding function to be @page_func. This function will be used to determine what will be the next page when the user presses the forward button. Setting @page_func to %NULL will make the assistant to use the default forward function, which just goes to the next visible page. a #GtkAssistant the #GtkAssistantPageFunc, or %NULL to use the default one user data for @page_func destroy notifier for @data Sets whether @page contents are complete. This will make @assistant update the buttons state to be able to continue the task. a #GtkAssistant a page of @assistant the completeness status of the page Sets whether the assistant is adding padding around the page. a #GtkAssistant a page of @assistant whether this page has padding Sets a header image for @page. Since GTK+ 3.2, a header is no longer shown; add your header decoration to the page content instead. a #GtkAssistant a page of @assistant the new header image @page Sets a side image for @page. This image used to be displayed in the side area of the assistant when @page is the current page. Since GTK+ 3.2, sidebar images are not shown anymore. a #GtkAssistant a page of @assistant the new side image @page Sets a title for @page. The title is displayed in the header area of the assistant when @page is the current page. a #GtkAssistant a page of @assistant the new title for @page Sets the page type for @page. The page type determines the page behavior in the @assistant. a #GtkAssistant a page of @assistant the new type for @page Forces @assistant to recompute the buttons state. GTK+ automatically takes care of this in most situations, e.g. when the user goes to a different page, or when the visibility or completeness of a page changes. One situation where it can be necessary to call this function is when changing a value on the current page affects the future page flow of the assistant. a #GtkAssistant %TRUE if the assistant uses a #GtkHeaderBar for action buttons instead of the action-area. For technical reasons, this property is declared as an integer property, but you should only set it to %TRUE or %FALSE. The ::apply signal is emitted when the apply button is clicked. The default behavior of the #GtkAssistant is to switch to the page after the current page, unless the current page is the last one. A handler for the ::apply signal should carry out the actions for which the wizard has collected data. If the action takes a long time to complete, you might consider putting a page of type %GTK_ASSISTANT_PAGE_PROGRESS after the confirmation page and handle this operation within the #GtkAssistant::prepare signal of the progress page. The ::cancel signal is emitted when then the cancel button is clicked. The ::close signal is emitted either when the close button of a summary page is clicked, or when the apply button in the last page in the flow (of type %GTK_ASSISTANT_PAGE_CONFIRM) is clicked. The ::prepare signal is emitted when a new page is set as the assistant's current page, before making the new page visible. A handler for this signal can do any preparations which are necessary before showing @page. the current page The parent class. Signal emitted when a new page is set as the assistant’s current page, before making the new page visible. Signal emitted when the apply button is clicked. Signal emitted either when the close button or last page apply button is clicked. Signal emitted when the cancel button is clicked. A function used by gtk_assistant_set_forward_page_func() to know which is the next page given a current one. It’s called both for computing the next page when the user presses the “forward” button and for handling the behavior of the “last” button. The next page number. The page number used to calculate the next page. user data. An enum for determining the page role inside the #GtkAssistant. It's used to handle buttons sensitivity and visibility. Note that an assistant needs to end its page flow with a page of type %GTK_ASSISTANT_PAGE_CONFIRM, %GTK_ASSISTANT_PAGE_SUMMARY or %GTK_ASSISTANT_PAGE_PROGRESS to be correct. The Cancel button will only be shown if the page isn’t “committed”. See gtk_assistant_commit() for details. The page has regular contents. Both the Back and forward buttons will be shown. The page contains an introduction to the assistant task. Only the Forward button will be shown if there is a next page. The page lets the user confirm or deny the changes. The Back and Apply buttons will be shown. The page informs the user of the changes done. Only the Close button will be shown. Used for tasks that take a long time to complete, blocks the assistant until the page is marked as complete. Only the back button will be shown. Used for when other page types are not appropriate. No buttons will be shown, and the application must add its own buttons through gtk_assistant_add_action_widget(). Denotes the expansion properties that a widget will have when it (or its parent) is resized. the widget should expand to take up any extra space in its container that has been allocated. the widget should shrink as and when possible. the widget should fill the space allocated to it. Like gtk_get_binary_age(), but from the headers used at application compile time, rather than from the library linked against at application run time. This macro should be used to emit a warning about and unexpected @type value in a #GtkBuildable add_child implementation. the #GtkBuildable on which the warning ocurred the unexpected type value Whenever a container has some form of natural row it may align children in that row along a common typographical baseline. If the amount of verical space in the row is taller than the total requested height of the baseline-aligned children then it can use a #GtkBaselinePosition to select where to put the baseline inside the extra availible space. Align the baseline at the top Center the baseline Align the baseline at the bottom The #GtkBin widget is a container with just one child. It is not very useful itself, but it is useful for deriving subclasses, since it provides common code needed for handling a single child widget. Many GTK+ widgets are subclasses of #GtkBin, including #GtkWindow, #GtkButton, #GtkFrame, #GtkHandleBox or #GtkScrolledWindow. Gets the child of the #GtkBin, or %NULL if the bin contains no child widget. The returned widget does not have a reference added, so you do not need to unref it. the child of @bin, or %NULL if it does not have a child. a #GtkBin The parent class. A #GtkBindingArg holds the data associated with an argument for a key binding signal emission as stored in #GtkBindingSignal. implementation detail Each key binding element of a binding sets binding list is represented by a GtkBindingEntry. key value to match key modifiers to match binding set this entry belongs to implementation detail implementation detail implementation detail linked list of entries maintained by binding set implementation detail action signals of this entry Override or install a new key binding for @keyval with @modifiers on @binding_set. When the binding is activated, @signal_name will be emitted on the target widget, with @n_args @Varargs used as arguments. Each argument to the signal must be passed as a pair of varargs: the #GType of the argument, followed by the argument value (which must be of the given type). There must be @n_args pairs in total. ## Adding a Key Binding |[<!-- language="C" --> GtkBindingSet *binding_set; GdkModifierType modmask = GDK_CONTROL_MASK; int count = 1; gtk_binding_entry_add_signal (binding_set, GDK_KEY_space, modmask, "move-cursor", 2, GTK_TYPE_MOVEMENT_STEP, GTK_MOVEMENT_PAGES, G_TYPE_INT, count, G_TYPE_BOOLEAN, FALSE); ]| a #GtkBindingSet to install an entry for key value of binding to install key modifier of binding to install signal to execute upon activation number of arguments to @signal_name arguments to @signal_name Parses a signal description from @signal_desc and incorporates it into @binding_set. Signal descriptions may either bind a key combination to one or more signals: |[ bind "key" { "signalname" (param, ...) ... } ]| Or they may also unbind a key combination: |[ unbind "key" ]| Key combinations must be in a format that can be parsed by gtk_accelerator_parse(). %G_TOKEN_NONE if the signal was successfully parsed and added, the expected token otherwise a #GtkBindingSet a signal description Override or install a new key binding for @keyval with @modifiers on @binding_set. a #GtkBindingSet to add a signal to key value key modifier signal name to be bound list of #GtkBindingArg signal arguments Remove a binding previously installed via gtk_binding_entry_add_signal() on @binding_set. a #GtkBindingSet to remove an entry of key value of binding to remove key modifier of binding to remove Install a binding on @binding_set which causes key lookups to be aborted, to prevent bindings from lower priority sets to be activated. a #GtkBindingSet to skip an entry of key value of binding to skip key modifier of binding to skip A binding set maintains a list of activatable key bindings. A single binding set can match multiple types of widgets. Similar to style contexts, can be matched by any information contained in a widgets #GtkWidgetPath. When a binding within a set is matched upon activation, an action signal is emitted on the target widget to carry out the actual activation. unique name of this binding set unused unused unused unused the key binding entries in this binding set implementation detail whether this binding set stems from a CSS file and is reset upon theme changes Find a key binding matching @keyval and @modifiers within @binding_set and activate the binding on @object. %TRUE if a binding was found and activated a #GtkBindingSet set to activate key value of the binding key modifier of the binding object to activate when binding found This function was used internally by the GtkRC parsing mechanism to assign match patterns to #GtkBindingSet structures. In GTK+ 3, these match patterns are unused. a #GtkBindingSet to add a path to path type the pattern applies to the actual match pattern binding priority This function returns the binding set named after the type name of the passed in class structure. New binding sets are created on demand by this function. the binding set corresponding to @object_class a valid #GObject class Find a binding set by its globally unique name. The @set_name can either be a name used for gtk_binding_set_new() or the type name of a class used in gtk_binding_set_by_class(). %NULL or the specified binding set unique binding set name GTK+ maintains a global list of binding sets. Each binding set has a unique name which needs to be specified upon creation. new binding set unique name of this binding set A GtkBindingSignal stores the necessary information to activate a widget in response to a key press via a signal emission. implementation detail the action signal to be emitted number of arguments specified for the signal the arguments specified for the signal A struct that specifies a border around a rectangular area that can be of different width on each side. The width of the left border The width of the right border The width of the top border The width of the bottom border Allocates a new #GtkBorder-struct and initializes its elements to zero. a newly allocated #GtkBorder-struct. Free with gtk_border_free() Copies a #GtkBorder-struct. a copy of @border_. a #GtkBorder-struct Frees a #GtkBorder-struct. a #GtkBorder-struct Describes how the border of a UI element should be rendered. No visible border A single line segment Looks as if the content is sunken into the canvas Looks as if the content is coming out of the canvas Same as @GTK_BORDER_STYLE_NONE A series of round dots A series of square-ended dashes Two parallel lines with some space between them Looks as if it were carved in the canvas Looks as if it were coming out of the canvas The GtkBox widget arranges child widgets into a single row or column, depending upon the value of its #GtkOrientable:orientation property. Within the other dimension, all children are allocated the same size. Of course, the #GtkWidget:halign and #GtkWidget:valign properties can be used on the children to influence their allocation. GtkBox uses a notion of packing. Packing refers to adding widgets with reference to a particular position in a #GtkContainer. For a GtkBox, there are two reference positions: the start and the end of the box. For a vertical #GtkBox, the start is defined as the top of the box and the end is defined as the bottom. For a horizontal #GtkBox the start is defined as the left side and the end is defined as the right side. Use repeated calls to gtk_box_pack_start() to pack widgets into a GtkBox from start to end. Use gtk_box_pack_end() to add widgets from end to start. You may intersperse these calls and add widgets from both ends of the same GtkBox. Because GtkBox is a #GtkContainer, you may also use gtk_container_add() to insert widgets into the box, and they will be packed with the default values for expand and fill child properties. Use gtk_container_remove() to remove widgets from the GtkBox. Use gtk_box_set_homogeneous() to specify whether or not all children of the GtkBox are forced to get the same amount of space. Use gtk_box_set_spacing() to determine how much space will be minimally placed between all children in the GtkBox. Note that spacing is added between the children, while padding added by gtk_box_pack_start() or gtk_box_pack_end() is added on either side of the widget it belongs to. Use gtk_box_reorder_child() to move a GtkBox child to a different place in the box. Use gtk_box_set_child_packing() to reset the expand, fill and padding child properties. Use gtk_box_query_child_packing() to query these fields. # CSS nodes GtkBox uses a single CSS node with name box. In horizontal orientation, the nodes of the children are always arranged from left to right. So :first-child will always select the leftmost child, regardless of text direction. Creates a new #GtkBox. a new #GtkBox. the box’s orientation. the number of pixels to place by default between children. Gets the value set by gtk_box_set_baseline_position(). the baseline position a #GtkBox Retrieves the center widget of the box. the center widget or %NULL in case no center widget is set. a #GtkBox Returns whether the box is homogeneous (all children are the same size). See gtk_box_set_homogeneous(). %TRUE if the box is homogeneous. a #GtkBox Gets the value set by gtk_box_set_spacing(). spacing between children a #GtkBox Adds @child to @box, packed with reference to the end of @box. The @child is packed after (away from end of) any other child packed with reference to the end of @box. a #GtkBox the #GtkWidget to be added to @box %TRUE if the new child is to be given extra space allocated to @box. The extra space will be divided evenly between all children of @box that use this option %TRUE if space given to @child by the @expand option is actually allocated to @child, rather than just padding it. This parameter has no effect if @expand is set to %FALSE. A child is always allocated the full height of a horizontal #GtkBox and the full width of a vertical #GtkBox. This option affects the other dimension extra space in pixels to put between this child and its neighbors, over and above the global amount specified by #GtkBox:spacing property. If @child is a widget at one of the reference ends of @box, then @padding pixels are also put between @child and the reference edge of @box Adds @child to @box, packed with reference to the start of @box. The @child is packed after any other child packed with reference to the start of @box. a #GtkBox the #GtkWidget to be added to @box %TRUE if the new child is to be given extra space allocated to @box. The extra space will be divided evenly between all children that use this option %TRUE if space given to @child by the @expand option is actually allocated to @child, rather than just padding it. This parameter has no effect if @expand is set to %FALSE. A child is always allocated the full height of a horizontal #GtkBox and the full width of a vertical #GtkBox. This option affects the other dimension extra space in pixels to put between this child and its neighbors, over and above the global amount specified by #GtkBox:spacing property. If @child is a widget at one of the reference ends of @box, then @padding pixels are also put between @child and the reference edge of @box Obtains information about how @child is packed into @box. a #GtkBox the #GtkWidget of the child to query pointer to return location for expand child property pointer to return location for fill child property pointer to return location for padding child property pointer to return location for pack-type child property Moves @child to a new @position in the list of @box children. The list contains widgets packed #GTK_PACK_START as well as widgets packed #GTK_PACK_END, in the order that these widgets were added to @box. A widget’s position in the @box children list determines where the widget is packed into @box. A child widget at some position in the list will be packed just after all other widgets of the same packing type that appear earlier in the list. a #GtkBox the #GtkWidget to move the new position for @child in the list of children of @box, starting from 0. If negative, indicates the end of the list Sets the baseline position of a box. This affects only horizontal boxes with at least one baseline aligned child. If there is more vertical space available than requested, and the baseline is not allocated by the parent then @position is used to allocate the baseline wrt the extra space available. a #GtkBox a #GtkBaselinePosition Sets a center widget; that is a child widget that will be centered with respect to the full width of the box, even if the children at either side take up different amounts of space. a #GtkBox the widget to center Sets the way @child is packed into @box. a #GtkBox the #GtkWidget of the child to set the new value of the expand child property the new value of the fill child property the new value of the padding child property the new value of the pack-type child property Sets the #GtkBox:homogeneous property of @box, controlling whether or not all children of @box are given equal space in the box. a #GtkBox a boolean value, %TRUE to create equal allotments, %FALSE for variable allotments Sets the #GtkBox:spacing property of @box, which is the number of pixels to place between children of @box. a #GtkBox the number of pixels to put between children The parent class. GtkBuildable allows objects to extend and customize their deserialization from [GtkBuilder UI descriptions][BUILDER-UI]. The interface includes methods for setting names and properties of objects, parsing custom tags and constructing child objects. The GtkBuildable interface is implemented by all widgets and many of the non-widget objects that are provided by GTK+. The main user of this interface is #GtkBuilder. There should be very little need for applications to call any of these functions directly. An object only needs to implement this interface if it needs to extend the #GtkBuilder format or run any extra routines at deserialization time. Adds a child to @buildable. @type is an optional string describing how the child should be added. a #GtkBuildable a #GtkBuilder child to add kind of child or %NULL Constructs a child of @buildable with the name @name. #GtkBuilder calls this function if a “constructor” has been specified in the UI definition. the constructed child A #GtkBuildable #GtkBuilder used to construct this object name of child to construct This is similar to gtk_buildable_parser_finished() but is called once for each custom tag handled by the @buildable. a #GtkBuildable a #GtkBuilder child object or %NULL for non-child tags the name of the tag user data created in custom_tag_start This is called at the end of each custom element handled by the buildable. A #GtkBuildable #GtkBuilder used to construct this object child object or %NULL for non-child tags name of tag user data that will be passed in to parser functions This is called for each unknown element under `<child>`. %TRUE if a object has a custom implementation, %FALSE if it doesn't. a #GtkBuildable a #GtkBuilder used to construct this object child object or %NULL for non-child tags name of tag a #GMarkupParser to fill in return location for user data that will be passed in to parser functions Get the internal child called @childname of the @buildable object. the internal child of the buildable object a #GtkBuildable a #GtkBuilder name of child Gets the name of the @buildable object. #GtkBuilder sets the name based on the [GtkBuilder UI definition][BUILDER-UI] used to construct the @buildable. the name set with gtk_buildable_set_name() a #GtkBuildable Called when the builder finishes the parsing of a [GtkBuilder UI definition][BUILDER-UI]. Note that this will be called once for each time gtk_builder_add_from_file() or gtk_builder_add_from_string() is called on a builder. a #GtkBuildable a #GtkBuilder Sets the property name @name to @value on the @buildable object. a #GtkBuildable a #GtkBuilder name of property value of property Sets the name of the @buildable object. a #GtkBuildable name to set Adds a child to @buildable. @type is an optional string describing how the child should be added. a #GtkBuildable a #GtkBuilder child to add kind of child or %NULL Constructs a child of @buildable with the name @name. #GtkBuilder calls this function if a “constructor” has been specified in the UI definition. the constructed child A #GtkBuildable #GtkBuilder used to construct this object name of child to construct This is similar to gtk_buildable_parser_finished() but is called once for each custom tag handled by the @buildable. a #GtkBuildable a #GtkBuilder child object or %NULL for non-child tags the name of the tag user data created in custom_tag_start This is called at the end of each custom element handled by the buildable. A #GtkBuildable #GtkBuilder used to construct this object child object or %NULL for non-child tags name of tag user data that will be passed in to parser functions This is called for each unknown element under `<child>`. %TRUE if a object has a custom implementation, %FALSE if it doesn't. a #GtkBuildable a #GtkBuilder used to construct this object child object or %NULL for non-child tags name of tag a #GMarkupParser to fill in return location for user data that will be passed in to parser functions Get the internal child called @childname of the @buildable object. the internal child of the buildable object a #GtkBuildable a #GtkBuilder name of child Gets the name of the @buildable object. #GtkBuilder sets the name based on the [GtkBuilder UI definition][BUILDER-UI] used to construct the @buildable. the name set with gtk_buildable_set_name() a #GtkBuildable Called when the builder finishes the parsing of a [GtkBuilder UI definition][BUILDER-UI]. Note that this will be called once for each time gtk_builder_add_from_file() or gtk_builder_add_from_string() is called on a builder. a #GtkBuildable a #GtkBuilder Sets the property name @name to @value on the @buildable object. a #GtkBuildable a #GtkBuilder name of property value of property Sets the name of the @buildable object. a #GtkBuildable name to set The #GtkBuildableIface interface contains method that are necessary to allow #GtkBuilder to construct an object from a #GtkBuilder UI definition. the parent class Stores the name attribute given in the GtkBuilder UI definition. #GtkWidget stores the name as object data. Implement this method if your object has some notion of “name” and it makes sense to map the XML name attribute to it. a #GtkBuildable name to set The getter corresponding to @set_name. Implement this if you implement @set_name. the name set with gtk_buildable_set_name() a #GtkBuildable Adds a child. The @type parameter can be used to differentiate the kind of child. #GtkContainer implements this to add add a child widget to the container, #GtkNotebook uses the @type to distinguish between page labels (of type "page-label") and normal children. a #GtkBuildable a #GtkBuilder child to add kind of child or %NULL Sets a property of a buildable object. It is normally not necessary to implement this, g_object_set_property() is used by default. #GtkWindow implements this to delay showing itself (i.e. setting the #GtkWidget:visible property) until the whole interface is created. a #GtkBuildable a #GtkBuilder name of property value of property Constructs a child of a buildable that has been specified as “constructor” in the UI definition. #GtkUIManager implements this to reference to a widget created in a `<ui>` tag which is outside of the normal GtkBuilder UI definition hierarchy. A reference to the constructed object is returned and becomes owned by the caller. the constructed child A #GtkBuildable #GtkBuilder used to construct this object name of child to construct Implement this if the buildable needs to parse content below `<child>`. To handle an element, the implementation must fill in the @parser and @user_data and return %TRUE. #GtkWidget implements this to parse keyboard accelerators specified in `<accelerator>` elements. #GtkContainer implements it to map properties defined via `<packing>` elements to child properties. Note that @user_data must be freed in @custom_tag_end or @custom_finished. %TRUE if a object has a custom implementation, %FALSE if it doesn't. a #GtkBuildable a #GtkBuilder used to construct this object child object or %NULL for non-child tags name of tag a #GMarkupParser to fill in return location for user data that will be passed in to parser functions Called for the end tag of each custom element that is handled by the buildable (see @custom_tag_start). A #GtkBuildable #GtkBuilder used to construct this object child object or %NULL for non-child tags name of tag user data that will be passed in to parser functions Called for each custom tag handled by the buildable when the builder finishes parsing (see @custom_tag_start) a #GtkBuildable a #GtkBuilder child object or %NULL for non-child tags the name of the tag user data created in custom_tag_start Called when a builder finishes the parsing of a UI definition. It is normally not necessary to implement this, unless you need to perform special cleanup actions. #GtkWindow sets the #GtkWidget:visible property here. a #GtkBuildable a #GtkBuilder Returns an internal child of a buildable. #GtkDialog implements this to give access to its @vbox, making it possible to add children to the vbox in a UI definition. Implement this if the buildable has internal children that may need to be accessed from a UI definition. the internal child of the buildable object a #GtkBuildable a #GtkBuilder name of child A GtkBuilder is an auxiliary object that reads textual descriptions of a user interface and instantiates the described objects. To create a GtkBuilder from a user interface description, call gtk_builder_new_from_file(), gtk_builder_new_from_resource() or gtk_builder_new_from_string(). In the (unusual) case that you want to add user interface descriptions from multiple sources to the same GtkBuilder you can call gtk_builder_new() to get an empty builder and populate it by (multiple) calls to gtk_builder_add_from_file(), gtk_builder_add_from_resource() or gtk_builder_add_from_string(). A GtkBuilder holds a reference to all objects that it has constructed and drops these references when it is finalized. This finalization can cause the destruction of non-widget objects or widgets which are not contained in a toplevel window. For toplevel windows constructed by a builder, it is the responsibility of the user to call gtk_widget_destroy() to get rid of them and all the widgets they contain. The functions gtk_builder_get_object() and gtk_builder_get_objects() can be used to access the widgets in the interface by the names assigned to them inside the UI description. Toplevel windows returned by these functions will stay around until the user explicitly destroys them with gtk_widget_destroy(). Other widgets will either be part of a larger hierarchy constructed by the builder (in which case you should not have to worry about their lifecycle), or without a parent, in which case they have to be added to some container to make use of them. Non-widget objects need to be reffed with g_object_ref() to keep them beyond the lifespan of the builder. The function gtk_builder_connect_signals() and variants thereof can be used to connect handlers to the named signals in the description. # GtkBuilder UI Definitions # {#BUILDER-UI} GtkBuilder parses textual descriptions of user interfaces which are specified in an XML format which can be roughly described by the RELAX NG schema below. We refer to these descriptions as “GtkBuilder UI definitions” or just “UI definitions” if the context is clear. Do not confuse GtkBuilder UI Definitions with [GtkUIManager UI Definitions][XML-UI], which are more limited in scope. It is common to use `.ui` as the filename extension for files containing GtkBuilder UI definitions. [RELAX NG Compact Syntax](https://gitlab.gnome.org/GNOME/gtk/-/blob/gtk-3-24/gtk/gtkbuilder.rnc) The toplevel element is `<interface>`. It optionally takes a “domain” attribute, which will make the builder look for translated strings using dgettext() in the domain specified. This can also be done by calling gtk_builder_set_translation_domain() on the builder. Objects are described by `<object>` elements, which can contain `<property>` elements to set properties, `<signal>` elements which connect signals to handlers, and `<child>` elements, which describe child objects (most often widgets inside a container, but also e.g. actions in an action group, or columns in a tree model). A `<child>` element contains an `<object>` element which describes the child object. The target toolkit version(s) are described by `<requires>` elements, the “lib” attribute specifies the widget library in question (currently the only supported value is “gtk+”) and the “version” attribute specifies the target version in the form `<major>.<minor>`. The builder will error out if the version requirements are not met. Typically, the specific kind of object represented by an `<object>` element is specified by the “class” attribute. If the type has not been loaded yet, GTK+ tries to find the `get_type()` function from the class name by applying heuristics. This works in most cases, but if necessary, it is possible to specify the name of the get_type() function explictly with the "type-func" attribute. As a special case, GtkBuilder allows to use an object that has been constructed by a #GtkUIManager in another part of the UI definition by specifying the id of the #GtkUIManager in the “constructor” attribute and the name of the object in the “id” attribute. Objects may be given a name with the “id” attribute, which allows the application to retrieve them from the builder with gtk_builder_get_object(). An id is also necessary to use the object as property value in other parts of the UI definition. GTK+ reserves ids starting and ending with `___` (3 underscores) for its own purposes. Setting properties of objects is pretty straightforward with the `<property>` element: the “name” attribute specifies the name of the property, and the content of the element specifies the value. If the “translatable” attribute is set to a true value, GTK+ uses gettext() (or dgettext() if the builder has a translation domain set) to find a translation for the value. This happens before the value is parsed, so it can be used for properties of any type, but it is probably most useful for string properties. It is also possible to specify a context to disambiguate short strings, and comments which may help the translators. GtkBuilder can parse textual representations for the most common property types: characters, strings, integers, floating-point numbers, booleans (strings like “TRUE”, “t”, “yes”, “y”, “1” are interpreted as %TRUE, strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted as %FALSE), enumerations (can be specified by their name, nick or integer value), flags (can be specified by their name, nick, integer value, optionally combined with “|”, e.g. “GTK_VISIBLE|GTK_REALIZED”) and colors (in a format understood by gdk_rgba_parse()). GVariants can be specified in the format understood by g_variant_parse(), and pixbufs can be specified as a filename of an image file to load. Objects can be referred to by their name and by default refer to objects declared in the local xml fragment and objects exposed via gtk_builder_expose_object(). In general, GtkBuilder allows forward references to objects — declared in the local xml; an object doesn’t have to be constructed before it can be referred to. The exception to this rule is that an object has to be constructed before it can be used as the value of a construct-only property. It is also possible to bind a property value to another object's property value using the attributes "bind-source" to specify the source object of the binding, "bind-property" to specify the source property and optionally "bind-flags" to specify the binding flags. Internally builder implements this using GBinding objects. For more information see g_object_bind_property() Signal handlers are set up with the `<signal>` element. The “name” attribute specifies the name of the signal, and the “handler” attribute specifies the function to connect to the signal. By default, GTK+ tries to find the handler using g_module_symbol(), but this can be changed by passing a custom #GtkBuilderConnectFunc to gtk_builder_connect_signals_full(). The remaining attributes, “after”, “swapped” and “object”, have the same meaning as the corresponding parameters of the g_signal_connect_object() or g_signal_connect_data() functions. A “last_modification_time” attribute is also allowed, but it does not have a meaning to the builder. Sometimes it is necessary to refer to widgets which have implicitly been constructed by GTK+ as part of a composite widget, to set properties on them or to add further children (e.g. the @vbox of a #GtkDialog). This can be achieved by setting the “internal-child” property of the `<child>` element to a true value. Note that GtkBuilder still requires an `<object>` element for the internal child, even if it has already been constructed. A number of widgets have different places where a child can be added (e.g. tabs vs. page content in notebooks). This can be reflected in a UI definition by specifying the “type” attribute on a `<child>` The possible values for the “type” attribute are described in the sections describing the widget-specific portions of UI definitions. # A GtkBuilder UI Definition |[<!-- language="xml" --> <interface> <object class="GtkDialog" id="dialog1"> <child internal-child="vbox"> <object class="GtkBox" id="vbox1"> <property name="border-width">10</property> <child internal-child="action_area"> <object class="GtkButtonBox" id="hbuttonbox1"> <property name="border-width">20</property> <child> <object class="GtkButton" id="ok_button"> <property name="label">gtk-ok</property> <property name="use-stock">TRUE</property> <signal name="clicked" handler="ok_button_clicked"/> </object> </child> </object> </child> </object> </child> </object> </interface> ]| Beyond this general structure, several object classes define their own XML DTD fragments for filling in the ANY placeholders in the DTD above. Note that a custom element in a `<child>` element gets parsed by the custom tag handler of the parent object, while a custom element in an `<object>` element gets parsed by the custom tag handler of the object. These XML fragments are explained in the documentation of the respective objects. Additionally, since 3.10 a special `<template>` tag has been added to the format allowing one to define a widget class’s components. See the [GtkWidget documentation][composite-templates] for details. Creates a new empty builder object. This function is only useful if you intend to make multiple calls to gtk_builder_add_from_file(), gtk_builder_add_from_resource() or gtk_builder_add_from_string() in order to merge multiple UI descriptions into a single builder. Most users will probably want to use gtk_builder_new_from_file(), gtk_builder_new_from_resource() or gtk_builder_new_from_string(). a new (empty) #GtkBuilder object Builds the [GtkBuilder UI definition][BUILDER-UI] in the file @filename. If there is an error opening the file or parsing the description then the program will be aborted. You should only ever attempt to parse user interface descriptions that are shipped as part of your program. a #GtkBuilder containing the described interface filename of user interface description file Builds the [GtkBuilder UI definition][BUILDER-UI] at @resource_path. If there is an error locating the resource or parsing the description, then the program will be aborted. a #GtkBuilder containing the described interface a #GResource resource path Builds the user interface described by @string (in the [GtkBuilder UI definition][BUILDER-UI] format). If @string is %NULL-terminated, then @length should be -1. If @length is not -1, then it is the length of @string. If there is an error parsing @string then the program will be aborted. You should not attempt to parse user interface description from untrusted sources. a #GtkBuilder containing the interface described by @string a user interface (XML) description the length of @string, or -1 Looks up a type by name, using the virtual function that #GtkBuilder has for that purpose. This is mainly used when implementing the #GtkBuildable interface on a type. the #GType found for @type_name or #G_TYPE_INVALID if no type was found a #GtkBuilder type name to lookup Adds the @callback_symbol to the scope of @builder under the given @callback_name. Using this function overrides the behavior of gtk_builder_connect_signals() for any callback symbols that are added. Using this method allows for better encapsulation as it does not require that callback symbols be declared in the global namespace. a #GtkBuilder The name of the callback, as expected in the XML The callback pointer A convenience function to add many callbacks instead of calling gtk_builder_add_callback_symbol() for each symbol. a #GtkBuilder The name of the callback, as expected in the XML The callback pointer A list of callback name and callback symbol pairs terminated with %NULL Parses a file containing a [GtkBuilder UI definition][BUILDER-UI] and merges it with the current contents of @builder. Most users will probably want to use gtk_builder_new_from_file(). If an error occurs, 0 will be returned and @error will be assigned a #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_FILE_ERROR domain. It’s not really reasonable to attempt to handle failures of this call. You should not use this function with untrusted files (ie: files that are not part of your application). Broken #GtkBuilder files can easily crash your program, and it’s possible that memory was leaked leading up to the reported failure. The only reasonable thing to do when an error is detected is to call g_error(). A positive value on success, 0 if an error occurred a #GtkBuilder the name of the file to parse Parses a resource file containing a [GtkBuilder UI definition][BUILDER-UI] and merges it with the current contents of @builder. Most users will probably want to use gtk_builder_new_from_resource(). If an error occurs, 0 will be returned and @error will be assigned a #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_RESOURCE_ERROR domain. It’s not really reasonable to attempt to handle failures of this call. The only reasonable thing to do when an error is detected is to call g_error(). A positive value on success, 0 if an error occurred a #GtkBuilder the path of the resource file to parse Parses a string containing a [GtkBuilder UI definition][BUILDER-UI] and merges it with the current contents of @builder. Most users will probably want to use gtk_builder_new_from_string(). Upon errors 0 will be returned and @error will be assigned a #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_VARIANT_PARSE_ERROR domain. It’s not really reasonable to attempt to handle failures of this call. The only reasonable thing to do when an error is detected is to call g_error(). A positive value on success, 0 if an error occurred a #GtkBuilder the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) Parses a file containing a [GtkBuilder UI definition][BUILDER-UI] building only the requested objects and merges them with the current contents of @builder. Upon errors 0 will be returned and @error will be assigned a #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_FILE_ERROR domain. If you are adding an object that depends on an object that is not its child (for instance a #GtkTreeView that depends on its #GtkTreeModel), you have to explicitly list all of them in @object_ids. A positive value on success, 0 if an error occurred a #GtkBuilder the name of the file to parse nul-terminated array of objects to build Parses a resource file containing a [GtkBuilder UI definition][BUILDER-UI] building only the requested objects and merges them with the current contents of @builder. Upon errors 0 will be returned and @error will be assigned a #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_RESOURCE_ERROR domain. If you are adding an object that depends on an object that is not its child (for instance a #GtkTreeView that depends on its #GtkTreeModel), you have to explicitly list all of them in @object_ids. A positive value on success, 0 if an error occurred a #GtkBuilder the path of the resource file to parse nul-terminated array of objects to build Parses a string containing a [GtkBuilder UI definition][BUILDER-UI] building only the requested objects and merges them with the current contents of @builder. Upon errors 0 will be returned and @error will be assigned a #GError from the #GTK_BUILDER_ERROR or #G_MARKUP_ERROR domain. If you are adding an object that depends on an object that is not its child (for instance a #GtkTreeView that depends on its #GtkTreeModel), you have to explicitly list all of them in @object_ids. A positive value on success, 0 if an error occurred a #GtkBuilder the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) nul-terminated array of objects to build This method is a simpler variation of gtk_builder_connect_signals_full(). It uses symbols explicitly added to @builder with prior calls to gtk_builder_add_callback_symbol(). In the case that symbols are not explicitly added; it uses #GModule’s introspective features (by opening the module %NULL) to look at the application’s symbol table. From here it tries to match the signal handler names given in the interface description with symbols in the application and connects the signals. Note that this function can only be called once, subsequent calls will do nothing. Note that unless gtk_builder_add_callback_symbol() is called for all signal callbacks which are referenced by the loaded XML, this function will require that #GModule be supported on the platform. If you rely on #GModule support to lookup callbacks in the symbol table, the following details should be noted: When compiling applications for Windows, you must declare signal callbacks with #G_MODULE_EXPORT, or they will not be put in the symbol table. On Linux and Unices, this is not necessary; applications should instead be compiled with the -Wl,--export-dynamic CFLAGS, and linked against gmodule-export-2.0. a #GtkBuilder user data to pass back with all signals This function can be thought of the interpreted language binding version of gtk_builder_connect_signals(), except that it does not require GModule to function correctly. a #GtkBuilder the function used to connect the signals arbitrary data that will be passed to the connection function Add @object to the @builder object pool so it can be referenced just like any other object built by builder. a #GtkBuilder the name of the object exposed to the builder the object to expose Main private entry point for building composite container components from template XML. This is exported purely to let gtk-builder-tool validate templates, applications have no need to call this function. A positive value on success, 0 if an error occurred a #GtkBuilder the widget that is being extended the type that the template is for the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) Gets the #GtkApplication associated with the builder. The #GtkApplication is used for creating action proxies as requested from XML that the builder is loading. By default, the builder uses the default application: the one from g_application_get_default(). If you want to use another application for constructing proxies, use gtk_builder_set_application(). the application being used by the builder, or %NULL a #GtkBuilder Gets the object named @name. Note that this function does not increment the reference count of the returned object. the object named @name or %NULL if it could not be found in the object tree. a #GtkBuilder name of object to get Gets all objects that have been constructed by @builder. Note that this function does not increment the reference counts of the returned objects. a newly-allocated #GSList containing all the objects constructed by the #GtkBuilder instance. It should be freed by g_slist_free() a #GtkBuilder Gets the translation domain of @builder. the translation domain. This string is owned by the builder object and must not be modified or freed. a #GtkBuilder Looks up a type by name, using the virtual function that #GtkBuilder has for that purpose. This is mainly used when implementing the #GtkBuildable interface on a type. the #GType found for @type_name or #G_TYPE_INVALID if no type was found a #GtkBuilder type name to lookup Fetches a symbol previously added to @builder with gtk_builder_add_callback_symbols() This function is intended for possible use in language bindings or for any case that one might be cusomizing signal connections using gtk_builder_connect_signals_full() The callback symbol in @builder for @callback_name, or %NULL a #GtkBuilder The name of the callback Sets the application associated with @builder. You only need this function if there is more than one #GApplication in your process. @application cannot be %NULL. a #GtkBuilder a #GtkApplication Sets the translation domain of @builder. See #GtkBuilder:translation-domain. a #GtkBuilder the translation domain or %NULL This function demarshals a value from a string. This function calls g_value_init() on the @value argument, so it need not be initialised beforehand. This function can handle char, uchar, boolean, int, uint, long, ulong, enum, flags, float, double, string, #GdkColor, #GdkRGBA and #GtkAdjustment type values. Support for #GtkWidget type values is still to come. Upon errors %FALSE will be returned and @error will be assigned a #GError from the #GTK_BUILDER_ERROR domain. %TRUE on success a #GtkBuilder the #GParamSpec for the property the string representation of the value the #GValue to store the result in Like gtk_builder_value_from_string(), this function demarshals a value from a string, but takes a #GType instead of #GParamSpec. This function calls g_value_init() on the @value argument, so it need not be initialised beforehand. Upon errors %FALSE will be returned and @error will be assigned a #GError from the #GTK_BUILDER_ERROR domain. %TRUE on success a #GtkBuilder the #GType of the value the string representation of the value the #GValue to store the result in The translation domain used when translating property values that have been marked as translatable in interface descriptions. If the translation domain is %NULL, #GtkBuilder uses gettext(), otherwise g_dgettext(). the #GType found for @type_name or #G_TYPE_INVALID if no type was found a #GtkBuilder type name to lookup This is the signature of a function used to connect signals. It is used by the gtk_builder_connect_signals() and gtk_builder_connect_signals_full() methods. It is mainly intended for interpreted language bindings, but could be useful where the programmer wants more control over the signal connection process. Note that this function can only be called once, subsequent calls will do nothing. a #GtkBuilder object to connect a signal to name of the signal name of the handler a #GObject, if non-%NULL, use g_signal_connect_object() #GConnectFlags to use user data Error codes that identify various errors that can occur while using #GtkBuilder. A type-func attribute didn’t name a function that returns a #GType. The input contained a tag that #GtkBuilder can’t handle. An attribute that is required by #GtkBuilder was missing. #GtkBuilder found an attribute that it doesn’t understand. #GtkBuilder found a tag that it doesn’t understand. A required property value was missing. #GtkBuilder couldn’t parse some attribute value. The input file requires a newer version of GTK+. An object id occurred twice. A specified object type is of the same type or derived from the type of the composite class being extended with builder XML. The wrong type was specified in a composite class’s template XML The specified property is unknown for the object class. The specified signal is unknown for the object class. An object id is unknown The #GtkButton widget is generally used to trigger a callback function that is called when the button is pressed. The various signals and how to use them are outlined below. The #GtkButton widget can hold any valid child widget. That is, it can hold almost any other standard #GtkWidget. The most commonly used child is the #GtkLabel. # CSS nodes GtkButton has a single CSS node with name button. The node will get the style classes .image-button or .text-button, if the content is just an image or label, respectively. It may also receive the .flat style class. Other style classes that are commonly used with GtkButton include .suggested-action and .destructive-action. In special cases, buttons can be made round by adding the .circular style class. Button-like widgets like #GtkToggleButton, #GtkMenuButton, #GtkVolumeButton, #GtkLockButton, #GtkColorButton, #GtkFontButton or #GtkFileChooserButton use style classes such as .toggle, .popup, .scale, .lock, .color, .font, .file to differentiate themselves from a plain GtkButton. Creates a new #GtkButton widget. To add a child widget to the button, use gtk_container_add(). The newly created #GtkButton widget. Creates a new button containing an icon from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately. This function is a convenience wrapper around gtk_button_new() and gtk_button_set_image(). a new #GtkButton displaying the themed icon an icon name or %NULL an icon size (#GtkIconSize) Creates a new #GtkButton containing the image and text from a [stock item][gtkstock]. Some stock ids have preprocessor macros like #GTK_STOCK_OK and #GTK_STOCK_APPLY. If @stock_id is unknown, then it will be treated as a mnemonic label (as for gtk_button_new_with_mnemonic()). Stock items are deprecated. Use gtk_button_new_with_label() instead. a new #GtkButton the name of the stock item Creates a #GtkButton widget with a #GtkLabel child containing the given text. The newly created #GtkButton widget. The text you want the #GtkLabel to hold. Creates a new #GtkButton containing a label. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button. a new #GtkButton The text of the button, with an underscore in front of the mnemonic character Signal that causes the button to animate press then release. Applications should never connect to this signal, but use the @clicked signal. Emits a #GtkButton::clicked signal to the given #GtkButton. The #GtkButton you want to send the signal to. Emits a #GtkButton::enter signal to the given #GtkButton. Use the #GtkWidget::enter-notify-event signal. The #GtkButton you want to send the signal to. Emits a #GtkButton::leave signal to the given #GtkButton. Use the #GtkWidget::leave-notify-event signal. The #GtkButton you want to send the signal to. Emits a #GtkButton::pressed signal to the given #GtkButton. Use the #GtkWidget::button-press-event signal. The #GtkButton you want to send the signal to. Emits a #GtkButton::released signal to the given #GtkButton. Use the #GtkWidget::button-release-event signal. The #GtkButton you want to send the signal to. Emits a #GtkButton::clicked signal to the given #GtkButton. The #GtkButton you want to send the signal to. Emits a #GtkButton::enter signal to the given #GtkButton. Use the #GtkWidget::enter-notify-event signal. The #GtkButton you want to send the signal to. Gets the alignment of the child in the button. Access the child widget directly if you need to control its alignment. a #GtkButton return location for horizontal alignment return location for vertical alignment Returns whether the button will ignore the #GtkSettings:gtk-button-images setting and always show the image, if available. %TRUE if the button will always show the image a #GtkButton Returns the button’s event window if it is realized, %NULL otherwise. This function should be rarely needed. @button’s event window. a #GtkButton Returns whether the button grabs focus when it is clicked with the mouse. See gtk_button_set_focus_on_click(). Use gtk_widget_get_focus_on_click() instead %TRUE if the button grabs focus when it is clicked with the mouse. a #GtkButton Gets the widget that is currenty set as the image of @button. This may have been explicitly set by gtk_button_set_image() or constructed by gtk_button_new_from_stock(). a #GtkWidget or %NULL in case there is no image a #GtkButton Gets the position of the image relative to the text inside the button. the position a #GtkButton Fetches the text from the label of the button, as set by gtk_button_set_label(). If the label text has not been set the return value will be %NULL. This will be the case if you create an empty button with gtk_button_new() to use as a container. The text of the label widget. This string is owned by the widget and must not be modified or freed. a #GtkButton Returns the current relief style of the given #GtkButton. The current #GtkReliefStyle The #GtkButton you want the #GtkReliefStyle from. Returns whether the button label is a stock item. %TRUE if the button label is used to select a stock item instead of being used directly as the label text. a #GtkButton Returns whether an embedded underline in the button label indicates a mnemonic. See gtk_button_set_use_underline (). %TRUE if an embedded underline in the button label indicates the mnemonic accelerator keys. a #GtkButton Emits a #GtkButton::leave signal to the given #GtkButton. Use the #GtkWidget::leave-notify-event signal. The #GtkButton you want to send the signal to. Emits a #GtkButton::pressed signal to the given #GtkButton. Use the #GtkWidget::button-press-event signal. The #GtkButton you want to send the signal to. Emits a #GtkButton::released signal to the given #GtkButton. Use the #GtkWidget::button-release-event signal. The #GtkButton you want to send the signal to. Sets the alignment of the child. This property has no effect unless the child is a #GtkMisc or a #GtkAlignment. Access the child widget directly if you need to control its alignment. a #GtkButton the horizontal position of the child, 0.0 is left aligned, 1.0 is right aligned the vertical position of the child, 0.0 is top aligned, 1.0 is bottom aligned If %TRUE, the button will ignore the #GtkSettings:gtk-button-images setting and always show the image, if available. Use this property if the button would be useless or hard to use without the image. a #GtkButton %TRUE if the menuitem should always show the image Sets whether the button will grab focus when it is clicked with the mouse. Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard focus removed from the main area of the application. Use gtk_widget_set_focus_on_click() instead a #GtkButton whether the button grabs focus when clicked with the mouse Set the image of @button to the given widget. The image will be displayed if the label text is %NULL or if #GtkButton:always-show-image is %TRUE. You don’t have to call gtk_widget_show() on @image yourself. a #GtkButton a widget to set as the image for the button, or %NULL to unset Sets the position of the image relative to the text inside the button. a #GtkButton the position Sets the text of the label of the button to @str. This text is also used to select the stock item if gtk_button_set_use_stock() is used. This will also clear any previously set labels. a #GtkButton a string Sets the relief style of the edges of the given #GtkButton widget. Two styles exist, %GTK_RELIEF_NORMAL and %GTK_RELIEF_NONE. The default style is, as one can guess, %GTK_RELIEF_NORMAL. The deprecated value %GTK_RELIEF_HALF behaves the same as %GTK_RELIEF_NORMAL. The #GtkButton you want to set relief styles of The GtkReliefStyle as described above If %TRUE, the label set on the button is used as a stock id to select the stock item for the button. a #GtkButton %TRUE if the button should use a stock item If true, an underline in the text of the button label indicates the next character should be used for the mnemonic accelerator key. a #GtkButton %TRUE if underlines in the text indicate mnemonics If %TRUE, the button will ignore the #GtkSettings:gtk-button-images setting and always show the image, if available. Use this property if the button would be useless or hard to use without the image. The child widget to appear next to the button text. The position of the image relative to the text inside the button. If the child of the button is a #GtkMisc or #GtkAlignment, this property can be used to control its horizontal alignment. 0.0 is left aligned, 1.0 is right aligned. Access the child widget directly if you need to control its alignment. If the child of the button is a #GtkMisc or #GtkAlignment, this property can be used to control its vertical alignment. 0.0 is top aligned, 1.0 is bottom aligned. Access the child widget directly if you need to control its alignment. The ::activate signal on GtkButton is an action signal and emitting it causes the button to animate press then release. Applications should never connect to this signal, but use the #GtkButton::clicked signal. Emitted when the button has been activated (pressed and released). Emitted when the pointer enters the button. Use the #GtkWidget::enter-notify-event signal. Emitted when the pointer leaves the button. Use the #GtkWidget::leave-notify-event signal. Emitted when the button is pressed. Use the #GtkWidget::button-press-event signal. Emitted when the button is released. Use the #GtkWidget::button-release-event signal. Creates a new #GtkButtonBox. a new #GtkButtonBox. the box's orientation. Returns whether the child is exempted from homogenous sizing. %TRUE if the child is not subject to homogenous sizing a #GtkButtonBox a child of @widget Returns whether @child should appear in a secondary group of children. whether @child should appear in a secondary group of children. a #GtkButtonBox a child of @widget Retrieves the method being used to arrange the buttons in a button box. the method used to lay out buttons in @widget. a #GtkButtonBox Sets whether the child is exempted from homogeous sizing. a #GtkButtonBox a child of @widget the new value Sets whether @child should appear in a secondary group of children. A typical use of a secondary child is the help button in a dialog. This group appears after the other children if the style is %GTK_BUTTONBOX_START, %GTK_BUTTONBOX_SPREAD or %GTK_BUTTONBOX_EDGE, and before the other children if the style is %GTK_BUTTONBOX_END. For horizontal button boxes, the definition of before/after depends on direction of the widget (see gtk_widget_set_direction()). If the style is %GTK_BUTTONBOX_START or %GTK_BUTTONBOX_END, then the secondary children are aligned at the other end of the button box from the main children. For the other styles, they appear immediately next to the main children. a #GtkButtonBox a child of @widget if %TRUE, the @child appears in a secondary group of the button box. Changes the way buttons are arranged in their container. a #GtkButtonBox the new layout style The parent class. Used to dictate the style that a #GtkButtonBox uses to layout the buttons it contains. Buttons are evenly spread across the box. Buttons are placed at the edges of the box. Buttons are grouped towards the start of the box, (on the left for a HBox, or the top for a VBox). Buttons are grouped towards the end of the box, (on the right for a HBox, or the bottom for a VBox). Buttons are centered in the box. Since 2.12. Buttons expand to fill the box. This entails giving buttons a "linked" appearance, making button sizes homogeneous, and setting spacing to 0 (same as calling gtk_box_set_homogeneous() and gtk_box_set_spacing() manually). Since 3.12. The parent class. Signal emitted when the button is pressed. Deprecated: 2.8. The #GtkButton you want to send the signal to. Signal emitted when the button is released. Deprecated: 2.8. The #GtkButton you want to send the signal to. Signal emitted when the button has been activated (pressed and released). The #GtkButton you want to send the signal to. Signal emitted when the pointer enters the button. Deprecated: 2.8. The #GtkButton you want to send the signal to. Signal emitted when the pointer leaves the button. Deprecated: 2.8. The #GtkButton you want to send the signal to. Signal that causes the button to animate press then release. Applications should never connect to this signal, but use the @clicked signal. The role specifies the desired appearance of a #GtkModelButton. A plain button A check button A radio button Prebuilt sets of buttons for the dialog. If none of these choices are appropriate, simply use %GTK_BUTTONS_NONE then call gtk_dialog_add_buttons(). > Please note that %GTK_BUTTONS_OK, %GTK_BUTTONS_YES_NO > and %GTK_BUTTONS_OK_CANCEL are discouraged by the > [GNOME Human Interface Guidelines](http://library.gnome.org/devel/hig-book/stable/). no buttons at all an OK button a Close button a Cancel button Yes and No buttons OK and Cancel buttons This macro should be used to emit a standard warning about unexpected properties in set_cell_property() and get_cell_property() implementations. the #GObject on which set_cell_property() or get_cell_property() was called the numeric id of the property the #GParamSpec of the property Returns %TRUE if the version of the GTK+ header files is the same as or newer than the passed-in version. major version (e.g. 1 for version 1.2.5) minor version (e.g. 2 for version 1.2.5) micro version (e.g. 5 for version 1.2.5) This macro should be used to emit a standard warning about unexpected properties in set_child_property() and get_child_property() implementations. the #GObject on which set_child_property() or get_child_property() was called the numeric id of the property the #GParamSpec of the property #GtkCalendar is a widget that displays a Gregorian calendar, one month at a time. It can be created with gtk_calendar_new(). The month and year currently displayed can be altered with gtk_calendar_select_month(). The exact day can be selected from the displayed month using gtk_calendar_select_day(). To place a visual marker on a particular day, use gtk_calendar_mark_day() and to remove the marker, gtk_calendar_unmark_day(). Alternative, all marks can be cleared with gtk_calendar_clear_marks(). The way in which the calendar itself is displayed can be altered using gtk_calendar_set_display_options(). The selected date can be retrieved from a #GtkCalendar using gtk_calendar_get_date(). Users should be aware that, although the Gregorian calendar is the legal calendar in most countries, it was adopted progressively between 1582 and 1929. Display before these dates is likely to be historically incorrect. Creates a new calendar, with the current date being selected. a newly #GtkCalendar widget Remove all visual markers. a #GtkCalendar Obtains the selected date from a #GtkCalendar. a #GtkCalendar location to store the year as a decimal number (e.g. 2011), or %NULL location to store the month number (between 0 and 11), or %NULL location to store the day number (between 1 and 31), or %NULL Returns if the @day of the @calendar is already marked. whether the day is marked. a #GtkCalendar the day number between 1 and 31. Queries the height of detail cells, in rows. See #GtkCalendar:detail-width-chars. The height of detail cells, in rows. a #GtkCalendar. Queries the width of detail cells, in characters. See #GtkCalendar:detail-width-chars. The width of detail cells, in characters. a #GtkCalendar. Returns the current display options of @calendar. the display options. a #GtkCalendar Places a visual marker on a particular day. a #GtkCalendar the day number to mark between 1 and 31. Selects a day from the current month. a #GtkCalendar. the day number between 1 and 31, or 0 to unselect the currently selected day. Shifts the calendar to a different month. a #GtkCalendar a month number between 0 and 11. the year the month is in. Installs a function which provides Pango markup with detail information for each day. Examples for such details are holidays or appointments. That information is shown below each day when #GtkCalendar:show-details is set. A tooltip containing with full detail information is provided, if the entire text should not fit into the details area, or if #GtkCalendar:show-details is not set. The size of the details area can be restricted by setting the #GtkCalendar:detail-width-chars and #GtkCalendar:detail-height-rows properties. a #GtkCalendar. a function providing details for each day. data to pass to @func invokations. a function for releasing @data. Updates the height of detail cells. See #GtkCalendar:detail-height-rows. a #GtkCalendar. detail height in rows. Updates the width of detail cells. See #GtkCalendar:detail-width-chars. a #GtkCalendar. detail width in characters. Sets display options (whether to display the heading and the month headings). a #GtkCalendar the display options to set Removes the visual marker from a particular day. a #GtkCalendar. the day number to unmark between 1 and 31. The selected day (as a number between 1 and 31, or 0 to unselect the currently selected day). This property gets initially set to the current day. Height of a detail cell, in rows. A value of 0 allows any width. See gtk_calendar_set_detail_func(). Width of a detail cell, in characters. A value of 0 allows any width. See gtk_calendar_set_detail_func(). The selected month (as a number between 0 and 11). This property gets initially set to the current month. Determines whether the selected month can be changed. Determines whether day names are displayed. Determines whether details are shown directly in the widget, or if they are available only as tooltip. When this property is set days with details are marked. Determines whether a heading is displayed. Determines whether week numbers are displayed. The selected year. This property gets initially set to the current year. Emitted when the user selects a day. Emitted when the user double-clicks a day. Emitted when the user clicks a button to change the selected month on a calendar. Emitted when the user switched to the next month. Emitted when user switched to the next year. Emitted when the user switched to the previous month. Emitted when user switched to the previous year. This kind of functions provide Pango markup with detail information for the specified day. Examples for such details are holidays or appointments. The function returns %NULL when no information is available. Newly allocated string with Pango markup with details for the specified day or %NULL. a #GtkCalendar. the year for which details are needed. the month for which details are needed. the day of @month for which details are needed. the data passed with gtk_calendar_set_detail_func(). These options can be used to influence the display and behaviour of a #GtkCalendar. Specifies that the month and year should be displayed. Specifies that three letter day descriptions should be present. Prevents the user from switching months with the calendar. Displays each week numbers of the current year, down the left side of the calendar. Just show an indicator, not the full details text when details are provided. See gtk_calendar_set_detail_func(). The type of the callback functions used for e.g. iterating over the children of a container, see gtk_container_foreach(). the widget to operate on user-supplied data The type of the callback functions used for iterating over the cell renderers and their allocated areas inside a #GtkCellArea, see gtk_cell_area_foreach_alloc(). %TRUE to stop iterating over cells. the cell renderer to operate on the area allocated to @renderer inside the rectangle provided to gtk_cell_area_foreach_alloc(). the background area for @renderer inside the background area provided to gtk_cell_area_foreach_alloc(). user-supplied data The #GtkCellArea is an abstract class for #GtkCellLayout widgets (also referred to as "layouting widgets") to interface with an arbitrary number of #GtkCellRenderers and interact with the user for a given #GtkTreeModel row. The cell area handles events, focus navigation, drawing and size requests and allocations for a given row of data. Usually users dont have to interact with the #GtkCellArea directly unless they are implementing a cell-layouting widget themselves. # Requesting area sizes As outlined in [GtkWidget’s geometry management section][geometry-management], GTK+ uses a height-for-width geometry management system to compute the sizes of widgets and user interfaces. #GtkCellArea uses the same semantics to calculate the size of an area for an arbitrary number of #GtkTreeModel rows. When requesting the size of a cell area one needs to calculate the size for a handful of rows, and this will be done differently by different layouting widgets. For instance a #GtkTreeViewColumn always lines up the areas from top to bottom while a #GtkIconView on the other hand might enforce that all areas received the same width and wrap the areas around, requesting height for more cell areas when allocated less width. It’s also important for areas to maintain some cell alignments with areas rendered for adjacent rows (cells can appear “columnized” inside an area even when the size of cells are different in each row). For this reason the #GtkCellArea uses a #GtkCellAreaContext object to store the alignments and sizes along the way (as well as the overall largest minimum and natural size for all the rows which have been calculated with the said context). The #GtkCellAreaContext is an opaque object specific to the #GtkCellArea which created it (see gtk_cell_area_create_context()). The owning cell-layouting widget can create as many contexts as it wishes to calculate sizes of rows which should receive the same size in at least one orientation (horizontally or vertically), However, it’s important that the same #GtkCellAreaContext which was used to request the sizes for a given #GtkTreeModel row be used when rendering or processing events for that row. In order to request the width of all the rows at the root level of a #GtkTreeModel one would do the following: |[<!-- language="C" --> GtkTreeIter iter; gint minimum_width; gint natural_width; valid = gtk_tree_model_get_iter_first (model, &iter); while (valid) { gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE); gtk_cell_area_get_preferred_width (area, context, widget, NULL, NULL); valid = gtk_tree_model_iter_next (model, &iter); } gtk_cell_area_context_get_preferred_width (context, &minimum_width, &natural_width); ]| Note that in this example it’s not important to observe the returned minimum and natural width of the area for each row unless the cell-layouting object is actually interested in the widths of individual rows. The overall width is however stored in the accompanying #GtkCellAreaContext object and can be consulted at any time. This can be useful since #GtkCellLayout widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The #GtkCellLayout widget in that case would calculate the required width of the rows in an idle or timeout source (see g_timeout_add()) and when the widget is requested its actual width in #GtkWidgetClass.get_preferred_width() it can simply consult the width accumulated so far in the #GtkCellAreaContext object. A simple example where rows are rendered from top to bottom and take up the full width of the layouting widget would look like: |[<!-- language="C" --> static void foo_get_preferred_width (GtkWidget *widget, gint *minimum_size, gint *natural_size) { Foo *foo = FOO (widget); FooPrivate *priv = foo->priv; foo_ensure_at_least_one_handfull_of_rows_have_been_requested (foo); gtk_cell_area_context_get_preferred_width (priv->context, minimum_size, natural_size); } ]| In the above example the Foo widget has to make sure that some row sizes have been calculated (the amount of rows that Foo judged was appropriate to request space for in a single timeout iteration) before simply returning the amount of space required by the area via the #GtkCellAreaContext. Requesting the height for width (or width for height) of an area is a similar task except in this case the #GtkCellAreaContext does not store the data (actually, it does not know how much space the layouting widget plans to allocate it for every row. It’s up to the layouting widget to render each row of data with the appropriate height and width which was requested by the #GtkCellArea). In order to request the height for width of all the rows at the root level of a #GtkTreeModel one would do the following: |[<!-- language="C" --> GtkTreeIter iter; gint minimum_height; gint natural_height; gint full_minimum_height = 0; gint full_natural_height = 0; valid = gtk_tree_model_get_iter_first (model, &iter); while (valid) { gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE); gtk_cell_area_get_preferred_height_for_width (area, context, widget, width, &minimum_height, &natural_height); if (width_is_for_allocation) cache_row_height (&iter, minimum_height, natural_height); full_minimum_height += minimum_height; full_natural_height += natural_height; valid = gtk_tree_model_iter_next (model, &iter); } ]| Note that in the above example we would need to cache the heights returned for each row so that we would know what sizes to render the areas for each row. However we would only want to really cache the heights if the request is intended for the layouting widgets real allocation. In some cases the layouting widget is requested the height for an arbitrary for_width, this is a special case for layouting widgets who need to request size for tens of thousands of rows. For this case it’s only important that the layouting widget calculate one reasonably sized chunk of rows and return that height synchronously. The reasoning here is that any layouting widget is at least capable of synchronously calculating enough height to fill the screen height (or scrolled window height) in response to a single call to #GtkWidgetClass.get_preferred_height_for_width(). Returning a perfect height for width that is larger than the screen area is inconsequential since after the layouting receives an allocation from a scrolled window it simply continues to drive the scrollbar values while more and more height is required for the row heights that are calculated in the background. # Rendering Areas Once area sizes have been aquired at least for the rows in the visible area of the layouting widget they can be rendered at #GtkWidgetClass.draw() time. A crude example of how to render all the rows at the root level runs as follows: |[<!-- language="C" --> GtkAllocation allocation; GdkRectangle cell_area = { 0, }; GtkTreeIter iter; gint minimum_width; gint natural_width; gtk_widget_get_allocation (widget, &allocation); cell_area.width = allocation.width; valid = gtk_tree_model_get_iter_first (model, &iter); while (valid) { cell_area.height = get_cached_height_for_row (&iter); gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE); gtk_cell_area_render (area, context, widget, cr, &cell_area, &cell_area, state_flags, FALSE); cell_area.y += cell_area.height; valid = gtk_tree_model_iter_next (model, &iter); } ]| Note that the cached height in this example really depends on how the layouting widget works. The layouting widget might decide to give every row its minimum or natural height or, if the model content is expected to fit inside the layouting widget without scrolling, it would make sense to calculate the allocation for each row at #GtkWidget::size-allocate time using gtk_distribute_natural_allocation(). # Handling Events and Driving Keyboard Focus Passing events to the area is as simple as handling events on any normal widget and then passing them to the gtk_cell_area_event() API as they come in. Usually #GtkCellArea is only interested in button events, however some customized derived areas can be implemented who are interested in handling other events. Handling an event can trigger the #GtkCellArea::focus-changed signal to fire; as well as #GtkCellArea::add-editable in the case that an editable cell was clicked and needs to start editing. You can call gtk_cell_area_stop_editing() at any time to cancel any cell editing that is currently in progress. The #GtkCellArea drives keyboard focus from cell to cell in a way similar to #GtkWidget. For layouting widgets that support giving focus to cells it’s important to remember to pass %GTK_CELL_RENDERER_FOCUSED to the area functions for the row that has focus and to tell the area to paint the focus at render time. Layouting widgets that accept focus on cells should implement the #GtkWidgetClass.focus() virtual method. The layouting widget is always responsible for knowing where #GtkTreeModel rows are rendered inside the widget, so at #GtkWidgetClass.focus() time the layouting widget should use the #GtkCellArea methods to navigate focus inside the area and then observe the GtkDirectionType to pass the focus to adjacent rows and areas. A basic example of how the #GtkWidgetClass.focus() virtual method should be implemented: |[<!-- language="C" --> static gboolean foo_focus (GtkWidget *widget, GtkDirectionType direction) { Foo *foo = FOO (widget); FooPrivate *priv = foo->priv; gint focus_row; gboolean have_focus = FALSE; focus_row = priv->focus_row; if (!gtk_widget_has_focus (widget)) gtk_widget_grab_focus (widget); valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, priv->focus_row); while (valid) { gtk_cell_area_apply_attributes (priv->area, priv->model, &iter, FALSE, FALSE); if (gtk_cell_area_focus (priv->area, direction)) { priv->focus_row = focus_row; have_focus = TRUE; break; } else { if (direction == GTK_DIR_RIGHT || direction == GTK_DIR_LEFT) break; else if (direction == GTK_DIR_UP || direction == GTK_DIR_TAB_BACKWARD) { if (focus_row == 0) break; else { focus_row--; valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, focus_row); } } else { if (focus_row == last_row) break; else { focus_row++; valid = gtk_tree_model_iter_next (priv->model, &iter); } } } } return have_focus; } ]| Note that the layouting widget is responsible for matching the GtkDirectionType values to the way it lays out its cells. # Cell Properties The #GtkCellArea introduces cell properties for #GtkCellRenderers in very much the same way that #GtkContainer introduces [child properties][child-properties] for #GtkWidgets. This provides some general interfaces for defining the relationship cell areas have with their cells. For instance in a #GtkCellAreaBox a cell might “expand” and receive extra space when the area is allocated more than its full natural request, or a cell might be configured to “align” with adjacent rows which were requested and rendered with the same #GtkCellAreaContext. Use gtk_cell_area_class_install_cell_property() to install cell properties for a cell area class and gtk_cell_area_class_find_cell_property() or gtk_cell_area_class_list_cell_properties() to get information about existing cell properties. To set the value of a cell property, use gtk_cell_area_cell_set_property(), gtk_cell_area_cell_set() or gtk_cell_area_cell_set_valist(). To obtain the value of a cell property, use gtk_cell_area_cell_get_property(), gtk_cell_area_cell_get() or gtk_cell_area_cell_get_valist(). Activates @area, usually by activating the currently focused cell, however some subclasses which embed widgets in the area can also activate a widget if it currently has the focus. Whether @area was successfully activated. a #GtkCellArea the #GtkCellAreaContext in context with the current row data the #GtkWidget that @area is rendering on the size and location of @area relative to @widget’s allocation the #GtkCellRendererState flags for @area for this row of data. if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated. Adds @renderer to @area with the default child cell properties. a #GtkCellArea the #GtkCellRenderer to add to @area Applies any connected attributes to the renderers in @area by pulling the values from @tree_model. a #GtkCellArea the #GtkTreeModel to pull values from the #GtkTreeIter in @tree_model to apply values for whether @iter has children whether @iter is expanded in the view and children are visible This is sometimes needed for cases where rows need to share alignments in one orientation but may be separately grouped in the opposing orientation. For instance, #GtkIconView creates all icons (rows) to have the same width and the cells theirin to have the same horizontal alignments. However each row of icons may have a separate collective height. #GtkIconView uses this to request the heights of each row based on a context which was already used to request all the row widths that are to be displayed. a newly created #GtkCellAreaContext copy of @context. a #GtkCellArea the #GtkCellAreaContext to copy Creates a #GtkCellAreaContext to be used with @area for all purposes. #GtkCellAreaContext stores geometry information for rows for which it was operated on, it is important to use the same context for the same row of data at all times (i.e. one should render and handle events with the same #GtkCellAreaContext which was used to request the size of those rows of data). a newly created #GtkCellAreaContext which can be used with @area. a #GtkCellArea Delegates event handling to a #GtkCellArea. %TRUE if the event was handled by @area. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the #GdkEvent to handle the @widget relative coordinates for @area the #GtkCellRendererState for @area in this row. This should be called by the @area’s owning layout widget when focus is to be passed to @area, or moved within @area for a given @direction and row data. Implementing #GtkCellArea classes should implement this method to receive and navigate focus in its own way particular to how it lays out cells. %TRUE if focus remains inside @area as a result of this call. a #GtkCellArea the #GtkDirectionType Calls @callback for every #GtkCellRenderer in @area. a #GtkCellArea the #GtkCellCallback to call user provided data pointer Calls @callback for every #GtkCellRenderer in @area with the allocated rectangle inside @cell_area. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the @widget relative coordinates and size for @area the @widget relative coordinates of the background area the #GtkCellAllocCallback to call user provided data pointer This should be implemented to report the values of child cell properties for a given child #GtkCellRenderer. Retrieves a cell area’s initial minimum and natural height. @area will store some geometrical information in @context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the @minimum_height and @natural_height of this call but rather to consult gtk_cell_area_context_get_preferred_height() after a series of requests. a #GtkCellArea the #GtkCellAreaContext to perform this request with the #GtkWidget where @area will be rendering location to store the minimum height, or %NULL location to store the natural height, or %NULL Retrieves a cell area’s minimum and natural height if it would be given the specified @width. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_width(). It’s important to perform a series of gtk_cell_area_get_preferred_width() requests with @context first and then call gtk_cell_area_get_preferred_height_for_width() on each cell area individually to get the height for width of each fully requested row. If at some point, the width of a single row changes, it should be requested with gtk_cell_area_get_preferred_width() again and then the full width of the requested rows checked again with gtk_cell_area_context_get_preferred_width(). a #GtkCellArea the #GtkCellAreaContext which has already been requested for widths. the #GtkWidget where @area will be rendering the width for which to check the height of this area location to store the minimum height, or %NULL location to store the natural height, or %NULL Retrieves a cell area’s initial minimum and natural width. @area will store some geometrical information in @context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the @minimum_width and @natural_width of this call but rather to consult gtk_cell_area_context_get_preferred_width() after a series of requests. a #GtkCellArea the #GtkCellAreaContext to perform this request with the #GtkWidget where @area will be rendering location to store the minimum width, or %NULL location to store the natural width, or %NULL Retrieves a cell area’s minimum and natural width if it would be given the specified @height. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_height(). It’s important to perform a series of gtk_cell_area_get_preferred_height() requests with @context first and then call gtk_cell_area_get_preferred_width_for_height() on each cell area individually to get the height for width of each fully requested row. If at some point, the height of a single row changes, it should be requested with gtk_cell_area_get_preferred_height() again and then the full height of the requested rows checked again with gtk_cell_area_context_get_preferred_height(). a #GtkCellArea the #GtkCellAreaContext which has already been requested for widths. the #GtkWidget where @area will be rendering the height for which to check the width of this area location to store the minimum width, or %NULL location to store the natural width, or %NULL Gets whether the area prefers a height-for-width layout or a width-for-height layout. The #GtkSizeRequestMode preferred by @area. a #GtkCellArea Returns whether the area can do anything when activated, after applying new attributes to @area. whether @area can do anything when activated. a #GtkCellArea Removes @renderer from @area. a #GtkCellArea the #GtkCellRenderer to remove from @area Renders @area’s cells according to @area’s layout onto @widget at the given coordinates. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the #cairo_t to render with the @widget relative coordinates for @area’s background the @widget relative coordinates for @area the #GtkCellRendererState for @area in this row. whether @area should paint focus on focused cells for focused rows or not. This should be implemented to handle changes in child cell properties for a given #GtkCellRenderer that were previously installed on the #GtkCellAreaClass with gtk_cell_area_class_install_cell_property(). Activates @area, usually by activating the currently focused cell, however some subclasses which embed widgets in the area can also activate a widget if it currently has the focus. Whether @area was successfully activated. a #GtkCellArea the #GtkCellAreaContext in context with the current row data the #GtkWidget that @area is rendering on the size and location of @area relative to @widget’s allocation the #GtkCellRendererState flags for @area for this row of data. if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated. This is used by #GtkCellArea subclasses when handling events to activate cells, the base #GtkCellArea class activates cells for keyboard events for free in its own GtkCellArea->activate() implementation. whether cell activation was successful a #GtkCellArea the #GtkWidget that @area is rendering onto the #GtkCellRenderer in @area to activate the #GdkEvent for which cell activation should occur the #GdkRectangle in @widget relative coordinates of @renderer for the current row. the #GtkCellRendererState for @renderer Adds @renderer to @area with the default child cell properties. a #GtkCellArea the #GtkCellRenderer to add to @area Adds @sibling to @renderer’s focusable area, focus will be drawn around @renderer and all of its siblings if @renderer can focus for a given row. Events handled by focus siblings can also activate the given focusable @renderer. a #GtkCellArea the #GtkCellRenderer expected to have focus the #GtkCellRenderer to add to @renderer’s focus area Adds @renderer to @area, setting cell properties at the same time. See gtk_cell_area_add() and gtk_cell_area_cell_set() for more details. a #GtkCellArea a #GtkCellRenderer to be placed inside @area the name of the first cell property to set a %NULL-terminated list of property names and values, starting with @first_prop_name Applies any connected attributes to the renderers in @area by pulling the values from @tree_model. a #GtkCellArea the #GtkTreeModel to pull values from the #GtkTreeIter in @tree_model to apply values for whether @iter has children whether @iter is expanded in the view and children are visible Connects an @attribute to apply values from @column for the #GtkTreeModel in use. a #GtkCellArea the #GtkCellRenderer to connect an attribute for the attribute name the #GtkTreeModel column to fetch attribute values from Disconnects @attribute for the @renderer in @area so that attribute will no longer be updated with values from the model. a #GtkCellArea the #GtkCellRenderer to disconnect an attribute for the attribute name Returns the model column that an attribute has been mapped to, or -1 if the attribute is not mapped. the model column, or -1 a #GtkCellArea a #GtkCellRenderer an attribute on the renderer Gets the values of one or more cell properties for @renderer in @area. a #GtkCellArea a #GtkCellRenderer which is inside @area the name of the first cell property to get return location for the first cell property, followed optionally by more name/return location pairs, followed by %NULL Gets the value of a cell property for @renderer in @area. a #GtkCellArea a #GtkCellRenderer inside @area the name of the property to get a location to return the value Gets the values of one or more cell properties for @renderer in @area. a #GtkCellArea a #GtkCellRenderer inside @area the name of the first property to get return location for the first property, followed optionally by more name/return location pairs, followed by %NULL Sets one or more cell properties for @cell in @area. a #GtkCellArea a #GtkCellRenderer which is a cell inside @area the name of the first cell property to set a %NULL-terminated list of property names and values, starting with @first_prop_name Sets a cell property for @renderer in @area. a #GtkCellArea a #GtkCellRenderer inside @area the name of the cell property to set the value to set the cell property to Sets one or more cell properties for @renderer in @area. a #GtkCellArea a #GtkCellRenderer which inside @area the name of the first cell property to set a %NULL-terminated list of property names and values, starting with @first_prop_name This is sometimes needed for cases where rows need to share alignments in one orientation but may be separately grouped in the opposing orientation. For instance, #GtkIconView creates all icons (rows) to have the same width and the cells theirin to have the same horizontal alignments. However each row of icons may have a separate collective height. #GtkIconView uses this to request the heights of each row based on a context which was already used to request all the row widths that are to be displayed. a newly created #GtkCellAreaContext copy of @context. a #GtkCellArea the #GtkCellAreaContext to copy Creates a #GtkCellAreaContext to be used with @area for all purposes. #GtkCellAreaContext stores geometry information for rows for which it was operated on, it is important to use the same context for the same row of data at all times (i.e. one should render and handle events with the same #GtkCellAreaContext which was used to request the size of those rows of data). a newly created #GtkCellAreaContext which can be used with @area. a #GtkCellArea Delegates event handling to a #GtkCellArea. %TRUE if the event was handled by @area. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the #GdkEvent to handle the @widget relative coordinates for @area the #GtkCellRendererState for @area in this row. This should be called by the @area’s owning layout widget when focus is to be passed to @area, or moved within @area for a given @direction and row data. Implementing #GtkCellArea classes should implement this method to receive and navigate focus in its own way particular to how it lays out cells. %TRUE if focus remains inside @area as a result of this call. a #GtkCellArea the #GtkDirectionType Calls @callback for every #GtkCellRenderer in @area. a #GtkCellArea the #GtkCellCallback to call user provided data pointer Calls @callback for every #GtkCellRenderer in @area with the allocated rectangle inside @cell_area. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the @widget relative coordinates and size for @area the @widget relative coordinates of the background area the #GtkCellAllocCallback to call user provided data pointer Derives the allocation of @renderer inside @area if @area were to be renderered in @cell_area. a #GtkCellArea the #GtkCellAreaContext used to hold sizes for @area. the #GtkWidget that @area is rendering on the #GtkCellRenderer to get the allocation for the whole allocated area for @area in @widget for this row where to store the allocation for @renderer Gets the #GtkCellRenderer at @x and @y coordinates inside @area and optionally returns the full cell allocation for it inside @cell_area. the #GtkCellRenderer at @x and @y. a #GtkCellArea the #GtkCellAreaContext used to hold sizes for @area. the #GtkWidget that @area is rendering on the whole allocated area for @area in @widget for this row the x position the y position where to store the inner allocated area of the returned cell renderer, or %NULL. Gets the current #GtkTreePath string for the currently applied #GtkTreeIter, this is implicitly updated when gtk_cell_area_apply_attributes() is called and can be used to interact with renderers from #GtkCellArea subclasses. The current #GtkTreePath string for the current attributes applied to @area. This string belongs to the area and should not be freed. a #GtkCellArea Gets the #GtkCellEditable widget currently used to edit the currently edited cell. The currently active #GtkCellEditable widget a #GtkCellArea Gets the #GtkCellRenderer in @area that is currently being edited. The currently edited #GtkCellRenderer a #GtkCellArea Retrieves the currently focused cell for @area the currently focused cell in @area. a #GtkCellArea Gets the #GtkCellRenderer which is expected to be focusable for which @renderer is, or may be a sibling. This is handy for #GtkCellArea subclasses when handling events, after determining the renderer at the event location it can then chose to activate the focus cell for which the event cell may have been a sibling. the #GtkCellRenderer for which @renderer is a sibling, or %NULL. a #GtkCellArea the #GtkCellRenderer Gets the focus sibling cell renderers for @renderer. A #GList of #GtkCellRenderers. The returned list is internal and should not be freed. a #GtkCellArea the #GtkCellRenderer expected to have focus Retrieves a cell area’s initial minimum and natural height. @area will store some geometrical information in @context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the @minimum_height and @natural_height of this call but rather to consult gtk_cell_area_context_get_preferred_height() after a series of requests. a #GtkCellArea the #GtkCellAreaContext to perform this request with the #GtkWidget where @area will be rendering location to store the minimum height, or %NULL location to store the natural height, or %NULL Retrieves a cell area’s minimum and natural height if it would be given the specified @width. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_width(). It’s important to perform a series of gtk_cell_area_get_preferred_width() requests with @context first and then call gtk_cell_area_get_preferred_height_for_width() on each cell area individually to get the height for width of each fully requested row. If at some point, the width of a single row changes, it should be requested with gtk_cell_area_get_preferred_width() again and then the full width of the requested rows checked again with gtk_cell_area_context_get_preferred_width(). a #GtkCellArea the #GtkCellAreaContext which has already been requested for widths. the #GtkWidget where @area will be rendering the width for which to check the height of this area location to store the minimum height, or %NULL location to store the natural height, or %NULL Retrieves a cell area’s initial minimum and natural width. @area will store some geometrical information in @context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the @minimum_width and @natural_width of this call but rather to consult gtk_cell_area_context_get_preferred_width() after a series of requests. a #GtkCellArea the #GtkCellAreaContext to perform this request with the #GtkWidget where @area will be rendering location to store the minimum width, or %NULL location to store the natural width, or %NULL Retrieves a cell area’s minimum and natural width if it would be given the specified @height. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_height(). It’s important to perform a series of gtk_cell_area_get_preferred_height() requests with @context first and then call gtk_cell_area_get_preferred_width_for_height() on each cell area individually to get the height for width of each fully requested row. If at some point, the height of a single row changes, it should be requested with gtk_cell_area_get_preferred_height() again and then the full height of the requested rows checked again with gtk_cell_area_context_get_preferred_height(). a #GtkCellArea the #GtkCellAreaContext which has already been requested for widths. the #GtkWidget where @area will be rendering the height for which to check the width of this area location to store the minimum width, or %NULL location to store the natural width, or %NULL Gets whether the area prefers a height-for-width layout or a width-for-height layout. The #GtkSizeRequestMode preferred by @area. a #GtkCellArea Checks if @area contains @renderer. %TRUE if @renderer is in the @area. a #GtkCellArea the #GtkCellRenderer to check This is a convenience function for #GtkCellArea implementations to get the inner area where a given #GtkCellRenderer will be rendered. It removes any padding previously added by gtk_cell_area_request_renderer(). a #GtkCellArea the #GtkWidget that @area is rendering onto the @widget relative coordinates where one of @area’s cells is to be placed the return location for the inner cell area Returns whether the area can do anything when activated, after applying new attributes to @area. whether @area can do anything when activated. a #GtkCellArea Returns whether @sibling is one of @renderer’s focus siblings (see gtk_cell_area_add_focus_sibling()). %TRUE if @sibling is a focus sibling of @renderer a #GtkCellArea the #GtkCellRenderer expected to have focus the #GtkCellRenderer to check against @renderer’s sibling list Removes @renderer from @area. a #GtkCellArea the #GtkCellRenderer to remove from @area Removes @sibling from @renderer’s focus sibling list (see gtk_cell_area_add_focus_sibling()). a #GtkCellArea the #GtkCellRenderer expected to have focus the #GtkCellRenderer to remove from @renderer’s focus area Renders @area’s cells according to @area’s layout onto @widget at the given coordinates. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the #cairo_t to render with the @widget relative coordinates for @area’s background the @widget relative coordinates for @area the #GtkCellRendererState for @area in this row. whether @area should paint focus on focused cells for focused rows or not. This is a convenience function for #GtkCellArea implementations to request size for cell renderers. It’s important to use this function to request size and then use gtk_cell_area_inner_cell_area() at render and event time since this function will add padding around the cell for focus painting. a #GtkCellArea the #GtkCellRenderer to request size for the #GtkOrientation in which to request size the #GtkWidget that @area is rendering onto the allocation contextual size to request for, or -1 if the base request for the orientation is to be returned. location to store the minimum size, or %NULL location to store the natural size, or %NULL Explicitly sets the currently focused cell to @renderer. This is generally called by implementations of #GtkCellAreaClass.focus() or #GtkCellAreaClass.event(), however it can also be used to implement functions such as gtk_tree_view_set_cursor_on_cell(). a #GtkCellArea the #GtkCellRenderer to give focus to Explicitly stops the editing of the currently edited cell. If @canceled is %TRUE, the currently edited cell renderer will emit the ::editing-canceled signal, otherwise the the ::editing-done signal will be emitted on the current edit widget. See gtk_cell_area_get_edited_cell() and gtk_cell_area_get_edit_widget(). a #GtkCellArea whether editing was canceled. The widget currently editing the edited cell This property is read-only and only changes as a result of a call gtk_cell_area_activate_cell(). The cell in the area that is currently edited This property is read-only and only changes as a result of a call gtk_cell_area_activate_cell(). The cell in the area that currently has focus Indicates that editing has started on @renderer and that @editable should be added to the owning cell-layouting widget at @cell_area. the #GtkCellRenderer that started the edited the #GtkCellEditable widget to add the #GtkWidget relative #GdkRectangle coordinates where @editable should be added the #GtkTreePath string this edit was initiated for This signal is emitted whenever applying attributes to @area from @model the #GtkTreeModel to apply the attributes from the #GtkTreeIter indicating which row to apply the attributes of whether the view shows children for this row whether the view is currently showing the children of this row Indicates that focus changed on this @area. This signal is emitted either as a result of focus handling or event handling. It's possible that the signal is emitted even if the currently focused renderer did not change, this is because focus may change to the same renderer in the same cell area for a different row of data. the #GtkCellRenderer that has focus the current #GtkTreePath string set for @area Indicates that editing finished on @renderer and that @editable should be removed from the owning cell-layouting widget. the #GtkCellRenderer that finished editeding the #GtkCellEditable widget to remove The #GtkCellAreaBox renders cell renderers into a row or a column depending on its #GtkOrientation. GtkCellAreaBox uses a notion of packing. Packing refers to adding cell renderers with reference to a particular position in a #GtkCellAreaBox. There are two reference positions: the start and the end of the box. When the #GtkCellAreaBox is oriented in the %GTK_ORIENTATION_VERTICAL orientation, the start is defined as the top of the box and the end is defined as the bottom. In the %GTK_ORIENTATION_HORIZONTAL orientation start is defined as the left side and the end is defined as the right side. Alignments of #GtkCellRenderers rendered in adjacent rows can be configured by configuring the #GtkCellAreaBox align child cell property with gtk_cell_area_cell_set_property() or by specifying the "align" argument to gtk_cell_area_box_pack_start() and gtk_cell_area_box_pack_end(). Creates a new #GtkCellAreaBox. a newly created #GtkCellAreaBox Gets the spacing added between cell renderers. the space added between cell renderers in @box. a #GtkCellAreaBox Adds @renderer to @box, packed with reference to the end of @box. The @renderer is packed after (away from end of) any other #GtkCellRenderer packed with reference to the end of @box. a #GtkCellAreaBox the #GtkCellRenderer to add whether @renderer should receive extra space when the area receives more than its natural size whether @renderer should be aligned in adjacent rows whether @renderer should have the same size in all rows Adds @renderer to @box, packed with reference to the start of @box. The @renderer is packed after any other #GtkCellRenderer packed with reference to the start of @box. a #GtkCellAreaBox the #GtkCellRenderer to add whether @renderer should receive extra space when the area receives more than its natural size whether @renderer should be aligned in adjacent rows whether @renderer should have the same size in all rows Sets the spacing to add between cell renderers in @box. a #GtkCellAreaBox the space to add between #GtkCellRenderers The amount of space to reserve between cells. adds a #GtkCellRenderer to the area. a #GtkCellArea the #GtkCellRenderer to add to @area removes a #GtkCellRenderer from the area. a #GtkCellArea the #GtkCellRenderer to remove from @area calls the #GtkCellCallback function on every #GtkCellRenderer in the area with the provided user data until the callback returns %TRUE. a #GtkCellArea the #GtkCellCallback to call user provided data pointer Calls the #GtkCellAllocCallback function on every #GtkCellRenderer in the area with the allocated area for the cell and the provided user data until the callback returns %TRUE. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the @widget relative coordinates and size for @area the @widget relative coordinates of the background area the #GtkCellAllocCallback to call user provided data pointer Handle an event in the area, this is generally used to activate a cell at the event location for button events but can also be used to generically pass events to #GtkWidgets drawn onto the area. %TRUE if the event was handled by @area. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the #GdkEvent to handle the @widget relative coordinates for @area the #GtkCellRendererState for @area in this row. Actually render the area’s cells to the specified rectangle, @background_area should be correctly distributed to the cells corresponding background areas. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the #cairo_t to render with the @widget relative coordinates for @area’s background the @widget relative coordinates for @area the #GtkCellRendererState for @area in this row. whether @area should paint focus on focused cells for focused rows or not. Apply the cell attributes to the cells. This is implemented as a signal and generally #GtkCellArea subclasses don't need to implement it since it is handled by the base class. a #GtkCellArea the #GtkTreeModel to pull values from the #GtkTreeIter in @tree_model to apply values for whether @iter has children whether @iter is expanded in the view and children are visible Creates and returns a class specific #GtkCellAreaContext to store cell alignment and allocation details for a said #GtkCellArea class. a newly created #GtkCellAreaContext which can be used with @area. a #GtkCellArea Creates a new #GtkCellAreaContext in the same state as the passed @context with any cell alignment data and allocations intact. a newly created #GtkCellAreaContext copy of @context. a #GtkCellArea the #GtkCellAreaContext to copy This allows an area to tell its layouting widget whether it prefers to be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. The #GtkSizeRequestMode preferred by @area. a #GtkCellArea Calculates the minimum and natural width of the areas cells with the current attributes applied while considering the particular layouting details of the said #GtkCellArea. While requests are performed over a series of rows, alignments and overall minimum and natural sizes should be stored in the corresponding #GtkCellAreaContext. a #GtkCellArea the #GtkCellAreaContext to perform this request with the #GtkWidget where @area will be rendering location to store the minimum width, or %NULL location to store the natural width, or %NULL Calculates the minimum and natural height for the area if the passed @context would be allocated the given width. When implementing this virtual method it is safe to assume that @context has already stored the aligned cell widths for every #GtkTreeModel row that @context will be allocated for since this information was stored at #GtkCellAreaClass.get_preferred_width() time. This virtual method should also store any necessary alignments of cell heights for the case that the context is allocated a height. a #GtkCellArea the #GtkCellAreaContext which has already been requested for widths. the #GtkWidget where @area will be rendering the width for which to check the height of this area location to store the minimum height, or %NULL location to store the natural height, or %NULL Calculates the minimum and natural height of the areas cells with the current attributes applied. Essentially this is the same as #GtkCellAreaClass.get_preferred_width() only for areas that are being requested as %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT. a #GtkCellArea the #GtkCellAreaContext to perform this request with the #GtkWidget where @area will be rendering location to store the minimum height, or %NULL location to store the natural height, or %NULL Calculates the minimum and natural width for the area if the passed @context would be allocated the given height. The same as #GtkCellAreaClass.get_preferred_height_for_width() only for handling requests in the %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. a #GtkCellArea the #GtkCellAreaContext which has already been requested for widths. the #GtkWidget where @area will be rendering the height for which to check the width of this area location to store the minimum width, or %NULL location to store the natural width, or %NULL This should be implemented to handle changes in child cell properties for a given #GtkCellRenderer that were previously installed on the #GtkCellAreaClass with gtk_cell_area_class_install_cell_property(). This should be implemented to report the values of child cell properties for a given child #GtkCellRenderer. This virtual method should be implemented to navigate focus from cell to cell inside the #GtkCellArea. The #GtkCellArea should move focus from cell to cell inside the area and return %FALSE if focus logically leaves the area with the following exceptions: When the area contains no activatable cells, the entire area recieves focus. Focus should not be given to cells that are actually “focus siblings” of other sibling cells (see gtk_cell_area_get_focus_from_sibling()). Focus is set by calling gtk_cell_area_set_focus_cell(). %TRUE if focus remains inside @area as a result of this call. a #GtkCellArea the #GtkDirectionType Returns whether the #GtkCellArea can respond to #GtkCellAreaClass.activate(), usually this does not need to be implemented since the base class takes care of this however it can be enhanced if the #GtkCellArea subclass can handle activation in other ways than activating its #GtkCellRenderers. whether @area can do anything when activated. a #GtkCellArea This is called when the layouting widget rendering the #GtkCellArea activates the focus cell (see gtk_cell_area_get_focus_cell()). Whether @area was successfully activated. a #GtkCellArea the #GtkCellAreaContext in context with the current row data the #GtkWidget that @area is rendering on the size and location of @area relative to @widget’s allocation the #GtkCellRendererState flags for @area for this row of data. if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated. Finds a cell property of a cell area class by name. the #GParamSpec of the child property or %NULL if @aclass has no child property with that name. a #GtkCellAreaClass the name of the child property to find Installs a cell property on a cell area class. a #GtkCellAreaClass the id for the property the #GParamSpec for the property Returns all cell properties of a cell area class. a newly allocated %NULL-terminated array of #GParamSpec*. The array must be freed with g_free(). a #GtkCellAreaClass location to return the number of cell properties found The #GtkCellAreaContext object is created by a given #GtkCellArea implementation via its #GtkCellAreaClass.create_context() virtual method and is used to store cell sizes and alignments for a series of #GtkTreeModel rows that are requested and rendered in the same context. #GtkCellLayout widgets can create any number of contexts in which to request and render groups of data rows. However, it’s important that the same context which was used to request sizes for a given #GtkTreeModel row also be used for the same row when calling other #GtkCellArea APIs such as gtk_cell_area_render() and gtk_cell_area_event(). Allocates a width and/or a height for all rows which are to be rendered with @context. Usually allocation is performed only horizontally or sometimes vertically since a group of rows are usually rendered side by side vertically or horizontally and share either the same width or the same height. Sometimes they are allocated in both horizontal and vertical orientations producing a homogeneous effect of the rows. This is generally the case for #GtkTreeView when #GtkTreeView:fixed-height-mode is enabled. Since 3.0 a #GtkCellAreaContext the allocated width for all #GtkTreeModel rows rendered with @context, or -1. the allocated height for all #GtkTreeModel rows rendered with @context, or -1. Gets the accumulative preferred height for @width for all rows which have been requested for the same said @width with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a #GtkCellArea, the returned values are -1. a #GtkCellAreaContext a proposed width for allocation location to store the minimum height, or %NULL location to store the natural height, or %NULL Gets the accumulative preferred width for @height for all rows which have been requested for the same said @height with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a #GtkCellArea, the returned values are -1. a #GtkCellAreaContext a proposed height for allocation location to store the minimum width, or %NULL location to store the natural width, or %NULL Resets any previously cached request and allocation data. When underlying #GtkTreeModel data changes its important to reset the context if the content size is allowed to shrink. If the content size is only allowed to grow (this is usually an option for views rendering large data stores as a measure of optimization), then only the row that changed or was inserted needs to be (re)requested with gtk_cell_area_get_preferred_width(). When the new overall size of the context requires that the allocated size changes (or whenever this allocation changes at all), the variable row sizes need to be re-requested for every row. For instance, if the rows are displayed all with the same width from top to bottom then a change in the allocated width necessitates a recalculation of all the displayed row heights using gtk_cell_area_get_preferred_height_for_width(). Since 3.0 a #GtkCellAreaContext Allocates a width and/or a height for all rows which are to be rendered with @context. Usually allocation is performed only horizontally or sometimes vertically since a group of rows are usually rendered side by side vertically or horizontally and share either the same width or the same height. Sometimes they are allocated in both horizontal and vertical orientations producing a homogeneous effect of the rows. This is generally the case for #GtkTreeView when #GtkTreeView:fixed-height-mode is enabled. Since 3.0 a #GtkCellAreaContext the allocated width for all #GtkTreeModel rows rendered with @context, or -1. the allocated height for all #GtkTreeModel rows rendered with @context, or -1. Fetches the current allocation size for @context. If the context was not allocated in width or height, or if the context was recently reset with gtk_cell_area_context_reset(), the returned value will be -1. a #GtkCellAreaContext location to store the allocated width, or %NULL location to store the allocated height, or %NULL Fetches the #GtkCellArea this @context was created by. This is generally unneeded by layouting widgets; however, it is important for the context implementation itself to fetch information about the area it is being used for. For instance at #GtkCellAreaContextClass.allocate() time it’s important to know details about any cell spacing that the #GtkCellArea is configured with in order to compute a proper allocation. the #GtkCellArea this context was created by. a #GtkCellAreaContext Gets the accumulative preferred height for all rows which have been requested with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a #GtkCellArea, the returned values are 0. a #GtkCellAreaContext location to store the minimum height, or %NULL location to store the natural height, or %NULL Gets the accumulative preferred height for @width for all rows which have been requested for the same said @width with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a #GtkCellArea, the returned values are -1. a #GtkCellAreaContext a proposed width for allocation location to store the minimum height, or %NULL location to store the natural height, or %NULL Gets the accumulative preferred width for all rows which have been requested with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a #GtkCellArea, the returned values are 0. a #GtkCellAreaContext location to store the minimum width, or %NULL location to store the natural width, or %NULL Gets the accumulative preferred width for @height for all rows which have been requested for the same said @height with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a #GtkCellArea, the returned values are -1. a #GtkCellAreaContext a proposed height for allocation location to store the minimum width, or %NULL location to store the natural width, or %NULL Causes the minimum and/or natural height to grow if the new proposed sizes exceed the current minimum and natural height. This is used by #GtkCellAreaContext implementations during the request process over a series of #GtkTreeModel rows to progressively push the requested height over a series of gtk_cell_area_get_preferred_height() requests. a #GtkCellAreaContext the proposed new minimum height for @context the proposed new natural height for @context Causes the minimum and/or natural width to grow if the new proposed sizes exceed the current minimum and natural width. This is used by #GtkCellAreaContext implementations during the request process over a series of #GtkTreeModel rows to progressively push the requested width over a series of gtk_cell_area_get_preferred_width() requests. a #GtkCellAreaContext the proposed new minimum width for @context the proposed new natural width for @context Resets any previously cached request and allocation data. When underlying #GtkTreeModel data changes its important to reset the context if the content size is allowed to shrink. If the content size is only allowed to grow (this is usually an option for views rendering large data stores as a measure of optimization), then only the row that changed or was inserted needs to be (re)requested with gtk_cell_area_get_preferred_width(). When the new overall size of the context requires that the allocated size changes (or whenever this allocation changes at all), the variable row sizes need to be re-requested for every row. For instance, if the rows are displayed all with the same width from top to bottom then a change in the allocated width necessitates a recalculation of all the displayed row heights using gtk_cell_area_get_preferred_height_for_width(). Since 3.0 a #GtkCellAreaContext The #GtkCellArea this context was created by The minimum height for the #GtkCellArea in this context for all #GtkTreeModel rows that this context was requested for using gtk_cell_area_get_preferred_height(). The minimum width for the #GtkCellArea in this context for all #GtkTreeModel rows that this context was requested for using gtk_cell_area_get_preferred_width(). The natural height for the #GtkCellArea in this context for all #GtkTreeModel rows that this context was requested for using gtk_cell_area_get_preferred_height(). The natural width for the #GtkCellArea in this context for all #GtkTreeModel rows that this context was requested for using gtk_cell_area_get_preferred_width(). This tells the context that an allocation width or height (or both) have been decided for a group of rows. The context should store any allocations for internally aligned cells at this point so that they dont need to be recalculated at gtk_cell_area_render() time. a #GtkCellAreaContext the allocated width for all #GtkTreeModel rows rendered with @context, or -1. the allocated height for all #GtkTreeModel rows rendered with @context, or -1. Clear any previously stored information about requested and allocated sizes for the context. a #GtkCellAreaContext Returns the aligned height for the given width that context must store while collecting sizes for it’s rows. a #GtkCellAreaContext a proposed width for allocation location to store the minimum height, or %NULL location to store the natural height, or %NULL Returns the aligned width for the given height that context must store while collecting sizes for it’s rows. a #GtkCellAreaContext a proposed height for allocation location to store the minimum width, or %NULL location to store the natural width, or %NULL The type of the callback functions used for iterating over the cell renderers of a #GtkCellArea, see gtk_cell_area_foreach(). %TRUE to stop iterating over cells. the cell renderer to operate on user-supplied data The #GtkCellEditable interface must be implemented for widgets to be usable to edit the contents of a #GtkTreeView cell. It provides a way to specify how temporary widgets should be configured for editing, get the new value, etc. Emits the #GtkCellEditable::editing-done signal. A #GtkCellEditable Emits the #GtkCellEditable::remove-widget signal. A #GtkCellEditable Begins editing on a @cell_editable. The #GtkCellRenderer for the cell creates and returns a #GtkCellEditable from gtk_cell_renderer_start_editing(), configured for the #GtkCellRenderer type. gtk_cell_editable_start_editing() can then set up @cell_editable suitably for editing a cell, e.g. making the Esc key emit #GtkCellEditable::editing-done. Note that the @cell_editable is created on-demand for the current edit; its lifetime is temporary and does not persist across other edits and/or cells. A #GtkCellEditable The #GdkEvent that began the editing process, or %NULL if editing was initiated programmatically Emits the #GtkCellEditable::editing-done signal. A #GtkCellEditable Emits the #GtkCellEditable::remove-widget signal. A #GtkCellEditable Begins editing on a @cell_editable. The #GtkCellRenderer for the cell creates and returns a #GtkCellEditable from gtk_cell_renderer_start_editing(), configured for the #GtkCellRenderer type. gtk_cell_editable_start_editing() can then set up @cell_editable suitably for editing a cell, e.g. making the Esc key emit #GtkCellEditable::editing-done. Note that the @cell_editable is created on-demand for the current edit; its lifetime is temporary and does not persist across other edits and/or cells. A #GtkCellEditable The #GdkEvent that began the editing process, or %NULL if editing was initiated programmatically Indicates whether editing on the cell has been canceled. This signal is a sign for the cell renderer to update its value from the @cell_editable. Implementations of #GtkCellEditable are responsible for emitting this signal when they are done editing, e.g. #GtkEntry emits this signal when the user presses Enter. Typical things to do in a handler for ::editing-done are to capture the edited value, disconnect the @cell_editable from signals on the #GtkCellRenderer, etc. gtk_cell_editable_editing_done() is a convenience method for emitting #GtkCellEditable::editing-done. This signal is meant to indicate that the cell is finished editing, and the @cell_editable widget is being removed and may subsequently be destroyed. Implementations of #GtkCellEditable are responsible for emitting this signal when they are done editing. It must be emitted after the #GtkCellEditable::editing-done signal, to give the cell renderer a chance to update the cell's value before the widget is removed. gtk_cell_editable_remove_widget() is a convenience method for emitting #GtkCellEditable::remove-widget. Signal is a sign for the cell renderer to update its value from the cell_editable. A #GtkCellEditable Signal is meant to indicate that the cell is finished editing, and the widget may now be destroyed. A #GtkCellEditable Begins editing on a cell_editable. A #GtkCellEditable The #GdkEvent that began the editing process, or %NULL if editing was initiated programmatically #GtkCellLayout is an interface to be implemented by all objects which want to provide a #GtkTreeViewColumn like API for packing cells, setting attributes and data funcs. One of the notable features provided by implementations of GtkCellLayout are attributes. Attributes let you set the properties in flexible ways. They can just be set to constant values like regular properties. But they can also be mapped to a column of the underlying tree model with gtk_cell_layout_set_attributes(), which means that the value of the attribute can change from cell to cell as they are rendered by the cell renderer. Finally, it is possible to specify a function with gtk_cell_layout_set_cell_data_func() that is called to determine the value of the attribute for each cell that is rendered. # GtkCellLayouts as GtkBuildable Implementations of GtkCellLayout which also implement the GtkBuildable interface (#GtkCellView, #GtkIconView, #GtkComboBox, #GtkEntryCompletion, #GtkTreeViewColumn) accept GtkCellRenderer objects as `<child>` elements in UI definitions. They support a custom `<attributes>` element for their children, which can contain multiple `<attribute>` elements. Each `<attribute>` element has a name attribute which specifies a property of the cell renderer; the content of the element is the attribute value. This is an example of a UI definition fragment specifying attributes: |[<!-- language="xml" --> <object class="GtkCellView"> <child> <object class="GtkCellRendererText"/> <attributes> <attribute name="text">0</attribute> </attributes> </child> </object> ]| Furthermore for implementations of GtkCellLayout that use a #GtkCellArea to lay out cells (all GtkCellLayouts in GTK+ use a GtkCellArea) [cell properties][cell-properties] can also be defined in the format by specifying the custom `<cell-packing>` attribute which can contain multiple `<property>` elements defined in the normal way. Here is a UI definition fragment specifying cell properties: |[<!-- language="xml" --> <object class="GtkTreeViewColumn"> <child> <object class="GtkCellRendererText"/> <cell-packing> <property name="align">True</property> <property name="expand">False</property> </cell-packing> </child> </object> ]| # Subclassing GtkCellLayout implementations When subclassing a widget that implements #GtkCellLayout like #GtkIconView or #GtkComboBox, there are some considerations related to the fact that these widgets internally use a #GtkCellArea. The cell area is exposed as a construct-only property by these widgets. This means that it is possible to e.g. do |[<!-- language="C" --> combo = g_object_new (GTK_TYPE_COMBO_BOX, "cell-area", my_cell_area, NULL); ]| to use a custom cell area with a combo box. But construct properties are only initialized after instance init() functions have run, which means that using functions which rely on the existence of the cell area in your subclass’ init() function will cause the default cell area to be instantiated. In this case, a provided construct property value will be ignored (with a warning, to alert you to the problem). |[<!-- language="C" --> static void my_combo_box_init (MyComboBox *b) { GtkCellRenderer *cell; cell = gtk_cell_renderer_pixbuf_new (); // The following call causes the default cell area for combo boxes, // a GtkCellAreaBox, to be instantiated gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (b), cell, FALSE); ... } GtkWidget * my_combo_box_new (GtkCellArea *area) { // This call is going to cause a warning about area being ignored return g_object_new (MY_TYPE_COMBO_BOX, "cell-area", area, NULL); } ]| If supporting alternative cell areas with your derived widget is not important, then this does not have to concern you. If you want to support alternative cell areas, you can do so by moving the problematic calls out of init() and into a constructor() for your class. Adds an attribute mapping to the list in @cell_layout. The @column is the column of the model to get a value from, and the @attribute is the parameter on @cell to be set from the value. So for example if column 2 of the model contains strings, you could have the “text” attribute of a #GtkCellRendererText get its values from column 2. a #GtkCellLayout a #GtkCellRenderer an attribute on the renderer the column position on the model to get the attribute from Unsets all the mappings on all renderers on @cell_layout and removes all renderers from @cell_layout. a #GtkCellLayout Clears all existing attributes previously set with gtk_cell_layout_set_attributes(). a #GtkCellLayout a #GtkCellRenderer to clear the attribute mapping on Returns the underlying #GtkCellArea which might be @cell_layout if called on a #GtkCellArea or might be %NULL if no #GtkCellArea is used by @cell_layout. the cell area used by @cell_layout, or %NULL in case no cell area is used. a #GtkCellLayout Returns the cell renderers which have been added to @cell_layout. a list of cell renderers. The list, but not the renderers has been newly allocated and should be freed with g_list_free() when no longer needed. a #GtkCellLayout Adds the @cell to the end of @cell_layout. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Note that reusing the same cell renderer is not supported. a #GtkCellLayout a #GtkCellRenderer %TRUE if @cell is to be given extra space allocated to @cell_layout Packs the @cell into the beginning of @cell_layout. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Note that reusing the same cell renderer is not supported. a #GtkCellLayout a #GtkCellRenderer %TRUE if @cell is to be given extra space allocated to @cell_layout Re-inserts @cell at @position. Note that @cell has already to be packed into @cell_layout for this to function properly. a #GtkCellLayout a #GtkCellRenderer to reorder new position to insert @cell at Sets the #GtkCellLayoutDataFunc to use for @cell_layout. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of @cell_layout’s cell renderer(s) as appropriate. @func may be %NULL to remove a previously set function. a #GtkCellLayout a #GtkCellRenderer the #GtkCellLayoutDataFunc to use, or %NULL user data for @func destroy notify for @func_data Adds an attribute mapping to the list in @cell_layout. The @column is the column of the model to get a value from, and the @attribute is the parameter on @cell to be set from the value. So for example if column 2 of the model contains strings, you could have the “text” attribute of a #GtkCellRendererText get its values from column 2. a #GtkCellLayout a #GtkCellRenderer an attribute on the renderer the column position on the model to get the attribute from Unsets all the mappings on all renderers on @cell_layout and removes all renderers from @cell_layout. a #GtkCellLayout Clears all existing attributes previously set with gtk_cell_layout_set_attributes(). a #GtkCellLayout a #GtkCellRenderer to clear the attribute mapping on Returns the underlying #GtkCellArea which might be @cell_layout if called on a #GtkCellArea or might be %NULL if no #GtkCellArea is used by @cell_layout. the cell area used by @cell_layout, or %NULL in case no cell area is used. a #GtkCellLayout Returns the cell renderers which have been added to @cell_layout. a list of cell renderers. The list, but not the renderers has been newly allocated and should be freed with g_list_free() when no longer needed. a #GtkCellLayout Adds the @cell to the end of @cell_layout. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Note that reusing the same cell renderer is not supported. a #GtkCellLayout a #GtkCellRenderer %TRUE if @cell is to be given extra space allocated to @cell_layout Packs the @cell into the beginning of @cell_layout. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Note that reusing the same cell renderer is not supported. a #GtkCellLayout a #GtkCellRenderer %TRUE if @cell is to be given extra space allocated to @cell_layout Re-inserts @cell at @position. Note that @cell has already to be packed into @cell_layout for this to function properly. a #GtkCellLayout a #GtkCellRenderer to reorder new position to insert @cell at Sets the attributes in list as the attributes of @cell_layout. The attributes should be in attribute/column order, as in gtk_cell_layout_add_attribute(). All existing attributes are removed, and replaced with the new attributes. a #GtkCellLayout a #GtkCellRenderer a %NULL-terminated list of attributes Sets the #GtkCellLayoutDataFunc to use for @cell_layout. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of @cell_layout’s cell renderer(s) as appropriate. @func may be %NULL to remove a previously set function. a #GtkCellLayout a #GtkCellRenderer the #GtkCellLayoutDataFunc to use, or %NULL user data for @func destroy notify for @func_data A function which should set the value of @cell_layout’s cell renderer(s) as appropriate. a #GtkCellLayout the cell renderer whose value is to be set the model a #GtkTreeIter indicating the row to set the value for user data passed to gtk_cell_layout_set_cell_data_func() Packs the cell into the beginning of cell_layout. a #GtkCellLayout a #GtkCellRenderer %TRUE if @cell is to be given extra space allocated to @cell_layout Adds the cell to the end of cell_layout. a #GtkCellLayout a #GtkCellRenderer %TRUE if @cell is to be given extra space allocated to @cell_layout Unsets all the mappings on all renderers on cell_layout and removes all renderers from cell_layout. a #GtkCellLayout Adds an attribute mapping to the list in cell_layout. a #GtkCellLayout a #GtkCellRenderer an attribute on the renderer the column position on the model to get the attribute from Sets the #GtkCellLayoutDataFunc to use for cell_layout. a #GtkCellLayout a #GtkCellRenderer the #GtkCellLayoutDataFunc to use, or %NULL user data for @func destroy notify for @func_data Clears all existing attributes previously set with gtk_cell_layout_set_attributes(). a #GtkCellLayout a #GtkCellRenderer to clear the attribute mapping on Re-inserts cell at position. a #GtkCellLayout a #GtkCellRenderer to reorder new position to insert @cell at Get the cell renderers which have been added to cell_layout. a list of cell renderers. The list, but not the renderers has been newly allocated and should be freed with g_list_free() when no longer needed. a #GtkCellLayout Get the underlying #GtkCellArea which might be cell_layout if called on a #GtkCellArea or might be NULL if no #GtkCellArea is used by cell_layout. the cell area used by @cell_layout, or %NULL in case no cell area is used. a #GtkCellLayout The #GtkCellRenderer is a base class of a set of objects used for rendering a cell to a #cairo_t. These objects are used primarily by the #GtkTreeView widget, though they aren’t tied to them in any specific way. It is worth noting that #GtkCellRenderer is not a #GtkWidget and cannot be treated as such. The primary use of a #GtkCellRenderer is for drawing a certain graphical elements on a #cairo_t. Typically, one cell renderer is used to draw many cells on the screen. To this extent, it isn’t expected that a CellRenderer keep any permanent state around. Instead, any state is set just prior to use using #GObjects property system. Then, the cell is measured using gtk_cell_renderer_get_size(). Finally, the cell is rendered in the correct location using gtk_cell_renderer_render(). There are a number of rules that must be followed when writing a new #GtkCellRenderer. First and foremost, it’s important that a certain set of properties will always yield a cell renderer of the same size, barring a #GtkStyle change. The #GtkCellRenderer also has a number of generic properties that are expected to be honored by all children. Beyond merely rendering a cell, cell renderers can optionally provide active user interface elements. A cell renderer can be “activatable” like #GtkCellRendererToggle, which toggles when it gets activated by a mouse click, or it can be “editable” like #GtkCellRendererText, which allows the user to edit the text using a widget implementing the #GtkCellEditable interface, e.g. #GtkEntry. To make a cell renderer activatable or editable, you have to implement the #GtkCellRendererClass.activate or #GtkCellRendererClass.start_editing virtual functions, respectively. Many properties of #GtkCellRenderer and its subclasses have a corresponding “set” property, e.g. “cell-background-set” corresponds to “cell-background”. These “set” properties reflect whether a property has been set or not. You should not set them independently. Passes an activate event to the cell renderer for possible processing. Some cell renderers may use events; for example, #GtkCellRendererToggle toggles when it gets a mouse click. %TRUE if the event was consumed/handled a #GtkCellRenderer a #GdkEvent widget that received the event widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Signal gets emitted when the user cancels the process of editing a cell. Signal gets emitted when a cell starts to be edited. Gets the aligned area used by @cell inside @cell_area. Used for finding the appropriate edit and focus rectangle. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to render flags cell area which would be passed to gtk_cell_renderer_render() the return location for the space inside @cell_area that would acually be used to render. Retreives a renderer’s natural size when rendered to @widget. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location to store the minimum size, or %NULL location to store the natural size, or %NULL Retreives a cell renderers’s minimum and natural height if it were rendered to @widget with the specified @width. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to the size which is available for allocation location for storing the minimum size, or %NULL location for storing the preferred size, or %NULL Retreives a renderer’s natural size when rendered to @widget. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location to store the minimum size, or %NULL location to store the natural size, or %NULL Retreives a cell renderers’s minimum and natural width if it were rendered to @widget with the specified @height. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to the size which is available for allocation location for storing the minimum size, or %NULL location for storing the preferred size, or %NULL Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. The #GtkSizeRequestMode preferred by this renderer. a #GtkCellRenderer instance Obtains the width and height needed to render the cell. Used by view widgets to determine the appropriate size for the cell_area passed to gtk_cell_renderer_render(). If @cell_area is not %NULL, fills in the x and y offsets (if set) of the cell relative to this location. Please note that the values set in @width and @height, as well as those in @x_offset and @y_offset are inclusive of the xpad and ypad properties. Use gtk_cell_renderer_get_preferred_size() instead. a #GtkCellRenderer the widget the renderer is rendering to The area a cell will be allocated, or %NULL location to return x offset of cell relative to @cell_area, or %NULL location to return y offset of cell relative to @cell_area, or %NULL location to return width needed to render a cell, or %NULL location to return height needed to render a cell, or %NULL Invokes the virtual render function of the #GtkCellRenderer. The three passed-in rectangles are areas in @cr. Most renderers will draw within @cell_area; the xalign, yalign, xpad, and ypad fields of the #GtkCellRenderer should be honored with respect to @cell_area. @background_area includes the blank space around the cell, and also the area containing the tree expander; so the @background_area rectangles for all cells tile to cover the entire @window. a #GtkCellRenderer a cairo context to draw to the widget owning @window entire cell area (including tree expanders and maybe padding on the sides) area normally rendered by a cell renderer flags that affect rendering Starts editing the contents of this @cell, through a new #GtkCellEditable widget created by the #GtkCellRendererClass.start_editing virtual function. A new #GtkCellEditable for editing this @cell, or %NULL if editing is not possible a #GtkCellRenderer a #GdkEvent widget that received the event widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Passes an activate event to the cell renderer for possible processing. Some cell renderers may use events; for example, #GtkCellRendererToggle toggles when it gets a mouse click. %TRUE if the event was consumed/handled a #GtkCellRenderer a #GdkEvent widget that received the event widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Gets the aligned area used by @cell inside @cell_area. Used for finding the appropriate edit and focus rectangle. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to render flags cell area which would be passed to gtk_cell_renderer_render() the return location for the space inside @cell_area that would acually be used to render. Fills in @xalign and @yalign with the appropriate values of @cell. A #GtkCellRenderer location to fill in with the x alignment of the cell, or %NULL location to fill in with the y alignment of the cell, or %NULL Fills in @width and @height with the appropriate size of @cell. A #GtkCellRenderer location to fill in with the fixed width of the cell, or %NULL location to fill in with the fixed height of the cell, or %NULL Fills in @xpad and @ypad with the appropriate values of @cell. A #GtkCellRenderer location to fill in with the x padding of the cell, or %NULL location to fill in with the y padding of the cell, or %NULL Retreives a renderer’s natural size when rendered to @widget. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location to store the minimum size, or %NULL location to store the natural size, or %NULL Retreives a cell renderers’s minimum and natural height if it were rendered to @widget with the specified @width. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to the size which is available for allocation location for storing the minimum size, or %NULL location for storing the preferred size, or %NULL Retrieves the minimum and natural size of a cell taking into account the widget’s preference for height-for-width management. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location for storing the minimum size, or %NULL location for storing the natural size, or %NULL Retreives a renderer’s natural size when rendered to @widget. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location to store the minimum size, or %NULL location to store the natural size, or %NULL Retreives a cell renderers’s minimum and natural width if it were rendered to @widget with the specified @height. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to the size which is available for allocation location for storing the minimum size, or %NULL location for storing the preferred size, or %NULL Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. The #GtkSizeRequestMode preferred by this renderer. a #GtkCellRenderer instance Returns the cell renderer’s sensitivity. %TRUE if the cell renderer is sensitive A #GtkCellRenderer Obtains the width and height needed to render the cell. Used by view widgets to determine the appropriate size for the cell_area passed to gtk_cell_renderer_render(). If @cell_area is not %NULL, fills in the x and y offsets (if set) of the cell relative to this location. Please note that the values set in @width and @height, as well as those in @x_offset and @y_offset are inclusive of the xpad and ypad properties. Use gtk_cell_renderer_get_preferred_size() instead. a #GtkCellRenderer the widget the renderer is rendering to The area a cell will be allocated, or %NULL location to return x offset of cell relative to @cell_area, or %NULL location to return y offset of cell relative to @cell_area, or %NULL location to return width needed to render a cell, or %NULL location to return height needed to render a cell, or %NULL Translates the cell renderer state to #GtkStateFlags, based on the cell renderer and widget sensitivity, and the given #GtkCellRendererState. the widget state flags applying to @cell a #GtkCellRenderer, or %NULL a #GtkWidget, or %NULL cell renderer state Returns the cell renderer’s visibility. %TRUE if the cell renderer is visible A #GtkCellRenderer Checks whether the cell renderer can do something when activated. %TRUE if the cell renderer can do anything when activated A #GtkCellRenderer Invokes the virtual render function of the #GtkCellRenderer. The three passed-in rectangles are areas in @cr. Most renderers will draw within @cell_area; the xalign, yalign, xpad, and ypad fields of the #GtkCellRenderer should be honored with respect to @cell_area. @background_area includes the blank space around the cell, and also the area containing the tree expander; so the @background_area rectangles for all cells tile to cover the entire @window. a #GtkCellRenderer a cairo context to draw to the widget owning @window entire cell area (including tree expanders and maybe padding on the sides) area normally rendered by a cell renderer flags that affect rendering Sets the renderer’s alignment within its available space. A #GtkCellRenderer the x alignment of the cell renderer the y alignment of the cell renderer Sets the renderer size to be explicit, independent of the properties set. A #GtkCellRenderer the width of the cell renderer, or -1 the height of the cell renderer, or -1 Sets the renderer’s padding. A #GtkCellRenderer the x padding of the cell renderer the y padding of the cell renderer Sets the cell renderer’s sensitivity. A #GtkCellRenderer the sensitivity of the cell Sets the cell renderer’s visibility. A #GtkCellRenderer the visibility of the cell Starts editing the contents of this @cell, through a new #GtkCellEditable widget created by the #GtkCellRendererClass.start_editing virtual function. A new #GtkCellEditable for editing this @cell, or %NULL if editing is not possible a #GtkCellRenderer a #GdkEvent widget that received the event widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Informs the cell renderer that the editing is stopped. If @canceled is %TRUE, the cell renderer will emit the #GtkCellRenderer::editing-canceled signal. This function should be called by cell renderer implementations in response to the #GtkCellEditable::editing-done signal of #GtkCellEditable. A #GtkCellRenderer %TRUE if the editing has been canceled Cell background as a #GdkColor Use #GtkCellRenderer:cell-background-rgba instead. Cell background as a #GdkRGBA This signal gets emitted when the user cancels the process of editing a cell. For example, an editable cell renderer could be written to cancel editing when the user presses Escape. See also: gtk_cell_renderer_stop_editing(). This signal gets emitted when a cell starts to be edited. The intended use of this signal is to do special setup on @editable, e.g. adding a #GtkEntryCompletion or setting up additional columns in a #GtkComboBox. See gtk_cell_editable_start_editing() for information on the lifecycle of the @editable and a way to do setup that doesn’t depend on the @renderer. Note that GTK+ doesn't guarantee that cell renderers will continue to use the same kind of widget for editing in future releases, therefore you should check the type of @editable before doing any specific setup, as in the following example: |[<!-- language="C" --> static void text_editing_started (GtkCellRenderer *cell, GtkCellEditable *editable, const gchar *path, gpointer data) { if (GTK_IS_ENTRY (editable)) { GtkEntry *entry = GTK_ENTRY (editable); // ... create a GtkEntryCompletion gtk_entry_set_completion (entry, completion); } } ]| the #GtkCellEditable the path identifying the edited cell #GtkCellRendererAccel displays a keyboard accelerator (i.e. a key combination like `Control + a`). If the cell renderer is editable, the accelerator can be changed by simply typing the new combination. The #GtkCellRendererAccel cell renderer was added in GTK+ 2.10. Creates a new #GtkCellRendererAccel. the new cell renderer The keyval of the accelerator. Determines if the edited accelerators are GTK+ accelerators. If they are, consumed modifiers are suppressed, only accelerators accepted by GTK+ are allowed, and the accelerators are rendered in the same way as they are in menus. The modifier mask of the accelerator. The hardware keycode of the accelerator. Note that the hardware keycode is only relevant if the key does not have a keyval. Normally, the keyboard configuration should assign keyvals to all keys. Gets emitted when the user has removed the accelerator. the path identifying the row of the edited cell Gets emitted when the user has selected a new accelerator. the path identifying the row of the edited cell the new accelerator keyval the new acclerator modifier mask the keycode of the new accelerator Determines if the edited accelerators are GTK+ accelerators. If they are, consumed modifiers are suppressed, only accelerators accepted by GTK+ are allowed, and the accelerators are rendered in the same way as they are in menus. GTK+ accelerators mode Other accelerator mode Called to gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. The #GtkSizeRequestMode preferred by this renderer. a #GtkCellRenderer instance Called to get a renderer’s natural width. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location to store the minimum size, or %NULL location to store the natural size, or %NULL Called to get a renderer’s natural height for width. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to the size which is available for allocation location for storing the minimum size, or %NULL location for storing the preferred size, or %NULL Called to get a renderer’s natural height. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location to store the minimum size, or %NULL location to store the natural size, or %NULL Called to get a renderer’s natural width for height. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to the size which is available for allocation location for storing the minimum size, or %NULL location for storing the preferred size, or %NULL Called to get the aligned area used by @cell inside @cell_area. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to render flags cell area which would be passed to gtk_cell_renderer_render() the return location for the space inside @cell_area that would acually be used to render. Called to get the width and height needed to render the cell. Deprecated: 3.0. a #GtkCellRenderer the widget the renderer is rendering to The area a cell will be allocated, or %NULL location to return x offset of cell relative to @cell_area, or %NULL location to return y offset of cell relative to @cell_area, or %NULL location to return width needed to render a cell, or %NULL location to return height needed to render a cell, or %NULL Called to render the content of the #GtkCellRenderer. a #GtkCellRenderer a cairo context to draw to the widget owning @window entire cell area (including tree expanders and maybe padding on the sides) area normally rendered by a cell renderer flags that affect rendering Called to activate the content of the #GtkCellRenderer. %TRUE if the event was consumed/handled a #GtkCellRenderer a #GdkEvent widget that received the event widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Called to initiate editing the content of the #GtkCellRenderer. A new #GtkCellEditable for editing this @cell, or %NULL if editing is not possible a #GtkCellRenderer a #GdkEvent widget that received the event widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Signal gets emitted when the user cancels the process of editing a cell. Signal gets emitted when a cell starts to be edited. Sets the type to be used for creating accessibles for cells rendered by cell renderers of @renderer_class. Note that multiple accessibles will be created. This function should only be called from class init functions of cell renderers. class to set the accessible type for The object type that implements the accessible for @widget_class. The type must be a subtype of #GtkRendererCellAccessible #GtkCellRendererCombo renders text in a cell like #GtkCellRendererText from which it is derived. But while #GtkCellRendererText offers a simple entry to edit the text, #GtkCellRendererCombo offers a #GtkComboBox widget to edit the text. The values to display in the combo box are taken from the tree model specified in the #GtkCellRendererCombo:model property. The combo cell renderer takes care of adding a text cell renderer to the combo box and sets it to display the column specified by its #GtkCellRendererCombo:text-column property. Further properties of the combo box can be set in a handler for the #GtkCellRenderer::editing-started signal. The #GtkCellRendererCombo cell renderer was added in GTK+ 2.6. Creates a new #GtkCellRendererCombo. Adjust how text is drawn using object properties. Object properties can be set globally (with g_object_set()). Also, with #GtkTreeViewColumn, you can bind a property to a value in a #GtkTreeModel. For example, you can bind the “text” property on the cell renderer to a string value in the model, thus rendering a different string in each row of the #GtkTreeView. the new cell renderer If %TRUE, the cell renderer will include an entry and allow to enter values other than the ones in the popup list. Holds a tree model containing the possible values for the combo box. Use the text_column property to specify the column holding the values. Specifies the model column which holds the possible values for the combo box. Note that this refers to the model specified in the model property, not the model backing the tree view to which this cell renderer is attached. #GtkCellRendererCombo automatically adds a text cell renderer for this column to its combo box. This signal is emitted each time after the user selected an item in the combo box, either by using the mouse or the arrow keys. Contrary to GtkComboBox, GtkCellRendererCombo::changed is not emitted for changes made to a selected item in the entry. The argument @new_iter corresponds to the newly selected item in the combo box and it is relative to the GtkTreeModel set via the model property on GtkCellRendererCombo. Note that as soon as you change the model displayed in the tree view, the tree view will immediately cease the editing operating. This means that you most probably want to refrain from changing the model until the combo cell renderer emits the edited or editing_canceled signal. a string of the path identifying the edited cell (relative to the tree view model) the new iter selected in the combo box (relative to the combo box model) Identifies how the user can interact with a particular cell. The cell is just for display and cannot be interacted with. Note that this doesn’t mean that eg. the row being drawn can’t be selected -- just that a particular element of it cannot be individually modified. The cell can be clicked. The cell can be edited or otherwise modified. A #GtkCellRendererPixbuf can be used to render an image in a cell. It allows to render either a given #GdkPixbuf (set via the #GtkCellRendererPixbuf:pixbuf property) or a named icon (set via the #GtkCellRendererPixbuf:icon-name property). To support the tree view, #GtkCellRendererPixbuf also supports rendering two alternative pixbufs, when the #GtkCellRenderer:is-expander property is %TRUE. If the #GtkCellRenderer:is-expanded property is %TRUE and the #GtkCellRendererPixbuf:pixbuf-expander-open property is set to a pixbuf, it renders that pixbuf, if the #GtkCellRenderer:is-expanded property is %FALSE and the #GtkCellRendererPixbuf:pixbuf-expander-closed property is set to a pixbuf, it renders that one. Creates a new #GtkCellRendererPixbuf. Adjust rendering parameters using object properties. Object properties can be set globally (with g_object_set()). Also, with #GtkTreeViewColumn, you can bind a property to a value in a #GtkTreeModel. For example, you can bind the “pixbuf” property on the cell renderer to a pixbuf value in the model, thus rendering a different image in each row of the #GtkTreeView. the new cell renderer Specifies whether the rendered pixbuf should be colorized according to the #GtkCellRendererState. Cell renderers always follow state. The GIcon representing the icon to display. If the icon theme is changed, the image will be updated automatically. The name of the themed icon to display. This property only has an effect if not overridden by "stock_id" or "pixbuf" properties. Use #GtkCellRendererPixbuf:icon-name instead. The #GtkIconSize value that specifies the size of the rendered icon. #GtkCellRendererProgress renders a numeric value as a progress par in a cell. Additionally, it can display a text on top of the progress bar. The #GtkCellRendererProgress cell renderer was added in GTK+ 2.6. Creates a new #GtkCellRendererProgress. the new cell renderer Setting this to a non-negative value causes the cell renderer to enter "activity mode", where a block bounces back and forth to indicate that some progress is made, without specifying exactly how much. Each increment of the property causes the block to move by a little bit. To indicate that the activity has not started yet, set the property to zero. To indicate completion, set the property to %G_MAXINT. The "text" property determines the label which will be drawn over the progress bar. Setting this property to %NULL causes the default label to be displayed. Setting this property to an empty string causes no label to be displayed. The "text-xalign" property controls the horizontal alignment of the text in the progress bar. Valid values range from 0 (left) to 1 (right). Reserved for RTL layouts. The "text-yalign" property controls the vertical alignment of the text in the progress bar. Valid values range from 0 (top) to 1 (bottom). The "value" property determines the percentage to which the progress bar will be "filled in". #GtkCellRendererSpin renders text in a cell like #GtkCellRendererText from which it is derived. But while #GtkCellRendererText offers a simple entry to edit the text, #GtkCellRendererSpin offers a #GtkSpinButton widget. Of course, that means that the text has to be parseable as a floating point number. The range of the spinbutton is taken from the adjustment property of the cell renderer, which can be set explicitly or mapped to a column in the tree model, like all properties of cell renders. #GtkCellRendererSpin also has properties for the #GtkCellRendererSpin:climb-rate and the number of #GtkCellRendererSpin:digits to display. Other #GtkSpinButton properties can be set in a handler for the #GtkCellRenderer::editing-started signal. The #GtkCellRendererSpin cell renderer was added in GTK+ 2.10. Creates a new #GtkCellRendererSpin. a new #GtkCellRendererSpin The adjustment that holds the value of the spinbutton. This must be non-%NULL for the cell renderer to be editable. The acceleration rate when you hold down a button. The number of decimal places to display. GtkCellRendererSpinner renders a spinning animation in a cell, very similar to #GtkSpinner. It can often be used as an alternative to a #GtkCellRendererProgress for displaying indefinite activity, instead of actual progress. To start the animation in a cell, set the #GtkCellRendererSpinner:active property to %TRUE and increment the #GtkCellRendererSpinner:pulse property at regular intervals. The usual way to set the cell renderer properties for each cell is to bind them to columns in your tree model using e.g. gtk_tree_view_column_add_attribute(). Returns a new cell renderer which will show a spinner to indicate activity. a new #GtkCellRenderer Pulse of the spinner. Increment this value to draw the next frame of the spinner animation. Usually, you would update this value in a timeout. By default, the #GtkSpinner widget draws one full cycle of the animation, consisting of 12 frames, in 750 milliseconds. The #GtkIconSize value that specifies the size of the rendered spinner. Tells how a cell is to be rendered. The cell is currently selected, and probably has a selection colored background to render to. The mouse is hovering over the cell. The cell is drawn in an insensitive manner The cell is in a sorted row The cell is in the focus row. The cell is in a row that can be expanded. Since 3.4 The cell is in a row that is expanded. Since 3.4 A #GtkCellRendererText renders a given text in its cell, using the font, color and style information provided by its properties. The text will be ellipsized if it is too long and the #GtkCellRendererText:ellipsize property allows it. If the #GtkCellRenderer:mode is %GTK_CELL_RENDERER_MODE_EDITABLE, the #GtkCellRendererText allows to edit its text using an entry. Creates a new #GtkCellRendererText. Adjust how text is drawn using object properties. Object properties can be set globally (with g_object_set()). Also, with #GtkTreeViewColumn, you can bind a property to a value in a #GtkTreeModel. For example, you can bind the “text” property on the cell renderer to a string value in the model, thus rendering a different string in each row of the #GtkTreeView the new cell renderer Sets the height of a renderer to explicitly be determined by the “font” and “y_pad” property set on it. Further changes in these properties do not affect the height, so they must be accompanied by a subsequent call to this function. Using this function is unflexible, and should really only be used if calculating the size of a cell is too slow (ie, a massive number of cells displayed). If @number_of_rows is -1, then the fixed height is unset, and the height is determined by the properties again. A #GtkCellRendererText Number of rows of text each cell renderer is allocated, or -1 Specifies how to align the lines of text with respect to each other. Note that this property describes how to align the lines of text in case there are several of them. The "xalign" property of #GtkCellRenderer, on the other hand, sets the horizontal alignment of the whole text. Background color as a #GdkColor Use #GtkCellRendererText:background-rgba instead. Background color as a #GdkRGBA Specifies the preferred place to ellipsize the string, if the cell renderer does not have enough room to display the entire string. Setting it to %PANGO_ELLIPSIZE_NONE turns off ellipsizing. See the wrap-width property for another way of making the text fit into a given width. Foreground color as a #GdkColor Use #GtkCellRendererText:foreground-rgba instead. Foreground color as a #GdkRGBA The desired maximum width of the cell, in characters. If this property is set to -1, the width will be calculated automatically. For cell renderers that ellipsize or wrap text; this property controls the maximum reported width of the cell. The cell should not receive any greater allocation unless it is set to expand in its #GtkCellLayout and all of the cell's siblings have received their natural width. The text that will be displayed in the #GtkCellRenderer if #GtkCellRendererText:editable is %TRUE and the cell is empty. Since 3.6 The desired width of the cell, in characters. If this property is set to -1, the width will be calculated automatically, otherwise the cell will request either 3 characters or the property value, whichever is greater. Specifies how to break the string into multiple lines, if the cell renderer does not have enough room to display the entire string. This property has no effect unless the wrap-width property is set. Specifies the minimum width at which the text is wrapped. The wrap-mode property can be used to influence at what character positions the line breaks can be placed. Setting wrap-width to -1 turns wrapping off. This signal is emitted after @renderer has been edited. It is the responsibility of the application to update the model and store @new_text at the position indicated by @path. the path identifying the edited cell the new text #GtkCellRendererToggle renders a toggle button in a cell. The button is drawn as a radio or a checkbutton, depending on the #GtkCellRendererToggle:radio property. When activated, it emits the #GtkCellRendererToggle::toggled signal. Creates a new #GtkCellRendererToggle. Adjust rendering parameters using object properties. Object properties can be set globally (with g_object_set()). Also, with #GtkTreeViewColumn, you can bind a property to a value in a #GtkTreeModel. For example, you can bind the “active” property on the cell renderer to a boolean value in the model, thus causing the check button to reflect the state of the model. the new cell renderer Returns whether the cell renderer is activatable. See gtk_cell_renderer_toggle_set_activatable(). %TRUE if the cell renderer is activatable. a #GtkCellRendererToggle Returns whether the cell renderer is active. See gtk_cell_renderer_toggle_set_active(). %TRUE if the cell renderer is active. a #GtkCellRendererToggle Returns whether we’re rendering radio toggles rather than checkboxes. %TRUE if we’re rendering radio toggles rather than checkboxes a #GtkCellRendererToggle Makes the cell renderer activatable. a #GtkCellRendererToggle. the value to set. Activates or deactivates a cell renderer. a #GtkCellRendererToggle. the value to set. If @radio is %TRUE, the cell renderer renders a radio toggle (i.e. a toggle in a group of mutually-exclusive toggles). If %FALSE, it renders a check toggle (a standalone boolean option). This can be set globally for the cell renderer, or changed just before rendering each cell in the model (for #GtkTreeView, you set up a per-row setting using #GtkTreeViewColumn to associate model columns with cell renderer properties). a #GtkCellRendererToggle %TRUE to make the toggle look like a radio button The ::toggled signal is emitted when the cell is toggled. It is the responsibility of the application to update the model with the correct value to store at @path. Often this is simply the opposite of the value currently stored at @path. string representation of #GtkTreePath describing the event location A #GtkCellView displays a single row of a #GtkTreeModel using a #GtkCellArea and #GtkCellAreaContext. A #GtkCellAreaContext can be provided to the #GtkCellView at construction time in order to keep the cellview in context of a group of cell views, this ensures that the renderers displayed will be properly aligned with eachother (like the aligned cells in the menus of #GtkComboBox). #GtkCellView is #GtkOrientable in order to decide in which orientation the underlying #GtkCellAreaContext should be allocated. Taking the #GtkComboBox menu as an example, cellviews should be oriented horizontally if the menus are listed top-to-bottom and thus all share the same width but may have separate individual heights (left-to-right menus should be allocated vertically since they all share the same height but may have variable widths). # CSS nodes GtkCellView has a single CSS node with name cellview. Creates a new #GtkCellView widget. A newly created #GtkCellView widget. Creates a new #GtkCellView widget with a specific #GtkCellArea to layout cells and a specific #GtkCellAreaContext. Specifying the same context for a handfull of cells lets the underlying area synchronize the geometry for those cells, in this way alignments with cellviews for other rows are possible. A newly created #GtkCellView widget. the #GtkCellArea to layout cells the #GtkCellAreaContext in which to calculate cell geometry Creates a new #GtkCellView widget, adds a #GtkCellRendererText to it, and makes it show @markup. The text can be marked up with the [Pango text markup language][PangoMarkupFormat]. A newly created #GtkCellView widget. the text to display in the cell view Creates a new #GtkCellView widget, adds a #GtkCellRendererPixbuf to it, and makes it show @pixbuf. A newly created #GtkCellView widget. the image to display in the cell view Creates a new #GtkCellView widget, adds a #GtkCellRendererText to it, and makes it show @text. A newly created #GtkCellView widget. the text to display in the cell view Returns a #GtkTreePath referring to the currently displayed row. If no row is currently displayed, %NULL is returned. the currently displayed row or %NULL a #GtkCellView Gets whether @cell_view is configured to draw all of its cells in a sensitive state. whether @cell_view draws all of its cells in a sensitive state a #GtkCellView Gets whether @cell_view is configured to request space to fit the entire #GtkTreeModel. whether @cell_view requests space to fit the entire #GtkTreeModel. a #GtkCellView Returns the model for @cell_view. If no model is used %NULL is returned. a #GtkTreeModel used or %NULL a #GtkCellView Sets @requisition to the size needed by @cell_view to display the model row pointed to by @path. Combo box formerly used this to calculate the sizes for cellviews, now you can achieve this by either using the #GtkCellView:fit-model property or by setting the currently displayed row of the #GtkCellView and using gtk_widget_get_preferred_size(). %TRUE a #GtkCellView a #GtkTreePath return location for the size Sets the background color of @view. Use gtk_cell_view_set_background_rgba() instead. a #GtkCellView the new background color Sets the background color of @cell_view. a #GtkCellView the new background color Sets the row of the model that is currently displayed by the #GtkCellView. If the path is unset, then the contents of the cellview “stick” at their last value; this is not normally a desired result, but may be a needed intermediate state if say, the model for the #GtkCellView becomes temporarily empty. a #GtkCellView a #GtkTreePath or %NULL to unset. Sets whether @cell_view should draw all of its cells in a sensitive state, this is used by #GtkComboBox menus to ensure that rows with insensitive cells that contain children appear sensitive in the parent menu item. a #GtkCellView whether to draw all cells in a sensitive state. Sets whether @cell_view should request space to fit the entire #GtkTreeModel. This is used by #GtkComboBox to ensure that the cell view displayed on the combo box’s button always gets enough space and does not resize when selection changes. a #GtkCellView whether @cell_view should request space for the whole model. Sets the model for @cell_view. If @cell_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. a #GtkCellView a #GtkTreeModel The background color as a #GdkColor Use #GtkCellView:background-rgba instead. The background color as a #GdkRGBA The #GtkCellArea rendering cells If no area is specified when creating the cell view with gtk_cell_view_new_with_context() a horizontally oriented #GtkCellAreaBox will be used. since 3.0 The #GtkCellAreaContext used to compute the geometry of the cell view. A group of cell views can be assigned the same context in order to ensure the sizes and cell alignments match across all the views with the same context. #GtkComboBox menus uses this to assign the same context to all cell views in the menu items for a single menu (each submenu creates its own context since the size of each submenu does not depend on parent or sibling menus). since 3.0 Whether all cells should be draw as sensitive for this view regardless of the actual cell properties (used to make menus with submenus appear sensitive when the items in submenus might be insensitive). since 3.0 Whether the view should request enough space to always fit the size of every row in the model (used by the combo box to ensure the combo box size doesnt change when different items are selected). since 3.0 The model for cell view since 2.10 The parent class. A #GtkCheckButton places a discrete #GtkToggleButton next to a widget, (usually a #GtkLabel). See the section on #GtkToggleButton widgets for more information about toggle/check buttons. The important signal ( #GtkToggleButton::toggled ) is also inherited from #GtkToggleButton. # CSS nodes |[<!-- language="plain" --> checkbutton ├── check ╰── <child> ]| A GtkCheckButton with indicator (see gtk_toggle_button_set_mode()) has a main CSS node with name checkbutton and a subnode with name check. |[<!-- language="plain" --> button.check ├── check ╰── <child> ]| A GtkCheckButton without indicator changes the name of its main node to button and adds a .check style class to it. The subnode is invisible in this case. Creates a new #GtkCheckButton. a #GtkWidget. Creates a new #GtkCheckButton with a #GtkLabel to the right of it. a #GtkWidget. the text for the check button. Creates a new #GtkCheckButton containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the check button. a new #GtkCheckButton The text of the button, with an underscore in front of the mnemonic character A #GtkCheckMenuItem is a menu item that maintains the state of a boolean value in addition to a #GtkMenuItem usual role in activating application code. A check box indicating the state of the boolean value is displayed at the left side of the #GtkMenuItem. Activating the #GtkMenuItem toggles the value. # CSS nodes |[<!-- language="plain" --> menuitem ├── check.left ╰── <child> ]| GtkCheckMenuItem has a main CSS node with name menuitem, and a subnode with name check, which gets the .left or .right style class. Creates a new #GtkCheckMenuItem. a new #GtkCheckMenuItem. Creates a new #GtkCheckMenuItem with a label. a new #GtkCheckMenuItem. the string to use for the label. Creates a new #GtkCheckMenuItem containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the menu item. a new #GtkCheckMenuItem The text of the button, with an underscore in front of the character Called to draw the check indicator. Emits the #GtkCheckMenuItem::toggled signal. a #GtkCheckMenuItem. Returns whether the check menu item is active. See gtk_check_menu_item_set_active (). %TRUE if the menu item is checked. a #GtkCheckMenuItem Returns whether @check_menu_item looks like a #GtkRadioMenuItem Whether @check_menu_item looks like a #GtkRadioMenuItem a #GtkCheckMenuItem Retrieves the value set by gtk_check_menu_item_set_inconsistent(). %TRUE if inconsistent a #GtkCheckMenuItem Sets the active state of the menu item’s check box. a #GtkCheckMenuItem. boolean value indicating whether the check box is active. Sets whether @check_menu_item is drawn like a #GtkRadioMenuItem a #GtkCheckMenuItem whether @check_menu_item is drawn like a #GtkRadioMenuItem If the user has selected a range of elements (such as some text or spreadsheet cells) that are affected by a boolean setting, and the current values in that range are inconsistent, you may want to display the check in an “in between” state. This function turns on “in between” display. Normally you would turn off the inconsistent state again if the user explicitly selects a setting. This has to be done manually, gtk_check_menu_item_set_inconsistent() only affects visual appearance, it doesn’t affect the semantics of the widget. a #GtkCheckMenuItem %TRUE to display an “inconsistent” third state check Emits the #GtkCheckMenuItem::toggled signal. a #GtkCheckMenuItem. This signal is emitted when the state of the check box is changed. A signal handler can use gtk_check_menu_item_get_active() to discover the new state. The parent class. Signal emitted when the state of the check box is changed. a #GtkCheckMenuItem. Called to draw the check indicator. The #GtkClipboard object represents a clipboard of data shared between different processes or between different widgets in the same process. Each clipboard is identified by a name encoded as a #GdkAtom. (Conversion to and from strings can be done with gdk_atom_intern() and gdk_atom_name().) The default clipboard corresponds to the “CLIPBOARD” atom; another commonly used clipboard is the “PRIMARY” clipboard, which, in X, traditionally contains the currently selected text. To support having a number of different formats on the clipboard at the same time, the clipboard mechanism allows providing callbacks instead of the actual data. When you set the contents of the clipboard, you can either supply the data directly (via functions like gtk_clipboard_set_text()), or you can supply a callback to be called at a later time when the data is needed (via gtk_clipboard_set_with_data() or gtk_clipboard_set_with_owner().) Providing a callback also avoids having to make copies of the data when it is not needed. gtk_clipboard_set_with_data() and gtk_clipboard_set_with_owner() are quite similar; the choice between the two depends mostly on which is more convenient in a particular situation. The former is most useful when you want to have a blob of data with callbacks to convert it into the various data types that you advertise. When the @clear_func you provided is called, you simply free the data blob. The latter is more useful when the contents of clipboard reflect the internal state of a #GObject (As an example, for the PRIMARY clipboard, when an entry widget provides the clipboard’s contents the contents are simply the text within the selected region.) If the contents change, the entry widget can call gtk_clipboard_set_with_owner() to update the timestamp for clipboard ownership, without having to worry about @clear_func being called. Requesting the data from the clipboard is essentially asynchronous. If the contents of the clipboard are provided within the same process, then a direct function call will be made to retrieve the data, but if they are provided by another process, then the data needs to be retrieved from the other process, which may take some time. To avoid blocking the user interface, the call to request the selection, gtk_clipboard_request_contents() takes a callback that will be called when the contents are received (or when the request fails.) If you don’t want to deal with providing a separate callback, you can also use gtk_clipboard_wait_for_contents(). What this does is run the GLib main loop recursively waiting for the contents. This can simplify the code flow, but you still have to be aware that other callbacks in your program can be called while this recursive mainloop is running. Along with the functions to get the clipboard contents as an arbitrary data chunk, there are also functions to retrieve it as text, gtk_clipboard_request_text() and gtk_clipboard_wait_for_text(). These functions take care of determining which formats are advertised by the clipboard provider, asking for the clipboard in the best available format and converting the results into the UTF-8 encoding. (The standard form for representing strings in GTK+.) Returns the clipboard object for the given selection. See gtk_clipboard_get_for_display() for complete details. the appropriate clipboard object. If no clipboard already exists, a new one will be created. Once a clipboard object has been created, it is persistent and, since it is owned by GTK+, must not be freed or unreffed. a #GdkAtom which identifies the clipboard to use Returns the default clipboard object for use with cut/copy/paste menu items and keyboard shortcuts. the default clipboard object. the #GdkDisplay for which the clipboard is to be retrieved. Returns the clipboard object for the given selection. Cut/copy/paste menu items and keyboard shortcuts should use the default clipboard, returned by passing %GDK_SELECTION_CLIPBOARD for @selection. (%GDK_NONE is supported as a synonym for GDK_SELECTION_CLIPBOARD for backwards compatibility reasons.) The currently-selected object or text should be provided on the clipboard identified by #GDK_SELECTION_PRIMARY. Cut/copy/paste menu items conceptually copy the contents of the #GDK_SELECTION_PRIMARY clipboard to the default clipboard, i.e. they copy the selection to what the user sees as the clipboard. (Passing #GDK_NONE is the same as using `gdk_atom_intern ("CLIPBOARD", FALSE)`. See the [FreeDesktop Clipboard Specification](http://www.freedesktop.org/Standards/clipboards-spec) for a detailed discussion of the “CLIPBOARD” vs. “PRIMARY” selections under the X window system. On Win32 the #GDK_SELECTION_PRIMARY clipboard is essentially ignored.) It’s possible to have arbitrary named clipboards; if you do invent new clipboards, you should prefix the selection name with an underscore (because the ICCCM requires that nonstandard atoms are underscore-prefixed), and namespace it as well. For example, if your application called “Foo” has a special-purpose clipboard, you might call it “_FOO_SPECIAL_CLIPBOARD”. the appropriate clipboard object. If no clipboard already exists, a new one will be created. Once a clipboard object has been created, it is persistent and, since it is owned by GTK+, must not be freed or unrefd. the #GdkDisplay for which the clipboard is to be retrieved or created. a #GdkAtom which identifies the clipboard to use. Clears the contents of the clipboard. Generally this should only be called between the time you call gtk_clipboard_set_with_owner() or gtk_clipboard_set_with_data(), and when the @clear_func you supplied is called. Otherwise, the clipboard may be owned by someone else. a #GtkClipboard Gets the #GdkDisplay associated with @clipboard the #GdkDisplay associated with @clipboard a #GtkClipboard If the clipboard contents callbacks were set with gtk_clipboard_set_with_owner(), and the gtk_clipboard_set_with_data() or gtk_clipboard_clear() has not subsequently called, returns the owner set by gtk_clipboard_set_with_owner(). the owner of the clipboard, if any; otherwise %NULL. a #GtkClipboard Gets the selection that this clipboard is for. the selection a #GtkClipboard Requests the contents of clipboard as the given target. When the results of the result are later received the supplied callback will be called. a #GtkClipboard an atom representing the form into which the clipboard owner should convert the selection. A function to call when the results are received (or the retrieval fails). If the retrieval fails the length field of @selection_data will be negative. user data to pass to @callback Requests the contents of the clipboard as image. When the image is later received, it will be converted to a #GdkPixbuf, and @callback will be called. The @pixbuf parameter to @callback will contain the resulting #GdkPixbuf if the request succeeded, or %NULL if it failed. This could happen for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into an image. a #GtkClipboard a function to call when the image is received, or the retrieval fails. (It will always be called one way or the other.) user data to pass to @callback. Requests the contents of the clipboard as rich text. When the rich text is later received, @callback will be called. The @text parameter to @callback will contain the resulting rich text if the request succeeded, or %NULL if it failed. The @length parameter will contain @text’s length. This function can fail for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into rich text form. a #GtkClipboard a #GtkTextBuffer a function to call when the text is received, or the retrieval fails. (It will always be called one way or the other.) user data to pass to @callback. Requests the contents of the clipboard as list of supported targets. When the list is later received, @callback will be called. The @targets parameter to @callback will contain the resulting targets if the request succeeded, or %NULL if it failed. a #GtkClipboard a function to call when the targets are received, or the retrieval fails. (It will always be called one way or the other.) user data to pass to @callback. Requests the contents of the clipboard as text. When the text is later received, it will be converted to UTF-8 if necessary, and @callback will be called. The @text parameter to @callback will contain the resulting text if the request succeeded, or %NULL if it failed. This could happen for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into text form. a #GtkClipboard a function to call when the text is received, or the retrieval fails. (It will always be called one way or the other.) user data to pass to @callback. Requests the contents of the clipboard as URIs. When the URIs are later received @callback will be called. The @uris parameter to @callback will contain the resulting array of URIs if the request succeeded, or %NULL if it failed. This could happen for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into URI form. a #GtkClipboard a function to call when the URIs are received, or the retrieval fails. (It will always be called one way or the other.) user data to pass to @callback. Hints that the clipboard data should be stored somewhere when the application exits or when gtk_clipboard_store () is called. This value is reset when the clipboard owner changes. Where the clipboard data is stored is platform dependent, see gdk_display_store_clipboard () for more information. a #GtkClipboard array containing information about which forms should be stored or %NULL to indicate that all forms should be stored. number of elements in @targets Sets the contents of the clipboard to the given #GdkPixbuf. GTK+ will take responsibility for responding for requests for the image, and for converting the image into the requested format. a #GtkClipboard object a #GdkPixbuf Sets the contents of the clipboard to the given UTF-8 string. GTK+ will make a copy of the text and take responsibility for responding for requests for the text, and for converting the text into the requested format. a #GtkClipboard object a UTF-8 string. length of @text, in bytes, or -1, in which case the length will be determined with strlen(). Virtually sets the contents of the specified clipboard by providing a list of supported formats for the clipboard data and a function to call to get the actual data when it is requested. %TRUE if setting the clipboard data succeeded. If setting the clipboard data failed the provided callback functions will be ignored. a #GtkClipboard array containing information about the available forms for the clipboard data number of elements in @targets function to call to get the actual clipboard data when the clipboard contents are set again, this function will be called, and @get_func will not be subsequently called. user data to pass to @get_func and @clear_func. Virtually sets the contents of the specified clipboard by providing a list of supported formats for the clipboard data and a function to call to get the actual data when it is requested. The difference between this function and gtk_clipboard_set_with_data() is that instead of an generic @user_data pointer, a #GObject is passed in. %TRUE if setting the clipboard data succeeded. If setting the clipboard data failed the provided callback functions will be ignored. a #GtkClipboard array containing information about the available forms for the clipboard data number of elements in @targets function to call to get the actual clipboard data when the clipboard contents are set again, this function will be called, and @get_func will not be subsequently called an object that “owns” the data. This object will be passed to the callbacks when called Stores the current clipboard data somewhere so that it will stay around after the application has quit. a #GtkClipboard Requests the contents of the clipboard using the given target. This function waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait. a newly-allocated #GtkSelectionData object or %NULL if retrieving the given target failed. If non-%NULL, this value must be freed with gtk_selection_data_free() when you are finished with it. a #GtkClipboard an atom representing the form into which the clipboard owner should convert the selection. Requests the contents of the clipboard as image and converts the result to a #GdkPixbuf. This function waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait. a newly-allocated #GdkPixbuf object which must be disposed with g_object_unref(), or %NULL if retrieving the selection data failed. (This could happen for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into an image.) a #GtkClipboard Requests the contents of the clipboard as rich text. This function waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait. a newly-allocated binary block of data which must be freed with g_free(), or %NULL if retrieving the selection data failed. (This could happen for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into text form.) a #GtkClipboard a #GtkTextBuffer return location for the format of the returned data return location for the length of the returned data Returns a list of targets that are present on the clipboard, or %NULL if there aren’t any targets available. The returned list must be freed with g_free(). This function waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait. %TRUE if any targets are present on the clipboard, otherwise %FALSE. a #GtkClipboard location to store an array of targets. The result stored here must be freed with g_free(). location to store number of items in @targets. Requests the contents of the clipboard as text and converts the result to UTF-8 if necessary. This function waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait. a newly-allocated UTF-8 string which must be freed with g_free(), or %NULL if retrieving the selection data failed. (This could happen for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into text form.) a #GtkClipboard Requests the contents of the clipboard as URIs. This function waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait. a newly-allocated %NULL-terminated array of strings which must be freed with g_strfreev(), or %NULL if retrieving the selection data failed. (This could happen for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into URI form.) a #GtkClipboard Test to see if there is an image available to be pasted This is done by requesting the TARGETS atom and checking if it contains any of the supported image targets. This function waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait. This function is a little faster than calling gtk_clipboard_wait_for_image() since it doesn’t need to retrieve the actual image data. %TRUE is there is an image available, %FALSE otherwise. a #GtkClipboard Test to see if there is rich text available to be pasted This is done by requesting the TARGETS atom and checking if it contains any of the supported rich text targets. This function waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait. This function is a little faster than calling gtk_clipboard_wait_for_rich_text() since it doesn’t need to retrieve the actual text. %TRUE is there is rich text available, %FALSE otherwise. a #GtkClipboard a #GtkTextBuffer Checks if a clipboard supports pasting data of a given type. This function can be used to determine if a “Paste” menu item should be insensitive or not. If you want to see if there’s text available on the clipboard, use gtk_clipboard_wait_is_text_available () instead. %TRUE if the target is available, %FALSE otherwise. a #GtkClipboard A #GdkAtom indicating which target to look for. Test to see if there is text available to be pasted This is done by requesting the TARGETS atom and checking if it contains any of the supported text targets. This function waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait. This function is a little faster than calling gtk_clipboard_wait_for_text() since it doesn’t need to retrieve the actual text. %TRUE is there is text available, %FALSE otherwise. a #GtkClipboard Test to see if there is a list of URIs available to be pasted This is done by requesting the TARGETS atom and checking if it contains the URI targets. This function waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait. This function is a little faster than calling gtk_clipboard_wait_for_uris() since it doesn’t need to retrieve the actual URI data. %TRUE is there is an URI list available, %FALSE otherwise. a #GtkClipboard The ::owner-change signal is emitted when GTK+ receives an event that indicates that the ownership of the selection associated with @clipboard has changed. the @GdkEventOwnerChange event A function that will be called when the contents of the clipboard are changed or cleared. Once this has called, the @user_data_or_owner argument will not be used again. the #GtkClipboard the @user_data argument passed to gtk_clipboard_set_with_data(), or the @owner argument passed to gtk_clipboard_set_with_owner() A function that will be called to provide the contents of the selection. If multiple types of data were advertised, the requested type can be determined from the @info parameter or by checking the target field of @selection_data. If the data could successfully be converted into then it should be stored into the @selection_data object by calling gtk_selection_data_set() (or related functions such as gtk_selection_data_set_text()). If no data is set, the requestor will be informed that the attempt to get the data failed. the #GtkClipboard a #GtkSelectionData argument in which the requested data should be stored. the info field corresponding to the requested target from the #GtkTargetEntry array passed to gtk_clipboard_set_with_data() or gtk_clipboard_set_with_owner(). the @user_data argument passed to gtk_clipboard_set_with_data(), or the @owner argument passed to gtk_clipboard_set_with_owner() A function to be called when the results of gtk_clipboard_request_image() are received, or when the request fails. the #GtkClipboard the received image the @user_data supplied to gtk_clipboard_request_image(). A function to be called when the results of gtk_clipboard_request_contents() are received, or when the request fails. the #GtkClipboard a #GtkSelectionData containing the data was received. If retrieving the data failed, then then length field of @selection_data will be negative. the @user_data supplied to gtk_clipboard_request_contents(). A function to be called when the results of gtk_clipboard_request_rich_text() are received, or when the request fails. the #GtkClipboard The format of the rich text the rich text received, as a UTF-8 encoded string, or %NULL if retrieving the data failed. Length of the text. the @user_data supplied to gtk_clipboard_request_rich_text(). A function to be called when the results of gtk_clipboard_request_targets() are received, or when the request fails. the #GtkClipboard the supported targets, as array of #GdkAtom, or %NULL if retrieving the data failed. the length of the @atoms array. the @user_data supplied to gtk_clipboard_request_targets(). A function to be called when the results of gtk_clipboard_request_text() are received, or when the request fails. the #GtkClipboard the text received, as a UTF-8 encoded string, or %NULL if retrieving the data failed. the @user_data supplied to gtk_clipboard_request_text(). A function to be called when the results of gtk_clipboard_request_uris() are received, or when the request fails. the #GtkClipboard the received URIs the @user_data supplied to gtk_clipboard_request_uris(). The #GtkColorButton is a button which displays the currently selected color and allows to open a color selection dialog to change the color. It is suitable widget for selecting a color in a preference dialog. # CSS nodes GtkColorButton has a single CSS node with name button. To differentiate it from a plain #GtkButton, it gets the .color style class. Creates a new color button. This returns a widget in the form of a small button containing a swatch representing the current selected color. When the button is clicked, a color-selection dialog will open, allowing the user to select a color. The swatch will be updated to reflect the new color when the user finishes. a new color button Creates a new color button. Use gtk_color_button_new_with_rgba() instead. a new color button A #GdkColor to set the current color with Creates a new color button. a new color button A #GdkRGBA to set the current color with Returns the current alpha value. Use gtk_color_chooser_get_rgba() instead. an integer between 0 and 65535 a #GtkColorButton Sets @color to be the current color in the #GtkColorButton widget. Use gtk_color_chooser_get_rgba() instead. a #GtkColorButton a #GdkColor to fill in with the current color Sets @rgba to be the current color in the #GtkColorButton widget. Use gtk_color_chooser_get_rgba() instead. a #GtkColorButton a #GdkRGBA to fill in with the current color Gets the title of the color selection dialog. An internal string, do not free the return value a #GtkColorButton Does the color selection dialog use the alpha channel ? Use gtk_color_chooser_get_use_alpha() instead. %TRUE if the color sample uses alpha channel, %FALSE if not a #GtkColorButton Sets the current opacity to be @alpha. Use gtk_color_chooser_set_rgba() instead. a #GtkColorButton an integer between 0 and 65535 Sets the current color to be @color. Use gtk_color_chooser_set_rgba() instead. a #GtkColorButton A #GdkColor to set the current color with Sets the current color to be @rgba. Use gtk_color_chooser_set_rgba() instead. a #GtkColorButton a #GdkRGBA to set the current color with Sets the title for the color selection dialog. a #GtkColorButton String containing new window title Sets whether or not the color button should use the alpha channel. Use gtk_color_chooser_set_use_alpha() instead. a #GtkColorButton %TRUE if color button should use alpha channel, %FALSE if not The selected opacity value (0 fully transparent, 65535 fully opaque). The selected color. Use #GtkColorButton:rgba instead. The RGBA color. Set this property to %TRUE to skip the palette in the dialog and go directly to the color editor. This property should be used in cases where the palette in the editor would be redundant, such as when the color button is already part of a palette. The title of the color selection dialog If this property is set to %TRUE, the color swatch on the button is rendered against a checkerboard background to show its opacity and the opacity slider is displayed in the color selection dialog. The ::color-set signal is emitted when the user selects a color. When handling this signal, use gtk_color_button_get_rgba() to find out which color was just selected. Note that this signal is only emitted when the user changes the color. If you need to react to programmatic color changes as well, use the notify::color signal. #GtkColorChooser is an interface that is implemented by widgets for choosing colors. Depending on the situation, colors may be allowed to have alpha (translucency). In GTK+, the main widgets that implement this interface are #GtkColorChooserWidget, #GtkColorChooserDialog and #GtkColorButton. Adds a palette to the color chooser. If @orientation is horizontal, the colors are grouped in rows, with @colors_per_line colors in each row. If @horizontal is %FALSE, the colors are grouped in columns instead. The default color palette of #GtkColorChooserWidget has 27 colors, organized in columns of 3 colors. The default gray palette has 9 grays in a single row. The layout of the color chooser widget works best when the palettes have 9-10 columns. Calling this function for the first time has the side effect of removing the default color and gray palettes from the color chooser. If @colors is %NULL, removes all previously added palettes. a #GtkColorChooser %GTK_ORIENTATION_HORIZONTAL if the palette should be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns the number of colors to show in each row/column the total number of elements in @colors the colors of the palette, or %NULL Gets the currently-selected color. a #GtkColorChooser a #GdkRGBA to fill in with the current color Sets the color. a #GtkColorChooser the new color Adds a palette to the color chooser. If @orientation is horizontal, the colors are grouped in rows, with @colors_per_line colors in each row. If @horizontal is %FALSE, the colors are grouped in columns instead. The default color palette of #GtkColorChooserWidget has 27 colors, organized in columns of 3 colors. The default gray palette has 9 grays in a single row. The layout of the color chooser widget works best when the palettes have 9-10 columns. Calling this function for the first time has the side effect of removing the default color and gray palettes from the color chooser. If @colors is %NULL, removes all previously added palettes. a #GtkColorChooser %GTK_ORIENTATION_HORIZONTAL if the palette should be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns the number of colors to show in each row/column the total number of elements in @colors the colors of the palette, or %NULL Gets the currently-selected color. a #GtkColorChooser a #GdkRGBA to fill in with the current color Returns whether the color chooser shows the alpha channel. %TRUE if the color chooser uses the alpha channel, %FALSE if not a #GtkColorChooser Sets the color. a #GtkColorChooser the new color Sets whether or not the color chooser should use the alpha channel. a #GtkColorChooser %TRUE if color chooser should use alpha channel, %FALSE if not The ::rgba property contains the currently selected color, as a #GdkRGBA struct. The property can be set to change the current selection programmatically. When ::use-alpha is %TRUE, colors may have alpha (translucency) information. When it is %FALSE, the #GdkRGBA struct obtained via the #GtkColorChooser:rgba property will be forced to have alpha == 1. Implementations are expected to show alpha by rendering the color over a non-uniform background (like a checkerboard pattern). Emitted when a color is activated from the color chooser. This usually happens when the user clicks a color swatch, or a color is selected and the user presses one of the keys Space, Shift+Space, Return or Enter. the color The #GtkColorChooserDialog widget is a dialog for choosing a color. It implements the #GtkColorChooser interface. Creates a new #GtkColorChooserDialog. a new #GtkColorChooserDialog Title of the dialog, or %NULL Transient parent of the dialog, or %NULL a #GtkColorChooser a #GdkRGBA to fill in with the current color a #GtkColorChooser the new color a #GtkColorChooser %GTK_ORIENTATION_HORIZONTAL if the palette should be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns the number of colors to show in each row/column the total number of elements in @colors the colors of the palette, or %NULL The #GtkColorChooserWidget widget lets the user select a color. By default, the chooser presents a predefined palette of colors, plus a small number of settable custom colors. It is also possible to select a different color with the single-color editor. To enter the single-color editing mode, use the context menu of any color of the palette, or use the '+' button to add a new custom color. The chooser automatically remembers the last selection, as well as custom colors. To change the initially selected color, use gtk_color_chooser_set_rgba(). To get the selected color use gtk_color_chooser_get_rgba(). The #GtkColorChooserWidget is used in the #GtkColorChooserDialog to provide a dialog for selecting colors. # CSS names GtkColorChooserWidget has a single CSS node with name colorchooser. Creates a new #GtkColorChooserWidget. a new #GtkColorChooserWidget The ::show-editor property is %TRUE when the color chooser is showing the single-color editor. It can be set to switch the color chooser into single-color editing mode. The parent class. Creates a new GtkColorSelection. a new #GtkColorSelection Parses a color palette string; the string is a colon-separated list of color names readable by gdk_color_parse(). %TRUE if a palette was successfully parsed a string encoding a color palette return location for allocated array of #GdkColor return location for length of array Encodes a palette as a string, useful for persistent storage. allocated string encoding the palette an array of colors length of the array Installs a global function to be called whenever the user tries to modify the palette in a color selection. This function should save the new palette contents, and update the #GtkSettings:gtk-color-palette GtkSettings property so all GtkColorSelection widgets will be modified. the previous change palette hook (that was replaced) a function to call when the custom palette needs saving Returns the current alpha value. an integer between 0 and 65535 a #GtkColorSelection Sets @color to be the current color in the GtkColorSelection widget. Use gtk_color_selection_get_current_rgba() instead. a #GtkColorSelection a #GdkColor to fill in with the current color Sets @rgba to be the current color in the GtkColorSelection widget. a #GtkColorSelection a #GdkRGBA to fill in with the current color Determines whether the colorsel has an opacity control. %TRUE if the @colorsel has an opacity control, %FALSE if it does't a #GtkColorSelection Determines whether the color selector has a color palette. %TRUE if the selector has a palette, %FALSE if it hasn't a #GtkColorSelection Returns the previous alpha value. an integer between 0 and 65535 a #GtkColorSelection Fills @color in with the original color value. Use gtk_color_selection_get_previous_rgba() instead. a #GtkColorSelection a #GdkColor to fill in with the original color value Fills @rgba in with the original color value. a #GtkColorSelection a #GdkRGBA to fill in with the original color value Gets the current state of the @colorsel. %TRUE if the user is currently dragging a color around, and %FALSE if the selection has stopped a #GtkColorSelection Sets the current opacity to be @alpha. The first time this is called, it will also set the original opacity to be @alpha too. a #GtkColorSelection an integer between 0 and 65535 Sets the current color to be @color. The first time this is called, it will also set the original color to be @color too. Use gtk_color_selection_set_current_rgba() instead. a #GtkColorSelection a #GdkColor to set the current color with Sets the current color to be @rgba. The first time this is called, it will also set the original color to be @rgba too. a #GtkColorSelection A #GdkRGBA to set the current color with Sets the @colorsel to use or not use opacity. a #GtkColorSelection %TRUE if @colorsel can set the opacity, %FALSE otherwise Shows and hides the palette based upon the value of @has_palette. a #GtkColorSelection %TRUE if palette is to be visible, %FALSE otherwise Sets the “previous” alpha to be @alpha. This function should be called with some hesitations, as it might seem confusing to have that alpha change. a #GtkColorSelection an integer between 0 and 65535 Sets the “previous” color to be @color. This function should be called with some hesitations, as it might seem confusing to have that color change. Calling gtk_color_selection_set_current_color() will also set this color the first time it is called. Use gtk_color_selection_set_previous_rgba() instead. a #GtkColorSelection a #GdkColor to set the previous color with Sets the “previous” color to be @rgba. This function should be called with some hesitations, as it might seem confusing to have that color change. Calling gtk_color_selection_set_current_rgba() will also set this color the first time it is called. a #GtkColorSelection a #GdkRGBA to set the previous color with The current GdkColor color. Use #GtkColorSelection:current-rgba instead. The current RGBA color. This signal is emitted when the color changes in the #GtkColorSelection according to its update policy. Array of colors Number of colors in the array Array of colors Number of colors in the array The parent class. Creates a new #GtkColorSelectionDialog. a #GtkColorSelectionDialog. a string containing the title text for the dialog. Retrieves the #GtkColorSelection widget embedded in the dialog. the embedded #GtkColorSelection a #GtkColorSelectionDialog A GtkComboBox is a widget that allows the user to choose from a list of valid choices. The GtkComboBox displays the selected choice. When activated, the GtkComboBox displays a popup which allows the user to make a new choice. The style in which the selected value is displayed, and the style of the popup is determined by the current theme. It may be similar to a Windows-style combo box. The GtkComboBox uses the model-view pattern; the list of valid choices is specified in the form of a tree model, and the display of the choices can be adapted to the data in the model by using cell renderers, as you would in a tree view. This is possible since GtkComboBox implements the #GtkCellLayout interface. The tree model holding the valid choices is not restricted to a flat list, it can be a real tree, and the popup will reflect the tree structure. To allow the user to enter values not in the model, the “has-entry” property allows the GtkComboBox to contain a #GtkEntry. This entry can be accessed by calling gtk_bin_get_child() on the combo box. For a simple list of textual choices, the model-view API of GtkComboBox can be a bit overwhelming. In this case, #GtkComboBoxText offers a simple alternative. Both GtkComboBox and #GtkComboBoxText can contain an entry. # CSS nodes |[<!-- language="plain" --> combobox ├── box.linked │ ╰── button.combo │ ╰── box │ ├── cellview │ ╰── arrow ╰── window.popup ]| A normal combobox contains a box with the .linked class, a button with the .combo class and inside those buttons, there are a cellview and an arrow. |[<!-- language="plain" --> combobox ├── box.linked │ ├── entry.combo │ ╰── button.combo │ ╰── box │ ╰── arrow ╰── window.popup ]| A GtkComboBox with an entry has a single CSS node with name combobox. It contains a box with the .linked class. That box contains an entry and a button, both with the .combo class added. The button also contains another node with name arrow. Creates a new empty #GtkComboBox. A new #GtkComboBox. Creates a new empty #GtkComboBox using @area to layout cells. A new #GtkComboBox. the #GtkCellArea to use to layout cell renderers Creates a new empty #GtkComboBox with an entry. The new combo box will use @area to layout cells. A new #GtkComboBox. the #GtkCellArea to use to layout cell renderers Creates a new empty #GtkComboBox with an entry. A new #GtkComboBox. Creates a new #GtkComboBox with the model initialized to @model. A new #GtkComboBox. A #GtkTreeModel. Creates a new empty #GtkComboBox with an entry and with the model initialized to @model. A new #GtkComboBox A #GtkTreeModel Signal is emitted when the active item is changed. Signal which allows you to change how the text displayed in a combo box’s entry is displayed. Returns the index of the currently active item, or -1 if there’s no active item. If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this function returns `gtk_tree_path_get_indices (path)[0]`, where `path` is the #GtkTreePath of the active item. An integer which is the index of the currently active item, or -1 if there’s no active item. A #GtkComboBox Returns the ID of the active row of @combo_box. This value is taken from the active row and the column specified by the #GtkComboBox:id-column property of @combo_box (see gtk_combo_box_set_id_column()). The returned value is an interned string which means that you can compare the pointer by value to other interned strings and that you must not free it. If the #GtkComboBox:id-column property of @combo_box is not set, or if no row is active, or if the active row has a %NULL ID value, then %NULL is returned. the ID of the active row, or %NULL a #GtkComboBox Sets @iter to point to the currently active item, if any item is active. Otherwise, @iter is left unchanged. %TRUE if @iter was set, %FALSE otherwise A #GtkComboBox A #GtkTreeIter Gets the current value of the :add-tearoffs property. the current value of the :add-tearoffs property. a #GtkComboBox Returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model. %GTK_SENSITIVITY_ON if the dropdown button is sensitive when the model is empty, %GTK_SENSITIVITY_OFF if the button is always insensitive or %GTK_SENSITIVITY_AUTO if it is only sensitive as long as the model has one item to be selected. a #GtkComboBox Returns the column with column span information for @combo_box. the column span column. A #GtkComboBox Returns the column which @combo_box is using to get the strings from to display in the internal entry. A column in the data source model of @combo_box. A #GtkComboBox. Returns whether the combo box grabs focus when it is clicked with the mouse. See gtk_combo_box_set_focus_on_click(). Use gtk_widget_get_focus_on_click() instead %TRUE if the combo box grabs focus when it is clicked with the mouse. a #GtkComboBox Returns whether the combo box has an entry. whether there is an entry in @combo_box. a #GtkComboBox Returns the column which @combo_box is using to get string IDs for values from. A column in the data source model of @combo_box. A #GtkComboBox Returns the #GtkTreeModel which is acting as data source for @combo_box. A #GtkTreeModel which was passed during construction. A #GtkComboBox Gets the accessible object corresponding to the combo box’s popup. This function is mostly intended for use by accessibility technologies; applications should have little use for it. the accessible object corresponding to the combo box’s popup. a #GtkComboBox Gets whether the popup uses a fixed width matching the allocated width of the combo box. %TRUE if the popup uses a fixed width a #GtkComboBox Returns the current row separator function. the current row separator function. a #GtkComboBox Returns the column with row span information for @combo_box. the row span column. A #GtkComboBox Gets the current title of the menu in tearoff mode. See gtk_combo_box_set_add_tearoffs(). the menu’s title in tearoff mode. This is an internal copy of the string which must not be freed. a #GtkComboBox Returns the wrap width which is used to determine the number of columns for the popup menu. If the wrap width is larger than 1, the combo box is in table mode. the wrap width. A #GtkComboBox Hides the menu or dropdown list of @combo_box. This function is mostly intended for use by accessibility technologies; applications should have little use for it. a #GtkComboBox Pops up the menu or dropdown list of @combo_box. This function is mostly intended for use by accessibility technologies; applications should have little use for it. Before calling this, @combo_box must be mapped, or nothing will happen. a #GtkComboBox Pops up the menu or dropdown list of @combo_box, the popup window will be grabbed so only @device and its associated pointer/keyboard are the only #GdkDevices able to send events to it. a #GtkComboBox a #GdkDevice Sets the active item of @combo_box to be the item at @index. A #GtkComboBox An index in the model passed during construction, or -1 to have no active item Changes the active row of @combo_box to the one that has an ID equal to @active_id, or unsets the active row if @active_id is %NULL. Rows having a %NULL ID string cannot be made active by this function. If the #GtkComboBox:id-column property of @combo_box is unset or if no row has the given ID then the function does nothing and returns %FALSE. %TRUE if a row with a matching ID was found. If a %NULL @active_id was given to unset the active row, the function always returns %TRUE. a #GtkComboBox the ID of the row to select, or %NULL Sets the current active item to be the one referenced by @iter, or unsets the active item if @iter is %NULL. A #GtkComboBox The #GtkTreeIter, or %NULL Sets whether the popup menu should have a tearoff menu item. a #GtkComboBox %TRUE to add tearoff menu items Sets whether the dropdown button of the combo box should be always sensitive (%GTK_SENSITIVITY_ON), never sensitive (%GTK_SENSITIVITY_OFF) or only if there is at least one item to display (%GTK_SENSITIVITY_AUTO). a #GtkComboBox specify the sensitivity of the dropdown button Sets the column with column span information for @combo_box to be @column_span. The column span column contains integers which indicate how many columns an item should span. A #GtkComboBox A column in the model passed during construction Sets the model column which @combo_box should use to get strings from to be @text_column. The column @text_column in the model of @combo_box must be of type %G_TYPE_STRING. This is only relevant if @combo_box has been created with #GtkComboBox:has-entry as %TRUE. A #GtkComboBox A column in @model to get the strings from for the internal entry Sets whether the combo box will grab focus when it is clicked with the mouse. Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard focus removed from the main area of the application. Use gtk_widget_set_focus_on_click() instead a #GtkComboBox whether the combo box grabs focus when clicked with the mouse Sets the model column which @combo_box should use to get string IDs for values from. The column @id_column in the model of @combo_box must be of type %G_TYPE_STRING. A #GtkComboBox A column in @model to get string IDs for values from Sets the model used by @combo_box to be @model. Will unset a previously set model (if applicable). If model is %NULL, then it will unset the model. Note that this function does not clear the cell renderers, you have to call gtk_cell_layout_clear() yourself if you need to set up different cell renderers for the new model. A #GtkComboBox A #GtkTreeModel Specifies whether the popup’s width should be a fixed width matching the allocated width of the combo box. a #GtkComboBox whether to use a fixed popup width Sets the row separator function, which is used to determine whether a row should be drawn as a separator. If the row separator function is %NULL, no separators are drawn. This is the default value. a #GtkComboBox a #GtkTreeViewRowSeparatorFunc user data to pass to @func, or %NULL destroy notifier for @data, or %NULL Sets the column with row span information for @combo_box to be @row_span. The row span column contains integers which indicate how many rows an item should span. A #GtkComboBox. A column in the model passed during construction. Sets the menu’s title in tearoff mode. a #GtkComboBox a title for the menu in tearoff mode Sets the wrap width of @combo_box to be @width. The wrap width is basically the preferred number of columns when you want the popup to be layed out in a table. A #GtkComboBox Preferred number of columns The item which is currently active. If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this property has the value `gtk_tree_path_get_indices (path)[0]`, where `path` is the #GtkTreePath of the active item. The value of the ID column of the active row. The add-tearoffs property controls whether generated menus have tearoff menu items. Note that this only affects menu style combo boxes. Whether the dropdown button is sensitive when the model is empty. The #GtkCellArea used to layout cell renderers for this combo box. If no area is specified when creating the combo box with gtk_combo_box_new_with_area() a horizontally oriented #GtkCellAreaBox will be used. If this is set to a non-negative value, it must be the index of a column of type %G_TYPE_INT in the model. The value in that column for each item will determine how many columns that item will span in the popup. Therefore, values in this column must be greater than zero, and the sum of an item’s column position + span should not exceed #GtkComboBox:wrap-width. The column in the combo box's model to associate with strings from the entry if the combo was created with #GtkComboBox:has-entry = %TRUE. Whether the combo box has an entry. The has-frame property controls whether a frame is drawn around the entry. The column in the combo box's model that provides string IDs for the values in the model, if != -1. The model from which the combo box takes the values shown in the list. Whether the popup's width should be a fixed width matching the allocated width of the combo box. Whether the combo boxes dropdown is popped up. Note that this property is mainly useful, because it allows you to connect to notify::popup-shown. If this is set to a non-negative value, it must be the index of a column of type %G_TYPE_INT in the model. The value in that column for each item will determine how many rows that item will span in the popup. Therefore, values in this column must be greater than zero. A title that may be displayed by the window manager when the popup is torn-off. If wrap-width is set to a positive value, items in the popup will be laid out along multiple columns, starting a new row on reaching the wrap width. The changed signal is emitted when the active item is changed. The can be due to the user selecting a different item from the list, or due to a call to gtk_combo_box_set_active_iter(). It will also be emitted while typing into the entry of a combo box with an entry. For combo boxes that are created with an entry (See GtkComboBox:has-entry). A signal which allows you to change how the text displayed in a combo box's entry is displayed. Connect a signal handler which returns an allocated string representing @path. That string will then be used to set the text in the combo box's entry. The default signal handler uses the text from the GtkComboBox::entry-text-column model column. Here's an example signal handler which fetches data from the model and displays it in the entry. |[<!-- language="C" --> static gchar* format_entry_text_callback (GtkComboBox *combo, const gchar *path, gpointer user_data) { GtkTreeIter iter; GtkTreeModel model; gdouble value; model = gtk_combo_box_get_model (combo); gtk_tree_model_get_iter_from_string (model, &iter, path); gtk_tree_model_get (model, &iter, THE_DOUBLE_VALUE_COLUMN, &value, -1); return g_strdup_printf ("%g", value); } ]| a newly allocated string representing @path for the current GtkComboBox model. the GtkTreePath string from the combo box's current model to format text for The ::move-active signal is a [keybinding signal][GtkBindingSignal] which gets emitted to move the active selection. a #GtkScrollType The ::popdown signal is a [keybinding signal][GtkBindingSignal] which gets emitted to popdown the combo box list. The default bindings for this signal are Alt+Up and Escape. The ::popup signal is a [keybinding signal][GtkBindingSignal] which gets emitted to popup the combo box list. The default binding for this signal is Alt+Down. The parent class. Signal is emitted when the active item is changed. Signal which allows you to change how the text displayed in a combo box’s entry is displayed. A GtkComboBoxText is a simple variant of #GtkComboBox that hides the model-view complexity for simple text-only use cases. To create a GtkComboBoxText, use gtk_combo_box_text_new() or gtk_combo_box_text_new_with_entry(). You can add items to a GtkComboBoxText with gtk_combo_box_text_append_text(), gtk_combo_box_text_insert_text() or gtk_combo_box_text_prepend_text() and remove options with gtk_combo_box_text_remove(). If the GtkComboBoxText contains an entry (via the “has-entry” property), its contents can be retrieved using gtk_combo_box_text_get_active_text(). The entry itself can be accessed by calling gtk_bin_get_child() on the combo box. You should not call gtk_combo_box_set_model() or attempt to pack more cells into this combo box via its GtkCellLayout interface. # GtkComboBoxText as GtkBuildable The GtkComboBoxText implementation of the GtkBuildable interface supports adding items directly using the `<items>` element and specifying `<item>` elements for each item. Each `<item>` element can specify the “id” corresponding to the appended text and also supports the regular translation attributes “translatable”, “context” and “comments”. Here is a UI definition fragment specifying GtkComboBoxText items: |[<!-- language="xml" --> <object class="GtkComboBoxText"> <items> <item translatable="yes" id="factory">Factory</item> <item translatable="yes" id="home">Home</item> <item translatable="yes" id="subway">Subway</item> </items> </object> ]| # CSS nodes |[<!-- language="plain" --> combobox ╰── box.linked ├── entry.combo ├── button.combo ╰── window.popup ]| GtkComboBoxText has a single CSS node with name combobox. It adds the style class .combo to the main CSS nodes of its entry and button children, and the .linked class to the node of its internal box. Creates a new #GtkComboBoxText, which is a #GtkComboBox just displaying strings. A new #GtkComboBoxText Creates a new #GtkComboBoxText, which is a #GtkComboBox just displaying strings. The combo box created by this function has an entry. a new #GtkComboBoxText Appends @text to the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. This is the same as calling gtk_combo_box_text_insert() with a position of -1. A #GtkComboBoxText a string ID for this value, or %NULL A string Appends @text to the list of strings stored in @combo_box. This is the same as calling gtk_combo_box_text_insert_text() with a position of -1. A #GtkComboBoxText A string Returns the currently active string in @combo_box, or %NULL if none is selected. If @combo_box contains an entry, this function will return its contents (which will not necessarily be an item from the list). a newly allocated string containing the currently active text. Must be freed with g_free(). A #GtkComboBoxText Inserts @text at @position in the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. See #GtkComboBox:id-column. If @position is negative then @text is appended. A #GtkComboBoxText An index to insert @text a string ID for this value, or %NULL A string to display Inserts @text at @position in the list of strings stored in @combo_box. If @position is negative then @text is appended. This is the same as calling gtk_combo_box_text_insert() with a %NULL ID string. A #GtkComboBoxText An index to insert @text A string Prepends @text to the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. This is the same as calling gtk_combo_box_text_insert() with a position of 0. A #GtkComboBox a string ID for this value, or %NULL a string Prepends @text to the list of strings stored in @combo_box. This is the same as calling gtk_combo_box_text_insert_text() with a position of 0. A #GtkComboBox A string Removes the string at @position from @combo_box. A #GtkComboBox Index of the item to remove Removes all the text entries from the combo box. A #GtkComboBoxText A GTK+ user interface is constructed by nesting widgets inside widgets. Container widgets are the inner nodes in the resulting tree of widgets: they contain other widgets. So, for example, you might have a #GtkWindow containing a #GtkFrame containing a #GtkLabel. If you wanted an image instead of a textual label inside the frame, you might replace the #GtkLabel widget with a #GtkImage widget. There are two major kinds of container widgets in GTK+. Both are subclasses of the abstract GtkContainer base class. The first type of container widget has a single child widget and derives from #GtkBin. These containers are decorators, which add some kind of functionality to the child. For example, a #GtkButton makes its child into a clickable button; a #GtkFrame draws a frame around its child and a #GtkWindow places its child widget inside a top-level window. The second type of container can have more than one child; its purpose is to manage layout. This means that these containers assign sizes and positions to their children. For example, a #GtkHBox arranges its children in a horizontal row, and a #GtkGrid arranges the widgets it contains in a two-dimensional grid. For implementations of #GtkContainer the virtual method #GtkContainerClass.forall() is always required, since it's used for drawing and other internal operations on the children. If the #GtkContainer implementation expect to have non internal children it's needed to implement both #GtkContainerClass.add() and #GtkContainerClass.remove(). If the GtkContainer implementation has internal children, they should be added with gtk_widget_set_parent() on init() and removed with gtk_widget_unparent() in the #GtkWidgetClass.destroy() implementation. See more about implementing custom widgets at https://wiki.gnome.org/HowDoI/CustomWidgets # Height for width geometry management GTK+ uses a height-for-width (and width-for-height) geometry management system. Height-for-width means that a widget can change how much vertical space it needs, depending on the amount of horizontal space that it is given (and similar for width-for-height). There are some things to keep in mind when implementing container widgets that make use of GTK+’s height for width geometry management system. First, it’s important to note that a container must prioritize one of its dimensions, that is to say that a widget or container can only have a #GtkSizeRequestMode that is %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT. However, every widget and container must be able to respond to the APIs for both dimensions, i.e. even if a widget has a request mode that is height-for-width, it is possible that its parent will request its sizes using the width-for-height APIs. To ensure that everything works properly, here are some guidelines to follow when implementing height-for-width (or width-for-height) containers. Each request mode involves 2 virtual methods. Height-for-width apis run through gtk_widget_get_preferred_width() and then through gtk_widget_get_preferred_height_for_width(). When handling requests in the opposite #GtkSizeRequestMode it is important that every widget request at least enough space to display all of its content at all times. When gtk_widget_get_preferred_height() is called on a container that is height-for-width, the container must return the height for its minimum width. This is easily achieved by simply calling the reverse apis implemented for itself as follows: |[<!-- language="C" --> static void foo_container_get_preferred_height (GtkWidget *widget, gint *min_height, gint *nat_height) { if (i_am_in_height_for_width_mode) { gint min_width; GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget, &min_width, NULL); GTK_WIDGET_GET_CLASS (widget)->get_preferred_height_for_width (widget, min_width, min_height, nat_height); } else { ... many containers support both request modes, execute the real width-for-height request here by returning the collective heights of all widgets that are stacked vertically (or whatever is appropriate for this container) ... } } ]| Similarly, when gtk_widget_get_preferred_width_for_height() is called for a container or widget that is height-for-width, it then only needs to return the base minimum width like so: |[<!-- language="C" --> static void foo_container_get_preferred_width_for_height (GtkWidget *widget, gint for_height, gint *min_width, gint *nat_width) { if (i_am_in_height_for_width_mode) { GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget, min_width, nat_width); } else { ... execute the real width-for-height request here based on the required width of the children collectively if the container were to be allocated the said height ... } } ]| Height for width requests are generally implemented in terms of a virtual allocation of widgets in the input orientation. Assuming an height-for-width request mode, a container would implement the get_preferred_height_for_width() virtual function by first calling gtk_widget_get_preferred_width() for each of its children. For each potential group of children that are lined up horizontally, the values returned by gtk_widget_get_preferred_width() should be collected in an array of #GtkRequestedSize structures. Any child spacing should be removed from the input @for_width and then the collective size should be allocated using the gtk_distribute_natural_allocation() convenience function. The container will then move on to request the preferred height for each child by using gtk_widget_get_preferred_height_for_width() and using the sizes stored in the #GtkRequestedSize array. To allocate a height-for-width container, it’s again important to consider that a container must prioritize one dimension over the other. So if a container is a height-for-width container it must first allocate all widgets horizontally using a #GtkRequestedSize array and gtk_distribute_natural_allocation() and then add any extra space (if and where appropriate) for the widget to expand. After adding all the expand space, the container assumes it was allocated sufficient height to fit all of its content. At this time, the container must use the total horizontal sizes of each widget to request the height-for-width of each of its children and store the requests in a #GtkRequestedSize array for any widgets that stack vertically (for tabular containers this can be generalized into the heights and widths of rows and columns). The vertical space must then again be distributed using gtk_distribute_natural_allocation() while this time considering the allocated height of the widget minus any vertical spacing that the container adds. Then vertical expand space should be added where appropriate and available and the container should go on to actually allocating the child widgets. See [GtkWidget’s geometry management section][geometry-management] to learn more about implementing height-for-width geometry management for widgets. # Child properties GtkContainer introduces child properties. These are object properties that are not specific to either the container or the contained widget, but rather to their relation. Typical examples of child properties are the position or pack-type of a widget which is contained in a #GtkBox. Use gtk_container_class_install_child_property() to install child properties for a container class and gtk_container_class_find_child_property() or gtk_container_class_list_child_properties() to get information about existing child properties. To set the value of a child property, use gtk_container_child_set_property(), gtk_container_child_set() or gtk_container_child_set_valist(). To obtain the value of a child property, use gtk_container_child_get_property(), gtk_container_child_get() or gtk_container_child_get_valist(). To emit notification about child property changes, use gtk_widget_child_notify(). # GtkContainer as GtkBuildable The GtkContainer implementation of the GtkBuildable interface supports a `<packing>` element for children, which can contain multiple `<property>` elements that specify child properties for the child. Since 2.16, child properties can also be marked as translatable using the same “translatable”, “comments” and “context” attributes that are used for regular properties. Since 3.16, containers can have a `<focus-chain>` element containing multiple `<widget>` elements, one for each child that should be added to the focus chain. The ”name” attribute gives the id of the widget. An example of these properties in UI definitions: |[<!-- language="xml" --> <object class="GtkBox"> <child> <object class="GtkEntry" id="entry1"/> <packing> <property name="pack-type">start</property> </packing> </child> <child> <object class="GtkEntry" id="entry2"/> </child> <focus-chain> <widget name="entry1"/> <widget name="entry2"/> </focus-chain> </object> ]| Adds @widget to @container. Typically used for simple containers such as #GtkWindow, #GtkFrame, or #GtkButton; for more complicated layout containers such as #GtkBox or #GtkGrid, this function will pick default packing parameters that may not be correct. So consider functions such as gtk_box_pack_start() and gtk_grid_attach() as an alternative to gtk_container_add() in those cases. A widget may be added to only one container at a time; you can’t place the same widget inside two different containers. Note that some containers, such as #GtkScrolledWindow or #GtkListBox, may add intermediate children between the added widget and the container. a #GtkContainer a widget to be placed inside @container Signal emitted when a size recalculation is needed. Returns the type of the children supported by the container. Note that this may return %G_TYPE_NONE to indicate that no more children can be added, e.g. for a #GtkPaned which already has two children. a #GType. a #GtkContainer Gets a widget’s composite name. Deprecated: 3.10. Invokes @callback on each direct child of @container, including children that are considered “internal” (implementation details of the container). “Internal” children generally weren’t added by the user of the container, but were added by the container implementation itself. Most applications should use gtk_container_foreach(), rather than gtk_container_forall(). a #GtkContainer a callback callback user data Get a property from a child of container. Returns a newly created widget path representing all the widget hierarchy from the toplevel down to and including @child. A newly created #GtkWidgetPath a #GtkContainer a child of @container Removes @widget from @container. @widget must be inside @container. Note that @container will own a reference to @widget, and that this may be the last reference held; so removing a widget from its container can destroy that widget. If you want to use @widget again, you need to add a reference to it before removing it from a container, using g_object_ref(). If you don’t want to use @widget again it’s usually more efficient to simply destroy it directly using gtk_widget_destroy() since this will remove it from the container and help break any circular reference count cycles. a #GtkContainer a current child of @container Set a property on a child of container. Sets, or unsets if @child is %NULL, the focused child of @container. This function emits the GtkContainer::set_focus_child signal of @container. Implementations of #GtkContainer can override the default behaviour by overriding the class closure of this signal. This is function is mostly meant to be used by widgets. Applications can use gtk_widget_grab_focus() to manually set the focus to a specific widget. a #GtkContainer a #GtkWidget, or %NULL Adds @widget to @container. Typically used for simple containers such as #GtkWindow, #GtkFrame, or #GtkButton; for more complicated layout containers such as #GtkBox or #GtkGrid, this function will pick default packing parameters that may not be correct. So consider functions such as gtk_box_pack_start() and gtk_grid_attach() as an alternative to gtk_container_add() in those cases. A widget may be added to only one container at a time; you can’t place the same widget inside two different containers. Note that some containers, such as #GtkScrolledWindow or #GtkListBox, may add intermediate children between the added widget and the container. a #GtkContainer a widget to be placed inside @container Adds @widget to @container, setting child properties at the same time. See gtk_container_add() and gtk_container_child_set() for more details. a #GtkContainer a widget to be placed inside @container the name of the first child property to set a %NULL-terminated list of property names and values, starting with @first_prop_name Gets the values of one or more child properties for @child and @container. a #GtkContainer a widget which is a child of @container the name of the first property to get return location for the first property, followed optionally by more name/return location pairs, followed by %NULL Gets the value of a child property for @child and @container. a #GtkContainer a widget which is a child of @container the name of the property to get a location to return the value Gets the values of one or more child properties for @child and @container. a #GtkContainer a widget which is a child of @container the name of the first property to get return location for the first property, followed optionally by more name/return location pairs, followed by %NULL Emits a #GtkWidget::child-notify signal for the [child property][child-properties] @child_property on the child. This is an analogue of g_object_notify() for child properties. Also see gtk_widget_child_notify(). the #GtkContainer the child widget the name of a child property installed on the class of @container Emits a #GtkWidget::child-notify signal for the [child property][child-properties] specified by @pspec on the child. This is an analogue of g_object_notify_by_pspec() for child properties. the #GtkContainer the child widget the #GParamSpec of a child property instealled on the class of @container Sets one or more child properties for @child and @container. a #GtkContainer a widget which is a child of @container the name of the first property to set a %NULL-terminated list of property names and values, starting with @first_prop_name Sets a child property for @child and @container. a #GtkContainer a widget which is a child of @container the name of the property to set the value to set the property to Sets one or more child properties for @child and @container. a #GtkContainer a widget which is a child of @container the name of the first property to set a %NULL-terminated list of property names and values, starting with @first_prop_name Returns the type of the children supported by the container. Note that this may return %G_TYPE_NONE to indicate that no more children can be added, e.g. for a #GtkPaned which already has two children. a #GType. a #GtkContainer Invokes @callback on each direct child of @container, including children that are considered “internal” (implementation details of the container). “Internal” children generally weren’t added by the user of the container, but were added by the container implementation itself. Most applications should use gtk_container_foreach(), rather than gtk_container_forall(). a #GtkContainer a callback callback user data Invokes @callback on each non-internal child of @container. See gtk_container_forall() for details on what constitutes an “internal” child. For all practical purposes, this function should iterate over precisely those child widgets that were added to the container by the application with explicit add() calls. It is permissible to remove the child from the @callback handler. Most applications should use gtk_container_foreach(), rather than gtk_container_forall(). a #GtkContainer a callback callback user data Retrieves the border width of the container. See gtk_container_set_border_width(). the current border width a #GtkContainer Returns the container’s non-internal children. See gtk_container_forall() for details on what constitutes an "internal" child. a newly-allocated list of the container’s non-internal children. a #GtkContainer Retrieves the focus chain of the container, if one has been set explicitly. If no focus chain has been explicitly set, GTK+ computes the focus chain based on the positions of the children. In that case, GTK+ stores %NULL in @focusable_widgets and returns %FALSE. For overriding focus behavior, use the GtkWidgetClass::focus signal. %TRUE if the focus chain of the container has been set explicitly. a #GtkContainer location to store the focus chain of the container, or %NULL. You should free this list using g_list_free() when you are done with it, however no additional reference count is added to the individual widgets in the focus chain. Returns the current focus child widget inside @container. This is not the currently focused widget. That can be obtained by calling gtk_window_get_focus(). The child widget which will receive the focus inside @container when the @container is focused, or %NULL if none is set. a #GtkContainer Retrieves the horizontal focus adjustment for the container. See gtk_container_set_focus_hadjustment (). the horizontal focus adjustment, or %NULL if none has been set. a #GtkContainer Retrieves the vertical focus adjustment for the container. See gtk_container_set_focus_vadjustment(). the vertical focus adjustment, or %NULL if none has been set. a #GtkContainer Returns a newly created widget path representing all the widget hierarchy from the toplevel down to and including @child. A newly created #GtkWidgetPath a #GtkContainer a child of @container Returns the resize mode for the container. See gtk_container_set_resize_mode (). Resize modes are deprecated. They aren’t necessary anymore since frame clocks and might introduce obscure bugs if used. the current resize mode a #GtkContainer When a container receives a call to the draw function, it must send synthetic #GtkWidget::draw calls to all children that don’t have their own #GdkWindows. This function provides a convenient way of doing this. A container, when it receives a call to its #GtkWidget::draw function, calls gtk_container_propagate_draw() once for each child, passing in the @cr the container received. gtk_container_propagate_draw() takes care of translating the origin of @cr, and deciding whether the draw needs to be sent to the child. It is a convenient and optimized way of getting the same effect as calling gtk_widget_draw() on the child directly. In most cases, a container can simply either inherit the #GtkWidget::draw implementation from #GtkContainer, or do some drawing and then chain to the ::draw implementation from #GtkContainer. a #GtkContainer a child of @container Cairo context as passed to the container. If you want to use @cr in container’s draw function, consider using cairo_save() and cairo_restore() before calling this function. Removes @widget from @container. @widget must be inside @container. Note that @container will own a reference to @widget, and that this may be the last reference held; so removing a widget from its container can destroy that widget. If you want to use @widget again, you need to add a reference to it before removing it from a container, using g_object_ref(). If you don’t want to use @widget again it’s usually more efficient to simply destroy it directly using gtk_widget_destroy() since this will remove it from the container and help break any circular reference count cycles. a #GtkContainer a current child of @container a #GtkContainer Sets the border width of the container. The border width of a container is the amount of space to leave around the outside of the container. The only exception to this is #GtkWindow; because toplevel windows can’t leave space outside, they leave the space inside. The border is added on all sides of the container. To add space to only one side, use a specific #GtkWidget:margin property on the child widget, for example #GtkWidget:margin-top. a #GtkContainer amount of blank space to leave outside the container. Valid values are in the range 0-65535 pixels. Sets a focus chain, overriding the one computed automatically by GTK+. In principle each widget in the chain should be a descendant of the container, but this is not enforced by this method, since it’s allowed to set the focus chain before you pack the widgets, or have a widget in the chain that isn’t always packed. The necessary checks are done when the focus chain is actually traversed. For overriding focus behavior, use the GtkWidgetClass::focus signal. a #GtkContainer the new focus chain Sets, or unsets if @child is %NULL, the focused child of @container. This function emits the GtkContainer::set_focus_child signal of @container. Implementations of #GtkContainer can override the default behaviour by overriding the class closure of this signal. This is function is mostly meant to be used by widgets. Applications can use gtk_widget_grab_focus() to manually set the focus to a specific widget. a #GtkContainer a #GtkWidget, or %NULL Hooks up an adjustment to focus handling in a container, so when a child of the container is focused, the adjustment is scrolled to show that widget. This function sets the horizontal alignment. See gtk_scrolled_window_get_hadjustment() for a typical way of obtaining the adjustment and gtk_container_set_focus_vadjustment() for setting the vertical adjustment. The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the container. a #GtkContainer an adjustment which should be adjusted when the focus is moved among the descendents of @container Hooks up an adjustment to focus handling in a container, so when a child of the container is focused, the adjustment is scrolled to show that widget. This function sets the vertical alignment. See gtk_scrolled_window_get_vadjustment() for a typical way of obtaining the adjustment and gtk_container_set_focus_hadjustment() for setting the horizontal adjustment. The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the container. a #GtkContainer an adjustment which should be adjusted when the focus is moved among the descendents of @container Sets the @reallocate_redraws flag of the container to the given value. Containers requesting reallocation redraws get automatically redrawn if any of their children changed allocation. Call gtk_widget_queue_draw() in your size_allocate handler. a #GtkContainer the new value for the container’s @reallocate_redraws flag Sets the resize mode for the container. The resize mode of a container determines whether a resize request will be passed to the container’s parent, queued for later execution or executed immediately. Resize modes are deprecated. They aren’t necessary anymore since frame clocks and might introduce obscure bugs if used. a #GtkContainer the new resize mode Removes a focus chain explicitly set with gtk_container_set_focus_chain(). For overriding focus behavior, use the GtkWidgetClass::focus signal. a #GtkContainer Get a list of children. the container Base class for containers. The parent class. Signal emitted when a widget is added to container. a #GtkContainer a widget to be placed inside @container Signal emitted when a widget is removed from container. a #GtkContainer a current child of @container Signal emitted when a size recalculation is needed. Invokes callback on each child of container. The callback handler may remove the child. a #GtkContainer a callback callback user data Sets the focused child of container. a #GtkContainer a #GtkWidget, or %NULL Returns the type of the children supported by the container. a #GType. a #GtkContainer Gets a widget’s composite name. Deprecated: 3.10. Set a property on a child of container. Get a property from a child of container. Get path representing entire widget hierarchy from the toplevel down to and including @child. A newly created #GtkWidgetPath a #GtkContainer a child of @container Finds a child property of a container class by name. the #GParamSpec of the child property or %NULL if @class has no child property with that name. a #GtkContainerClass the name of the child property to find Modifies a subclass of #GtkContainerClass to automatically add and remove the border-width setting on GtkContainer. This allows the subclass to ignore the border width in its size request and allocate methods. The intent is for a subclass to invoke this in its class_init function. gtk_container_class_handle_border_width() is necessary because it would break API too badly to make this behavior the default. So subclasses must “opt in” to the parent class handling border_width for them. the class struct of a #GtkContainer subclass Installs child properties on a container class. a #GtkContainerClass the length of the #GParamSpec array the #GParamSpec array defining the new child properties Installs a child property on a container class. a #GtkContainerClass the id for the property the #GParamSpec for the property Returns all child properties of a container class. a newly allocated %NULL-terminated array of #GParamSpec*. The array must be freed with g_free(). a #GtkContainerClass location to return the number of child properties found Specifies which corner a child widget should be placed in when packed into a #GtkScrolledWindow. This is effectively the opposite of where the scroll bars are placed. Place the scrollbars on the right and bottom of the widget (default behaviour). Place the scrollbars on the top and right of the widget. Place the scrollbars on the left and bottom of the widget. Place the scrollbars on the top and left of the widget. GtkCssProvider is an object implementing the #GtkStyleProvider interface. It is able to parse [CSS-like][css-overview] input in order to style widgets. An application can make GTK+ parse a specific CSS style sheet by calling gtk_css_provider_load_from_file() or gtk_css_provider_load_from_resource() and adding the provider with gtk_style_context_add_provider() or gtk_style_context_add_provider_for_screen(). In addition, certain files will be read when GTK+ is initialized. First, the file `$XDG_CONFIG_HOME/gtk-3.0/gtk.css` is loaded if it exists. Then, GTK+ loads the first existing file among `XDG_DATA_HOME/themes/THEME/gtk-VERSION/gtk.css`, `$HOME/.themes/THEME/gtk-VERSION/gtk.css`, `$XDG_DATA_DIRS/themes/THEME/gtk-VERSION/gtk.css` and `DATADIR/share/themes/THEME/gtk-VERSION/gtk.css`, where `THEME` is the name of the current theme (see the #GtkSettings:gtk-theme-name setting), `DATADIR` is the prefix configured when GTK+ was compiled (unless overridden by the `GTK_DATA_PREFIX` environment variable), and `VERSION` is the GTK+ version number. If no file is found for the current version, GTK+ tries older versions all the way back to 3.0. In the same way, GTK+ tries to load a gtk-keys.css file for the current key theme, as defined by #GtkSettings:gtk-key-theme-name. Returns a newly created #GtkCssProvider. A new #GtkCssProvider Returns the provider containing the style settings used as a fallback for all widgets. Use gtk_css_provider_new() instead. The provider used for fallback styling. This memory is owned by GTK+, and you must not free it. Loads a theme from the usual theme paths a #GtkCssProvider with the theme loaded. This memory is owned by GTK+, and you must not free it. A theme name variant to load, for example, "dark", or %NULL for the default Loads @data into @css_provider, and by doing so clears any previously loaded information. %TRUE. The return value is deprecated and %FALSE will only be returned for backwards compatibility reasons if an @error is not %NULL and a loading error occurred. To track errors while loading CSS, connect to the #GtkCssProvider::parsing-error signal. a #GtkCssProvider CSS data loaded in memory the length of @data in bytes, or -1 for NUL terminated strings. If @length is not -1, the code will assume it is not NUL terminated and will potentially do a copy. Loads the data contained in @file into @css_provider, making it clear any previously loaded information. %TRUE. The return value is deprecated and %FALSE will only be returned for backwards compatibility reasons if an @error is not %NULL and a loading error occurred. To track errors while loading CSS, connect to the #GtkCssProvider::parsing-error signal. a #GtkCssProvider #GFile pointing to a file to load Loads the data contained in @path into @css_provider, making it clear any previously loaded information. %TRUE. The return value is deprecated and %FALSE will only be returned for backwards compatibility reasons if an @error is not %NULL and a loading error occurred. To track errors while loading CSS, connect to the #GtkCssProvider::parsing-error signal. a #GtkCssProvider the path of a filename to load, in the GLib filename encoding Loads the data contained in the resource at @resource_path into the #GtkCssProvider, clearing any previously loaded information. To track errors while loading CSS, connect to the #GtkCssProvider::parsing-error signal. a #GtkCssProvider a #GResource resource path Converts the @provider into a string representation in CSS format. Using gtk_css_provider_load_from_data() with the return value from this function on a new provider created with gtk_css_provider_new() will basically create a duplicate of this @provider. a new string representing the @provider. the provider to write to a string Signals that a parsing error occurred. the @path, @line and @position describe the actual location of the error as accurately as possible. Parsing errors are never fatal, so the parsing will resume after the error. Errors may however cause parts of the given data or even all of it to not be parsed at all. So it is a useful idea to check that the parsing succeeds by connecting to this signal. Note that this signal may be emitted at any time as the css provider may opt to defer parsing parts or all of the input to a later time than when a loading function was called. section the error happened in The parsing error Error codes for %GTK_CSS_PROVIDER_ERROR. Failed. Syntax error. Import error. Name error. Deprecation error. Unknown value. Defines a part of a CSS document. Because sections are nested into one another, you can use gtk_css_section_get_parent() to get the containing region. Returns the line in the CSS document where this section end. The line number is 0-indexed, so the first line of the document will return 0. This value may change in future invocations of this function if @section is not yet parsed completely. This will for example happen in the GtkCssProvider::parsing-error signal. The end position and line may be identical to the start position and line for sections which failed to parse anything successfully. the line number the section Returns the offset in bytes from the start of the current line returned via gtk_css_section_get_end_line(). This value may change in future invocations of this function if @section is not yet parsed completely. This will for example happen in the GtkCssProvider::parsing-error signal. The end position and line may be identical to the start position and line for sections which failed to parse anything successfully. the offset in bytes from the start of the line. the section Gets the file that @section was parsed from. If no such file exists, for example because the CSS was loaded via @gtk_css_provider_load_from_data(), then %NULL is returned. the #GFile that @section was parsed from or %NULL if @section was parsed from other data the section Gets the parent section for the given @section. The parent section is the section that contains this @section. A special case are sections of type #GTK_CSS_SECTION_DOCUMENT. Their parent will either be %NULL if they are the original CSS document that was loaded by gtk_css_provider_load_from_file() or a section of type #GTK_CSS_SECTION_IMPORT if it was loaded with an import rule from a different file. the parent section or %NULL if none the section Gets the type of information that @section describes. the type of @section the section Returns the line in the CSS document where this section starts. The line number is 0-indexed, so the first line of the document will return 0. the line number the section Returns the offset in bytes from the start of the current line returned via gtk_css_section_get_start_line(). the offset in bytes from the start of the line. the section Increments the reference count on @section. @section itself. a #GtkCssSection Decrements the reference count on @section, freeing the structure if the reference count reaches 0. a #GtkCssSection The different types of sections indicate parts of a CSS document as parsed by GTK’s CSS parser. They are oriented towards the [CSS Grammar](http://www.w3.org/TR/CSS21/grammar.html), but may contain extensions. More types might be added in the future as the parser incorporates more features. The section describes a complete document. This section time is the only one where gtk_css_section_get_parent() might return %NULL. The section defines an import rule. The section defines a color. This is a GTK extension to CSS. The section defines a binding set. This is a GTK extension to CSS. The section defines a CSS ruleset. The section defines a CSS selector. The section defines the declaration of a CSS variable. The section defines the value of a CSS declaration. The section defines keyframes. See [CSS Animations](http://dev.w3.org/csswg/css3-animations/#keyframes) for details. Since 3.6 See also: #GtkEntry::delete-from-cursor. Delete characters. Delete only the portion of the word to the left/right of cursor if we’re in the middle of a word. Delete words. Delete display-lines. Display-lines refers to the visible lines, with respect to to the current line breaks. As opposed to paragraphs, which are defined by line breaks in the input. Delete only the portion of the display-line to the left/right of cursor. Delete to the end of the paragraph. Like C-k in Emacs (or its reverse). Delete entire line. Like C-k in pico. Delete only whitespace. Like M-\ in Emacs. The #GtkDestDefaults enumeration specifies the various types of action that will be taken on behalf of the user for a drag destination site. If set for a widget, GTK+, during a drag over this widget will check if the drag matches this widget’s list of possible targets and actions. GTK+ will then call gdk_drag_status() as appropriate. If set for a widget, GTK+ will draw a highlight on this widget as long as a drag is over this widget and the widget drag format and action are acceptable. If set for a widget, when a drop occurs, GTK+ will will check if the drag matches this widget’s list of possible targets and actions. If so, GTK+ will call gtk_drag_get_data() on behalf of the widget. Whether or not the drop is successful, GTK+ will call gtk_drag_finish(). If the action was a move, then if the drag was successful, then %TRUE will be passed for the @delete parameter to gtk_drag_finish(). If set, specifies that all default actions should be taken. Dialog boxes are a convenient way to prompt the user for a small amount of input, e.g. to display a message, ask a question, or anything else that does not require extensive effort on the user’s part. GTK+ treats a dialog as a window split vertically. The top section is a #GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry should be packed. The bottom area is known as the “action area”. This is generally used for packing buttons into the dialog which may perform functions such as cancel, ok, or apply. #GtkDialog boxes are created with a call to gtk_dialog_new() or gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is recommended; it allows you to set the dialog title, some convenient flags, and add simple buttons. If “dialog” is a newly created dialog, the two primary areas of the window can be accessed through gtk_dialog_get_content_area() and gtk_dialog_get_action_area(), as can be seen from the example below. A “modal” dialog (that is, one which freezes the rest of the application from user input), can be created by calling gtk_window_set_modal() on the dialog. Use the GTK_WINDOW() macro to cast the widget returned from gtk_dialog_new() into a #GtkWindow. When using gtk_dialog_new_with_buttons() you can also pass the #GTK_DIALOG_MODAL flag to make a dialog modal. If you add buttons to #GtkDialog using gtk_dialog_new_with_buttons(), gtk_dialog_add_button(), gtk_dialog_add_buttons(), or gtk_dialog_add_action_widget(), clicking the button will emit a signal called #GtkDialog::response with a response ID that you specified. GTK+ will never assign a meaning to positive response IDs; these are entirely user-defined. But for convenience, you can use the response IDs in the #GtkResponseType enumeration (these all have values less than zero). If a dialog receives a delete event, the #GtkDialog::response signal will be emitted with a response ID of #GTK_RESPONSE_DELETE_EVENT. If you want to block waiting for a dialog to return before returning control flow to your code, you can call gtk_dialog_run(). This function enters a recursive main loop and waits for the user to respond to the dialog, returning the response ID corresponding to the button the user clicked. For the simple dialog in the following example, in reality you’d probably use #GtkMessageDialog to save yourself some effort. But you’d need to create the dialog contents manually if you had more than a simple message in the dialog. An example for simple GtkDialog usage: |[<!-- language="C" --> // Function to open a dialog box with a message void quick_message (GtkWindow *parent, gchar *message) { GtkWidget *dialog, *label, *content_area; GtkDialogFlags flags; // Create the widgets flags = GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_dialog_new_with_buttons ("Message", parent, flags, _("_OK"), GTK_RESPONSE_NONE, NULL); content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog)); label = gtk_label_new (message); // Ensure that the dialog box is destroyed when the user responds g_signal_connect_swapped (dialog, "response", G_CALLBACK (gtk_widget_destroy), dialog); // Add the label, and show everything we’ve added gtk_container_add (GTK_CONTAINER (content_area), label); gtk_widget_show_all (dialog); } ]| # GtkDialog as GtkBuildable The GtkDialog implementation of the #GtkBuildable interface exposes the @vbox and @action_area as internal children with the names “vbox” and “action_area”. GtkDialog supports a custom `<action-widgets>` element, which can contain multiple `<action-widget>` elements. The “response” attribute specifies a numeric response, and the content of the element is the id of widget (which should be a child of the dialogs @action_area). To mark a response as default, set the “default“ attribute of the `<action-widget>` element to true. GtkDialog supports adding action widgets by specifying “action“ as the “type“ attribute of a `<child>` element. The widget will be added either to the action area or the headerbar of the dialog, depending on the “use-header-bar“ property. The response id has to be associated with the action widget using the `<action-widgets>` element. An example of a #GtkDialog UI definition fragment: |[<!-- language="xml" --> <object class="GtkDialog" id="dialog1"> <child type="action"> <object class="GtkButton" id="button_cancel"/> </child> <child type="action"> <object class="GtkButton" id="button_ok"> <property name="can-default">True</property> </object> </child> <action-widgets> <action-widget response="cancel">button_cancel</action-widget> <action-widget response="ok" default="true">button_ok</action-widget> </action-widgets> </object> ]| Creates a new dialog box. Widgets should not be packed into this #GtkWindow directly, but into the @vbox and @action_area, as described above. the new dialog as a #GtkWidget Creates a new #GtkDialog with title @title (or %NULL for the default title; see gtk_window_set_title()) and transient parent @parent (or %NULL for none; see gtk_window_set_transient_for()). The @flags argument can be used to make the dialog modal (#GTK_DIALOG_MODAL) and/or to have it destroyed along with its transient parent (#GTK_DIALOG_DESTROY_WITH_PARENT). After @flags, button text/response ID pairs should be listed, with a %NULL pointer ending the list. Button text can be arbitrary text. A response ID can be any positive number, or one of the values in the #GtkResponseType enumeration. If the user clicks one of these dialog buttons, #GtkDialog will emit the #GtkDialog::response signal with the corresponding response ID. If a #GtkDialog receives the #GtkWidget::delete-event signal, it will emit ::response with a response ID of #GTK_RESPONSE_DELETE_EVENT. However, destroying a dialog does not emit the ::response signal; so be careful relying on ::response when using the #GTK_DIALOG_DESTROY_WITH_PARENT flag. Buttons are from left to right, so the first button in the list will be the leftmost button in the dialog. Here’s a simple example: |[<!-- language="C" --> GtkWidget *main_app_window; // Window the dialog should show up on GtkWidget *dialog; GtkDialogFlags flags = GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_dialog_new_with_buttons ("My dialog", main_app_window, flags, _("_OK"), GTK_RESPONSE_ACCEPT, _("_Cancel"), GTK_RESPONSE_REJECT, NULL); ]| a new #GtkDialog Title of the dialog, or %NULL Transient parent of the dialog, or %NULL from #GtkDialogFlags text to go in first button, or %NULL response ID for first button, then additional buttons, ending with %NULL Signal emitted when the user uses a keybinding to close the dialog. Emits the #GtkDialog::response signal with the given response ID. Used to indicate that the user has responded to the dialog in some way; typically either you or gtk_dialog_run() will be monitoring the ::response signal and take appropriate action. a #GtkDialog response ID Adds an activatable widget to the action area of a #GtkDialog, connecting a signal handler that will emit the #GtkDialog::response signal on the dialog when the widget is activated. The widget is appended to the end of the dialog’s action area. If you want to add a non-activatable widget, simply pack it into the @action_area field of the #GtkDialog struct. a #GtkDialog an activatable widget response ID for @child Adds a button with the given text and sets things up so that clicking the button will emit the #GtkDialog::response signal with the given @response_id. The button is appended to the end of the dialog’s action area. The button widget is returned, but usually you don’t need it. the #GtkButton widget that was added a #GtkDialog text of button response ID for the button Adds more buttons, same as calling gtk_dialog_add_button() repeatedly. The variable argument list should be %NULL-terminated as with gtk_dialog_new_with_buttons(). Each button must have both text and response ID. a #GtkDialog button text response ID for first button, then more text-response_id pairs Returns the action area of @dialog. Direct access to the action area is discouraged; use gtk_dialog_add_button(), etc. the action area a #GtkDialog Returns the content area of @dialog. the content area #GtkBox. a #GtkDialog Returns the header bar of @dialog. Note that the headerbar is only used by the dialog if the #GtkDialog:use-header-bar property is %TRUE. the header bar a #GtkDialog Gets the response id of a widget in the action area of a dialog. the response id of @widget, or %GTK_RESPONSE_NONE if @widget doesn’t have a response id set. a #GtkDialog a widget in the action area of @dialog Gets the widget button that uses the given response ID in the action area of a dialog. the @widget button that uses the given @response_id, or %NULL. a #GtkDialog the response ID used by the @dialog widget Emits the #GtkDialog::response signal with the given response ID. Used to indicate that the user has responded to the dialog in some way; typically either you or gtk_dialog_run() will be monitoring the ::response signal and take appropriate action. a #GtkDialog response ID Blocks in a recursive main loop until the @dialog either emits the #GtkDialog::response signal, or is destroyed. If the dialog is destroyed during the call to gtk_dialog_run(), gtk_dialog_run() returns #GTK_RESPONSE_NONE. Otherwise, it returns the response ID from the ::response signal emission. Before entering the recursive main loop, gtk_dialog_run() calls gtk_widget_show() on the dialog for you. Note that you still need to show any children of the dialog yourself. During gtk_dialog_run(), the default behavior of #GtkWidget::delete-event is disabled; if the dialog receives ::delete_event, it will not be destroyed as windows usually are, and gtk_dialog_run() will return #GTK_RESPONSE_DELETE_EVENT. Also, during gtk_dialog_run() the dialog will be modal. You can force gtk_dialog_run() to return at any time by calling gtk_dialog_response() to emit the ::response signal. Destroying the dialog during gtk_dialog_run() is a very bad idea, because your post-run code won’t know whether the dialog was destroyed or not. After gtk_dialog_run() returns, you are responsible for hiding or destroying the dialog if you wish to do so. Typical usage of this function might be: |[<!-- language="C" --> GtkWidget *dialog = gtk_dialog_new (); // Set up dialog... int result = gtk_dialog_run (GTK_DIALOG (dialog)); switch (result) { case GTK_RESPONSE_ACCEPT: // do_application_specific_something (); break; default: // do_nothing_since_dialog_was_cancelled (); break; } gtk_widget_destroy (dialog); ]| Note that even though the recursive main loop gives the effect of a modal dialog (it prevents the user from interacting with other windows in the same window group while the dialog is run), callbacks such as timeouts, IO channel watches, DND drops, etc, will be triggered during a gtk_dialog_run() call. response ID a #GtkDialog Sets an alternative button order. If the #GtkSettings:gtk-alternative-button-order setting is set to %TRUE, the dialog buttons are reordered according to the order of the response ids passed to this function. By default, GTK+ dialogs use the button order advocated by the [GNOME Human Interface Guidelines](http://library.gnome.org/devel/hig-book/stable/) with the affirmative button at the far right, and the cancel button left of it. But the builtin GTK+ dialogs and #GtkMessageDialogs do provide an alternative button order, which is more suitable on some platforms, e.g. Windows. Use this function after adding all the buttons to your dialog, as the following example shows: |[<!-- language="C" --> cancel_button = gtk_dialog_add_button (GTK_DIALOG (dialog), _("_Cancel"), GTK_RESPONSE_CANCEL); ok_button = gtk_dialog_add_button (GTK_DIALOG (dialog), _("_OK"), GTK_RESPONSE_OK); gtk_widget_grab_default (ok_button); help_button = gtk_dialog_add_button (GTK_DIALOG (dialog), _("_Help"), GTK_RESPONSE_HELP); gtk_dialog_set_alternative_button_order (GTK_DIALOG (dialog), GTK_RESPONSE_OK, GTK_RESPONSE_CANCEL, GTK_RESPONSE_HELP, -1); ]| Deprecated a #GtkDialog a response id used by one @dialog’s buttons a list of more response ids of @dialog’s buttons, terminated by -1 Sets an alternative button order. If the #GtkSettings:gtk-alternative-button-order setting is set to %TRUE, the dialog buttons are reordered according to the order of the response ids in @new_order. See gtk_dialog_set_alternative_button_order() for more information. This function is for use by language bindings. Deprecated a #GtkDialog the number of response ids in @new_order an array of response ids of @dialog’s buttons Sets the last widget in the dialog’s action area with the given @response_id as the default widget for the dialog. Pressing “Enter” normally activates the default widget. a #GtkDialog a response ID Calls `gtk_widget_set_sensitive (widget, @setting)` for each widget in the dialog’s action area with the given @response_id. A convenient way to sensitize/desensitize dialog buttons. a #GtkDialog a response ID %TRUE for sensitive %TRUE if the dialog uses a #GtkHeaderBar for action buttons instead of the action-area. For technical reasons, this property is declared as an integer property, but you should only set it to %TRUE or %FALSE. The ::close signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user uses a keybinding to close the dialog. The default binding for this signal is the Escape key. Emitted when an action widget is clicked, the dialog receives a delete event, or the application programmer calls gtk_dialog_response(). On a delete event, the response ID is #GTK_RESPONSE_DELETE_EVENT. Otherwise, it depends on which action widget was clicked. the response ID The parent class. Signal emitted when an action widget is activated. a #GtkDialog response ID Signal emitted when the user uses a keybinding to close the dialog. Flags used to influence dialog construction. Make the constructed dialog modal, see gtk_window_set_modal() Destroy the dialog when its parent is destroyed, see gtk_window_set_destroy_with_parent() Create dialog with actions in header bar instead of action area. Since 3.12. Focus movement types. Move forward. Move backward. Move up. Move down. Move left. Move right. Gives an indication why a drag operation failed. The value can by obtained by connecting to the #GtkWidget::drag-failed signal. The drag operation was successful. No suitable drag target. The user cancelled the drag operation. The drag operation timed out. The pointer or keyboard grab used for the drag operation was broken. The drag operation failed due to some unspecified error. The #GtkDrawingArea widget is used for creating custom user interface elements. It’s essentially a blank widget; you can draw on it. After creating a drawing area, the application may want to connect to: - Mouse and button press signals to respond to input from the user. (Use gtk_widget_add_events() to enable events you wish to receive.) - The #GtkWidget::realize signal to take any necessary actions when the widget is instantiated on a particular display. (Create GDK resources in response to this signal.) - The #GtkWidget::size-allocate signal to take any necessary actions when the widget changes size. - The #GtkWidget::draw signal to handle redrawing the contents of the widget. The following code portion demonstrates using a drawing area to display a circle in the normal widget foreground color. Note that GDK automatically clears the exposed area before sending the expose event, and that drawing is implicitly clipped to the exposed area. If you want to have a theme-provided background, you need to call gtk_render_background() in your ::draw method. ## Simple GtkDrawingArea usage |[<!-- language="C" --> gboolean draw_callback (GtkWidget *widget, cairo_t *cr, gpointer data) { guint width, height; GdkRGBA color; GtkStyleContext *context; context = gtk_widget_get_style_context (widget); width = gtk_widget_get_allocated_width (widget); height = gtk_widget_get_allocated_height (widget); gtk_render_background (context, cr, 0, 0, width, height); cairo_arc (cr, width / 2.0, height / 2.0, MIN (width, height) / 2.0, 0, 2 * G_PI); gtk_style_context_get_color (context, gtk_style_context_get_state (context), &color); gdk_cairo_set_source_rgba (cr, &color); cairo_fill (cr); return FALSE; } [...] GtkWidget *drawing_area = gtk_drawing_area_new (); gtk_widget_set_size_request (drawing_area, 100, 100); g_signal_connect (G_OBJECT (drawing_area), "draw", G_CALLBACK (draw_callback), NULL); ]| Draw signals are normally delivered when a drawing area first comes onscreen, or when it’s covered by another window and then uncovered. You can also force an expose event by adding to the “damage region” of the drawing area’s window; gtk_widget_queue_draw_area() and gdk_window_invalidate_rect() are equally good ways to do this. You’ll then get a draw signal for the invalid region. The available routines for drawing are documented on the [GDK Drawing Primitives][gdk3-Cairo-Interaction] page and the cairo documentation. To receive mouse events on a drawing area, you will need to enable them with gtk_widget_add_events(). To receive keyboard events, you will need to set the “can-focus” property on the drawing area, and you should probably draw some user-visible indication that the drawing area is focused. Use gtk_widget_has_focus() in your expose event handler to decide whether to draw the focus indicator. See gtk_render_focus() for one way to draw focus. Creates a new drawing area. a new #GtkDrawingArea The #GtkEditable interface is an interface which should be implemented by text editing widgets, such as #GtkEntry and #GtkSpinButton. It contains functions for generically manipulating an editable widget, a large number of action signals used for key bindings, and several signals that an application can connect to to modify the behavior of a widget. As an example of the latter usage, by connecting the following handler to #GtkEditable::insert-text, an application can convert all entry into a widget into uppercase. ## Forcing entry to uppercase. |[<!-- language="C" --> #include <ctype.h>; void insert_text_handler (GtkEditable *editable, const gchar *text, gint length, gint *position, gpointer data) { gchar *result = g_utf8_strup (text, length); g_signal_handlers_block_by_func (editable, (gpointer) insert_text_handler, data); gtk_editable_insert_text (editable, result, length, position); g_signal_handlers_unblock_by_func (editable, (gpointer) insert_text_handler, data); g_signal_stop_emission_by_name (editable, "insert_text"); g_free (result); } ]| Deletes a sequence of characters. The characters that are deleted are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters deleted are those from @start_pos to the end of the text. Note that the positions are specified in characters, not bytes. a #GtkEditable start position end position Deletes a sequence of characters. The characters that are deleted are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters deleted are those from @start_pos to the end of the text. Note that the positions are specified in characters, not bytes. a #GtkEditable start position end position Inserts @new_text_length bytes of @new_text into the contents of the widget, at position @position. Note that the position is in characters, not in bytes. The function updates @position to point after the newly inserted text. a #GtkEditable the text to append the length of the text in bytes, or -1 location of the position text will be inserted at Retrieves a sequence of characters. The characters that are retrieved are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters retrieved are those characters from @start_pos to the end of the text. Note that positions are specified in characters, not bytes. a pointer to the contents of the widget as a string. This string is allocated by the #GtkEditable implementation and should be freed by the caller. a #GtkEditable start of text end of text Retrieves the current position of the cursor relative to the start of the content of the editable. Note that this position is in characters, not in bytes. the cursor position a #GtkEditable Retrieves the selection bound of the editable. start_pos will be filled with the start of the selection and @end_pos with end. If no text was selected both will be identical and %FALSE will be returned. Note that positions are specified in characters, not bytes. %TRUE if an area is selected, %FALSE otherwise a #GtkEditable location to store the starting position, or %NULL location to store the end position, or %NULL Inserts @new_text_length bytes of @new_text into the contents of the widget, at position @position. Note that the position is in characters, not in bytes. The function updates @position to point after the newly inserted text. a #GtkEditable the text to append the length of the text in bytes, or -1 location of the position text will be inserted at Sets the cursor position in the editable to the given value. The cursor is displayed before the character with the given (base 0) index in the contents of the editable. The value must be less than or equal to the number of characters in the editable. A value of -1 indicates that the position should be set after the last character of the editable. Note that @position is in characters, not in bytes. a #GtkEditable the position of the cursor Selects a region of text. The characters that are selected are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters selected are those characters from @start_pos to the end of the text. Note that positions are specified in characters, not bytes. a #GtkEditable start of region end of region Copies the contents of the currently selected content in the editable and puts it on the clipboard. a #GtkEditable Removes the contents of the currently selected content in the editable and puts it on the clipboard. a #GtkEditable Deletes the currently selected text of the editable. This call doesn’t do anything if there is no selected text. a #GtkEditable Deletes a sequence of characters. The characters that are deleted are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters deleted are those from @start_pos to the end of the text. Note that the positions are specified in characters, not bytes. a #GtkEditable start position end position Retrieves a sequence of characters. The characters that are retrieved are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters retrieved are those characters from @start_pos to the end of the text. Note that positions are specified in characters, not bytes. a pointer to the contents of the widget as a string. This string is allocated by the #GtkEditable implementation and should be freed by the caller. a #GtkEditable start of text end of text Retrieves whether @editable is editable. See gtk_editable_set_editable(). %TRUE if @editable is editable. a #GtkEditable Retrieves the current position of the cursor relative to the start of the content of the editable. Note that this position is in characters, not in bytes. the cursor position a #GtkEditable Retrieves the selection bound of the editable. start_pos will be filled with the start of the selection and @end_pos with end. If no text was selected both will be identical and %FALSE will be returned. Note that positions are specified in characters, not bytes. %TRUE if an area is selected, %FALSE otherwise a #GtkEditable location to store the starting position, or %NULL location to store the end position, or %NULL Inserts @new_text_length bytes of @new_text into the contents of the widget, at position @position. Note that the position is in characters, not in bytes. The function updates @position to point after the newly inserted text. a #GtkEditable the text to append the length of the text in bytes, or -1 location of the position text will be inserted at Pastes the content of the clipboard to the current position of the cursor in the editable. a #GtkEditable Selects a region of text. The characters that are selected are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters selected are those characters from @start_pos to the end of the text. Note that positions are specified in characters, not bytes. a #GtkEditable start of region end of region Determines if the user can edit the text in the editable widget or not. a #GtkEditable %TRUE if the user is allowed to edit the text in the widget Sets the cursor position in the editable to the given value. The cursor is displayed before the character with the given (base 0) index in the contents of the editable. The value must be less than or equal to the number of characters in the editable. A value of -1 indicates that the position should be set after the last character of the editable. Note that @position is in characters, not in bytes. a #GtkEditable the position of the cursor The ::changed signal is emitted at the end of a single user-visible operation on the contents of the #GtkEditable. E.g., a paste operation that replaces the contents of the selection will cause only one signal emission (even though it is implemented by first deleting the selection, then inserting the new content, and may cause multiple ::notify::text signals to be emitted). This signal is emitted when text is deleted from the widget by the user. The default handler for this signal will normally be responsible for deleting the text, so by connecting to this signal and then stopping the signal with g_signal_stop_emission(), it is possible to modify the range of deleted text, or prevent it from being deleted entirely. The @start_pos and @end_pos parameters are interpreted as for gtk_editable_delete_text(). the starting position the end position This signal is emitted when text is inserted into the widget by the user. The default handler for this signal will normally be responsible for inserting the text, so by connecting to this signal and then stopping the signal with g_signal_stop_emission(), it is possible to modify the inserted text, or prevent it from being inserted entirely. the new text to insert the length of the new text, in bytes, or -1 if new_text is nul-terminated the position, in characters, at which to insert the new text. this is an in-out parameter. After the signal emission is finished, it should point after the newly inserted text. a #GtkEditable the text to append the length of the text in bytes, or -1 location of the position text will be inserted at a #GtkEditable start position end position a #GtkEditable the text to append the length of the text in bytes, or -1 location of the position text will be inserted at a #GtkEditable start position end position a pointer to the contents of the widget as a string. This string is allocated by the #GtkEditable implementation and should be freed by the caller. a #GtkEditable start of text end of text a #GtkEditable start of region end of region %TRUE if an area is selected, %FALSE otherwise a #GtkEditable location to store the starting position, or %NULL location to store the end position, or %NULL a #GtkEditable the position of the cursor the cursor position a #GtkEditable The #GtkEntry widget is a single line text entry widget. A fairly large set of key bindings are supported by default. If the entered text is longer than the allocation of the widget, the widget will scroll so that the cursor position is visible. When using an entry for passwords and other sensitive information, it can be put into “password mode” using gtk_entry_set_visibility(). In this mode, entered text is displayed using a “invisible” character. By default, GTK+ picks the best invisible character that is available in the current font, but it can be changed with gtk_entry_set_invisible_char(). Since 2.16, GTK+ displays a warning when Caps Lock or input methods might interfere with entering text in a password entry. The warning can be turned off with the #GtkEntry:caps-lock-warning property. Since 2.16, GtkEntry has the ability to display progress or activity information behind the text. To make an entry display such information, use gtk_entry_set_progress_fraction() or gtk_entry_set_progress_pulse_step(). Additionally, GtkEntry can show icons at either side of the entry. These icons can be activatable by clicking, can be set up as drag source and can have tooltips. To add an icon, use gtk_entry_set_icon_from_gicon() or one of the various other functions that set an icon from a stock id, an icon name or a pixbuf. To trigger an action when the user clicks an icon, connect to the #GtkEntry::icon-press signal. To allow DND operations from an icon, use gtk_entry_set_icon_drag_source(). To set a tooltip on an icon, use gtk_entry_set_icon_tooltip_text() or the corresponding function for markup. Note that functionality or information that is only available by clicking on an icon in an entry may not be accessible at all to users which are not able to use a mouse or other pointing device. It is therefore recommended that any such functionality should also be available by other means, e.g. via the context menu of the entry. # CSS nodes |[<!-- language="plain" --> entry[.read-only][.flat][.warning][.error] ├── image.left ├── image.right ├── undershoot.left ├── undershoot.right ├── [selection] ├── [progress[.pulse]] ╰── [window.popup] ]| GtkEntry has a main node with the name entry. Depending on the properties of the entry, the style classes .read-only and .flat may appear. The style classes .warning and .error may also be used with entries. When the entry shows icons, it adds subnodes with the name image and the style class .left or .right, depending on where the icon appears. When the entry has a selection, it adds a subnode with the name selection. When the entry shows progress, it adds a subnode with the name progress. The node has the style class .pulse when the shown progress is pulsing. The CSS node for a context menu is added as a subnode below entry as well. The undershoot nodes are used to draw the underflow indication when content is scrolled out of view. These nodes get the .left and .right style classes added depending on where the indication is drawn. When touch is used and touch selection handles are shown, they are using CSS nodes with name cursor-handle. They get the .top or .bottom style class depending on where they are shown in relation to the selection. If there is just a single handle for the text cursor, it gets the style class .insertion-cursor. Creates a new entry. a new #GtkEntry. Creates a new entry with the specified text buffer. a new #GtkEntry The buffer to use for the new #GtkEntry. Class handler for the #GtkEntry::activate signal. The default implementation calls gtk_window_activate_default() on the entry’s top-level window. Class handler for the #GtkEntry::backspace signal. The default implementation deletes the selection or a single character or word. Class handler for the #GtkEntry::copy-clipboard signal. The default implementation copies the selection, if one exists. Class handler for the #GtkEntry::cut-clipboard signal. The default implementation cuts the selection, if one exists. Class handler for the #GtkEntry::delete-from-cursor signal. The default implementation deletes the selection or the specified number of characters or words. Calculate the size of the text area frame, which is its allocated width and requested height, minus space for margins and borders, and taking baseline and text height into account. This virtual function must be non-%NULL. Calculate the size of the text area, which is its allocated width and requested height, minus space for margins and borders. This virtual function must be non-%NULL. Class handler for the #GtkEntry::insert-at-cursor signal. The default implementation inserts text at the cursor. Class handler for the #GtkEntry::move-cursor signal. The default implementation specifies the standard #GtkEntry cursor movement behavior. Class handler for the #GtkEntry::paste-clipboard signal. The default implementation pastes at the current cursor position or over the current selection if one exists. Class handler for the #GtkEntry::populate-popup signal. If non-%NULL, this will be called to add additional entries to the context menu when it is displayed. Class handler for the #GtkEntry::toggle-overwrite signal. The default implementation toggles overwrite mode and blinks the cursor. Retrieves the value set by gtk_entry_set_activates_default(). %TRUE if the entry will activate the default widget a #GtkEntry Gets the value set by gtk_entry_set_alignment(). the alignment a #GtkEntry Gets the attribute list that was set on the entry using gtk_entry_set_attributes(), if any. the attribute list, or %NULL if none was set. a #GtkEntry Get the #GtkEntryBuffer object which holds the text for this widget. A #GtkEntryBuffer object. a #GtkEntry Returns the auxiliary completion object currently in use by @entry. The auxiliary completion object currently in use by @entry. A #GtkEntry Returns the index of the icon which is the source of the current DND operation, or -1. This function is meant to be used in a #GtkWidget::drag-data-get callback. index of the icon which is the source of the current DND operation, or -1. a #GtkEntry Retrieves the horizontal cursor adjustment for the entry. See gtk_entry_set_cursor_hadjustment(). the horizontal cursor adjustment, or %NULL if none has been set. a #GtkEntry Gets the value set by gtk_entry_set_has_frame(). whether the entry has a beveled frame a #GtkEntry Returns whether the icon is activatable. %TRUE if the icon is activatable. a #GtkEntry Icon position Gets the area where entry’s icon at @icon_pos is drawn. This function is useful when drawing something to the entry in a draw callback. If the entry is not realized or has no icon at the given position, @icon_area is filled with zeros. Otherwise, @icon_area will be filled with the icon’s allocation, relative to @entry’s allocation. See also gtk_entry_get_text_area() A #GtkEntry Icon position Return location for the icon’s area Finds the icon at the given position and return its index. The position’s coordinates are relative to the @entry’s top left corner. If @x, @y doesn’t lie inside an icon, -1 is returned. This function is intended for use in a #GtkWidget::query-tooltip signal handler. the index of the icon at the given position, or -1 a #GtkEntry the x coordinate of the position to find the y coordinate of the position to find Retrieves the #GIcon used for the icon, or %NULL if there is no icon or if the icon was set by some other method (e.g., by stock, pixbuf, or icon name). A #GIcon, or %NULL if no icon is set or if the icon is not a #GIcon A #GtkEntry Icon position Retrieves the icon name used for the icon, or %NULL if there is no icon or if the icon was set by some other method (e.g., by pixbuf, stock or gicon). An icon name, or %NULL if no icon is set or if the icon wasn’t set from an icon name A #GtkEntry Icon position Retrieves the image used for the icon. Unlike the other methods of setting and getting icon data, this method will work regardless of whether the icon was set using a #GdkPixbuf, a #GIcon, a stock item, or an icon name. A #GdkPixbuf, or %NULL if no icon is set for this position. A #GtkEntry Icon position Returns whether the icon appears sensitive or insensitive. %TRUE if the icon is sensitive. a #GtkEntry Icon position Retrieves the stock id used for the icon, or %NULL if there is no icon or if the icon was set by some other method (e.g., by pixbuf, icon name or gicon). Use gtk_entry_get_icon_name() instead. A stock id, or %NULL if no icon is set or if the icon wasn’t set from a stock id A #GtkEntry Icon position Gets the type of representation being used by the icon to store image data. If the icon has no image data, the return value will be %GTK_IMAGE_EMPTY. image representation being used a #GtkEntry Icon position Gets the contents of the tooltip on the icon at the specified position in @entry. the tooltip text, or %NULL. Free the returned string with g_free() when done. a #GtkEntry the icon position Gets the contents of the tooltip on the icon at the specified position in @entry. the tooltip text, or %NULL. Free the returned string with g_free() when done. a #GtkEntry the icon position This function returns the entry’s #GtkEntry:inner-border property. See gtk_entry_set_inner_border() for more information. Use the standard border and padding CSS properties (through objects like #GtkStyleContext and #GtkCssProvider); the value returned by this function is ignored by #GtkEntry. the entry’s #GtkBorder, or %NULL if none was set. a #GtkEntry Gets the value of the #GtkEntry:input-hints property. a #GtkEntry Gets the value of the #GtkEntry:input-purpose property. a #GtkEntry Retrieves the character displayed in place of the real characters for entries with visibility set to false. See gtk_entry_set_invisible_char(). the current invisible char, or 0, if the entry does not show invisible text at all. a #GtkEntry Gets the #PangoLayout used to display the entry. The layout is useful to e.g. convert text positions to pixel positions, in combination with gtk_entry_get_layout_offsets(). The returned layout is owned by the entry and must not be modified or freed by the caller. Keep in mind that the layout text may contain a preedit string, so gtk_entry_layout_index_to_text_index() and gtk_entry_text_index_to_layout_index() are needed to convert byte indices in the layout to byte indices in the entry contents. the #PangoLayout for this entry a #GtkEntry Obtains the position of the #PangoLayout used to render text in the entry, in widget coordinates. Useful if you want to line up the text in an entry with some other text, e.g. when using the entry to implement editable cells in a sheet widget. Also useful to convert mouse events into coordinates inside the #PangoLayout, e.g. to take some action if some part of the entry text is clicked. Note that as the user scrolls around in the entry the offsets will change; you’ll need to connect to the “notify::scroll-offset” signal to track this. Remember when using the #PangoLayout functions you need to convert to and from pixels using PANGO_PIXELS() or #PANGO_SCALE. Keep in mind that the layout text may contain a preedit string, so gtk_entry_layout_index_to_text_index() and gtk_entry_text_index_to_layout_index() are needed to convert byte indices in the layout to byte indices in the entry contents. a #GtkEntry location to store X offset of layout, or %NULL location to store Y offset of layout, or %NULL Retrieves the maximum allowed length of the text in @entry. See gtk_entry_set_max_length(). This is equivalent to getting @entry's #GtkEntryBuffer and calling gtk_entry_buffer_get_max_length() on it. the maximum allowed number of characters in #GtkEntry, or 0 if there is no maximum. a #GtkEntry Retrieves the desired maximum width of @entry, in characters. See gtk_entry_set_max_width_chars(). the maximum width of the entry, in characters a #GtkEntry Gets the value set by gtk_entry_set_overwrite_mode(). whether the text is overwritten when typing. a #GtkEntry Retrieves the text that will be displayed when @entry is empty and unfocused a pointer to the placeholder text as a string. This string points to internally allocated storage in the widget and must not be freed, modified or stored. a #GtkEntry Returns the current fraction of the task that’s been completed. See gtk_entry_set_progress_fraction(). a fraction from 0.0 to 1.0 a #GtkEntry Retrieves the pulse step set with gtk_entry_set_progress_pulse_step(). a fraction from 0.0 to 1.0 a #GtkEntry Gets the tabstops that were set on the entry using gtk_entry_set_tabs(), if any. the tabstops, or %NULL if none was set. a #GtkEntry Retrieves the contents of the entry widget. See also gtk_editable_get_chars(). This is equivalent to getting @entry's #GtkEntryBuffer and calling gtk_entry_buffer_get_text() on it. a pointer to the contents of the widget as a string. This string points to internally allocated storage in the widget and must not be freed, modified or stored. a #GtkEntry Gets the area where the entry’s text is drawn. This function is useful when drawing something to the entry in a draw callback. If the entry is not realized, @text_area is filled with zeros. See also gtk_entry_get_icon_area(). a #GtkEntry Return location for the text area. Retrieves the current length of the text in @entry. This is equivalent to getting @entry's #GtkEntryBuffer and calling gtk_entry_buffer_get_length() on it. the current number of characters in #GtkEntry, or 0 if there are none. a #GtkEntry Retrieves whether the text in @entry is visible. See gtk_entry_set_visibility(). %TRUE if the text is currently visible a #GtkEntry Gets the value set by gtk_entry_set_width_chars(). number of chars to request space for, or negative if unset a #GtkEntry Causes @entry to have keyboard focus. It behaves like gtk_widget_grab_focus(), except that it doesn't select the contents of the entry. You only want to call this on some special entries which the user usually doesn't want to replace all text in, such as search-as-you-type entries. a #GtkEntry Allow the #GtkEntry input method to internally handle key press and release events. If this function returns %TRUE, then no further processing should be done for this key event. See gtk_im_context_filter_keypress(). Note that you are expected to call this function from your handler when overriding key event handling. This is needed in the case when you need to insert your own key handling between the input method and the default key event handling of the #GtkEntry. See gtk_text_view_reset_im_context() for an example of use. %TRUE if the input method handled the key event. a #GtkEntry the key event Converts from a position in the entry’s #PangoLayout (returned by gtk_entry_get_layout()) to a position in the entry contents (returned by gtk_entry_get_text()). byte index into the entry contents a #GtkEntry byte index into the entry layout text Indicates that some progress is made, but you don’t know how much. Causes the entry’s progress indicator to enter “activity mode,” where a block bounces back and forth. Each call to gtk_entry_progress_pulse() causes the block to move by a little bit (the amount of movement per pulse is determined by gtk_entry_set_progress_pulse_step()). a #GtkEntry Reset the input method context of the entry if needed. This can be necessary in the case where modifying the buffer would confuse on-going input method behavior. a #GtkEntry If @setting is %TRUE, pressing Enter in the @entry will activate the default widget for the window containing the entry. This usually means that the dialog box containing the entry will be closed, since the default widget is usually one of the dialog buttons. (For experts: if @setting is %TRUE, the entry calls gtk_window_activate_default() on the window containing the entry, in the default handler for the #GtkEntry::activate signal.) a #GtkEntry %TRUE to activate window’s default widget on Enter keypress Sets the alignment for the contents of the entry. This controls the horizontal positioning of the contents when the displayed text is shorter than the width of the entry. a #GtkEntry The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts Sets a #PangoAttrList; the attributes in the list are applied to the entry text. a #GtkEntry a #PangoAttrList Set the #GtkEntryBuffer object which holds the text for this widget. a #GtkEntry a #GtkEntryBuffer Sets @completion to be the auxiliary completion object to use with @entry. All further configuration of the completion mechanism is done on @completion using the #GtkEntryCompletion API. Completion is disabled if @completion is set to %NULL. A #GtkEntry The #GtkEntryCompletion or %NULL Hooks up an adjustment to the cursor position in an entry, so that when the cursor is moved, the adjustment is scrolled to show that position. See gtk_scrolled_window_get_hadjustment() for a typical way of obtaining the adjustment. The adjustment has to be in pixel units and in the same coordinate system as the entry. a #GtkEntry an adjustment which should be adjusted when the cursor is moved, or %NULL Sets whether the entry has a beveled frame around it. a #GtkEntry new value Sets whether the icon is activatable. A #GtkEntry Icon position %TRUE if the icon should be activatable Sets up the icon at the given position so that GTK+ will start a drag operation when the user clicks and drags the icon. To handle the drag operation, you need to connect to the usual #GtkWidget::drag-data-get (or possibly #GtkWidget::drag-data-delete) signal, and use gtk_entry_get_current_icon_drag_source() in your signal handler to find out if the drag was started from an icon. By default, GTK+ uses the icon as the drag icon. You can use the #GtkWidget::drag-begin signal to set a different icon. Note that you have to use g_signal_connect_after() to ensure that your signal handler gets executed after the default handler. a #GtkEntry icon position the targets (data formats) in which the data can be provided a bitmask of the allowed drag actions Sets the icon shown in the entry at the specified position from the current icon theme. If the icon isn’t known, a “broken image” icon will be displayed instead. If @icon is %NULL, no icon will be shown in the specified position. A #GtkEntry The position at which to set the icon The icon to set, or %NULL Sets the icon shown in the entry at the specified position from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If @icon_name is %NULL, no icon will be shown in the specified position. A #GtkEntry The position at which to set the icon An icon name, or %NULL Sets the icon shown in the specified position using a pixbuf. If @pixbuf is %NULL, no icon will be shown in the specified position. a #GtkEntry Icon position A #GdkPixbuf, or %NULL Sets the icon shown in the entry at the specified position from a stock image. If @stock_id is %NULL, no icon will be shown in the specified position. Use gtk_entry_set_icon_from_icon_name() instead. A #GtkEntry Icon position The name of the stock item, or %NULL Sets the sensitivity for the specified icon. A #GtkEntry Icon position Specifies whether the icon should appear sensitive or insensitive Sets @tooltip as the contents of the tooltip for the icon at the specified position. @tooltip is assumed to be marked up with the [Pango text markup language][PangoMarkupFormat]. Use %NULL for @tooltip to remove an existing tooltip. See also gtk_widget_set_tooltip_markup() and gtk_entry_set_icon_tooltip_text(). a #GtkEntry the icon position the contents of the tooltip for the icon, or %NULL Sets @tooltip as the contents of the tooltip for the icon at the specified position. Use %NULL for @tooltip to remove an existing tooltip. See also gtk_widget_set_tooltip_text() and gtk_entry_set_icon_tooltip_markup(). If you unset the widget tooltip via gtk_widget_set_tooltip_text() or gtk_widget_set_tooltip_markup(), this sets GtkWidget:has-tooltip to %FALSE, which suppresses icon tooltips too. You can resolve this by then calling gtk_widget_set_has_tooltip() to set GtkWidget:has-tooltip back to %TRUE, or setting at least one non-empty tooltip on any icon achieves the same result. a #GtkEntry the icon position the contents of the tooltip for the icon, or %NULL Sets %entry’s inner-border property to @border, or clears it if %NULL is passed. The inner-border is the area around the entry’s text, but inside its frame. If set, this property overrides the inner-border style property. Overriding the style-provided border is useful when you want to do in-place editing of some text in a canvas or list widget, where pixel-exact positioning of the entry is important. Use the standard border and padding CSS properties (through objects like #GtkStyleContext and #GtkCssProvider); the value set with this function is ignored by #GtkEntry. a #GtkEntry a #GtkBorder, or %NULL Sets the #GtkEntry:input-hints property, which allows input methods to fine-tune their behaviour. a #GtkEntry the hints Sets the #GtkEntry:input-purpose property which can be used by on-screen keyboards and other input methods to adjust their behaviour. a #GtkEntry the purpose Sets the character to use in place of the actual text when gtk_entry_set_visibility() has been called to set text visibility to %FALSE. i.e. this is the character used in “password mode” to show the user how many characters have been typed. By default, GTK+ picks the best invisible char available in the current font. If you set the invisible char to 0, then the user will get no feedback at all; there will be no text on the screen as they type. a #GtkEntry a Unicode character Sets the maximum allowed length of the contents of the widget. If the current contents are longer than the given length, then they will be truncated to fit. This is equivalent to getting @entry's #GtkEntryBuffer and calling gtk_entry_buffer_set_max_length() on it. ]| a #GtkEntry the maximum length of the entry, or 0 for no maximum. (other than the maximum length of entries.) The value passed in will be clamped to the range 0-65536. Sets the desired maximum width in characters of @entry. a #GtkEntry the new desired maximum width, in characters Sets whether the text is overwritten when typing in the #GtkEntry. a #GtkEntry new value Sets text to be displayed in @entry when it is empty and unfocused. This can be used to give a visual hint of the expected contents of the #GtkEntry. Note that since the placeholder text gets removed when the entry received focus, using this feature is a bit problematic if the entry is given the initial focus in a window. Sometimes this can be worked around by delaying the initial focus setting until the first key event arrives. a #GtkEntry a string to be displayed when @entry is empty and unfocused, or %NULL Causes the entry’s progress indicator to “fill in” the given fraction of the bar. The fraction should be between 0.0 and 1.0, inclusive. a #GtkEntry fraction of the task that’s been completed Sets the fraction of total entry width to move the progress bouncing block for each call to gtk_entry_progress_pulse(). a #GtkEntry fraction between 0.0 and 1.0 Sets a #PangoTabArray; the tabstops in the array are applied to the entry text. a #GtkEntry a #PangoTabArray Sets the text in the widget to the given value, replacing the current contents. See gtk_entry_buffer_set_text(). a #GtkEntry the new text Sets whether the contents of the entry are visible or not. When visibility is set to %FALSE, characters are displayed as the invisible char, and will also appear that way when the text in the entry widget is copied elsewhere. By default, GTK+ picks the best invisible character available in the current font, but it can be changed with gtk_entry_set_invisible_char(). Note that you probably want to set #GtkEntry:input-purpose to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN to inform input methods about the purpose of this entry, in addition to setting visibility to %FALSE. a #GtkEntry %TRUE if the contents of the entry are displayed as plaintext Changes the size request of the entry to be about the right size for @n_chars characters. Note that it changes the size request, the size can still be affected by how you pack the widget into containers. If @n_chars is -1, the size reverts to the default entry size. a #GtkEntry width in chars Converts from a position in the entry contents (returned by gtk_entry_get_text()) to a position in the entry’s #PangoLayout (returned by gtk_entry_get_layout(), with text retrieved via pango_layout_get_text()). byte index into the entry layout text a #GtkEntry byte index into the entry contents Unsets the invisible char previously set with gtk_entry_set_invisible_char(). So that the default invisible char is used again. a #GtkEntry A list of Pango attributes to apply to the text of the entry. This is mainly useful to change the size or weight of the text. The #PangoAttribute's @start_index and @end_index must refer to the #GtkEntryBuffer text, i.e. without the preedit string. Whether password entries will show a warning when Caps Lock is on. Note that the warning is shown using a secondary icon, and thus does not work if you are using the secondary icon position for some other purpose. The auxiliary completion object to use with the entry. Which IM (input method) module should be used for this entry. See #GtkIMContext. Setting this to a non-%NULL value overrides the system-wide IM module setting. See the GtkSettings #GtkSettings:gtk-im-module property. Sets the text area's border between the text and the frame. Use the standard border and padding CSS properties (through objects like #GtkStyleContext and #GtkCssProvider); the value of this style property is ignored. Additional hints (beyond #GtkEntry:input-purpose) that allow input methods to fine-tune their behaviour. The purpose of this text field. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN is independent from setting #GtkEntry:visibility. The invisible character is used when masking entry contents (in \"password mode\")"). When it is not explicitly set with the #GtkEntry:invisible-char property, GTK+ determines the character to use from a list of possible candidates, depending on availability in the current font. This style property allows the theme to prepend a character to the list of candidates. Whether the invisible char has been set for the #GtkEntry. The desired maximum width of the entry, in characters. If this property is set to -1, the width will be calculated automatically. If text is overwritten when typing in the #GtkEntry. The text that will be displayed in the #GtkEntry when it is empty and unfocused. If :populate-all is %TRUE, the #GtkEntry::populate-popup signal is also emitted for touch popups. Whether the primary icon is activatable. GTK+ emits the #GtkEntry::icon-press and #GtkEntry::icon-release signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes. The #GIcon to use for the primary icon for the entry. The icon name to use for the primary icon for the entry. A pixbuf to use as the primary icon for the entry. Whether the primary icon is sensitive. An insensitive icon appears grayed out. GTK+ does not emit the #GtkEntry::icon-press and #GtkEntry::icon-release signals and does not allow DND from insensitive icons. An icon should be set insensitive if the action that would trigger when clicked is currently not available. The stock id to use for the primary icon for the entry. Use #GtkEntry:primary-icon-name instead. The representation which is used for the primary icon of the entry. The contents of the tooltip on the primary icon, which is marked up with the [Pango text markup language][PangoMarkupFormat]. Also see gtk_entry_set_icon_tooltip_markup(). The contents of the tooltip on the primary icon. Also see gtk_entry_set_icon_tooltip_text(). The current fraction of the task that's been completed. The fraction of total entry width to move the progress bouncing block for each call to gtk_entry_progress_pulse(). Whether the secondary icon is activatable. GTK+ emits the #GtkEntry::icon-press and #GtkEntry::icon-release signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes. The #GIcon to use for the secondary icon for the entry. The icon name to use for the secondary icon for the entry. An pixbuf to use as the secondary icon for the entry. Whether the secondary icon is sensitive. An insensitive icon appears grayed out. GTK+ does not emit the #GtkEntry::icon-press and #GtkEntry::icon-release signals and does not allow DND from insensitive icons. An icon should be set insensitive if the action that would trigger when clicked is currently not available. The stock id to use for the secondary icon for the entry. Use #GtkEntry:secondary-icon-name instead. The representation which is used for the secondary icon of the entry. The contents of the tooltip on the secondary icon, which is marked up with the [Pango text markup language][PangoMarkupFormat]. Also see gtk_entry_set_icon_tooltip_markup(). The contents of the tooltip on the secondary icon. Also see gtk_entry_set_icon_tooltip_text(). Which kind of shadow to draw around the entry when #GtkEntry:has-frame is set to %TRUE. Use CSS to determine the style of the border; the value of this style property is ignored. The length of the text in the #GtkEntry. When %TRUE, pasted multi-line text is truncated to the first line. The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts. The ::activate signal is emitted when the user hits the Enter key. While this signal is used as a [keybinding signal][GtkBindingSignal], it is also commonly used by applications to intercept activation of entries. The default bindings for this signal are all forms of the Enter key. The ::backspace signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. The default bindings for this signal are Backspace and Shift-Backspace. The ::copy-clipboard signal is a [keybinding signal][GtkBindingSignal] which gets emitted to copy the selection to the clipboard. The default bindings for this signal are Ctrl-c and Ctrl-Insert. The ::cut-clipboard signal is a [keybinding signal][GtkBindingSignal] which gets emitted to cut the selection to the clipboard. The default bindings for this signal are Ctrl-x and Shift-Delete. The ::delete-from-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a text deletion. If the @type is %GTK_DELETE_CHARS, GTK+ deletes the selection if there is one, otherwise it deletes the requested number of characters. The default bindings for this signal are Delete for deleting a character and Ctrl-Delete for deleting a word. the granularity of the deletion, as a #GtkDeleteType the number of @type units to delete The ::icon-press signal is emitted when an activatable icon is clicked. The position of the clicked icon the button press event The ::icon-release signal is emitted on the button release from a mouse click over an activatable icon. The position of the clicked icon the button release event The ::insert-at-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates the insertion of a fixed string at the cursor. This signal has no default bindings. the string to insert The ::insert-emoji signal is a [keybinding signal][GtkBindingSignal] which gets emitted to present the Emoji chooser for the @entry. The default bindings for this signal are Ctrl-. and Ctrl-; The ::move-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a cursor movement. If the cursor is not visible in @entry, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifer does not. There are too many key combinations to list them all here. - Arrow keys move by individual characters/lines - Ctrl-arrow key combinations move by words/paragraphs - Home/End keys move to the ends of the buffer the granularity of the move, as a #GtkMovementStep the number of @step units to move %TRUE if the move should extend the selection The ::paste-clipboard signal is a [keybinding signal][GtkBindingSignal] which gets emitted to paste the contents of the clipboard into the text view. The default bindings for this signal are Ctrl-v and Shift-Insert. The ::populate-popup signal gets emitted before showing the context menu of the entry. If you need to add items to the context menu, connect to this signal and append your items to the @widget, which will be a #GtkMenu in this case. If #GtkEntry:populate-all is %TRUE, this signal will also be emitted to populate touch popups. In this case, @widget will be a different container, e.g. a #GtkToolbar. The signal handler should not make assumptions about the type of @widget. the container that is being populated If an input method is used, the typed text will not immediately be committed to the buffer. So if you are interested in the text, connect to this signal. the current preedit string The ::toggle-overwrite signal is a [keybinding signal][GtkBindingSignal] which gets emitted to toggle the overwrite mode of the entry. The default bindings for this signal is Insert. The #GtkEntryBuffer class contains the actual text displayed in a #GtkEntry widget. A single #GtkEntryBuffer object can be shared by multiple #GtkEntry widgets which will then share the same text content, but not the cursor position, visibility attributes, icon etc. #GtkEntryBuffer may be derived from. Such a derived class might allow text to be stored in an alternate location, such as non-pageable memory, useful in the case of important passwords. Or a derived class could integrate with an application’s concept of undo/redo. Create a new GtkEntryBuffer object. Optionally, specify initial text to set in the buffer. A new GtkEntryBuffer object. initial buffer text, or %NULL number of characters in @initial_chars, or -1 Deletes a sequence of characters from the buffer. @n_chars characters are deleted starting at @position. If @n_chars is negative, then all characters until the end of the text are deleted. If @position or @n_chars are out of bounds, then they are coerced to sane values. Note that the positions are specified in characters, not bytes. The number of characters deleted. a #GtkEntryBuffer position at which to delete text number of characters to delete Retrieves the length in characters of the buffer. The number of characters in the buffer. a #GtkEntryBuffer Inserts @n_chars characters of @chars into the contents of the buffer, at position @position. If @n_chars is negative, then characters from chars will be inserted until a null-terminator is found. If @position or @n_chars are out of bounds, or the maximum buffer text length is exceeded, then they are coerced to sane values. Note that the position and length are in characters, not in bytes. The number of characters actually inserted. a #GtkEntryBuffer the position at which to insert text. the text to insert into the buffer. the length of the text in characters, or -1 Deletes a sequence of characters from the buffer. @n_chars characters are deleted starting at @position. If @n_chars is negative, then all characters until the end of the text are deleted. If @position or @n_chars are out of bounds, then they are coerced to sane values. Note that the positions are specified in characters, not bytes. The number of characters deleted. a #GtkEntryBuffer position at which to delete text number of characters to delete Used when subclassing #GtkEntryBuffer a #GtkEntryBuffer position at which text was deleted number of characters deleted Used when subclassing #GtkEntryBuffer a #GtkEntryBuffer position at which text was inserted text that was inserted number of characters inserted Retrieves the length in bytes of the buffer. See gtk_entry_buffer_get_length(). The byte length of the buffer. a #GtkEntryBuffer Retrieves the length in characters of the buffer. The number of characters in the buffer. a #GtkEntryBuffer Retrieves the maximum allowed length of the text in @buffer. See gtk_entry_buffer_set_max_length(). the maximum allowed number of characters in #GtkEntryBuffer, or 0 if there is no maximum. a #GtkEntryBuffer Retrieves the contents of the buffer. The memory pointer returned by this call will not change unless this object emits a signal, or is finalized. a pointer to the contents of the widget as a string. This string points to internally allocated storage in the buffer and must not be freed, modified or stored. a #GtkEntryBuffer Inserts @n_chars characters of @chars into the contents of the buffer, at position @position. If @n_chars is negative, then characters from chars will be inserted until a null-terminator is found. If @position or @n_chars are out of bounds, or the maximum buffer text length is exceeded, then they are coerced to sane values. Note that the position and length are in characters, not in bytes. The number of characters actually inserted. a #GtkEntryBuffer the position at which to insert text. the text to insert into the buffer. the length of the text in characters, or -1 Sets the maximum allowed length of the contents of the buffer. If the current contents are longer than the given length, then they will be truncated to fit. a #GtkEntryBuffer the maximum length of the entry buffer, or 0 for no maximum. (other than the maximum length of entries.) The value passed in will be clamped to the range 0-65536. Sets the text in the buffer. This is roughly equivalent to calling gtk_entry_buffer_delete_text() and gtk_entry_buffer_insert_text(). Note that @n_chars is in characters, not in bytes. a #GtkEntryBuffer the new text the number of characters in @text, or -1 The length (in characters) of the text in buffer. The maximum length (in characters) of the text in the buffer. The contents of the buffer. This signal is emitted after text is deleted from the buffer. the position the text was deleted at. The number of characters that were deleted. This signal is emitted after text is inserted into the buffer. the position the text was inserted at. The text that was inserted. The number of characters that were inserted. The number of characters in the buffer. a #GtkEntryBuffer The number of characters actually inserted. a #GtkEntryBuffer the position at which to insert text. the text to insert into the buffer. the length of the text in characters, or -1 The number of characters deleted. a #GtkEntryBuffer position at which to delete text number of characters to delete Class structure for #GtkEntry. All virtual functions have a default implementation. Derived classes may set the virtual function pointers for the signal handlers to %NULL, but must keep @get_text_area_size and @get_frame_size non-%NULL; either use the default implementation, or provide a custom one. The parent class. Class handler for the #GtkEntry::populate-popup signal. If non-%NULL, this will be called to add additional entries to the context menu when it is displayed. Class handler for the #GtkEntry::activate signal. The default implementation calls gtk_window_activate_default() on the entry’s top-level window. Class handler for the #GtkEntry::move-cursor signal. The default implementation specifies the standard #GtkEntry cursor movement behavior. Class handler for the #GtkEntry::insert-at-cursor signal. The default implementation inserts text at the cursor. Class handler for the #GtkEntry::delete-from-cursor signal. The default implementation deletes the selection or the specified number of characters or words. Class handler for the #GtkEntry::backspace signal. The default implementation deletes the selection or a single character or word. Class handler for the #GtkEntry::cut-clipboard signal. The default implementation cuts the selection, if one exists. Class handler for the #GtkEntry::copy-clipboard signal. The default implementation copies the selection, if one exists. Class handler for the #GtkEntry::paste-clipboard signal. The default implementation pastes at the current cursor position or over the current selection if one exists. Class handler for the #GtkEntry::toggle-overwrite signal. The default implementation toggles overwrite mode and blinks the cursor. Calculate the size of the text area, which is its allocated width and requested height, minus space for margins and borders. This virtual function must be non-%NULL. Calculate the size of the text area frame, which is its allocated width and requested height, minus space for margins and borders, and taking baseline and text height into account. This virtual function must be non-%NULL. #GtkEntryCompletion is an auxiliary object to be used in conjunction with #GtkEntry to provide the completion functionality. It implements the #GtkCellLayout interface, to allow the user to add extra cells to the #GtkTreeView with completion matches. “Completion functionality” means that when the user modifies the text in the entry, #GtkEntryCompletion checks which rows in the model match the current content of the entry, and displays a list of matches. By default, the matching is done by comparing the entry text case-insensitively against the text column of the model (see gtk_entry_completion_set_text_column()), but this can be overridden with a custom match function (see gtk_entry_completion_set_match_func()). When the user selects a completion, the content of the entry is updated. By default, the content of the entry is replaced by the text column of the model, but this can be overridden by connecting to the #GtkEntryCompletion::match-selected signal and updating the entry in the signal handler. Note that you should return %TRUE from the signal handler to suppress the default behaviour. To add completion functionality to an entry, use gtk_entry_set_completion(). In addition to regular completion matches, which will be inserted into the entry when they are selected, #GtkEntryCompletion also allows to display “actions” in the popup window. Their appearance is similar to menuitems, to differentiate them clearly from completion strings. When an action is selected, the #GtkEntryCompletion::action-activated signal is emitted. GtkEntryCompletion uses a #GtkTreeModelFilter model to represent the subset of the entire model that is currently matching. While the GtkEntryCompletion signals #GtkEntryCompletion::match-selected and #GtkEntryCompletion::cursor-on-match take the original model and an iter pointing to that model as arguments, other callbacks and signals (such as #GtkCellLayoutDataFuncs or #GtkCellArea::apply-attributes) will generally take the filter model as argument. As long as you are only calling gtk_tree_model_get(), this will make no difference to you. If for some reason, you need the original model, use gtk_tree_model_filter_get_model(). Don’t forget to use gtk_tree_model_filter_convert_iter_to_child_iter() to obtain a matching iter. Creates a new #GtkEntryCompletion object. A newly created #GtkEntryCompletion object Creates a new #GtkEntryCompletion object using the specified @area to layout cells in the underlying #GtkTreeViewColumn for the drop-down menu. A newly created #GtkEntryCompletion object the #GtkCellArea used to layout cells Requests a completion operation, or in other words a refiltering of the current list with completions, using the current key. The completion list view will be updated accordingly. a #GtkEntryCompletion Computes the common prefix that is shared by all rows in @completion that start with @key. If no row matches @key, %NULL will be returned. Note that a text column must have been set for this function to work, see gtk_entry_completion_set_text_column() for details. The common prefix all rows starting with @key or %NULL if no row matches @key. the entry completion The text to complete for Deletes the action at @index_ from @completion’s action list. Note that @index_ is a relative position and the position of an action may have changed since it was inserted. a #GtkEntryCompletion the index of the item to delete Get the original text entered by the user that triggered the completion or %NULL if there’s no completion ongoing. the prefix for the current completion a #GtkEntryCompletion Gets the entry @completion has been attached to. The entry @completion has been attached to a #GtkEntryCompletion Returns whether the common prefix of the possible completions should be automatically inserted in the entry. %TRUE if inline completion is turned on a #GtkEntryCompletion Returns %TRUE if inline-selection mode is turned on. %TRUE if inline-selection mode is on a #GtkEntryCompletion Returns the minimum key length as set for @completion. The currently used minimum key length a #GtkEntryCompletion Returns the model the #GtkEntryCompletion is using as data source. Returns %NULL if the model is unset. A #GtkTreeModel, or %NULL if none is currently being used a #GtkEntryCompletion Returns whether the completions should be presented in a popup window. %TRUE if popup completion is turned on a #GtkEntryCompletion Returns whether the completion popup window will be resized to the width of the entry. %TRUE if the popup window will be resized to the width of the entry a #GtkEntryCompletion Returns whether the completion popup window will appear even if there is only a single match. %TRUE if the popup window will appear regardless of the number of matches a #GtkEntryCompletion Returns the column in the model of @completion to get strings from. the column containing the strings a #GtkEntryCompletion Inserts an action in @completion’s action item list at position @index_ with markup @markup. a #GtkEntryCompletion the index of the item to insert markup of the item to insert Inserts an action in @completion’s action item list at position @index_ with text @text. If you want the action item to have markup, use gtk_entry_completion_insert_action_markup(). Note that @index_ is a relative position in the list of actions and the position of an action can change when deleting a different action. a #GtkEntryCompletion the index of the item to insert text of the item to insert Requests a prefix insertion. a #GtkEntryCompletion Sets whether the common prefix of the possible completions should be automatically inserted in the entry. a #GtkEntryCompletion %TRUE to do inline completion Sets whether it is possible to cycle through the possible completions inside the entry. a #GtkEntryCompletion %TRUE to do inline selection Sets the match function for @completion to be @func. The match function is used to determine if a row should or should not be in the completion list. a #GtkEntryCompletion the #GtkEntryCompletionMatchFunc to use user data for @func destroy notify for @func_data. Requires the length of the search key for @completion to be at least @length. This is useful for long lists, where completing using a small key takes a lot of time and will come up with meaningless results anyway (ie, a too large dataset). a #GtkEntryCompletion the minimum length of the key in order to start completing Sets the model for a #GtkEntryCompletion. If @completion already has a model set, it will remove it before setting the new model. If model is %NULL, then it will unset the model. a #GtkEntryCompletion the #GtkTreeModel Sets whether the completions should be presented in a popup window. a #GtkEntryCompletion %TRUE to do popup completion Sets whether the completion popup window will be resized to be the same width as the entry. a #GtkEntryCompletion %TRUE to make the width of the popup the same as the entry Sets whether the completion popup window will appear even if there is only a single match. You may want to set this to %FALSE if you are using [inline completion][GtkEntryCompletion--inline-completion]. a #GtkEntryCompletion %TRUE if the popup should appear even for a single match Convenience function for setting up the most used case of this code: a completion list with just strings. This function will set up @completion to have a list displaying all (and just) strings in the completion list, and to get those strings from @column in the model of @completion. This functions creates and adds a #GtkCellRendererText for the selected column. If you need to set the text column, but don't want the cell renderer, use g_object_set() to set the #GtkEntryCompletion:text-column property directly. a #GtkEntryCompletion the column in the model of @completion to get strings from The #GtkCellArea used to layout cell renderers in the treeview column. If no area is specified when creating the entry completion with gtk_entry_completion_new_with_area() a horizontally oriented #GtkCellAreaBox will be used. Determines whether the common prefix of the possible completions should be inserted automatically in the entry. Note that this requires text-column to be set, even if you are using a custom match function. Determines whether the possible completions on the popup will appear in the entry as you navigate through them. Determines whether the possible completions should be shown in a popup window. Determines whether the completions popup window will be resized to the width of the entry. Determines whether the completions popup window will shown for a single possible completion. You probably want to set this to %FALSE if you are using [inline completion][GtkEntryCompletion--inline-completion]. The column of the model containing the strings. Note that the strings must be UTF-8. Gets emitted when an action is activated. the index of the activated action Gets emitted when a match from the cursor is on a match of the list. The default behaviour is to replace the contents of the entry with the contents of the text column in the row pointed to by @iter. Note that @model is the model that was passed to gtk_entry_completion_set_model(). %TRUE if the signal has been handled the #GtkTreeModel containing the matches a #GtkTreeIter positioned at the selected match Gets emitted when the inline autocompletion is triggered. The default behaviour is to make the entry display the whole prefix and select the newly inserted part. Applications may connect to this signal in order to insert only a smaller part of the @prefix into the entry - e.g. the entry used in the #GtkFileChooser inserts only the part of the prefix up to the next '/'. %TRUE if the signal has been handled the common prefix of all possible completions Gets emitted when a match from the list is selected. The default behaviour is to replace the contents of the entry with the contents of the text column in the row pointed to by @iter. Note that @model is the model that was passed to gtk_entry_completion_set_model(). %TRUE if the signal has been handled the #GtkTreeModel containing the matches a #GtkTreeIter positioned at the selected match Gets emitted when the filter model has zero number of rows in completion_complete method. (In other words when GtkEntryCompletion is out of suggestions) A function which decides whether the row indicated by @iter matches a given @key, and should be displayed as a possible completion for @key. Note that @key is normalized and case-folded (see g_utf8_normalize() and g_utf8_casefold()). If this is not appropriate, match functions have access to the unmodified key via `gtk_entry_get_text (GTK_ENTRY (gtk_entry_completion_get_entry ()))`. %TRUE if @iter should be displayed as a possible completion for @key the #GtkEntryCompletion the string to match, normalized and case-folded a #GtkTreeIter indicating the row to match user data given to gtk_entry_completion_set_match_func() Specifies the side of the entry at which an icon is placed. At the beginning of the entry (depending on the text direction). At the end of the entry (depending on the text direction). The #GtkEventBox widget is a subclass of #GtkBin which also has its own window. It is useful since it allows you to catch events for widgets which do not have their own window. Creates a new #GtkEventBox. a new #GtkEventBox Returns whether the event box window is above or below the windows of its child. See gtk_event_box_set_above_child() for details. %TRUE if the event box window is above the window of its child a #GtkEventBox Returns whether the event box has a visible window. See gtk_event_box_set_visible_window() for details. %TRUE if the event box window is visible a #GtkEventBox Set whether the event box window is positioned above the windows of its child, as opposed to below it. If the window is above, all events inside the event box will go to the event box. If the window is below, events in windows of child widgets will first got to that widget, and then to its parents. The default is to keep the window below the child. a #GtkEventBox %TRUE if the event box window is above its child Set whether the event box uses a visible or invisible child window. The default is to use visible windows. In an invisible window event box, the window that the event box creates is a %GDK_INPUT_ONLY window, which means that it is invisible and only serves to receive events. A visible window event box creates a visible (%GDK_INPUT_OUTPUT) window that acts as the parent window for all the widgets contained in the event box. You should generally make your event box invisible if you just want to trap events. Creating a visible window may cause artifacts that are visible to the user, especially if the user is using a theme with gradients or pixmaps. The main reason to create a non input-only event box is if you want to set the background to a different color or draw on it. There is one unexpected issue for an invisible event box that has its window below the child. (See gtk_event_box_set_above_child().) Since the input-only window is not an ancestor window of any windows that descendent widgets of the event box create, events on these windows aren’t propagated up by the windowing system, but only by GTK+. The practical effect of this is if an event isn’t in the event mask for the descendant window (see gtk_widget_add_events()), it won’t be received by the event box. This problem doesn’t occur for visible event boxes, because in that case, the event box window is actually the ancestor of the descendant windows, not just at the same place on the screen. a #GtkEventBox %TRUE to make the event box have a visible window The parent class. #GtkEventController is a base, low-level implementation for event controllers. Those react to a series of #GdkEvents, and possibly trigger actions as a consequence of those. Gets the propagation phase at which @controller handles events. the propagation phase a #GtkEventController Returns the #GtkWidget this controller relates to. a #GtkWidget a #GtkEventController Feeds an events into @controller, so it can be interpreted and the controller actions triggered. %TRUE if the event was potentially useful to trigger the controller action a #GtkEventController a #GdkEvent Resets the @controller to a clean state. Every interaction the controller did through #GtkEventController::handle-event will be dropped at this point. a #GtkEventController Sets the propagation phase at which a controller handles events. If @phase is %GTK_PHASE_NONE, no automatic event handling will be performed, but other additional gesture maintenance will. In that phase, the events can be managed by calling gtk_event_controller_handle_event(). a #GtkEventController a propagation phase The propagation phase at which this controller will handle events. The widget receiving the #GdkEvents that the controller will handle. #GtkEventControllerKey is an event controller meant for situations where you need access to key events. This object was added in 3.24. Gets the IM context of a key controller. the IM context a #GtkEventControllerKey This signal is emitted whenever a key is pressed. %TRUE if the key press was handled, %FALSE otherwise. the pressed key. the raw code of the pressed key. the bitmask, representing the state of modifier keys and pointer buttons. See #GdkModifierType. This signal is emitted whenever a key is released. the released key. the raw code of the released key. the bitmask, representing the state of modifier keys and pointer buttons. See #GdkModifierType. #GtkEventControllerMotion is an event controller meant for situations where you need to track the position of the pointer. This object was added in 3.24. Creates a new event controller that will handle motion events for the given @widget. a new #GtkEventControllerMotion a #GtkWidget Signals that the pointer has entered the widget. the x coordinate the y coordinate Signals that pointer has left the widget. Emitted when the pointer moves inside the widget. the x coordinate the y coordinate #GtkEventControllerScroll is an event controller meant to handle scroll events from mice and touchpads. It is capable of handling both discrete and continuous scroll events, abstracting them both on the #GtkEventControllerScroll::scroll signal (deltas in the discrete case are multiples of 1). In the case of continuous scroll events, #GtkEventControllerScroll encloses all #GtkEventControllerScroll::scroll events between two #GtkEventControllerScroll::scroll-begin and #GtkEventControllerScroll::scroll-end signals. The behavior of the event controller can be modified by the flags given at creation time, or modified at a later point through gtk_event_controller_scroll_set_flags() (e.g. because the scrolling conditions of the widget changed). The controller can be set up to emit motion for either/both vertical and horizontal scroll events through #GTK_EVENT_CONTROLLER_SCROLL_VERTICAL, #GTK_EVENT_CONTROLLER_SCROLL_HORIZONTAL and #GTK_EVENT_CONTROLLER_SCROLL_BOTH. If any axis is disabled, the respective #GtkEventControllerScroll::scroll delta will be 0. Vertical scroll events will be translated to horizontal motion for the devices incapable of horizontal scrolling. The event controller can also be forced to emit discrete events on all devices through #GTK_EVENT_CONTROLLER_SCROLL_DISCRETE. This can be used to implement discrete actions triggered through scroll events (e.g. switching across combobox options). The #GTK_EVENT_CONTROLLER_SCROLL_KINETIC flag toggles the emission of the #GtkEventControllerScroll::decelerate signal, emitted at the end of scrolling with two X/Y velocity arguments that are consistent with the motion that was received. This object was added in 3.24. Creates a new event controller that will handle scroll events for the given @widget. a new #GtkEventControllerScroll a #GtkWidget behavior flags Gets the flags conditioning the scroll controller behavior. the controller flags. a #GtkEventControllerScroll Sets the flags conditioning scroll controller behavior. a #GtkEventControllerScroll behavior flags The flags affecting event controller behavior Emitted after scroll is finished if the #GTK_EVENT_CONTROLLER_SCROLL_KINETIC flag is set. @vel_x and @vel_y express the initial velocity that was imprinted by the scroll events. @vel_x and @vel_y are expressed in pixels/ms. X velocity Y velocity Signals that the widget should scroll by the amount specified by @dx and @dy. X delta Y delta Signals that a new scrolling operation has begun. It will only be emitted on devices capable of it. Signals that a new scrolling operation has finished. It will only be emitted on devices capable of it. Describes the behavior of a #GtkEventControllerScroll. Don't emit scroll. Emit scroll with vertical deltas. Emit scroll with horizontal deltas. Only emit deltas that are multiples of 1. Emit #GtkEventControllerScroll::decelerate after continuous scroll finishes. Emit scroll on both axes. Describes the state of a #GdkEventSequence in a #GtkGesture. The sequence is handled, but not grabbed. The sequence is handled and grabbed. The sequence is denied. A #GtkExpander allows the user to hide or show its child by clicking on an expander triangle similar to the triangles used in a #GtkTreeView. Normally you use an expander as you would use any other descendant of #GtkBin; you create the child widget and use gtk_container_add() to add it to the expander. When the expander is toggled, it will take care of showing and hiding the child automatically. # Special Usage There are situations in which you may prefer to show and hide the expanded widget yourself, such as when you want to actually create the widget at expansion time. In this case, create a #GtkExpander but do not add a child to it. The expander widget has an #GtkExpander:expanded property which can be used to monitor its expansion state. You should watch this property with a signal connection as follows: |[<!-- language="C" --> static void expander_callback (GObject *object, GParamSpec *param_spec, gpointer user_data) { GtkExpander *expander; expander = GTK_EXPANDER (object); if (gtk_expander_get_expanded (expander)) { // Show or create widgets } else { // Hide or destroy widgets } } static void create_expander (void) { GtkWidget *expander = gtk_expander_new_with_mnemonic ("_More Options"); g_signal_connect (expander, "notify::expanded", G_CALLBACK (expander_callback), NULL); // ... } ]| # GtkExpander as GtkBuildable The GtkExpander implementation of the GtkBuildable interface supports placing a child in the label position by specifying “label” as the “type” attribute of a `<child>` element. A normal content child can be specified without specifying a `<child>` type attribute. An example of a UI definition fragment with GtkExpander: |[<!-- language="xml" --> <object class="GtkExpander"> <child type="label"> <object class="GtkLabel" id="expander-label"/> </child> <child> <object class="GtkEntry" id="expander-content"/> </child> </object> ]| # CSS nodes |[<!-- language="plain" --> expander ├── title │ ├── arrow │ ╰── <label widget> ╰── <child> ]| GtkExpander has three CSS nodes, the main node with the name expander, a subnode with name title and node below it with name arrow. The arrow of an expander that is showing its child gets the :checked pseudoclass added to it. Creates a new expander using @label as the text of the label. a new #GtkExpander widget. the text of the label Creates a new expander using @label as the text of the label. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button. a new #GtkExpander widget. the text of the label with an underscore in front of the mnemonic character Keybinding signal is emitted when the user hits the Enter key. Queries a #GtkExpander and returns its current state. Returns %TRUE if the child widget is revealed. See gtk_expander_set_expanded(). the current state of the expander a #GtkExpander Fetches the text from a label widget including any embedded underlines indicating mnemonics and Pango markup, as set by gtk_expander_set_label(). If the label text has not been set the return value will be %NULL. This will be the case if you create an empty button with gtk_button_new() to use as a container. Note that this function behaved differently in versions prior to 2.14 and used to return the label text stripped of embedded underlines indicating mnemonics and Pango markup. This problem can be avoided by fetching the label text directly from the label widget. The text of the label widget. This string is owned by the widget and must not be modified or freed. a #GtkExpander Returns whether the label widget will fill all available horizontal space allocated to @expander. %TRUE if the label widget will fill all available horizontal space a #GtkExpander Retrieves the label widget for the frame. See gtk_expander_set_label_widget(). the label widget, or %NULL if there is none a #GtkExpander Returns whether the expander will resize the toplevel widget containing the expander upon resizing and collpasing. the “resize toplevel” setting. a #GtkExpander Gets the value set by gtk_expander_set_spacing(). Use margins on the child instead. spacing between the expander and child a #GtkExpander Returns whether the label’s text is interpreted as marked up with the [Pango text markup language][PangoMarkupFormat]. See gtk_expander_set_use_markup(). %TRUE if the label’s text will be parsed for markup a #GtkExpander Returns whether an embedded underline in the expander label indicates a mnemonic. See gtk_expander_set_use_underline(). %TRUE if an embedded underline in the expander label indicates the mnemonic accelerator keys a #GtkExpander Sets the state of the expander. Set to %TRUE, if you want the child widget to be revealed, and %FALSE if you want the child widget to be hidden. a #GtkExpander whether the child widget is revealed Sets the text of the label of the expander to @label. This will also clear any previously set labels. a #GtkExpander a string Sets whether the label widget should fill all available horizontal space allocated to @expander. Note that this function has no effect since 3.20. a #GtkExpander %TRUE if the label should should fill all available horizontal space Set the label widget for the expander. This is the widget that will appear embedded alongside the expander arrow. a #GtkExpander the new label widget Sets whether the expander will resize the toplevel widget containing the expander upon resizing and collpasing. a #GtkExpander whether to resize the toplevel Sets the spacing field of @expander, which is the number of pixels to place between expander and the child. Use margins on the child instead. a #GtkExpander distance between the expander and child in pixels Sets whether the text of the label contains markup in [Pango’s text markup language][PangoMarkupFormat]. See gtk_label_set_markup(). a #GtkExpander %TRUE if the label’s text should be parsed for markup If true, an underline in the text of the expander label indicates the next character should be used for the mnemonic accelerator key. a #GtkExpander %TRUE if underlines in the text indicate mnemonics Whether the label widget should fill all available horizontal space. Note that this property is ignored since 3.20. When this property is %TRUE, the expander will resize the toplevel widget containing the expander upon expanding and collapsing. Space to put between the label and the child when the expander is expanded. This property is deprecated and ignored. Use margins on the child instead. The parent class. Keybinding signal is emitted when the user hits the Enter key. Used to specify the style of the expanders drawn by a #GtkTreeView. The style used for a collapsed subtree. Intermediate style used during animation. Intermediate style used during animation. The style used for an expanded subtree. #GtkFileChooser is an interface that can be implemented by file selection widgets. In GTK+, the main objects that implement this interface are #GtkFileChooserWidget, #GtkFileChooserDialog, and #GtkFileChooserButton. You do not need to write an object that implements the #GtkFileChooser interface unless you are trying to adapt an existing file selector to expose a standard programming interface. #GtkFileChooser allows for shortcuts to various places in the filesystem. In the default implementation these are displayed in the left pane. It may be a bit confusing at first that these shortcuts come from various sources and in various flavours, so lets explain the terminology here: - Bookmarks: are created by the user, by dragging folders from the right pane to the left pane, or by using the “Add”. Bookmarks can be renamed and deleted by the user. - Shortcuts: can be provided by the application. For example, a Paint program may want to add a shortcut for a Clipart folder. Shortcuts cannot be modified by the user. - Volumes: are provided by the underlying filesystem abstraction. They are the “roots” of the filesystem. # File Names and Encodings When the user is finished selecting files in a #GtkFileChooser, your program can get the selected names either as filenames or as URIs. For URIs, the normal escaping rules are applied if the URI contains non-ASCII characters. However, filenames are always returned in the character set specified by the `G_FILENAME_ENCODING` environment variable. Please see the GLib documentation for more details about this variable. This means that while you can pass the result of gtk_file_chooser_get_filename() to g_open() or g_fopen(), you may not be able to directly set it as the text of a #GtkLabel widget unless you convert it first to UTF-8, which all GTK+ widgets expect. You should use g_filename_to_utf8() to convert filenames into strings that can be passed to GTK+ widgets. # Adding a Preview Widget You can add a custom preview widget to a file chooser and then get notification about when the preview needs to be updated. To install a preview widget, use gtk_file_chooser_set_preview_widget(). Then, connect to the #GtkFileChooser::update-preview signal to get notified when you need to update the contents of the preview. Your callback should use gtk_file_chooser_get_preview_filename() to see what needs previewing. Once you have generated the preview for the corresponding file, you must call gtk_file_chooser_set_preview_widget_active() with a boolean flag that indicates whether your callback could successfully generate a preview. ## Example: Using a Preview Widget ## {#gtkfilechooser-preview} |[<!-- language="C" --> { GtkImage *preview; ... preview = gtk_image_new (); gtk_file_chooser_set_preview_widget (my_file_chooser, preview); g_signal_connect (my_file_chooser, "update-preview", G_CALLBACK (update_preview_cb), preview); } static void update_preview_cb (GtkFileChooser *file_chooser, gpointer data) { GtkWidget *preview; char *filename; GdkPixbuf *pixbuf; gboolean have_preview; preview = GTK_WIDGET (data); filename = gtk_file_chooser_get_preview_filename (file_chooser); pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL); have_preview = (pixbuf != NULL); g_free (filename); gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf); if (pixbuf) g_object_unref (pixbuf); gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview); } ]| # Adding Extra Widgets You can add extra widgets to a file chooser to provide options that are not present in the default design. For example, you can add a toggle button to give the user the option to open a file in read-only mode. You can use gtk_file_chooser_set_extra_widget() to insert additional widgets in a file chooser. An example for adding extra widgets: |[<!-- language="C" --> GtkWidget *toggle; ... toggle = gtk_check_button_new_with_label ("Open file read-only"); gtk_widget_show (toggle); gtk_file_chooser_set_extra_widget (my_file_chooser, toggle); } ]| If you want to set more than one extra widget in the file chooser, you can a container such as a #GtkBox or a #GtkGrid and include your widgets in it. Then, set the container as the whole extra widget. Adds a 'choice' to the file chooser. This is typically implemented as a combobox or, for boolean choices, as a checkbutton. You can select a value using gtk_file_chooser_set_choice() before the dialog is shown, and you can obtain the user-selected value in the ::response signal handler using gtk_file_chooser_get_choice(). Compare gtk_file_chooser_set_extra_widget(). a #GtkFileChooser id for the added choice user-visible label for the added choice ids for the options of the choice, or %NULL for a boolean choice user-visible labels for the options, must be the same length as @options Adds @filter to the list of filters that the user can select between. When a filter is selected, only files that are passed by that filter are displayed. Note that the @chooser takes ownership of the filter, so you have to ref and sink it if you want to keep a reference. a #GtkFileChooser a #GtkFileFilter Adds a folder to be displayed with the shortcut folders in a file chooser. Note that shortcut folders do not get saved, as they are provided by the application. For example, you can use this to add a “/usr/share/mydrawprogram/Clipart” folder to the volume list. %TRUE if the folder could be added successfully, %FALSE otherwise. In the latter case, the @error will be set as appropriate. a #GtkFileChooser filename of the folder to add Adds a folder URI to be displayed with the shortcut folders in a file chooser. Note that shortcut folders do not get saved, as they are provided by the application. For example, you can use this to add a “file:///usr/share/mydrawprogram/Clipart” folder to the volume list. %TRUE if the folder could be added successfully, %FALSE otherwise. In the latter case, the @error will be set as appropriate. a #GtkFileChooser URI of the folder to add Gets the type of operation that the file chooser is performing; see gtk_file_chooser_set_action(). the action that the file selector is performing a #GtkFileChooser Gets the currently selected option in the 'choice' with the given ID. the ID of the currenly selected option a #GtkFileChooser the ID of the choice to get Gets whether file choser will offer to create new folders. See gtk_file_chooser_set_create_folders(). %TRUE if the Create Folder button should be displayed. a #GtkFileChooser Gets the current folder of @chooser as a local filename. See gtk_file_chooser_set_current_folder(). Note that this is the folder that the file chooser is currently displaying (e.g. "/home/username/Documents"), which is not the same as the currently-selected folder if the chooser is in %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER mode (e.g. "/home/username/Documents/selected-folder/". To get the currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the usual way to get the selection. the full path of the current folder, or %NULL if the current path cannot be represented as a local filename. Free with g_free(). This function will also return %NULL if the file chooser was unable to load the last folder that was requested from it; for example, as would be for calling gtk_file_chooser_set_current_folder() on a nonexistent folder. a #GtkFileChooser Gets the current folder of @chooser as #GFile. See gtk_file_chooser_get_current_folder_uri(). the #GFile for the current folder. a #GtkFileChooser Gets the current folder of @chooser as an URI. See gtk_file_chooser_set_current_folder_uri(). Note that this is the folder that the file chooser is currently displaying (e.g. "file:///home/username/Documents"), which is not the same as the currently-selected folder if the chooser is in %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER mode (e.g. "file:///home/username/Documents/selected-folder/". To get the currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the usual way to get the selection. the URI for the current folder. Free with g_free(). This function will also return %NULL if the file chooser was unable to load the last folder that was requested from it; for example, as would be for calling gtk_file_chooser_set_current_folder_uri() on a nonexistent folder. a #GtkFileChooser Gets the current name in the file selector, as entered by the user in the text entry for “Name”. This is meant to be used in save dialogs, to get the currently typed filename when the file itself does not exist yet. For example, an application that adds a custom extra widget to the file chooser for “file format” may want to change the extension of the typed filename based on the chosen format, say, from “.jpg” to “.png”. The raw text from the file chooser’s “Name” entry. Free this with g_free(). Note that this string is not a full pathname or URI; it is whatever the contents of the entry are. Note also that this string is in UTF-8 encoding, which is not necessarily the system’s encoding for filenames. a #GtkFileChooser Queries whether a file chooser is set to confirm for overwriting when the user types a file name that already exists. %TRUE if the file chooser will present a confirmation dialog; %FALSE otherwise. a #GtkFileChooser Gets the current extra widget; see gtk_file_chooser_set_extra_widget(). the current extra widget, or %NULL a #GtkFileChooser Gets the #GFile for the currently selected file in the file selector. If multiple files are selected, one of the files will be returned at random. If the file chooser is in folder mode, this function returns the selected folder. a selected #GFile. You own the returned file; use g_object_unref() to release it. a #GtkFileChooser Gets the filename for the currently selected file in the file selector. The filename is returned as an absolute path. If multiple files are selected, one of the filenames will be returned at random. If the file chooser is in folder mode, this function returns the selected folder. The currently selected filename, or %NULL if no file is selected, or the selected file can't be represented with a local filename. Free with g_free(). a #GtkFileChooser Lists all the selected files and subfolders in the current folder of @chooser. The returned names are full absolute paths. If files in the current folder cannot be represented as local filenames they will be ignored. (See gtk_file_chooser_get_uris()) a #GSList containing the filenames of all selected files and subfolders in the current folder. Free the returned list with g_slist_free(), and the filenames with g_free(). a #GtkFileChooser Lists all the selected files and subfolders in the current folder of @chooser as #GFile. An internal function, see gtk_file_chooser_get_uris(). a #GSList containing a #GFile for each selected file and subfolder in the current folder. Free the returned list with g_slist_free(), and the files with g_object_unref(). a #GtkFileChooser Gets the current filter; see gtk_file_chooser_set_filter(). the current filter, or %NULL a #GtkFileChooser Gets whether only local files can be selected in the file selector. See gtk_file_chooser_set_local_only() %TRUE if only local files can be selected. a #GtkFileChooser Gets the #GFile that should be previewed in a custom preview Internal function, see gtk_file_chooser_get_preview_uri(). the #GFile for the file to preview, or %NULL if no file is selected. Free with g_object_unref(). a #GtkFileChooser Gets the filename that should be previewed in a custom preview widget. See gtk_file_chooser_set_preview_widget(). the filename to preview, or %NULL if no file is selected, or if the selected file cannot be represented as a local filename. Free with g_free() a #GtkFileChooser Gets the URI that should be previewed in a custom preview widget. See gtk_file_chooser_set_preview_widget(). the URI for the file to preview, or %NULL if no file is selected. Free with g_free(). a #GtkFileChooser Gets the current preview widget; see gtk_file_chooser_set_preview_widget(). the current preview widget, or %NULL a #GtkFileChooser Gets whether the preview widget set by gtk_file_chooser_set_preview_widget() should be shown for the current filename. See gtk_file_chooser_set_preview_widget_active(). %TRUE if the preview widget is active for the current filename. a #GtkFileChooser Gets whether multiple files can be selected in the file selector. See gtk_file_chooser_set_select_multiple(). %TRUE if multiple files can be selected. a #GtkFileChooser Gets whether hidden files and folders are displayed in the file selector. See gtk_file_chooser_set_show_hidden(). %TRUE if hidden files and folders are displayed. a #GtkFileChooser Gets the URI for the currently selected file in the file selector. If multiple files are selected, one of the filenames will be returned at random. If the file chooser is in folder mode, this function returns the selected folder. The currently selected URI, or %NULL if no file is selected. If gtk_file_chooser_set_local_only() is set to %TRUE (the default) a local URI will be returned for any FUSE locations. Free with g_free() a #GtkFileChooser Lists all the selected files and subfolders in the current folder of @chooser. The returned names are full absolute URIs. a #GSList containing the URIs of all selected files and subfolders in the current folder. Free the returned list with g_slist_free(), and the filenames with g_free(). a #GtkFileChooser Gets whether a stock label should be drawn with the name of the previewed file. See gtk_file_chooser_set_use_preview_label(). %TRUE if the file chooser is set to display a label with the name of the previewed file, %FALSE otherwise. a #GtkFileChooser Lists the current set of user-selectable filters; see gtk_file_chooser_add_filter(), gtk_file_chooser_remove_filter(). a #GSList containing the current set of user selectable filters. The contents of the list are owned by GTK+, but you must free the list itself with g_slist_free() when you are done with it. a #GtkFileChooser Queries the list of shortcut folders in the file chooser, as set by gtk_file_chooser_add_shortcut_folder_uri(). A list of folder URIs, or %NULL if there are no shortcut folders. Free the returned list with g_slist_free(), and the URIs with g_free(). a #GtkFileChooser Queries the list of shortcut folders in the file chooser, as set by gtk_file_chooser_add_shortcut_folder(). A list of folder filenames, or %NULL if there are no shortcut folders. Free the returned list with g_slist_free(), and the filenames with g_free(). a #GtkFileChooser Removes a 'choice' that has been added with gtk_file_chooser_add_choice(). a #GtkFileChooser the ID of the choice to remove Removes @filter from the list of filters that the user can select between. a #GtkFileChooser a #GtkFileFilter Removes a folder from a file chooser’s list of shortcut folders. %TRUE if the operation succeeds, %FALSE otherwise. In the latter case, the @error will be set as appropriate. See also: gtk_file_chooser_add_shortcut_folder() a #GtkFileChooser filename of the folder to remove Removes a folder URI from a file chooser’s list of shortcut folders. %TRUE if the operation succeeds, %FALSE otherwise. In the latter case, the @error will be set as appropriate. See also: gtk_file_chooser_add_shortcut_folder_uri() a #GtkFileChooser URI of the folder to remove Selects all the files in the current folder of a file chooser. a #GtkFileChooser Selects the file referred to by @file. An internal function. See _gtk_file_chooser_select_uri(). Not useful. a #GtkFileChooser the file to select Selects a filename. If the file name isn’t in the current folder of @chooser, then the current folder of @chooser will be changed to the folder containing @filename. Not useful. See also: gtk_file_chooser_set_filename() a #GtkFileChooser the filename to select Selects the file to by @uri. If the URI doesn’t refer to a file in the current folder of @chooser, then the current folder of @chooser will be changed to the folder containing @filename. Not useful. a #GtkFileChooser the URI to select Sets the type of operation that the chooser is performing; the user interface is adapted to suit the selected action. For example, an option to create a new folder might be shown if the action is %GTK_FILE_CHOOSER_ACTION_SAVE but not if the action is %GTK_FILE_CHOOSER_ACTION_OPEN. a #GtkFileChooser the action that the file selector is performing Selects an option in a 'choice' that has been added with gtk_file_chooser_add_choice(). For a boolean choice, the possible options are "true" and "false". a #GtkFileChooser the ID of the choice to set the ID of the option to select Sets whether file choser will offer to create new folders. This is only relevant if the action is not set to be %GTK_FILE_CHOOSER_ACTION_OPEN. a #GtkFileChooser %TRUE if the Create Folder button should be displayed Sets the current folder for @chooser from a local filename. The user will be shown the full contents of the current folder, plus user interface elements for navigating to other folders. In general, you should not use this function. See the [section on setting up a file chooser dialog][gtkfilechooserdialog-setting-up] for the rationale behind this. Not useful. a #GtkFileChooser the full path of the new current folder Sets the current folder for @chooser from a #GFile. Internal function, see gtk_file_chooser_set_current_folder_uri(). %TRUE if the folder could be changed successfully, %FALSE otherwise. a #GtkFileChooser the #GFile for the new folder Sets the current folder for @chooser from an URI. The user will be shown the full contents of the current folder, plus user interface elements for navigating to other folders. In general, you should not use this function. See the [section on setting up a file chooser dialog][gtkfilechooserdialog-setting-up] for the rationale behind this. %TRUE if the folder could be changed successfully, %FALSE otherwise. a #GtkFileChooser the URI for the new current folder Sets the current name in the file selector, as if entered by the user. Note that the name passed in here is a UTF-8 string rather than a filename. This function is meant for such uses as a suggested name in a “Save As...” dialog. You can pass “Untitled.doc” or a similarly suitable suggestion for the @name. If you want to preselect a particular existing file, you should use gtk_file_chooser_set_filename() or gtk_file_chooser_set_uri() instead. Please see the documentation for those functions for an example of using gtk_file_chooser_set_current_name() as well. a #GtkFileChooser the filename to use, as a UTF-8 string Sets whether a file chooser in %GTK_FILE_CHOOSER_ACTION_SAVE mode will present a confirmation dialog if the user types a file name that already exists. This is %FALSE by default. If set to %TRUE, the @chooser will emit the #GtkFileChooser::confirm-overwrite signal when appropriate. If all you need is the stock confirmation dialog, set this property to %TRUE. You can override the way confirmation is done by actually handling the #GtkFileChooser::confirm-overwrite signal; please refer to its documentation for the details. a #GtkFileChooser whether to confirm overwriting in save mode Sets an application-supplied widget to provide extra options to the user. a #GtkFileChooser widget for extra options Sets @file as the current filename for the file chooser, by changing to the file’s parent folder and actually selecting the file in list. If the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file’s base name will also appear in the dialog’s file name entry. If the file name isn’t in the current folder of @chooser, then the current folder of @chooser will be changed to the folder containing @filename. This is equivalent to a sequence of gtk_file_chooser_unselect_all() followed by gtk_file_chooser_select_filename(). Note that the file must exist, or nothing will be done except for the directory change. If you are implementing a save dialog, you should use this function if you already have a file name to which the user may save; for example, when the user opens an existing file and then does Save As... If you don’t have a file name already — for example, if the user just created a new file and is saving it for the first time, do not call this function. Instead, use something similar to this: |[<!-- language="C" --> if (document_is_new) { // the user just created a new document gtk_file_chooser_set_current_folder_file (chooser, default_file_for_saving); gtk_file_chooser_set_current_name (chooser, "Untitled document"); } else { // the user edited an existing document gtk_file_chooser_set_file (chooser, existing_file); } ]| Not useful. a #GtkFileChooser the #GFile to set as current Sets @filename as the current filename for the file chooser, by changing to the file’s parent folder and actually selecting the file in list; all other files will be unselected. If the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file’s base name will also appear in the dialog’s file name entry. Note that the file must exist, or nothing will be done except for the directory change. You should use this function only when implementing a save dialog for which you already have a file name to which the user may save. For example, when the user opens an existing file and then does Save As... to save a copy or a modified version. If you don’t have a file name already — for example, if the user just created a new file and is saving it for the first time, do not call this function. Instead, use something similar to this: |[<!-- language="C" --> if (document_is_new) { // the user just created a new document gtk_file_chooser_set_current_name (chooser, "Untitled document"); } else { // the user edited an existing document gtk_file_chooser_set_filename (chooser, existing_filename); } ]| In the first case, the file chooser will present the user with useful suggestions as to where to save his new file. In the second case, the file’s existing location is already known, so the file chooser will use it. Not useful. a #GtkFileChooser the filename to set as current Sets the current filter; only the files that pass the filter will be displayed. If the user-selectable list of filters is non-empty, then the filter should be one of the filters in that list. Setting the current filter when the list of filters is empty is useful if you want to restrict the displayed set of files without letting the user change it. a #GtkFileChooser a #GtkFileFilter Sets whether only local files can be selected in the file selector. If @local_only is %TRUE (the default), then the selected file or files are guaranteed to be accessible through the operating systems native file system and therefore the application only needs to worry about the filename functions in #GtkFileChooser, like gtk_file_chooser_get_filename(), rather than the URI functions like gtk_file_chooser_get_uri(), On some systems non-native files may still be available using the native filesystem via a userspace filesystem (FUSE). a #GtkFileChooser %TRUE if only local files can be selected Sets an application-supplied widget to use to display a custom preview of the currently selected file. To implement a preview, after setting the preview widget, you connect to the #GtkFileChooser::update-preview signal, and call gtk_file_chooser_get_preview_filename() or gtk_file_chooser_get_preview_uri() on each change. If you can display a preview of the new file, update your widget and set the preview active using gtk_file_chooser_set_preview_widget_active(). Otherwise, set the preview inactive. When there is no application-supplied preview widget, or the application-supplied preview widget is not active, the file chooser will display no preview at all. a #GtkFileChooser widget for displaying preview. Sets whether the preview widget set by gtk_file_chooser_set_preview_widget() should be shown for the current filename. When @active is set to false, the file chooser may display an internally generated preview of the current file or it may display no preview at all. See gtk_file_chooser_set_preview_widget() for more details. a #GtkFileChooser whether to display the user-specified preview widget Sets whether multiple files can be selected in the file selector. This is only relevant if the action is set to be %GTK_FILE_CHOOSER_ACTION_OPEN or %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. a #GtkFileChooser %TRUE if multiple files can be selected. Sets whether hidden files and folders are displayed in the file selector. a #GtkFileChooser %TRUE if hidden files and folders should be displayed. Sets the file referred to by @uri as the current file for the file chooser, by changing to the URI’s parent folder and actually selecting the URI in the list. If the @chooser is %GTK_FILE_CHOOSER_ACTION_SAVE mode, the URI’s base name will also appear in the dialog’s file name entry. Note that the URI must exist, or nothing will be done except for the directory change. You should use this function only when implementing a save dialog for which you already have a file name to which the user may save. For example, when the user opens an existing file and then does Save As... to save a copy or a modified version. If you don’t have a file name already — for example, if the user just created a new file and is saving it for the first time, do not call this function. Instead, use something similar to this: |[<!-- language="C" --> if (document_is_new) { // the user just created a new document gtk_file_chooser_set_current_name (chooser, "Untitled document"); } else { // the user edited an existing document gtk_file_chooser_set_uri (chooser, existing_uri); } ]| In the first case, the file chooser will present the user with useful suggestions as to where to save his new file. In the second case, the file’s existing location is already known, so the file chooser will use it. Not useful. a #GtkFileChooser the URI to set as current Sets whether the file chooser should display a stock label with the name of the file that is being previewed; the default is %TRUE. Applications that want to draw the whole preview area themselves should set this to %FALSE and display the name themselves in their preview widget. See also: gtk_file_chooser_set_preview_widget() a #GtkFileChooser whether to display a stock label with the name of the previewed file Unselects all the files in the current folder of a file chooser. a #GtkFileChooser Unselects the file referred to by @file. If the file is not in the current directory, does not exist, or is otherwise not currently selected, does nothing. a #GtkFileChooser a #GFile Unselects a currently selected filename. If the filename is not in the current directory, does not exist, or is otherwise not currently selected, does nothing. a #GtkFileChooser the filename to unselect Unselects the file referred to by @uri. If the file is not in the current directory, does not exist, or is otherwise not currently selected, does nothing. a #GtkFileChooser the URI to unselect Whether a file chooser not in %GTK_FILE_CHOOSER_ACTION_OPEN mode will offer the user to create new folders. Whether a file chooser in %GTK_FILE_CHOOSER_ACTION_SAVE mode will present an overwrite confirmation dialog if the user selects a file name that already exists. This signal gets emitted whenever it is appropriate to present a confirmation dialog when the user has selected a file name that already exists. The signal only gets emitted when the file chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode. Most applications just need to turn on the #GtkFileChooser:do-overwrite-confirmation property (or call the gtk_file_chooser_set_do_overwrite_confirmation() function), and they will automatically get a stock confirmation dialog. Applications which need to customize this behavior should do that, and also connect to the #GtkFileChooser::confirm-overwrite signal. A signal handler for this signal must return a #GtkFileChooserConfirmation value, which indicates the action to take. If the handler determines that the user wants to select a different filename, it should return %GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN. If it determines that the user is satisfied with his choice of file name, it should return %GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME. On the other hand, if it determines that the stock confirmation dialog should be used, it should return %GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM. The following example illustrates this. ## Custom confirmation ## {#gtkfilechooser-confirmation} |[<!-- language="C" --> static GtkFileChooserConfirmation confirm_overwrite_callback (GtkFileChooser *chooser, gpointer data) { char *uri; uri = gtk_file_chooser_get_uri (chooser); if (is_uri_read_only (uri)) { if (user_wants_to_replace_read_only_file (uri)) return GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME; else return GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN; } else return GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM; // fall back to the default dialog } ... chooser = gtk_file_chooser_dialog_new (...); gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE); g_signal_connect (chooser, "confirm-overwrite", G_CALLBACK (confirm_overwrite_callback), NULL); if (gtk_dialog_run (chooser) == GTK_RESPONSE_ACCEPT) save_to_file (gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (chooser)); gtk_widget_destroy (chooser); ]| a #GtkFileChooserConfirmation value that indicates which action to take after emitting the signal. This signal is emitted when the current folder in a #GtkFileChooser changes. This can happen due to the user performing some action that changes folders, such as selecting a bookmark or visiting a folder on the file list. It can also happen as a result of calling a function to explicitly change the current folder in a file chooser. Normally you do not need to connect to this signal, unless you need to keep track of which folder a file chooser is showing. See also: gtk_file_chooser_set_current_folder(), gtk_file_chooser_get_current_folder(), gtk_file_chooser_set_current_folder_uri(), gtk_file_chooser_get_current_folder_uri(). This signal is emitted when the user "activates" a file in the file chooser. This can happen by double-clicking on a file in the file list, or by pressing `Enter`. Normally you do not need to connect to this signal. It is used internally by #GtkFileChooserDialog to know when to activate the default button in the dialog. See also: gtk_file_chooser_get_filename(), gtk_file_chooser_get_filenames(), gtk_file_chooser_get_uri(), gtk_file_chooser_get_uris(). This signal is emitted when there is a change in the set of selected files in a #GtkFileChooser. This can happen when the user modifies the selection with the mouse or the keyboard, or when explicitly calling functions to change the selection. Normally you do not need to connect to this signal, as it is easier to wait for the file chooser to finish running, and then to get the list of selected files using the functions mentioned below. See also: gtk_file_chooser_select_filename(), gtk_file_chooser_unselect_filename(), gtk_file_chooser_get_filename(), gtk_file_chooser_get_filenames(), gtk_file_chooser_select_uri(), gtk_file_chooser_unselect_uri(), gtk_file_chooser_get_uri(), gtk_file_chooser_get_uris(). This signal is emitted when the preview in a file chooser should be regenerated. For example, this can happen when the currently selected file changes. You should use this signal if you want your file chooser to have a preview widget. Once you have installed a preview widget with gtk_file_chooser_set_preview_widget(), you should update it when this signal is emitted. You can use the functions gtk_file_chooser_get_preview_filename() or gtk_file_chooser_get_preview_uri() to get the name of the file to preview. Your widget may not be able to preview all kinds of files; your callback must call gtk_file_chooser_set_preview_widget_active() to inform the file chooser about whether the preview was generated successfully or not. Please see the example code in [Using a Preview Widget][gtkfilechooser-preview]. See also: gtk_file_chooser_set_preview_widget(), gtk_file_chooser_set_preview_widget_active(), gtk_file_chooser_set_use_preview_label(), gtk_file_chooser_get_preview_filename(), gtk_file_chooser_get_preview_uri(). Describes whether a #GtkFileChooser is being used to open existing files or to save to a possibly new file. Indicates open mode. The file chooser will only let the user pick an existing file. Indicates save mode. The file chooser will let the user pick an existing file, or type in a new filename. Indicates an Open mode for selecting folders. The file chooser will let the user pick an existing folder. Indicates a mode for creating a new folder. The file chooser will let the user name an existing or new folder. The #GtkFileChooserButton is a widget that lets the user select a file. It implements the #GtkFileChooser interface. Visually, it is a file name with a button to bring up a #GtkFileChooserDialog. The user can then use that dialog to change the file associated with that button. This widget does not support setting the #GtkFileChooser:select-multiple property to %TRUE. ## Create a button to let the user select a file in /etc |[<!-- language="C" --> { GtkWidget *button; button = gtk_file_chooser_button_new (_("Select a file"), GTK_FILE_CHOOSER_ACTION_OPEN); gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (button), "/etc"); } ]| The #GtkFileChooserButton supports the #GtkFileChooserActions %GTK_FILE_CHOOSER_ACTION_OPEN and %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. > The #GtkFileChooserButton will ellipsize the label, and will thus > request little horizontal space. To give the button more space, > you should call gtk_widget_get_preferred_size(), > gtk_file_chooser_button_set_width_chars(), or pack the button in > such a way that other interface elements give space to the > widget. # CSS nodes GtkFileChooserButton has a CSS node with name “filechooserbutton”, containing a subnode for the internal button with name “button” and style class “.file”. Creates a new file-selecting button widget. a new button widget. the title of the browse dialog. the open mode for the widget. Creates a #GtkFileChooserButton widget which uses @dialog as its file-picking window. Note that @dialog must be a #GtkDialog (or subclass) which implements the #GtkFileChooser interface and must not have %GTK_DIALOG_DESTROY_WITH_PARENT set. Also note that the dialog needs to have its confirmative button added with response %GTK_RESPONSE_ACCEPT or %GTK_RESPONSE_OK in order for the button to take over the file selected in the dialog. a new button widget. the widget to use as dialog Signal emitted when the user selects a file. Returns whether the button grabs focus when it is clicked with the mouse. See gtk_file_chooser_button_set_focus_on_click(). Use gtk_widget_get_focus_on_click() instead %TRUE if the button grabs focus when it is clicked with the mouse. a #GtkFileChooserButton Retrieves the title of the browse dialog used by @button. The returned value should not be modified or freed. a pointer to the browse dialog’s title. the button widget to examine. Retrieves the width in characters of the @button widget’s entry and/or label. an integer width (in characters) that the button will use to size itself. the button widget to examine. Sets whether the button will grab focus when it is clicked with the mouse. Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard focus removed from the main area of the application. Use gtk_widget_set_focus_on_click() instead a #GtkFileChooserButton whether the button grabs focus when clicked with the mouse Modifies the @title of the browse dialog used by @button. the button widget to modify. the new browse dialog title. Sets the width (in characters) that @button will use to @n_chars. the button widget to examine. the new width, in characters. Instance of the #GtkFileChooserDialog associated with the button. Title to put on the #GtkFileChooserDialog associated with the button. The width of the entry and label inside the button, in characters. The ::file-set signal is emitted when the user selects a file. Note that this signal is only emitted when the user changes the file. The parent class. Signal emitted when the user selects a file. Used as a return value of handlers for the #GtkFileChooser::confirm-overwrite signal of a #GtkFileChooser. This value determines whether the file chooser will present the stock confirmation dialog, accept the user’s choice of a filename, or let the user choose another filename. The file chooser will present its stock dialog to confirm about overwriting an existing file. The file chooser will terminate and accept the user’s choice of a file name. The file chooser will continue running, so as to let the user select another file name. #GtkFileChooserDialog is a dialog box suitable for use with “File/Open” or “File/Save as” commands. This widget works by putting a #GtkFileChooserWidget inside a #GtkDialog. It exposes the #GtkFileChooser interface, so you can use all of the #GtkFileChooser functions on the file chooser dialog as well as those for #GtkDialog. Note that #GtkFileChooserDialog does not have any methods of its own. Instead, you should use the functions that work on a #GtkFileChooser. If you want to integrate well with the platform you should use the #GtkFileChooserNative API, which will use a platform-specific dialog if available and fall back to GtkFileChooserDialog otherwise. ## Typical usage ## {#gtkfilechooser-typical-usage} In the simplest of cases, you can the following code to use #GtkFileChooserDialog to select a file for opening: |[ GtkWidget *dialog; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN; gint res; dialog = gtk_file_chooser_dialog_new ("Open File", parent_window, action, _("_Cancel"), GTK_RESPONSE_CANCEL, _("_Open"), GTK_RESPONSE_ACCEPT, NULL); res = gtk_dialog_run (GTK_DIALOG (dialog)); if (res == GTK_RESPONSE_ACCEPT) { char *filename; GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog); filename = gtk_file_chooser_get_filename (chooser); open_file (filename); g_free (filename); } gtk_widget_destroy (dialog); ]| To use a dialog for saving, you can use this: |[ GtkWidget *dialog; GtkFileChooser *chooser; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE; gint res; dialog = gtk_file_chooser_dialog_new ("Save File", parent_window, action, _("_Cancel"), GTK_RESPONSE_CANCEL, _("_Save"), GTK_RESPONSE_ACCEPT, NULL); chooser = GTK_FILE_CHOOSER (dialog); gtk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE); if (user_edited_a_new_document) gtk_file_chooser_set_current_name (chooser, _("Untitled document")); else gtk_file_chooser_set_filename (chooser, existing_filename); res = gtk_dialog_run (GTK_DIALOG (dialog)); if (res == GTK_RESPONSE_ACCEPT) { char *filename; filename = gtk_file_chooser_get_filename (chooser); save_to_file (filename); g_free (filename); } gtk_widget_destroy (dialog); ]| ## Setting up a file chooser dialog ## {#gtkfilechooserdialog-setting-up} There are various cases in which you may need to use a #GtkFileChooserDialog: - To select a file for opening. Use #GTK_FILE_CHOOSER_ACTION_OPEN. - To save a file for the first time. Use #GTK_FILE_CHOOSER_ACTION_SAVE, and suggest a name such as “Untitled” with gtk_file_chooser_set_current_name(). - To save a file under a different name. Use #GTK_FILE_CHOOSER_ACTION_SAVE, and set the existing filename with gtk_file_chooser_set_filename(). - To choose a folder instead of a file. Use #GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. Note that old versions of the file chooser’s documentation suggested using gtk_file_chooser_set_current_folder() in various situations, with the intention of letting the application suggest a reasonable default folder. This is no longer considered to be a good policy, as now the file chooser is able to make good suggestions on its own. In general, you should only cause the file chooser to show a specific folder when it is appropriate to use gtk_file_chooser_set_filename(), i.e. when you are doing a Save As command and you already have a file saved somewhere. ## Response Codes ## {#gtkfilechooserdialog-responses} #GtkFileChooserDialog inherits from #GtkDialog, so buttons that go in its action area have response codes such as #GTK_RESPONSE_ACCEPT and #GTK_RESPONSE_CANCEL. For example, you could call gtk_file_chooser_dialog_new() as follows: |[ GtkWidget *dialog; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN; dialog = gtk_file_chooser_dialog_new ("Open File", parent_window, action, _("_Cancel"), GTK_RESPONSE_CANCEL, _("_Open"), GTK_RESPONSE_ACCEPT, NULL); ]| This will create buttons for “Cancel” and “Open” that use stock response identifiers from #GtkResponseType. For most dialog boxes you can use your own custom response codes rather than the ones in #GtkResponseType, but #GtkFileChooserDialog assumes that its “accept”-type action, e.g. an “Open” or “Save” button, will have one of the following response codes: - #GTK_RESPONSE_ACCEPT - #GTK_RESPONSE_OK - #GTK_RESPONSE_YES - #GTK_RESPONSE_APPLY This is because #GtkFileChooserDialog must intercept responses and switch to folders if appropriate, rather than letting the dialog terminate — the implementation uses these known response codes to know which responses can be blocked if appropriate. To summarize, make sure you use a [stock response code][gtkfilechooserdialog-responses] when you use #GtkFileChooserDialog to ensure proper operation. Creates a new #GtkFileChooserDialog. This function is analogous to gtk_dialog_new_with_buttons(). a new #GtkFileChooserDialog Title of the dialog, or %NULL Transient parent of the dialog, or %NULL Open or save mode for the dialog stock ID or text to go in the first button, or %NULL response ID for the first button, then additional (button, id) pairs, ending with %NULL These identify the various errors that can occur while calling #GtkFileChooser functions. Indicates that a file does not exist. Indicates a malformed filename. Indicates a duplicate path (e.g. when adding a bookmark). Indicates an incomplete hostname (e.g. "http://foo" without a slash after that). Registers an error quark for #GtkFileChooser if necessary. The error quark used for #GtkFileChooser errors. #GtkFileChooserNative is an abstraction of a dialog box suitable for use with “File/Open” or “File/Save as” commands. By default, this just uses a #GtkFileChooserDialog to implement the actual dialog. However, on certain platforms, such as Windows and macOS, the native platform file chooser is used instead. When the application is running in a sandboxed environment without direct filesystem access (such as Flatpak), #GtkFileChooserNative may call the proper APIs (portals) to let the user choose a file and make it available to the application. While the API of #GtkFileChooserNative closely mirrors #GtkFileChooserDialog, the main difference is that there is no access to any #GtkWindow or #GtkWidget for the dialog. This is required, as there may not be one in the case of a platform native dialog. Showing, hiding and running the dialog is handled by the #GtkNativeDialog functions. ## Typical usage ## {#gtkfilechoosernative-typical-usage} In the simplest of cases, you can the following code to use #GtkFileChooserDialog to select a file for opening: |[ GtkFileChooserNative *native; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN; gint res; native = gtk_file_chooser_native_new ("Open File", parent_window, action, "_Open", "_Cancel"); res = gtk_native_dialog_run (GTK_NATIVE_DIALOG (native)); if (res == GTK_RESPONSE_ACCEPT) { char *filename; GtkFileChooser *chooser = GTK_FILE_CHOOSER (native); filename = gtk_file_chooser_get_filename (chooser); open_file (filename); g_free (filename); } g_object_unref (native); ]| To use a dialog for saving, you can use this: |[ GtkFileChooserNative *native; GtkFileChooser *chooser; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE; gint res; native = gtk_file_chooser_native_new ("Save File", parent_window, action, "_Save", "_Cancel"); chooser = GTK_FILE_CHOOSER (native); gtk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE); if (user_edited_a_new_document) gtk_file_chooser_set_current_name (chooser, _("Untitled document")); else gtk_file_chooser_set_filename (chooser, existing_filename); res = gtk_native_dialog_run (GTK_NATIVE_DIALOG (native)); if (res == GTK_RESPONSE_ACCEPT) { char *filename; filename = gtk_file_chooser_get_filename (chooser); save_to_file (filename); g_free (filename); } g_object_unref (native); ]| For more information on how to best set up a file dialog, see #GtkFileChooserDialog. ## Response Codes ## {#gtkfilechooserdialognative-responses} #GtkFileChooserNative inherits from #GtkNativeDialog, which means it will return #GTK_RESPONSE_ACCEPT if the user accepted, and #GTK_RESPONSE_CANCEL if he pressed cancel. It can also return #GTK_RESPONSE_DELETE_EVENT if the window was unexpectedly closed. ## Differences from #GtkFileChooserDialog ## {#gtkfilechooserdialognative-differences} There are a few things in the GtkFileChooser API that are not possible to use with #GtkFileChooserNative, as such use would prohibit the use of a native dialog. There is no support for the signals that are emitted when the user navigates in the dialog, including: * #GtkFileChooser::current-folder-changed * #GtkFileChooser::selection-changed * #GtkFileChooser::file-activated * #GtkFileChooser::confirm-overwrite You can also not use the methods that directly control user navigation: * gtk_file_chooser_unselect_filename() * gtk_file_chooser_select_all() * gtk_file_chooser_unselect_all() If you need any of the above you will have to use #GtkFileChooserDialog directly. No operations that change the the dialog work while the dialog is visible. Set all the properties that are required before showing the dialog. ## Win32 details ## {#gtkfilechooserdialognative-win32} On windows the IFileDialog implementation (added in Windows Vista) is used. It supports many of the features that #GtkFileChooserDialog does, but there are some things it does not handle: * Extra widgets added with gtk_file_chooser_set_extra_widget(). * Use of custom previews by connecting to #GtkFileChooser::update-preview. * Any #GtkFileFilter added using a mimetype or custom filter. If any of these features are used the regular #GtkFileChooserDialog will be used in place of the native one. ## Portal details ## {#gtkfilechooserdialognative-portal} When the org.freedesktop.portal.FileChooser portal is available on the session bus, it is used to bring up an out-of-process file chooser. Depending on the kind of session the application is running in, this may or may not be a GTK+ file chooser. In this situation, the following things are not supported and will be silently ignored: * Extra widgets added with gtk_file_chooser_set_extra_widget(). * Use of custom previews by connecting to #GtkFileChooser::update-preview. * Any #GtkFileFilter added with a custom filter. ## macOS details ## {#gtkfilechooserdialognative-macos} On macOS the NSSavePanel and NSOpenPanel classes are used to provide native file chooser dialogs. Some features provided by #GtkFileChooserDialog are not supported: * Extra widgets added with gtk_file_chooser_set_extra_widget(), unless the widget is an instance of GtkLabel, in which case the label text will be used to set the NSSavePanel message instance property. * Use of custom previews by connecting to #GtkFileChooser::update-preview. * Any #GtkFileFilter added with a custom filter. * Shortcut folders. Creates a new #GtkFileChooserNative. a new #GtkFileChooserNative Title of the native, or %NULL Transient parent of the native, or %NULL Open or save mode for the dialog text to go in the accept button, or %NULL for the default text to go in the cancel button, or %NULL for the default Retrieves the custom label text for the accept button. The custom label, or %NULL for the default. This string is owned by GTK+ and should not be modified or freed a #GtFileChooserNative Retrieves the custom label text for the cancel button. The custom label, or %NULL for the default. This string is owned by GTK+ and should not be modified or freed a #GtFileChooserNative Sets the custom label text for the accept button. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button. a #GtFileChooserNative custom label or %NULL for the default Sets the custom label text for the cancel button. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button. a #GtFileChooserNative custom label or %NULL for the default The text used for the label on the accept button in the dialog, or %NULL to use the default text. The text used for the label on the cancel button in the dialog, or %NULL to use the default text. #GtkFileChooserWidget is a widget for choosing files. It exposes the #GtkFileChooser interface, and you should use the methods of this interface to interact with the widget. # CSS nodes GtkFileChooserWidget has a single CSS node with name filechooser. Creates a new #GtkFileChooserWidget. This is a file chooser widget that can be embedded in custom windows, and it is the same widget that is used by #GtkFileChooserDialog. a new #GtkFileChooserWidget Open or save mode for the widget The ::desktop-folder signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. This is used to make the file chooser show the user's Desktop folder in the file list. The default binding for this signal is `Alt + D`. The ::down-folder signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. This is used to make the file chooser go to a child of the current folder in the file hierarchy. The subfolder that will be used is displayed in the path bar widget of the file chooser. For example, if the path bar is showing "/foo/bar/baz", with bar currently displayed, then this will cause the file chooser to switch to the "baz" subfolder. The default binding for this signal is `Alt + Down`. The ::home-folder signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. This is used to make the file chooser show the user's home folder in the file list. The default binding for this signal is `Alt + Home`. The ::location-popup signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. This is used to make the file chooser show a "Location" prompt which the user can use to manually type the name of the file he wishes to select. The default bindings for this signal are `Control + L` with a @path string of "" (the empty string). It is also bound to `/` with a @path string of "`/`" (a slash): this lets you type `/` and immediately type a path name. On Unix systems, this is bound to `~` (tilde) with a @path string of "~" itself for access to home directories. a string that gets put in the text entry for the file name The ::location-popup-on-paste signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. This is used to make the file chooser show a "Location" prompt when the user pastes into a #GtkFileChooserWidget. The default binding for this signal is `Control + V`. The ::location-toggle-popup signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. This is used to toggle the visibility of a "Location" prompt which the user can use to manually type the name of the file he wishes to select. The default binding for this signal is `Control + L`. The ::places-shortcut signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. This is used to move the focus to the places sidebar. The default binding for this signal is `Alt + P`. The ::quick-bookmark signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. This is used to make the file chooser switch to the bookmark specified in the @bookmark_index parameter. For example, if you have three bookmarks, you can pass 0, 1, 2 to this signal to switch to each of them, respectively. The default binding for this signal is `Alt + 1`, `Alt + 2`, etc. until `Alt + 0`. Note that in the default binding, that `Alt + 1` is actually defined to switch to the bookmark at index 0, and so on successively; `Alt + 0` is defined to switch to the bookmark at index 10. the number of the bookmark to switch to The ::recent-shortcut signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. This is used to make the file chooser show the Recent location. The default binding for this signal is `Alt + R`. The ::search-shortcut signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. This is used to make the file chooser show the search entry. The default binding for this signal is `Alt + S`. The ::show-hidden signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. This is used to make the file chooser display hidden files. The default binding for this signal is `Control + H`. The ::up-folder signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. This is used to make the file chooser go to the parent of the current folder in the file hierarchy. The default binding for this signal is `Alt + Up`. The parent class. A GtkFileFilter can be used to restrict the files being shown in a #GtkFileChooser. Files can be filtered based on their name (with gtk_file_filter_add_pattern()), on their mime type (with gtk_file_filter_add_mime_type()), or by a custom filter function (with gtk_file_filter_add_custom()). Filtering by mime types handles aliasing and subclassing of mime types; e.g. a filter for text/plain also matches a file with mime type application/rtf, since application/rtf is a subclass of text/plain. Note that #GtkFileFilter allows wildcards for the subtype of a mime type, so you can e.g. filter for image/\*. Normally, filters are used by adding them to a #GtkFileChooser, see gtk_file_chooser_add_filter(), but it is also possible to manually use a filter on a file with gtk_file_filter_filter(). # GtkFileFilter as GtkBuildable The GtkFileFilter implementation of the GtkBuildable interface supports adding rules using the `<mime-types>`, `<patterns>` and `<applications>` elements and listing the rules within. Specifying a `<mime-type>` or `<pattern>` has the same effect as as calling gtk_file_filter_add_mime_type() or gtk_file_filter_add_pattern(). An example of a UI definition fragment specifying GtkFileFilter rules: |[<!-- language="xml" --> <object class="GtkFileFilter"> <mime-types> <mime-type>text/plain</mime-type> <mime-type>image/ *</mime-type> </mime-types> <patterns> <pattern>*.txt</pattern> <pattern>*.png</pattern> </patterns> </object> ]| Creates a new #GtkFileFilter with no rules added to it. Such a filter doesn’t accept any files, so is not particularly useful until you add rules with gtk_file_filter_add_mime_type(), gtk_file_filter_add_pattern(), or gtk_file_filter_add_custom(). To create a filter that accepts any file, use: |[<!-- language="C" --> GtkFileFilter *filter = gtk_file_filter_new (); gtk_file_filter_add_pattern (filter, "*"); ]| a new #GtkFileFilter Deserialize a file filter from an a{sv} variant in the format produced by gtk_file_filter_to_gvariant(). a new #GtkFileFilter object an a{sv} #GVariant Adds rule to a filter that allows files based on a custom callback function. The bitfield @needed which is passed in provides information about what sorts of information that the filter function needs; this allows GTK+ to avoid retrieving expensive information when it isn’t needed by the filter. a #GtkFileFilter bitfield of flags indicating the information that the custom filter function needs. callback function; if the function returns %TRUE, then the file will be displayed. data to pass to @func function to call to free @data when it is no longer needed. Adds a rule allowing a given mime type to @filter. A #GtkFileFilter name of a MIME type Adds a rule allowing a shell style glob to a filter. a #GtkFileFilter a shell style glob Adds a rule allowing image files in the formats supported by GdkPixbuf. a #GtkFileFilter Tests whether a file should be displayed according to @filter. The #GtkFileFilterInfo @filter_info should include the fields returned from gtk_file_filter_get_needed(). This function will not typically be used by applications; it is intended principally for use in the implementation of #GtkFileChooser. %TRUE if the file should be displayed a #GtkFileFilter a #GtkFileFilterInfo containing information about a file. Gets the human-readable name for the filter. See gtk_file_filter_set_name(). The human-readable name of the filter, or %NULL. This value is owned by GTK+ and must not be modified or freed. a #GtkFileFilter Gets the fields that need to be filled in for the #GtkFileFilterInfo passed to gtk_file_filter_filter() This function will not typically be used by applications; it is intended principally for use in the implementation of #GtkFileChooser. bitfield of flags indicating needed fields when calling gtk_file_filter_filter() a #GtkFileFilter Sets the human-readable name of the filter; this is the string that will be displayed in the file selector user interface if there is a selectable list of filters. a #GtkFileFilter the human-readable-name for the filter, or %NULL to remove any existing name. Serialize a file filter to an a{sv} variant. a new, floating, #GVariant a #GtkFileFilter These flags indicate what parts of a #GtkFileFilterInfo struct are filled or need to be filled. the filename of the file being tested the URI for the file being tested the string that will be used to display the file in the file chooser the mime type of the file The type of function that is used with custom filters, see gtk_file_filter_add_custom(). %TRUE if the file should be displayed a #GtkFileFilterInfo that is filled according to the @needed flags passed to gtk_file_filter_add_custom() user data passed to gtk_file_filter_add_custom() A #GtkFileFilterInfo-struct is used to pass information about the tested file to gtk_file_filter_filter(). Flags indicating which of the following fields need are filled the filename of the file being tested the URI for the file being tested the string that will be used to display the file in the file chooser the mime type of the file The #GtkFixed widget is a container which can place child widgets at fixed positions and with fixed sizes, given in pixels. #GtkFixed performs no automatic layout management. For most applications, you should not use this container! It keeps you from having to learn about the other GTK+ containers, but it results in broken applications. With #GtkFixed, the following things will result in truncated text, overlapping widgets, and other display bugs: - Themes, which may change widget sizes. - Fonts other than the one you used to write the app will of course change the size of widgets containing text; keep in mind that users may use a larger font because of difficulty reading the default, or they may be using a different OS that provides different fonts. - Translation of text into other languages changes its size. Also, display of non-English text will use a different font in many cases. In addition, #GtkFixed does not pay attention to text direction and thus may produce unwanted results if your app is run under right-to-left languages such as Hebrew or Arabic. That is: normally GTK+ will order containers appropriately for the text direction, e.g. to put labels to the right of the thing they label when using an RTL language, but it can’t do that with #GtkFixed. So if you need to reorder widgets depending on the text direction, you would need to manually detect it and adjust child positions accordingly. Finally, fixed positioning makes it kind of annoying to add/remove GUI elements, since you have to reposition all the other elements. This is a long-term maintenance problem for your application. If you know none of these things are an issue for your application, and prefer the simplicity of #GtkFixed, by all means use the widget. But you should be aware of the tradeoffs. See also #GtkLayout, which shares the ability to perform fixed positioning of child widgets and additionally adds custom drawing and scrollability. Creates a new #GtkFixed. a new #GtkFixed. Moves a child of a #GtkFixed container to the given position. a #GtkFixed. the child widget. the horizontal position to move the widget to. the vertical position to move the widget to. Adds a widget to a #GtkFixed container at the given position. a #GtkFixed. the widget to add. the horizontal position to place the widget at. the vertical position to place the widget at. A GtkFlowBox positions child widgets in sequence according to its orientation. For instance, with the horizontal orientation, the widgets will be arranged from left to right, starting a new row under the previous row when necessary. Reducing the width in this case will require more rows, so a larger height will be requested. Likewise, with the vertical orientation, the widgets will be arranged from top to bottom, starting a new column to the right when necessary. Reducing the height will require more columns, so a larger width will be requested. The size request of a GtkFlowBox alone may not be what you expect; if you need to be able to shrink it along both axes and dynamically reflow its children, you may have to wrap it in a #GtkScrolledWindow to enable that. The children of a GtkFlowBox can be dynamically sorted and filtered. Although a GtkFlowBox must have only #GtkFlowBoxChild children, you can add any kind of widget to it via gtk_container_add(), and a GtkFlowBoxChild widget will automatically be inserted between the box and the widget. Also see #GtkListBox. GtkFlowBox was added in GTK+ 3.12. # CSS nodes |[<!-- language="plain" --> flowbox ├── flowboxchild │ ╰── <child> ├── flowboxchild │ ╰── <child> ┊ ╰── [rubberband] ]| GtkFlowBox uses a single CSS node with name flowbox. GtkFlowBoxChild uses a single CSS node with name flowboxchild. For rubberband selection, a subnode with name rubberband is used. Creates a GtkFlowBox. a new #GtkFlowBox container Select all children of @box, if the selection mode allows it. a #GtkFlowBox Unselect all children of @box, if the selection mode allows it. a #GtkFlowBox Binds @model to @box. If @box was already bound to a model, that previous binding is destroyed. The contents of @box are cleared and then filled with widgets that represent items from @model. @box is updated whenever @model changes. If @model is %NULL, @box is left empty. It is undefined to add or remove widgets directly (for example, with gtk_flow_box_insert() or gtk_container_add()) while @box is bound to a model. Note that using a model is incompatible with the filtering and sorting functionality in GtkFlowBox. When using a model, filtering and sorting should be implemented by the model. a #GtkFlowBox the #GListModel to be bound to @box a function that creates widgets for items user data passed to @create_widget_func function for freeing @user_data Returns whether children activate on single clicks. %TRUE if children are activated on single click, %FALSE otherwise a #GtkFlowBox Gets the nth child in the @box. the child widget, which will always be a #GtkFlowBoxChild or %NULL in case no child widget with the given index exists. a #GtkFlowBox the position of the child Gets the child in the (@x, @y) position. the child widget, which will always be a #GtkFlowBoxChild or %NULL in case no child widget exists for the given x and y coordinates. a #GtkFlowBox the x coordinate of the child the y coordinate of the child Gets the horizontal spacing. the horizontal spacing a #GtkFlowBox Returns whether the box is homogeneous (all children are the same size). See gtk_box_set_homogeneous(). %TRUE if the box is homogeneous. a #GtkFlowBox Gets the maximum number of children per line. the maximum number of children per line a #GtkFlowBox Gets the minimum number of children per line. the minimum number of children per line a #GtkFlowBox Gets the vertical spacing. the vertical spacing a #GtkFlowBox Creates a list of all selected children. A #GList containing the #GtkWidget for each selected child. Free with g_list_free() when done. a #GtkFlowBox Gets the selection mode of @box. the #GtkSelectionMode a #GtkFlowBox Inserts the @widget into @box at @position. If a sort function is set, the widget will actually be inserted at the calculated position and this function has the same effect as gtk_container_add(). If @position is -1, or larger than the total number of children in the @box, then the @widget will be appended to the end. a #GtkFlowBox the #GtkWidget to add the position to insert @child in Updates the filtering for all children. Call this function when the result of the filter function on the @box is changed due ot an external factor. For instance, this would be used if the filter function just looked for a specific search term, and the entry with the string has changed. a #GtkFlowBox Updates the sorting for all children. Call this when the result of the sort function on @box is changed due to an external factor. a #GtkFlowBox Select all children of @box, if the selection mode allows it. a #GtkFlowBox Selects a single child of @box, if the selection mode allows it. a #GtkFlowBox a child of @box Calls a function for each selected child. Note that the selection cannot be modified from within this function. a #GtkFlowBox the function to call for each selected child user data to pass to the function If @single is %TRUE, children will be activated when you click on them, otherwise you need to double-click. a #GtkFlowBox %TRUE to emit child-activated on a single click Sets the horizontal space to add between children. See the #GtkFlowBox:column-spacing property. a #GtkFlowBox the spacing to use By setting a filter function on the @box one can decide dynamically which of the children to show. For instance, to implement a search function that only shows the children matching the search terms. The @filter_func will be called for each child after the call, and it will continue to be called each time a child changes (via gtk_flow_box_child_changed()) or when gtk_flow_box_invalidate_filter() is called. Note that using a filter function is incompatible with using a model (see gtk_flow_box_bind_model()). a #GtkFlowBox callback that lets you filter which children to show user data passed to @filter_func destroy notifier for @user_data Hooks up an adjustment to focus handling in @box. The adjustment is also used for autoscrolling during rubberband selection. See gtk_scrolled_window_get_hadjustment() for a typical way of obtaining the adjustment, and gtk_flow_box_set_vadjustment()for setting the vertical adjustment. The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the box. a #GtkFlowBox an adjustment which should be adjusted when the focus is moved among the descendents of @container Sets the #GtkFlowBox:homogeneous property of @box, controlling whether or not all children of @box are given equal space in the box. a #GtkFlowBox %TRUE to create equal allotments, %FALSE for variable allotments Sets the maximum number of children to request and allocate space for in @box’s orientation. Setting the maximum number of children per line limits the overall natural size request to be no more than @n_children children long in the given orientation. a #GtkFlowBox the maximum number of children per line Sets the minimum number of children to line up in @box’s orientation before flowing. a #GtkFlowBox the minimum number of children per line Sets the vertical space to add between children. See the #GtkFlowBox:row-spacing property. a #GtkFlowBox the spacing to use Sets how selection works in @box. See #GtkSelectionMode for details. a #GtkFlowBox the new selection mode By setting a sort function on the @box, one can dynamically reorder the children of the box, based on the contents of the children. The @sort_func will be called for each child after the call, and will continue to be called each time a child changes (via gtk_flow_box_child_changed()) and when gtk_flow_box_invalidate_sort() is called. Note that using a sort function is incompatible with using a model (see gtk_flow_box_bind_model()). a #GtkFlowBox the sort function user data passed to @sort_func destroy notifier for @user_data Hooks up an adjustment to focus handling in @box. The adjustment is also used for autoscrolling during rubberband selection. See gtk_scrolled_window_get_vadjustment() for a typical way of obtaining the adjustment, and gtk_flow_box_set_hadjustment()for setting the horizontal adjustment. The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the box. a #GtkFlowBox an adjustment which should be adjusted when the focus is moved among the descendents of @container Unselect all children of @box, if the selection mode allows it. a #GtkFlowBox Unselects a single child of @box, if the selection mode allows it. a #GtkFlowBox a child of @box Determines whether children can be activated with a single click, or require a double-click. The amount of horizontal space between two children. Determines whether all children should be allocated the same size. The maximum amount of children to request space for consecutively in the given orientation. The minimum number of children to allocate consecutively in the given orientation. Setting the minimum children per line ensures that a reasonably small height will be requested for the overall minimum width of the box. The amount of vertical space between two children. The selection mode used by the flow box. The ::activate-cursor-child signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user activates the @box. The ::child-activated signal is emitted when a child has been activated by the user. the child that is activated The ::move-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a cursor movement. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifer does not. There are too many key combinations to list them all here. - Arrow keys move by individual children - Home/End keys move to the ends of the box - PageUp/PageDown keys move vertically by pages %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the granularity fo the move, as a #GtkMovementStep the number of @step units to move The ::select-all signal is a [keybinding signal][GtkBindingSignal] which gets emitted to select all children of the box, if the selection mode permits it. The default bindings for this signal is Ctrl-a. The ::selected-children-changed signal is emitted when the set of selected children changes. Use gtk_flow_box_selected_foreach() or gtk_flow_box_get_selected_children() to obtain the selected children. The ::toggle-cursor-child signal is a [keybinding signal][GtkBindingSignal] which toggles the selection of the child that has the focus. The default binding for this signal is Ctrl-Space. The ::unselect-all signal is a [keybinding signal][GtkBindingSignal] which gets emitted to unselect all children of the box, if the selection mode permits it. The default bindings for this signal is Ctrl-Shift-a. Creates a new #GtkFlowBoxChild, to be used as a child of a #GtkFlowBox. a new #GtkFlowBoxChild Marks @child as changed, causing any state that depends on this to be updated. This affects sorting and filtering. Note that calls to this method must be in sync with the data used for the sorting and filtering functions. For instance, if the list is mirroring some external data set, and *two* children changed in the external data set when you call gtk_flow_box_child_changed() on the first child, the sort function must only read the new data for the first of the two changed children, otherwise the resorting of the children will be wrong. This generally means that if you don’t fully control the data model, you have to duplicate the data that affects the sorting and filtering functions into the widgets themselves. Another alternative is to call gtk_flow_box_invalidate_sort() on any model change, but that is more expensive. a #GtkFlowBoxChild Gets the current index of the @child in its #GtkFlowBox container. the index of the @child, or -1 if the @child is not in a flow box. a #GtkFlowBoxChild Returns whether the @child is currently selected in its #GtkFlowBox container. %TRUE if @child is selected a #GtkFlowBoxChild The ::activate signal is emitted when the user activates a child widget in a #GtkFlowBox, either by clicking or double-clicking, or by using the Space or Enter key. While this signal is used as a [keybinding signal][GtkBindingSignal], it can be used by applications for their own purposes. a #GtkFlowBox a #GtkFlowBox Called for flow boxes that are bound to a #GListModel with gtk_flow_box_bind_model() for each item that gets added to the model. a #GtkWidget that represents @item the item from the model for which to create a widget for user data from gtk_flow_box_bind_model() A function that will be called whenrever a child changes or is added. It lets you control if the child should be visible or not. %TRUE if the row should be visible, %FALSE otherwise a #GtkFlowBoxChild that may be filtered user data A function used by gtk_flow_box_selected_foreach(). It will be called on every selected child of the @box. a #GtkFlowBox a #GtkFlowBoxChild user data A function to compare two children to determine which should come first. < 0 if @child1 should be before @child2, 0 if the are equal, and > 0 otherwise the first child the second child user data The #GtkFontButton is a button which displays the currently selected font an allows to open a font chooser dialog to change the font. It is suitable widget for selecting a font in a preference dialog. # CSS nodes GtkFontButton has a single CSS node with name button and style class .font. Creates a new font picker widget. a new font picker widget. Creates a new font picker widget. a new font picker widget. Name of font to display in font chooser dialog Retrieves the name of the currently selected font. This name includes style and size information as well. If you want to render something with the font, use this string with pango_font_description_from_string() . If you’re interested in peeking certain values (family name, style, size, weight) just query these properties from the #PangoFontDescription object. Use gtk_font_chooser_get_font() instead an internal copy of the font name which must not be freed. a #GtkFontButton Returns whether the font size will be shown in the label. whether the font size will be shown in the label. a #GtkFontButton Returns whether the name of the font style will be shown in the label. whether the font style will be shown in the label. a #GtkFontButton Retrieves the title of the font chooser dialog. an internal copy of the title string which must not be freed. a #GtkFontButton Returns whether the selected font is used in the label. whether the selected font is used in the label. a #GtkFontButton Returns whether the selected size is used in the label. whether the selected size is used in the label. a #GtkFontButton Sets or updates the currently-displayed font in font picker dialog. Use gtk_font_chooser_set_font() instead %TRUE a #GtkFontButton Name of font to display in font chooser dialog If @show_size is %TRUE, the font size will be displayed along with the name of the selected font. a #GtkFontButton %TRUE if font size should be displayed in dialog. If @show_style is %TRUE, the font style will be displayed along with name of the selected font. a #GtkFontButton %TRUE if font style should be displayed in label. Sets the title for the font chooser dialog. a #GtkFontButton a string containing the font chooser dialog title If @use_font is %TRUE, the font name will be written using the selected font. a #GtkFontButton If %TRUE, font name will be written using font chosen. If @use_size is %TRUE, the font name will be written using the selected size. a #GtkFontButton If %TRUE, font name will be written using the selected size. The name of the currently selected font. Use the #GtkFontChooser::font property instead If this property is set to %TRUE, the selected font size will be shown in the label. For a more WYSIWYG way to show the selected size, see the ::use-size property. If this property is set to %TRUE, the name of the selected font style will be shown in the label. For a more WYSIWYG way to show the selected style, see the ::use-font property. The title of the font chooser dialog. If this property is set to %TRUE, the label will be drawn in the selected font. If this property is set to %TRUE, the label will be drawn with the selected font size. The ::font-set signal is emitted when the user selects a font. When handling this signal, use gtk_font_chooser_get_font() to find out which font was just selected. Note that this signal is only emitted when the user changes the font. If you need to react to programmatic font changes as well, use the notify::font signal. #GtkFontChooser is an interface that can be implemented by widgets displaying the list of fonts. In GTK+, the main objects that implement this interface are #GtkFontChooserWidget, #GtkFontChooserDialog and #GtkFontButton. The GtkFontChooser interface has been introducted in GTK+ 3.2. Gets the #PangoFontFace representing the selected font group details (i.e. family, slant, weight, width, etc). If the selected font is not installed, returns %NULL. A #PangoFontFace representing the selected font group details, or %NULL. The returned object is owned by @fontchooser and must not be modified or freed. a #GtkFontChooser Gets the #PangoFontFamily representing the selected font family. Font families are a collection of font faces. If the selected font is not installed, returns %NULL. A #PangoFontFamily representing the selected font family, or %NULL. The returned object is owned by @fontchooser and must not be modified or freed. a #GtkFontChooser Gets the custom font map of this font chooser widget, or %NULL if it does not have one. a #PangoFontMap, or %NULL a #GtkFontChooser The selected font size. A n integer representing the selected font size, or -1 if no font size is selected. a #GtkFontChooser Adds a filter function that decides which fonts to display in the font chooser. a #GtkFontChooser a #GtkFontFilterFunc, or %NULL data to pass to @filter function to call to free @data when it is no longer needed Sets a custom font map to use for this font chooser widget. A custom font map can be used to present application-specific fonts instead of or in addition to the normal system fonts. |[<!-- language="C" --> FcConfig *config; PangoFontMap *fontmap; config = FcInitLoadConfigAndFonts (); FcConfigAppFontAddFile (config, my_app_font_file); fontmap = pango_cairo_font_map_new_for_font_type (CAIRO_FONT_TYPE_FT); pango_fc_font_map_set_config (PANGO_FC_FONT_MAP (fontmap), config); gtk_font_chooser_set_font_map (font_chooser, fontmap); ]| Note that other GTK+ widgets will only be able to use the application-specific font if it is present in the font map they use: |[ context = gtk_widget_get_pango_context (label); pango_context_set_font_map (context, fontmap); ]| a #GtkFontChooser a #PangoFontMap Gets the currently-selected font name. Note that this can be a different string than what you set with gtk_font_chooser_set_font(), as the font chooser widget may normalize font names and thus return a string with a different structure. For example, “Helvetica Italic Bold 12” could be normalized to “Helvetica Bold Italic 12”. Use pango_font_description_equal() if you want to compare two font descriptions. A string with the name of the current font, or %NULL if no font is selected. You must free this string with g_free(). a #GtkFontChooser Gets the currently-selected font. Note that this can be a different string than what you set with gtk_font_chooser_set_font(), as the font chooser widget may normalize font names and thus return a string with a different structure. For example, “Helvetica Italic Bold 12” could be normalized to “Helvetica Bold Italic 12”. Use pango_font_description_equal() if you want to compare two font descriptions. A #PangoFontDescription for the current font, or %NULL if no font is selected. a #GtkFontChooser Gets the #PangoFontFace representing the selected font group details (i.e. family, slant, weight, width, etc). If the selected font is not installed, returns %NULL. A #PangoFontFace representing the selected font group details, or %NULL. The returned object is owned by @fontchooser and must not be modified or freed. a #GtkFontChooser Gets the #PangoFontFamily representing the selected font family. Font families are a collection of font faces. If the selected font is not installed, returns %NULL. A #PangoFontFamily representing the selected font family, or %NULL. The returned object is owned by @fontchooser and must not be modified or freed. a #GtkFontChooser Gets the currently-selected font features. the currently selected font features a #GtkFontChooser Gets the custom font map of this font chooser widget, or %NULL if it does not have one. a #PangoFontMap, or %NULL a #GtkFontChooser The selected font size. A n integer representing the selected font size, or -1 if no font size is selected. a #GtkFontChooser Gets the language that is used for font features. the currently selected language a #GtkFontChooser Returns the current level of granularity for selecting fonts. the current granularity level a #GtkFontChooser Gets the text displayed in the preview area. the text displayed in the preview area a #GtkFontChooser Returns whether the preview entry is shown or not. %TRUE if the preview entry is shown or %FALSE if it is hidden. a #GtkFontChooser Adds a filter function that decides which fonts to display in the font chooser. a #GtkFontChooser a #GtkFontFilterFunc, or %NULL data to pass to @filter function to call to free @data when it is no longer needed Sets the currently-selected font. a #GtkFontChooser a font name like “Helvetica 12” or “Times Bold 18” Sets the currently-selected font from @font_desc. a #GtkFontChooser a #PangoFontDescription Sets a custom font map to use for this font chooser widget. A custom font map can be used to present application-specific fonts instead of or in addition to the normal system fonts. |[<!-- language="C" --> FcConfig *config; PangoFontMap *fontmap; config = FcInitLoadConfigAndFonts (); FcConfigAppFontAddFile (config, my_app_font_file); fontmap = pango_cairo_font_map_new_for_font_type (CAIRO_FONT_TYPE_FT); pango_fc_font_map_set_config (PANGO_FC_FONT_MAP (fontmap), config); gtk_font_chooser_set_font_map (font_chooser, fontmap); ]| Note that other GTK+ widgets will only be able to use the application-specific font if it is present in the font map they use: |[ context = gtk_widget_get_pango_context (label); pango_context_set_font_map (context, fontmap); ]| a #GtkFontChooser a #PangoFontMap Sets the language to use for font features. a #GtkFontChooser a language Sets the desired level of granularity for selecting fonts. a #GtkFontChooser the desired level of granularity Sets the text displayed in the preview area. The @text is used to show how the selected font looks. a #GtkFontChooser the text to display in the preview area Shows or hides the editable preview entry. a #GtkFontChooser whether to show the editable preview entry or not The font description as a string, e.g. "Sans Italic 12". The font description as a #PangoFontDescription. The selected font features, in a format that is compatible with CSS and with Pango attributes. The language for which the #GtkFontChooser:font-features were selected, in a format that is compatible with CSS and with Pango attributes. The level of granularity to offer for selecting fonts. The string with which to preview the font. Whether to show an entry to change the preview text. Emitted when a font is activated. This usually happens when the user double clicks an item, or an item is selected and the user presses one of the keys Space, Shift+Space, Return or Enter. the font name The #GtkFontChooserDialog widget is a dialog for selecting a font. It implements the #GtkFontChooser interface. # GtkFontChooserDialog as GtkBuildable The GtkFontChooserDialog implementation of the #GtkBuildable interface exposes the buttons with the names “select_button” and “cancel_button”. Creates a new #GtkFontChooserDialog. a new #GtkFontChooserDialog Title of the dialog, or %NULL Transient parent of the dialog, or %NULL The parent class. A #PangoFontFamily representing the selected font family, or %NULL. The returned object is owned by @fontchooser and must not be modified or freed. a #GtkFontChooser A #PangoFontFace representing the selected font group details, or %NULL. The returned object is owned by @fontchooser and must not be modified or freed. a #GtkFontChooser A n integer representing the selected font size, or -1 if no font size is selected. a #GtkFontChooser a #GtkFontChooser a #GtkFontFilterFunc, or %NULL data to pass to @filter function to call to free @data when it is no longer needed a #GtkFontChooser a #PangoFontMap a #PangoFontMap, or %NULL a #GtkFontChooser This enumeration specifies the granularity of font selection that is desired in a font chooser. This enumeration may be extended in the future; applications should ignore unknown values. Allow selecting a font family Allow selecting a specific font face Allow selecting a specific font size Allow selecting specific OpenType font features The #GtkFontChooserWidget widget lists the available fonts, styles and sizes, allowing the user to select a font. It is used in the #GtkFontChooserDialog widget to provide a dialog box for selecting fonts. To set the font which is initially selected, use gtk_font_chooser_set_font() or gtk_font_chooser_set_font_desc(). To get the selected font use gtk_font_chooser_get_font() or gtk_font_chooser_get_font_desc(). To change the text which is shown in the preview area, use gtk_font_chooser_set_preview_text(). # CSS nodes GtkFontChooserWidget has a single CSS node with name fontchooser. Creates a new #GtkFontChooserWidget. a new #GtkFontChooserWidget A toggle action that can be used to switch to the tweak page of the font chooser widget, which lets the user tweak the OpenType features and variation axes of the selected font. The action will be enabled or disabled depending on whether the selected font has any features or axes. The parent class. The type of function that is used for deciding what fonts get shown in a #GtkFontChooser. See gtk_font_chooser_set_filter_func(). %TRUE if the font should be displayed a #PangoFontFamily a #PangoFontFace belonging to @family user data passed to gtk_font_chooser_set_filter_func() Creates a new #GtkFontSelection. Use #GtkFontChooserWidget instead a new #GtkFontSelection Gets the #PangoFontFace representing the selected font group details (i.e. family, slant, weight, width, etc). Use #GtkFontChooser A #PangoFontFace representing the selected font group details. The returned object is owned by @fontsel and must not be modified or freed. a #GtkFontSelection This returns the #GtkTreeView which lists all styles available for the selected font. For example, “Regular”, “Bold”, etc. Use #GtkFontChooser A #GtkWidget that is part of @fontsel a #GtkFontSelection Gets the #PangoFontFamily representing the selected font family. Use #GtkFontChooser A #PangoFontFamily representing the selected font family. Font families are a collection of font faces. The returned object is owned by @fontsel and must not be modified or freed. a #GtkFontSelection This returns the #GtkTreeView that lists font families, for example, “Sans”, “Serif”, etc. Use #GtkFontChooser A #GtkWidget that is part of @fontsel a #GtkFontSelection Gets the currently-selected font name. Note that this can be a different string than what you set with gtk_font_selection_set_font_name(), as the font selection widget may normalize font names and thus return a string with a different structure. For example, “Helvetica Italic Bold 12” could be normalized to “Helvetica Bold Italic 12”. Use pango_font_description_equal() if you want to compare two font descriptions. Use #GtkFontChooser A string with the name of the current font, or %NULL if no font is selected. You must free this string with g_free(). a #GtkFontSelection This returns the #GtkEntry used to display the font as a preview. Use #GtkFontChooser A #GtkWidget that is part of @fontsel a #GtkFontSelection Gets the text displayed in the preview area. Use #GtkFontChooser the text displayed in the preview area. This string is owned by the widget and should not be modified or freed a #GtkFontSelection The selected font size. Use #GtkFontChooser A n integer representing the selected font size, or -1 if no font size is selected. a #GtkFontSelection This returns the #GtkEntry used to allow the user to edit the font number manually instead of selecting it from the list of font sizes. Use #GtkFontChooser A #GtkWidget that is part of @fontsel a #GtkFontSelection This returns the #GtkTreeView used to list font sizes. Use #GtkFontChooser A #GtkWidget that is part of @fontsel a #GtkFontSelection Sets the currently-selected font. Note that the @fontsel needs to know the screen in which it will appear for this to work; this can be guaranteed by simply making sure that the @fontsel is inserted in a toplevel window before you call this function. Use #GtkFontChooser %TRUE if the font could be set successfully; %FALSE if no such font exists or if the @fontsel doesn’t belong to a particular screen yet. a #GtkFontSelection a font name like “Helvetica 12” or “Times Bold 18” Sets the text displayed in the preview area. The @text is used to show how the selected font looks. Use #GtkFontChooser a #GtkFontSelection the text to display in the preview area Creates a new #GtkFontSelectionDialog. Use #GtkFontChooserDialog a new #GtkFontSelectionDialog the title of the dialog window Gets the “Cancel” button. Use #GtkFontChooserDialog the #GtkWidget used in the dialog for the “Cancel” button. a #GtkFontSelectionDialog Gets the currently-selected font name. Note that this can be a different string than what you set with gtk_font_selection_dialog_set_font_name(), as the font selection widget may normalize font names and thus return a string with a different structure. For example, “Helvetica Italic Bold 12” could be normalized to “Helvetica Bold Italic 12”. Use pango_font_description_equal() if you want to compare two font descriptions. Use #GtkFontChooserDialog A string with the name of the current font, or %NULL if no font is selected. You must free this string with g_free(). a #GtkFontSelectionDialog Retrieves the #GtkFontSelection widget embedded in the dialog. Use #GtkFontChooserDialog the embedded #GtkFontSelection a #GtkFontSelectionDialog Gets the “OK” button. Use #GtkFontChooserDialog the #GtkWidget used in the dialog for the “OK” button. a #GtkFontSelectionDialog Gets the text displayed in the preview area. Use #GtkFontChooserDialog the text displayed in the preview area. This string is owned by the widget and should not be modified or freed a #GtkFontSelectionDialog Sets the currently selected font. Use #GtkFontChooserDialog %TRUE if the font selected in @fsd is now the @fontname specified, %FALSE otherwise. a #GtkFontSelectionDialog a font name like “Helvetica 12” or “Times Bold 18” Sets the text displayed in the preview area. Use #GtkFontChooserDialog a #GtkFontSelectionDialog the text to display in the preview area The frame widget is a bin that surrounds its child with a decorative frame and an optional label. If present, the label is drawn in a gap in the top side of the frame. The position of the label can be controlled with gtk_frame_set_label_align(). # GtkFrame as GtkBuildable The GtkFrame implementation of the #GtkBuildable interface supports placing a child in the label position by specifying “label” as the “type” attribute of a `<child>` element. A normal content child can be specified without specifying a `<child>` type attribute. An example of a UI definition fragment with `GtkFrame`: |[<!-- language="xml" --> <object class="GtkFrame"> <child type="label"> <object class="GtkLabel" id="frame-label"/> </child> <child> <object class="GtkEntry" id="frame-content"/> </child> </object> ]| # CSS nodes |[<!-- language="plain" --> frame ├── border[.flat] ├── <label widget> ╰── <child> ]| GtkFrame has a main CSS node named “frame” and a subnode named “border”. The “border” node is used to draw the visible border. You can set the appearance of the border using CSS properties like “border-style” on the “border” node. The border node can be given the style class “.flat”, which is used by themes to disable drawing of the border. To do this from code, call gtk_frame_set_shadow_type() with %GTK_SHADOW_NONE to add the “.flat” class or any other shadow type to remove it. Creates a new #GtkFrame, with optional label @label. If @label is %NULL, the label is omitted. a new #GtkFrame widget the text to use as the label of the frame If the frame’s label widget is a #GtkLabel, returns the text in the label widget. (The frame will have a #GtkLabel for the label widget if a non-%NULL argument was passed to gtk_frame_new().) the text in the label, or %NULL if there was no label widget or the lable widget was not a #GtkLabel. This string is owned by GTK+ and must not be modified or freed. a #GtkFrame Retrieves the X and Y alignment of the frame’s label. See gtk_frame_set_label_align(). a #GtkFrame location to store X alignment of frame’s label, or %NULL location to store X alignment of frame’s label, or %NULL Retrieves the label widget for the frame. See gtk_frame_set_label_widget(). the label widget, or %NULL if there is none. a #GtkFrame Retrieves the shadow type of the frame. See gtk_frame_set_shadow_type(). the current shadow type of the frame. a #GtkFrame Removes the current #GtkFrame:label-widget. If @label is not %NULL, creates a new #GtkLabel with that text and adds it as the #GtkFrame:label-widget. a #GtkFrame the text to use as the label of the frame Sets the alignment of the frame widget’s label. The default values for a newly created frame are 0.0 and 0.5. a #GtkFrame The position of the label along the top edge of the widget. A value of 0.0 represents left alignment; 1.0 represents right alignment. The y alignment of the label. A value of 0.0 aligns under the frame; 1.0 aligns above the frame. If the values are exactly 0.0 or 1.0 the gap in the frame won’t be painted because the label will be completely above or below the frame. Sets the #GtkFrame:label-widget for the frame. This is the widget that will appear embedded in the top edge of the frame as a title. a #GtkFrame the new label widget Sets the #GtkFrame:shadow-type for @frame, i.e. whether it is drawn without (%GTK_SHADOW_NONE) or with (other values) a visible border. Values other than %GTK_SHADOW_NONE are treated identically by GtkFrame. The chosen type is applied by removing or adding the .flat class to the CSS node named border. a #GtkFrame the new #GtkShadowType The parent class. #GtkGLArea is a widget that allows drawing with OpenGL. #GtkGLArea sets up its own #GdkGLContext for the window it creates, and creates a custom GL framebuffer that the widget will do GL rendering onto. It also ensures that this framebuffer is the default GL rendering target when rendering. In order to draw, you have to connect to the #GtkGLArea::render signal, or subclass #GtkGLArea and override the @GtkGLAreaClass.render() virtual function. The #GtkGLArea widget ensures that the #GdkGLContext is associated with the widget's drawing area, and it is kept updated when the size and position of the drawing area changes. ## Drawing with GtkGLArea ## The simplest way to draw using OpenGL commands in a #GtkGLArea is to create a widget instance and connect to the #GtkGLArea::render signal: |[<!-- language="C" --> // create a GtkGLArea instance GtkWidget *gl_area = gtk_gl_area_new (); // connect to the "render" signal g_signal_connect (gl_area, "render", G_CALLBACK (render), NULL); ]| The `render()` function will be called when the #GtkGLArea is ready for you to draw its content: |[<!-- language="C" --> static gboolean render (GtkGLArea *area, GdkGLContext *context) { // inside this function it's safe to use GL; the given // #GdkGLContext has been made current to the drawable // surface used by the #GtkGLArea and the viewport has // already been set to be the size of the allocation // we can start by clearing the buffer glClearColor (0, 0, 0, 0); glClear (GL_COLOR_BUFFER_BIT); // draw your object draw_an_object (); // we completed our drawing; the draw commands will be // flushed at the end of the signal emission chain, and // the buffers will be drawn on the window return TRUE; } ]| If you need to initialize OpenGL state, e.g. buffer objects or shaders, you should use the #GtkWidget::realize signal; you can use the #GtkWidget::unrealize signal to clean up. Since the #GdkGLContext creation and initialization may fail, you will need to check for errors, using gtk_gl_area_get_error(). An example of how to safely initialize the GL state is: |[<!-- language="C" --> static void on_realize (GtkGLarea *area) { // We need to make the context current if we want to // call GL API gtk_gl_area_make_current (area); // If there were errors during the initialization or // when trying to make the context current, this // function will return a #GError for you to catch if (gtk_gl_area_get_error (area) != NULL) return; // You can also use gtk_gl_area_set_error() in order // to show eventual initialization errors on the // GtkGLArea widget itself GError *internal_error = NULL; init_buffer_objects (&error); if (error != NULL) { gtk_gl_area_set_error (area, error); g_error_free (error); return; } init_shaders (&error); if (error != NULL) { gtk_gl_area_set_error (area, error); g_error_free (error); return; } } ]| If you need to change the options for creating the #GdkGLContext you should use the #GtkGLArea::create-context signal. Creates a new #GtkGLArea widget. a new #GtkGLArea class closure for the #GtkGLArea::create-context signal class closure for the #GtkGLArea::render signal class closeure for the #GtkGLArea::resize signal Ensures that the @area framebuffer object is made the current draw and read target, and that all the required buffers for the @area are created and bound to the frambuffer. This function is automatically called before emitting the #GtkGLArea::render signal, and doesn't normally need to be called by application code. a #GtkGLArea Returns whether the area is in auto render mode or not. %TRUE if the @area is auto rendering, %FALSE otherwise a #GtkGLArea Retrieves the #GdkGLContext used by @area. the #GdkGLContext a #GtkGLArea Gets the current error set on the @area. the #GError or %NULL a #GtkGLArea Returns whether the area has an alpha component. %TRUE if the @area has an alpha component, %FALSE otherwise a #GtkGLArea Returns whether the area has a depth buffer. %TRUE if the @area has a depth buffer, %FALSE otherwise a #GtkGLArea Returns whether the area has a stencil buffer. %TRUE if the @area has a stencil buffer, %FALSE otherwise a #GtkGLArea Retrieves the required version of OpenGL set using gtk_gl_area_set_required_version(). a #GtkGLArea return location for the required major version return location for the required minor version Retrieves the value set by gtk_gl_area_set_use_es(). %TRUE if the #GtkGLArea should create an OpenGL ES context and %FALSE otherwise a #GtkGLArea Ensures that the #GdkGLContext used by @area is associated with the #GtkGLArea. This function is automatically called before emitting the #GtkGLArea::render signal, and doesn't normally need to be called by application code. a #GtkGLArea Marks the currently rendered data (if any) as invalid, and queues a redraw of the widget, ensuring that the #GtkGLArea::render signal is emitted during the draw. This is only needed when the gtk_gl_area_set_auto_render() has been called with a %FALSE value. The default behaviour is to emit #GtkGLArea::render on each draw. a #GtkGLArea If @auto_render is %TRUE the #GtkGLArea::render signal will be emitted every time the widget draws. This is the default and is useful if drawing the widget is faster. If @auto_render is %FALSE the data from previous rendering is kept around and will be used for drawing the widget the next time, unless the window is resized. In order to force a rendering gtk_gl_area_queue_render() must be called. This mode is useful when the scene changes seldomly, but takes a long time to redraw. a #GtkGLArea a boolean Sets an error on the area which will be shown instead of the GL rendering. This is useful in the #GtkGLArea::create-context signal if GL context creation fails. a #GtkGLArea a new #GError, or %NULL to unset the error If @has_alpha is %TRUE the buffer allocated by the widget will have an alpha channel component, and when rendering to the window the result will be composited over whatever is below the widget. If @has_alpha is %FALSE there will be no alpha channel, and the buffer will fully replace anything below the widget. a #GtkGLArea %TRUE to add an alpha component If @has_depth_buffer is %TRUE the widget will allocate and enable a depth buffer for the target framebuffer. Otherwise there will be none. a #GtkGLArea %TRUE to add a depth buffer If @has_stencil_buffer is %TRUE the widget will allocate and enable a stencil buffer for the target framebuffer. Otherwise there will be none. a #GtkGLArea %TRUE to add a stencil buffer Sets the required version of OpenGL to be used when creating the context for the widget. This function must be called before the area has been realized. a #GtkGLArea the major version the minor version Sets whether the @area should create an OpenGL or an OpenGL ES context. You should check the capabilities of the #GdkGLContext before drawing with either API. a #GtkGLArea whether to use OpenGL or OpenGL ES If set to %TRUE the #GtkGLArea::render signal will be emitted every time the widget draws. This is the default and is useful if drawing the widget is faster. If set to %FALSE the data from previous rendering is kept around and will be used for drawing the widget the next time, unless the window is resized. In order to force a rendering gtk_gl_area_queue_render() must be called. This mode is useful when the scene changes seldomly, but takes a long time to redraw. The #GdkGLContext used by the #GtkGLArea widget. The #GtkGLArea widget is responsible for creating the #GdkGLContext instance. If you need to render with other kinds of buffers (stencil, depth, etc), use render buffers. If set to %TRUE the buffer allocated by the widget will have an alpha channel component, and when rendering to the window the result will be composited over whatever is below the widget. If set to %FALSE there will be no alpha channel, and the buffer will fully replace anything below the widget. If set to %TRUE the widget will allocate and enable a depth buffer for the target framebuffer. If set to %TRUE the widget will allocate and enable a stencil buffer for the target framebuffer. If set to %TRUE the widget will try to create a #GdkGLContext using OpenGL ES instead of OpenGL. See also: gdk_gl_context_set_use_es() The ::create-context signal is emitted when the widget is being realized, and allows you to override how the GL context is created. This is useful when you want to reuse an existing GL context, or if you want to try creating different kinds of GL options. If context creation fails then the signal handler can use gtk_gl_area_set_error() to register a more detailed error of how the construction failed. a newly created #GdkGLContext; the #GtkGLArea widget will take ownership of the returned value. The ::render signal is emitted every time the contents of the #GtkGLArea should be redrawn. The @context is bound to the @area prior to emitting this function, and the buffers are painted to the window once the emission terminates. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkGLContext used by @area The ::resize signal is emitted once when the widget is realized, and then each time the widget is changed while realized. This is useful in order to keep GL state up to date with the widget size, like for instance camera properties which may depend on the width/height ratio. The GL context for the area is guaranteed to be current when this signal is emitted. The default handler sets up the GL viewport. the width of the viewport the height of the viewport The `GtkGLAreaClass` structure contains only private data. class closure for the #GtkGLArea::render signal class closeure for the #GtkGLArea::resize signal class closure for the #GtkGLArea::create-context signal #GtkGesture is the base object for gesture recognition, although this object is quite generalized to serve as a base for multi-touch gestures, it is suitable to implement single-touch and pointer-based gestures (using the special %NULL #GdkEventSequence value for these). The number of touches that a #GtkGesture need to be recognized is controlled by the #GtkGesture:n-points property, if a gesture is keeping track of less or more than that number of sequences, it won't check wether the gesture is recognized. As soon as the gesture has the expected number of touches, the gesture will run the #GtkGesture::check signal regularly on input events until the gesture is recognized, the criteria to consider a gesture as "recognized" is left to #GtkGesture subclasses. A recognized gesture will then emit the following signals: - #GtkGesture::begin when the gesture is recognized. - A number of #GtkGesture::update, whenever an input event is processed. - #GtkGesture::end when the gesture is no longer recognized. ## Event propagation In order to receive events, a gesture needs to either set a propagation phase through gtk_event_controller_set_propagation_phase(), or feed those manually through gtk_event_controller_handle_event(). In the capture phase, events are propagated from the toplevel down to the target widget, and gestures that are attached to containers above the widget get a chance to interact with the event before it reaches the target. After the capture phase, GTK+ emits the traditional #GtkWidget::button-press-event, #GtkWidget::button-release-event, #GtkWidget::touch-event, etc signals. Gestures with the %GTK_PHASE_TARGET phase are fed events from the default #GtkWidget::event handlers. In the bubble phase, events are propagated up from the target widget to the toplevel, and gestures that are attached to containers above the widget get a chance to interact with events that have not been handled yet. ## States of a sequence # {#touch-sequence-states} Whenever input interaction happens, a single event may trigger a cascade of #GtkGestures, both across the parents of the widget receiving the event and in parallel within an individual widget. It is a responsibility of the widgets using those gestures to set the state of touch sequences accordingly in order to enable cooperation of gestures around the #GdkEventSequences triggering those. Within a widget, gestures can be grouped through gtk_gesture_group(), grouped gestures synchronize the state of sequences, so calling gtk_gesture_set_sequence_state() on one will effectively propagate the state throughout the group. By default, all sequences start out in the #GTK_EVENT_SEQUENCE_NONE state, sequences in this state trigger the gesture event handler, but event propagation will continue unstopped by gestures. If a sequence enters into the #GTK_EVENT_SEQUENCE_DENIED state, the gesture group will effectively ignore the sequence, letting events go unstopped through the gesture, but the "slot" will still remain occupied while the touch is active. If a sequence enters in the #GTK_EVENT_SEQUENCE_CLAIMED state, the gesture group will grab all interaction on the sequence, by: - Setting the same sequence to #GTK_EVENT_SEQUENCE_DENIED on every other gesture group within the widget, and every gesture on parent widgets in the propagation chain. - calling #GtkGesture::cancel on every gesture in widgets underneath in the propagation chain. - Stopping event propagation after the gesture group handles the event. Note: if a sequence is set early to #GTK_EVENT_SEQUENCE_CLAIMED on #GDK_TOUCH_BEGIN/#GDK_BUTTON_PRESS (so those events are captured before reaching the event widget, this implies #GTK_PHASE_CAPTURE), one similar event will emulated if the sequence changes to #GTK_EVENT_SEQUENCE_DENIED. This way event coherence is preserved before event propagation is unstopped again. Sequence states can't be changed freely, see gtk_gesture_set_sequence_state() to know about the possible lifetimes of a #GdkEventSequence. ## Touchpad gestures On the platforms that support it, #GtkGesture will handle transparently touchpad gesture events. The only precautions users of #GtkGesture should do to enable this support are: - Enabling %GDK_TOUCHPAD_GESTURE_MASK on their #GdkWindows - If the gesture has %GTK_PHASE_NONE, ensuring events of type %GDK_TOUCHPAD_SWIPE and %GDK_TOUCHPAD_PINCH are handled by the #GtkGesture If there are touch sequences being currently handled by @gesture, this function returns %TRUE and fills in @rect with the bounding box containing all active touches. Otherwise, %FALSE will be returned. Note: This function will yield unexpected results on touchpad gestures. Since there is no correlation between physical and pixel distances, these will look as if constrained in an infinitely small area, @rect width and height will thus be 0 regardless of the number of touchpoints. %TRUE if there are active touches, %FALSE otherwise a #GtkGesture bounding box containing all active touches. If there are touch sequences being currently handled by @gesture, this function returns %TRUE and fills in @x and @y with the center of the bounding box containing all active touches. Otherwise, %FALSE will be returned. %FALSE if no active touches are present, %TRUE otherwise a #GtkGesture X coordinate for the bounding box center Y coordinate for the bounding box center Returns the master #GdkDevice that is currently operating on @gesture, or %NULL if the gesture is not being interacted. a #GdkDevice, or %NULL a #GtkGesture Returns all gestures in the group of @gesture The list of #GtkGestures, free with g_list_free() a #GtkGesture Returns the last event that was processed for @sequence. Note that the returned pointer is only valid as long as the @sequence is still interpreted by the @gesture. If in doubt, you should make a copy of the event. The last event from @sequence a #GtkGesture a #GdkEventSequence Returns the #GdkEventSequence that was last updated on @gesture. The last updated sequence a #GtkGesture If @sequence is currently being interpreted by @gesture, this function returns %TRUE and fills in @x and @y with the last coordinates stored for that event sequence. The coordinates are always relative to the widget allocation. %TRUE if @sequence is currently interpreted a #GtkGesture a #GdkEventSequence, or %NULL for pointer events return location for X axis of the sequence coordinates return location for Y axis of the sequence coordinates Returns the @sequence state, as seen by @gesture. The sequence state in @gesture a #GtkGesture a #GdkEventSequence Returns the list of #GdkEventSequences currently being interpreted by @gesture. A list of #GdkEventSequences, the list elements are owned by GTK+ and must not be freed or modified, the list itself must be deleted through g_list_free() a #GtkGesture Returns the user-defined window that receives the events handled by @gesture. See gtk_gesture_set_window() for more information. the user defined window, or %NULL if none a #GtkGesture Adds @gesture to the same group than @group_gesture. Gestures are by default isolated in their own groups. When gestures are grouped, the state of #GdkEventSequences is kept in sync for all of those, so calling gtk_gesture_set_sequence_state(), on one will transfer the same value to the others. Groups also perform an "implicit grabbing" of sequences, if a #GdkEventSequence state is set to #GTK_EVENT_SEQUENCE_CLAIMED on one group, every other gesture group attached to the same #GtkWidget will switch the state for that sequence to #GTK_EVENT_SEQUENCE_DENIED. #GtkGesture to group @gesture with a #GtkGesture Returns %TRUE if @gesture is currently handling events corresponding to @sequence. %TRUE if @gesture is handling @sequence, %FALSE otherwise a #GtkGesture a #GdkEventSequence or %NULL Returns %TRUE if the gesture is currently active. A gesture is active meanwhile there are touch sequences interacting with it. %TRUE if gesture is active a #GtkGesture Returns %TRUE if both gestures pertain to the same group. whether the gestures are grouped a #GtkGesture another #GtkGesture Returns %TRUE if the gesture is currently recognized. A gesture is recognized if there are as many interacting touch sequences as required by @gesture, and #GtkGesture::check returned %TRUE for the sequences being currently interpreted. %TRUE if gesture is recognized a #GtkGesture Sets the state of @sequence in @gesture. Sequences start in state #GTK_EVENT_SEQUENCE_NONE, and whenever they change state, they can never go back to that state. Likewise, sequences in state #GTK_EVENT_SEQUENCE_DENIED cannot turn back to a not denied state. With these rules, the lifetime of an event sequence is constrained to the next four: * None * None → Denied * None → Claimed * None → Claimed → Denied Note: Due to event handling ordering, it may be unsafe to set the state on another gesture within a #GtkGesture::begin signal handler, as the callback might be executed before the other gesture knows about the sequence. A safe way to perform this could be: |[ static void first_gesture_begin_cb (GtkGesture *first_gesture, GdkEventSequence *sequence, gpointer user_data) { gtk_gesture_set_sequence_state (first_gesture, sequence, GTK_EVENT_SEQUENCE_CLAIMED); gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED); } static void second_gesture_begin_cb (GtkGesture *second_gesture, GdkEventSequence *sequence, gpointer user_data) { if (gtk_gesture_get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_CLAIMED) gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED); } ]| If both gestures are in the same group, just set the state on the gesture emitting the event, the sequence will be already be initialized to the group's global state when the second gesture processes the event. %TRUE if @sequence is handled by @gesture, and the state is changed successfully a #GtkGesture a #GdkEventSequence the sequence state Sets the state of all sequences that @gesture is currently interacting with. See gtk_gesture_set_sequence_state() for more details on sequence states. %TRUE if the state of at least one sequence was changed successfully a #GtkGesture the sequence state Sets a specific window to receive events about, so @gesture will effectively handle only events targeting @window, or a child of it. @window must pertain to gtk_event_controller_get_widget(). a #GtkGesture a #GdkWindow, or %NULL Separates @gesture into an isolated group. a #GtkGesture The number of touch points that trigger recognition on this gesture, If non-%NULL, the gesture will only listen for events that happen on this #GdkWindow, or a child of it. This signal is emitted when the gesture is recognized. This means the number of touch sequences matches #GtkGesture:n-points, and the #GtkGesture::check handler(s) returned #TRUE. Note: These conditions may also happen when an extra touch (eg. a third touch on a 2-touches gesture) is lifted, in that situation @sequence won't pertain to the current set of active touches, so don't rely on this being true. the #GdkEventSequence that made the gesture to be recognized This signal is emitted whenever a sequence is cancelled. This usually happens on active touches when gtk_event_controller_reset() is called on @gesture (manually, due to grabs...), or the individual @sequence was claimed by parent widgets' controllers (see gtk_gesture_set_sequence_state()). @gesture must forget everything about @sequence as a reaction to this signal. the #GdkEventSequence that was cancelled This signal is emitted when @gesture either stopped recognizing the event sequences as something to be handled (the #GtkGesture::check handler returned %FALSE), or the number of touch sequences became higher or lower than #GtkGesture:n-points. Note: @sequence might not pertain to the group of sequences that were previously triggering recognition on @gesture (ie. a just pressed touch sequence that exceeds #GtkGesture:n-points). This situation may be detected by checking through gtk_gesture_handles_sequence(). the #GdkEventSequence that made gesture recognition to finish This signal is emitted whenever a sequence state changes. See gtk_gesture_set_sequence_state() to know more about the expectable sequence lifetimes. the #GdkEventSequence that was cancelled the new sequence state This signal is emitted whenever an event is handled while the gesture is recognized. @sequence is guaranteed to pertain to the set of active touches. the #GdkEventSequence that was updated #GtkGestureDrag is a #GtkGesture implementation that recognizes drag operations. The drag operation itself can be tracked throught the #GtkGestureDrag::drag-begin, #GtkGestureDrag::drag-update and #GtkGestureDrag::drag-end signals, or the relevant coordinates be extracted through gtk_gesture_drag_get_offset() and gtk_gesture_drag_get_start_point(). Returns a newly created #GtkGesture that recognizes drags. a newly created #GtkGestureDrag a #GtkWidget If the @gesture is active, this function returns %TRUE and fills in @x and @y with the coordinates of the current point, as an offset to the starting drag point. %TRUE if the gesture is active a #GtkGesture X offset for the current point Y offset for the current point If the @gesture is active, this function returns %TRUE and fills in @x and @y with the drag start coordinates, in window-relative coordinates. %TRUE if the gesture is active a #GtkGesture X coordinate for the drag start point Y coordinate for the drag start point This signal is emitted whenever dragging starts. X coordinate, relative to the widget allocation Y coordinate, relative to the widget allocation This signal is emitted whenever the dragging is finished. X offset, relative to the start point Y offset, relative to the start point This signal is emitted whenever the dragging point moves. X offset, relative to the start point Y offset, relative to the start point #GtkGestureLongPress is a #GtkGesture implementation able to recognize long presses, triggering the #GtkGestureLongPress::pressed after the timeout is exceeded. If the touchpoint is lifted before the timeout passes, or if it drifts too far of the initial press point, the #GtkGestureLongPress::cancelled signal will be emitted. Returns a newly created #GtkGesture that recognizes long presses. a newly created #GtkGestureLongPress a #GtkWidget This signal is emitted whenever a press moved too far, or was released before #GtkGestureLongPress::pressed happened. This signal is emitted whenever a press goes unmoved/unreleased longer than what the GTK+ defaults tell. the X coordinate where the press happened, relative to the widget allocation the Y coordinate where the press happened, relative to the widget allocation #GtkGestureMultiPress is a #GtkGesture implementation able to recognize multiple clicks on a nearby zone, which can be listened for through the #GtkGestureMultiPress::pressed signal. Whenever time or distance between clicks exceed the GTK+ defaults, #GtkGestureMultiPress::stopped is emitted, and the click counter is reset. Callers may also restrict the area that is considered valid for a >1 touch/button press through gtk_gesture_multi_press_set_area(), so any click happening outside that area is considered to be a first click of its own. Returns a newly created #GtkGesture that recognizes single and multiple presses. a newly created #GtkGestureMultiPress a #GtkWidget If an area was set through gtk_gesture_multi_press_set_area(), this function will return %TRUE and fill in @rect with the press area. See gtk_gesture_multi_press_set_area() for more details on what the press area represents. %TRUE if @rect was filled with the press area a #GtkGestureMultiPress return location for the press area If @rect is non-%NULL, the press area will be checked to be confined within the rectangle, otherwise the button count will be reset so the press is seen as being the first one. If @rect is %NULL, the area will be reset to an unrestricted state. Note: The rectangle is only used to determine whether any non-first click falls within the expected area. This is not akin to an input shape. a #GtkGestureMultiPress rectangle to receive coordinates on This signal is emitted whenever a button or touch press happens. how many touch/button presses happened with this one The X coordinate, in widget allocation coordinates The Y coordinate, in widget allocation coordinates This signal is emitted when a button or touch is released. @n_press will report the number of press that is paired to this event, note that #GtkGestureMultiPress::stopped may have been emitted between the press and its release, @n_press will only start over at the next press. number of press that is paired with this release The X coordinate, in widget allocation coordinates The Y coordinate, in widget allocation coordinates This signal is emitted whenever any time/distance threshold has been exceeded. #GtkGesturePan is a #GtkGesture implementation able to recognize pan gestures, those are drags that are locked to happen along one axis. The axis that a #GtkGesturePan handles is defined at construct time, and can be changed through gtk_gesture_pan_set_orientation(). When the gesture starts to be recognized, #GtkGesturePan will attempt to determine as early as possible whether the sequence is moving in the expected direction, and denying the sequence if this does not happen. Once a panning gesture along the expected axis is recognized, the #GtkGesturePan::pan signal will be emitted as input events are received, containing the offset in the given axis. Returns a newly created #GtkGesture that recognizes pan gestures. a newly created #GtkGesturePan a #GtkWidget expected orientation Returns the orientation of the pan gestures that this @gesture expects. the expected orientation for pan gestures A #GtkGesturePan Sets the orientation to be expected on pan gestures. A #GtkGesturePan expected orientation The expected orientation of pan gestures. This signal is emitted once a panning gesture along the expected axis is detected. current direction of the pan gesture Offset along the gesture orientation #GtkGestureRotate is a #GtkGesture implementation able to recognize 2-finger rotations, whenever the angle between both handled sequences changes, the #GtkGestureRotate::angle-changed signal is emitted. Returns a newly created #GtkGesture that recognizes 2-touch rotation gestures. a newly created #GtkGestureRotate a #GtkWidget If @gesture is active, this function returns the angle difference in radians since the gesture was first recognized. If @gesture is not active, 0 is returned. the angle delta in radians a #GtkGestureRotate This signal is emitted when the angle between both tracked points changes. Current angle in radians Difference with the starting angle, in radians #GtkGestureSingle is a subclass of #GtkGesture, optimized (although not restricted) for dealing with mouse and single-touch gestures. Under interaction, these gestures stick to the first interacting sequence, which is accessible through gtk_gesture_single_get_current_sequence() while the gesture is being interacted with. By default gestures react to both %GDK_BUTTON_PRIMARY and touch events, gtk_gesture_single_set_touch_only() can be used to change the touch behavior. Callers may also specify a different mouse button number to interact with through gtk_gesture_single_set_button(), or react to any mouse button by setting 0. While the gesture is active, the button being currently pressed can be known through gtk_gesture_single_get_current_button(). Returns the button number @gesture listens for, or 0 if @gesture reacts to any button press. The button number, or 0 for any button a #GtkGestureSingle Returns the button number currently interacting with @gesture, or 0 if there is none. The current button number a #GtkGestureSingle Returns the event sequence currently interacting with @gesture. This is only meaningful if gtk_gesture_is_active() returns %TRUE. the current sequence a #GtkGestureSingle Gets whether a gesture is exclusive. For more information, see gtk_gesture_single_set_exclusive(). Whether the gesture is exclusive a #GtkGestureSingle Returns %TRUE if the gesture is only triggered by touch events. %TRUE if the gesture only handles touch events a #GtkGestureSingle Sets the button number @gesture listens to. If non-0, every button press from a different button number will be ignored. Touch events implicitly match with button 1. a #GtkGestureSingle button number to listen to, or 0 for any button Sets whether @gesture is exclusive. An exclusive gesture will only handle pointer and "pointer emulated" touch events, so at any given time, there is only one sequence able to interact with those. a #GtkGestureSingle %TRUE to make @gesture exclusive If @touch_only is %TRUE, @gesture will only handle events of type #GDK_TOUCH_BEGIN, #GDK_TOUCH_UPDATE or #GDK_TOUCH_END. If %FALSE, mouse events will be handled too. a #GtkGestureSingle whether @gesture handles only touch events Mouse button number to listen to, or 0 to listen for any button. Whether the gesture is exclusive. Exclusive gestures only listen to pointer and pointer emulated events. Whether the gesture handles only touch events. #GtkGestureStylus is a #GtkGesture implementation specific to stylus input. The provided signals just provide the basic information Creates a new #GtkGestureStylus. a newly created stylus gesture a #GtkWidget Returns the current values for the requested @axes. This function must be called from either the #GtkGestureStylus:down, #GtkGestureStylus:motion, #GtkGestureStylus:up or #GtkGestureStylus:proximity signals. #TRUE if there is a current value for the axes a GtkGestureStylus array of requested axes, terminated with #GDK_AXIS_IGNORE return location for the axis values Returns the current value for the requested @axis. This function must be called from either the #GtkGestureStylus:down, #GtkGestureStylus:motion, #GtkGestureStylus:up or #GtkGestureStylus:proximity signals. #TRUE if there is a current value for the axis a #GtkGestureStylus requested device axis return location for the axis value Returns the #GdkDeviceTool currently driving input through this gesture. This function must be called from either the #GtkGestureStylus::down, #GtkGestureStylus::motion, #GtkGestureStylus::up or #GtkGestureStylus::proximity signal handlers. The current stylus tool a #GtkGestureStylus #GtkGestureSwipe is a #GtkGesture implementation able to recognize swipes, after a press/move/.../move/release sequence happens, the #GtkGestureSwipe::swipe signal will be emitted, providing the velocity and directionality of the sequence at the time it was lifted. If the velocity is desired in intermediate points, gtk_gesture_swipe_get_velocity() can be called on eg. a #GtkGesture::update handler. All velocities are reported in pixels/sec units. Returns a newly created #GtkGesture that recognizes swipes. a newly created #GtkGestureSwipe a #GtkWidget If the gesture is recognized, this function returns %TRUE and fill in @velocity_x and @velocity_y with the recorded velocity, as per the last event(s) processed. whether velocity could be calculated a #GtkGestureSwipe return value for the velocity in the X axis, in pixels/sec return value for the velocity in the Y axis, in pixels/sec This signal is emitted when the recognized gesture is finished, velocity and direction are a product of previously recorded events. velocity in the X axis, in pixels/sec velocity in the Y axis, in pixels/sec #GtkGestureZoom is a #GtkGesture implementation able to recognize pinch/zoom gestures, whenever the distance between both tracked sequences changes, the #GtkGestureZoom::scale-changed signal is emitted to report the scale factor. Returns a newly created #GtkGesture that recognizes zoom in/out gestures (usually known as pinch/zoom). a newly created #GtkGestureZoom a #GtkWidget If @gesture is active, this function returns the zooming difference since the gesture was recognized (hence the starting point is considered 1:1). If @gesture is not active, 1 is returned. the scale delta a #GtkGestureZoom This signal is emitted whenever the distance between both tracked sequences changes. Scale delta, taking the initial state as 1:1 GtkGradient is a boxed type that represents a gradient. It is the result of parsing a [gradient expression][gtkcssprovider-gradients]. To obtain the gradient represented by a GtkGradient, it has to be resolved with gtk_gradient_resolve(), which replaces all symbolic color references by the colors they refer to (in a given context) and constructs a #cairo_pattern_t value. It is not normally necessary to deal directly with #GtkGradients, since they are mostly used behind the scenes by #GtkStyleContext and #GtkCssProvider. #GtkGradient is deprecated. It was used internally by GTK’s CSS engine to represent gradients. As its handling is not conforming to modern web standards, it is not used anymore. If you want to use gradients in your own code, please use Cairo directly. Creates a new linear gradient along the line defined by (x0, y0) and (x1, y1). Before using the gradient a number of stop colors must be added through gtk_gradient_add_color_stop(). #GtkGradient is deprecated. A newly created #GtkGradient X coordinate of the starting point Y coordinate of the starting point X coordinate of the end point Y coordinate of the end point Creates a new radial gradient along the two circles defined by (x0, y0, radius0) and (x1, y1, radius1). Before using the gradient a number of stop colors must be added through gtk_gradient_add_color_stop(). #GtkGradient is deprecated. A newly created #GtkGradient X coordinate of the start circle Y coordinate of the start circle radius of the start circle X coordinate of the end circle Y coordinate of the end circle radius of the end circle Adds a stop color to @gradient. #GtkGradient is deprecated. a #GtkGradient offset for the color stop color to use Increases the reference count of @gradient. #GtkGradient is deprecated. The same @gradient a #GtkGradient If @gradient is resolvable, @resolved_gradient will be filled in with the resolved gradient as a cairo_pattern_t, and %TRUE will be returned. Generally, if @gradient can’t be resolved, it is due to it being defined on top of a named color that doesn't exist in @props. #GtkGradient is deprecated. %TRUE if the gradient has been resolved a #GtkGradient #GtkStyleProperties to use when resolving named colors return location for the resolved pattern Creates a string representation for @gradient that is suitable for using in GTK CSS files. #GtkGradient is deprecated. A string representation for @gradient the gradient to print Decreases the reference count of @gradient, freeing its memory if the reference count reaches 0. #GtkGradient is deprecated. a #GtkGradient GtkGrid is a container which arranges its child widgets in rows and columns, with arbitrary positions and horizontal/vertical spans. Children are added using gtk_grid_attach(). They can span multiple rows or columns. It is also possible to add a child next to an existing child, using gtk_grid_attach_next_to(). The behaviour of GtkGrid when several children occupy the same grid cell is undefined. GtkGrid can be used like a #GtkBox by just using gtk_container_add(), which will place children next to each other in the direction determined by the #GtkOrientable:orientation property. However, if all you want is a single row or column, then #GtkBox is the preferred widget. # CSS nodes GtkGrid uses a single CSS node with name grid. Creates a new grid widget. the new #GtkGrid Adds a widget to the grid. The position of @child is determined by @left and @top. The number of “cells” that @child will occupy is determined by @width and @height. a #GtkGrid the widget to add the column number to attach the left side of @child to the row number to attach the top side of @child to the number of columns that @child will span the number of rows that @child will span Adds a widget to the grid. The widget is placed next to @sibling, on the side determined by @side. When @sibling is %NULL, the widget is placed in row (for left or right placement) or column 0 (for top or bottom placement), at the end indicated by @side. Attaching widgets labeled [1], [2], [3] with @sibling == %NULL and @side == %GTK_POS_LEFT yields a layout of [3][2][1]. a #GtkGrid the widget to add the child of @grid that @child will be placed next to, or %NULL to place @child at the beginning or end the side of @sibling that @child is positioned next to the number of columns that @child will span the number of rows that @child will span Returns which row defines the global baseline of @grid. the row index defining the global baseline a #GtkGrid Gets the child of @grid whose area covers the grid cell whose upper left corner is at @left, @top. the child at the given position, or %NULL a #GtkGrid the left edge of the cell the top edge of the cell Returns whether all columns of @grid have the same width. whether all columns of @grid have the same width. a #GtkGrid Returns the amount of space between the columns of @grid. the column spacing of @grid a #GtkGrid Returns the baseline position of @row as set by gtk_grid_set_row_baseline_position() or the default value %GTK_BASELINE_POSITION_CENTER. the baseline position of @row a #GtkGrid a row index Returns whether all rows of @grid have the same height. whether all rows of @grid have the same height. a #GtkGrid Returns the amount of space between the rows of @grid. the row spacing of @grid a #GtkGrid Inserts a column at the specified position. Children which are attached at or to the right of this position are moved one column to the right. Children which span across this position are grown to span the new column. a #GtkGrid the position to insert the column at Inserts a row or column at the specified position. The new row or column is placed next to @sibling, on the side determined by @side. If @side is %GTK_POS_TOP or %GTK_POS_BOTTOM, a row is inserted. If @side is %GTK_POS_LEFT of %GTK_POS_RIGHT, a column is inserted. a #GtkGrid the child of @grid that the new row or column will be placed next to the side of @sibling that @child is positioned next to Inserts a row at the specified position. Children which are attached at or below this position are moved one row down. Children which span across this position are grown to span the new row. a #GtkGrid the position to insert the row at Removes a column from the grid. Children that are placed in this column are removed, spanning children that overlap this column have their width reduced by one, and children after the column are moved to the left. a #GtkGrid the position of the column to remove Removes a row from the grid. Children that are placed in this row are removed, spanning children that overlap this row have their height reduced by one, and children below the row are moved up. a #GtkGrid the position of the row to remove Sets which row defines the global baseline for the entire grid. Each row in the grid can have its own local baseline, but only one of those is global, meaning it will be the baseline in the parent of the @grid. a #GtkGrid the row index Sets whether all columns of @grid will have the same width. a #GtkGrid %TRUE to make columns homogeneous Sets the amount of space between columns of @grid. a #GtkGrid the amount of space to insert between columns Sets how the baseline should be positioned on @row of the grid, in case that row is assigned more space than is requested. a #GtkGrid a row index a #GtkBaselinePosition Sets whether all rows of @grid will have the same height. a #GtkGrid %TRUE to make rows homogeneous Sets the amount of space between rows of @grid. a #GtkGrid the amount of space to insert between rows The parent class. #GtkHBox is a container that organizes child widgets into a single row. Use the #GtkBox packing interface to determine the arrangement, spacing, width, and alignment of #GtkHBox children. All children are allocated the same height. GtkHBox has been deprecated. You can use #GtkBox instead, which is a very quick and easy change. If you have derived your own classes from GtkHBox, you can simply change the inheritance to derive directly from #GtkBox. No further changes are needed, since the default value of the #GtkOrientable:orientation property is %GTK_ORIENTATION_HORIZONTAL. If you have a grid-like layout composed of nested boxes, and you don’t need first-child or last-child styling, the recommendation is to switch to #GtkGrid. For more information about migrating to #GtkGrid, see [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid]. Creates a new #GtkHBox. You should use gtk_box_new() with a %GTK_ORIENTATION_HORIZONTAL #GtkOrientable:orientation instead a new #GtkHBox. %TRUE if all children are to be given equal space allotments. the number of pixels to place by default between children. Creates a new horizontal button box. Use gtk_button_box_new() with %GTK_ORIENTATION_HORIZONTAL instead a new button box #GtkWidget. The HPaned widget is a container widget with two children arranged horizontally. The division between the two panes is adjustable by the user by dragging a handle. See #GtkPaned for details. GtkHPaned has been deprecated, use #GtkPaned instead. Create a new #GtkHPaned Use gtk_paned_new() with %GTK_ORIENTATION_HORIZONTAL instead the new #GtkHPaned #GtkHSV is the “color wheel” part of a complete color selector widget. It allows to select a color by determining its HSV components in an intuitive way. Moving the selection around the outer ring changes the hue, and moving the selection point inside the inner triangle changes value and saturation. #GtkHSV has been deprecated together with #GtkColorSelection, where it was used. Creates a new HSV color selector. A newly-created HSV color selector. Converts a color from HSV space to RGB. Input values must be in the [0.0, 1.0] range; output values will be in the same range. Hue Saturation Value Return value for the red component Return value for the green component Return value for the blue component Queries the current color in an HSV color selector. Returned values will be in the [0.0, 1.0] range. An HSV color selector Return value for the hue Return value for the saturation Return value for the value Queries the size and ring width of an HSV color selector. An HSV color selector Return value for the diameter of the hue ring Return value for the width of the hue ring An HSV color selector can be said to be adjusting if multiple rapid changes are being made to its value, for example, when the user is adjusting the value with the mouse. This function queries whether the HSV color selector is being adjusted or not. %TRUE if clients can ignore changes to the color value, since they may be transitory, or %FALSE if they should consider the color value status to be final. A #GtkHSV Sets the current color in an HSV color selector. Color component values must be in the [0.0, 1.0] range. An HSV color selector Hue Saturation Value Sets the size and ring width of an HSV color selector. An HSV color selector Diameter for the hue ring Width of the hue ring The #GtkHScale widget is used to allow the user to select a value using a horizontal slider. To create one, use gtk_hscale_new_with_range(). The position to show the current value, and the number of decimal places shown can be set using the parent #GtkScale class’s functions. GtkHScale has been deprecated, use #GtkScale instead. Creates a new #GtkHScale. Use gtk_scale_new() with %GTK_ORIENTATION_HORIZONTAL instead a new #GtkHScale. the #GtkAdjustment which sets the range of the scale. Creates a new horizontal scale widget that lets the user input a number between @min and @max (including @min and @max) with the increment @step. @step must be nonzero; it’s the distance the slider moves when using the arrow keys to adjust the scale value. Note that the way in which the precision is derived works best if @step is a power of ten. If the resulting precision is not suitable for your needs, use gtk_scale_set_digits() to correct it. Use gtk_scale_new_with_range() with %GTK_ORIENTATION_HORIZONTAL instead a new #GtkHScale minimum value maximum value step increment (tick size) used with keyboard shortcuts The #GtkHScrollbar widget is a widget arranged horizontally creating a scrollbar. See #GtkScrollbar for details on scrollbars. #GtkAdjustment pointers may be added to handle the adjustment of the scrollbar or it may be left %NULL in which case one will be created for you. See #GtkScrollbar for a description of what the fields in an adjustment represent for a scrollbar. GtkHScrollbar has been deprecated, use #GtkScrollbar instead. Creates a new horizontal scrollbar. Use gtk_scrollbar_new() with %GTK_ORIENTATION_HORIZONTAL instead the new #GtkHScrollbar the #GtkAdjustment to use, or %NULL to create a new adjustment The #GtkHSeparator widget is a horizontal separator, used to group the widgets within a window. It displays a horizontal line with a shadow to make it appear sunken into the interface. > The #GtkHSeparator widget is not used as a separator within menus. > To create a separator in a menu create an empty #GtkSeparatorMenuItem > widget using gtk_separator_menu_item_new() and add it to the menu with > gtk_menu_shell_append(). GtkHSeparator has been deprecated, use #GtkSeparator instead. Creates a new #GtkHSeparator. Use gtk_separator_new() with %GTK_ORIENTATION_HORIZONTAL instead a new #GtkHSeparator. The #GtkHandleBox widget allows a portion of a window to be "torn off". It is a bin widget which displays its child and a handle that the user can drag to tear off a separate window (the “float window”) containing the child widget. A thin “ghost” is drawn in the original location of the handlebox. By dragging the separate window back to its original location, it can be reattached. When reattaching, the ghost and float window, must be aligned along one of the edges, the “snap edge”. This either can be specified by the application programmer explicitly, or GTK+ will pick a reasonable default based on the handle position. To make detaching and reattaching the handlebox as minimally confusing as possible to the user, it is important to set the snap edge so that the snap edge does not move when the handlebox is deattached. For instance, if the handlebox is packed at the bottom of a VBox, then when the handlebox is detached, the bottom edge of the handlebox's allocation will remain fixed as the height of the handlebox shrinks, so the snap edge should be set to %GTK_POS_BOTTOM. > #GtkHandleBox has been deprecated. It is very specialized, lacks features > to make it useful and most importantly does not fit well into modern > application design. Do not use it. There is no replacement. Create a new handle box. #GtkHandleBox has been deprecated. a new #GtkHandleBox. Signal emitted when the contents of the handlebox are reattached to the main window. Deprecated: 3.4. Signal emitted when the contents of the handlebox are detached from the main window. Deprecated: 3.4. Whether the handlebox’s child is currently detached. #GtkHandleBox has been deprecated. %TRUE if the child is currently detached, otherwise %FALSE a #GtkHandleBox Gets the handle position of the handle box. See gtk_handle_box_set_handle_position(). #GtkHandleBox has been deprecated. the current handle position. a #GtkHandleBox Gets the type of shadow drawn around the handle box. See gtk_handle_box_set_shadow_type(). #GtkHandleBox has been deprecated. the type of shadow currently drawn around the handle box. a #GtkHandleBox Gets the edge used for determining reattachment of the handle box. See gtk_handle_box_set_snap_edge(). #GtkHandleBox has been deprecated. the edge used for determining reattachment, or (GtkPositionType)-1 if this is determined (as per default) from the handle position. a #GtkHandleBox Sets the side of the handlebox where the handle is drawn. #GtkHandleBox has been deprecated. a #GtkHandleBox the side of the handlebox where the handle should be drawn. Sets the type of shadow to be drawn around the border of the handle box. #GtkHandleBox has been deprecated. a #GtkHandleBox the shadow type. Sets the snap edge of a handlebox. The snap edge is the edge of the detached child that must be aligned with the corresponding edge of the “ghost” left behind when the child was detached to reattach the torn-off window. Usually, the snap edge should be chosen so that it stays in the same place on the screen when the handlebox is torn off. If the snap edge is not set, then an appropriate value will be guessed from the handle position. If the handle position is %GTK_POS_RIGHT or %GTK_POS_LEFT, then the snap edge will be %GTK_POS_TOP, otherwise it will be %GTK_POS_LEFT. #GtkHandleBox has been deprecated. a #GtkHandleBox the snap edge, or -1 to unset the value; in which case GTK+ will try to guess an appropriate value in the future. This signal is emitted when the contents of the handlebox are reattached to the main window. #GtkHandleBox has been deprecated. the child widget of the handlebox. (this argument provides no extra information and is here only for backwards-compatibility) This signal is emitted when the contents of the handlebox are detached from the main window. #GtkHandleBox has been deprecated. the child widget of the handlebox. (this argument provides no extra information and is here only for backwards-compatibility) The parent class. Signal emitted when the contents of the handlebox are reattached to the main window. Deprecated: 3.4. Signal emitted when the contents of the handlebox are detached from the main window. Deprecated: 3.4. GtkHeaderBar is similar to a horizontal #GtkBox. It allows children to be placed at the start or the end. In addition, it allows a title and subtitle to be displayed. The title will be centered with respect to the width of the box, even if the children at either side take up different amounts of space. The height of the titlebar will be set to provide sufficient space for the subtitle, even if none is currently set. If a subtitle is not needed, the space reservation can be turned off with gtk_header_bar_set_has_subtitle(). GtkHeaderBar can add typical window frame controls, such as minimize, maximize and close buttons, or the window icon. For these reasons, GtkHeaderBar is the natural choice for use as the custom titlebar widget of a #GtkWindow (see gtk_window_set_titlebar()), as it gives features typical of titlebars while allowing the addition of child widgets. Creates a new #GtkHeaderBar widget. a new #GtkHeaderBar Retrieves the custom title widget of the header. See gtk_header_bar_set_custom_title(). the custom title widget of the header, or %NULL if none has been set explicitly. a #GtkHeaderBar Gets the decoration layout set with gtk_header_bar_set_decoration_layout(). the decoration layout a #GtkHeaderBar Retrieves whether the header bar reserves space for a subtitle, regardless if one is currently set or not. %TRUE if the header bar reserves space for a subtitle a #GtkHeaderBar Returns whether this header bar shows the standard window decorations. %TRUE if the decorations are shown a #GtkHeaderBar Retrieves the subtitle of the header. See gtk_header_bar_set_subtitle(). the subtitle of the header, or %NULL if none has been set explicitly. The returned string is owned by the widget and must not be modified or freed. a #GtkHeaderBar Retrieves the title of the header. See gtk_header_bar_set_title(). the title of the header, or %NULL if none has been set explicitly. The returned string is owned by the widget and must not be modified or freed. a #GtkHeaderBar Adds @child to @bar, packed with reference to the end of the @bar. A #GtkHeaderBar the #GtkWidget to be added to @bar Adds @child to @bar, packed with reference to the start of the @bar. A #GtkHeaderBar the #GtkWidget to be added to @bar Sets a custom title for the #GtkHeaderBar. The title should help a user identify the current view. This supersedes any title set by gtk_header_bar_set_title() or gtk_header_bar_set_subtitle(). To achieve the same style as the builtin title and subtitle, use the “title” and “subtitle” style classes. You should set the custom title to %NULL, for the header title label to be visible again. a #GtkHeaderBar a custom widget to use for a title Sets the decoration layout for this header bar, overriding the #GtkSettings:gtk-decoration-layout setting. There can be valid reasons for overriding the setting, such as a header bar design that does not allow for buttons to take room on the right, or only offers room for a single close button. Split header bars are another example for overriding the setting. The format of the string is button names, separated by commas. A colon separates the buttons that should appear on the left from those on the right. Recognized button names are minimize, maximize, close, icon (the window icon) and menu (a menu button for the fallback app menu). For example, “menu:minimize,maximize,close” specifies a menu on the left, and minimize, maximize and close buttons on the right. a #GtkHeaderBar a decoration layout, or %NULL to unset the layout Sets whether the header bar should reserve space for a subtitle, even if none is currently set. a #GtkHeaderBar %TRUE to reserve space for a subtitle Sets whether this header bar shows the standard window decorations, including close, maximize, and minimize. a #GtkHeaderBar %TRUE to show standard window decorations Sets the subtitle of the #GtkHeaderBar. The title should give a user an additional detail to help him identify the current view. Note that GtkHeaderBar by default reserves room for the subtitle, even if none is currently set. If this is not desired, set the #GtkHeaderBar:has-subtitle property to %FALSE. a #GtkHeaderBar a subtitle, or %NULL Sets the title of the #GtkHeaderBar. The title should help a user identify the current view. A good title should not include the application name. a #GtkHeaderBar a title, or %NULL The decoration layout for buttons. If this property is not set, the #GtkSettings:gtk-decoration-layout setting is used. See gtk_header_bar_set_decoration_layout() for information about the format of this string. Set to %TRUE if #GtkHeaderBar:decoration-layout is set. If %TRUE, reserve space for a subtitle, even if none is currently set. Whether to show window decorations. Which buttons are actually shown and where is determined by the #GtkHeaderBar:decoration-layout property, and by the state of the window (e.g. a close button will not be shown if the window can't be closed). #GtkIMContext defines the interface for GTK+ input methods. An input method is used by GTK+ text input widgets like #GtkEntry to map from key events to Unicode character strings. The default input method can be set programmatically via the #GtkSettings:gtk-im-module GtkSettings property. Alternatively, you may set the GTK_IM_MODULE environment variable as documented in [Running GTK+ Applications][gtk-running]. The #GtkEntry #GtkEntry:im-module and #GtkTextView #GtkTextView:im-module properties may also be used to set input methods for specific widget instances. For instance, a certain entry widget might be expected to contain certain characters which would be easier to input with a certain input method. An input method may consume multiple key events in sequence and finally output the composed result. This is called preediting, and an input method may provide feedback about this process by displaying the intermediate composition states as preedit text. For instance, the default GTK+ input method implements the input of arbitrary Unicode code points by holding down the Control and Shift keys and then typing “U” followed by the hexadecimal digits of the code point. When releasing the Control and Shift keys, preediting ends and the character is inserted as text. Ctrl+Shift+u20AC for example results in the € sign. Additional input methods can be made available for use by GTK+ widgets as loadable modules. An input method module is a small shared library which implements a subclass of #GtkIMContext or #GtkIMContextSimple and exports these four functions: |[<!-- language="C" --> void im_module_init(GTypeModule *module); ]| This function should register the #GType of the #GtkIMContext subclass which implements the input method by means of g_type_module_register_type(). Note that g_type_register_static() cannot be used as the type needs to be registered dynamically. |[<!-- language="C" --> void im_module_exit(void); ]| Here goes any cleanup code your input method might require on module unload. |[<!-- language="C" --> void im_module_list(const GtkIMContextInfo ***contexts, int *n_contexts) { *contexts = info_list; *n_contexts = G_N_ELEMENTS (info_list); } ]| This function returns the list of input methods provided by the module. The example implementation above shows a common solution and simply returns a pointer to statically defined array of #GtkIMContextInfo items for each provided input method. |[<!-- language="C" --> GtkIMContext * im_module_create(const gchar *context_id); ]| This function should return a pointer to a newly created instance of the #GtkIMContext subclass identified by @context_id. The context ID is the same as specified in the #GtkIMContextInfo array returned by im_module_list(). After a new loadable input method module has been installed on the system, the configuration file `gtk.immodules` needs to be regenerated by [gtk-query-immodules-3.0][gtk-query-immodules-3.0], in order for the new input method to become available to GTK+ applications. Default handler of the #GtkIMContext::commit signal. Asks the widget that the input context is attached to to delete characters around the cursor position by emitting the GtkIMContext::delete_surrounding signal. Note that @offset and @n_chars are in characters not in bytes which differs from the usage other places in #GtkIMContext. In order to use this function, you should first call gtk_im_context_get_surrounding() to get the current context, and call this function immediately afterwards to make sure that you know what you are deleting. You should also account for the fact that even if the signal was handled, the input context might not have deleted all the characters that were requested to be deleted. This function is used by an input method that wants to make subsitutions in the existing text in response to new input. It is not useful for applications. %TRUE if the signal was handled. a #GtkIMContext offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. Allow an input method to internally handle key press and release events. If this function returns %TRUE, then no further processing should be done for this key event. %TRUE if the input method handled the key event. a #GtkIMContext the key event Notify the input method that the widget to which this input context corresponds has gained focus. The input method may, for example, change the displayed feedback to reflect this change. a #GtkIMContext Notify the input method that the widget to which this input context corresponds has lost focus. The input method may, for example, change the displayed feedback or reset the contexts state to reflect this change. a #GtkIMContext Retrieve the current preedit string for the input context, and a list of attributes to apply to the string. This string should be displayed inserted at the insertion point. a #GtkIMContext location to store the retrieved string. The string retrieved must be freed with g_free(). location to store the retrieved attribute list. When you are done with this list, you must unreference it with pango_attr_list_unref(). location to store position of cursor (in characters) within the preedit string. Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai where only some sequences of characters are allowed. This function is implemented by emitting the GtkIMContext::retrieve_surrounding signal on the input method; in response to this signal, a widget should provide as much context as is available, up to an entire paragraph, by calling gtk_im_context_set_surrounding(). Note that there is no obligation for a widget to respond to the ::retrieve_surrounding signal, so input methods must be prepared to function without context. %TRUE if surrounding text was provided; in this case you must free the result stored in *text. a #GtkIMContext location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. Default handler of the #GtkIMContext::preedit-changed signal. Default handler of the #GtkIMContext::preedit-end signal. Default handler of the #GtkIMContext::preedit-start signal. Notify the input method that a change such as a change in cursor position has been made. This will typically cause the input method to clear the preedit state. a #GtkIMContext Default handler of the #GtkIMContext::retrieve-surrounding signal. Set the client window for the input context; this is the #GdkWindow in which the input appears. This window is used in order to correctly position status windows, and may also be used for purposes internal to the input method. a #GtkIMContext the client window. This may be %NULL to indicate that the previous client window no longer exists. Notify the input method that a change in cursor position has been made. The location is relative to the client window. a #GtkIMContext new location Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the GtkIMContext::retrieve_surrounding signal, and will likely have no effect if called at other times. a #GtkIMContext text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text. the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. Sets whether the IM context should use the preedit string to display feedback. If @use_preedit is FALSE (default is TRUE), then the IM context may use some other method to display feedback, such as displaying it in a child of the root window. a #GtkIMContext whether the IM context should use the preedit string. Asks the widget that the input context is attached to to delete characters around the cursor position by emitting the GtkIMContext::delete_surrounding signal. Note that @offset and @n_chars are in characters not in bytes which differs from the usage other places in #GtkIMContext. In order to use this function, you should first call gtk_im_context_get_surrounding() to get the current context, and call this function immediately afterwards to make sure that you know what you are deleting. You should also account for the fact that even if the signal was handled, the input context might not have deleted all the characters that were requested to be deleted. This function is used by an input method that wants to make subsitutions in the existing text in response to new input. It is not useful for applications. %TRUE if the signal was handled. a #GtkIMContext offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. Allow an input method to internally handle key press and release events. If this function returns %TRUE, then no further processing should be done for this key event. %TRUE if the input method handled the key event. a #GtkIMContext the key event Notify the input method that the widget to which this input context corresponds has gained focus. The input method may, for example, change the displayed feedback to reflect this change. a #GtkIMContext Notify the input method that the widget to which this input context corresponds has lost focus. The input method may, for example, change the displayed feedback or reset the contexts state to reflect this change. a #GtkIMContext Retrieve the current preedit string for the input context, and a list of attributes to apply to the string. This string should be displayed inserted at the insertion point. a #GtkIMContext location to store the retrieved string. The string retrieved must be freed with g_free(). location to store the retrieved attribute list. When you are done with this list, you must unreference it with pango_attr_list_unref(). location to store position of cursor (in characters) within the preedit string. Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai where only some sequences of characters are allowed. This function is implemented by emitting the GtkIMContext::retrieve_surrounding signal on the input method; in response to this signal, a widget should provide as much context as is available, up to an entire paragraph, by calling gtk_im_context_set_surrounding(). Note that there is no obligation for a widget to respond to the ::retrieve_surrounding signal, so input methods must be prepared to function without context. %TRUE if surrounding text was provided; in this case you must free the result stored in *text. a #GtkIMContext location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. Notify the input method that a change such as a change in cursor position has been made. This will typically cause the input method to clear the preedit state. a #GtkIMContext Set the client window for the input context; this is the #GdkWindow in which the input appears. This window is used in order to correctly position status windows, and may also be used for purposes internal to the input method. a #GtkIMContext the client window. This may be %NULL to indicate that the previous client window no longer exists. Notify the input method that a change in cursor position has been made. The location is relative to the client window. a #GtkIMContext new location Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the GtkIMContext::retrieve_surrounding signal, and will likely have no effect if called at other times. a #GtkIMContext text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text. the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. Sets whether the IM context should use the preedit string to display feedback. If @use_preedit is FALSE (default is TRUE), then the IM context may use some other method to display feedback, such as displaying it in a child of the root window. a #GtkIMContext whether the IM context should use the preedit string. The ::commit signal is emitted when a complete input sequence has been entered by the user. This can be a single character immediately after a key press or the final result of preediting. the completed character(s) entered by the user The ::delete-surrounding signal is emitted when the input method needs to delete all or part of the context surrounding the cursor. %TRUE if the signal was handled. the character offset from the cursor position of the text to be deleted. A negative value indicates a position before the cursor. the number of characters to be deleted The ::preedit-changed signal is emitted whenever the preedit sequence currently being entered has changed. It is also emitted at the end of a preedit sequence, in which case gtk_im_context_get_preedit_string() returns the empty string. The ::preedit-end signal is emitted when a preediting sequence has been completed or canceled. The ::preedit-start signal is emitted when a new preediting sequence starts. The ::retrieve-surrounding signal is emitted when the input method requires the context surrounding the cursor. The callback should set the input method surrounding context by calling the gtk_im_context_set_surrounding() method. %TRUE if the signal was handled. Default handler of the #GtkIMContext::preedit-start signal. Default handler of the #GtkIMContext::preedit-end signal. Default handler of the #GtkIMContext::preedit-changed signal. Default handler of the #GtkIMContext::commit signal. Default handler of the #GtkIMContext::retrieve-surrounding signal. Default handler of the #GtkIMContext::delete-surrounding signal. %TRUE if the signal was handled. a #GtkIMContext offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. Called via gtk_im_context_set_client_window() when the input window where the entered text will appear changes. Override this to keep track of the current input window, for instance for the purpose of positioning a status display of your input method. a #GtkIMContext the client window. This may be %NULL to indicate that the previous client window no longer exists. Called via gtk_im_context_get_preedit_string() to retrieve the text currently being preedited for display at the cursor position. Any input method which composes complex characters or any other compositions from multiple sequential key presses should override this method to provide feedback. a #GtkIMContext location to store the retrieved string. The string retrieved must be freed with g_free(). location to store the retrieved attribute list. When you are done with this list, you must unreference it with pango_attr_list_unref(). location to store position of cursor (in characters) within the preedit string. Called via gtk_im_context_filter_keypress() on every key press or release event. Every non-trivial input method needs to override this in order to implement the mapping from key events to text. A return value of %TRUE indicates to the caller that the event was consumed by the input method. In that case, the #GtkIMContext::commit signal should be emitted upon completion of a key sequence to pass the resulting text back to the input widget. Alternatively, %FALSE may be returned to indicate that the event wasn’t handled by the input method. If a builtin mapping exists for the key, it is used to produce a character. %TRUE if the input method handled the key event. a #GtkIMContext the key event Called via gtk_im_context_focus_in() when the input widget has gained focus. May be overridden to keep track of the current focus. a #GtkIMContext Called via gtk_im_context_focus_out() when the input widget has lost focus. May be overridden to keep track of the current focus. a #GtkIMContext Called via gtk_im_context_reset() to signal a change such as a change in cursor position. An input method that implements preediting should override this method to clear the preedit state on reset. a #GtkIMContext Called via gtk_im_context_set_cursor_location() to inform the input method of the current cursor location relative to the client window. May be overridden to implement the display of popup windows at the cursor position. a #GtkIMContext new location Called via gtk_im_context_set_use_preedit() to control the use of the preedit string. Override this to display feedback by some other means if turned off. a #GtkIMContext whether the IM context should use the preedit string. Called via gtk_im_context_set_surrounding() in response to signal #GtkIMContext::retrieve-surrounding to update the input method’s idea of the context around the cursor. It is not necessary to override this method even with input methods which implement context-dependent behavior. The base implementation is sufficient for gtk_im_context_get_surrounding() to work. a #GtkIMContext text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text. the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. Called via gtk_im_context_get_surrounding() to update the context around the cursor location. It is not necessary to override this method even with input methods which implement context-dependent behavior. The base implementation emits #GtkIMContext::retrieve-surrounding and records the context received by the subsequent invocation of @get_surrounding. %TRUE if surrounding text was provided; in this case you must free the result stored in *text. a #GtkIMContext location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. Bookkeeping information about a loadable input method. The unique identification string of the input method. The human-readable name of the input method. Translation domain to be used with dgettext() Name of locale directory for use with bindtextdomain() A colon-separated list of locales where this input method should be the default. The asterisk “*” sets the default for all locales. GtkIMContextSimple is a simple input method context supporting table-based input methods. It has a built-in table of compose sequences that is derived from the X11 Compose files. GtkIMContextSimple reads additional compose sequences from the first of the following files that is found: ~/.config/gtk-3.0/Compose, ~/.XCompose, /usr/share/X11/locale/$locale/Compose (for locales that have a nontrivial Compose file). The syntax of these files is described in the Compose(5) manual page. ## Unicode characters GtkIMContextSimple also supports numeric entry of Unicode characters by typing Ctrl-Shift-u, followed by a hexadecimal Unicode codepoint. For example, Ctrl-Shift-u 1 2 3 Enter yields U+0123 LATIN SMALL LETTER G WITH CEDILLA, i.e. ģ. Creates a new #GtkIMContextSimple. a new #GtkIMContextSimple. Adds an additional table from the X11 compose file. A #GtkIMContextSimple The path of compose file Adds an additional table to search to the input context. Each row of the table consists of @max_seq_len key symbols followed by two #guint16 interpreted as the high and low words of a #gunicode value. Tables are searched starting from the last added. The table must be sorted in dictionary order on the numeric value of the key symbol fields. (Values beyond the length of the sequence should be zero.) A #GtkIMContextSimple the table Maximum length of a sequence in the table number of sequences in the table Creates a new #GtkIMMulticontext. a new #GtkIMMulticontext. Add menuitems for various available input methods to a menu; the menuitems, when selected, will switch the input method for the context and the global default input method. It is better to use the system-wide input method framework for changing input methods. Modern desktop shells offer on-screen displays for this that can triggered with a keyboard shortcut, e.g. Super-Space. a #GtkIMMulticontext a #GtkMenuShell Gets the id of the currently active slave of the @context. the id of the currently active slave a #GtkIMMulticontext Sets the context id for @context. This causes the currently active slave of @context to be replaced by the slave corresponding to the new context id. a #GtkIMMulticontext the id to use Style for input method preedit. See also #GtkSettings:gtk-im-preedit-style Deprecated Deprecated Deprecated Style for input method status. See also #GtkSettings:gtk-im-status-style Deprecated Deprecated Deprecated Constant to return from a signal handler for the #GtkSpinButton::input signal in case of conversion failure. Like gtk_get_interface_age(), but from the headers used at application compile time, rather than from the library linked against at application run time. An icon factory manages a collection of #GtkIconSet; a #GtkIconSet manages a set of variants of a particular icon (i.e. a #GtkIconSet contains variants for different sizes and widget states). Icons in an icon factory are named by a stock ID, which is a simple string identifying the icon. Each #GtkStyle has a list of #GtkIconFactory derived from the current theme; those icon factories are consulted first when searching for an icon. If the theme doesn’t set a particular icon, GTK+ looks for the icon in a list of default icon factories, maintained by gtk_icon_factory_add_default() and gtk_icon_factory_remove_default(). Applications with icons should add a default icon factory with their icons, which will allow themes to override the icons for the application. To display an icon, always use gtk_style_lookup_icon_set() on the widget that will display the icon, or the convenience function gtk_widget_render_icon(). These functions take the theme into account when looking up the icon to use for a given stock ID. # GtkIconFactory as GtkBuildable # {#GtkIconFactory-BUILDER-UI} GtkIconFactory supports a custom `<sources>` element, which can contain multiple `<source>` elements. The following attributes are allowed: - stock-id The stock id of the source, a string. This attribute is mandatory - filename The filename of the source, a string. This attribute is optional - icon-name The icon name for the source, a string. This attribute is optional. - size Size of the icon, a #GtkIconSize enum value. This attribute is optional. - direction Direction of the source, a #GtkTextDirection enum value. This attribute is optional. - state State of the source, a #GtkStateType enum value. This attribute is optional. ## A #GtkIconFactory UI definition fragment. ## |[ <object class="GtkIconFactory" id="iconfactory1"> <sources> <source stock-id="apple-red" filename="apple-red.png"/> </sources> </object> <object class="GtkWindow" id="window1"> <child> <object class="GtkButton" id="apple_button"> <property name="label">apple-red</property> <property name="use-stock">True</property> </object> </child> </object> ]| Creates a new #GtkIconFactory. An icon factory manages a collection of #GtkIconSets; a #GtkIconSet manages a set of variants of a particular icon (i.e. a #GtkIconSet contains variants for different sizes and widget states). Icons in an icon factory are named by a stock ID, which is a simple string identifying the icon. Each #GtkStyle has a list of #GtkIconFactorys derived from the current theme; those icon factories are consulted first when searching for an icon. If the theme doesn’t set a particular icon, GTK+ looks for the icon in a list of default icon factories, maintained by gtk_icon_factory_add_default() and gtk_icon_factory_remove_default(). Applications with icons should add a default icon factory with their icons, which will allow themes to override the icons for the application. Use #GtkIconTheme instead. a new #GtkIconFactory Looks for an icon in the list of default icon factories. For display to the user, you should use gtk_style_lookup_icon_set() on the #GtkStyle for the widget that will display the icon, instead of using this function directly, so that themes are taken into account. Use #GtkIconTheme instead. a #GtkIconSet, or %NULL an icon name Adds the given @icon_set to the icon factory, under the name @stock_id. @stock_id should be namespaced for your application, e.g. “myapp-whatever-icon”. Normally applications create a #GtkIconFactory, then add it to the list of default factories with gtk_icon_factory_add_default(). Then they pass the @stock_id to widgets such as #GtkImage to display the icon. Themes can provide an icon with the same name (such as "myapp-whatever-icon") to override your application’s default icons. If an icon already existed in @factory for @stock_id, it is unreferenced and replaced with the new @icon_set. Use #GtkIconTheme instead. a #GtkIconFactory icon name icon set Adds an icon factory to the list of icon factories searched by gtk_style_lookup_icon_set(). This means that, for example, gtk_image_new_from_stock() will be able to find icons in @factory. There will normally be an icon factory added for each library or application that comes with icons. The default icon factories can be overridden by themes. Use #GtkIconTheme instead. a #GtkIconFactory Looks up @stock_id in the icon factory, returning an icon set if found, otherwise %NULL. For display to the user, you should use gtk_style_lookup_icon_set() on the #GtkStyle for the widget that will display the icon, instead of using this function directly, so that themes are taken into account. Use #GtkIconTheme instead. icon set of @stock_id. a #GtkIconFactory an icon name Removes an icon factory from the list of default icon factories. Not normally used; you might use it for a library that can be unloaded or shut down. Use #GtkIconTheme instead. a #GtkIconFactory previously added with gtk_icon_factory_add_default() The parent class. Contains information found when looking up an icon in an icon theme. Creates a #GtkIconInfo for a #GdkPixbuf. a #GtkIconInfo a #GtkIconTheme the pixbuf to wrap in a #GtkIconInfo Make a copy of a #GtkIconInfo. Use g_object_ref() the new GtkIconInfo a #GtkIconInfo Free a #GtkIconInfo and associated information Use g_object_unref() a #GtkIconInfo This function is deprecated and always returns %FALSE. Attachment points are deprecated %FALSE a #GtkIconInfo location to store pointer to an array of points, or %NULL free the array of points with g_free(). location to store the number of points in @points, or %NULL Gets the base scale for the icon. The base scale is a scale for the icon that was specified by the icon theme creator. For instance an icon drawn for a high-dpi screen with window scale 2 for a base size of 32 will be 64 pixels tall and have a base scale of 2. the base scale a #GtkIconInfo Gets the base size for the icon. The base size is a size for the icon that was specified by the icon theme creator. This may be different than the actual size of image; an example of this is small emblem icons that can be attached to a larger icon. These icons will be given the same base size as the larger icons to which they are attached. Note that for scaled icons the base size does not include the base scale. the base size, or 0, if no base size is known for the icon. a #GtkIconInfo Gets the built-in image for this icon, if any. To allow GTK+ to use built in icon images, you must pass the %GTK_ICON_LOOKUP_USE_BUILTIN to gtk_icon_theme_lookup_icon(). This function is deprecated, use gtk_icon_theme_add_resource_path() instead of builtin icons. the built-in image pixbuf, or %NULL. No extra reference is added to the returned pixbuf, so if you want to keep it around, you must use g_object_ref(). The returned image must not be modified. a #GtkIconInfo This function is deprecated and always returns %NULL. Display names are deprecated %NULL a #GtkIconInfo This function is deprecated and always returns %FALSE. Embedded rectangles are deprecated %FALSE a #GtkIconInfo #GdkRectangle in which to store embedded rectangle coordinates; coordinates are only stored when this function returns %TRUE. Gets the filename for the icon. If the %GTK_ICON_LOOKUP_USE_BUILTIN flag was passed to gtk_icon_theme_lookup_icon(), there may be no filename if a builtin icon is returned; in this case, you should use gtk_icon_info_get_builtin_pixbuf(). the filename for the icon, or %NULL if gtk_icon_info_get_builtin_pixbuf() should be used instead. The return value is owned by GTK+ and should not be modified or freed. a #GtkIconInfo Checks if the icon is symbolic or not. This currently uses only the file name and not the file contents for determining this. This behaviour may change in the future. %TRUE if the icon is symbolic, %FALSE otherwise a #GtkIconInfo Renders an icon previously looked up in an icon theme using gtk_icon_theme_lookup_icon(); the size will be based on the size passed to gtk_icon_theme_lookup_icon(). Note that the resulting pixbuf may not be exactly this size; an icon theme may have icons that differ slightly from their nominal sizes, and in addition GTK+ will avoid scaling icons that it considers sufficiently close to the requested size or for which the source image would have to be scaled up too far. (This maintains sharpness.). This behaviour can be changed by passing the %GTK_ICON_LOOKUP_FORCE_SIZE flag when obtaining the #GtkIconInfo. If this flag has been specified, the pixbuf returned by this function will be scaled to the exact size. the rendered icon; this may be a newly created icon or a new reference to an internal icon, so you must not modify the icon. Use g_object_unref() to release your reference to the icon. a #GtkIconInfo from gtk_icon_theme_lookup_icon() Asynchronously load, render and scale an icon previously looked up from the icon theme using gtk_icon_theme_lookup_icon(). For more details, see gtk_icon_info_load_icon() which is the synchronous version of this call. a #GtkIconInfo from gtk_icon_theme_lookup_icon() optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an async icon load, see gtk_icon_info_load_icon_async(). the rendered icon; this may be a newly created icon or a new reference to an internal icon, so you must not modify the icon. Use g_object_unref() to release your reference to the icon. a #GtkIconInfo from gtk_icon_theme_lookup_icon() a #GAsyncResult Renders an icon previously looked up in an icon theme using gtk_icon_theme_lookup_icon(); the size will be based on the size passed to gtk_icon_theme_lookup_icon(). Note that the resulting surface may not be exactly this size; an icon theme may have icons that differ slightly from their nominal sizes, and in addition GTK+ will avoid scaling icons that it considers sufficiently close to the requested size or for which the source image would have to be scaled up too far. (This maintains sharpness.). This behaviour can be changed by passing the %GTK_ICON_LOOKUP_FORCE_SIZE flag when obtaining the #GtkIconInfo. If this flag has been specified, the pixbuf returned by this function will be scaled to the exact size. the rendered icon; this may be a newly created icon or a new reference to an internal icon, so you must not modify the icon. Use cairo_surface_destroy() to release your reference to the icon. a #GtkIconInfo from gtk_icon_theme_lookup_icon() #GdkWindow to optimize drawing for, or %NULL Loads an icon, modifying it to match the system colours for the foreground, success, warning and error colors provided. If the icon is not a symbolic one, the function will return the result from gtk_icon_info_load_icon(). This allows loading symbolic icons that will match the system theme. Unless you are implementing a widget, you will want to use g_themed_icon_new_with_default_fallbacks() to load the icon. As implementation details, the icon loaded needs to be of SVG type, contain the “symbolic” term as the last component of the icon name, and use the “fg”, “success”, “warning” and “error” CSS styles in the SVG file itself. See the [Symbolic Icons Specification](http://www.freedesktop.org/wiki/SymbolicIcons) for more information about symbolic icons. a #GdkPixbuf representing the loaded icon a #GtkIconInfo a #GdkRGBA representing the foreground color of the icon a #GdkRGBA representing the warning color of the icon or %NULL to use the default color a #GdkRGBA representing the warning color of the icon or %NULL to use the default color a #GdkRGBA representing the error color of the icon or %NULL to use the default color (allow-none) a #gboolean, returns whether the loaded icon was a symbolic one and whether the @fg color was applied to it. Asynchronously load, render and scale a symbolic icon previously looked up from the icon theme using gtk_icon_theme_lookup_icon(). For more details, see gtk_icon_info_load_symbolic() which is the synchronous version of this call. a #GtkIconInfo from gtk_icon_theme_lookup_icon() a #GdkRGBA representing the foreground color of the icon a #GdkRGBA representing the warning color of the icon or %NULL to use the default color a #GdkRGBA representing the warning color of the icon or %NULL to use the default color a #GdkRGBA representing the error color of the icon or %NULL to use the default color (allow-none) optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an async icon load, see gtk_icon_info_load_symbolic_async(). the rendered icon; this may be a newly created icon or a new reference to an internal icon, so you must not modify the icon. Use g_object_unref() to release your reference to the icon. a #GtkIconInfo from gtk_icon_theme_lookup_icon() a #GAsyncResult a #gboolean, returns whether the loaded icon was a symbolic one and whether the @fg color was applied to it. Loads an icon, modifying it to match the system colors for the foreground, success, warning and error colors provided. If the icon is not a symbolic one, the function will return the result from gtk_icon_info_load_icon(). This function uses the regular foreground color and the symbolic colors with the names “success_color”, “warning_color” and “error_color” from the context. This allows loading symbolic icons that will match the system theme. See gtk_icon_info_load_symbolic() for more details. a #GdkPixbuf representing the loaded icon a #GtkIconInfo a #GtkStyleContext a #gboolean, returns whether the loaded icon was a symbolic one and whether the @fg color was applied to it. Asynchronously load, render and scale a symbolic icon previously looked up from the icon theme using gtk_icon_theme_lookup_icon(). For more details, see gtk_icon_info_load_symbolic_for_context() which is the synchronous version of this call. a #GtkIconInfo from gtk_icon_theme_lookup_icon() a #GtkStyleContext optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an async icon load, see gtk_icon_info_load_symbolic_for_context_async(). the rendered icon; this may be a newly created icon or a new reference to an internal icon, so you must not modify the icon. Use g_object_unref() to release your reference to the icon. a #GtkIconInfo from gtk_icon_theme_lookup_icon() a #GAsyncResult a #gboolean, returns whether the loaded icon was a symbolic one and whether the @fg color was applied to it. Loads an icon, modifying it to match the system colours for the foreground, success, warning and error colors provided. If the icon is not a symbolic one, the function will return the result from gtk_icon_info_load_icon(). This allows loading symbolic icons that will match the system theme. See gtk_icon_info_load_symbolic() for more details. Use gtk_icon_info_load_symbolic_for_context() instead a #GdkPixbuf representing the loaded icon a #GtkIconInfo a #GtkStyle to take the colors from the widget state to use for colors a #gboolean, returns whether the loaded icon was a symbolic one and whether the @fg color was applied to it. Sets whether the coordinates returned by gtk_icon_info_get_embedded_rect() and gtk_icon_info_get_attach_points() should be returned in their original form as specified in the icon theme, instead of scaled appropriately for the pixbuf returned by gtk_icon_info_load_icon(). Raw coordinates are somewhat strange; they are specified to be with respect to the unscaled pixmap for PNG and XPM icons, but for SVG icons, they are in a 1000x1000 coordinate space that is scaled to the final size of the icon. You can determine if the icon is an SVG icon by using gtk_icon_info_get_filename(), and seeing if it is non-%NULL and ends in “.svg”. This function is provided primarily to allow compatibility wrappers for older API's, and is not expected to be useful for applications. Embedded rectangles and attachment points are deprecated a #GtkIconInfo whether the coordinates of embedded rectangles and attached points should be returned in their original (unscaled) form. Used to specify options for gtk_icon_theme_lookup_icon() Never get SVG icons, even if gdk-pixbuf supports them. Cannot be used together with %GTK_ICON_LOOKUP_FORCE_SVG. Get SVG icons, even if gdk-pixbuf doesn’t support them. Cannot be used together with %GTK_ICON_LOOKUP_NO_SVG. When passed to gtk_icon_theme_lookup_icon() includes builtin icons as well as files. For a builtin icon, gtk_icon_info_get_filename() is %NULL and you need to call gtk_icon_info_get_builtin_pixbuf(). Try to shorten icon name at '-' characters before looking at inherited themes. This flag is only supported in functions that take a single icon name. For more general fallback, see gtk_icon_theme_choose_icon(). Since 2.12. Always get the icon scaled to the requested size. Since 2.14. Try to always load regular icons, even when symbolic icon names are given. Since 3.14. Try to always load symbolic icons, even when regular icon names are given. Since 3.14. Try to load a variant of the icon for left-to-right text direction. Since 3.14. Try to load a variant of the icon for right-to-left text direction. Since 3.14. Creates a new #GtkIconSet. A #GtkIconSet represents a single icon in various sizes and widget states. It can provide a #GdkPixbuf for a given size and state on request, and automatically caches some of the rendered #GdkPixbuf objects. Normally you would use gtk_widget_render_icon_pixbuf() instead of using #GtkIconSet directly. The one case where you’d use #GtkIconSet is to create application-specific icon sets to place in a #GtkIconFactory. Use #GtkIconTheme instead. a new #GtkIconSet Creates a new #GtkIconSet with @pixbuf as the default/fallback source image. If you don’t add any additional #GtkIconSource to the icon set, all variants of the icon will be created from @pixbuf, using scaling, pixelation, etc. as required to adjust the icon size or make the icon look insensitive/prelighted. Use #GtkIconTheme instead. a new #GtkIconSet a #GdkPixbuf Icon sets have a list of #GtkIconSource, which they use as base icons for rendering icons in different states and sizes. Icons are scaled, made to look insensitive, etc. in gtk_icon_set_render_icon(), but #GtkIconSet needs base images to work with. The base images and when to use them are described by a #GtkIconSource. This function copies @source, so you can reuse the same source immediately without affecting the icon set. An example of when you’d use this function: a web browser’s "Back to Previous Page" icon might point in a different direction in Hebrew and in English; it might look different when insensitive; and it might change size depending on toolbar mode (small/large icons). So a single icon set would contain all those variants of the icon, and you might add a separate source for each one. You should nearly always add a “default” icon source with all fields wildcarded, which will be used as a fallback if no more specific source matches. #GtkIconSet always prefers more specific icon sources to more generic icon sources. The order in which you add the sources to the icon set does not matter. gtk_icon_set_new_from_pixbuf() creates a new icon set with a default icon source based on the given pixbuf. Use #GtkIconTheme instead. a #GtkIconSet a #GtkIconSource Copies @icon_set by value. Use #GtkIconTheme instead. a new #GtkIconSet identical to the first. a #GtkIconSet Obtains a list of icon sizes this icon set can render. The returned array must be freed with g_free(). Use #GtkIconTheme instead. a #GtkIconSet return location for array of sizes (#GtkIconSize) location to store number of elements in returned array Increments the reference count on @icon_set. Use #GtkIconTheme instead. @icon_set. a #GtkIconSet. Renders an icon using gtk_style_render_icon(). In most cases, gtk_widget_render_icon() is better, since it automatically provides most of the arguments from the current widget settings. This function never returns %NULL; if the icon can’t be rendered (perhaps because an image file fails to load), a default "missing image" icon will be returned instead. Use gtk_icon_set_render_icon_pixbuf() instead a #GdkPixbuf to be displayed a #GtkIconSet a #GtkStyle associated with @widget, or %NULL text direction widget state icon size (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale. widget that will display the icon, or %NULL. The only use that is typically made of this is to determine the appropriate #GdkScreen. detail to pass to the theme engine, or %NULL. Note that passing a detail of anything but %NULL will disable caching. Renders an icon using gtk_render_icon_pixbuf(). In most cases, gtk_widget_render_icon_pixbuf() is better, since it automatically provides most of the arguments from the current widget settings. This function never returns %NULL; if the icon can’t be rendered (perhaps because an image file fails to load), a default "missing image" icon will be returned instead. Use #GtkIconTheme instead. a #GdkPixbuf to be displayed a #GtkIconSet a #GtkStyleContext icon size (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale. Renders an icon using gtk_render_icon_pixbuf() and converts it to a cairo surface. This function never returns %NULL; if the icon can’t be rendered (perhaps because an image file fails to load), a default "missing image" icon will be returned instead. Use #GtkIconTheme instead. a #cairo_surface_t to be displayed a #GtkIconSet a #GtkStyleContext icon size (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale. the window scale to render for #GdkWindow to optimize drawing for, or %NULL Decrements the reference count on @icon_set, and frees memory if the reference count reaches 0. Use #GtkIconTheme instead. a #GtkIconSet Built-in stock icon sizes. Invalid size. Size appropriate for menus (16px). Size appropriate for small toolbars (16px). Size appropriate for large toolbars (24px) Size appropriate for buttons (16px) Size appropriate for drag and drop (32px) Size appropriate for dialogs (48px) Looks up the icon size associated with @name. Use #GtkIconTheme instead. the icon size (#GtkIconSize) the name to look up. Gets the canonical name of the given icon size. The returned string is statically allocated and should not be freed. Use #GtkIconTheme instead. the name of the given icon size. a #GtkIconSize. Obtains the pixel size of a semantic icon size @size: #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_BUTTON, etc. This function isn’t normally needed, gtk_icon_theme_load_icon() is the usual way to get an icon for rendering, then just look at the size of the rendered pixbuf. The rendered pixbuf may not even correspond to the width/height returned by gtk_icon_size_lookup(), because themes are free to render the pixbuf however they like, including changing the usual size. %TRUE if @size was a valid size an icon size (#GtkIconSize) location to store icon width location to store icon height Obtains the pixel size of a semantic icon size, possibly modified by user preferences for a particular #GtkSettings. Normally @size would be #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_BUTTON, etc. This function isn’t normally needed, gtk_widget_render_icon_pixbuf() is the usual way to get an icon for rendering, then just look at the size of the rendered pixbuf. The rendered pixbuf may not even correspond to the width/height returned by gtk_icon_size_lookup(), because themes are free to render the pixbuf however they like, including changing the usual size. Use gtk_icon_size_lookup() instead. %TRUE if @size was a valid size a #GtkSettings object, used to determine which set of user preferences to used. an icon size (#GtkIconSize) location to store icon width location to store icon height Registers a new icon size, along the same lines as #GTK_ICON_SIZE_MENU, etc. Returns the integer value for the size. Use #GtkIconTheme instead. integer value representing the size (#GtkIconSize) name of the icon size the icon width the icon height Registers @alias as another name for @target. So calling gtk_icon_size_from_name() with @alias as argument will return @target. Use #GtkIconTheme instead. an alias for @target an existing icon size (#GtkIconSize) Creates a new #GtkIconSource. A #GtkIconSource contains a #GdkPixbuf (or image filename) that serves as the base image for one or more of the icons in a #GtkIconSet, along with a specification for which icons in the icon set will be based on that pixbuf or image file. An icon set contains a set of icons that represent “the same” logical concept in different states, different global text directions, and different sizes. So for example a web browser’s “Back to Previous Page” icon might point in a different direction in Hebrew and in English; it might look different when insensitive; and it might change size depending on toolbar mode (small/large icons). So a single icon set would contain all those variants of the icon. #GtkIconSet contains a list of #GtkIconSource from which it can derive specific icon variants in the set. In the simplest case, #GtkIconSet contains one source pixbuf from which it derives all variants. The convenience function gtk_icon_set_new_from_pixbuf() handles this case; if you only have one source pixbuf, just use that function. If you want to use a different base pixbuf for different icon variants, you create multiple icon sources, mark which variants they’ll be used to create, and add them to the icon set with gtk_icon_set_add_source(). By default, the icon source has all parameters wildcarded. That is, the icon source will be used as the base icon for any desired text direction, widget state, or icon size. Use #GtkIconTheme instead. a new #GtkIconSource Creates a copy of @source; mostly useful for language bindings. Use #GtkIconTheme instead. a new #GtkIconSource a #GtkIconSource Frees a dynamically-allocated icon source, along with its filename, size, and pixbuf fields if those are not %NULL. Use #GtkIconTheme instead. a #GtkIconSource Obtains the text direction this icon source applies to. The return value is only useful/meaningful if the text direction is not wildcarded. Use #GtkIconTheme instead. text direction this source matches a #GtkIconSource Gets the value set by gtk_icon_source_set_direction_wildcarded(). Use #GtkIconTheme instead. %TRUE if this icon source is a base for any text direction variant a #GtkIconSource Retrieves the source filename, or %NULL if none is set. The filename is not a copy, and should not be modified or expected to persist beyond the lifetime of the icon source. Use #GtkIconTheme instead. image filename. This string must not be modified or freed. a #GtkIconSource Retrieves the source icon name, or %NULL if none is set. The icon_name is not a copy, and should not be modified or expected to persist beyond the lifetime of the icon source. Use #GtkIconTheme instead. icon name. This string must not be modified or freed. a #GtkIconSource Retrieves the source pixbuf, or %NULL if none is set. In addition, if a filename source is in use, this function in some cases will return the pixbuf from loaded from the filename. This is, for example, true for the GtkIconSource passed to the #GtkStyle render_icon() virtual function. The reference count on the pixbuf is not incremented. Use #GtkIconTheme instead. source pixbuf a #GtkIconSource Obtains the icon size this source applies to. The return value is only useful/meaningful if the icon size is not wildcarded. Use #GtkIconTheme instead. icon size (#GtkIconSize) this source matches. a #GtkIconSource Gets the value set by gtk_icon_source_set_size_wildcarded(). Use #GtkIconTheme instead. %TRUE if this icon source is a base for any icon size variant a #GtkIconSource Obtains the widget state this icon source applies to. The return value is only useful/meaningful if the widget state is not wildcarded. Use #GtkIconTheme instead. widget state this source matches a #GtkIconSource Gets the value set by gtk_icon_source_set_state_wildcarded(). Use #GtkIconTheme instead. %TRUE if this icon source is a base for any widget state variant a #GtkIconSource Sets the text direction this icon source is intended to be used with. Setting the text direction on an icon source makes no difference if the text direction is wildcarded. Therefore, you should usually call gtk_icon_source_set_direction_wildcarded() to un-wildcard it in addition to calling this function. Use #GtkIconTheme instead. a #GtkIconSource text direction this source applies to If the text direction is wildcarded, this source can be used as the base image for an icon in any #GtkTextDirection. If the text direction is not wildcarded, then the text direction the icon source applies to should be set with gtk_icon_source_set_direction(), and the icon source will only be used with that text direction. #GtkIconSet prefers non-wildcarded sources (exact matches) over wildcarded sources, and will use an exact match when possible. Use #GtkIconTheme instead. a #GtkIconSource %TRUE to wildcard the text direction Sets the name of an image file to use as a base image when creating icon variants for #GtkIconSet. The filename must be absolute. Use #GtkIconTheme instead. a #GtkIconSource image file to use Sets the name of an icon to look up in the current icon theme to use as a base image when creating icon variants for #GtkIconSet. Use #GtkIconTheme instead. a #GtkIconSource name of icon to use Sets a pixbuf to use as a base image when creating icon variants for #GtkIconSet. Use #GtkIconTheme instead. a #GtkIconSource pixbuf to use as a source Sets the icon size this icon source is intended to be used with. Setting the icon size on an icon source makes no difference if the size is wildcarded. Therefore, you should usually call gtk_icon_source_set_size_wildcarded() to un-wildcard it in addition to calling this function. Use #GtkIconTheme instead. a #GtkIconSource icon size (#GtkIconSize) this source applies to If the icon size is wildcarded, this source can be used as the base image for an icon of any size. If the size is not wildcarded, then the size the source applies to should be set with gtk_icon_source_set_size() and the icon source will only be used with that specific size. #GtkIconSet prefers non-wildcarded sources (exact matches) over wildcarded sources, and will use an exact match when possible. #GtkIconSet will normally scale wildcarded source images to produce an appropriate icon at a given size, but will not change the size of source images that match exactly. Use #GtkIconTheme instead. a #GtkIconSource %TRUE to wildcard the widget state Sets the widget state this icon source is intended to be used with. Setting the widget state on an icon source makes no difference if the state is wildcarded. Therefore, you should usually call gtk_icon_source_set_state_wildcarded() to un-wildcard it in addition to calling this function. Use #GtkIconTheme instead. a #GtkIconSource widget state this source applies to If the widget state is wildcarded, this source can be used as the base image for an icon in any #GtkStateType. If the widget state is not wildcarded, then the state the source applies to should be set with gtk_icon_source_set_state() and the icon source will only be used with that specific state. #GtkIconSet prefers non-wildcarded sources (exact matches) over wildcarded sources, and will use an exact match when possible. #GtkIconSet will normally transform wildcarded source images to produce an appropriate icon for a given state, for example lightening an image on prelight, but will not modify source images that match exactly. Use #GtkIconTheme instead. a #GtkIconSource %TRUE to wildcard the widget state #GtkIconTheme provides a facility for looking up icons by name and size. The main reason for using a name rather than simply providing a filename is to allow different icons to be used depending on what “icon theme” is selected by the user. The operation of icon themes on Linux and Unix follows the [Icon Theme Specification](http://www.freedesktop.org/Standards/icon-theme-spec) There is a fallback icon theme, named `hicolor`, where applications should install their icons, but additional icon themes can be installed as operating system vendors and users choose. Named icons are similar to the deprecated [Stock Items][gtkstock], and the distinction between the two may be a bit confusing. A few things to keep in mind: - Stock images usually are used in conjunction with [Stock Items][gtkstock], such as %GTK_STOCK_OK or %GTK_STOCK_OPEN. Named icons are easier to set up and therefore are more useful for new icons that an application wants to add, such as application icons or window icons. - Stock images can only be loaded at the symbolic sizes defined by the #GtkIconSize enumeration, or by custom sizes defined by gtk_icon_size_register(), while named icons are more flexible and any pixel size can be specified. - Because stock images are closely tied to stock items, and thus to actions in the user interface, stock images may come in multiple variants for different widget states or writing directions. A good rule of thumb is that if there is a stock image for what you want to use, use it, otherwise use a named icon. It turns out that internally stock images are generally defined in terms of one or more named icons. (An example of the more than one case is icons that depend on writing direction; %GTK_STOCK_GO_FORWARD uses the two themed icons “gtk-stock-go-forward-ltr” and “gtk-stock-go-forward-rtl”.) In many cases, named themes are used indirectly, via #GtkImage or stock items, rather than directly, but looking up icons directly is also simple. The #GtkIconTheme object acts as a database of all the icons in the current theme. You can create new #GtkIconTheme objects, but it’s much more efficient to use the standard icon theme for the #GdkScreen so that the icon information is shared with other people looking up icons. |[<!-- language="C" --> GError *error = NULL; GtkIconTheme *icon_theme; GdkPixbuf *pixbuf; icon_theme = gtk_icon_theme_get_default (); pixbuf = gtk_icon_theme_load_icon (icon_theme, "my-icon-name", // icon name 48, // icon size 0, // flags &error); if (!pixbuf) { g_warning ("Couldn’t load icon: %s", error->message); g_error_free (error); } else { // Use the pixbuf g_object_unref (pixbuf); } ]| Creates a new icon theme object. Icon theme objects are used to lookup up an icon by name in a particular icon theme. Usually, you’ll want to use gtk_icon_theme_get_default() or gtk_icon_theme_get_for_screen() rather than creating a new icon theme object for scratch. the newly created #GtkIconTheme object. Registers a built-in icon for icon theme lookups. The idea of built-in icons is to allow an application or library that uses themed icons to function requiring files to be present in the file system. For instance, the default images for all of GTK+’s stock icons are registered as built-icons. In general, if you use gtk_icon_theme_add_builtin_icon() you should also install the icon in the icon theme, so that the icon is generally available. This function will generally be used with pixbufs loaded via gdk_pixbuf_new_from_inline(). Use gtk_icon_theme_add_resource_path() to add application-specific icons to the icon theme. the name of the icon to register the size in pixels at which to register the icon (different images can be registered for the same icon name at different sizes.) #GdkPixbuf that contains the image to use for @icon_name Gets the icon theme for the default screen. See gtk_icon_theme_get_for_screen(). A unique #GtkIconTheme associated with the default screen. This icon theme is associated with the screen and can be used as long as the screen is open. Do not ref or unref it. Gets the icon theme object associated with @screen; if this function has not previously been called for the given screen, a new icon theme object will be created and associated with the screen. Icon theme objects are fairly expensive to create, so using this function is usually a better choice than calling than gtk_icon_theme_new() and setting the screen yourself; by using this function a single icon theme object will be shared between users. A unique #GtkIconTheme associated with the given screen. This icon theme is associated with the screen and can be used as long as the screen is open. Do not ref or unref it. a #GdkScreen Signal emitted when the current icon theme is switched or GTK+ detects that a change has occurred in the contents of the current icon theme. Adds a resource path that will be looked at when looking for icons, similar to search paths. This function should be used to make application-specific icons available as part of the icon theme. The resources are considered as part of the hicolor icon theme and must be located in subdirectories that are defined in the hicolor icon theme, such as `@path/16x16/actions/run.png`. Icons that are directly placed in the resource path instead of a subdirectory are also considered as ultimate fallback. a #GtkIconTheme a resource path Appends a directory to the search path. See gtk_icon_theme_set_search_path(). a #GtkIconTheme directory name to append to the icon path Looks up a named icon and returns a #GtkIconInfo containing information such as the filename of the icon. The icon can then be rendered into a pixbuf using gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon() combines these two steps if all you need is the pixbuf.) If @icon_names contains more than one name, this function tries them all in the given order before falling back to inherited icon themes. a #GtkIconInfo object containing information about the icon, or %NULL if the icon wasn’t found. a #GtkIconTheme %NULL-terminated array of icon names to lookup desired icon size flags modifying the behavior of the icon lookup Looks up a named icon for a particular window scale and returns a #GtkIconInfo containing information such as the filename of the icon. The icon can then be rendered into a pixbuf using gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon() combines these two steps if all you need is the pixbuf.) If @icon_names contains more than one name, this function tries them all in the given order before falling back to inherited icon themes. a #GtkIconInfo object containing information about the icon, or %NULL if the icon wasn’t found. a #GtkIconTheme %NULL-terminated array of icon names to lookup desired icon size desired scale flags modifying the behavior of the icon lookup Gets the name of an icon that is representative of the current theme (for instance, to use when presenting a list of themes to the user.) the name of an example icon or %NULL. Free with g_free(). a #GtkIconTheme Returns an array of integers describing the sizes at which the icon is available without scaling. A size of -1 means that the icon is available in a scalable format. The array is zero-terminated. An newly allocated array describing the sizes at which the icon is available. The array should be freed with g_free() when it is no longer needed. a #GtkIconTheme the name of an icon Gets the current search path. See gtk_icon_theme_set_search_path(). a #GtkIconTheme location to store a list of icon theme path directories or %NULL. The stored value should be freed with g_strfreev(). location to store number of elements in @path, or %NULL Checks whether an icon theme includes an icon for a particular name. %TRUE if @icon_theme includes an icon for @icon_name. a #GtkIconTheme the name of an icon Gets the list of contexts available within the current hierarchy of icon themes. See gtk_icon_theme_list_icons() for details about contexts. a #GList list holding the names of all the contexts in the theme. You must first free each element in the list with g_free(), then free the list itself with g_list_free(). a #GtkIconTheme Lists the icons in the current icon theme. Only a subset of the icons can be listed by providing a context string. The set of values for the context string is system dependent, but will typically include such values as “Applications” and “MimeTypes”. Contexts are explained in the [Icon Theme Specification](http://www.freedesktop.org/wiki/Specifications/icon-theme-spec). The standard contexts are listed in the [Icon Naming Specification](http://www.freedesktop.org/wiki/Specifications/icon-naming-spec). Also see gtk_icon_theme_list_contexts(). a #GList list holding the names of all the icons in the theme. You must first free each element in the list with g_free(), then free the list itself with g_list_free(). a #GtkIconTheme a string identifying a particular type of icon, or %NULL to list all icons. Looks up an icon in an icon theme, scales it to the given size and renders it into a pixbuf. This is a convenience function; if more details about the icon are needed, use gtk_icon_theme_lookup_icon() followed by gtk_icon_info_load_icon(). Note that you probably want to listen for icon theme changes and update the icon. This is usually done by connecting to the GtkWidget::style-set signal. If for some reason you do not want to update the icon when the icon theme changes, you should consider using gdk_pixbuf_copy() to make a private copy of the pixbuf returned by this function. Otherwise GTK+ may need to keep the old icon theme loaded, which would be a waste of memory. the rendered icon; this may be a newly created icon or a new reference to an internal icon, so you must not modify the icon. Use g_object_unref() to release your reference to the icon. %NULL if the icon isn’t found. a #GtkIconTheme the name of the icon to lookup the desired icon size. The resulting icon may not be exactly this size; see gtk_icon_info_load_icon(). flags modifying the behavior of the icon lookup Looks up an icon in an icon theme for a particular window scale, scales it to the given size and renders it into a pixbuf. This is a convenience function; if more details about the icon are needed, use gtk_icon_theme_lookup_icon() followed by gtk_icon_info_load_icon(). Note that you probably want to listen for icon theme changes and update the icon. This is usually done by connecting to the GtkWidget::style-set signal. If for some reason you do not want to update the icon when the icon theme changes, you should consider using gdk_pixbuf_copy() to make a private copy of the pixbuf returned by this function. Otherwise GTK+ may need to keep the old icon theme loaded, which would be a waste of memory. the rendered icon; this may be a newly created icon or a new reference to an internal icon, so you must not modify the icon. Use g_object_unref() to release your reference to the icon. %NULL if the icon isn’t found. a #GtkIconTheme the name of the icon to lookup the desired icon size. The resulting icon may not be exactly this size; see gtk_icon_info_load_icon(). desired scale flags modifying the behavior of the icon lookup Looks up an icon in an icon theme for a particular window scale, scales it to the given size and renders it into a cairo surface. This is a convenience function; if more details about the icon are needed, use gtk_icon_theme_lookup_icon() followed by gtk_icon_info_load_surface(). Note that you probably want to listen for icon theme changes and update the icon. This is usually done by connecting to the GtkWidget::style-set signal. the rendered icon; this may be a newly created icon or a new reference to an internal icon, so you must not modify the icon. Use cairo_surface_destroy() to release your reference to the icon. %NULL if the icon isn’t found. a #GtkIconTheme the name of the icon to lookup the desired icon size. The resulting icon may not be exactly this size; see gtk_icon_info_load_icon(). desired scale #GdkWindow to optimize drawing for, or %NULL flags modifying the behavior of the icon lookup Looks up an icon and returns a #GtkIconInfo containing information such as the filename of the icon. The icon can then be rendered into a pixbuf using gtk_icon_info_load_icon(). When rendering on displays with high pixel densities you should not use a @size multiplied by the scaling factor returned by functions like gdk_window_get_scale_factor(). Instead, you should use gtk_icon_theme_lookup_by_gicon_for_scale(), as the assets loaded for a given scaling factor may be different. a #GtkIconInfo containing information about the icon, or %NULL if the icon wasn’t found. Unref with g_object_unref() a #GtkIconTheme the #GIcon to look up desired icon size flags modifying the behavior of the icon lookup Looks up an icon and returns a #GtkIconInfo containing information such as the filename of the icon. The icon can then be rendered into a pixbuf using gtk_icon_info_load_icon(). a #GtkIconInfo containing information about the icon, or %NULL if the icon wasn’t found. Unref with g_object_unref() a #GtkIconTheme the #GIcon to look up desired icon size the desired scale flags modifying the behavior of the icon lookup Looks up a named icon and returns a #GtkIconInfo containing information such as the filename of the icon. The icon can then be rendered into a pixbuf using gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon() combines these two steps if all you need is the pixbuf.) When rendering on displays with high pixel densities you should not use a @size multiplied by the scaling factor returned by functions like gdk_window_get_scale_factor(). Instead, you should use gtk_icon_theme_lookup_icon_for_scale(), as the assets loaded for a given scaling factor may be different. a #GtkIconInfo object containing information about the icon, or %NULL if the icon wasn’t found. a #GtkIconTheme the name of the icon to lookup desired icon size flags modifying the behavior of the icon lookup Looks up a named icon for a particular window scale and returns a #GtkIconInfo containing information such as the filename of the icon. The icon can then be rendered into a pixbuf using gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon() combines these two steps if all you need is the pixbuf.) a #GtkIconInfo object containing information about the icon, or %NULL if the icon wasn’t found. a #GtkIconTheme the name of the icon to lookup desired icon size the desired scale flags modifying the behavior of the icon lookup Prepends a directory to the search path. See gtk_icon_theme_set_search_path(). a #GtkIconTheme directory name to prepend to the icon path Checks to see if the icon theme has changed; if it has, any currently cached information is discarded and will be reloaded next time @icon_theme is accessed. %TRUE if the icon theme has changed and needed to be reloaded. a #GtkIconTheme Sets the name of the icon theme that the #GtkIconTheme object uses overriding system configuration. This function cannot be called on the icon theme objects returned from gtk_icon_theme_get_default() and gtk_icon_theme_get_for_screen(). a #GtkIconTheme name of icon theme to use instead of configured theme, or %NULL to unset a previously set custom theme Sets the screen for an icon theme; the screen is used to track the user’s currently configured icon theme, which might be different for different screens. a #GtkIconTheme a #GdkScreen Sets the search path for the icon theme object. When looking for an icon theme, GTK+ will search for a subdirectory of one or more of the directories in @path with the same name as the icon theme containing an index.theme file. (Themes from multiple of the path elements are combined to allow themes to be extended by adding icons in the user’s home directory.) In addition if an icon found isn’t found either in the current icon theme or the default icon theme, and an image file with the right name is found directly in one of the elements of @path, then that image will be used for the icon name. (This is legacy feature, and new icons should be put into the fallback icon theme, which is called hicolor, rather than directly on the icon path.) a #GtkIconTheme array of directories that are searched for icon themes number of elements in @path. Emitted when the current icon theme is switched or GTK+ detects that a change has occurred in the contents of the current icon theme. The parent class. Signal emitted when the current icon theme is switched or GTK+ detects that a change has occurred in the contents of the current icon theme. Error codes for GtkIconTheme operations. The icon specified does not exist in the theme An unspecified error occurred. #GtkIconView provides an alternative view on a #GtkTreeModel. It displays the model as a grid of icons with labels. Like #GtkTreeView, it allows to select one or multiple items (depending on the selection mode, see gtk_icon_view_set_selection_mode()). In addition to selection with the arrow keys, #GtkIconView supports rubberband selection, which is controlled by dragging the pointer. Note that if the tree model is backed by an actual tree store (as opposed to a flat list where the mapping to icons is obvious), #GtkIconView will only display the first level of the tree and ignore the tree’s branches. # CSS nodes |[<!-- language="plain" --> iconview.view ╰── [rubberband] ]| GtkIconView has a single CSS node with name iconview and style class .view. For rubberband selection, a subnode with name rubberband is used. Creates a new #GtkIconView widget A newly created #GtkIconView widget Creates a new #GtkIconView widget using the specified @area to layout cells inside the icons. A newly created #GtkIconView widget the #GtkCellArea to use to layout cells Creates a new #GtkIconView widget with the model @model. A newly created #GtkIconView widget. The model. Activates the item determined by @path. A #GtkIconView The #GtkTreePath to be activated Selects all the icons. @icon_view must has its selection mode set to #GTK_SELECTION_MULTIPLE. A #GtkIconView. Unselects all the icons. A #GtkIconView. Converts widget coordinates to coordinates for the bin_window, as expected by e.g. gtk_icon_view_get_path_at_pos(). a #GtkIconView X coordinate relative to the widget Y coordinate relative to the widget return location for bin_window X coordinate return location for bin_window Y coordinate Creates a #cairo_surface_t representation of the item at @path. This image is used for a drag icon. a newly-allocated surface of the drag icon. a #GtkIconView a #GtkTreePath in @icon_view Turns @icon_view into a drop destination for automatic DND. Calling this method sets #GtkIconView:reorderable to %FALSE. a #GtkIconView the table of targets that the drag will support the number of items in @targets the bitmask of possible actions for a drag to this widget Turns @icon_view into a drag source for automatic DND. Calling this method sets #GtkIconView:reorderable to %FALSE. a #GtkIconView Mask of allowed buttons to start drag the table of targets that the drag will support the number of items in @targets the bitmask of possible actions for a drag from this widget Gets the setting set by gtk_icon_view_set_activate_on_single_click(). %TRUE if item-activated will be emitted on a single click a #GtkIconView Fills the bounding rectangle in widget coordinates for the cell specified by @path and @cell. If @cell is %NULL the main cell area is used. This function is only valid if @icon_view is realized. %FALSE if there is no such item, %TRUE otherwise a #GtkIconView a #GtkTreePath a #GtkCellRenderer or %NULL rectangle to fill with cell rect Returns the value of the ::column-spacing property. the space between columns a #GtkIconView Returns the value of the ::columns property. the number of columns, or -1 a #GtkIconView Fills in @path and @cell with the current cursor path and cell. If the cursor isn’t currently set, then *@path will be %NULL. If no cell currently has focus, then *@cell will be %NULL. The returned #GtkTreePath must be freed with gtk_tree_path_free(). %TRUE if the cursor is set. A #GtkIconView Return location for the current cursor path, or %NULL Return location the current focus cell, or %NULL Determines the destination item for a given position. whether there is an item at the given position. a #GtkIconView the position to determine the destination item for the position to determine the destination item for Return location for the path of the item, or %NULL. Return location for the drop position, or %NULL Gets information about the item that is highlighted for feedback. a #GtkIconView Return location for the path of the highlighted item, or %NULL. Return location for the drop position, or %NULL Finds the path at the point (@x, @y), relative to bin_window coordinates. In contrast to gtk_icon_view_get_path_at_pos(), this function also obtains the cell at the specified position. The returned path should be freed with gtk_tree_path_free(). See gtk_icon_view_convert_widget_to_bin_window_coords() for converting widget coordinates to bin_window coordinates. %TRUE if an item exists at the specified position A #GtkIconView. The x position to be identified The y position to be identified Return location for the path, or %NULL Return location for the renderer responsible for the cell at (@x, @y), or %NULL Gets the column in which the item @path is currently displayed. Column numbers start at 0. The column in which the item is displayed a #GtkIconView the #GtkTreePath of the item Returns the value of the ::item-orientation property which determines whether the labels are drawn beside the icons instead of below. the relative position of texts and icons a #GtkIconView Returns the value of the ::item-padding property. the padding around items a #GtkIconView Gets the row in which the item @path is currently displayed. Row numbers start at 0. The row in which the item is displayed a #GtkIconView the #GtkTreePath of the item Returns the value of the ::item-width property. the width of a single item, or -1 a #GtkIconView Returns the value of the ::margin property. the space at the borders a #GtkIconView Returns the column with markup text for @icon_view. the markup column, or -1 if it’s unset. A #GtkIconView. Returns the model the #GtkIconView is based on. Returns %NULL if the model is unset. A #GtkTreeModel, or %NULL if none is currently being used. a #GtkIconView Finds the path at the point (@x, @y), relative to bin_window coordinates. See gtk_icon_view_get_item_at_pos(), if you are also interested in the cell at the specified position. See gtk_icon_view_convert_widget_to_bin_window_coords() for converting widget coordinates to bin_window coordinates. The #GtkTreePath corresponding to the icon or %NULL if no icon exists at that position. A #GtkIconView. The x position to be identified The y position to be identified Returns the column with pixbufs for @icon_view. the pixbuf column, or -1 if it’s unset. A #GtkIconView. Retrieves whether the user can reorder the list via drag-and-drop. See gtk_icon_view_set_reorderable(). %TRUE if the list can be reordered. a #GtkIconView Returns the value of the ::row-spacing property. the space between rows a #GtkIconView Creates a list of paths of all selected items. Additionally, if you are planning on modifying the model after calling this function, you may want to convert the returned list into a list of #GtkTreeRowReferences. To do this, you can use gtk_tree_row_reference_new(). To free the return value, use: |[<!-- language="C" --> g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); ]| A #GList containing a #GtkTreePath for each selected row. A #GtkIconView. Gets the selection mode of the @icon_view. the current selection mode A #GtkIconView. Returns the value of the ::spacing property. the space between cells a #GtkIconView Returns the column with text for @icon_view. the text column, or -1 if it’s unset. A #GtkIconView. Returns the column of @icon_view’s model which is being used for displaying tooltips on @icon_view’s rows. the index of the tooltip column that is currently being used, or -1 if this is disabled. a #GtkIconView This function is supposed to be used in a #GtkWidget::query-tooltip signal handler for #GtkIconView. The @x, @y and @keyboard_tip values which are received in the signal handler, should be passed to this function without modification. The return value indicates whether there is an icon view item at the given coordinates (%TRUE) or not (%FALSE) for mouse tooltips. For keyboard tooltips the item returned will be the cursor item. When %TRUE, then any of @model, @path and @iter which have been provided will be set to point to that row and the corresponding model. @x and @y will always be converted to be relative to @icon_view’s bin_window if @keyboard_tooltip is %FALSE. whether or not the given tooltip context points to a item an #GtkIconView the x coordinate (relative to widget coordinates) the y coordinate (relative to widget coordinates) whether this is a keyboard tooltip or not a pointer to receive a #GtkTreeModel or %NULL a pointer to receive a #GtkTreePath or %NULL a pointer to receive a #GtkTreeIter or %NULL Sets @start_path and @end_path to be the first and last visible path. Note that there may be invisible paths in between. Both paths should be freed with gtk_tree_path_free() after use. %TRUE, if valid paths were placed in @start_path and @end_path A #GtkIconView Return location for start of region, or %NULL Return location for end of region, or %NULL Activates the item determined by @path. A #GtkIconView The #GtkTreePath to be activated Returns %TRUE if the icon pointed to by @path is currently selected. If @path does not point to a valid location, %FALSE is returned. %TRUE if @path is selected. A #GtkIconView. A #GtkTreePath to check selection on. Moves the alignments of @icon_view to the position specified by @path. @row_align determines where the row is placed, and @col_align determines where @column is placed. Both are expected to be between 0.0 and 1.0. 0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 means center. If @use_align is %FALSE, then the alignment arguments are ignored, and the tree does the minimum amount of work to scroll the item onto the screen. This means that the item will be scrolled to the edge closest to its current position. If the item is currently visible on the screen, nothing is done. This function only works if the model is set, and @path is a valid row on the model. If the model changes before the @icon_view is realized, the centered path will be modified to reflect this change. A #GtkIconView. The path of the item to move to. whether to use alignment arguments, or %FALSE. The vertical alignment of the item specified by @path. The horizontal alignment of the item specified by @path. Selects all the icons. @icon_view must has its selection mode set to #GTK_SELECTION_MULTIPLE. A #GtkIconView. Selects the row at @path. A #GtkIconView. The #GtkTreePath to be selected. Calls a function for each selected icon. Note that the model or selection cannot be modified from within this function. A #GtkIconView. The function to call for each selected icon. User data to pass to the function. Causes the #GtkIconView::item-activated signal to be emitted on a single click instead of a double click. a #GtkIconView %TRUE to emit item-activated on a single click Sets the ::column-spacing property which specifies the space which is inserted between the columns of the icon view. a #GtkIconView the column spacing Sets the ::columns property which determines in how many columns the icons are arranged. If @columns is -1, the number of columns will be chosen automatically to fill the available area. a #GtkIconView the number of columns Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular item. If @cell is not %NULL, then focus is given to the cell specified by it. Additionally, if @start_editing is %TRUE, then editing should be started in the specified cell. This function is often followed by `gtk_widget_grab_focus (icon_view)` in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized. A #GtkIconView A #GtkTreePath One of the cell renderers of @icon_view, or %NULL %TRUE if the specified cell should start being edited. Sets the item that is highlighted for feedback. a #GtkIconView The path of the item to highlight, or %NULL. Specifies where to drop, relative to the item Sets the ::item-orientation property which determines whether the labels are drawn beside the icons instead of below. a #GtkIconView the relative position of texts and icons Sets the #GtkIconView:item-padding property which specifies the padding around each of the icon view’s items. a #GtkIconView the item padding Sets the ::item-width property which specifies the width to use for each item. If it is set to -1, the icon view will automatically determine a suitable item size. a #GtkIconView the width for each item Sets the ::margin property which specifies the space which is inserted at the top, bottom, left and right of the icon view. a #GtkIconView the margin Sets the column with markup information for @icon_view to be @column. The markup column must be of type #G_TYPE_STRING. If the markup column is set to something, it overrides the text column set by gtk_icon_view_set_text_column(). A #GtkIconView. A column in the currently used model, or -1 to display no text Sets the model for a #GtkIconView. If the @icon_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. A #GtkIconView. The model. Sets the column with pixbufs for @icon_view to be @column. The pixbuf column must be of type #GDK_TYPE_PIXBUF A #GtkIconView. A column in the currently used model, or -1 to disable This function is a convenience function to allow you to reorder models that support the #GtkTreeDragSourceIface and the #GtkTreeDragDestIface. Both #GtkTreeStore and #GtkListStore support these. If @reorderable is %TRUE, then the user can reorder the model by dragging and dropping rows. The developer can listen to these changes by connecting to the model's row_inserted and row_deleted signals. The reordering is implemented by setting up the icon view as a drag source and destination. Therefore, drag and drop can not be used in a reorderable view for any other purpose. This function does not give you any degree of control over the order -- any reordering is allowed. If more control is needed, you should probably handle drag and drop manually. A #GtkIconView. %TRUE, if the list of items can be reordered. Sets the ::row-spacing property which specifies the space which is inserted between the rows of the icon view. a #GtkIconView the row spacing Sets the selection mode of the @icon_view. A #GtkIconView. The selection mode Sets the ::spacing property which specifies the space which is inserted between the cells (i.e. the icon and the text) of an item. a #GtkIconView the spacing Sets the column with text for @icon_view to be @column. The text column must be of type #G_TYPE_STRING. A #GtkIconView. A column in the currently used model, or -1 to display no text Sets the tip area of @tooltip to the area which @cell occupies in the item pointed to by @path. See also gtk_tooltip_set_tip_area(). See also gtk_icon_view_set_tooltip_column() for a simpler alternative. a #GtkIconView a #GtkTooltip a #GtkTreePath a #GtkCellRenderer or %NULL If you only plan to have simple (text-only) tooltips on full items, you can use this function to have #GtkIconView handle these automatically for you. @column should be set to the column in @icon_view’s model containing the tooltip texts, or -1 to disable this feature. When enabled, #GtkWidget:has-tooltip will be set to %TRUE and @icon_view will connect a #GtkWidget::query-tooltip signal handler. Note that the signal handler sets the text with gtk_tooltip_set_markup(), so &, <, etc have to be escaped in the text. a #GtkIconView an integer, which is a valid column number for @icon_view’s model Sets the tip area of @tooltip to be the area covered by the item at @path. See also gtk_icon_view_set_tooltip_column() for a simpler alternative. See also gtk_tooltip_set_tip_area(). a #GtkIconView a #GtkTooltip a #GtkTreePath Unselects all the icons. A #GtkIconView. Unselects the row at @path. A #GtkIconView. The #GtkTreePath to be unselected. Undoes the effect of gtk_icon_view_enable_model_drag_dest(). Calling this method sets #GtkIconView:reorderable to %FALSE. a #GtkIconView Undoes the effect of gtk_icon_view_enable_model_drag_source(). Calling this method sets #GtkIconView:reorderable to %FALSE. a #GtkIconView The activate-on-single-click property specifies whether the "item-activated" signal will be emitted after a single click. The #GtkCellArea used to layout cell renderers for this view. If no area is specified when creating the icon view with gtk_icon_view_new_with_area() a #GtkCellAreaBox will be used. The column-spacing property specifies the space which is inserted between the columns of the icon view. The columns property contains the number of the columns in which the items should be displayed. If it is -1, the number of columns will be chosen automatically to fill the available area. The item-orientation property specifies how the cells (i.e. the icon and the text) of the item are positioned relative to each other. The item-padding property specifies the padding around each of the icon view's item. The item-width property specifies the width to use for each item. If it is set to -1, the icon view will automatically determine a suitable item size. The margin property specifies the space which is inserted at the edges of the icon view. The ::markup-column property contains the number of the model column containing markup information to be displayed. The markup column must be of type #G_TYPE_STRING. If this property and the :text-column property are both set to column numbers, it overrides the text column. If both are set to -1, no texts are displayed. The ::pixbuf-column property contains the number of the model column containing the pixbufs which are displayed. The pixbuf column must be of type #GDK_TYPE_PIXBUF. Setting this property to -1 turns off the display of pixbufs. The reorderable property specifies if the items can be reordered by DND. The row-spacing property specifies the space which is inserted between the rows of the icon view. The ::selection-mode property specifies the selection mode of icon view. If the mode is #GTK_SELECTION_MULTIPLE, rubberband selection is enabled, for the other modes, only keyboard selection is possible. The spacing property specifies the space which is inserted between the cells (i.e. the icon and the text) of an item. The ::text-column property contains the number of the model column containing the texts which are displayed. The text column must be of type #G_TYPE_STRING. If this property and the :markup-column property are both set to -1, no texts are displayed. A [keybinding signal][GtkBindingSignal] which gets emitted when the user activates the currently focused item. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control activation programmatically. The default bindings for this signal are Space, Return and Enter. The ::item-activated signal is emitted when the method gtk_icon_view_item_activated() is called, when the user double clicks an item with the "activate-on-single-click" property set to %FALSE, or when the user single clicks an item when the "activate-on-single-click" property set to %TRUE. It is also emitted when a non-editable item is selected and one of the keys: Space, Return or Enter is pressed. the #GtkTreePath for the activated item The ::move-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a cursor movement. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal include - Arrow keys which move by individual steps - Home/End keys which move to the first/last item - PageUp/PageDown which move by "pages" All of these will extend the selection when combined with the Shift modifier. the granularity of the move, as a #GtkMovementStep the number of @step units to move A [keybinding signal][GtkBindingSignal] which gets emitted when the user selects all items. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control selection programmatically. The default binding for this signal is Ctrl-a. A [keybinding signal][GtkBindingSignal] which gets emitted when the user selects the item that is currently focused. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control selection programmatically. There is no default binding for this signal. The ::selection-changed signal is emitted when the selection (i.e. the set of selected items) changes. A [keybinding signal][GtkBindingSignal] which gets emitted when the user toggles whether the currently focused item is selected or not. The exact effect of this depend on the selection mode. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control selection programmatically. There is no default binding for this signal is Ctrl-Space. A [keybinding signal][GtkBindingSignal] which gets emitted when the user unselects all items. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control selection programmatically. The default binding for this signal is Ctrl-Shift-a. A #GtkIconView The #GtkTreePath to be activated A #GtkIconView. A #GtkIconView. An enum for determining where a dropped item goes. no drop possible dropped item replaces the item droppped item is inserted to the left dropped item is inserted to the right dropped item is inserted above dropped item is inserted below A function used by gtk_icon_view_selected_foreach() to map all selected rows. It will be called on every selected row in the view. a #GtkIconView The #GtkTreePath of a selected row user data The #GtkImage widget displays an image. Various kinds of object can be displayed as an image; most typically, you would load a #GdkPixbuf ("pixel buffer") from a file, and then display that. There’s a convenience function to do this, gtk_image_new_from_file(), used as follows: |[<!-- language="C" --> GtkWidget *image; image = gtk_image_new_from_file ("myfile.png"); ]| If the file isn’t loaded successfully, the image will contain a “broken image” icon similar to that used in many web browsers. If you want to handle errors in loading the file yourself, for example by displaying an error message, then load the image with gdk_pixbuf_new_from_file(), then create the #GtkImage with gtk_image_new_from_pixbuf(). The image file may contain an animation, if so the #GtkImage will display an animation (#GdkPixbufAnimation) instead of a static image. #GtkImage is a subclass of #GtkMisc, which implies that you can align it (center, left, right) and add padding to it, using #GtkMisc methods. #GtkImage is a “no window” widget (has no #GdkWindow of its own), so by default does not receive events. If you want to receive events on the image, such as button clicks, place the image inside a #GtkEventBox, then connect to the event signals on the event box. ## Handling button press events on a #GtkImage. |[<!-- language="C" --> static gboolean button_press_callback (GtkWidget *event_box, GdkEventButton *event, gpointer data) { g_print ("Event box clicked at coordinates %f,%f\n", event->x, event->y); // Returning TRUE means we handled the event, so the signal // emission should be stopped (don’t call any further callbacks // that may be connected). Return FALSE to continue invoking callbacks. return TRUE; } static GtkWidget* create_image (void) { GtkWidget *image; GtkWidget *event_box; image = gtk_image_new_from_file ("myfile.png"); event_box = gtk_event_box_new (); gtk_container_add (GTK_CONTAINER (event_box), image); g_signal_connect (G_OBJECT (event_box), "button_press_event", G_CALLBACK (button_press_callback), image); return image; } ]| When handling events on the event box, keep in mind that coordinates in the image may be different from event box coordinates due to the alignment and padding settings on the image (see #GtkMisc). The simplest way to solve this is to set the alignment to 0.0 (left/top), and set the padding to zero. Then the origin of the image will be the same as the origin of the event box. Sometimes an application will want to avoid depending on external data files, such as image files. GTK+ comes with a program to avoid this, called “gdk-pixbuf-csource”. This library allows you to convert an image into a C variable declaration, which can then be loaded into a #GdkPixbuf using gdk_pixbuf_new_from_inline(). # CSS nodes GtkImage has a single CSS node with the name image. The style classes may appear on image CSS nodes: .icon-dropshadow, .lowres-icon. Creates a new empty #GtkImage widget. a newly created #GtkImage widget. Creates a #GtkImage displaying the given animation. The #GtkImage does not assume a reference to the animation; you still need to unref it if you own references. #GtkImage will add its own reference rather than adopting yours. Note that the animation frames are shown using a timeout with #G_PRIORITY_DEFAULT. When using animations to indicate busyness, keep in mind that the animation will only be shown if the main loop is not busy with something that has a higher priority. a new #GtkImage widget an animation Creates a new #GtkImage displaying the file @filename. If the file isn’t found or can’t be loaded, the resulting #GtkImage will display a “broken image” icon. This function never returns %NULL, it always returns a valid #GtkImage widget. If the file contains an animation, the image will contain an animation. If you need to detect failures to load the file, use gdk_pixbuf_new_from_file() to load the file yourself, then create the #GtkImage from the pixbuf. (Or for animations, use gdk_pixbuf_animation_new_from_file()). The storage type (gtk_image_get_storage_type()) of the returned image is not defined, it will be whatever is appropriate for displaying the file. a new #GtkImage a filename Creates a #GtkImage displaying an icon from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately. a new #GtkImage displaying the themed icon an icon a stock icon size (#GtkIconSize) Creates a #GtkImage displaying an icon from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately. a new #GtkImage displaying the themed icon an icon name or %NULL a stock icon size (#GtkIconSize) Creates a #GtkImage displaying an icon set. Sample stock sizes are #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_SMALL_TOOLBAR. Instead of using this function, usually it’s better to create a #GtkIconFactory, put your icon sets in the icon factory, add the icon factory to the list of default factories with gtk_icon_factory_add_default(), and then use gtk_image_new_from_stock(). This will allow themes to override the icon you ship with your application. The #GtkImage does not assume a reference to the icon set; you still need to unref it if you own references. #GtkImage will add its own reference rather than adopting yours. Use gtk_image_new_from_icon_name() instead. a new #GtkImage a #GtkIconSet a stock icon size (#GtkIconSize) Creates a new #GtkImage displaying @pixbuf. The #GtkImage does not assume a reference to the pixbuf; you still need to unref it if you own references. #GtkImage will add its own reference rather than adopting yours. Note that this function just creates an #GtkImage from the pixbuf. The #GtkImage created will not react to state changes. Should you want that, you should use gtk_image_new_from_icon_name(). a new #GtkImage a #GdkPixbuf, or %NULL Creates a new #GtkImage displaying the resource file @resource_path. If the file isn’t found or can’t be loaded, the resulting #GtkImage will display a “broken image” icon. This function never returns %NULL, it always returns a valid #GtkImage widget. If the file contains an animation, the image will contain an animation. If you need to detect failures to load the file, use gdk_pixbuf_new_from_file() to load the file yourself, then create the #GtkImage from the pixbuf. (Or for animations, use gdk_pixbuf_animation_new_from_file()). The storage type (gtk_image_get_storage_type()) of the returned image is not defined, it will be whatever is appropriate for displaying the file. a new #GtkImage a resource path Creates a #GtkImage displaying a stock icon. Sample stock icon names are #GTK_STOCK_OPEN, #GTK_STOCK_QUIT. Sample stock sizes are #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_SMALL_TOOLBAR. If the stock icon name isn’t known, the image will be empty. You can register your own stock icon names, see gtk_icon_factory_add_default() and gtk_icon_factory_add(). Use gtk_image_new_from_icon_name() instead. a new #GtkImage displaying the stock icon a stock icon name a stock icon size (#GtkIconSize) Creates a new #GtkImage displaying @surface. The #GtkImage does not assume a reference to the surface; you still need to unref it if you own references. #GtkImage will add its own reference rather than adopting yours. a new #GtkImage a #cairo_surface_t, or %NULL Resets the image to be empty. a #GtkImage Gets the #GdkPixbufAnimation being displayed by the #GtkImage. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_ANIMATION (see gtk_image_get_storage_type()). The caller of this function does not own a reference to the returned animation. the displayed animation, or %NULL if the image is empty a #GtkImage Gets the #GIcon and size being displayed by the #GtkImage. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_GICON (see gtk_image_get_storage_type()). The caller of this function does not own a reference to the returned #GIcon. a #GtkImage place to store a #GIcon, or %NULL place to store an icon size (#GtkIconSize), or %NULL Gets the icon name and size being displayed by the #GtkImage. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_ICON_NAME (see gtk_image_get_storage_type()). The returned string is owned by the #GtkImage and should not be freed. a #GtkImage place to store an icon name, or %NULL place to store an icon size (#GtkIconSize), or %NULL Gets the icon set and size being displayed by the #GtkImage. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_ICON_SET (see gtk_image_get_storage_type()). Use gtk_image_get_icon_name() instead. a #GtkImage location to store a #GtkIconSet, or %NULL location to store a stock icon size (#GtkIconSize), or %NULL Gets the #GdkPixbuf being displayed by the #GtkImage. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_PIXBUF (see gtk_image_get_storage_type()). The caller of this function does not own a reference to the returned pixbuf. the displayed pixbuf, or %NULL if the image is empty a #GtkImage Gets the pixel size used for named icons. the pixel size used for named icons. a #GtkImage Gets the stock icon name and size being displayed by the #GtkImage. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_STOCK (see gtk_image_get_storage_type()). The returned string is owned by the #GtkImage and should not be freed. Use gtk_image_get_icon_name() instead. a #GtkImage place to store a stock icon name, or %NULL place to store a stock icon size (#GtkIconSize), or %NULL Gets the type of representation being used by the #GtkImage to store image data. If the #GtkImage has no image data, the return value will be %GTK_IMAGE_EMPTY. image representation being used a #GtkImage Causes the #GtkImage to display the given animation (or display nothing, if you set the animation to %NULL). a #GtkImage the #GdkPixbufAnimation See gtk_image_new_from_file() for details. a #GtkImage a filename or %NULL See gtk_image_new_from_gicon() for details. a #GtkImage an icon an icon size (#GtkIconSize) See gtk_image_new_from_icon_name() for details. a #GtkImage an icon name or %NULL an icon size (#GtkIconSize) See gtk_image_new_from_icon_set() for details. Use gtk_image_set_from_icon_name() instead. a #GtkImage a #GtkIconSet a stock icon size (#GtkIconSize) See gtk_image_new_from_pixbuf() for details. a #GtkImage a #GdkPixbuf or %NULL See gtk_image_new_from_resource() for details. a #GtkImage a resource path or %NULL See gtk_image_new_from_stock() for details. Use gtk_image_set_from_icon_name() instead. a #GtkImage a stock icon name a stock icon size (#GtkIconSize) See gtk_image_new_from_surface() for details. a #GtkImage a cairo_surface_t or %NULL Sets the pixel size to use for named icons. If the pixel size is set to a value != -1, it is used instead of the icon size set by gtk_image_set_from_icon_name(). a #GtkImage the new pixel size The GIcon displayed in the GtkImage. For themed icons, If the icon theme is changed, the image will be updated automatically. The name of the icon in the icon theme. If the icon theme is changed, the image will be updated automatically. Use #GtkImage:icon-name instead. The "pixel-size" property can be used to specify a fixed size overriding the #GtkImage:icon-size property for images of type %GTK_IMAGE_ICON_NAME. A path to a resource file to display. Use #GtkImage:icon-name instead. Whether the icon displayed in the GtkImage will use standard icon names fallback. The value of this property is only relevant for images of type %GTK_IMAGE_ICON_NAME and %GTK_IMAGE_GICON. A GtkImageMenuItem is a menu item which has an icon next to the text label. This is functionally equivalent to: |[<!-- language="C" --> GtkWidget *box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 6); GtkWidget *icon = gtk_image_new_from_icon_name ("folder-music-symbolic", GTK_ICON_SIZE_MENU); GtkWidget *label = gtk_label_new ("Music"); GtkWidget *menu_item = gtk_menu_item_new (); gtk_container_add (GTK_CONTAINER (box), icon); gtk_container_add (GTK_CONTAINER (box), label); gtk_container_add (GTK_CONTAINER (menu_item), box); gtk_widget_show_all (menu_item); ]| Note that the user may disable display of menu icons using the #GtkSettings:gtk-menu-images setting, so make sure to still fill in the text label. If you want to ensure that your menu items show an icon you are strongly encouraged to use a #GtkMenuItem with a #GtkImage instead. #GtkImageMenuItem has been deprecated since GTK+ 3.10. If you want to display an icon in a menu item, you should use #GtkMenuItem and pack a #GtkBox with a #GtkImage and a #GtkLabel instead. You should also consider using #GtkBuilder and the XML #GMenu description for creating menus, by following the [GMenu guide][https://developer.gnome.org/GMenu/]. You should consider using icons in menu items only sparingly, and for "objects" (or "nouns") elements only, like bookmarks, files, and links; "actions" (or "verbs") should not have icons. Furthermore, if you would like to display keyboard accelerator, you must pack the accel label into the box using gtk_box_pack_end() and align the label, otherwise the accelerator will not display correctly. The following code snippet adds a keyboard accelerator to the menu item, with a key binding of Ctrl+M: |[<!-- language="C" --> GtkWidget *box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 6); GtkWidget *icon = gtk_image_new_from_icon_name ("folder-music-symbolic", GTK_ICON_SIZE_MENU); GtkWidget *label = gtk_accel_label_new ("Music"); GtkWidget *menu_item = gtk_menu_item_new (); GtkAccelGroup *accel_group = gtk_accel_group_new (); gtk_container_add (GTK_CONTAINER (box), icon); gtk_label_set_use_underline (GTK_LABEL (label), TRUE); gtk_label_set_xalign (GTK_LABEL (label), 0.0); gtk_widget_add_accelerator (menu_item, "activate", accel_group, GDK_KEY_m, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE); gtk_accel_label_set_accel_widget (GTK_ACCEL_LABEL (label), menu_item); gtk_box_pack_end (GTK_BOX (box), label, TRUE, TRUE, 0); gtk_container_add (GTK_CONTAINER (menu_item), box); gtk_widget_show_all (menu_item); ]| Creates a new #GtkImageMenuItem with an empty label. Use gtk_menu_item_new() instead. a new #GtkImageMenuItem Creates a new #GtkImageMenuItem containing the image and text from a stock item. Some stock ids have preprocessor macros like #GTK_STOCK_OK and #GTK_STOCK_APPLY. If you want this menu item to have changeable accelerators, then pass in %NULL for accel_group. Next call gtk_menu_item_set_accel_path() with an appropriate path for the menu item, use gtk_stock_lookup() to look up the standard accelerator for the stock item, and if one is found, call gtk_accel_map_add_entry() to register it. Use gtk_menu_item_new_with_mnemonic() instead. a new #GtkImageMenuItem. the name of the stock item. the #GtkAccelGroup to add the menu items accelerator to, or %NULL. Creates a new #GtkImageMenuItem containing a label. Use gtk_menu_item_new_with_label() instead. a new #GtkImageMenuItem. the text of the menu item. Creates a new #GtkImageMenuItem containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the menu item. Use gtk_menu_item_new_with_mnemonic() instead. a new #GtkImageMenuItem the text of the menu item, with an underscore in front of the mnemonic character Returns whether the menu item will ignore the #GtkSettings:gtk-menu-images setting and always show the image, if available. %TRUE if the menu item will always show the image a #GtkImageMenuItem Gets the widget that is currently set as the image of @image_menu_item. See gtk_image_menu_item_set_image(). the widget set as image of @image_menu_item a #GtkImageMenuItem Checks whether the label set in the menuitem is used as a stock id to select the stock item for the item. %TRUE if the label set in the menuitem is used as a stock id to select the stock item for the item a #GtkImageMenuItem Specifies an @accel_group to add the menu items accelerator to (this only applies to stock items so a stock item must already be set, make sure to call gtk_image_menu_item_set_use_stock() and gtk_menu_item_set_label() with a valid stock item first). If you want this menu item to have changeable accelerators then you shouldnt need this (see gtk_image_menu_item_new_from_stock()). a #GtkImageMenuItem the #GtkAccelGroup If %TRUE, the menu item will ignore the #GtkSettings:gtk-menu-images setting and always show the image, if available. Use this property if the menuitem would be useless or hard to use without the image. a #GtkImageMenuItem %TRUE if the menuitem should always show the image Sets the image of @image_menu_item to the given widget. Note that it depends on the show-menu-images setting whether the image will be displayed or not. a #GtkImageMenuItem. a widget to set as the image for the menu item. If %TRUE, the label set in the menuitem is used as a stock id to select the stock item for the item. a #GtkImageMenuItem %TRUE if the menuitem should use a stock item The Accel Group to use for stock accelerator keys Use gtk_widget_add_accelerator() instead If %TRUE, the menu item will always show the image, if available. Use this property only if the menuitem would be useless or hard to use without the image. Use a #GtkMenuItem containing a #GtkBox with a #GtkAccelLabel and a #GtkImage instead Child widget to appear next to the menu text. Use a #GtkMenuItem containing a #GtkBox with a #GtkAccelLabel and a #GtkImage instead If %TRUE, the label set in the menuitem is used as a stock id to select the stock item for the item. Use a named icon from the #GtkIconTheme instead The parent class. Describes the image data representation used by a #GtkImage. If you want to get the image from the widget, you can only get the currently-stored representation. e.g. if the gtk_image_get_storage_type() returns #GTK_IMAGE_PIXBUF, then you can call gtk_image_get_pixbuf() but not gtk_image_get_stock(). For empty images, you can request any storage type (call any of the "get" functions), but they will all return %NULL values. there is no image displayed by the widget the widget contains a #GdkPixbuf the widget contains a [stock item name][gtkstock] the widget contains a #GtkIconSet the widget contains a #GdkPixbufAnimation the widget contains a named icon. This image type was added in GTK+ 2.6 the widget contains a #GIcon. This image type was added in GTK+ 2.14 the widget contains a #cairo_surface_t. This image type was added in GTK+ 3.10 #GtkInfoBar is a widget that can be used to show messages to the user without showing a dialog. It is often temporarily shown at the top or bottom of a document. In contrast to #GtkDialog, which has a action area at the bottom, #GtkInfoBar has an action area at the side. The API of #GtkInfoBar is very similar to #GtkDialog, allowing you to add buttons to the action area with gtk_info_bar_add_button() or gtk_info_bar_new_with_buttons(). The sensitivity of action widgets can be controlled with gtk_info_bar_set_response_sensitive(). To add widgets to the main content area of a #GtkInfoBar, use gtk_info_bar_get_content_area() and add your widgets to the container. Similar to #GtkMessageDialog, the contents of a #GtkInfoBar can by classified as error message, warning, informational message, etc, by using gtk_info_bar_set_message_type(). GTK+ may use the message type to determine how the message is displayed. A simple example for using a #GtkInfoBar: |[<!-- language="C" --> GtkWidget *widget, *message_label, *content_area; GtkWidget *grid; GtkInfoBar *bar; // set up info bar widget = gtk_info_bar_new (); bar = GTK_INFO_BAR (widget); grid = gtk_grid_new (); gtk_widget_set_no_show_all (widget, TRUE); message_label = gtk_label_new (""); content_area = gtk_info_bar_get_content_area (bar); gtk_container_add (GTK_CONTAINER (content_area), message_label); gtk_info_bar_add_button (bar, _("_OK"), GTK_RESPONSE_OK); g_signal_connect (bar, "response", G_CALLBACK (gtk_widget_hide), NULL); gtk_grid_attach (GTK_GRID (grid), widget, 0, 2, 1, 1); // ... // show an error message gtk_label_set_text (GTK_LABEL (message_label), "An error occurred!"); gtk_info_bar_set_message_type (bar, GTK_MESSAGE_ERROR); gtk_widget_show (bar); ]| # GtkInfoBar as GtkBuildable The GtkInfoBar implementation of the GtkBuildable interface exposes the content area and action area as internal children with the names “content_area” and “action_area”. GtkInfoBar supports a custom `<action-widgets>` element, which can contain multiple `<action-widget>` elements. The “response” attribute specifies a numeric response, and the content of the element is the id of widget (which should be a child of the dialogs @action_area). # CSS nodes GtkInfoBar has a single CSS node with name infobar. The node may get one of the style classes .info, .warning, .error or .question, depending on the message type. Creates a new #GtkInfoBar object. a new #GtkInfoBar object Creates a new #GtkInfoBar with buttons. Button text/response ID pairs should be listed, with a %NULL pointer ending the list. Button text can be either a stock ID such as %GTK_STOCK_OK, or some arbitrary text. A response ID can be any positive number, or one of the values in the #GtkResponseType enumeration. If the user clicks one of these dialog buttons, GtkInfoBar will emit the “response” signal with the corresponding response ID. a new #GtkInfoBar stock ID or text to go in first button, or %NULL response ID for first button, then additional buttons, ending with %NULL Emits the “response” signal with the given @response_id. a #GtkInfoBar a response ID Add an activatable widget to the action area of a #GtkInfoBar, connecting a signal handler that will emit the #GtkInfoBar::response signal on the message area when the widget is activated. The widget is appended to the end of the message areas action area. a #GtkInfoBar an activatable widget response ID for @child Adds a button with the given text and sets things up so that clicking the button will emit the “response” signal with the given response_id. The button is appended to the end of the info bars's action area. The button widget is returned, but usually you don't need it. the #GtkButton widget that was added a #GtkInfoBar text of button response ID for the button Adds more buttons, same as calling gtk_info_bar_add_button() repeatedly. The variable argument list should be %NULL-terminated as with gtk_info_bar_new_with_buttons(). Each button must have both text and response ID. a #GtkInfoBar button text or stock ID response ID for first button, then more text-response_id pairs, ending with %NULL Returns the action area of @info_bar. the action area a #GtkInfoBar Returns the content area of @info_bar. the content area a #GtkInfoBar Returns the message type of the message area. the message type of the message area. a #GtkInfoBar the current value of the GtkInfoBar:revealed property. a #GtkInfoBar Returns whether the widget will display a standard close button. %TRUE if the widget displays standard close button a #GtkInfoBar Emits the “response” signal with the given @response_id. a #GtkInfoBar a response ID Sets the last widget in the info bar’s action area with the given response_id as the default widget for the dialog. Pressing “Enter” normally activates the default widget. Note that this function currently requires @info_bar to be added to a widget hierarchy. a #GtkInfoBar a response ID Sets the message type of the message area. GTK+ uses this type to determine how the message is displayed. a #GtkInfoBar a #GtkMessageType Calls gtk_widget_set_sensitive (widget, setting) for each widget in the info bars’s action area with the given response_id. A convenient way to sensitize/desensitize dialog buttons. a #GtkInfoBar a response ID TRUE for sensitive Sets the GtkInfoBar:revealed property to @revealed. This will cause @info_bar to show up with a slide-in transition. Note that this property does not automatically show @info_bar and thus won’t have any effect if it is invisible. a #GtkInfoBar The new value of the property If true, a standard close button is shown. When clicked it emits the response %GTK_RESPONSE_CLOSE. a #GtkInfoBar %TRUE to include a close button The type of the message. The type may be used to determine the appearance of the info bar. Whether to include a standard close button. The ::close signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user uses a keybinding to dismiss the info bar. The default binding for this signal is the Escape key. Emitted when an action widget is clicked or the application programmer calls gtk_dialog_response(). The @response_id depends on which action widget was clicked. the response ID a #GtkInfoBar a response ID Describes hints that might be taken into account by input methods or applications. Note that input methods may already tailor their behaviour according to the #GtkInputPurpose of the entry. Some common sense is expected when using these flags - mixing @GTK_INPUT_HINT_LOWERCASE with any of the uppercase hints makes no sense. This enumeration may be extended in the future; input methods should ignore unknown values. No special behaviour suggested Suggest checking for typos Suggest not checking for typos Suggest word completion Suggest to convert all text to lowercase Suggest to capitalize all text Suggest to capitalize the first character of each word Suggest to capitalize the first word of each sentence Suggest to not show an onscreen keyboard (e.g for a calculator that already has all the keys). The text is vertical. Since 3.18 Suggest offering Emoji support. Since 3.22.20 Suggest not offering Emoji support. Since 3.22.20 Describes primary purpose of the input widget. This information is useful for on-screen keyboards and similar input methods to decide which keys should be presented to the user. Note that the purpose is not meant to impose a totally strict rule about allowed characters, and does not replace input validation. It is fine for an on-screen keyboard to let the user override the character set restriction that is expressed by the purpose. The application is expected to validate the entry contents, even if it specified a purpose. The difference between @GTK_INPUT_PURPOSE_DIGITS and @GTK_INPUT_PURPOSE_NUMBER is that the former accepts only digits while the latter also some punctuation (like commas or points, plus, minus) and “e” or “E” as in 3.14E+000. This enumeration may be extended in the future; input methods should interpret unknown values as “free form”. Allow any character Allow only alphabetic characters Allow only digits Edited field expects numbers Edited field expects phone number Edited field expects URL Edited field expects email address Edited field expects the name of a person Like @GTK_INPUT_PURPOSE_FREE_FORM, but characters are hidden Like @GTK_INPUT_PURPOSE_DIGITS, but characters are hidden Allow any character, in addition to control codes The #GtkInvisible widget is used internally in GTK+, and is probably not very useful for application developers. It is used for reliable pointer grabs and selection handling in the code for drag-and-drop. Creates a new #GtkInvisible. a new #GtkInvisible. Creates a new #GtkInvisible object for a specified screen a newly created #GtkInvisible object a #GdkScreen which identifies on which the new #GtkInvisible will be created. Returns the #GdkScreen object associated with @invisible the associated #GdkScreen. a #GtkInvisible. Sets the #GdkScreen where the #GtkInvisible object will be displayed. a #GtkInvisible. a #GdkScreen. Describes how a rendered element connects to adjacent elements. No junctions. Element connects on the top-left corner. Element connects on the top-right corner. Element connects on the bottom-left corner. Element connects on the bottom-right corner. Element connects on the top side. Element connects on the bottom side. Element connects on the left side. Element connects on the right side. Used for justifying the text inside a #GtkLabel widget. (See also #GtkAlignment). The text is placed at the left edge of the label. The text is placed at the right edge of the label. The text is placed in the center of the label. The text is placed is distributed across the label. Key snooper functions are called before normal event delivery. They can be used to implement custom key event handling. %TRUE to stop further processing of @event, %FALSE to continue. the widget to which the event will be delivered the key event data supplied to gtk_key_snooper_install() The name used for the stock full offset included by #GtkLevelBar. The name used for the stock high offset included by #GtkLevelBar. The name used for the stock low offset included by #GtkLevelBar. The #GtkLabel widget displays a small amount of text. As the name implies, most labels are used to label another widget such as a #GtkButton, a #GtkMenuItem, or a #GtkComboBox. # CSS nodes |[<!-- language="plain" --> label ├── [selection] ├── [link] ┊ ╰── [link] ]| GtkLabel has a single CSS node with the name label. A wide variety of style classes may be applied to labels, such as .title, .subtitle, .dim-label, etc. In the #GtkShortcutsWindow, labels are used wth the .keycap style class. If the label has a selection, it gets a subnode with name selection. If the label has links, there is one subnode per link. These subnodes carry the link or visited state depending on whether they have been visited. # GtkLabel as GtkBuildable The GtkLabel implementation of the GtkBuildable interface supports a custom `<attributes>` element, which supports any number of `<attribute>` elements. The `<attribute>` element has attributes named “name“, “value“, “start“ and “end“ and allows you to specify #PangoAttribute values for this label. An example of a UI definition fragment specifying Pango attributes: |[<!-- language="xml" --> <object class="GtkLabel"> <attributes> <attribute name="weight" value="PANGO_WEIGHT_BOLD"/> <attribute name="background" value="red" start="5" end="10"/> </attributes> </object> ]| The start and end attributes specify the range of characters to which the Pango attribute applies. If start and end are not specified, the attribute is applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup embedded in the translatable content instead. # Mnemonics Labels may contain “mnemonics”. Mnemonics are underlined characters in the label, used for keyboard navigation. Mnemonics are created by providing a string with an underscore before the mnemonic character, such as `"_File"`, to the functions gtk_label_new_with_mnemonic() or gtk_label_set_text_with_mnemonic(). Mnemonics automatically activate any activatable widget the label is inside, such as a #GtkButton; if the label is not inside the mnemonic’s target widget, you have to tell the label about the target using gtk_label_set_mnemonic_widget(). Here’s a simple example where the label is inside a button: |[<!-- language="C" --> // Pressing Alt+H will activate this button GtkWidget *button = gtk_button_new (); GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello"); gtk_container_add (GTK_CONTAINER (button), label); ]| There’s a convenience function to create buttons with a mnemonic label already inside: |[<!-- language="C" --> // Pressing Alt+H will activate this button GtkWidget *button = gtk_button_new_with_mnemonic ("_Hello"); ]| To create a mnemonic for a widget alongside the label, such as a #GtkEntry, you have to point the label at the entry with gtk_label_set_mnemonic_widget(): |[<!-- language="C" --> // Pressing Alt+H will focus the entry GtkWidget *entry = gtk_entry_new (); GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello"); gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry); ]| # Markup (styled text) To make it easy to format text in a label (changing colors, fonts, etc.), label text can be provided in a simple [markup format][PangoMarkupFormat]. Here’s how to create a label with a small font: |[<!-- language="C" --> GtkWidget *label = gtk_label_new (NULL); gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>"); ]| (See [complete documentation][PangoMarkupFormat] of available tags in the Pango manual.) The markup passed to gtk_label_set_markup() must be valid; for example, literal <, > and & characters must be escaped as &lt;, &gt;, and &amp;. If you pass text obtained from the user, file, or a network to gtk_label_set_markup(), you’ll want to escape it with g_markup_escape_text() or g_markup_printf_escaped(). Markup strings are just a convenient way to set the #PangoAttrList on a label; gtk_label_set_attributes() may be a simpler way to set attributes in some cases. Be careful though; #PangoAttrList tends to cause internationalization problems, unless you’re applying attributes to the entire string (i.e. unless you set the range of each attribute to [0, %G_MAXINT)). The reason is that specifying the start_index and end_index for a #PangoAttribute requires knowledge of the exact string being displayed, so translations will cause problems. # Selectable labels Labels can be made selectable with gtk_label_set_selectable(). Selectable labels allow the user to copy the label contents to the clipboard. Only labels that contain useful-to-copy information — such as error messages — should be made selectable. # Text layout # {#label-text-layout} A label can contain any number of paragraphs, but will have performance problems if it contains more than a small number. Paragraphs are separated by newlines or other paragraph separators understood by Pango. Labels can automatically wrap text if you call gtk_label_set_line_wrap(). gtk_label_set_justify() sets how the lines in a label align with one another. If you want to set how the label as a whole aligns in its available space, see the #GtkWidget:halign and #GtkWidget:valign properties. The #GtkLabel:width-chars and #GtkLabel:max-width-chars properties can be used to control the size allocation of ellipsized or wrapped labels. For ellipsizing labels, if either is specified (and less than the actual text size), it is used as the minimum width, and the actual text size is used as the natural width of the label. For wrapping labels, width-chars is used as the minimum width, if specified, and max-width-chars is used as the natural width. Even if max-width-chars specified, wrapping labels will be rewrapped to use all of the available width. Note that the interpretation of #GtkLabel:width-chars and #GtkLabel:max-width-chars has changed a bit with the introduction of [width-for-height geometry management.][geometry-management] # Links Since 2.18, GTK+ supports markup for clickable hyperlinks in addition to regular Pango markup. The markup for links is borrowed from HTML, using the `<a>` with “href“ and “title“ attributes. GTK+ renders links similar to the way they appear in web browsers, with colored, underlined text. The “title“ attribute is displayed as a tooltip on the link. An example looks like this: |[<!-- language="C" --> const gchar *text = "Go to the" "<a href=\"http://www.gtk.org title=\"&lt;i&gt;Our&lt;/i&gt; website\">" "GTK+ website</a> for more..."; GtkWidget *label = gtk_label_new (NULL); gtk_label_set_markup (GTK_LABEL (label), text); ]| It is possible to implement custom handling for links and their tooltips with the #GtkLabel::activate-link signal and the gtk_label_get_current_uri() function. Creates a new label with the given text inside it. You can pass %NULL to get an empty label widget. the new #GtkLabel The text of the label Creates a new #GtkLabel, containing the text in @str. If characters in @str are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use '__' (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using gtk_label_set_mnemonic_widget(). If gtk_label_set_mnemonic_widget() is not called, then the first activatable ancestor of the #GtkLabel will be chosen as the mnemonic widget. For instance, if the label is inside a button or menu item, the button or menu item will automatically become the mnemonic widget and be activated by the mnemonic. the new #GtkLabel The text of the label, with an underscore in front of the mnemonic character Gets the angle of rotation for the label. See gtk_label_set_angle(). the angle of rotation for the label a #GtkLabel Gets the attribute list that was set on the label using gtk_label_set_attributes(), if any. This function does not reflect attributes that come from the labels markup (see gtk_label_set_markup()). If you want to get the effective attributes for the label, use pango_layout_get_attribute (gtk_label_get_layout (label)). the attribute list, or %NULL if none was set. a #GtkLabel Returns the URI for the currently active link in the label. The active link is the one under the mouse pointer or, in a selectable label, the link in which the text cursor is currently positioned. This function is intended for use in a #GtkLabel::activate-link handler or for use in a #GtkWidget::query-tooltip handler. the currently active URI. The string is owned by GTK+ and must not be freed or modified. a #GtkLabel Returns the ellipsizing position of the label. See gtk_label_set_ellipsize(). #PangoEllipsizeMode a #GtkLabel Returns the justification of the label. See gtk_label_set_justify(). #GtkJustification a #GtkLabel Fetches the text from a label widget including any embedded underlines indicating mnemonics and Pango markup. (See gtk_label_get_text()). the text of the label widget. This string is owned by the widget and must not be modified or freed. a #GtkLabel Gets the #PangoLayout used to display the label. The layout is useful to e.g. convert text positions to pixel positions, in combination with gtk_label_get_layout_offsets(). The returned layout is owned by the @label so need not be freed by the caller. The @label is free to recreate its layout at any time, so it should be considered read-only. the #PangoLayout for this label a #GtkLabel Obtains the coordinates where the label will draw the #PangoLayout representing the text in the label; useful to convert mouse events into coordinates inside the #PangoLayout, e.g. to take some action if some part of the label is clicked. Of course you will need to create a #GtkEventBox to receive the events, and pack the label inside it, since labels are windowless (they return %FALSE from gtk_widget_get_has_window()). Remember when using the #PangoLayout functions you need to convert to and from pixels using PANGO_PIXELS() or #PANGO_SCALE. a #GtkLabel location to store X offset of layout, or %NULL location to store Y offset of layout, or %NULL Returns whether lines in the label are automatically wrapped. See gtk_label_set_line_wrap(). %TRUE if the lines of the label are automatically wrapped. a #GtkLabel Returns line wrap mode used by the label. See gtk_label_set_line_wrap_mode(). %TRUE if the lines of the label are automatically wrapped. a #GtkLabel Gets the number of lines to which an ellipsized, wrapping label should be limited. See gtk_label_set_lines(). The number of lines a #GtkLabel Retrieves the desired maximum width of @label, in characters. See gtk_label_set_width_chars(). the maximum width of the label in characters. a #GtkLabel If the label has been set so that it has an mnemonic key this function returns the keyval used for the mnemonic accelerator. If there is no mnemonic set up it returns #GDK_KEY_VoidSymbol. GDK keyval usable for accelerators, or #GDK_KEY_VoidSymbol a #GtkLabel Retrieves the target of the mnemonic (keyboard shortcut) of this label. See gtk_label_set_mnemonic_widget(). the target of the label’s mnemonic, or %NULL if none has been set and the default algorithm will be used. a #GtkLabel Gets the value set by gtk_label_set_selectable(). %TRUE if the user can copy text from the label a #GtkLabel Gets the selected range of characters in the label, returning %TRUE if there’s a selection. %TRUE if selection is non-empty a #GtkLabel return location for start of selection, as a character offset return location for end of selection, as a character offset Returns whether the label is in single line mode. %TRUE when the label is in single line mode. a #GtkLabel Fetches the text from a label widget, as displayed on the screen. This does not include any embedded underlines indicating mnemonics or Pango markup. (See gtk_label_get_label()) the text in the label widget. This is the internal string used by the label, and must not be modified. a #GtkLabel Returns whether the label is currently keeping track of clicked links. %TRUE if clicked links are remembered a #GtkLabel Returns whether the label’s text is interpreted as marked up with the [Pango text markup language][PangoMarkupFormat]. See gtk_label_set_use_markup (). %TRUE if the label’s text will be parsed for markup. a #GtkLabel Returns whether an embedded underline in the label indicates a mnemonic. See gtk_label_set_use_underline(). %TRUE whether an embedded underline in the label indicates the mnemonic accelerator keys. a #GtkLabel Retrieves the desired width of @label, in characters. See gtk_label_set_width_chars(). the width of the label in characters. a #GtkLabel Gets the #GtkLabel:xalign property for @label. the xalign property a #GtkLabel Gets the #GtkLabel:yalign property for @label. the yalign property a #GtkLabel Selects a range of characters in the label, if the label is selectable. See gtk_label_set_selectable(). If the label is not selectable, this function has no effect. If @start_offset or @end_offset are -1, then the end of the label will be substituted. a #GtkLabel start offset (in characters not bytes) end offset (in characters not bytes) Sets the angle of rotation for the label. An angle of 90 reads from from bottom to top, an angle of 270, from top to bottom. The angle setting for the label is ignored if the label is selectable, wrapped, or ellipsized. a #GtkLabel the angle that the baseline of the label makes with the horizontal, in degrees, measured counterclockwise Sets a #PangoAttrList; the attributes in the list are applied to the label text. The attributes set with this function will be applied and merged with any other attributes previously effected by way of the #GtkLabel:use-underline or #GtkLabel:use-markup properties. While it is not recommended to mix markup strings with manually set attributes, if you must; know that the attributes will be applied to the label after the markup string is parsed. a #GtkLabel a #PangoAttrList, or %NULL Sets the mode used to ellipsize (add an ellipsis: "...") to the text if there is not enough space to render the entire string. a #GtkLabel a #PangoEllipsizeMode Sets the alignment of the lines in the text of the label relative to each other. %GTK_JUSTIFY_LEFT is the default value when the widget is first created with gtk_label_new(). If you instead want to set the alignment of the label as a whole, use gtk_widget_set_halign() instead. gtk_label_set_justify() has no effect on labels containing only a single line. a #GtkLabel a #GtkJustification Sets the text of the label. The label is interpreted as including embedded underlines and/or Pango markup depending on the values of the #GtkLabel:use-underline and #GtkLabel:use-markup properties. a #GtkLabel the new text to set for the label Toggles line wrapping within the #GtkLabel widget. %TRUE makes it break lines if text exceeds the widget’s size. %FALSE lets the text get cut off by the edge of the widget if it exceeds the widget size. Note that setting line wrapping to %TRUE does not make the label wrap at its parent container’s width, because GTK+ widgets conceptually can’t make their requisition depend on the parent container’s size. For a label that wraps at a specific position, set the label’s width using gtk_widget_set_size_request(). a #GtkLabel the setting If line wrapping is on (see gtk_label_set_line_wrap()) this controls how the line wrapping is done. The default is %PANGO_WRAP_WORD which means wrap on word boundaries. a #GtkLabel the line wrapping mode Sets the number of lines to which an ellipsized, wrapping label should be limited. This has no effect if the label is not wrapping or ellipsized. Set this to -1 if you don’t want to limit the number of lines. a #GtkLabel the desired number of lines, or -1 Parses @str which is marked up with the [Pango text markup language][PangoMarkupFormat], setting the label’s text and attribute list based on the parse results. If the @str is external data, you may need to escape it with g_markup_escape_text() or g_markup_printf_escaped(): |[<!-- language="C" --> GtkWidget *label = gtk_label_new (NULL); const char *str = "some text"; const char *format = "<span style=\"italic\">\%s</span>"; char *markup; markup = g_markup_printf_escaped (format, str); gtk_label_set_markup (GTK_LABEL (label), markup); g_free (markup); ]| This function will set the #GtkLabel:use-markup property to %TRUE as a side effect. If you set the label contents using the #GtkLabel:label property you should also ensure that you set the #GtkLabel:use-markup property accordingly. See also: gtk_label_set_text() a #GtkLabel a markup string (see [Pango markup format][PangoMarkupFormat]) Parses @str which is marked up with the [Pango text markup language][PangoMarkupFormat], setting the label’s text and attribute list based on the parse results. If characters in @str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using gtk_label_set_mnemonic_widget(). a #GtkLabel a markup string (see [Pango markup format][PangoMarkupFormat]) Sets the desired maximum width in characters of @label to @n_chars. a #GtkLabel the new desired maximum width, in characters. If the label has been set so that it has an mnemonic key (using i.e. gtk_label_set_markup_with_mnemonic(), gtk_label_set_text_with_mnemonic(), gtk_label_new_with_mnemonic() or the “use_underline” property) the label can be associated with a widget that is the target of the mnemonic. When the label is inside a widget (like a #GtkButton or a #GtkNotebook tab) it is automatically associated with the correct widget, but sometimes (i.e. when the target is a #GtkEntry next to the label) you need to set it explicitly using this function. The target widget will be accelerated by emitting the GtkWidget::mnemonic-activate signal on it. The default handler for this signal will activate the widget if there are no mnemonic collisions and toggle focus between the colliding widgets otherwise. a #GtkLabel the target #GtkWidget, or %NULL to unset The pattern of underlines you want under the existing text within the #GtkLabel widget. For example if the current text of the label says “FooBarBaz” passing a pattern of “___ ___” will underline “Foo” and “Baz” but not “Bar”. The #GtkLabel you want to set the pattern to. The pattern as described above. Selectable labels allow the user to select text from the label, for copy-and-paste. a #GtkLabel %TRUE to allow selecting text in the label Sets whether the label is in single line mode. a #GtkLabel %TRUE if the label should be in single line mode Sets the text within the #GtkLabel widget. It overwrites any text that was there before. This function will clear any previously set mnemonic accelerators, and set the #GtkLabel:use-underline property to %FALSE as a side effect. This function will set the #GtkLabel:use-markup property to %FALSE as a side effect. See also: gtk_label_set_markup() a #GtkLabel The text you want to set Sets the label’s text from the string @str. If characters in @str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using gtk_label_set_mnemonic_widget(). a #GtkLabel a string Sets whether the label should keep track of clicked links (and use a different color for them). a #GtkLabel %TRUE to track visited links Sets whether the text of the label contains markup in [Pango’s text markup language][PangoMarkupFormat]. See gtk_label_set_markup(). a #GtkLabel %TRUE if the label’s text should be parsed for markup. If true, an underline in the text indicates the next character should be used for the mnemonic accelerator key. a #GtkLabel %TRUE if underlines in the text indicate mnemonics Sets the desired width in characters of @label to @n_chars. a #GtkLabel the new desired width, in characters. Sets the #GtkLabel:xalign property for @label. a #GtkLabel the new xalign value, between 0 and 1 Sets the #GtkLabel:yalign property for @label. a #GtkLabel the new yalign value, between 0 and 1 The angle that the baseline of the label makes with the horizontal, in degrees, measured counterclockwise. An angle of 90 reads from from bottom to top, an angle of 270, from top to bottom. Ignored if the label is selectable. The preferred place to ellipsize the string, if the label does not have enough room to display the entire string, specified as a #PangoEllipsizeMode. Note that setting this property to a value other than %PANGO_ELLIPSIZE_NONE has the side-effect that the label requests only enough space to display the ellipsis "...". In particular, this means that ellipsizing labels do not work well in notebook tabs, unless the #GtkNotebook tab-expand child property is set to %TRUE. Other ways to set a label's width are gtk_widget_set_size_request() and gtk_label_set_width_chars(). The contents of the label. If the string contains [Pango XML markup][PangoMarkupFormat], you will have to set the #GtkLabel:use-markup property to %TRUE in order for the label to display the markup attributes. See also gtk_label_set_markup() for a convenience function that sets both this property and the #GtkLabel:use-markup property at the same time. If the string contains underlines acting as mnemonics, you will have to set the #GtkLabel:use-underline property to %TRUE in order for the label to display them. The number of lines to which an ellipsized, wrapping label should be limited. This property has no effect if the label is not wrapping or ellipsized. Set this property to -1 if you don't want to limit the number of lines. The desired maximum width of the label, in characters. If this property is set to -1, the width will be calculated automatically. See the section on [text layout][label-text-layout] for details of how #GtkLabel:width-chars and #GtkLabel:max-width-chars determine the width of ellipsized and wrapped labels. Whether the label is in single line mode. In single line mode, the height of the label does not depend on the actual text, it is always set to ascent + descent of the font. This can be an advantage in situations where resizing the label because of text changes would be distracting, e.g. in a statusbar. Set this property to %TRUE to make the label track which links have been visited. It will then apply the #GTK_STATE_FLAG_VISITED when rendering this link, in addition to #GTK_STATE_FLAG_LINK. The desired width of the label, in characters. If this property is set to -1, the width will be calculated automatically. See the section on [text layout][label-text-layout] for details of how #GtkLabel:width-chars and #GtkLabel:max-width-chars determine the width of ellipsized and wrapped labels. If line wrapping is on (see the #GtkLabel:wrap property) this controls how the line wrapping is done. The default is %PANGO_WRAP_WORD, which means wrap on word boundaries. The xalign property determines the horizontal aligment of the label text inside the labels size allocation. Compare this to #GtkWidget:halign, which determines how the labels size allocation is positioned in the space available for the label. The yalign property determines the vertical aligment of the label text inside the labels size allocation. Compare this to #GtkWidget:valign, which determines how the labels size allocation is positioned in the space available for the label. A [keybinding signal][GtkBindingSignal] which gets emitted when the user activates a link in the label. Applications may also emit the signal with g_signal_emit_by_name() if they need to control activation of URIs programmatically. The default bindings for this signal are all forms of the Enter key. The signal which gets emitted to activate a URI. Applications may connect to it to override the default behaviour, which is to call gtk_show_uri_on_window(). %TRUE if the link has been activated the URI that is activated The ::copy-clipboard signal is a [keybinding signal][GtkBindingSignal] which gets emitted to copy the selection to the clipboard. The default binding for this signal is Ctrl-c. The ::move-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a cursor movement. If the cursor is not visible in @entry, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifer does not. There are too many key combinations to list them all here. - Arrow keys move by individual characters/lines - Ctrl-arrow key combinations move by words/paragraphs - Home/End keys move to the ends of the buffer the granularity of the move, as a #GtkMovementStep the number of @step units to move %TRUE if the move should extend the selection The ::populate-popup signal gets emitted before showing the context menu of the label. Note that only selectable labels have context menus. If you need to add items to the context menu, connect to this signal and append your menuitems to the @menu. the menu that is being populated #GtkLayout is similar to #GtkDrawingArea in that it’s a “blank slate” and doesn’t do anything except paint a blank background by default. It’s different in that it supports scrolling natively due to implementing #GtkScrollable, and can contain child widgets since it’s a #GtkContainer. If you just want to draw, a #GtkDrawingArea is a better choice since it has lower overhead. If you just need to position child widgets at specific points, then #GtkFixed provides that functionality on its own. When handling expose events on a #GtkLayout, you must draw to the #GdkWindow returned by gtk_layout_get_bin_window(), rather than to the one returned by gtk_widget_get_window() as you would for a #GtkDrawingArea. Creates a new #GtkLayout. Unless you have a specific adjustment you’d like the layout to use for scrolling, pass %NULL for @hadjustment and @vadjustment. a new #GtkLayout horizontal scroll adjustment, or %NULL vertical scroll adjustment, or %NULL Retrieve the bin window of the layout used for drawing operations. a #GdkWindow a #GtkLayout This function should only be called after the layout has been placed in a #GtkScrolledWindow or otherwise configured for scrolling. It returns the #GtkAdjustment used for communication between the horizontal scrollbar and @layout. See #GtkScrolledWindow, #GtkScrollbar, #GtkAdjustment for details. Use gtk_scrollable_get_hadjustment() horizontal scroll adjustment a #GtkLayout Gets the size that has been set on the layout, and that determines the total extents of the layout’s scrollbar area. See gtk_layout_set_size (). a #GtkLayout location to store the width set on @layout, or %NULL location to store the height set on @layout, or %NULL This function should only be called after the layout has been placed in a #GtkScrolledWindow or otherwise configured for scrolling. It returns the #GtkAdjustment used for communication between the vertical scrollbar and @layout. See #GtkScrolledWindow, #GtkScrollbar, #GtkAdjustment for details. Use gtk_scrollable_get_vadjustment() vertical scroll adjustment a #GtkLayout Moves a current child of @layout to a new position. a #GtkLayout a current child of @layout X position to move to Y position to move to Adds @child_widget to @layout, at position (@x,@y). @layout becomes the new parent container of @child_widget. a #GtkLayout child widget X position of child widget Y position of child widget Sets the horizontal scroll adjustment for the layout. See #GtkScrolledWindow, #GtkScrollbar, #GtkAdjustment for details. Use gtk_scrollable_set_hadjustment() a #GtkLayout new scroll adjustment Sets the size of the scrollable area of the layout. a #GtkLayout width of entire scrollable area height of entire scrollable area Sets the vertical scroll adjustment for the layout. See #GtkScrolledWindow, #GtkScrollbar, #GtkAdjustment for details. Use gtk_scrollable_set_vadjustment() a #GtkLayout new scroll adjustment The #GtkLevelBar is a bar widget that can be used as a level indicator. Typical use cases are displaying the strength of a password, or showing the charge level of a battery. Use gtk_level_bar_set_value() to set the current value, and gtk_level_bar_add_offset_value() to set the value offsets at which the bar will be considered in a different state. GTK will add a few offsets by default on the level bar: #GTK_LEVEL_BAR_OFFSET_LOW, #GTK_LEVEL_BAR_OFFSET_HIGH and #GTK_LEVEL_BAR_OFFSET_FULL, with values 0.25, 0.75 and 1.0 respectively. Note that it is your responsibility to update preexisting offsets when changing the minimum or maximum value. GTK+ will simply clamp them to the new range. ## Adding a custom offset on the bar |[<!-- language="C" --> static GtkWidget * create_level_bar (void) { GtkWidget *widget; GtkLevelBar *bar; widget = gtk_level_bar_new (); bar = GTK_LEVEL_BAR (widget); // This changes the value of the default low offset gtk_level_bar_add_offset_value (bar, GTK_LEVEL_BAR_OFFSET_LOW, 0.10); // This adds a new offset to the bar; the application will // be able to change its color CSS like this: // // levelbar block.my-offset { // background-color: magenta; // border-style: solid; // border-color: black; // border-style: 1px; // } gtk_level_bar_add_offset_value (bar, "my-offset", 0.60); return widget; } ]| The default interval of values is between zero and one, but it’s possible to modify the interval using gtk_level_bar_set_min_value() and gtk_level_bar_set_max_value(). The value will be always drawn in proportion to the admissible interval, i.e. a value of 15 with a specified interval between 10 and 20 is equivalent to a value of 0.5 with an interval between 0 and 1. When #GTK_LEVEL_BAR_MODE_DISCRETE is used, the bar level is rendered as a finite number of separated blocks instead of a single one. The number of blocks that will be rendered is equal to the number of units specified by the admissible interval. For instance, to build a bar rendered with five blocks, it’s sufficient to set the minimum value to 0 and the maximum value to 5 after changing the indicator mode to discrete. GtkLevelBar was introduced in GTK+ 3.6. # GtkLevelBar as GtkBuildable The GtkLevelBar implementation of the GtkBuildable interface supports a custom `<offsets>` element, which can contain any number of `<offset>` elements, each of which must have "name" and "value" attributes. # CSS nodes |[<!-- language="plain" --> levelbar[.discrete] ╰── trough ├── block.filled.level-name ┊ ├── block.empty ┊ ]| GtkLevelBar has a main CSS node with name levelbar and one of the style classes .discrete or .continuous and a subnode with name trough. Below the trough node are a number of nodes with name block and style class .filled or .empty. In continuous mode, there is exactly one node of each, in discrete mode, the number of filled and unfilled nodes corresponds to blocks that are drawn. The block.filled nodes also get a style class .level-name corresponding to the level for the current value. In horizontal orientation, the nodes are always arranged from left to right, regardless of text direction. Creates a new #GtkLevelBar. a #GtkLevelBar. Utility constructor that creates a new #GtkLevelBar for the specified interval. a #GtkLevelBar a positive value a positive value Adds a new offset marker on @self at the position specified by @value. When the bar value is in the interval topped by @value (or between @value and #GtkLevelBar:max-value in case the offset is the last one on the bar) a style class named `level-`@name will be applied when rendering the level bar fill. If another offset marker named @name exists, its value will be replaced by @value. a #GtkLevelBar the name of the new offset the value for the new offset Return the value of the #GtkLevelBar:inverted property. %TRUE if the level bar is inverted a #GtkLevelBar Returns the value of the #GtkLevelBar:max-value property. a positive value a #GtkLevelBar Returns the value of the #GtkLevelBar:min-value property. a positive value a #GtkLevelBar Returns the value of the #GtkLevelBar:mode property. a #GtkLevelBarMode a #GtkLevelBar Fetches the value specified for the offset marker @name in @self, returning %TRUE in case an offset named @name was found. %TRUE if the specified offset is found a #GtkLevelBar the name of an offset in the bar location where to store the value Returns the value of the #GtkLevelBar:value property. a value in the interval between #GtkLevelBar:min-value and #GtkLevelBar:max-value a #GtkLevelBar Removes an offset marker previously added with gtk_level_bar_add_offset_value(). a #GtkLevelBar the name of an offset in the bar Sets the value of the #GtkLevelBar:inverted property. a #GtkLevelBar %TRUE to invert the level bar Sets the value of the #GtkLevelBar:max-value property. You probably want to update preexisting level offsets after calling this function. a #GtkLevelBar a positive value Sets the value of the #GtkLevelBar:min-value property. You probably want to update preexisting level offsets after calling this function. a #GtkLevelBar a positive value Sets the value of the #GtkLevelBar:mode property. a #GtkLevelBar a #GtkLevelBarMode Sets the value of the #GtkLevelBar:value property. a #GtkLevelBar a value in the interval between #GtkLevelBar:min-value and #GtkLevelBar:max-value Level bars normally grow from top to bottom or left to right. Inverted level bars grow in the opposite direction. The #GtkLevelBar:max-value property determaxes the maximum value of the interval that can be displayed by the bar. The #GtkLevelBar:min-value property determines the minimum value of the interval that can be displayed by the bar. The #GtkLevelBar:mode property determines the way #GtkLevelBar interprets the value properties to draw the level fill area. Specifically, when the value is #GTK_LEVEL_BAR_MODE_CONTINUOUS, #GtkLevelBar will draw a single block representing the current value in that area; when the value is #GTK_LEVEL_BAR_MODE_DISCRETE, the widget will draw a succession of separate blocks filling the draw area, with the number of blocks being equal to the units separating the integral roundings of #GtkLevelBar:min-value and #GtkLevelBar:max-value. The #GtkLevelBar:value property determines the currently filled value of the level bar. Emitted when an offset specified on the bar changes value as an effect to gtk_level_bar_add_offset_value() being called. The signal supports detailed connections; you can connect to the detailed signal "changed::x" in order to only receive callbacks when the value of offset "x" changes. the name of the offset that changed value Describes how #GtkLevelBar contents should be rendered. Note that this enumeration could be extended with additional modes in the future. the bar has a continuous mode the bar has a discrete mode The type of license for an application. This enumeration can be expanded at later date. No license specified A license text is going to be specified by the developer The GNU General Public License, version 2.0 or later The GNU General Public License, version 3.0 or later The GNU Lesser General Public License, version 2.1 or later The GNU Lesser General Public License, version 3.0 or later The BSD standard license The MIT/X11 standard license The Artistic License, version 2.0 The GNU General Public License, version 2.0 only. Since 3.12. The GNU General Public License, version 3.0 only. Since 3.12. The GNU Lesser General Public License, version 2.1 only. Since 3.12. The GNU Lesser General Public License, version 3.0 only. Since 3.12. The GNU Affero General Public License, version 3.0 or later. Since: 3.22. The GNU Affero General Public License, version 3.0 only. Since: 3.22.27. The 3-clause BSD licence. Since: 3.24.20. The Apache License, version 2.0. Since: 3.24.20. The Mozilla Public License, version 2.0. Since: 3.24.20. A GtkLinkButton is a #GtkButton with a hyperlink, similar to the one used by web browsers, which triggers an action when clicked. It is useful to show quick links to resources. A link button is created by calling either gtk_link_button_new() or gtk_link_button_new_with_label(). If using the former, the URI you pass to the constructor is used as a label for the widget. The URI bound to a GtkLinkButton can be set specifically using gtk_link_button_set_uri(), and retrieved using gtk_link_button_get_uri(). By default, GtkLinkButton calls gtk_show_uri_on_window() when the button is clicked. This behaviour can be overridden by connecting to the #GtkLinkButton::activate-link signal and returning %TRUE from the signal handler. # CSS nodes GtkLinkButton has a single CSS node with name button. To differentiate it from a plain #GtkButton, it gets the .link style class. Creates a new #GtkLinkButton with the URI as its text. a new link button widget. a valid URI Creates a new #GtkLinkButton containing a label. a new link button widget. a valid URI the text of the button class handler for the #GtkLinkButton::activate-link signal Retrieves the URI set using gtk_link_button_set_uri(). a valid URI. The returned string is owned by the link button and should not be modified or freed. a #GtkLinkButton Retrieves the “visited” state of the URI where the #GtkLinkButton points. The button becomes visited when it is clicked. If the URI is changed on the button, the “visited” state is unset again. The state may also be changed using gtk_link_button_set_visited(). %TRUE if the link has been visited, %FALSE otherwise a #GtkLinkButton Sets @uri as the URI where the #GtkLinkButton points. As a side-effect this unsets the “visited” state of the button. a #GtkLinkButton a valid URI Sets the “visited” state of the URI where the #GtkLinkButton points. See gtk_link_button_get_visited() for more details. a #GtkLinkButton the new “visited” state The URI bound to this button. The 'visited' state of this button. A visited link is drawn in a different color. The ::activate-link signal is emitted each time the #GtkLinkButton has been clicked. The default handler will call gtk_show_uri_on_window() with the URI stored inside the #GtkLinkButton:uri property. To override the default behavior, you can connect to the ::activate-link signal and stop the propagation of the signal by returning %TRUE from your handler. The #GtkLinkButtonClass contains only private data. class handler for the #GtkLinkButton::activate-link signal A GtkListBox is a vertical container that contains GtkListBoxRow children. These rows can be dynamically sorted and filtered, and headers can be added dynamically depending on the row content. It also allows keyboard and mouse navigation and selection like a typical list. Using GtkListBox is often an alternative to #GtkTreeView, especially when the list contents has a more complicated layout than what is allowed by a #GtkCellRenderer, or when the contents is interactive (i.e. has a button in it). Although a #GtkListBox must have only #GtkListBoxRow children you can add any kind of widget to it via gtk_container_add(), and a #GtkListBoxRow widget will automatically be inserted between the list and the widget. #GtkListBoxRows can be marked as activatable or selectable. If a row is activatable, #GtkListBox::row-activated will be emitted for it when the user tries to activate it. If it is selectable, the row will be marked as selected when the user tries to select it. The GtkListBox widget was added in GTK+ 3.10. # GtkListBox as GtkBuildable The GtkListBox implementation of the #GtkBuildable interface supports setting a child as the placeholder by specifying “placeholder” as the “type” attribute of a `<child>` element. See gtk_list_box_set_placeholder() for info. # CSS nodes |[<!-- language="plain" --> list ╰── row[.activatable] ]| GtkListBox uses a single CSS node named list. Each GtkListBoxRow uses a single CSS node named row. The row nodes get the .activatable style class added when appropriate. Creates a new #GtkListBox container. a new #GtkListBox Class handler for the #GtkListBox::activate-cursor-row signal Class handler for the #GtkListBox::move-cursor signal Class handler for the #GtkListBox::row-activated signal Class handler for the #GtkListBox::row-selected signal Select all children of @box, if the selection mode allows it. a #GtkListBox Class handler for the #GtkListBox::selected-rows-changed signal Class handler for the #GtkListBox::toggle-cursor-row signal Unselect all children of @box, if the selection mode allows it. a #GtkListBox Binds @model to @box. If @box was already bound to a model, that previous binding is destroyed. The contents of @box are cleared and then filled with widgets that represent items from @model. @box is updated whenever @model changes. If @model is %NULL, @box is left empty. It is undefined to add or remove widgets directly (for example, with gtk_list_box_insert() or gtk_container_add()) while @box is bound to a model. Note that using a model is incompatible with the filtering and sorting functionality in GtkListBox. When using a model, filtering and sorting should be implemented by the model. a #GtkListBox the #GListModel to be bound to @box a function that creates widgets for items or %NULL in case you also passed %NULL as @model user data passed to @create_widget_func function for freeing @user_data This is a helper function for implementing DnD onto a #GtkListBox. The passed in @row will be highlighted via gtk_drag_highlight(), and any previously highlighted row will be unhighlighted. The row will also be unhighlighted when the widget gets a drag leave event. a #GtkListBox a #GtkListBoxRow If a row has previously been highlighted via gtk_list_box_drag_highlight_row() it will have the highlight removed. a #GtkListBox Returns whether rows activate on single clicks. %TRUE if rows are activated on single click, %FALSE otherwise a #GtkListBox Gets the adjustment (if any) that the widget uses to for vertical scrolling. the adjustment a #GtkListBox Gets the n-th child in the list (not counting headers). If @_index is negative or larger than the number of items in the list, %NULL is returned. the child #GtkWidget or %NULL a #GtkListBox the index of the row Gets the row at the @y position. the row or %NULL in case no row exists for the given y coordinate. a #GtkListBox position Gets the selected row. Note that the box may allow multiple selection, in which case you should use gtk_list_box_selected_foreach() to find all selected rows. the selected row a #GtkListBox Creates a list of all selected children. A #GList containing the #GtkWidget for each selected child. Free with g_list_free() when done. a #GtkListBox Gets the selection mode of the listbox. a #GtkSelectionMode a #GtkListBox Insert the @child into the @box at @position. If a sort function is set, the widget will actually be inserted at the calculated position and this function has the same effect of gtk_container_add(). If @position is -1, or larger than the total number of items in the @box, then the @child will be appended to the end. a #GtkListBox the #GtkWidget to add the position to insert @child in Update the filtering for all rows. Call this when result of the filter function on the @box is changed due to an external factor. For instance, this would be used if the filter function just looked for a specific search string and the entry with the search string has changed. a #GtkListBox Update the separators for all rows. Call this when result of the header function on the @box is changed due to an external factor. a #GtkListBox Update the sorting for all rows. Call this when result of the sort function on the @box is changed due to an external factor. a #GtkListBox Prepend a widget to the list. If a sort function is set, the widget will actually be inserted at the calculated position and this function has the same effect of gtk_container_add(). a #GtkListBox the #GtkWidget to add Select all children of @box, if the selection mode allows it. a #GtkListBox Make @row the currently selected row. a #GtkListBox The row to select or %NULL Calls a function for each selected child. Note that the selection cannot be modified from within this function. a #GtkListBox the function to call for each selected child user data to pass to the function If @single is %TRUE, rows will be activated when you click on them, otherwise you need to double-click. a #GtkListBox a boolean Sets the adjustment (if any) that the widget uses to for vertical scrolling. For instance, this is used to get the page size for PageUp/Down key handling. In the normal case when the @box is packed inside a #GtkScrolledWindow the adjustment from that will be picked up automatically, so there is no need to manually do that. a #GtkListBox the adjustment, or %NULL By setting a filter function on the @box one can decide dynamically which of the rows to show. For instance, to implement a search function on a list that filters the original list to only show the matching rows. The @filter_func will be called for each row after the call, and it will continue to be called each time a row changes (via gtk_list_box_row_changed()) or when gtk_list_box_invalidate_filter() is called. Note that using a filter function is incompatible with using a model (see gtk_list_box_bind_model()). a #GtkListBox callback that lets you filter which rows to show user data passed to @filter_func destroy notifier for @user_data By setting a header function on the @box one can dynamically add headers in front of rows, depending on the contents of the row and its position in the list. For instance, one could use it to add headers in front of the first item of a new kind, in a list sorted by the kind. The @update_header can look at the current header widget using gtk_list_box_row_get_header() and either update the state of the widget as needed, or set a new one using gtk_list_box_row_set_header(). If no header is needed, set the header to %NULL. Note that you may get many calls @update_header to this for a particular row when e.g. changing things that don’t affect the header. In this case it is important for performance to not blindly replace an existing header with an identical one. The @update_header function will be called for each row after the call, and it will continue to be called each time a row changes (via gtk_list_box_row_changed()) and when the row before changes (either by gtk_list_box_row_changed() on the previous row, or when the previous row becomes a different row). It is also called for all rows when gtk_list_box_invalidate_headers() is called. a #GtkListBox callback that lets you add row headers user data passed to @update_header destroy notifier for @user_data Sets the placeholder widget that is shown in the list when it doesn't display any visible children. a #GtkListBox a #GtkWidget or %NULL Sets how selection works in the listbox. See #GtkSelectionMode for details. a #GtkListBox The #GtkSelectionMode By setting a sort function on the @box one can dynamically reorder the rows of the list, based on the contents of the rows. The @sort_func will be called for each row after the call, and will continue to be called each time a row changes (via gtk_list_box_row_changed()) and when gtk_list_box_invalidate_sort() is called. Note that using a sort function is incompatible with using a model (see gtk_list_box_bind_model()). a #GtkListBox the sort function user data passed to @sort_func destroy notifier for @user_data Unselect all children of @box, if the selection mode allows it. a #GtkListBox Unselects a single row of @box, if the selection mode allows it. a #GtkListBox the row to unselected The ::row-activated signal is emitted when a row has been activated by the user. the activated row The ::row-selected signal is emitted when a new row is selected, or (with a %NULL @row) when the selection is cleared. When the @box is using #GTK_SELECTION_MULTIPLE, this signal will not give you the full picture of selection changes, and you should use the #GtkListBox::selected-rows-changed signal instead. the selected row The ::select-all signal is a [keybinding signal][GtkBindingSignal] which gets emitted to select all children of the box, if the selection mode permits it. The default bindings for this signal is Ctrl-a. The ::selected-rows-changed signal is emitted when the set of selected rows changes. The ::unselect-all signal is a [keybinding signal][GtkBindingSignal] which gets emitted to unselect all children of the box, if the selection mode permits it. The default bindings for this signal is Ctrl-Shift-a. The parent class. Class handler for the #GtkListBox::row-selected signal Class handler for the #GtkListBox::row-activated signal Class handler for the #GtkListBox::activate-cursor-row signal Class handler for the #GtkListBox::toggle-cursor-row signal Class handler for the #GtkListBox::move-cursor signal Class handler for the #GtkListBox::selected-rows-changed signal Class handler for the #GtkListBox::select-all signal a #GtkListBox Class handler for the #GtkListBox::unselect-all signal a #GtkListBox Called for list boxes that are bound to a #GListModel with gtk_list_box_bind_model() for each item that gets added to the model. Versions of GTK+ prior to 3.18 called gtk_widget_show_all() on the rows created by the GtkListBoxCreateWidgetFunc, but this forced all widgets inside the row to be shown, and is no longer the case. Applications should be updated to show the desired row widgets. a #GtkWidget that represents @item the item from the model for which to create a widget for user data Will be called whenever the row changes or is added and lets you control if the row should be visible or not. %TRUE if the row should be visible, %FALSE otherwise the row that may be filtered user data A function used by gtk_list_box_selected_foreach(). It will be called on every selected child of the @box. a #GtkListBox a #GtkListBoxRow user data Creates a new #GtkListBoxRow, to be used as a child of a #GtkListBox. a new #GtkListBoxRow Marks @row as changed, causing any state that depends on this to be updated. This affects sorting, filtering and headers. Note that calls to this method must be in sync with the data used for the row functions. For instance, if the list is mirroring some external data set, and *two* rows changed in the external data set then when you call gtk_list_box_row_changed() on the first row the sort function must only read the new data for the first of the two changed rows, otherwise the resorting of the rows will be wrong. This generally means that if you don’t fully control the data model you have to duplicate the data that affects the listbox row functions into the row widgets themselves. Another alternative is to call gtk_list_box_invalidate_sort() on any model change, but that is more expensive. a #GtkListBoxRow Gets the value of the #GtkListBoxRow:activatable property for this row. %TRUE if the row is activatable a #GtkListBoxRow Returns the current header of the @row. This can be used in a #GtkListBoxUpdateHeaderFunc to see if there is a header set already, and if so to update the state of it. the current header, or %NULL if none a #GtkListBoxRow Gets the current index of the @row in its #GtkListBox container. the index of the @row, or -1 if the @row is not in a listbox a #GtkListBoxRow Gets the value of the #GtkListBoxRow:selectable property for this row. %TRUE if the row is selectable a #GtkListBoxRow Returns whether the child is currently selected in its #GtkListBox container. %TRUE if @row is selected a #GtkListBoxRow Set the #GtkListBoxRow:activatable property for this row. a #GtkListBoxRow %TRUE to mark the row as activatable Sets the current header of the @row. This is only allowed to be called from a #GtkListBoxUpdateHeaderFunc. It will replace any existing header in the row, and be shown in front of the row in the listbox. a #GtkListBoxRow the header, or %NULL Set the #GtkListBoxRow:selectable property for this row. a #GtkListBoxRow %TRUE to mark the row as selectable The property determines whether the #GtkListBox::row-activated signal will be emitted for this row. The property determines whether this row can be selected. This is a keybinding signal, which will cause this row to be activated. If you want to be notified when the user activates a row (by key or not), use the #GtkListBox::row-activated signal on the row’s parent #GtkListBox. The parent class. Compare two rows to determine which should be first. < 0 if @row1 should be before @row2, 0 if they are equal and > 0 otherwise the first row the second row user data Whenever @row changes or which row is before @row changes this is called, which lets you update the header on @row. You may remove or set a new one via gtk_list_box_row_set_header() or just change the state of the current header widget. the row to update the row before @row, or %NULL if it is first user data The #GtkListStore object is a list model for use with a #GtkTreeView widget. It implements the #GtkTreeModel interface, and consequentialy, can use all of the methods available there. It also implements the #GtkTreeSortable interface so it can be sorted by the view. Finally, it also implements the tree [drag and drop][gtk3-GtkTreeView-drag-and-drop] interfaces. The #GtkListStore can accept most GObject types as a column type, though it can’t accept all custom types. Internally, it will keep a copy of data passed in (such as a string or a boxed pointer). Columns that accept #GObjects are handled a little differently. The #GtkListStore will keep a reference to the object instead of copying the value. As a result, if the object is modified, it is up to the application writer to call gtk_tree_model_row_changed() to emit the #GtkTreeModel::row_changed signal. This most commonly affects lists with #GdkPixbufs stored. An example for creating a simple list store: |[<!-- language="C" --> enum { COLUMN_STRING, COLUMN_INT, COLUMN_BOOLEAN, N_COLUMNS }; { GtkListStore *list_store; GtkTreePath *path; GtkTreeIter iter; gint i; list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT, G_TYPE_BOOLEAN); for (i = 0; i < 10; i++) { gchar *some_data; some_data = get_some_data (i); // Add a new row to the model gtk_list_store_append (list_store, &iter); gtk_list_store_set (list_store, &iter, COLUMN_STRING, some_data, COLUMN_INT, i, COLUMN_BOOLEAN, FALSE, -1); // As the store will keep a copy of the string internally, // we free some_data. g_free (some_data); } // Modify a particular row path = gtk_tree_path_new_from_string ("4"); gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store), &iter, path); gtk_tree_path_free (path); gtk_list_store_set (list_store, &iter, COLUMN_BOOLEAN, TRUE, -1); } ]| # Performance Considerations Internally, the #GtkListStore was implemented with a linked list with a tail pointer prior to GTK+ 2.6. As a result, it was fast at data insertion and deletion, and not fast at random data access. The #GtkListStore sets the #GTK_TREE_MODEL_ITERS_PERSIST flag, which means that #GtkTreeIters can be cached while the row exists. Thus, if access to a particular row is needed often and your code is expected to run on older versions of GTK+, it is worth keeping the iter around. # Atomic Operations It is important to note that only the methods gtk_list_store_insert_with_values() and gtk_list_store_insert_with_valuesv() are atomic, in the sense that the row is being appended to the store and the values filled in in a single operation with regard to #GtkTreeModel signaling. In contrast, using e.g. gtk_list_store_append() and then gtk_list_store_set() will first create a row, which triggers the #GtkTreeModel::row-inserted signal on #GtkListStore. The row, however, is still empty, and any signal handler connecting to #GtkTreeModel::row-inserted on this particular store should be prepared for the situation that the row might be empty. This is especially important if you are wrapping the #GtkListStore inside a #GtkTreeModelFilter and are using a #GtkTreeModelFilterVisibleFunc. Using any of the non-atomic operations to append rows to the #GtkListStore will cause the #GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the function must be prepared for that. # GtkListStore as GtkBuildable The GtkListStore implementation of the GtkBuildable interface allows to specify the model columns with a `<columns>` element that may contain multiple `<column>` elements, each specifying one model column. The “type” attribute specifies the data type for the column. Additionally, it is possible to specify content for the list store in the UI definition, with the `<data>` element. It can contain multiple `<row>` elements, each specifying to content for one row of the list model. Inside a `<row>`, the `<col>` elements specify the content for individual cells. Note that it is probably more common to define your models in the code, and one might consider it a layering violation to specify the content of a list store in a UI definition, data, not presentation, and common wisdom is to separate the two, as far as possible. An example of a UI Definition fragment for a list store: |[<!-- language="xml" --> <object class="GtkListStore"> <columns> <column type="gchararray"/> <column type="gchararray"/> <column type="gint"/> </columns> <data> <row> <col id="0">John</col> <col id="1">Doe</col> <col id="2">25</col> </row> <row> <col id="0">Johan</col> <col id="1">Dahlin</col> <col id="2">50</col> </row> </data> </object> ]| Creates a new list store as with @n_columns columns each of the types passed in. Note that only types derived from standard GObject fundamental types are supported. As an example, `gtk_list_store_new (3, G_TYPE_INT, G_TYPE_STRING, GDK_TYPE_PIXBUF);` will create a new #GtkListStore with three columns, of type int, string and #GdkPixbuf respectively. a new #GtkListStore number of columns in the list store all #GType types for the columns, from first to last Non-vararg creation function. Used primarily by language bindings. a new #GtkListStore number of columns in the list store an array of #GType types for the columns, from first to last Appends a new row to @list_store. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). A #GtkListStore An unset #GtkTreeIter to set to the appended row Removes all rows from the list store. a #GtkListStore. Creates a new row at @position. @iter will be changed to point to this new row. If @position is -1 or is larger than the number of rows on the list, then the new row will be appended to the list. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). A #GtkListStore An unset #GtkTreeIter to set to the new row position to insert the new row, or -1 for last Inserts a new row after @sibling. If @sibling is %NULL, then the row will be prepended to the beginning of the list. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). A #GtkListStore An unset #GtkTreeIter to set to the new row A valid #GtkTreeIter, or %NULL Inserts a new row before @sibling. If @sibling is %NULL, then the row will be appended to the end of the list. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). A #GtkListStore An unset #GtkTreeIter to set to the new row A valid #GtkTreeIter, or %NULL Creates a new row at @position. @iter will be changed to point to this new row. If @position is -1, or larger than the number of rows in the list, then the new row will be appended to the list. The row will be filled with the values given to this function. Calling `gtk_list_store_insert_with_values (list_store, iter, position...)` has the same effect as calling |[<!-- language="C" --> static void insert_value (GtkListStore *list_store, GtkTreeIter *iter, int position) { gtk_list_store_insert (list_store, iter, position); gtk_list_store_set (list_store, iter // ... ); } ]| with the difference that the former will only emit a row_inserted signal, while the latter will emit row_inserted, row_changed and, if the list store is sorted, rows_reordered. Since emitting the rows_reordered signal repeatedly can affect the performance of the program, gtk_list_store_insert_with_values() should generally be preferred when inserting rows in a sorted list store. A #GtkListStore An unset #GtkTreeIter to set to the new row, or %NULL position to insert the new row, or -1 to append after existing rows pairs of column number and value, terminated with -1 A variant of gtk_list_store_insert_with_values() which takes the columns and values as two arrays, instead of varargs. This function is mainly intended for language-bindings. A #GtkListStore An unset #GtkTreeIter to set to the new row, or %NULL. position to insert the new row, or -1 for last an array of column numbers an array of GValues the length of the @columns and @values arrays > This function is slow. Only use it for debugging and/or testing > purposes. Checks if the given iter is a valid iter for this #GtkListStore. %TRUE if the iter is valid, %FALSE if the iter is invalid. A #GtkListStore. A #GtkTreeIter. Moves @iter in @store to the position after @position. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the start of the list. A #GtkListStore. A #GtkTreeIter. A #GtkTreeIter or %NULL. Moves @iter in @store to the position before @position. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the end of the list. A #GtkListStore. A #GtkTreeIter. A #GtkTreeIter, or %NULL. Prepends a new row to @list_store. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). A #GtkListStore An unset #GtkTreeIter to set to the prepend row Removes the given row from the list store. After being removed, @iter is set to be the next valid row, or invalidated if it pointed to the last row in @list_store. %TRUE if @iter is valid, %FALSE if not. A #GtkListStore A valid #GtkTreeIter Reorders @store to follow the order indicated by @new_order. Note that this function only works with unsorted stores. A #GtkListStore. an array of integers mapping the new position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos`. It must have exactly as many items as the list store’s length. Sets the value of one or more cells in the row referenced by @iter. The variable argument list should contain integer column numbers, each column number followed by the value to be set. The list is terminated by a -1. For example, to set column 0 with type %G_TYPE_STRING to “Foo”, you would write `gtk_list_store_set (store, iter, 0, "Foo", -1)`. The value will be referenced by the store if it is a %G_TYPE_OBJECT, and it will be copied if it is a %G_TYPE_STRING or %G_TYPE_BOXED. a #GtkListStore row iterator pairs of column number and value, terminated with -1 This function is meant primarily for #GObjects that inherit from #GtkListStore, and should only be used when constructing a new #GtkListStore. It will not function after a row has been added, or a method on the #GtkTreeModel interface is called. A #GtkListStore Number of columns for the list store An array length n of #GTypes See gtk_list_store_set(); this version takes a va_list for use by language bindings. A #GtkListStore A valid #GtkTreeIter for the row being modified va_list of column/value pairs Sets the data in the cell specified by @iter and @column. The type of @value must be convertible to the type of the column. A #GtkListStore A valid #GtkTreeIter for the row being modified column number to modify new value for the cell A variant of gtk_list_store_set_valist() which takes the columns and values as two arrays, instead of varargs. This function is mainly intended for language-bindings and in case the number of columns to change is not known until run-time. A #GtkListStore A valid #GtkTreeIter for the row being modified an array of column numbers an array of GValues the length of the @columns and @values arrays Swaps @a and @b in @store. Note that this function only works with unsorted stores. A #GtkListStore. A #GtkTreeIter. Another #GtkTreeIter. GtkLockButton is a widget that can be used in control panels or preference dialogs to allow users to obtain and revoke authorizations needed to operate the controls. The required authorization is represented by a #GPermission object. Concrete implementations of #GPermission may use PolicyKit or some other authorization framework. To obtain a PolicyKit-based #GPermission, use polkit_permission_new(). If the user is not currently allowed to perform the action, but can obtain the permission, the widget looks like this: ![](lockbutton-locked.png) and the user can click the button to request the permission. Depending on the platform, this may pop up an authentication dialog or ask the user to authenticate in some other way. Once the user has obtained the permission, the widget changes to this: ![](lockbutton-unlocked.png) and the permission can be dropped again by clicking the button. If the user is not able to obtain the permission at all, the widget looks like this: ![](lockbutton-sorry.png) If the user has the permission and cannot drop it, the button is hidden. The text (and tooltips) that are shown in the various cases can be adjusted with the #GtkLockButton:text-lock, #GtkLockButton:text-unlock, #GtkLockButton:tooltip-lock, #GtkLockButton:tooltip-unlock and #GtkLockButton:tooltip-not-authorized properties. Creates a new lock button which reflects the @permission. a new #GtkLockButton a #GPermission Obtains the #GPermission object that controls @button. the #GPermission of @button a #GtkLockButton Sets the #GPermission object that controls @button. a #GtkLockButton a #GPermission object, or %NULL The parent class. Like gtk_get_major_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. The maximum length of sequences in compose tables. Like gtk_get_micro_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. Like gtk_get_minor_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. A #GtkMenu is a #GtkMenuShell that implements a drop down menu consisting of a list of #GtkMenuItem objects which can be navigated and activated by the user to perform application functions. A #GtkMenu is most commonly dropped down by activating a #GtkMenuItem in a #GtkMenuBar or popped up by activating a #GtkMenuItem in another #GtkMenu. A #GtkMenu can also be popped up by activating a #GtkComboBox. Other composite widgets such as the #GtkNotebook can pop up a #GtkMenu as well. Applications can display a #GtkMenu as a popup menu by calling the gtk_menu_popup() function. The example below shows how an application can pop up a menu when the 3rd mouse button is pressed. ## Connecting the popup signal handler. |[<!-- language="C" --> // connect our handler which will popup the menu g_signal_connect_swapped (window, "button_press_event", G_CALLBACK (my_popup_handler), menu); ]| ## Signal handler which displays a popup menu. |[<!-- language="C" --> static gint my_popup_handler (GtkWidget *widget, GdkEvent *event) { GtkMenu *menu; GdkEventButton *event_button; g_return_val_if_fail (widget != NULL, FALSE); g_return_val_if_fail (GTK_IS_MENU (widget), FALSE); g_return_val_if_fail (event != NULL, FALSE); // The "widget" is the menu that was supplied when // g_signal_connect_swapped() was called. menu = GTK_MENU (widget); if (event->type == GDK_BUTTON_PRESS) { event_button = (GdkEventButton *) event; if (event_button->button == GDK_BUTTON_SECONDARY) { gtk_menu_popup (menu, NULL, NULL, NULL, NULL, event_button->button, event_button->time); return TRUE; } } return FALSE; } ]| # CSS nodes |[<!-- language="plain" --> menu ├── arrow.top ├── <child> ┊ ├── <child> ╰── arrow.bottom ]| The main CSS node of GtkMenu has name menu, and there are two subnodes with name arrow, for scrolling menu arrows. These subnodes get the .top and .bottom style classes. Creates a new #GtkMenu a new #GtkMenu Creates a #GtkMenu and populates it with menu items and submenus according to @model. The created menu items are connected to actions found in the #GtkApplicationWindow to which the menu belongs - typically by means of being attached to a widget (see gtk_menu_attach_to_widget()) that is contained within the #GtkApplicationWindows widget hierarchy. Actions can also be added using gtk_widget_insert_action_group() on the menu's attach widget or on any of its parent widgets. a new #GtkMenu a #GMenuModel Returns a list of the menus which are attached to this widget. This list is owned by GTK+ and must not be modified. the list of menus attached to his widget. a #GtkWidget Adds a new #GtkMenuItem to a (table) menu. The number of “cells” that an item will occupy is specified by @left_attach, @right_attach, @top_attach and @bottom_attach. These each represent the leftmost, rightmost, uppermost and lower column and row numbers of the table. (Columns and rows are indexed from zero). Note that this function is not related to gtk_menu_detach(). a #GtkMenu a #GtkMenuItem The column number to attach the left side of the item to The column number to attach the right side of the item to The row number to attach the top of the item to The row number to attach the bottom of the item to Attaches the menu to the widget and provides a callback function that will be invoked when the menu calls gtk_menu_detach() during its destruction. If the menu is attached to the widget then it will be destroyed when the widget is destroyed, as if it was a child widget. An attached menu will also move between screens correctly if the widgets moves between screens. a #GtkMenu the #GtkWidget that the menu will be attached to the user supplied callback function that will be called when the menu calls gtk_menu_detach() Detaches the menu from the widget to which it had been attached. This function will call the callback function, @detacher, provided when the gtk_menu_attach_to_widget() function was called. a #GtkMenu Gets the #GtkAccelGroup which holds global accelerators for the menu. See gtk_menu_set_accel_group(). the #GtkAccelGroup associated with the menu a #GtkMenu Retrieves the accelerator path set on the menu. the accelerator path set on the menu. a valid #GtkMenu Returns the selected menu item from the menu. This is used by the #GtkComboBox. the #GtkMenuItem that was last selected in the menu. If a selection has not yet been made, the first menu item is selected. a #GtkMenu Returns the #GtkWidget that the menu is attached to. the #GtkWidget that the menu is attached to a #GtkMenu Retrieves the number of the monitor on which to show the menu. the number of the monitor on which the menu should be popped up or -1, if no monitor has been set a #GtkMenu Returns whether the menu reserves space for toggles and icons, regardless of their actual presence. Whether the menu reserves toggle space a #GtkMenu Returns whether the menu is torn off. See gtk_menu_set_tearoff_state(). %TRUE if the menu is currently torn off. a #GtkMenu Returns the title of the menu. See gtk_menu_set_title(). the title of the menu, or %NULL if the menu has no title set on it. This string is owned by GTK+ and should not be modified or freed. a #GtkMenu Places @menu on the given monitor. a #GtkMenu the monitor to place the menu on Removes the menu from the screen. a #GtkMenu Displays a menu and makes it available for selection. Applications can use this function to display context-sensitive menus, and will typically supply %NULL for the @parent_menu_shell, @parent_menu_item, @func and @data parameters. The default menu positioning function will position the menu at the current mouse cursor position. The @button parameter should be the mouse button pressed to initiate the menu popup. If the menu popup was initiated by something other than a mouse button press, such as a mouse button release or a keypress, @button should be 0. The @activate_time parameter is used to conflict-resolve initiation of concurrent requests for mouse/keyboard grab requests. To function properly, this needs to be the timestamp of the user event (such as a mouse click or key press) that caused the initiation of the popup. Only if no such event is available, gtk_get_current_event_time() can be used instead. Note that this function does not work very well on GDK backends that do not have global coordinates, such as Wayland or Mir. You should probably use one of the gtk_menu_popup_at_ variants, which do not have this problem. Please use gtk_menu_popup_at_widget(), gtk_menu_popup_at_pointer(). or gtk_menu_popup_at_rect() instead a #GtkMenu the menu shell containing the triggering menu item, or %NULL the menu item whose activation triggered the popup, or %NULL a user supplied function used to position the menu, or %NULL user supplied data to be passed to @func. the mouse button which was pressed to initiate the event. the time at which the activation event occurred. Displays @menu and makes it available for selection. See gtk_menu_popup_at_widget () to pop up a menu at a widget. gtk_menu_popup_at_rect () also allows you to position a menu at an arbitrary rectangle. @menu will be positioned at the pointer associated with @trigger_event. Properties that influence the behaviour of this function are #GtkMenu:anchor-hints, #GtkMenu:rect-anchor-dx, #GtkMenu:rect-anchor-dy, and #GtkMenu:menu-type-hint. Connect to the #GtkMenu::popped-up signal to find out how it was actually positioned. the #GtkMenu to pop up the #GdkEvent that initiated this request or %NULL if it's the current event Displays @menu and makes it available for selection. See gtk_menu_popup_at_widget () and gtk_menu_popup_at_pointer (), which handle more common cases for popping up menus. @menu will be positioned at @rect, aligning their anchor points. @rect is relative to the top-left corner of @rect_window. @rect_anchor and @menu_anchor determine anchor points on @rect and @menu to pin together. @menu can optionally be offset by #GtkMenu:rect-anchor-dx and #GtkMenu:rect-anchor-dy. Anchors should be specified under the assumption that the text direction is left-to-right; they will be flipped horizontally automatically if the text direction is right-to-left. Other properties that influence the behaviour of this function are #GtkMenu:anchor-hints and #GtkMenu:menu-type-hint. Connect to the #GtkMenu::popped-up signal to find out how it was actually positioned. the #GtkMenu to pop up the #GdkWindow @rect is relative to the #GdkRectangle to align @menu with the point on @rect to align with @menu's anchor point the point on @menu to align with @rect's anchor point the #GdkEvent that initiated this request or %NULL if it's the current event Displays @menu and makes it available for selection. See gtk_menu_popup_at_pointer () to pop up a menu at the master pointer. gtk_menu_popup_at_rect () also allows you to position a menu at an arbitrary rectangle. ![](popup-anchors.png) @menu will be positioned at @widget, aligning their anchor points. @widget_anchor and @menu_anchor determine anchor points on @widget and @menu to pin together. @menu can optionally be offset by #GtkMenu:rect-anchor-dx and #GtkMenu:rect-anchor-dy. Anchors should be specified under the assumption that the text direction is left-to-right; they will be flipped horizontally automatically if the text direction is right-to-left. Other properties that influence the behaviour of this function are #GtkMenu:anchor-hints and #GtkMenu:menu-type-hint. Connect to the #GtkMenu::popped-up signal to find out how it was actually positioned. the #GtkMenu to pop up the #GtkWidget to align @menu with the point on @widget to align with @menu's anchor point the point on @menu to align with @widget's anchor point the #GdkEvent that initiated this request or %NULL if it's the current event Displays a menu and makes it available for selection. Applications can use this function to display context-sensitive menus, and will typically supply %NULL for the @parent_menu_shell, @parent_menu_item, @func, @data and @destroy parameters. The default menu positioning function will position the menu at the current position of @device (or its corresponding pointer). The @button parameter should be the mouse button pressed to initiate the menu popup. If the menu popup was initiated by something other than a mouse button press, such as a mouse button release or a keypress, @button should be 0. The @activate_time parameter is used to conflict-resolve initiation of concurrent requests for mouse/keyboard grab requests. To function properly, this needs to be the time stamp of the user event (such as a mouse click or key press) that caused the initiation of the popup. Only if no such event is available, gtk_get_current_event_time() can be used instead. Note that this function does not work very well on GDK backends that do not have global coordinates, such as Wayland or Mir. You should probably use one of the gtk_menu_popup_at_ variants, which do not have this problem. Please use gtk_menu_popup_at_widget(), gtk_menu_popup_at_pointer(). or gtk_menu_popup_at_rect() instead a #GtkMenu a #GdkDevice the menu shell containing the triggering menu item, or %NULL the menu item whose activation triggered the popup, or %NULL a user supplied function used to position the menu, or %NULL user supplied data to be passed to @func destroy notify for @data the mouse button which was pressed to initiate the event the time at which the activation event occurred Moves @child to a new @position in the list of @menu children. a #GtkMenu the #GtkMenuItem to move the new position to place @child. Positions are numbered from 0 to n - 1 Repositions the menu according to its position function. a #GtkMenu Set the #GtkAccelGroup which holds global accelerators for the menu. This accelerator group needs to also be added to all windows that this menu is being used in with gtk_window_add_accel_group(), in order for those windows to support all the accelerators contained in this group. a #GtkMenu the #GtkAccelGroup to be associated with the menu. Sets an accelerator path for this menu from which accelerator paths for its immediate children, its menu items, can be constructed. The main purpose of this function is to spare the programmer the inconvenience of having to call gtk_menu_item_set_accel_path() on each menu item that should support runtime user changable accelerators. Instead, by just calling gtk_menu_set_accel_path() on their parent, each menu item of this menu, that contains a label describing its purpose, automatically gets an accel path assigned. For example, a menu containing menu items “New” and “Exit”, will, after `gtk_menu_set_accel_path (menu, "<Gnumeric-Sheet>/File");` has been called, assign its items the accel paths: `"<Gnumeric-Sheet>/File/New"` and `"<Gnumeric-Sheet>/File/Exit"`. Assigning accel paths to menu items then enables the user to change their accelerators at runtime. More details about accelerator paths and their default setups can be found at gtk_accel_map_add_entry(). Note that @accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). a valid #GtkMenu a valid accelerator path, or %NULL to unset the path Selects the specified menu item within the menu. This is used by the #GtkComboBox and should not be used by anyone else. a #GtkMenu the index of the menu item to select. Index values are from 0 to n-1 Informs GTK+ on which monitor a menu should be popped up. See gdk_monitor_get_geometry(). This function should be called from a #GtkMenuPositionFunc if the menu should not appear on the same monitor as the pointer. This information can’t be reliably inferred from the coordinates returned by a #GtkMenuPositionFunc, since, for very long menus, these coordinates may extend beyond the monitor boundaries or even the screen boundaries. a #GtkMenu the number of the monitor on which the menu should be popped up Sets whether the menu should reserve space for drawing toggles or icons, regardless of their actual presence. a #GtkMenu whether to reserve size for toggles Sets the #GdkScreen on which the menu will be displayed. a #GtkMenu a #GdkScreen, or %NULL if the screen should be determined by the widget the menu is attached to Changes the tearoff state of the menu. A menu is normally displayed as drop down menu which persists as long as the menu is active. It can also be displayed as a tearoff menu which persists until it is closed or reattached. a #GtkMenu If %TRUE, menu is displayed as a tearoff menu. Sets the title string for the menu. The title is displayed when the menu is shown as a tearoff menu. If @title is %NULL, the menu will see if it is attached to a parent menu item, and if so it will try to use the same text as that menu item’s label. a #GtkMenu a string containing the title for the menu, or %NULL to inherit the title of the parent menu item, if any The accel group holding accelerators for the menu. An accel path used to conveniently construct accel paths of child items. The index of the currently selected menu item, or -1 if no menu item is selected. Positioning hints for aligning the menu relative to a rectangle. These hints determine how the menu should be positioned in the case that the menu would fall off-screen if placed in its ideal position. ![](popup-flip.png) For example, %GDK_ANCHOR_FLIP_Y will replace %GDK_GRAVITY_NORTH_WEST with %GDK_GRAVITY_SOUTH_WEST and vice versa if the menu extends beyond the bottom edge of the monitor. See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (), gtk_menu_popup_at_pointer (), #GtkMenu:rect-anchor-dx, #GtkMenu:rect-anchor-dy, #GtkMenu:menu-type-hint, and #GtkMenu::popped-up. The widget the menu is attached to. Setting this property attaches the menu without a #GtkMenuDetachFunc. If you need to use a detacher, use gtk_menu_attach_to_widget() directly. The #GdkWindowTypeHint to use for the menu's #GdkWindow. See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (), gtk_menu_popup_at_pointer (), #GtkMenu:anchor-hints, #GtkMenu:rect-anchor-dx, #GtkMenu:rect-anchor-dy, and #GtkMenu::popped-up. The monitor the menu will be popped up on. Horizontal offset to apply to the menu, i.e. the rectangle or widget anchor. See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (), gtk_menu_popup_at_pointer (), #GtkMenu:anchor-hints, #GtkMenu:rect-anchor-dy, #GtkMenu:menu-type-hint, and #GtkMenu::popped-up. Vertical offset to apply to the menu, i.e. the rectangle or widget anchor. See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (), gtk_menu_popup_at_pointer (), #GtkMenu:anchor-hints, #GtkMenu:rect-anchor-dx, #GtkMenu:menu-type-hint, and #GtkMenu::popped-up. A boolean that indicates whether the menu reserves space for toggles and icons, regardless of their actual presence. This property should only be changed from its default value for special-purposes such as tabular menus. Regular menus that are connected to a menu bar or context menus should reserve toggle space for consistency. A boolean that indicates whether the menu is torn-off. A title that may be displayed by the window manager when this menu is torn-off. a #GtkScrollType Emitted when the position of @menu is finalized after being popped up using gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (), or gtk_menu_popup_at_pointer (). @menu might be flipped over the anchor rectangle in order to keep it on-screen, in which case @flipped_x and @flipped_y will be set to %TRUE accordingly. @flipped_rect is the ideal position of @menu after any possible flipping, but before any possible sliding. @final_rect is @flipped_rect, but possibly translated in the case that flipping is still ineffective in keeping @menu on-screen. ![](popup-slide.png) The blue menu is @menu's ideal position, the green menu is @flipped_rect, and the red menu is @final_rect. See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (), gtk_menu_popup_at_pointer (), #GtkMenu:anchor-hints, #GtkMenu:rect-anchor-dx, #GtkMenu:rect-anchor-dy, and #GtkMenu:menu-type-hint. the position of @menu after any possible flipping or %NULL if the backend can't obtain it the final position of @menu or %NULL if the backend can't obtain it %TRUE if the anchors were flipped horizontally %TRUE if the anchors were flipped vertically The #GtkMenuBar is a subclass of #GtkMenuShell which contains one or more #GtkMenuItems. The result is a standard menu bar which can hold many menu items. # CSS nodes GtkMenuBar has a single CSS node with name menubar. Creates a new #GtkMenuBar the new menu bar, as a #GtkWidget Creates a new #GtkMenuBar and populates it with menu items and submenus according to @model. The created menu items are connected to actions found in the #GtkApplicationWindow to which the menu bar belongs - typically by means of being contained within the #GtkApplicationWindows widget hierarchy. a new #GtkMenuBar a #GMenuModel Retrieves the current child pack direction of the menubar. See gtk_menu_bar_set_child_pack_direction(). the child pack direction a #GtkMenuBar Retrieves the current pack direction of the menubar. See gtk_menu_bar_set_pack_direction(). the pack direction a #GtkMenuBar Sets how widgets should be packed inside the children of a menubar. a #GtkMenuBar a new #GtkPackDirection Sets how items should be packed inside a menubar. a #GtkMenuBar a new #GtkPackDirection The child pack direction of the menubar. It determines how the widgets contained in child menuitems are arranged. The pack direction of the menubar. It determines how menuitems are arranged in the menubar. The #GtkMenuButton widget is used to display a popup when clicked on. This popup can be provided either as a #GtkMenu, a #GtkPopover or an abstract #GMenuModel. The #GtkMenuButton widget can hold any valid child widget. That is, it can hold almost any other standard #GtkWidget. The most commonly used child is #GtkImage. If no widget is explicitely added to the #GtkMenuButton, a #GtkImage is automatically created, using an arrow image oriented according to #GtkMenuButton:direction or the generic “open-menu-symbolic” icon if the direction is not set. The positioning of the popup is determined by the #GtkMenuButton:direction property of the menu button. For menus, the #GtkWidget:halign and #GtkWidget:valign properties of the menu are also taken into account. For example, when the direction is %GTK_ARROW_DOWN and the horizontal alignment is %GTK_ALIGN_START, the menu will be positioned below the button, with the starting edge (depending on the text direction) of the menu aligned with the starting edge of the button. If there is not enough space below the button, the menu is popped up above the button instead. If the alignment would move part of the menu offscreen, it is “pushed in”. ## Direction = Down - halign = start ![](down-start.png) - halign = center ![](down-center.png) - halign = end ![](down-end.png) ## Direction = Up - halign = start ![](up-start.png) - halign = center ![](up-center.png) - halign = end ![](up-end.png) ## Direction = Left - valign = start ![](left-start.png) - valign = center ![](left-center.png) - valign = end ![](left-end.png) ## Direction = Right - valign = start ![](right-start.png) - valign = center ![](right-center.png) - valign = end ![](right-end.png) # CSS nodes GtkMenuButton has a single CSS node with name button. To differentiate it from a plain #GtkButton, it gets the .popup style class. Creates a new #GtkMenuButton widget with downwards-pointing arrow as the only child. You can replace the child widget with another #GtkWidget should you wish to. The newly created #GtkMenuButton widget Returns the parent #GtkWidget to use to line up with menu. a #GtkWidget value or %NULL a #GtkMenuButton Returns the direction the popup will be pointing at when popped up. a #GtkArrowType value a #GtkMenuButton Returns the #GMenuModel used to generate the popup. a #GMenuModel or %NULL a #GtkMenuButton Returns the #GtkPopover that pops out of the button. If the button is not using a #GtkPopover, this function returns %NULL. a #GtkPopover or %NULL a #GtkMenuButton Returns the #GtkMenu that pops out of the button. If the button does not use a #GtkMenu, this function returns %NULL. a #GtkMenu or %NULL a #GtkMenuButton Returns whether a #GtkPopover or a #GtkMenu will be constructed from the menu model. %TRUE if using a #GtkPopover a #GtkMenuButton Sets the #GtkWidget to use to line the menu with when popped up. Note that the @align_widget must contain the #GtkMenuButton itself. Setting it to %NULL means that the menu will be aligned with the button itself. Note that this property is only used with menus currently, and not for popovers. a #GtkMenuButton a #GtkWidget Sets the direction in which the popup will be popped up, as well as changing the arrow’s direction. The child will not be changed to an arrow if it was customized. If the does not fit in the available space in the given direction, GTK+ will its best to keep it inside the screen and fully visible. If you pass %GTK_ARROW_NONE for a @direction, the popup will behave as if you passed %GTK_ARROW_DOWN (although you won’t see any arrows). a #GtkMenuButton a #GtkArrowType Sets the #GMenuModel from which the popup will be constructed, or %NULL to dissociate any existing menu model and disable the button. Depending on the value of #GtkMenuButton:use-popover, either a #GtkMenu will be created with gtk_menu_new_from_model(), or a #GtkPopover with gtk_popover_new_from_model(). In either case, actions will be connected as documented for these functions. If #GtkMenuButton:popup or #GtkMenuButton:popover are already set, those widgets are dissociated from the @menu_button, and those properties are set to %NULL. a #GtkMenuButton a #GMenuModel, or %NULL to unset and disable the button Sets the #GtkPopover that will be popped up when the @menu_button is clicked, or %NULL to dissociate any existing popover and disable the button. If #GtkMenuButton:menu-model or #GtkMenuButton:popup are set, those objects are dissociated from the @menu_button, and those properties are set to %NULL. a #GtkMenuButton a #GtkPopover, or %NULL to unset and disable the button Sets the #GtkMenu that will be popped up when the @menu_button is clicked, or %NULL to dissociate any existing menu and disable the button. If #GtkMenuButton:menu-model or #GtkMenuButton:popover are set, those objects are dissociated from the @menu_button, and those properties are set to %NULL. a #GtkMenuButton a #GtkMenu, or %NULL to unset and disable the button Sets whether to construct a #GtkPopover instead of #GtkMenu when gtk_menu_button_set_menu_model() is called. Note that this property is only consulted when a new menu model is set. a #GtkMenuButton %TRUE to construct a popover from the menu model The #GtkWidget to use to align the menu with. The #GtkArrowType representing the direction in which the menu or popover will be popped out. The #GMenuModel from which the popup will be created. Depending on the #GtkMenuButton:use-popover property, that may be a menu or a popover. See gtk_menu_button_set_menu_model() for the interaction with the #GtkMenuButton:popup property. The #GtkPopover that will be popped up when the button is clicked. The #GtkMenu that will be popped up when the button is clicked. Whether to construct a #GtkPopover from the menu model, or a #GtkMenu. A user function supplied when calling gtk_menu_attach_to_widget() which will be called when the menu is later detached from the widget. the #GtkWidget that the menu is being detached from. the #GtkMenu being detached. An enumeration representing directional movements within a menu. To the parent menu shell To the submenu, if any, associated with the item To the next menu item To the previous menu item The #GtkMenuItem widget and the derived widgets are the only valid children for menus. Their function is to correctly handle highlighting, alignment, events and submenus. As a GtkMenuItem derives from #GtkBin it can hold any valid child widget, although only a few are really useful. By default, a GtkMenuItem sets a #GtkAccelLabel as its child. GtkMenuItem has direct functions to set the label and its mnemonic. For more advanced label settings, you can fetch the child widget from the GtkBin. An example for setting markup and accelerator on a MenuItem: |[<!-- language="C" --> GtkWidget *menu_item = gtk_menu_item_new_with_label ("Example Menu Item"); GtkWidget *child = gtk_bin_get_child (GTK_BIN (menu_item)); gtk_label_set_markup (GTK_LABEL (child), "<i>new label</i> with <b>markup</b>"); gtk_accel_label_set_accel (GTK_ACCEL_LABEL (child), GDK_KEY_1, 0); ]| # GtkMenuItem as GtkBuildable The GtkMenuItem implementation of the #GtkBuildable interface supports adding a submenu by specifying “submenu” as the “type” attribute of a `<child>` element. An example of UI definition fragment with submenus: |[<!-- language="xml" --> <object class="GtkMenuItem"> <child type="submenu"> <object class="GtkMenu"/> </child> </object> ]| # CSS nodes |[<!-- language="plain" --> menuitem ├── <child> ╰── [arrow.right] ]| GtkMenuItem has a single CSS node with name menuitem. If the menuitem has a submenu, it gets another CSS node with name arrow, which has the .left or .right style class. Creates a new #GtkMenuItem. the newly created #GtkMenuItem Creates a new #GtkMenuItem whose child is a #GtkLabel. the newly created #GtkMenuItem the text for the label Creates a new #GtkMenuItem containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the menu item. a new #GtkMenuItem The text of the button, with an underscore in front of the mnemonic character Emits the #GtkMenuItem::activate signal on the given item the menu item Signal emitted when the item is activated, but also if the menu item has a submenu. Emits the #GtkMenuItem::deselect signal on the given item. the menu item Sets @text on the @menu_item label The text in the @menu_item label. This is the internal string used by the label, and must not be modified. a #GtkMenuItem Emits the #GtkMenuItem::select signal on the given item. the menu item Sets @text on the @menu_item label a #GtkMenuItem the text you want to set Emits the #GtkMenuItem::toggle-size-allocate signal on the given item. the menu item. the allocation to use as signal data. Emits the #GtkMenuItem::toggle-size-request signal on the given item. the menu item the requisition to use as signal data. Emits the #GtkMenuItem::activate signal on the given item the menu item Emits the #GtkMenuItem::deselect signal on the given item. the menu item Retrieve the accelerator path that was previously set on @menu_item. See gtk_menu_item_set_accel_path() for details. the accelerator path corresponding to this menu item’s functionality, or %NULL if not set a valid #GtkMenuItem Sets @text on the @menu_item label The text in the @menu_item label. This is the internal string used by the label, and must not be modified. a #GtkMenuItem Returns whether the @menu_item reserves space for the submenu indicator, regardless if it has a submenu or not. %TRUE if @menu_item always reserves space for the submenu indicator a #GtkMenuItem Gets whether the menu item appears justified at the right side of the menu bar. See gtk_menu_item_set_right_justified() %TRUE if the menu item will appear at the far right if added to a menu bar. a #GtkMenuItem Gets the submenu underneath this menu item, if any. See gtk_menu_item_set_submenu(). submenu for this menu item, or %NULL if none a #GtkMenuItem Checks if an underline in the text indicates the next character should be used for the mnemonic accelerator key. %TRUE if an embedded underline in the label indicates the mnemonic accelerator key. a #GtkMenuItem Emits the #GtkMenuItem::select signal on the given item. the menu item Set the accelerator path on @menu_item, through which runtime changes of the menu item’s accelerator caused by the user can be identified and saved to persistent storage (see gtk_accel_map_save() on this). To set up a default accelerator for this menu item, call gtk_accel_map_add_entry() with the same @accel_path. See also gtk_accel_map_add_entry() on the specifics of accelerator paths, and gtk_menu_set_accel_path() for a more convenient variant of this function. This function is basically a convenience wrapper that handles calling gtk_widget_set_accel_path() with the appropriate accelerator group for the menu item. Note that you do need to set an accelerator on the parent menu with gtk_menu_set_accel_group() for this to work. Note that @accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). a valid #GtkMenuItem accelerator path, corresponding to this menu item’s functionality, or %NULL to unset the current path. Sets @text on the @menu_item label a #GtkMenuItem the text you want to set Sets whether the @menu_item should reserve space for the submenu indicator, regardless if it actually has a submenu or not. There should be little need for applications to call this functions. a #GtkMenuItem the new value Sets whether the menu item appears justified at the right side of a menu bar. This was traditionally done for “Help” menu items, but is now considered a bad idea. (If the widget layout is reversed for a right-to-left language like Hebrew or Arabic, right-justified-menu-items appear at the left.) If you insist on using it, use gtk_widget_set_hexpand() and gtk_widget_set_halign(). a #GtkMenuItem. if %TRUE the menu item will appear at the far right if added to a menu bar Sets or replaces the menu item’s submenu, or removes it when a %NULL submenu is passed. a #GtkMenuItem the submenu, or %NULL If true, an underline in the text indicates the next character should be used for the mnemonic accelerator key. a #GtkMenuItem %TRUE if underlines in the text indicate mnemonics Emits the #GtkMenuItem::toggle-size-allocate signal on the given item. the menu item. the allocation to use as signal data. Emits the #GtkMenuItem::toggle-size-request signal on the given item. the menu item the requisition to use as signal data. Sets the accelerator path of the menu item, through which runtime changes of the menu item's accelerator caused by the user can be identified and saved to persistant storage. The text for the child label. Sets whether the menu item appears justified at the right side of a menu bar. The submenu attached to the menu item, or %NULL if it has none. %TRUE if underlines in the text indicate mnemonics. Emitted when the item is activated. Emitted when the item is activated, but also if the menu item has a submenu. For normal applications, the relevant signal is #GtkMenuItem::activate. The parent class. If %TRUE, then we should always hide the menu when the %GtkMenuItem is activated. Otherwise, it is up to the caller. Signal emitted when the item is activated. the menu item Signal emitted when the item is activated, but also if the menu item has a submenu. the menu item the requisition to use as signal data. the menu item. the allocation to use as signal data. Sets @text on the #GtkMenuItem label a #GtkMenuItem the text you want to set Gets @text from the #GtkMenuItem label The text in the @menu_item label. This is the internal string used by the label, and must not be modified. a #GtkMenuItem Signal emitted when the item is selected. the menu item Signal emitted when the item is deselected. the menu item A user function supplied when calling gtk_menu_popup() which controls the positioning of the menu when it is displayed. The function sets the @x and @y parameters to the coordinates where the menu is to be drawn. To make the menu appear on a different monitor than the mouse pointer, gtk_menu_set_monitor() must be called. a #GtkMenu. address of the #gint representing the horizontal position where the menu shall be drawn. address of the #gint representing the vertical position where the menu shall be drawn. This is an output parameter. This parameter controls how menus placed outside the monitor are handled. If this is set to %TRUE and part of the menu is outside the monitor then GTK+ pushes the window into the visible area, effectively modifying the popup position. Note that moving and possibly resizing the menu around will alter the scroll position to keep the menu items “in place”, i.e. at the same monitor position they would have been without resizing. In practice, this behavior is only useful for combobox popups or option menus and cannot be used to simply confine a menu to monitor boundaries. In that case, changing the scroll offset is not desirable. the data supplied by the user in the gtk_menu_popup() @data parameter. A #GtkMenuShell is the abstract base class used to derive the #GtkMenu and #GtkMenuBar subclasses. A #GtkMenuShell is a container of #GtkMenuItem objects arranged in a list which can be navigated, selected, and activated by the user to perform application functions. A #GtkMenuItem can have a submenu associated with it, allowing for nested hierarchical menus. # Terminology A menu item can be “selected”, this means that it is displayed in the prelight state, and if it has a submenu, that submenu will be popped up. A menu is “active” when it is visible onscreen and the user is selecting from it. A menubar is not active until the user clicks on one of its menuitems. When a menu is active, passing the mouse over a submenu will pop it up. There is also is a concept of the current menu and a current menu item. The current menu item is the selected menu item that is furthest down in the hierarchy. (Every active menu shell does not necessarily contain a selected menu item, but if it does, then the parent menu shell must also contain a selected menu item.) The current menu is the menu that contains the current menu item. It will always have a GTK grab and receive all key presses. Cancels the selection within the menu shell. a #GtkMenuShell Deactivates the menu shell. Typically this results in the menu shell being erased from the screen. a #GtkMenuShell Adds a new #GtkMenuItem to the menu shell’s item list at the position indicated by @position. a #GtkMenuShell The #GtkMenuItem to add The position in the item list where @child is added. Positions are numbered from 0 to n-1 Selects the menu item from the menu shell. a #GtkMenuShell The #GtkMenuItem to select Activates the menu item within the menu shell. a #GtkMenuShell the #GtkMenuItem to activate if %TRUE, force the deactivation of the menu shell after the menu item is activated Adds a new #GtkMenuItem to the end of the menu shell's item list. a #GtkMenuShell The #GtkMenuItem to add Establishes a binding between a #GtkMenuShell and a #GMenuModel. The contents of @shell are removed and then refilled with menu items according to @model. When @model changes, @shell is updated. Calling this function twice on @shell with different @model will cause the first binding to be replaced with a binding to the new model. If @model is %NULL then any previous binding is undone and all children are removed. @with_separators determines if toplevel items (eg: sections) have separators inserted between them. This is typically desired for menus but doesn’t make sense for menubars. If @action_namespace is non-%NULL then the effect is as if all actions mentioned in the @model have their names prefixed with the namespace, plus a dot. For example, if the action “quit” is mentioned and @action_namespace is “app” then the effective action name is “app.quit”. This function uses #GtkActionable to define the action name and target values on the created menu items. If you want to use an action group other than “app” and “win”, or if you want to use a #GtkMenuShell outside of a #GtkApplicationWindow, then you will need to attach your own action group to the widget hierarchy using gtk_widget_insert_action_group(). As an example, if you created a group with a “quit” action and inserted it with the name “mygroup” then you would use the action name “mygroup.quit” in your #GMenuModel. For most cases you are probably better off using gtk_menu_new_from_model() or gtk_menu_bar_new_from_model() or just directly passing the #GMenuModel to gtk_application_set_app_menu() or gtk_application_set_menubar(). a #GtkMenuShell the #GMenuModel to bind to or %NULL to remove binding the namespace for actions in @model %TRUE if toplevel items in @shell should have separators between them Cancels the selection within the menu shell. a #GtkMenuShell Deactivates the menu shell. Typically this results in the menu shell being erased from the screen. a #GtkMenuShell Deselects the currently selected item from the menu shell, if any. a #GtkMenuShell Gets the parent menu shell. The parent menu shell of a submenu is the #GtkMenu or #GtkMenuBar from which it was opened up. the parent #GtkMenuShell a #GtkMenuShell Gets the currently selected item. the currently selected item a #GtkMenuShell Returns %TRUE if the menu shell will take the keyboard focus on popup. %TRUE if the menu shell will take the keyboard focus on popup. a #GtkMenuShell Adds a new #GtkMenuItem to the menu shell’s item list at the position indicated by @position. a #GtkMenuShell The #GtkMenuItem to add The position in the item list where @child is added. Positions are numbered from 0 to n-1 Adds a new #GtkMenuItem to the beginning of the menu shell's item list. a #GtkMenuShell The #GtkMenuItem to add Select the first visible or selectable child of the menu shell; don’t select tearoff items unless the only item is a tearoff item. a #GtkMenuShell if %TRUE, search for the first selectable menu item, otherwise select nothing if the first item isn’t sensitive. This should be %FALSE if the menu is being popped up initially. Selects the menu item from the menu shell. a #GtkMenuShell The #GtkMenuItem to select If @take_focus is %TRUE (the default) the menu shell will take the keyboard focus so that it will receive all keyboard events which is needed to enable keyboard navigation in menus. Setting @take_focus to %FALSE is useful only for special applications like virtual keyboard implementations which should not take keyboard focus. The @take_focus state of a menu or menu bar is automatically propagated to submenus whenever a submenu is popped up, so you don’t have to worry about recursively setting it for your entire menu hierarchy. Only when programmatically picking a submenu and popping it up manually, the @take_focus property of the submenu needs to be set explicitly. Note that setting it to %FALSE has side-effects: If the focus is in some other app, it keeps the focus and keynav in the menu doesn’t work. Consequently, keynav on the menu will only work if the focus is on some toplevel owned by the onscreen keyboard. To avoid confusing the user, menus with @take_focus set to %FALSE should not display mnemonics or accelerators, since it cannot be guaranteed that they will work. See also gdk_keyboard_grab() a #GtkMenuShell %TRUE if the menu shell should take the keyboard focus on popup A boolean that determines whether the menu and its submenus grab the keyboard focus. See gtk_menu_shell_set_take_focus() and gtk_menu_shell_get_take_focus(). An action signal that activates the current menu item within the menu shell. if %TRUE, hide the menu after activating the menu item An action signal which cancels the selection within the menu shell. Causes the #GtkMenuShell::selection-done signal to be emitted. A keybinding signal which moves the focus in the given @direction. the direction to cycle in This signal is emitted when a menu shell is deactivated. The ::insert signal is emitted when a new #GtkMenuItem is added to a #GtkMenuShell. A separate signal is used instead of GtkContainer::add because of the need for an additional position parameter. The inverse of this signal is the GtkContainer::removed signal. the #GtkMenuItem that is being inserted the position at which the insert occurs An keybinding signal which moves the current menu item in the direction specified by @direction. the direction to move The ::move-selected signal is emitted to move the selection to another item. %TRUE to stop the signal emission, %FALSE to continue +1 to move to the next item, -1 to move to the previous This signal is emitted when a selection has been completed within a menu shell. a #GtkMenuShell a #GtkMenuShell a #GtkMenuShell The #GtkMenuItem to select a #GtkMenuShell The #GtkMenuItem to add The position in the item list where @child is added. Positions are numbered from 0 to n-1 A #GtkMenuToolButton is a #GtkToolItem that contains a button and a small additional button with an arrow. When clicked, the arrow button pops up a dropdown menu. Use gtk_menu_tool_button_new() to create a new #GtkMenuToolButton. # GtkMenuToolButton as GtkBuildable The GtkMenuToolButton implementation of the GtkBuildable interface supports adding a menu by specifying “menu” as the “type” attribute of a `<child>` element. An example for a UI definition fragment with menus: |[<!-- language="xml" --> <object class="GtkMenuToolButton"> <child type="menu"> <object class="GtkMenu"/> </child> </object> ]| Creates a new #GtkMenuToolButton using @icon_widget as icon and @label as label. the new #GtkMenuToolButton a widget that will be used as icon widget, or %NULL a string that will be used as label, or %NULL Creates a new #GtkMenuToolButton. The new #GtkMenuToolButton will contain an icon and label from the stock item indicated by @stock_id. Use gtk_menu_tool_button_new() instead. the new #GtkMenuToolButton the name of a stock item Signal emitted before the menu is shown. Gets the #GtkMenu associated with #GtkMenuToolButton. the #GtkMenu associated with #GtkMenuToolButton a #GtkMenuToolButton Sets the tooltip markup text to be used as tooltip for the arrow button which pops up the menu. See gtk_tool_item_set_tooltip_text() for setting a tooltip on the whole #GtkMenuToolButton. a #GtkMenuToolButton markup text to be used as tooltip text for button’s arrow button Sets the tooltip text to be used as tooltip for the arrow button which pops up the menu. See gtk_tool_item_set_tooltip_text() for setting a tooltip on the whole #GtkMenuToolButton. a #GtkMenuToolButton text to be used as tooltip text for button’s arrow button Sets the #GtkMenu that is popped up when the user clicks on the arrow. If @menu is NULL, the arrow button becomes insensitive. a #GtkMenuToolButton the #GtkMenu associated with #GtkMenuToolButton The ::show-menu signal is emitted before the menu is shown. It can be used to populate the menu on demand, using gtk_menu_tool_button_set_menu(). Note that even if you populate the menu dynamically in this way, you must set an empty menu on the #GtkMenuToolButton beforehand, since the arrow is made insensitive if the menu is not set. The parent class. Signal emitted before the menu is shown. #GtkMessageDialog presents a dialog with some message text. It’s simply a convenience widget; you could construct the equivalent of #GtkMessageDialog from #GtkDialog without too much effort, but #GtkMessageDialog saves typing. One difference from #GtkDialog is that #GtkMessageDialog sets the #GtkWindow:skip-taskbar-hint property to %TRUE, so that the dialog is hidden from the taskbar by default. The easiest way to do a modal message dialog is to use gtk_dialog_run(), though you can also pass in the %GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically makes the dialog modal and waits for the user to respond to it. gtk_dialog_run() returns when any dialog button is clicked. An example for using a modal dialog: |[<!-- language="C" --> GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_message_dialog_new (parent_window, flags, GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, "Error reading “%s”: %s", filename, g_strerror (errno)); gtk_dialog_run (GTK_DIALOG (dialog)); gtk_widget_destroy (dialog); ]| You might do a non-modal #GtkMessageDialog as follows: An example for a non-modal dialog: |[<!-- language="C" --> GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_message_dialog_new (parent_window, flags, GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, "Error reading “%s”: %s", filename, g_strerror (errno)); // Destroy the dialog when the user responds to it // (e.g. clicks a button) g_signal_connect_swapped (dialog, "response", G_CALLBACK (gtk_widget_destroy), dialog); ]| # GtkMessageDialog as GtkBuildable The GtkMessageDialog implementation of the GtkBuildable interface exposes the message area as an internal child with the name “message_area”. Creates a new message dialog, which is a simple dialog with some text the user may want to see. When the user clicks a button a “response” signal is emitted with response IDs from #GtkResponseType. See #GtkDialog for more details. a new #GtkMessageDialog transient parent, or %NULL for none flags type of message set of buttons to use printf()-style format string, or %NULL arguments for @message_format Creates a new message dialog, which is a simple dialog with some text that is marked up with the [Pango text markup language][PangoMarkupFormat]. When the user clicks a button a “response” signal is emitted with response IDs from #GtkResponseType. See #GtkDialog for more details. Special XML characters in the printf() arguments passed to this function will automatically be escaped as necessary. (See g_markup_printf_escaped() for how this is implemented.) Usually this is what you want, but if you have an existing Pango markup string that you want to use literally as the label, then you need to use gtk_message_dialog_set_markup() instead, since you can’t pass the markup string either as the format (it might contain “%” characters) or as a string argument. |[<!-- language="C" --> GtkWidget *dialog; GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_message_dialog_new (parent_window, flags, GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, NULL); gtk_message_dialog_set_markup (GTK_MESSAGE_DIALOG (dialog), markup); ]| a new #GtkMessageDialog transient parent, or %NULL for none flags type of message set of buttons to use printf()-style format string, or %NULL arguments for @message_format Sets the secondary text of the message dialog to be @message_format (with printf()-style), which is marked up with the [Pango text markup language][PangoMarkupFormat]. Due to an oversight, this function does not escape special XML characters like gtk_message_dialog_new_with_markup() does. Thus, if the arguments may contain special XML characters, you should use g_markup_printf_escaped() to escape it. |[<!-- language="C" --> gchar *msg; msg = g_markup_printf_escaped (message_format, ...); gtk_message_dialog_format_secondary_markup (message_dialog, "%s", msg); g_free (msg); ]| a #GtkMessageDialog printf()-style markup string (see [Pango markup format][PangoMarkupFormat]), or %NULL arguments for @message_format Sets the secondary text of the message dialog to be @message_format (with printf()-style). a #GtkMessageDialog printf()-style format string, or %NULL arguments for @message_format Gets the dialog’s image. Use #GtkDialog for dialogs with images the dialog’s image a #GtkMessageDialog Returns the message area of the dialog. This is the box where the dialog’s primary and secondary labels are packed. You can add your own extra content to that box and it will appear below those labels. See gtk_dialog_get_content_area() for the corresponding function in the parent #GtkDialog. A #GtkBox corresponding to the “message area” in the @message_dialog. a #GtkMessageDialog Sets the dialog’s image to @image. Use #GtkDialog to create dialogs with images a #GtkMessageDialog the image Sets the text of the message dialog to be @str, which is marked up with the [Pango text markup language][PangoMarkupFormat]. a #GtkMessageDialog markup string (see [Pango markup format][PangoMarkupFormat]) The image for this dialog. Use #GtkDialog to create dialogs with images The #GtkBox that corresponds to the message area of this dialog. See gtk_message_dialog_get_message_area() for a detailed description of this area. The type of the message. The secondary text of the message dialog. %TRUE if the secondary text of the dialog includes Pango markup. See pango_parse_markup(). The primary text of the message dialog. If the dialog has a secondary text, this will appear as the title. %TRUE if the primary text of the dialog includes Pango markup. See pango_parse_markup(). The type of message being displayed in the dialog. Informational message Non-fatal warning message Question requiring a choice Fatal error message None of the above The #GtkMisc widget is an abstract widget which is not useful itself, but is used to derive subclasses which have alignment and padding attributes. The horizontal and vertical padding attributes allows extra space to be added around the widget. The horizontal and vertical alignment attributes enable the widget to be positioned within its allocated area. Note that if the widget is added to a container in such a way that it expands automatically to fill its allocated area, the alignment settings will not alter the widget's position. Note that the desired effect can in most cases be achieved by using the #GtkWidget:halign, #GtkWidget:valign and #GtkWidget:margin properties on the child widget, so GtkMisc should not be used in new code. To reflect this fact, all #GtkMisc API has been deprecated. Gets the X and Y alignment of the widget within its allocation. See gtk_misc_set_alignment(). Use #GtkWidget alignment and margin properties. a #GtkMisc location to store X alignment of @misc, or %NULL location to store Y alignment of @misc, or %NULL Gets the padding in the X and Y directions of the widget. See gtk_misc_set_padding(). Use #GtkWidget alignment and margin properties. a #GtkMisc location to store padding in the X direction, or %NULL location to store padding in the Y direction, or %NULL Sets the alignment of the widget. Use #GtkWidget's alignment (#GtkWidget:halign and #GtkWidget:valign) and margin properties or #GtkLabel's #GtkLabel:xalign and #GtkLabel:yalign properties. a #GtkMisc. the horizontal alignment, from 0 (left) to 1 (right). the vertical alignment, from 0 (top) to 1 (bottom). Sets the amount of space to add around the widget. Use #GtkWidget alignment and margin properties. a #GtkMisc. the amount of space to add on the left and right of the widget, in pixels. the amount of space to add on the top and bottom of the widget, in pixels. The horizontal alignment. A value of 0.0 means left alignment (or right on RTL locales); a value of 1.0 means right alignment (or left on RTL locales). Use gtk_widget_set_halign() instead. If you are using #GtkLabel, use #GtkLabel:xalign instead. The amount of space to add on the left and right of the widget, in pixels. Use gtk_widget_set_margin_start() and gtk_widget_set_margin_end() instead The vertical alignment. A value of 0.0 means top alignment; a value of 1.0 means bottom alignment. Use gtk_widget_set_valign() instead. If you are using #GtkLabel, use #GtkLabel:yalign instead. The amount of space to add on the top and bottom of the widget, in pixels. Use gtk_widget_set_margin_top() and gtk_widget_set_margin_bottom() instead GtkModelButton is a button class that can use a #GAction as its model. In contrast to #GtkToggleButton or #GtkRadioButton, which can also be backed by a #GAction via the #GtkActionable:action-name property, GtkModelButton will adapt its appearance according to the kind of action it is backed by, and appear either as a plain, check or radio button. Model buttons are used when popovers from a menu model with gtk_popover_new_from_model(); they can also be used manually in a #GtkPopoverMenu. When the action is specified via the #GtkActionable:action-name and #GtkActionable:action-target properties, the role of the button (i.e. whether it is a plain, check or radio button) is determined by the type of the action and doesn't have to be explicitly specified with the #GtkModelButton:role property. The content of the button is specified by the #GtkModelButton:text and #GtkModelButton:icon properties. The appearance of model buttons can be influenced with the #GtkModelButton:centered and #GtkModelButton:iconic properties. Model buttons have built-in support for submenus in #GtkPopoverMenu. To make a GtkModelButton that opens a submenu when activated, set the #GtkModelButton:menu-name property. To make a button that goes back to the parent menu, you should set the #GtkModelButton:inverted property to place the submenu indicator at the opposite side. # Example |[ <object class="GtkPopoverMenu"> <child> <object class="GtkBox"> <property name="visible">True</property> <property name="margin">10</property> <child> <object class="GtkModelButton"> <property name="visible">True</property> <property name="action-name">view.cut</property> <property name="text" translatable="yes">Cut</property> </object> </child> <child> <object class="GtkModelButton"> <property name="visible">True</property> <property name="action-name">view.copy</property> <property name="text" translatable="yes">Copy</property> </object> </child> <child> <object class="GtkModelButton"> <property name="visible">True</property> <property name="action-name">view.paste</property> <property name="text" translatable="yes">Paste</property> </object> </child> </object> </child> </object> ]| # CSS nodes |[<!-- language="plain" --> modelbutton ├── <child> ╰── check ]| |[<!-- language="plain" --> modelbutton ├── <child> ╰── radio ]| |[<!-- language="plain" --> modelbutton ├── <child> ╰── arrow ]| GtkModelButton has a main CSS node with name modelbutton, and a subnode, which will have the name check, radio or arrow, depending on the role of the button and whether it has a menu name set. The subnode is positioned before or after the content nodes and gets the .left or .right style class, depending on where it is located. |[<!-- language="plain" --> button.model ├── <child> ╰── check ]| Iconic model buttons (see #GtkModelButton:iconic) change the name of their main node to button and add a .model style class to it. The indicator subnode is invisible in this case. Creates a new GtkModelButton. the newly created #GtkModelButton widget The state of the button. This is reflecting the state of the associated #GAction. Whether to render the button contents centered instead of left-aligned. This property should be set for title-like items. A #GIcon that will be used if iconic appearance for the button is desired. If this property is set, the button will show an icon if one is set. If no icon is set, the text will be used. This is typically used for horizontal sections of linked buttons. Whether to show the submenu indicator at the opposite side than normal. This property should be set for model buttons that 'go back' to a parent menu. The name of a submenu to open when the button is activated. If this is set, the button should not have an action associated with it. Specifies whether the button is a plain, check or radio button. When #GtkActionable:action-name is set, the role will be determined from the action and does not have to be set explicitly. The label for the button. If %TRUE, XML tags in the text of the button are interpreted as by pango_parse_markup() to format the enclosed spans of text. If %FALSE, the text will be displayed verbatim. A multihead-aware GTK+ module may have a gtk_module_display_init() function with this prototype. GTK+ calls this function for each opened display. an open #GdkDisplay Each GTK+ module must have a function gtk_module_init() with this prototype. This function is called after loading the module. GTK+ always passes %NULL for this argument GTK+ always passes %NULL for this argument This should not be accessed directly. Use the accessor functions below. Creates a new #GtkMountOperation a new #GtkMountOperation transient parent of the window, or %NULL Gets the transient parent used by the #GtkMountOperation the transient parent for windows shown by @op a #GtkMountOperation Gets the screen on which windows of the #GtkMountOperation will be shown. the screen on which windows of @op are shown a #GtkMountOperation Returns whether the #GtkMountOperation is currently displaying a window. %TRUE if @op is currently displaying a window a #GtkMountOperation Sets the transient parent for windows shown by the #GtkMountOperation. a #GtkMountOperation transient parent of the window, or %NULL Sets the screen to show windows of the #GtkMountOperation on. a #GtkMountOperation a #GdkScreen The parent class. Move forward or back by graphemes Move left or right by graphemes Move forward or back by words Move up or down lines (wrapped lines) Move to either end of a line Move up or down paragraphs (newline-ended lines) Move to either end of a paragraph Move by pages Move to ends of the buffer Move horizontally by pages Native dialogs are platform dialogs that don't use #GtkDialog or #GtkWindow. They are used in order to integrate better with a platform, by looking the same as other native applications and supporting platform specific features. The #GtkDialog functions cannot be used on such objects, but we need a similar API in order to drive them. The #GtkNativeDialog object is an API that allows you to do this. It allows you to set various common properties on the dialog, as well as show and hide it and get a #GtkNativeDialog::response signal when the user finished with the dialog. There is also a gtk_native_dialog_run() helper that makes it easy to run any native dialog in a modal way with a recursive mainloop, similar to gtk_dialog_run(). Hides the dialog if it is visilbe, aborting any interaction. Once this is called the #GtkNativeDialog::response signal will not be emitted until after the next call to gtk_native_dialog_show(). If the dialog is not visible this does nothing. a #GtkNativeDialog Shows the dialog on the display, allowing the user to interact with it. When the user accepts the state of the dialog the dialog will be automatically hidden and the #GtkNativeDialog::response signal will be emitted. Multiple calls while the dialog is visible will be ignored. a #GtkNativeDialog Destroys a dialog. When a dialog is destroyed, it will break any references it holds to other objects. If it is visible it will be hidden and any underlying window system resources will be destroyed. Note that this does not release any reference to the object (as opposed to destroying a GtkWindow) because there is no reference from the windowing system to the #GtkNativeDialog. a #GtkNativeDialog Returns whether the dialog is modal. See gtk_native_dialog_set_modal(). %TRUE if the dialog is set to be modal a #GtkNativeDialog Gets the title of the #GtkNativeDialog. the title of the dialog, or %NULL if none has been set explicitly. The returned string is owned by the widget and must not be modified or freed. a #GtkNativeDialog Fetches the transient parent for this window. See gtk_native_dialog_set_transient_for(). the transient parent for this window, or %NULL if no transient parent has been set. a #GtkNativeDialog Determines whether the dialog is visible. %TRUE if the dialog is visible a #GtkNativeDialog Hides the dialog if it is visilbe, aborting any interaction. Once this is called the #GtkNativeDialog::response signal will not be emitted until after the next call to gtk_native_dialog_show(). If the dialog is not visible this does nothing. a #GtkNativeDialog Blocks in a recursive main loop until @self emits the #GtkNativeDialog::response signal. It then returns the response ID from the ::response signal emission. Before entering the recursive main loop, gtk_native_dialog_run() calls gtk_native_dialog_show() on the dialog for you. After gtk_native_dialog_run() returns, then dialog will be hidden. Typical usage of this function might be: |[<!-- language="C" --> gint result = gtk_native_dialog_run (GTK_NATIVE_DIALOG (dialog)); switch (result) { case GTK_RESPONSE_ACCEPT: do_application_specific_something (); break; default: do_nothing_since_dialog_was_cancelled (); break; } g_object_unref (dialog); ]| Note that even though the recursive main loop gives the effect of a modal dialog (it prevents the user from interacting with other windows in the same window group while the dialog is run), callbacks such as timeouts, IO channel watches, DND drops, etc, will be triggered during a gtk_native_dialog_run() call. response ID a #GtkNativeDialog Sets a dialog modal or non-modal. Modal dialogs prevent interaction with other windows in the same application. To keep modal dialogs on top of main application windows, use gtk_native_dialog_set_transient_for() to make the dialog transient for the parent; most [window managers][gtk-X11-arch] will then disallow lowering the dialog below the parent. a #GtkNativeDialog whether the window is modal Sets the title of the #GtkNativeDialog. a #GtkNativeDialog title of the dialog Dialog windows should be set transient for the main application window they were spawned from. This allows [window managers][gtk-X11-arch] to e.g. keep the dialog on top of the main window, or center the dialog over the main window. Passing %NULL for @parent unsets the current transient window. a #GtkNativeDialog parent window, or %NULL Shows the dialog on the display, allowing the user to interact with it. When the user accepts the state of the dialog the dialog will be automatically hidden and the #GtkNativeDialog::response signal will be emitted. Multiple calls while the dialog is visible will be ignored. a #GtkNativeDialog Whether the window should be modal with respect to its transient parent. The title of the dialog window The transient parent of the dialog, or %NULL for none. Whether the window is currenlty visible. Emitted when the user responds to the dialog. When this is called the dialog has been hidden. If you call gtk_native_dialog_hide() before the user responds to the dialog this signal will not be emitted. the response ID a #GtkNativeDialog a #GtkNativeDialog The #GtkNotebook widget is a #GtkContainer whose children are pages that can be switched between using tab labels along one edge. There are many configuration options for GtkNotebook. Among other things, you can choose on which edge the tabs appear (see gtk_notebook_set_tab_pos()), whether, if there are too many tabs to fit the notebook should be made bigger or scrolling arrows added (see gtk_notebook_set_scrollable()), and whether there will be a popup menu allowing the users to switch pages. (see gtk_notebook_popup_enable(), gtk_notebook_popup_disable()) # GtkNotebook as GtkBuildable The GtkNotebook implementation of the #GtkBuildable interface supports placing children into tabs by specifying “tab” as the “type” attribute of a `<child>` element. Note that the content of the tab must be created before the tab can be filled. A tab child can be specified without specifying a `<child>` type attribute. To add a child widget in the notebooks action area, specify "action-start" or “action-end” as the “type” attribute of the `<child>` element. An example of a UI definition fragment with GtkNotebook: |[<!-- language="xml" --> <object class="GtkNotebook"> <child> <object class="GtkLabel" id="notebook-content"> <property name="label">Content</property> </object> </child> <child type="tab"> <object class="GtkLabel" id="notebook-tab"> <property name="label">Tab</property> </object> </child> </object> ]| # CSS nodes |[<!-- language="plain" --> notebook ├── header.top │ ├── [<action widget>] │ ├── tabs │ │ ├── [arrow] │ │ ├── tab │ │ │ ╰── <tab label> ┊ ┊ ┊ │ │ ├── tab[.reorderable-page] │ │ │ ╰── <tab label> │ │ ╰── [arrow] │ ╰── [<action widget>] │ ╰── stack ├── <child> ┊ ╰── <child> ]| GtkNotebook has a main CSS node with name notebook, a subnode with name header and below that a subnode with name tabs which contains one subnode per tab with name tab. If action widgets are present, their CSS nodes are placed next to the tabs node. If the notebook is scrollable, CSS nodes with name arrow are placed as first and last child of the tabs node. The main node gets the .frame style class when the notebook has a border (see gtk_notebook_set_show_border()). The header node gets one of the style class .top, .bottom, .left or .right, depending on where the tabs are placed. For reorderable pages, the tab node gets the .reorderable-page class. A tab node gets the .dnd style class while it is moved with drag-and-drop. The nodes are always arranged from left-to-right, regarldess of text direction. Creates a new #GtkNotebook widget with no pages. the newly created #GtkNotebook Appends a page to @notebook. the index (starting from 0) of the appended page in the notebook, or -1 if function fails a #GtkNotebook the #GtkWidget to use as the contents of the page the #GtkWidget to be used as the label for the page, or %NULL to use the default label, “page N” Appends a page to @notebook, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the appended page in the notebook, or -1 if function fails a #GtkNotebook the #GtkWidget to use as the contents of the page the #GtkWidget to be used as the label for the page, or %NULL to use the default label, “page N” the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a #GtkLabel or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label is not a #GtkLabel, @menu_label must be specified if the page-switch menu is to be used. Removes the child from the notebook. This function is very similar to gtk_container_remove(), but additionally informs the notebook that the removal is happening as part of a tab DND operation, which should not be cancelled. a #GtkNotebook a child Gets one of the action widgets. See gtk_notebook_set_action_widget(). The action widget with the given @pack_type or %NULL when this action widget has not been set a #GtkNotebook pack type of the action widget to receive Returns the page number of the current page. the index (starting from 0) of the current page in the notebook. If the notebook has no pages, then -1 will be returned. a #GtkNotebook Gets the current group name for @notebook. the group name, or %NULL if none is set a #GtkNotebook Retrieves the menu label widget of the page containing @child. the menu label, or %NULL if the notebook page does not have a menu label other than the default (the tab label). a #GtkNotebook a widget contained in a page of @notebook Retrieves the text of the menu label for the page containing @child. the text of the tab label, or %NULL if the widget does not have a menu label other than the default menu label, or the menu label widget is not a #GtkLabel. The string is owned by the widget and must not be freed. a #GtkNotebook the child widget of a page of the notebook. Gets the number of pages in a notebook. the number of pages in the notebook a #GtkNotebook Returns the child widget contained in page number @page_num. the child widget, or %NULL if @page_num is out of bounds a #GtkNotebook the index of a page in the notebook, or -1 to get the last page Returns whether the tab label area has arrows for scrolling. See gtk_notebook_set_scrollable(). %TRUE if arrows for scrolling are present a #GtkNotebook Returns whether a bevel will be drawn around the notebook pages. See gtk_notebook_set_show_border(). %TRUE if the bevel is drawn a #GtkNotebook Returns whether the tabs of the notebook are shown. See gtk_notebook_set_show_tabs(). %TRUE if the tabs are shown a #GtkNotebook Returns whether the tab contents can be detached from @notebook. %TRUE if the tab is detachable. a #GtkNotebook a child #GtkWidget Returns the horizontal width of a tab border. this function returns zero horizontal width of a tab border a #GtkNotebook Returns the tab label widget for the page @child. %NULL is returned if @child is not in @notebook or if no tab label has specifically been set for @child. the tab label a #GtkNotebook the page Retrieves the text of the tab label for the page containing @child. the text of the tab label, or %NULL if the tab label widget is not a #GtkLabel. The string is owned by the widget and must not be freed. a #GtkNotebook a widget contained in a page of @notebook Gets the edge at which the tabs for switching pages in the notebook are drawn. the edge at which the tabs are drawn a #GtkNotebook Gets whether the tab can be reordered via drag and drop or not. %TRUE if the tab is reorderable. a #GtkNotebook a child #GtkWidget Returns the vertical width of a tab border. this function returns zero vertical width of a tab border a #GtkNotebook Insert a page into @notebook at the given position. the index (starting from 0) of the inserted page in the notebook, or -1 if function fails a #GtkNotebook the #GtkWidget to use as the contents of the page the #GtkWidget to be used as the label for the page, or %NULL to use the default label, “page N” the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages Insert a page into @notebook at the given position, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the inserted page in the notebook a #GtkNotebook the #GtkWidget to use as the contents of the page the #GtkWidget to be used as the label for the page, or %NULL to use the default label, “page N” the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a #GtkLabel or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label is not a #GtkLabel, @menu_label must be specified if the page-switch menu is to be used. the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages. Switches to the next page. Nothing happens if the current page is the last page. a #GtkNotebook Finds the index of the page which contains the given child widget. the index of the page containing @child, or -1 if @child is not in the notebook a #GtkNotebook a #GtkWidget Disables the popup menu. a #GtkNotebook Enables the popup menu: if the user clicks with the right mouse button on the tab labels, a menu with all the pages will be popped up. a #GtkNotebook Prepends a page to @notebook. the index (starting from 0) of the prepended page in the notebook, or -1 if function fails a #GtkNotebook the #GtkWidget to use as the contents of the page the #GtkWidget to be used as the label for the page, or %NULL to use the default label, “page N” Prepends a page to @notebook, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the prepended page in the notebook, or -1 if function fails a #GtkNotebook the #GtkWidget to use as the contents of the page the #GtkWidget to be used as the label for the page, or %NULL to use the default label, “page N” the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a #GtkLabel or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label is not a #GtkLabel, @menu_label must be specified if the page-switch menu is to be used. Switches to the previous page. Nothing happens if the current page is the first page. a #GtkNotebook Removes a page from the notebook given its index in the notebook. a #GtkNotebook the index of a notebook page, starting from 0. If -1, the last page will be removed. Reorders the page containing @child, so that it appears in position @position. If @position is greater than or equal to the number of children in the list or negative, @child will be moved to the end of the list. a #GtkNotebook the child to move the new position, or -1 to move to the end Sets @widget as one of the action widgets. Depending on the pack type the widget will be placed before or after the tabs. You can use a #GtkBox if you need to pack more than one widget on the same side. Note that action widgets are “internal” children of the notebook and thus not included in the list returned from gtk_container_foreach(). a #GtkNotebook a #GtkWidget pack type of the action widget Switches to the page number @page_num. Note that due to historical reasons, GtkNotebook refuses to switch to a page unless the child widget is visible. Therefore, it is recommended to show child widgets before adding them to a notebook. a #GtkNotebook index of the page to switch to, starting from 0. If negative, the last page will be used. If greater than the number of pages in the notebook, nothing will be done. Sets a group name for @notebook. Notebooks with the same name will be able to exchange tabs via drag and drop. A notebook with a %NULL group name will not be able to exchange tabs with any other notebook. a #GtkNotebook the name of the notebook group, or %NULL to unset it Changes the menu label for the page containing @child. a #GtkNotebook the child widget the menu label, or %NULL for default Creates a new label and sets it as the menu label of @child. a #GtkNotebook the child widget the label text Sets whether the tab label area will have arrows for scrolling if there are too many tabs to fit in the area. a #GtkNotebook %TRUE if scroll arrows should be added Sets whether a bevel will be drawn around the notebook pages. This only has a visual effect when the tabs are not shown. See gtk_notebook_set_show_tabs(). a #GtkNotebook %TRUE if a bevel should be drawn around the notebook Sets whether to show the tabs for the notebook or not. a #GtkNotebook %TRUE if the tabs should be shown Sets whether the tab can be detached from @notebook to another notebook or widget. Note that 2 notebooks must share a common group identificator (see gtk_notebook_set_group_name()) to allow automatic tabs interchange between them. If you want a widget to interact with a notebook through DnD (i.e.: accept dragged tabs from it) it must be set as a drop destination and accept the target “GTK_NOTEBOOK_TAB”. The notebook will fill the selection with a GtkWidget** pointing to the child widget that corresponds to the dropped tab. Note that you should use gtk_notebook_detach_tab() instead of gtk_container_remove() if you want to remove the tab from the source notebook as part of accepting a drop. Otherwise, the source notebook will think that the dragged tab was removed from underneath the ongoing drag operation, and will initiate a drag cancel animation. |[<!-- language="C" --> static void on_drag_data_received (GtkWidget *widget, GdkDragContext *context, gint x, gint y, GtkSelectionData *data, guint info, guint time, gpointer user_data) { GtkWidget *notebook; GtkWidget **child; notebook = gtk_drag_get_source_widget (context); child = (void*) gtk_selection_data_get_data (data); // process_widget (*child); gtk_notebook_detach_tab (GTK_NOTEBOOK (notebook), *child); } ]| If you want a notebook to accept drags from other widgets, you will have to set your own DnD code to do it. a #GtkNotebook a child #GtkWidget whether the tab is detachable or not Changes the tab label for @child. If %NULL is specified for @tab_label, then the page will have the label “page N”. a #GtkNotebook the page the tab label widget to use, or %NULL for default tab label Creates a new label and sets it as the tab label for the page containing @child. a #GtkNotebook the page the label text Sets the edge at which the tabs for switching pages in the notebook are drawn. a #GtkNotebook. the edge to draw the tabs at Sets whether the notebook tab can be reordered via drag and drop or not. a #GtkNotebook a child #GtkWidget whether the tab is reorderable or not Group name for tab drag and drop. The ::create-window signal is emitted when a detachable tab is dropped on the root window. A handler for this signal can create a window containing a notebook where the tab will be attached. It is also responsible for moving/resizing the window and adding the necessary properties to the notebook (e.g. the #GtkNotebook:group-name ). a #GtkNotebook that @page should be added to, or %NULL. the tab of @notebook that is being detached the X coordinate where the drop happens the Y coordinate where the drop happens the ::page-added signal is emitted in the notebook right after a page is added to the notebook. the child #GtkWidget affected the new page number for @child the ::page-removed signal is emitted in the notebook right after a page is removed from the notebook. the child #GtkWidget affected the @child page number the ::page-reordered signal is emitted in the notebook right after a page has been reordered. the child #GtkWidget affected the new page number for @child Emitted when the user or a function changes the current page. the new current page the index of the page Used to determine the layout of pages on a sheet when printing multiple pages per sheet. ![](layout-lrtb.png) ![](layout-lrbt.png) ![](layout-rltb.png) ![](layout-rlbt.png) ![](layout-tblr.png) ![](layout-tbrl.png) ![](layout-btlr.png) ![](layout-btrl.png) GtkNumerableIcon is a subclass of #GEmblemedIcon that can show a number or short string as an emblem. The number can be overlayed on top of another emblem, if desired. It supports theming by taking font and color information from a provided #GtkStyleContext; see gtk_numerable_icon_set_style_context(). Typical numerable icons: ![](numerableicon.png) ![](numerableicon2.png) Creates a new unthemed #GtkNumerableIcon. a new #GIcon a #GIcon to overlay on Creates a new #GtkNumerableIcon which will themed according to the passed #GtkStyleContext. This is a convenience constructor that calls gtk_numerable_icon_set_style_context() internally. a new #GIcon a #GIcon to overlay on a #GtkStyleContext Returns the #GIcon that was set as the base background image, or %NULL if there’s none. The caller of this function does not own a reference to the returned #GIcon. a #GIcon, or %NULL a #GtkNumerableIcon Returns the icon name used as the base background image, or %NULL if there’s none. an icon name, or %NULL a #GtkNumerableIcon Returns the value currently displayed by @self. the currently displayed value a #GtkNumerableIcon Returns the currently displayed label of the icon, or %NULL. the currently displayed label a #GtkNumerableIcon Returns the #GtkStyleContext used by the icon for theming, or %NULL if there’s none. a #GtkStyleContext, or %NULL. This object is internal to GTK+ and should not be unreffed. Use g_object_ref() if you want to keep it around a #GtkNumerableIcon Updates the icon to use @icon as the base background image. If @icon is %NULL, @self will go back using style information or default theming for its background image. If this method is called and an icon name was already set as background for the icon, @icon will be used, i.e. the last method called between gtk_numerable_icon_set_background_gicon() and gtk_numerable_icon_set_background_icon_name() has always priority. a #GtkNumerableIcon a #GIcon, or %NULL Updates the icon to use the icon named @icon_name from the current icon theme as the base background image. If @icon_name is %NULL, @self will go back using style information or default theming for its background image. If this method is called and a #GIcon was already set as background for the icon, @icon_name will be used, i.e. the last method called between gtk_numerable_icon_set_background_icon_name() and gtk_numerable_icon_set_background_gicon() has always priority. a #GtkNumerableIcon an icon name, or %NULL Sets the currently displayed value of @self to @count. The numeric value is always clamped to make it two digits, i.e. between -99 and 99. Setting a count of zero removes the emblem. If this method is called, and a label was already set on the icon, it will automatically be reset to %NULL before rendering the number, i.e. the last method called between gtk_numerable_icon_set_count() and gtk_numerable_icon_set_label() has always priority. a #GtkNumerableIcon a number between -99 and 99 Sets the currently displayed value of @self to the string in @label. Setting an empty label removes the emblem. Note that this is meant for displaying short labels, such as roman numbers, or single letters. For roman numbers, consider using the Unicode characters U+2160 - U+217F. Strings longer than two characters will likely not be rendered very well. If this method is called, and a number was already set on the icon, it will automatically be reset to zero before rendering the label, i.e. the last method called between gtk_numerable_icon_set_label() and gtk_numerable_icon_set_count() has always priority. a #GtkNumerableIcon a short label, or %NULL Updates the icon to fetch theme information from the given #GtkStyleContext. a #GtkNumerableIcon a #GtkStyleContext GtkOffscreenWindow is strictly intended to be used for obtaining snapshots of widgets that are not part of a normal widget hierarchy. Since #GtkOffscreenWindow is a toplevel widget you cannot obtain snapshots of a full window with it since you cannot pack a toplevel widget in another toplevel. The idea is to take a widget and manually set the state of it, add it to a GtkOffscreenWindow and then retrieve the snapshot as a #cairo_surface_t or #GdkPixbuf. GtkOffscreenWindow derives from #GtkWindow only as an implementation detail. Applications should not use any API specific to #GtkWindow to operate on this object. It should be treated as a #GtkBin that has no parent widget. When contained offscreen widgets are redrawn, GtkOffscreenWindow will emit a #GtkWidget::damage-event signal. Creates a toplevel container widget that is used to retrieve snapshots of widgets without showing them on the screen. A pointer to a #GtkWidget Retrieves a snapshot of the contained widget in the form of a #GdkPixbuf. This is a new pixbuf with a reference count of 1, and the application should unreference it once it is no longer needed. A #GdkPixbuf pointer, or %NULL. the #GtkOffscreenWindow contained widget. Retrieves a snapshot of the contained widget in the form of a #cairo_surface_t. If you need to keep this around over window resizes then you should add a reference to it. A #cairo_surface_t pointer to the offscreen surface, or %NULL. the #GtkOffscreenWindow contained widget. The parent class. The #GtkOrientable interface is implemented by all widgets that can be oriented horizontally or vertically. Historically, such widgets have been realized as subclasses of a common base class (e.g #GtkBox/#GtkHBox/#GtkVBox or #GtkScale/#GtkHScale/#GtkVScale). #GtkOrientable is more flexible in that it allows the orientation to be changed at runtime, allowing the widgets to “flip”. #GtkOrientable was introduced in GTK+ 2.16. Retrieves the orientation of the @orientable. the orientation of the @orientable. a #GtkOrientable Sets the orientation of the @orientable. a #GtkOrientable the orientable’s new orientation. The orientation of the orientable. Represents the orientation of widgets and other objects which can be switched between horizontal and vertical orientation on the fly, like #GtkToolbar or #GtkGesturePan. The element is in horizontal orientation. The element is in vertical orientation. GtkOverlay is a container which contains a single main child, on top of which it can place “overlay” widgets. The position of each overlay widget is determined by its #GtkWidget:halign and #GtkWidget:valign properties. E.g. a widget with both alignments set to %GTK_ALIGN_START will be placed at the top left corner of the GtkOverlay container, whereas an overlay with halign set to %GTK_ALIGN_CENTER and valign set to %GTK_ALIGN_END will be placed a the bottom edge of the GtkOverlay, horizontally centered. The position can be adjusted by setting the margin properties of the child to non-zero values. More complicated placement of overlays is possible by connecting to the #GtkOverlay::get-child-position signal. An overlay’s minimum and natural sizes are those of its main child. The sizes of overlay children are not considered when measuring these preferred sizes. # GtkOverlay as GtkBuildable The GtkOverlay implementation of the GtkBuildable interface supports placing a child as an overlay by specifying “overlay” as the “type” attribute of a `<child>` element. # CSS nodes GtkOverlay has a single CSS node with the name “overlay”. Overlay children whose alignments cause them to be positioned at an edge get the style classes “.left”, “.right”, “.top”, and/or “.bottom” according to their position. Creates a new #GtkOverlay. a new #GtkOverlay object. Signal emitted to determine the position and size of any overlay child widgets. Adds @widget to @overlay. The widget will be stacked on top of the main widget added with gtk_container_add(). The position at which @widget is placed is determined from its #GtkWidget:halign and #GtkWidget:valign properties. a #GtkOverlay a #GtkWidget to be added to the container Convenience function to get the value of the #GtkOverlay:pass-through child property for @widget. whether the widget is a pass through child. a #GtkOverlay an overlay child of #GtkOverlay Moves @child to a new @index in the list of @overlay children. The list contains overlays in the order that these were added to @overlay by default. See also #GtkOverlay:index. A widget’s index in the @overlay children list determines which order the children are drawn if they overlap. The first child is drawn at the bottom. It also affects the default focus chain order. a #GtkOverlay the overlaid #GtkWidget to move the new index for @child in the list of overlay children of @overlay, starting from 0. If negative, indicates the end of the list Convenience function to set the value of the #GtkOverlay:pass-through child property for @widget. a #GtkOverlay an overlay child of #GtkOverlay whether the child should pass the input through The ::get-child-position signal is emitted to determine the position and size of any overlay child widgets. A handler for this signal should fill @allocation with the desired position and size for @widget, relative to the 'main' child of @overlay. The default handler for this signal uses the @widget's halign and valign properties to determine the position and gives the widget its natural size (except that an alignment of %GTK_ALIGN_FILL will cause the overlay to be full-width/height). If the main child is a #GtkScrolledWindow, the overlays are placed relative to its contents. %TRUE if the @allocation has been filled the child widget to position return location for the allocation The parent class. Signal emitted to determine the position and size of any overlay child widgets. Name for the A3 paper size. Name for the A4 paper size. Name for the A5 paper size. Name for the B5 paper size. Name for the Executive paper size. Name for the Legal paper size. Name for the Letter paper size. The key used by the “Print to file” printer to store the file name of the output without the path to the directory and the file extension. The key used by the “Print to file” printer to store the directory to which the output should be written. The key used by the “Print to file” printer to store the format of the output. The supported values are “PS” and “PDF”. The key used by the “Print to file” printer to store the URI to which the output should be written. GTK+ itself supports only “file://” URIs. Use this priority for functionality related to size allocation. It is used internally by GTK+ to compute the sizes of widgets. This priority is higher than %GDK_PRIORITY_REDRAW to avoid resizing a widget which was just redrawn. Determines how widgets should be packed inside menubars and menuitems contained in menubars. Widgets are packed left-to-right Widgets are packed right-to-left Widgets are packed top-to-bottom Widgets are packed bottom-to-top Represents the packing location #GtkBox children. (See: #GtkVBox, #GtkHBox, and #GtkButtonBox). The child is packed into the start of the box The child is packed into the end of the box Struct defining a pad action entry. the type of pad feature that will trigger this action entry. the 0-indexed button/ring/strip number that will trigger this action entry. the mode that will trigger this action entry, or -1 for all modes. Human readable description of this action entry, this string should be deemed user-visible. action name that will be activated in the #GActionGroup. The type of a pad action. Action is triggered by a pad button Action is triggered by a pad ring Action is triggered by a pad strip #GtkPadController is an event controller for the pads found in drawing tablets (The collection of buttons and tactile sensors often found around the stylus-sensitive area). These buttons and sensors have no implicit meaning, and by default they perform no action, this event controller is provided to map those to #GAction objects, thus letting the application give those a more semantic meaning. Buttons and sensors are not constrained to triggering a single action, some %GDK_SOURCE_TABLET_PAD devices feature multiple "modes", all these input elements have one current mode, which may determine the final action being triggered. Pad devices often divide buttons and sensors into groups, all elements in a group share the same current mode, but different groups may have different modes. See gdk_device_pad_get_n_groups() and gdk_device_pad_get_group_n_modes(). Each of the actions that a given button/strip/ring performs for a given mode is defined by #GtkPadActionEntry, it contains an action name that will be looked up in the given #GActionGroup and activated whenever the specified input element and mode are triggered. A simple example of #GtkPadController usage, assigning button 1 in all modes and pad devices to an "invert-selection" action: |[ GtkPadActionEntry *pad_actions[] = { { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection", "pad-actions.invert-selection" }, … }; … action_group = g_simple_action_group_new (); action = g_simple_action_new ("pad-actions.invert-selection", NULL); g_signal_connect (action, "activate", on_invert_selection_activated, NULL); g_action_map_add_action (G_ACTION_MAP (action_group), action); … pad_controller = gtk_pad_controller_new (window, action_group, NULL); ]| The actions belonging to rings/strips will be activated with a parameter of type %G_VARIANT_TYPE_DOUBLE bearing the value of the given axis, it is required that those are made stateful and accepting this #GVariantType. Creates a new #GtkPadController that will associate events from @pad to actions. A %NULL pad may be provided so the controller manages all pad devices generically, it is discouraged to mix #GtkPadController objects with %NULL and non-%NULL @pad argument on the same @window, as execution order is not guaranteed. The #GtkPadController is created with no mapped actions. In order to map pad events to actions, use gtk_pad_controller_set_action_entries() or gtk_pad_controller_set_action(). A newly created #GtkPadController a #GtkWindow #GActionGroup to trigger actions from A %GDK_SOURCE_TABLET_PAD device, or %NULL to handle all pads Adds an individual action to @controller. This action will only be activated if the given button/ring/strip number in @index is interacted while the current mode is @mode. -1 may be used for simple cases, so the action is triggered on all modes. The given @label should be considered user-visible, so internationalization rules apply. Some windowing systems may be able to use those for user feedback. a #GtkPadController the type of pad feature that will trigger this action the 0-indexed button/ring/strip number that will trigger this action the mode that will trigger this action, or -1 for all modes. Human readable description of this action, this string should be deemed user-visible. action name that will be activated in the #GActionGroup This is a convenience function to add a group of action entries on @controller. See #GtkPadActionEntry and gtk_pad_controller_set_action(). a #GtkPadController the action entries to set on @controller the number of elements in @entries See also gtk_print_settings_set_orientation(). Portrait mode. Landscape mode. Reverse portrait mode. Reverse landscape mode. See also gtk_print_settings_set_page_ranges(). start of page range. end of page range. See also gtk_print_job_set_page_set(). All pages. Even pages. Odd pages. A GtkPageSetup object stores the page size, orientation and margins. The idea is that you can get one of these from the page setup dialog and then pass it to the #GtkPrintOperation when printing. The benefit of splitting this out of the #GtkPrintSettings is that these affect the actual layout of the page, and thus need to be set long before user prints. ## Margins ## {#print-margins} The margins specified in this object are the “print margins”, i.e. the parts of the page that the printer cannot print on. These are different from the layout margins that a word processor uses; they are typically used to determine the minimal size for the layout margins. To obtain a #GtkPageSetup use gtk_page_setup_new() to get the defaults, or use gtk_print_run_page_setup_dialog() to show the page setup dialog and receive the resulting page setup. ## A page setup dialog |[<!-- language="C" --> static GtkPrintSettings *settings = NULL; static GtkPageSetup *page_setup = NULL; static void do_page_setup (void) { GtkPageSetup *new_page_setup; if (settings == NULL) settings = gtk_print_settings_new (); new_page_setup = gtk_print_run_page_setup_dialog (GTK_WINDOW (main_window), page_setup, settings); if (page_setup) g_object_unref (page_setup); page_setup = new_page_setup; } ]| Printing support was added in GTK+ 2.10. Creates a new #GtkPageSetup. a new #GtkPageSetup. Reads the page setup from the file @file_name. Returns a new #GtkPageSetup object with the restored page setup, or %NULL if an error occurred. See gtk_page_setup_to_file(). the restored #GtkPageSetup the filename to read the page setup from Desrialize a page setup from an a{sv} variant in the format produced by gtk_page_setup_to_gvariant(). a new #GtkPageSetup object an a{sv} #GVariant Reads the page setup from the group @group_name in the key file @key_file. Returns a new #GtkPageSetup object with the restored page setup, or %NULL if an error occurred. the restored #GtkPageSetup the #GKeyFile to retrieve the page_setup from the name of the group in the key_file to read, or %NULL to use the default name “Page Setup” Copies a #GtkPageSetup. a copy of @other the #GtkPageSetup to copy Gets the bottom margin in units of @unit. the bottom margin a #GtkPageSetup the unit for the return value Gets the left margin in units of @unit. the left margin a #GtkPageSetup the unit for the return value Gets the page orientation of the #GtkPageSetup. the page orientation a #GtkPageSetup Returns the page height in units of @unit. Note that this function takes orientation and margins into consideration. See gtk_page_setup_get_paper_height(). the page height. a #GtkPageSetup the unit for the return value Returns the page width in units of @unit. Note that this function takes orientation and margins into consideration. See gtk_page_setup_get_paper_width(). the page width. a #GtkPageSetup the unit for the return value Returns the paper height in units of @unit. Note that this function takes orientation, but not margins into consideration. See gtk_page_setup_get_page_height(). the paper height. a #GtkPageSetup the unit for the return value Gets the paper size of the #GtkPageSetup. the paper size a #GtkPageSetup Returns the paper width in units of @unit. Note that this function takes orientation, but not margins into consideration. See gtk_page_setup_get_page_width(). the paper width. a #GtkPageSetup the unit for the return value Gets the right margin in units of @unit. the right margin a #GtkPageSetup the unit for the return value Gets the top margin in units of @unit. the top margin a #GtkPageSetup the unit for the return value Reads the page setup from the file @file_name. See gtk_page_setup_to_file(). %TRUE on success a #GtkPageSetup the filename to read the page setup from Reads the page setup from the group @group_name in the key file @key_file. %TRUE on success a #GtkPageSetup the #GKeyFile to retrieve the page_setup from the name of the group in the key_file to read, or %NULL to use the default name “Page Setup” Sets the bottom margin of the #GtkPageSetup. a #GtkPageSetup the new bottom margin in units of @unit the units for @margin Sets the left margin of the #GtkPageSetup. a #GtkPageSetup the new left margin in units of @unit the units for @margin Sets the page orientation of the #GtkPageSetup. a #GtkPageSetup a #GtkPageOrientation value Sets the paper size of the #GtkPageSetup without changing the margins. See gtk_page_setup_set_paper_size_and_default_margins(). a #GtkPageSetup a #GtkPaperSize Sets the paper size of the #GtkPageSetup and modifies the margins according to the new paper size. a #GtkPageSetup a #GtkPaperSize Sets the right margin of the #GtkPageSetup. a #GtkPageSetup the new right margin in units of @unit the units for @margin Sets the top margin of the #GtkPageSetup. a #GtkPageSetup the new top margin in units of @unit the units for @margin This function saves the information from @setup to @file_name. %TRUE on success a #GtkPageSetup the file to save to Serialize page setup to an a{sv} variant. a new, floating, #GVariant a #GtkPageSetup This function adds the page setup from @setup to @key_file. a #GtkPageSetup the #GKeyFile to save the page setup to the group to add the settings to in @key_file, or %NULL to use the default name “Page Setup” The type of function that is passed to gtk_print_run_page_setup_dialog_async(). This function will be called when the page setup dialog is dismissed, and also serves as destroy notify for @data. the #GtkPageSetup that has been user data that has been passed to gtk_print_run_page_setup_dialog_async() Describes the panning direction of a #GtkGesturePan panned towards the left panned towards the right panned upwards panned downwards #GtkPaned has two panes, arranged either horizontally or vertically. The division between the two panes is adjustable by the user by dragging a handle. Child widgets are added to the panes of the widget with gtk_paned_pack1() and gtk_paned_pack2(). The division between the two children is set by default from the size requests of the children, but it can be adjusted by the user. A paned widget draws a separator between the two child widgets and a small handle that the user can drag to adjust the division. It does not draw any relief around the children or around the separator. (The space in which the separator is called the gutter.) Often, it is useful to put each child inside a #GtkFrame with the shadow type set to %GTK_SHADOW_IN so that the gutter appears as a ridge. No separator is drawn if one of the children is missing. Each child has two options that can be set, @resize and @shrink. If @resize is true, then when the #GtkPaned is resized, that child will expand or shrink along with the paned widget. If @shrink is true, then that child can be made smaller than its requisition by the user. Setting @shrink to %FALSE allows the application to set a minimum size. If @resize is false for both children, then this is treated as if @resize is true for both children. The application can set the position of the slider as if it were set by the user, by calling gtk_paned_set_position(). # CSS nodes |[<!-- language="plain" --> paned ├── <child> ├── separator[.wide] ╰── <child> ]| GtkPaned has a main CSS node with name paned, and a subnode for the separator with name separator. The subnode gets a .wide style class when the paned is supposed to be wide. In horizontal orientation, the nodes of the children are always arranged from left to right. So :first-child will always select the leftmost child, regardless of text direction. ## Creating a paned widget with minimum sizes. |[<!-- language="C" --> GtkWidget *hpaned = gtk_paned_new (GTK_ORIENTATION_HORIZONTAL); GtkWidget *frame1 = gtk_frame_new (NULL); GtkWidget *frame2 = gtk_frame_new (NULL); gtk_frame_set_shadow_type (GTK_FRAME (frame1), GTK_SHADOW_IN); gtk_frame_set_shadow_type (GTK_FRAME (frame2), GTK_SHADOW_IN); gtk_widget_set_size_request (hpaned, 200, -1); gtk_paned_pack1 (GTK_PANED (hpaned), frame1, TRUE, FALSE); gtk_widget_set_size_request (frame1, 50, -1); gtk_paned_pack2 (GTK_PANED (hpaned), frame2, FALSE, FALSE); gtk_widget_set_size_request (frame2, 50, -1); ]| Creates a new #GtkPaned widget. a new #GtkPaned. the paned’s orientation. Adds a child to the top or left pane with default parameters. This is equivalent to `gtk_paned_pack1 (paned, child, FALSE, TRUE)`. a paned widget the child to add Adds a child to the bottom or right pane with default parameters. This is equivalent to `gtk_paned_pack2 (paned, child, TRUE, TRUE)`. a paned widget the child to add Obtains the first child of the paned widget. first child, or %NULL if it is not set. a #GtkPaned widget Obtains the second child of the paned widget. second child, or %NULL if it is not set. a #GtkPaned widget Returns the #GdkWindow of the handle. This function is useful when handling button or motion events because it enables the callback to distinguish between the window of the paned, a child and the handle. the paned’s handle window. a #GtkPaned Obtains the position of the divider between the two panes. position of the divider a #GtkPaned widget Gets the #GtkPaned:wide-handle property. %TRUE if the paned should have a wide handle a #GtkPaned Adds a child to the top or left pane. a paned widget the child to add should this child expand when the paned widget is resized. can this child be made smaller than its requisition. Adds a child to the bottom or right pane. a paned widget the child to add should this child expand when the paned widget is resized. can this child be made smaller than its requisition. Sets the position of the divider between the two panes. a #GtkPaned widget pixel position of divider, a negative value means that the position is unset. Sets the #GtkPaned:wide-handle property. a #GtkPaned the new value for the #GtkPaned:wide-handle property The largest possible value for the position property. This property is derived from the size and shrinkability of the widget's children. The smallest possible value for the position property. This property is derived from the size and shrinkability of the widget's children. Setting this property to %TRUE indicates that the paned needs to provide stronger visual separation (e.g. because it separates between two notebooks, whose tab rows would otherwise merge visually). The ::accept-position signal is a [keybinding signal][GtkBindingSignal] which gets emitted to accept the current position of the handle when moving it using key bindings. The default binding for this signal is Return or Space. The ::cancel-position signal is a [keybinding signal][GtkBindingSignal] which gets emitted to cancel moving the position of the handle using key bindings. The position of the handle will be reset to the value prior to moving it. The default binding for this signal is Escape. The ::cycle-child-focus signal is a [keybinding signal][GtkBindingSignal] which gets emitted to cycle the focus between the children of the paned. The default binding is f6. whether cycling backward or forward The ::cycle-handle-focus signal is a [keybinding signal][GtkBindingSignal] which gets emitted to cycle whether the paned should grab focus to allow the user to change position of the handle by using key bindings. The default binding for this signal is f8. whether cycling backward or forward The ::move-handle signal is a [keybinding signal][GtkBindingSignal] which gets emitted to move the handle when the user is using key bindings to move it. a #GtkScrollType The ::toggle-handle-focus is a [keybinding signal][GtkBindingSignal] which gets emitted to accept the current position of the handle and then move focus to the next widget in the focus chain. The default binding is Tab. GtkPaperSize handles paper sizes. It uses the standard called [PWG 5101.1-2002 PWG: Standard for Media Standardized Names](http://www.pwg.org/standards.html) to name the paper sizes (and to get the data for the page sizes). In addition to standard paper sizes, GtkPaperSize allows to construct custom paper sizes with arbitrary dimensions. The #GtkPaperSize object stores not only the dimensions (width and height) of a paper size and its name, it also provides default [print margins][print-margins]. Printing support has been added in GTK+ 2.10. Creates a new #GtkPaperSize object by parsing a [PWG 5101.1-2002](ftp://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn10-20020226-5101.1.pdf) paper name. If @name is %NULL, the default paper size is returned, see gtk_paper_size_get_default(). a new #GtkPaperSize, use gtk_paper_size_free() to free it a paper size name, or %NULL Creates a new #GtkPaperSize object with the given parameters. a new #GtkPaperSize object, use gtk_paper_size_free() to free it the paper name the human-readable name the paper width, in units of @unit the paper height, in units of @unit the unit for @width and @height. not %GTK_UNIT_NONE. Deserialize a paper size from an a{sv} variant in the format produced by gtk_paper_size_to_gvariant(). a new #GtkPaperSize object an a{sv} #GVariant Creates a new #GtkPaperSize object by using IPP information. If @ipp_name is not a recognized paper name, @width and @height are used to construct a custom #GtkPaperSize object. a new #GtkPaperSize, use gtk_paper_size_free() to free it an IPP paper name the paper width, in points the paper height in points Reads a paper size from the group @group_name in the key file @key_file. a new #GtkPaperSize object with the restored paper size, or %NULL if an error occurred the #GKeyFile to retrieve the papersize from the name of the group in the key file to read, or %NULL to read the first group Creates a new #GtkPaperSize object by using PPD information. If @ppd_name is not a recognized PPD paper name, @ppd_display_name, @width and @height are used to construct a custom #GtkPaperSize object. a new #GtkPaperSize, use gtk_paper_size_free() to free it a PPD paper name the corresponding human-readable name the paper width, in points the paper height in points Copies an existing #GtkPaperSize. a copy of @other a #GtkPaperSize Free the given #GtkPaperSize object. a #GtkPaperSize Gets the default bottom margin for the #GtkPaperSize. the default bottom margin a #GtkPaperSize object the unit for the return value, not %GTK_UNIT_NONE Gets the default left margin for the #GtkPaperSize. the default left margin a #GtkPaperSize object the unit for the return value, not %GTK_UNIT_NONE Gets the default right margin for the #GtkPaperSize. the default right margin a #GtkPaperSize object the unit for the return value, not %GTK_UNIT_NONE Gets the default top margin for the #GtkPaperSize. the default top margin a #GtkPaperSize object the unit for the return value, not %GTK_UNIT_NONE Gets the human-readable name of the #GtkPaperSize. the human-readable name of @size a #GtkPaperSize object Gets the paper height of the #GtkPaperSize, in units of @unit. the paper height a #GtkPaperSize object the unit for the return value, not %GTK_UNIT_NONE Gets the name of the #GtkPaperSize. the name of @size a #GtkPaperSize object Gets the PPD name of the #GtkPaperSize, which may be %NULL. the PPD name of @size a #GtkPaperSize object Gets the paper width of the #GtkPaperSize, in units of @unit. the paper width a #GtkPaperSize object the unit for the return value, not %GTK_UNIT_NONE Returns %TRUE if @size is not a standard paper size. whether @size is a custom paper size. a #GtkPaperSize object Compares two #GtkPaperSize objects. %TRUE, if @size1 and @size2 represent the same paper size a #GtkPaperSize object another #GtkPaperSize object Returns %TRUE if @size is an IPP standard paper size. whether @size is not an IPP custom paper size. a #GtkPaperSize object Changes the dimensions of a @size to @width x @height. a custom #GtkPaperSize object the new width in units of @unit the new height in units of @unit the unit for @width and @height Serialize a paper size to an a{sv} variant. a new, floating, #GVariant a #GtkPaperSize This function adds the paper size from @size to @key_file. a #GtkPaperSize the #GKeyFile to save the paper size to the group to add the settings to in @key_file Returns the name of the default paper size, which depends on the current locale. the name of the default paper size. The string is owned by GTK+ and should not be modified. Creates a list of known paper sizes. a newly allocated list of newly allocated #GtkPaperSize objects whether to include custom paper sizes as defined in the page setup dialog Priorities for path lookups. See also gtk_binding_set_add_path(). Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Widget path types. See also gtk_binding_set_add_path(). Deprecated Deprecated Deprecated These flags serve two purposes. First, the application can call gtk_places_sidebar_set_open_flags() using these flags as a bitmask. This tells the sidebar that the application is able to open folders selected from the sidebar in various ways, for example, in new tabs or in new windows in addition to the normal mode. Second, when one of these values gets passed back to the application in the #GtkPlacesSidebar::open-location signal, it means that the application should open the selected location in the normal way, in a new tab, or in a new window. The sidebar takes care of determining the desired way to open the location, based on the modifier keys that the user is pressing at the time the selection is made. If the application never calls gtk_places_sidebar_set_open_flags(), then the sidebar will only use #GTK_PLACES_OPEN_NORMAL in the #GtkPlacesSidebar::open-location signal. This is the default mode of operation. This is the default mode that #GtkPlacesSidebar uses if no other flags are specified. It indicates that the calling application should open the selected location in the normal way, for example, in the folder view beside the sidebar. When passed to gtk_places_sidebar_set_open_flags(), this indicates that the application can open folders selected from the sidebar in new tabs. This value will be passed to the #GtkPlacesSidebar::open-location signal when the user selects that a location be opened in a new tab instead of in the standard fashion. Similar to @GTK_PLACES_OPEN_NEW_TAB, but indicates that the application can open folders in new windows. #GtkPlacesSidebar is a widget that displays a list of frequently-used places in the file system: the user’s home directory, the user’s bookmarks, and volumes and drives. This widget is used as a sidebar in #GtkFileChooser and may be used by file managers and similar programs. The places sidebar displays drives and volumes, and will automatically mount or unmount them when the user selects them. Applications can hook to various signals in the places sidebar to customize its behavior. For example, they can add extra commands to the context menu of the sidebar. While bookmarks are completely in control of the user, the places sidebar also allows individual applications to provide extra shortcut folders that are unique to each application. For example, a Paint program may want to add a shortcut for a Clipart folder. You can do this with gtk_places_sidebar_add_shortcut(). To make use of the places sidebar, an application at least needs to connect to the #GtkPlacesSidebar::open-location signal. This is emitted when the user selects in the sidebar a location to open. The application should also call gtk_places_sidebar_set_location() when it changes the currently-viewed location. # CSS nodes GtkPlacesSidebar uses a single CSS node with name placessidebar and style class .sidebar. Among the children of the places sidebar, the following style classes can be used: - .sidebar-new-bookmark-row for the 'Add new bookmark' row - .sidebar-placeholder-row for a row that is a placeholder - .has-open-popup when a popup is open for a row Creates a new #GtkPlacesSidebar widget. The application should connect to at least the #GtkPlacesSidebar::open-location signal to be notified when the user makes a selection in the sidebar. a newly created #GtkPlacesSidebar Applications may want to present some folders in the places sidebar if they could be immediately useful to users. For example, a drawing program could add a “/usr/share/clipart” location when the sidebar is being used in an “Insert Clipart” dialog box. This function adds the specified @location to a special place for immutable shortcuts. The shortcuts are application-specific; they are not shared across applications, and they are not persistent. If this function is called multiple times with different locations, then they are added to the sidebar’s list in the same order as the function is called. a places sidebar location to add as an application-specific shortcut Returns the value previously set with gtk_places_sidebar_set_local_only(). %TRUE if the sidebar will only show local files. a places sidebar Gets the currently selected location in the @sidebar. This can be %NULL when nothing is selected, for example, when gtk_places_sidebar_set_location() has been called with a location that is not among the sidebar’s list of places to show. You can use this function to get the selection in the @sidebar. Also, if you connect to the #GtkPlacesSidebar::populate-popup signal, you can use this function to get the location that is being referred to during the callbacks for your menu items. a #GFile with the selected location, or %NULL if nothing is visually selected. a places sidebar This function queries the bookmarks added by the user to the places sidebar, and returns one of them. This function is used by #GtkFileChooser to implement the “Alt-1”, “Alt-2”, etc. shortcuts, which activate the cooresponding bookmark. The bookmark specified by the index @n, or %NULL if no such index exist. Note that the indices start at 0, even though the file chooser starts them with the keyboard shortcut "Alt-1". a places sidebar index of the bookmark to query Gets the open flags. the #GtkPlacesOpenFlags of @sidebar a #GtkPlacesSidebar Returns the value previously set with gtk_places_sidebar_set_show_connect_to_server() It is recommended to group this functionality with the drives and network location under the new 'Other Location' item %TRUE if the sidebar will display a “Connect to Server” item. a places sidebar Returns the value previously set with gtk_places_sidebar_set_show_desktop() %TRUE if the sidebar will display a builtin shortcut to the desktop folder. a places sidebar Returns the value previously set with gtk_places_sidebar_set_show_enter_location() %TRUE if the sidebar will display an “Enter Location” item. a places sidebar Returns the value previously set with gtk_places_sidebar_set_show_other_locations() %TRUE if the sidebar will display an “Other Locations” item. a places sidebar Returns the value previously set with gtk_places_sidebar_set_show_recent() %TRUE if the sidebar will display a builtin shortcut for recent files a places sidebar Returns the value previously set with gtk_places_sidebar_set_show_starred_location() %TRUE if the sidebar will display a Starred item. a places sidebar Returns the value previously set with gtk_places_sidebar_set_show_trash() %TRUE if the sidebar will display a “Trash” item. a places sidebar Gets the list of shortcuts. A #GSList of #GFile of the locations that have been added as application-specific shortcuts with gtk_places_sidebar_add_shortcut(). To free this list, you can use |[<!-- language="C" --> g_slist_free_full (list, (GDestroyNotify) g_object_unref); ]| a places sidebar Removes an application-specific shortcut that has been previously been inserted with gtk_places_sidebar_add_shortcut(). If the @location is not a shortcut in the sidebar, then nothing is done. a places sidebar location to remove Make the GtkPlacesSidebar show drop targets, so it can show the available drop targets and a "new bookmark" row. This improves the Drag-and-Drop experience of the user and allows applications to show all available drop targets at once. This needs to be called when the application is aware of an ongoing drag that might target the sidebar. The drop-targets-visible state will be unset automatically if the drag finishes in the GtkPlacesSidebar. You only need to unset the state when the drag ends on some other widget on your application. a places sidebar. whether to show the valid targets or not. drag context used to ask the source about the action that wants to perform, so hints are more accurate. Sets whether the @sidebar should only show local files. a places sidebar whether to show only local files Sets the location that is being shown in the widgets surrounding the @sidebar, for example, in a folder view in a file manager. In turn, the @sidebar will highlight that location if it is being shown in the list of places, or it will unhighlight everything if the @location is not among the places in the list. a places sidebar location to select, or %NULL for no current path Sets the way in which the calling application can open new locations from the places sidebar. For example, some applications only open locations “directly” into their main view, while others may support opening locations in a new notebook tab or a new window. This function is used to tell the places @sidebar about the ways in which the application can open new locations, so that the sidebar can display (or not) the “Open in new tab” and “Open in new window” menu items as appropriate. When the #GtkPlacesSidebar::open-location signal is emitted, its flags argument will be set to one of the @flags that was passed in gtk_places_sidebar_set_open_flags(). Passing 0 for @flags will cause #GTK_PLACES_OPEN_NORMAL to always be sent to callbacks for the “open-location” signal. a places sidebar Bitmask of modes in which the calling application can open locations Sets whether the @sidebar should show an item for connecting to a network server; this is off by default. An application may want to turn this on if it implements a way for the user to connect to network servers directly. If you enable this, you should connect to the #GtkPlacesSidebar::show-connect-to-server signal. It is recommended to group this functionality with the drives and network location under the new 'Other Location' item a places sidebar whether to show an item for the Connect to Server command Sets whether the @sidebar should show an item for the Desktop folder. The default value for this option is determined by the desktop environment and the user’s configuration, but this function can be used to override it on a per-application basis. a places sidebar whether to show an item for the Desktop folder Sets whether the @sidebar should show an item for entering a location; this is off by default. An application may want to turn this on if manually entering URLs is an expected user action. If you enable this, you should connect to the #GtkPlacesSidebar::show-enter-location signal. a places sidebar whether to show an item to enter a location Sets whether the @sidebar should show an item for the application to show an Other Locations view; this is off by default. When set to %TRUE, persistent devices such as hard drives are hidden, otherwise they are shown in the sidebar. An application may want to turn this on if it implements a way for the user to see and interact with drives and network servers directly. If you enable this, you should connect to the #GtkPlacesSidebar::show-other-locations signal. a places sidebar whether to show an item for the Other Locations view Sets whether the @sidebar should show an item for recent files. The default value for this option is determined by the desktop environment, but this function can be used to override it on a per-application basis. a places sidebar whether to show an item for recent files If you enable this, you should connect to the #GtkPlacesSidebar::show-starred-location signal. a places sidebar whether to show an item for Starred files Sets whether the @sidebar should show an item for the Trash location. a places sidebar whether to show an item for the Trash location If :populate-all is %TRUE, the #GtkPlacesSidebar::populate-popup signal is also emitted for popovers. The places sidebar emits this signal when it needs to ask the application to pop up a menu to ask the user for which drag action to perform. the final drag action that the sidebar should pass to the drag side of the drag-and-drop operation. Possible drag actions that need to be asked for. When the user starts a drag-and-drop operation and the sidebar needs to ask the application for which drag action to perform, then the sidebar will emit this signal. The application can evaluate the @context for customary actions, or it can check the type of the files indicated by @source_file_list against the possible actions for the destination @dest_file. The drag action to use must be the return value of the signal handler. The drag action to use, for example, #GDK_ACTION_COPY or #GDK_ACTION_MOVE, or 0 if no action is allowed here (i.e. drops are not allowed in the specified @dest_file). #GdkDragContext with information about the drag operation #GFile with the tentative location that is being hovered for a drop List of #GFile that are being dragged The places sidebar emits this signal when the user completes a drag-and-drop operation and one of the sidebar's items is the destination. This item is in the @dest_file, and the @source_file_list has the list of files that are dropped into it and which should be copied/moved/etc. based on the specified @action. Destination #GFile. #GList of #GFile that got dropped. Drop action to perform. The places sidebar emits this signal when it starts a new operation because the user clicked on some location that needs mounting. In this way the application using the #GtkPlacesSidebar can track the progress of the operation and, for example, show a notification. the #GMountOperation that is going to start. The places sidebar emits this signal when the user selects a location in it. The calling application should display the contents of that location; for example, a file manager should show a list of files in the specified location. #GFile to which the caller should switch. a single value from #GtkPlacesOpenFlags specifying how the @location should be opened. The places sidebar emits this signal when the user invokes a contextual popup on one of its items. In the signal handler, the application may add extra items to the menu as appropriate. For example, a file manager may want to add a "Properties" command to the menu. It is not necessary to store the @selected_item for each menu item; during their callbacks, the application can use gtk_places_sidebar_get_location() to get the file to which the item refers. The @selected_item argument may be %NULL in case the selection refers to a volume. In this case, @selected_volume will be non-%NULL. In this case, the calling application will have to g_object_ref() the @selected_volume and keep it around to use it in the callback. The @container and all its contents are destroyed after the user dismisses the popup. The popup is re-created (and thus, this signal is emitted) every time the user activates the contextual menu. Before 3.18, the @container always was a #GtkMenu, and you were expected to add your items as #GtkMenuItems. Since 3.18, the popup may be implemented as a #GtkPopover, in which case @container will be something else, e.g. a #GtkBox, to which you may add #GtkModelButtons or other widgets, such as #GtkEntries, #GtkSpinButtons, etc. If your application can deal with this situation, you can set #GtkPlacesSidebar::populate-all to %TRUE to request that this signal is emitted for populating popovers as well. a #GtkMenu or another #GtkContainer #GFile with the item to which the popup should refer, or %NULL in the case of a @selected_volume. #GVolume if the selected item is a volume, or %NULL if it is a file. The places sidebar emits this signal when it needs the calling application to present an way to connect directly to a network server. For example, the application may bring up a dialog box asking for a URL like "sftp://ftp.example.com". It is up to the application to create the corresponding mount by using, for example, g_file_mount_enclosing_volume(). use the #GtkPlacesSidebar::show-other-locations signal to connect to network servers. The places sidebar emits this signal when it needs the calling application to present an way to directly enter a location. For example, the application may bring up a dialog box asking for a URL like "http://http.example.com". The places sidebar emits this signal when it needs the calling application to present an error message. Most of these messages refer to mounting or unmounting media, for example, when a drive cannot be started for some reason. primary message with a summary of the error to show. secondary message with details of the error to show. The places sidebar emits this signal when it needs the calling application to present a way to show other locations e.g. drives and network access points. For example, the application may bring up a page showing persistent volumes and discovered network addresses. use the #GtkPlacesSidebar::show-other-locations-with-flags which includes the open flags in order to allow the user to specify to open in a new tab or window, in a similar way than #GtkPlacesSidebar::open-location The places sidebar emits this signal when it needs the calling application to present a way to show other locations e.g. drives and network access points. For example, the application may bring up a page showing persistent volumes and discovered network addresses. a single value from #GtkPlacesOpenFlags specifying how it should be opened. The places sidebar emits this signal when it needs the calling application to present a way to show the starred files. In GNOME, starred files are implemented by setting the nao:predefined-tag-favorite tag in the tracker database. a single value from #GtkPlacesOpenFlags specifying how the starred file should be opened. The places sidebar emits this signal when it starts a new operation because the user for example ejected some drive or unmounted a mount. In this way the application using the #GtkPlacesSidebar can track the progress of the operation and, for example, show a notification. the #GMountOperation that is going to start. Together with #GtkSocket, #GtkPlug provides the ability to embed widgets from one process into another process in a fashion that is transparent to the user. One process creates a #GtkSocket widget and passes the ID of that widget’s window to the other process, which then creates a #GtkPlug with that window ID. Any widgets contained in the #GtkPlug then will appear inside the first application’s window. The communication between a #GtkSocket and a #GtkPlug follows the [XEmbed Protocol](http://www.freedesktop.org/Standards/xembed-spec). This protocol has also been implemented in other toolkits, e.g. Qt, allowing the same level of integration when embedding a Qt widget in GTK+ or vice versa. The #GtkPlug and #GtkSocket widgets are only available when GTK+ is compiled for the X11 platform and %GDK_WINDOWING_X11 is defined. They can only be used on a #GdkX11Display. To use #GtkPlug and #GtkSocket, you need to include the `gtk/gtkx.h` header. Creates a new plug widget inside the #GtkSocket identified by @socket_id. If @socket_id is 0, the plug is left “unplugged” and can later be plugged into a #GtkSocket by gtk_socket_add_id(). the new #GtkPlug widget. the window ID of the socket, or 0. Create a new plug widget inside the #GtkSocket identified by socket_id. the new #GtkPlug widget. the #GdkDisplay on which @socket_id is displayed the XID of the socket’s window. Finish the initialization of @plug for a given #GtkSocket identified by @socket_id. This function will generally only be used by classes deriving from #GtkPlug. a #GtkPlug. the XID of the socket’s window. Finish the initialization of @plug for a given #GtkSocket identified by @socket_id which is currently displayed on @display. This function will generally only be used by classes deriving from #GtkPlug. a #GtkPlug. the #GdkDisplay associated with @socket_id’s #GtkSocket. the XID of the socket’s window. Determines whether the plug is embedded in a socket. %TRUE if the plug is embedded in a socket a #GtkPlug Gets the window ID of a #GtkPlug widget, which can then be used to embed this window inside another window, for instance with gtk_socket_add_id(). the window ID for the plug a #GtkPlug. Retrieves the socket the plug is embedded in. the window of the socket, or %NULL a #GtkPlug %TRUE if the plug is embedded in a socket. The window of the socket the plug is embedded in. Gets emitted when the plug becomes embedded in a socket. Determines how the size should be computed to achieve the one of the visibility mode for the scrollbars. The scrollbar is always visible. The view size is independent of the content. The scrollbar will appear and disappear as necessary. For example, when all of a #GtkTreeView can not be seen. The scrollbar should never appear. In this mode the content determines the size. Don't show a scrollbar, but don't force the size to follow the content. This can be used e.g. to make multiple scrolled windows share a scrollbar. Since: 3.16 GtkPopover is a bubble-like context window, primarily meant to provide context-dependent information or options. Popovers are attached to a widget, passed at construction time on gtk_popover_new(), or updated afterwards through gtk_popover_set_relative_to(), by default they will point to the whole widget area, although this behavior can be changed through gtk_popover_set_pointing_to(). The position of a popover relative to the widget it is attached to can also be changed through gtk_popover_set_position(). By default, #GtkPopover performs a GTK+ grab, in order to ensure input events get redirected to it while it is shown, and also so the popover is dismissed in the expected situations (clicks outside the popover, or the Esc key being pressed). If no such modal behavior is desired on a popover, gtk_popover_set_modal() may be called on it to tweak its behavior. ## GtkPopover as menu replacement GtkPopover is often used to replace menus. To facilitate this, it supports being populated from a #GMenuModel, using gtk_popover_new_from_model(). In addition to all the regular menu model features, this function supports rendering sections in the model in a more compact form, as a row of icon buttons instead of menu items. To use this rendering, set the ”display-hint” attribute of the section to ”horizontal-buttons” and set the icons of your items with the ”verb-icon” attribute. |[ <section> <attribute name="display-hint">horizontal-buttons</attribute> <item> <attribute name="label">Cut</attribute> <attribute name="action">app.cut</attribute> <attribute name="verb-icon">edit-cut-symbolic</attribute> </item> <item> <attribute name="label">Copy</attribute> <attribute name="action">app.copy</attribute> <attribute name="verb-icon">edit-copy-symbolic</attribute> </item> <item> <attribute name="label">Paste</attribute> <attribute name="action">app.paste</attribute> <attribute name="verb-icon">edit-paste-symbolic</attribute> </item> </section> ]| # CSS nodes GtkPopover has a single css node called popover. It always gets the .background style class and it gets the .menu style class if it is menu-like (e.g. #GtkPopoverMenu or created using gtk_popover_new_from_model(). Particular uses of GtkPopover, such as touch selection popups or magnifiers in #GtkEntry or #GtkTextView get style classes like .touch-selection or .magnifier to differentiate from plain popovers. Creates a new popover to point to @relative_to a new #GtkPopover #GtkWidget the popover is related to Creates a #GtkPopover and populates it according to @model. The popover is pointed to the @relative_to widget. The created buttons are connected to actions found in the #GtkApplicationWindow to which the popover belongs - typically by means of being attached to a widget that is contained within the #GtkApplicationWindows widget hierarchy. Actions can also be added using gtk_widget_insert_action_group() on the menus attach widget or on any of its parent widgets. the new #GtkPopover #GtkWidget the popover is related to a #GMenuModel Establishes a binding between a #GtkPopover and a #GMenuModel. The contents of @popover are removed and then refilled with menu items according to @model. When @model changes, @popover is updated. Calling this function twice on @popover with different @model will cause the first binding to be replaced with a binding to the new model. If @model is %NULL then any previous binding is undone and all children are removed. If @action_namespace is non-%NULL then the effect is as if all actions mentioned in the @model have their names prefixed with the namespace, plus a dot. For example, if the action “quit” is mentioned and @action_namespace is “app” then the effective action name is “app.quit”. This function uses #GtkActionable to define the action name and target values on the created menu items. If you want to use an action group other than “app” and “win”, or if you want to use a #GtkMenuShell outside of a #GtkApplicationWindow, then you will need to attach your own action group to the widget hierarchy using gtk_widget_insert_action_group(). As an example, if you created a group with a “quit” action and inserted it with the name “mygroup” then you would use the action name “mygroup.quit” in your #GMenuModel. a #GtkPopover the #GMenuModel to bind to or %NULL to remove binding the namespace for actions in @model Returns the constraint for placing this popover. See gtk_popover_set_constrain_to(). the constraint for placing this popover. a #GtkPopover Gets the widget that should be set as the default while the popover is shown. the default widget, or %NULL if there is none a #GtkPopover Returns whether the popover is modal, see gtk_popover_set_modal to see the implications of this. #TRUE if @popover is modal a #GtkPopover If a rectangle to point to has been set, this function will return %TRUE and fill in @rect with such rectangle, otherwise it will return %FALSE and fill in @rect with the attached widget width and height if a widget exists, otherwise it will zero-out @rect. %TRUE if a rectangle to point to was set. a #GtkPopover location to store the rectangle Returns the preferred position of @popover. The preferred position. a #GtkPopover Returns the widget @popover is currently attached to a #GtkWidget a #GtkPopover Returns whether show/hide transitions are enabled on this popover. You can show or hide the popover without transitions using gtk_widget_show() and gtk_widget_hide() while gtk_popover_popup() and gtk_popover_popdown() will use transitions. #TRUE if the show and hide transitions of the given popover are enabled, #FALSE otherwise. a #GtkPopover Pops @popover down.This is different than a gtk_widget_hide() call in that it shows the popover with a transition. If you want to hide the popover without a transition, use gtk_widget_hide(). a #GtkPopover Pops @popover up. This is different than a gtk_widget_show() call in that it shows the popover with a transition. If you want to show the popover without a transition, use gtk_widget_show(). a #GtkPopover Sets a constraint for positioning this popover. Note that not all platforms support placing popovers freely, and may already impose constraints. a #GtkPopover the new constraint Sets the widget that should be set as default widget while the popover is shown (see gtk_window_set_default()). #GtkPopover remembers the previous default widget and reestablishes it when the popover is dismissed. a #GtkPopover the new default widget, or %NULL Sets whether @popover is modal, a modal popover will grab all input within the toplevel and grab the keyboard focus on it when being displayed. Clicking outside the popover area or pressing Esc will dismiss the popover and ungrab input. a #GtkPopover #TRUE to make popover claim all input within the toplevel Sets the rectangle that @popover will point to, in the coordinate space of the widget @popover is attached to, see gtk_popover_set_relative_to(). a #GtkPopover rectangle to point to Sets the preferred position for @popover to appear. If the @popover is currently visible, it will be immediately updated. This preference will be respected where possible, although on lack of space (eg. if close to the window edges), the #GtkPopover may choose to appear on the opposite side a #GtkPopover preferred popover position Sets a new widget to be attached to @popover. If @popover is visible, the position will be updated. Note: the ownership of popovers is always given to their @relative_to widget, so if @relative_to is set to %NULL on an attached @popover, it will be detached from its previous widget, and consequently destroyed unless extra references are kept. a #GtkPopover a #GtkWidget Sets whether show/hide transitions are enabled on this popover You can show or hide the popover without transitions using gtk_widget_show() and gtk_widget_hide() while gtk_popover_popup() and gtk_popover_popdown() will use transitions. a #GtkPopover Whether transitions are enabled Sets a constraint for the popover position. Sets whether the popover is modal (so other elements in the window do not receive input while the popover is visible). Marks a specific rectangle to be pointed. Sets the preferred position of the popover. Sets the attached widget. Whether show/hide transitions are enabled for this popover. You can show or hide the popover without transitions using gtk_widget_show() and gtk_widget_hide() while gtk_popover_popup() and gtk_popover_popdown() will use transitions. This signal is emitted when the popover is dismissed either through API or user interaction. Describes constraints to positioning of popovers. More values may be added to this enumeration in the future. Don't constrain the popover position beyond what is imposed by the implementation Constrain the popover to the boundaries of the window that it is attached to GtkPopoverMenu is a subclass of #GtkPopover that treats its children like menus and allows switching between them. It is meant to be used primarily together with #GtkModelButton, but any widget can be used, such as #GtkSpinButton or #GtkScale. In this respect, GtkPopoverMenu is more flexible than popovers that are created from a #GMenuModel with gtk_popover_new_from_model(). To add a child as a submenu, set the #GtkPopoverMenu:submenu child property to the name of the submenu. To let the user open this submenu, add a #GtkModelButton whose #GtkModelButton:menu-name property is set to the name you've given to the submenu. By convention, the first child of a submenu should be a #GtkModelButton to switch back to the parent menu. Such a button should use the #GtkModelButton:inverted and #GtkModelButton:centered properties to achieve a title-like appearance and place the submenu indicator at the opposite side. To switch back to the main menu, use "main" as the menu name. # Example |[<!-- language="xml" --> <object class="GtkPopoverMenu"> <child> <object class="GtkBox"> <property name="visible">True</property> <property name="margin">10</property> <child> <object class="GtkModelButton"> <property name="visible">True</property> <property name="action-name">win.frob</property> <property name="text" translatable="yes">Frob</property> </object> </child> <child> <object class="GtkModelButton"> <property name="visible">True</property> <property name="menu-name">more</property> <property name="text" translatable="yes">More</property> </object> </child> </object> </child> <child> <object class="GtkBox"> <property name="visible">True</property> <property name="margin">10</property> <child> <object class="GtkModelButton"> <property name="visible">True</property> <property name="action-name">win.foo</property> <property name="text" translatable="yes">Foo</property> </object> </child> <child> <object class="GtkModelButton"> <property name="visible">True</property> <property name="action-name">win.bar</property> <property name="text" translatable="yes">Bar</property> </object> </child> </object> <packing> <property name="submenu">more</property> </packing> </child> </object> ]| Just like normal popovers created using gtk_popover_new_from_model, #GtkPopoverMenu instances have a single css node called "popover" and get the .menu style class. Creates a new popover menu. a new #GtkPopoverMenu Opens a submenu of the @popover. The @name must be one of the names given to the submenus of @popover with #GtkPopoverMenu:submenu, or "main" to switch back to the main menu. #GtkModelButton will open submenus automatically when the #GtkModelButton:menu-name property is set, so this function is only needed when you are using other kinds of widgets to initiate menu changes. a #GtkPopoverMenu the name of the menu to switch to Describes which edge of a widget a certain feature is positioned at, e.g. the tabs of a #GtkNotebook, the handle of a #GtkHandleBox or the label of a #GtkScale. The feature is at the left edge. The feature is at the right edge. The feature is at the top edge. The feature is at the bottom edge. A GtkPrintContext encapsulates context information that is required when drawing pages for printing, such as the cairo context and important parameters like page size and resolution. It also lets you easily create #PangoLayout and #PangoContext objects that match the font metrics of the cairo surface. GtkPrintContext objects gets passed to the #GtkPrintOperation::begin-print, #GtkPrintOperation::end-print, #GtkPrintOperation::request-page-setup and #GtkPrintOperation::draw-page signals on the #GtkPrintOperation. ## Using GtkPrintContext in a #GtkPrintOperation::draw-page callback |[<!-- language="C" --> static void draw_page (GtkPrintOperation *operation, GtkPrintContext *context, int page_nr) { cairo_t *cr; PangoLayout *layout; PangoFontDescription *desc; cr = gtk_print_context_get_cairo_context (context); // Draw a red rectangle, as wide as the paper (inside the margins) cairo_set_source_rgb (cr, 1.0, 0, 0); cairo_rectangle (cr, 0, 0, gtk_print_context_get_width (context), 50); cairo_fill (cr); // Draw some lines cairo_move_to (cr, 20, 10); cairo_line_to (cr, 40, 20); cairo_arc (cr, 60, 60, 20, 0, M_PI); cairo_line_to (cr, 80, 20); cairo_set_source_rgb (cr, 0, 0, 0); cairo_set_line_width (cr, 5); cairo_set_line_cap (cr, CAIRO_LINE_CAP_ROUND); cairo_set_line_join (cr, CAIRO_LINE_JOIN_ROUND); cairo_stroke (cr); // Draw some text layout = gtk_print_context_create_pango_layout (context); pango_layout_set_text (layout, "Hello World! Printing is easy", -1); desc = pango_font_description_from_string ("sans 28"); pango_layout_set_font_description (layout, desc); pango_font_description_free (desc); cairo_move_to (cr, 30, 20); pango_cairo_layout_path (cr, layout); // Font Outline cairo_set_source_rgb (cr, 0.93, 1.0, 0.47); cairo_set_line_width (cr, 0.5); cairo_stroke_preserve (cr); // Font Fill cairo_set_source_rgb (cr, 0, 0.0, 1.0); cairo_fill (cr); g_object_unref (layout); } ]| Printing support was added in GTK+ 2.10. Creates a new #PangoContext that can be used with the #GtkPrintContext. a new Pango context for @context a #GtkPrintContext Creates a new #PangoLayout that is suitable for use with the #GtkPrintContext. a new Pango layout for @context a #GtkPrintContext Obtains the cairo context that is associated with the #GtkPrintContext. the cairo context of @context a #GtkPrintContext Obtains the horizontal resolution of the #GtkPrintContext, in dots per inch. the horizontal resolution of @context a #GtkPrintContext Obtains the vertical resolution of the #GtkPrintContext, in dots per inch. the vertical resolution of @context a #GtkPrintContext Obtains the hardware printer margins of the #GtkPrintContext, in units. %TRUE if the hard margins were retrieved a #GtkPrintContext top hardware printer margin bottom hardware printer margin left hardware printer margin right hardware printer margin Obtains the height of the #GtkPrintContext, in pixels. the height of @context a #GtkPrintContext Obtains the #GtkPageSetup that determines the page dimensions of the #GtkPrintContext. the page setup of @context a #GtkPrintContext Returns a #PangoFontMap that is suitable for use with the #GtkPrintContext. the font map of @context a #GtkPrintContext Obtains the width of the #GtkPrintContext, in pixels. the width of @context a #GtkPrintContext Sets a new cairo context on a print context. This function is intended to be used when implementing an internal print preview, it is not needed for printing, since GTK+ itself creates a suitable cairo context in that case. a #GtkPrintContext the cairo context the horizontal resolution to use with @cr the vertical resolution to use with @cr See also gtk_print_settings_set_duplex(). No duplex. Horizontal duplex. Vertical duplex. Error codes that identify various errors that can occur while using the GTK+ printing support. An unspecified error occurred. An internal error occurred. A memory allocation failed. An error occurred while loading a page setup or paper size from a key file. Registers an error quark for #GtkPrintOperation if necessary. The error quark used for #GtkPrintOperation errors. GtkPrintOperation is the high-level, portable printing API. It looks a bit different than other GTK+ dialogs such as the #GtkFileChooser, since some platforms don’t expose enough infrastructure to implement a good print dialog. On such platforms, GtkPrintOperation uses the native print dialog. On platforms which do not provide a native print dialog, GTK+ uses its own, see #GtkPrintUnixDialog. The typical way to use the high-level printing API is to create a GtkPrintOperation object with gtk_print_operation_new() when the user selects to print. Then you set some properties on it, e.g. the page size, any #GtkPrintSettings from previous print operations, the number of pages, the current page, etc. Then you start the print operation by calling gtk_print_operation_run(). It will then show a dialog, let the user select a printer and options. When the user finished the dialog various signals will be emitted on the #GtkPrintOperation, the main one being #GtkPrintOperation::draw-page, which you are supposed to catch and render the page on the provided #GtkPrintContext using Cairo. # The high-level printing API |[<!-- language="C" --> static GtkPrintSettings *settings = NULL; static void do_print (void) { GtkPrintOperation *print; GtkPrintOperationResult res; print = gtk_print_operation_new (); if (settings != NULL) gtk_print_operation_set_print_settings (print, settings); g_signal_connect (print, "begin_print", G_CALLBACK (begin_print), NULL); g_signal_connect (print, "draw_page", G_CALLBACK (draw_page), NULL); res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, GTK_WINDOW (main_window), NULL); if (res == GTK_PRINT_OPERATION_RESULT_APPLY) { if (settings != NULL) g_object_unref (settings); settings = g_object_ref (gtk_print_operation_get_print_settings (print)); } g_object_unref (print); } ]| By default GtkPrintOperation uses an external application to do print preview. To implement a custom print preview, an application must connect to the preview signal. The functions gtk_print_operation_preview_render_page(), gtk_print_operation_preview_end_preview() and gtk_print_operation_preview_is_selected() are useful when implementing a print preview. Creates a new #GtkPrintOperation. a new #GtkPrintOperation Signal emitted after the user has finished changing print settings in the dialog, before the actual rendering starts. Signal emitted when displaying the print dialog. Signal emitted right before “begin-print” if you added a custom widget in the “create-custom-widget” handler. Signal emitted when the print operation run has finished doing everything required for printing. Signal emitted for every page that is printed. Signal emitted after all pages have been rendered. Signal emitted after the “begin-print” signal, but before the actual rendering starts. Signal emitted when a preview is requested from the native dialog. Emitted once for every page that is printed, to give the application a chance to modify the page setup. Emitted at between the various phases of the print operation. Emitted after change of selected printer. Cancels a running print operation. This function may be called from a #GtkPrintOperation::begin-print, #GtkPrintOperation::paginate or #GtkPrintOperation::draw-page signal handler to stop the currently running print operation. a #GtkPrintOperation Signalize that drawing of particular page is complete. It is called after completion of page drawing (e.g. drawing in another thread). If gtk_print_operation_set_defer_drawing() was called before, then this function has to be called by application. In another case it is called by the library itself. a #GtkPrintOperation Returns the default page setup, see gtk_print_operation_set_default_page_setup(). the default page setup a #GtkPrintOperation Gets the value of #GtkPrintOperation:embed-page-setup property. whether page setup selection combos are embedded a #GtkPrintOperation Call this when the result of a print operation is %GTK_PRINT_OPERATION_RESULT_ERROR, either as returned by gtk_print_operation_run(), or in the #GtkPrintOperation::done signal handler. The returned #GError will contain more details on what went wrong. a #GtkPrintOperation Gets the value of #GtkPrintOperation:has-selection property. whether there is a selection a #GtkPrintOperation Returns the number of pages that will be printed. Note that this value is set during print preparation phase (%GTK_PRINT_STATUS_PREPARING), so this function should never be called before the data generation phase (%GTK_PRINT_STATUS_GENERATING_DATA). You can connect to the #GtkPrintOperation::status-changed signal and call gtk_print_operation_get_n_pages_to_print() when print status is %GTK_PRINT_STATUS_GENERATING_DATA. This is typically used to track the progress of print operation. the number of pages that will be printed a #GtkPrintOperation Returns the current print settings. Note that the return value is %NULL until either gtk_print_operation_set_print_settings() or gtk_print_operation_run() have been called. the current print settings of @op. a #GtkPrintOperation Returns the status of the print operation. Also see gtk_print_operation_get_status_string(). the status of the print operation a #GtkPrintOperation Returns a string representation of the status of the print operation. The string is translated and suitable for displaying the print status e.g. in a #GtkStatusbar. Use gtk_print_operation_get_status() to obtain a status value that is suitable for programmatic use. a string representation of the status of the print operation a #GtkPrintOperation Gets the value of #GtkPrintOperation:support-selection property. whether the application supports print of selection a #GtkPrintOperation A convenience function to find out if the print operation is finished, either successfully (%GTK_PRINT_STATUS_FINISHED) or unsuccessfully (%GTK_PRINT_STATUS_FINISHED_ABORTED). Note: when you enable print status tracking the print operation can be in a non-finished state even after done has been called, as the operation status then tracks the print job status on the printer. %TRUE, if the print operation is finished. a #GtkPrintOperation Runs the print operation, by first letting the user modify print settings in the print dialog, and then print the document. Normally that this function does not return until the rendering of all pages is complete. You can connect to the #GtkPrintOperation::status-changed signal on @op to obtain some information about the progress of the print operation. Furthermore, it may use a recursive mainloop to show the print dialog. If you call gtk_print_operation_set_allow_async() or set the #GtkPrintOperation:allow-async property the operation will run asynchronously if this is supported on the platform. The #GtkPrintOperation::done signal will be emitted with the result of the operation when the it is done (i.e. when the dialog is canceled, or when the print succeeds or fails). |[<!-- language="C" --> if (settings != NULL) gtk_print_operation_set_print_settings (print, settings); if (page_setup != NULL) gtk_print_operation_set_default_page_setup (print, page_setup); g_signal_connect (print, "begin-print", G_CALLBACK (begin_print), &data); g_signal_connect (print, "draw-page", G_CALLBACK (draw_page), &data); res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, parent, &error); if (res == GTK_PRINT_OPERATION_RESULT_ERROR) { error_dialog = gtk_message_dialog_new (GTK_WINDOW (parent), GTK_DIALOG_DESTROY_WITH_PARENT, GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, "Error printing file:\n%s", error->message); g_signal_connect (error_dialog, "response", G_CALLBACK (gtk_widget_destroy), NULL); gtk_widget_show (error_dialog); g_error_free (error); } else if (res == GTK_PRINT_OPERATION_RESULT_APPLY) { if (settings != NULL) g_object_unref (settings); settings = g_object_ref (gtk_print_operation_get_print_settings (print)); } ]| Note that gtk_print_operation_run() can only be called once on a given #GtkPrintOperation. the result of the print operation. A return value of %GTK_PRINT_OPERATION_RESULT_APPLY indicates that the printing was completed successfully. In this case, it is a good idea to obtain the used print settings with gtk_print_operation_get_print_settings() and store them for reuse with the next print operation. A value of %GTK_PRINT_OPERATION_RESULT_IN_PROGRESS means the operation is running asynchronously, and will emit the #GtkPrintOperation::done signal when done. a #GtkPrintOperation the action to start Transient parent of the dialog Sets whether the gtk_print_operation_run() may return before the print operation is completed. Note that some platforms may not allow asynchronous operation. a #GtkPrintOperation %TRUE to allow asynchronous operation Sets the current page. If this is called before gtk_print_operation_run(), the user will be able to select to print only the current page. Note that this only makes sense for pre-paginated documents. a #GtkPrintOperation the current page, 0-based Sets the label for the tab holding custom widgets. a #GtkPrintOperation the label to use, or %NULL to use the default label Makes @default_page_setup the default page setup for @op. This page setup will be used by gtk_print_operation_run(), but it can be overridden on a per-page basis by connecting to the #GtkPrintOperation::request-page-setup signal. a #GtkPrintOperation a #GtkPageSetup, or %NULL Sets up the #GtkPrintOperation to wait for calling of gtk_print_operation_draw_page_finish() from application. It can be used for drawing page in another thread. This function must be called in the callback of “draw-page” signal. a #GtkPrintOperation Embed page size combo box and orientation combo box into page setup page. Selected page setup is stored as default page setup in #GtkPrintOperation. a #GtkPrintOperation %TRUE to embed page setup selection in the #GtkPrintUnixDialog Sets up the #GtkPrintOperation to generate a file instead of showing the print dialog. The indended use of this function is for implementing “Export to PDF” actions. Currently, PDF is the only supported format. “Print to PDF” support is independent of this and is done by letting the user pick the “Print to PDF” item from the list of printers in the print dialog. a #GtkPrintOperation the filename for the exported file Sets whether there is a selection to print. Application has to set number of pages to which the selection will draw by gtk_print_operation_set_n_pages() in a callback of #GtkPrintOperation::begin-print. a #GtkPrintOperation %TRUE indicates that a selection exists Sets the name of the print job. The name is used to identify the job (e.g. in monitoring applications like eggcups). If you don’t set a job name, GTK+ picks a default one by numbering successive print jobs. a #GtkPrintOperation a string that identifies the print job Sets the number of pages in the document. This must be set to a positive number before the rendering starts. It may be set in a #GtkPrintOperation::begin-print signal hander. Note that the page numbers passed to the #GtkPrintOperation::request-page-setup and #GtkPrintOperation::draw-page signals are 0-based, i.e. if the user chooses to print all pages, the last ::draw-page signal will be for page @n_pages - 1. a #GtkPrintOperation the number of pages Sets the print settings for @op. This is typically used to re-establish print settings from a previous print operation, see gtk_print_operation_run(). a #GtkPrintOperation #GtkPrintSettings If @show_progress is %TRUE, the print operation will show a progress dialog during the print operation. a #GtkPrintOperation %TRUE to show a progress dialog Sets whether selection is supported by #GtkPrintOperation. a #GtkPrintOperation %TRUE to support selection If track_status is %TRUE, the print operation will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like “out of paper” issues, and when the print job actually reaches the printer. This function is often implemented using some form of polling, so it should not be enabled unless needed. a #GtkPrintOperation %TRUE to track status after printing Sets up the transformation for the cairo context obtained from #GtkPrintContext in such a way that distances are measured in units of @unit. a #GtkPrintOperation the unit to use If @full_page is %TRUE, the transformation for the cairo context obtained from #GtkPrintContext puts the origin at the top left corner of the page (which may not be the top left corner of the sheet, depending on page orientation and the number of pages per sheet). Otherwise, the origin is at the top left corner of the imageable area (i.e. inside the margins). a #GtkPrintOperation %TRUE to set up the #GtkPrintContext for the full page Determines whether the print operation may run asynchronously or not. Some systems don't support asynchronous printing, but those that do will return %GTK_PRINT_OPERATION_RESULT_IN_PROGRESS as the status, and emit the #GtkPrintOperation::done signal when the operation is actually done. The Windows port does not support asynchronous operation at all (this is unlikely to change). On other platforms, all actions except for %GTK_PRINT_OPERATION_ACTION_EXPORT support asynchronous operation. The current page in the document. If this is set before gtk_print_operation_run(), the user will be able to select to print only the current page. Note that this only makes sense for pre-paginated documents. Used as the label of the tab containing custom widgets. Note that this property may be ignored on some platforms. If this is %NULL, GTK+ uses a default label. The #GtkPageSetup used by default. This page setup will be used by gtk_print_operation_run(), but it can be overridden on a per-page basis by connecting to the #GtkPrintOperation::request-page-setup signal. If %TRUE, page size combo box and orientation combo box are embedded into page setup page. The name of a file to generate instead of showing the print dialog. Currently, PDF is the only supported format. The intended use of this property is for implementing “Export to PDF” actions. “Print to PDF” support is independent of this and is done by letting the user pick the “Print to PDF” item from the list of printers in the print dialog. Determines whether there is a selection in your application. This can allow your application to print the selection. This is typically used to make a "Selection" button sensitive. A string used to identify the job (e.g. in monitoring applications like eggcups). If you don't set a job name, GTK+ picks a default one by numbering successive print jobs. The number of pages in the document. This must be set to a positive number before the rendering starts. It may be set in a #GtkPrintOperation::begin-print signal hander. Note that the page numbers passed to the #GtkPrintOperation::request-page-setup and #GtkPrintOperation::draw-page signals are 0-based, i.e. if the user chooses to print all pages, the last ::draw-page signal will be for page @n_pages - 1. The number of pages that will be printed. Note that this value is set during print preparation phase (%GTK_PRINT_STATUS_PREPARING), so this value should never be get before the data generation phase (%GTK_PRINT_STATUS_GENERATING_DATA). You can connect to the #GtkPrintOperation::status-changed signal and call gtk_print_operation_get_n_pages_to_print() when print status is %GTK_PRINT_STATUS_GENERATING_DATA. This is typically used to track the progress of print operation. The #GtkPrintSettings used for initializing the dialog. Setting this property is typically used to re-establish print settings from a previous print operation, see gtk_print_operation_run(). Determines whether to show a progress dialog during the print operation. The status of the print operation. A string representation of the status of the print operation. The string is translated and suitable for displaying the print status e.g. in a #GtkStatusbar. See the #GtkPrintOperation:status property for a status value that is suitable for programmatic use. If %TRUE, the print operation will support print of selection. This allows the print dialog to show a "Selection" button. If %TRUE, the print operation will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like “out of paper” issues, and when the print job actually reaches the printer. However, this is often implemented using polling, and should not be enabled unless needed. The transformation for the cairo context obtained from #GtkPrintContext is set up in such a way that distances are measured in units of @unit. If %TRUE, the transformation for the cairo context obtained from #GtkPrintContext puts the origin at the top left corner of the page (which may not be the top left corner of the sheet, depending on page orientation and the number of pages per sheet). Otherwise, the origin is at the top left corner of the imageable area (i.e. inside the margins). Emitted after the user has finished changing print settings in the dialog, before the actual rendering starts. A typical use for ::begin-print is to use the parameters from the #GtkPrintContext and paginate the document accordingly, and then set the number of pages with gtk_print_operation_set_n_pages(). the #GtkPrintContext for the current operation Emitted when displaying the print dialog. If you return a widget in a handler for this signal it will be added to a custom tab in the print dialog. You typically return a container widget with multiple widgets in it. The print dialog owns the returned widget, and its lifetime is not controlled by the application. However, the widget is guaranteed to stay around until the #GtkPrintOperation::custom-widget-apply signal is emitted on the operation. Then you can read out any information you need from the widgets. A custom widget that gets embedded in the print dialog, or %NULL Emitted right before #GtkPrintOperation::begin-print if you added a custom widget in the #GtkPrintOperation::create-custom-widget handler. When you get this signal you should read the information from the custom widgets, as the widgets are not guaraneed to be around at a later time. the custom widget added in create-custom-widget Emitted when the print operation run has finished doing everything required for printing. @result gives you information about what happened during the run. If @result is %GTK_PRINT_OPERATION_RESULT_ERROR then you can call gtk_print_operation_get_error() for more information. If you enabled print status tracking then gtk_print_operation_is_finished() may still return %FALSE after #GtkPrintOperation::done was emitted. the result of the print operation Emitted for every page that is printed. The signal handler must render the @page_nr's page onto the cairo context obtained from @context using gtk_print_context_get_cairo_context(). |[<!-- language="C" --> static void draw_page (GtkPrintOperation *operation, GtkPrintContext *context, gint page_nr, gpointer user_data) { cairo_t *cr; PangoLayout *layout; gdouble width, text_height; gint layout_height; PangoFontDescription *desc; cr = gtk_print_context_get_cairo_context (context); width = gtk_print_context_get_width (context); cairo_rectangle (cr, 0, 0, width, HEADER_HEIGHT); cairo_set_source_rgb (cr, 0.8, 0.8, 0.8); cairo_fill (cr); layout = gtk_print_context_create_pango_layout (context); desc = pango_font_description_from_string ("sans 14"); pango_layout_set_font_description (layout, desc); pango_font_description_free (desc); pango_layout_set_text (layout, "some text", -1); pango_layout_set_width (layout, width * PANGO_SCALE); pango_layout_set_alignment (layout, PANGO_ALIGN_CENTER); pango_layout_get_size (layout, NULL, &layout_height); text_height = (gdouble)layout_height / PANGO_SCALE; cairo_move_to (cr, width / 2, (HEADER_HEIGHT - text_height) / 2); pango_cairo_show_layout (cr, layout); g_object_unref (layout); } ]| Use gtk_print_operation_set_use_full_page() and gtk_print_operation_set_unit() before starting the print operation to set up the transformation of the cairo context according to your needs. the #GtkPrintContext for the current operation the number of the currently printed page (0-based) Emitted after all pages have been rendered. A handler for this signal can clean up any resources that have been allocated in the #GtkPrintOperation::begin-print handler. the #GtkPrintContext for the current operation Emitted after the #GtkPrintOperation::begin-print signal, but before the actual rendering starts. It keeps getting emitted until a connected signal handler returns %TRUE. The ::paginate signal is intended to be used for paginating a document in small chunks, to avoid blocking the user interface for a long time. The signal handler should update the number of pages using gtk_print_operation_set_n_pages(), and return %TRUE if the document has been completely paginated. If you don't need to do pagination in chunks, you can simply do it all in the ::begin-print handler, and set the number of pages from there. %TRUE if pagination is complete the #GtkPrintContext for the current operation Gets emitted when a preview is requested from the native dialog. The default handler for this signal uses an external viewer application to preview. To implement a custom print preview, an application must return %TRUE from its handler for this signal. In order to use the provided @context for the preview implementation, it must be given a suitable cairo context with gtk_print_context_set_cairo_context(). The custom preview implementation can use gtk_print_operation_preview_is_selected() and gtk_print_operation_preview_render_page() to find pages which are selected for print and render them. The preview must be finished by calling gtk_print_operation_preview_end_preview() (typically in response to the user clicking a close button). %TRUE if the listener wants to take over control of the preview the #GtkPrintOperationPreview for the current operation the #GtkPrintContext that will be used the #GtkWindow to use as window parent, or %NULL Emitted once for every page that is printed, to give the application a chance to modify the page setup. Any changes done to @setup will be in force only for printing this page. the #GtkPrintContext for the current operation the number of the currently printed page (0-based) the #GtkPageSetup Emitted at between the various phases of the print operation. See #GtkPrintStatus for the phases that are being discriminated. Use gtk_print_operation_get_status() to find out the current status. Emitted after change of selected printer. The actual page setup and print settings are passed to the custom widget, which can actualize itself according to this change. the custom widget added in create-custom-widget actual page setup actual print settings The @action parameter to gtk_print_operation_run() determines what action the print operation should perform. Show the print dialog. Start to print without showing the print dialog, based on the current print settings. Show the print preview. Export to a file. This requires the export-filename property to be set. The parent class. Signal emitted when the print operation run has finished doing everything required for printing. Signal emitted after the user has finished changing print settings in the dialog, before the actual rendering starts. Signal emitted after the “begin-print” signal, but before the actual rendering starts. Emitted once for every page that is printed, to give the application a chance to modify the page setup. Signal emitted for every page that is printed. Signal emitted after all pages have been rendered. Emitted at between the various phases of the print operation. Signal emitted when displaying the print dialog. Signal emitted right before “begin-print” if you added a custom widget in the “create-custom-widget” handler. Signal emitted when a preview is requested from the native dialog. Emitted after change of selected printer. Ends a preview. This function must be called to finish a custom print preview. a #GtkPrintOperationPreview Returns whether the given page is included in the set of pages that have been selected for printing. %TRUE if the page has been selected for printing a #GtkPrintOperationPreview a page number Renders a page to the preview, using the print context that was passed to the #GtkPrintOperation::preview handler together with @preview. A custom iprint preview should use this function in its ::expose handler to render the currently selected page. Note that this function requires a suitable cairo context to be associated with the print context. a #GtkPrintOperationPreview the page to render Ends a preview. This function must be called to finish a custom print preview. a #GtkPrintOperationPreview Returns whether the given page is included in the set of pages that have been selected for printing. %TRUE if the page has been selected for printing a #GtkPrintOperationPreview a page number Renders a page to the preview, using the print context that was passed to the #GtkPrintOperation::preview handler together with @preview. A custom iprint preview should use this function in its ::expose handler to render the currently selected page. Note that this function requires a suitable cairo context to be associated with the print context. a #GtkPrintOperationPreview the page to render The ::got-page-size signal is emitted once for each page that gets rendered to the preview. A handler for this signal should update the @context according to @page_setup and set up a suitable cairo context, using gtk_print_context_set_cairo_context(). the current #GtkPrintContext the #GtkPageSetup for the current page The ::ready signal gets emitted once per preview operation, before the first page is rendered. A handler for this signal can be used for setup tasks. the current #GtkPrintContext a #GtkPrintOperationPreview the page to render %TRUE if the page has been selected for printing a #GtkPrintOperationPreview a page number a #GtkPrintOperationPreview A value of this type is returned by gtk_print_operation_run(). An error has occurred. The print settings should be stored. The print operation has been canceled, the print settings should not be stored. The print operation is not complete yet. This value will only be returned when running asynchronously. See also gtk_print_job_set_pages() All pages. Current page. Range of pages. Selected pages. See also gtk_print_settings_set_quality(). Low quality. Normal quality. High quality. Draft quality. A GtkPrintSettings object represents the settings of a print dialog in a system-independent way. The main use for this object is that once you’ve printed you can get a settings object that represents the settings the user chose, and the next time you print you can pass that object in so that the user doesn’t have to re-set all his settings. Its also possible to enumerate the settings so that you can easily save the settings for the next time your app runs, or even store them in a document. The predefined keys try to use shared values as much as possible so that moving such a document between systems still works. Printing support was added in GTK+ 2.10. Creates a new #GtkPrintSettings object. a new #GtkPrintSettings object Reads the print settings from @file_name. Returns a new #GtkPrintSettings object with the restored settings, or %NULL if an error occurred. If the file could not be loaded then error is set to either a #GFileError or #GKeyFileError. See gtk_print_settings_to_file(). the restored #GtkPrintSettings the filename to read the settings from Deserialize print settings from an a{sv} variant in the format produced by gtk_print_settings_to_gvariant(). a new #GtkPrintSettings object an a{sv} #GVariant Reads the print settings from the group @group_name in @key_file. Returns a new #GtkPrintSettings object with the restored settings, or %NULL if an error occurred. If the file could not be loaded then error is set to either a #GFileError or #GKeyFileError. the restored #GtkPrintSettings the #GKeyFile to retrieve the settings from the name of the group to use, or %NULL to use the default “Print Settings” Copies a #GtkPrintSettings object. a newly allocated copy of @other a #GtkPrintSettings Calls @func for each key-value pair of @settings. a #GtkPrintSettings the function to call user data for @func Looks up the string value associated with @key. the string value for @key a #GtkPrintSettings a key Returns the boolean represented by the value that is associated with @key. The string “true” represents %TRUE, any other string %FALSE. %TRUE, if @key maps to a true value. a #GtkPrintSettings a key Gets the value of %GTK_PRINT_SETTINGS_COLLATE. whether to collate the printed pages a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE. the default source a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_DITHER. the dithering that is used a #GtkPrintSettings Returns the double value associated with @key, or 0. the double value of @key a #GtkPrintSettings a key Returns the floating point number represented by the value that is associated with @key, or @default_val if the value does not represent a floating point number. Floating point numbers are parsed with g_ascii_strtod(). the floating point number associated with @key a #GtkPrintSettings a key the default value Gets the value of %GTK_PRINT_SETTINGS_DUPLEX. whether to print the output in duplex. a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_FINISHINGS. the finishings a #GtkPrintSettings Returns the integer value of @key, or 0. the integer value of @key a #GtkPrintSettings a key Returns the value of @key, interpreted as an integer, or the default value. the integer value of @key a #GtkPrintSettings a key the default value Returns the value associated with @key, interpreted as a length. The returned value is converted to @units. the length value of @key, converted to @unit a #GtkPrintSettings a key the unit of the return value Gets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE. The set of media types is defined in PWG 5101.1-2002 PWG. the media type a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_N_COPIES. the number of copies to print a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP. the number of pages per sheet a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT. layout of page in number-up mode a #GtkPrintSettings Get the value of %GTK_PRINT_SETTINGS_ORIENTATION, converted to a #GtkPageOrientation. the orientation a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN. the output bin a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES. an array of #GtkPageRanges. Use g_free() to free the array when it is no longer needed. a #GtkPrintSettings return location for the length of the returned array Gets the value of %GTK_PRINT_SETTINGS_PAGE_SET. the set of pages to print a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT, converted to @unit. the paper height, in units of @unit a #GtkPrintSettings the unit for the return value Gets the value of %GTK_PRINT_SETTINGS_PAPER_FORMAT, converted to a #GtkPaperSize. the paper size a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH, converted to @unit. the paper width, in units of @unit a #GtkPrintSettings the unit for the return value Gets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES. which pages to print a #GtkPrintSettings Convenience function to obtain the value of %GTK_PRINT_SETTINGS_PRINTER. the printer name a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI. the resolution in lpi (lines per inch) a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_QUALITY. the print quality a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION. the resolution in dpi a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_X. the horizontal resolution in dpi a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_Y. the vertical resolution in dpi a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_REVERSE. whether to reverse the order of the printed pages a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_SCALE. the scale in percent a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_USE_COLOR. whether to use color a #GtkPrintSettings Returns %TRUE, if a value is associated with @key. %TRUE, if @key has a value a #GtkPrintSettings a key Reads the print settings from @file_name. If the file could not be loaded then error is set to either a #GFileError or #GKeyFileError. See gtk_print_settings_to_file(). %TRUE on success a #GtkPrintSettings the filename to read the settings from Reads the print settings from the group @group_name in @key_file. If the file could not be loaded then error is set to either a #GFileError or #GKeyFileError. %TRUE on success a #GtkPrintSettings the #GKeyFile to retrieve the settings from the name of the group to use, or %NULL to use the default “Print Settings” Associates @value with @key. a #GtkPrintSettings a key a string value, or %NULL Sets @key to a boolean value. a #GtkPrintSettings a key a boolean Sets the value of %GTK_PRINT_SETTINGS_COLLATE. a #GtkPrintSettings whether to collate the output Sets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE. a #GtkPrintSettings the default source Sets the value of %GTK_PRINT_SETTINGS_DITHER. a #GtkPrintSettings the dithering that is used Sets @key to a double value. a #GtkPrintSettings a key a double value Sets the value of %GTK_PRINT_SETTINGS_DUPLEX. a #GtkPrintSettings a #GtkPrintDuplex value Sets the value of %GTK_PRINT_SETTINGS_FINISHINGS. a #GtkPrintSettings the finishings Sets @key to an integer value. a #GtkPrintSettings a key an integer Associates a length in units of @unit with @key. a #GtkPrintSettings a key a length the unit of @length Sets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE. The set of media types is defined in PWG 5101.1-2002 PWG. a #GtkPrintSettings the media type Sets the value of %GTK_PRINT_SETTINGS_N_COPIES. a #GtkPrintSettings the number of copies Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP. a #GtkPrintSettings the number of pages per sheet Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT. a #GtkPrintSettings a #GtkNumberUpLayout value Sets the value of %GTK_PRINT_SETTINGS_ORIENTATION. a #GtkPrintSettings a page orientation Sets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN. a #GtkPrintSettings the output bin Sets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES. a #GtkPrintSettings an array of #GtkPageRanges the length of @page_ranges Sets the value of %GTK_PRINT_SETTINGS_PAGE_SET. a #GtkPrintSettings a #GtkPageSet value Sets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT. a #GtkPrintSettings the paper height the units of @height Sets the value of %GTK_PRINT_SETTINGS_PAPER_FORMAT, %GTK_PRINT_SETTINGS_PAPER_WIDTH and %GTK_PRINT_SETTINGS_PAPER_HEIGHT. a #GtkPrintSettings a paper size Sets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH. a #GtkPrintSettings the paper width the units of @width Sets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES. a #GtkPrintSettings a #GtkPrintPages value Convenience function to set %GTK_PRINT_SETTINGS_PRINTER to @printer. a #GtkPrintSettings the printer name Sets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI. a #GtkPrintSettings the resolution in lpi (lines per inch) Sets the value of %GTK_PRINT_SETTINGS_QUALITY. a #GtkPrintSettings a #GtkPrintQuality value Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION, %GTK_PRINT_SETTINGS_RESOLUTION_X and %GTK_PRINT_SETTINGS_RESOLUTION_Y. a #GtkPrintSettings the resolution in dpi Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION, %GTK_PRINT_SETTINGS_RESOLUTION_X and %GTK_PRINT_SETTINGS_RESOLUTION_Y. a #GtkPrintSettings the horizontal resolution in dpi the vertical resolution in dpi Sets the value of %GTK_PRINT_SETTINGS_REVERSE. a #GtkPrintSettings whether to reverse the output Sets the value of %GTK_PRINT_SETTINGS_SCALE. a #GtkPrintSettings the scale in percent Sets the value of %GTK_PRINT_SETTINGS_USE_COLOR. a #GtkPrintSettings whether to use color This function saves the print settings from @settings to @file_name. If the file could not be loaded then error is set to either a #GFileError or #GKeyFileError. %TRUE on success a #GtkPrintSettings the file to save to Serialize print settings to an a{sv} variant. a new, floating, #GVariant a #GtkPrintSettings This function adds the print settings from @settings to @key_file. a #GtkPrintSettings the #GKeyFile to save the print settings to the group to add the settings to in @key_file, or %NULL to use the default “Print Settings” Removes any value associated with @key. This has the same effect as setting the value to %NULL. a #GtkPrintSettings a key The status gives a rough indication of the completion of a running print operation. The printing has not started yet; this status is set initially, and while the print dialog is shown. This status is set while the begin-print signal is emitted and during pagination. This status is set while the pages are being rendered. The print job is being sent off to the printer. The print job has been sent to the printer, but is not printed for some reason, e.g. the printer may be stopped. Some problem has occurred during printing, e.g. a paper jam. The printer is processing the print job. The printing has been completed successfully. The printing has been aborted. The #GtkProgressBar is typically used to display the progress of a long running operation. It provides a visual clue that processing is underway. The GtkProgressBar can be used in two different modes: percentage mode and activity mode. When an application can determine how much work needs to take place (e.g. read a fixed number of bytes from a file) and can monitor its progress, it can use the GtkProgressBar in percentage mode and the user sees a growing bar indicating the percentage of the work that has been completed. In this mode, the application is required to call gtk_progress_bar_set_fraction() periodically to update the progress bar. When an application has no accurate way of knowing the amount of work to do, it can use the #GtkProgressBar in activity mode, which shows activity by a block moving back and forth within the progress area. In this mode, the application is required to call gtk_progress_bar_pulse() periodically to update the progress bar. There is quite a bit of flexibility provided to control the appearance of the #GtkProgressBar. Functions are provided to control the orientation of the bar, optional text can be displayed along with the bar, and the step size used in activity mode can be set. # CSS nodes |[<!-- language="plain" --> progressbar[.osd] ├── [text] ╰── trough[.empty][.full] ╰── progress[.pulse] ]| GtkProgressBar has a main CSS node with name progressbar and subnodes with names text and trough, of which the latter has a subnode named progress. The text subnode is only present if text is shown. The progress subnode has the style class .pulse when in activity mode. It gets the style classes .left, .right, .top or .bottom added when the progress 'touches' the corresponding end of the GtkProgressBar. The .osd class on the progressbar node is for use in overlays like the one Epiphany has for page loading progress. Creates a new #GtkProgressBar. a #GtkProgressBar. Returns the ellipsizing position of the progress bar. See gtk_progress_bar_set_ellipsize(). #PangoEllipsizeMode a #GtkProgressBar Returns the current fraction of the task that’s been completed. a fraction from 0.0 to 1.0 a #GtkProgressBar Gets the value set by gtk_progress_bar_set_inverted(). %TRUE if the progress bar is inverted a #GtkProgressBar Retrieves the pulse step set with gtk_progress_bar_set_pulse_step(). a fraction from 0.0 to 1.0 a #GtkProgressBar Gets the value of the #GtkProgressBar:show-text property. See gtk_progress_bar_set_show_text(). %TRUE if text is shown in the progress bar a #GtkProgressBar Retrieves the text that is displayed with the progress bar, if any, otherwise %NULL. The return value is a reference to the text, not a copy of it, so will become invalid if you change the text in the progress bar. text, or %NULL; this string is owned by the widget and should not be modified or freed. a #GtkProgressBar Indicates that some progress has been made, but you don’t know how much. Causes the progress bar to enter “activity mode,” where a block bounces back and forth. Each call to gtk_progress_bar_pulse() causes the block to move by a little bit (the amount of movement per pulse is determined by gtk_progress_bar_set_pulse_step()). a #GtkProgressBar Sets the mode used to ellipsize (add an ellipsis: "...") the text if there is not enough space to render the entire string. a #GtkProgressBar a #PangoEllipsizeMode Causes the progress bar to “fill in” the given fraction of the bar. The fraction should be between 0.0 and 1.0, inclusive. a #GtkProgressBar fraction of the task that’s been completed Progress bars normally grow from top to bottom or left to right. Inverted progress bars grow in the opposite direction. a #GtkProgressBar %TRUE to invert the progress bar Sets the fraction of total progress bar length to move the bouncing block for each call to gtk_progress_bar_pulse(). a #GtkProgressBar fraction between 0.0 and 1.0 Sets whether the progress bar will show text next to the bar. The shown text is either the value of the #GtkProgressBar:text property or, if that is %NULL, the #GtkProgressBar:fraction value, as a percentage. To make a progress bar that is styled and sized suitably for containing text (even if the actual text is blank), set #GtkProgressBar:show-text to %TRUE and #GtkProgressBar:text to the empty string (not %NULL). a #GtkProgressBar whether to show text Causes the given @text to appear next to the progress bar. If @text is %NULL and #GtkProgressBar:show-text is %TRUE, the current value of #GtkProgressBar:fraction will be displayed as a percentage. If @text is non-%NULL and #GtkProgressBar:show-text is %TRUE, the text will be displayed. In this case, it will not display the progress percentage. If @text is the empty string, the progress bar will still be styled and sized suitably for containing text, as long as #GtkProgressBar:show-text is %TRUE. a #GtkProgressBar a UTF-8 string, or %NULL The preferred place to ellipsize the string, if the progress bar does not have enough room to display the entire string, specified as a #PangoEllipsizeMode. Note that setting this property to a value other than %PANGO_ELLIPSIZE_NONE has the side-effect that the progress bar requests only enough space to display the ellipsis ("..."). Another means to set a progress bar's width is gtk_widget_set_size_request(). Sets whether the progress bar will show a text in addition to the bar itself. The shown text is either the value of the #GtkProgressBar:text property or, if that is %NULL, the #GtkProgressBar:fraction value, as a percentage. To make a progress bar that is styled and sized suitably for showing text (even if the actual text is blank), set #GtkProgressBar:show-text to %TRUE and #GtkProgressBar:text to the empty string (not %NULL). Describes the stage at which events are fed into a #GtkEventController. Events are not delivered automatically. Those can be manually fed through gtk_event_controller_handle_event(). This should only be used when full control about when, or whether the controller handles the event is needed. Events are delivered in the capture phase. The capture phase happens before the bubble phase, runs from the toplevel down to the event widget. This option should only be used on containers that might possibly handle events before their children do. Events are delivered in the bubble phase. The bubble phase happens after the capture phase, and before the default handlers are run. This phase runs from the event widget, up to the toplevel. Events are delivered in the default widget event handlers, note that widget implementations must chain up on button, motion, touch and grab broken handlers for controllers in this phase to be run. A #GtkRadioAction is similar to #GtkRadioMenuItem. A number of radio actions can be linked together so that only one may be active at any one time. Creates a new #GtkRadioAction object. To add the action to a #GtkActionGroup and set the accelerator for the action, call gtk_action_group_add_action_with_accel(). a new #GtkRadioAction A unique name for the action The label displayed in menu items and on buttons, or %NULL A tooltip for this action, or %NULL The stock icon to display in widgets representing this action, or %NULL The value which gtk_radio_action_get_current_value() should return if this action is selected. Obtains the value property of the currently active member of the group to which @action belongs. The value of the currently active group member a #GtkRadioAction Returns the list representing the radio group for this object. Note that the returned list is only valid until the next change to the group. A common way to set up a group of radio group is the following: |[<!-- language="C" --> GSList *group = NULL; GtkRadioAction *action; while ( ...more actions to add... /) { action = gtk_radio_action_new (...); gtk_radio_action_set_group (action, group); group = gtk_radio_action_get_group (action); } ]| the list representing the radio group for this object the action object Joins a radio action object to the group of another radio action object. Use this in language bindings instead of the gtk_radio_action_get_group() and gtk_radio_action_set_group() methods A common way to set up a group of radio actions is the following: |[<!-- language="C" --> GtkRadioAction *action; GtkRadioAction *last_action; while ( ...more actions to add... /) { action = gtk_radio_action_new (...); gtk_radio_action_join_group (action, last_action); last_action = action; } ]| the action object a radio action object whos group we are joining, or %NULL to remove the radio action from its group Sets the currently active group member to the member with value property @current_value. a #GtkRadioAction the new value Sets the radio group for the radio action object. the action object a list representing a radio group, or %NULL The value property of the currently active member of the group to which this action belongs. Sets a new group for a radio action. The value is an arbitrary integer which can be used as a convenient way to determine which action in the group is currently active in an ::activate or ::changed signal handler. See gtk_radio_action_get_current_value() and #GtkRadioActionEntry for convenient ways to get and set this property. The ::changed signal is emitted on every member of a radio group when the active member is changed. The signal gets emitted after the ::activate signals for the previous and current active members. the member of @action's group which has just been activated #GtkRadioActionEntry structs are used with gtk_action_group_add_radio_actions() to construct groups of radio actions. The name of the action. The stock id for the action, or the name of an icon from the icon theme. The label for the action. This field should typically be marked for translation, see gtk_action_group_set_translation_domain(). The accelerator for the action, in the format understood by gtk_accelerator_parse(). The tooltip for the action. This field should typically be marked for translation, see gtk_action_group_set_translation_domain(). The value to set on the radio action. See gtk_radio_action_get_current_value(). A single radio button performs the same basic function as a #GtkCheckButton, as its position in the object hierarchy reflects. It is only when multiple radio buttons are grouped together that they become a different user interface component in their own right. Every radio button is a member of some group of radio buttons. When one is selected, all other radio buttons in the same group are deselected. A #GtkRadioButton is one way of giving the user a choice from many options. Radio button widgets are created with gtk_radio_button_new(), passing %NULL as the argument if this is the first radio button in a group. In subsequent calls, the group you wish to add this button to should be passed as an argument. Optionally, gtk_radio_button_new_with_label() can be used if you want a text label on the radio button. Alternatively, when adding widgets to an existing group of radio buttons, use gtk_radio_button_new_from_widget() with a #GtkRadioButton that already has a group assigned to it. The convenience function gtk_radio_button_new_with_label_from_widget() is also provided. To retrieve the group a #GtkRadioButton is assigned to, use gtk_radio_button_get_group(). To remove a #GtkRadioButton from one group and make it part of a new one, use gtk_radio_button_set_group(). The group list does not need to be freed, as each #GtkRadioButton will remove itself and its list item when it is destroyed. # CSS nodes |[<!-- language="plain" --> radiobutton ├── radio ╰── <child> ]| A GtkRadioButton with indicator (see gtk_toggle_button_set_mode()) has a main CSS node with name radiobutton and a subnode with name radio. |[<!-- language="plain" --> button.radio ├── radio ╰── <child> ]| A GtkRadioButton without indicator changes the name of its main node to button and adds a .radio style class to it. The subnode is invisible in this case. ## How to create a group of two radio buttons. |[<!-- language="C" --> void create_radio_buttons (void) { GtkWidget *window, *radio1, *radio2, *box, *entry; window = gtk_window_new (GTK_WINDOW_TOPLEVEL); box = gtk_box_new (GTK_ORIENTATION_VERTICAL, 2); gtk_box_set_homogeneous (GTK_BOX (box), TRUE); // Create a radio button with a GtkEntry widget radio1 = gtk_radio_button_new (NULL); entry = gtk_entry_new (); gtk_container_add (GTK_CONTAINER (radio1), entry); // Create a radio button with a label radio2 = gtk_radio_button_new_with_label_from_widget (GTK_RADIO_BUTTON (radio1), "I’m the second radio button."); // Pack them into a box, then show all the widgets gtk_box_pack_start (GTK_BOX (box), radio1); gtk_box_pack_start (GTK_BOX (box), radio2); gtk_container_add (GTK_CONTAINER (window), box); gtk_widget_show_all (window); return; } ]| When an unselected button in the group is clicked the clicked button receives the #GtkToggleButton::toggled signal, as does the previously selected button. Inside the #GtkToggleButton::toggled handler, gtk_toggle_button_get_active() can be used to determine if the button has been selected or deselected. Creates a new #GtkRadioButton. To be of any practical value, a widget should then be packed into the radio button. a new radio button an existing radio button group, or %NULL if you are creating a new group. Creates a new #GtkRadioButton, adding it to the same group as @radio_group_member. As with gtk_radio_button_new(), a widget should be packed into the radio button. a new radio button. an existing #GtkRadioButton. Creates a new #GtkRadioButton with a text label. a new radio button. an existing radio button group, or %NULL if you are creating a new group. the text label to display next to the radio button. Creates a new #GtkRadioButton with a text label, adding it to the same group as @radio_group_member. a new radio button. widget to get radio group from or %NULL a text string to display next to the radio button. Creates a new #GtkRadioButton containing a label, adding it to the same group as @group. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the button. a new #GtkRadioButton the radio button group, or %NULL the text of the button, with an underscore in front of the mnemonic character Creates a new #GtkRadioButton containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the button. a new #GtkRadioButton widget to get radio group from or %NULL the text of the button, with an underscore in front of the mnemonic character Retrieves the group assigned to a radio button. a linked list containing all the radio buttons in the same group as @radio_button. The returned list is owned by the radio button and must not be modified or freed. a #GtkRadioButton. Joins a #GtkRadioButton object to the group of another #GtkRadioButton object Use this in language bindings instead of the gtk_radio_button_get_group() and gtk_radio_button_set_group() methods A common way to set up a group of radio buttons is the following: |[<!-- language="C" --> GtkRadioButton *radio_button; GtkRadioButton *last_button; while (some_condition) { radio_button = gtk_radio_button_new (NULL); gtk_radio_button_join_group (radio_button, last_button); last_button = radio_button; } ]| the #GtkRadioButton object a radio button object whos group we are joining, or %NULL to remove the radio button from its group Sets a #GtkRadioButton’s group. It should be noted that this does not change the layout of your interface in any way, so if you are changing the group, it is likely you will need to re-arrange the user interface to reflect these changes. a #GtkRadioButton. an existing radio button group, such as one returned from gtk_radio_button_get_group(), or %NULL. Sets a new group for a radio button. Emitted when the group of radio buttons that a radio button belongs to changes. This is emitted when a radio button switches from being alone to being part of a group of 2 or more buttons, or vice-versa, and when a button is moved from one group of 2 or more buttons to a different one, but not when the composition of the group that a button belongs to changes. A radio menu item is a check menu item that belongs to a group. At each instant exactly one of the radio menu items from a group is selected. The group list does not need to be freed, as each #GtkRadioMenuItem will remove itself and its list item when it is destroyed. The correct way to create a group of radio menu items is approximatively this: ## How to create a group of radio menu items. |[<!-- language="C" --> GSList *group = NULL; GtkWidget *item; gint i; for (i = 0; i < 5; i++) { item = gtk_radio_menu_item_new_with_label (group, "This is an example"); group = gtk_radio_menu_item_get_group (GTK_RADIO_MENU_ITEM (item)); if (i == 1) gtk_check_menu_item_set_active (GTK_CHECK_MENU_ITEM (item), TRUE); } ]| # CSS nodes |[<!-- language="plain" --> menuitem ├── radio.left ╰── <child> ]| GtkRadioMenuItem has a main CSS node with name menuitem, and a subnode with name radio, which gets the .left or .right style class. Creates a new #GtkRadioMenuItem. a new #GtkRadioMenuItem the group to which the radio menu item is to be attached, or %NULL Creates a new #GtkRadioMenuItem adding it to the same group as @group. The new #GtkRadioMenuItem An existing #GtkRadioMenuItem Creates a new #GtkRadioMenuItem whose child is a simple #GtkLabel. A new #GtkRadioMenuItem group the radio menu item is inside, or %NULL the text for the label Creates a new GtkRadioMenuItem whose child is a simple GtkLabel. The new #GtkRadioMenuItem is added to the same group as @group. The new #GtkRadioMenuItem an existing #GtkRadioMenuItem the text for the label Creates a new #GtkRadioMenuItem containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the menu item. a new #GtkRadioMenuItem group the radio menu item is inside, or %NULL the text of the button, with an underscore in front of the mnemonic character Creates a new GtkRadioMenuItem containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in label indicate the mnemonic for the menu item. The new #GtkRadioMenuItem is added to the same group as @group. The new #GtkRadioMenuItem An existing #GtkRadioMenuItem the text of the button, with an underscore in front of the mnemonic character Returns the group to which the radio menu item belongs, as a #GList of #GtkRadioMenuItem. The list belongs to GTK+ and should not be freed. the group of @radio_menu_item a #GtkRadioMenuItem Joins a #GtkRadioMenuItem object to the group of another #GtkRadioMenuItem object. This function should be used by language bindings to avoid the memory manangement of the opaque #GSList of gtk_radio_menu_item_get_group() and gtk_radio_menu_item_set_group(). A common way to set up a group of #GtkRadioMenuItem instances is: |[ GtkRadioMenuItem *last_item = NULL; while ( ...more items to add... ) { GtkRadioMenuItem *radio_item; radio_item = gtk_radio_menu_item_new (...); gtk_radio_menu_item_join_group (radio_item, last_item); last_item = radio_item; } ]| a #GtkRadioMenuItem a #GtkRadioMenuItem whose group we are joining, or %NULL to remove the @radio_menu_item from its current group Sets the group of a radio menu item, or changes it. a #GtkRadioMenuItem. the new group, or %NULL. The radio menu item whose group this widget belongs to. A #GtkRadioToolButton is a #GtkToolItem that contains a radio button, that is, a button that is part of a group of toggle buttons where only one button can be active at a time. Use gtk_radio_tool_button_new() to create a new GtkRadioToolButton. Use gtk_radio_tool_button_new_from_widget() to create a new GtkRadioToolButton that is part of the same group as an existing GtkRadioToolButton. # CSS nodes GtkRadioToolButton has a single CSS node with name toolbutton. Creates a new #GtkRadioToolButton, adding it to @group. The new #GtkRadioToolButton An existing radio button group, or %NULL if you are creating a new group Creates a new #GtkRadioToolButton, adding it to @group. The new #GtkRadioToolButton will contain an icon and label from the stock item indicated by @stock_id. Use gtk_radio_tool_button_new() instead. The new #GtkRadioToolButton an existing radio button group, or %NULL if you are creating a new group the name of a stock item Creates a new #GtkRadioToolButton adding it to the same group as @gruup The new #GtkRadioToolButton An existing #GtkRadioToolButton, or %NULL Creates a new #GtkRadioToolButton adding it to the same group as @group. The new #GtkRadioToolButton will contain an icon and label from the stock item indicated by @stock_id. gtk_radio_tool_button_new_from_widget A new #GtkRadioToolButton An existing #GtkRadioToolButton. the name of a stock item Returns the radio button group @button belongs to. The group @button belongs to. a #GtkRadioToolButton Adds @button to @group, removing it from the group it belonged to before. a #GtkRadioToolButton an existing radio button group, or %NULL Sets a new group for a radio tool button. #GtkRange is the common base class for widgets which visualize an adjustment, e.g #GtkScale or #GtkScrollbar. Apart from signals for monitoring the parameters of the adjustment, #GtkRange provides properties and methods for influencing the sensitivity of the “steppers”. It also provides properties and methods for setting a “fill level” on range widgets. See gtk_range_set_fill_level(). Get the #GtkAdjustment which is the “model” object for #GtkRange. See gtk_range_set_adjustment() for details. The return value does not have a reference added, so should not be unreferenced. a #GtkAdjustment a #GtkRange Gets the current position of the fill level indicator. The current fill level A #GtkRange Gets the value set by gtk_range_set_flippable(). %TRUE if the range is flippable a #GtkRange Gets the value set by gtk_range_set_inverted(). %TRUE if the range is inverted a #GtkRange Gets the sensitivity policy for the stepper that points to the 'lower' end of the GtkRange’s adjustment. The lower stepper’s sensitivity policy. a #GtkRange This function is useful mainly for #GtkRange subclasses. See gtk_range_set_min_slider_size(). Use the min-height/min-width CSS properties on the slider node. The minimum size of the range’s slider. a #GtkRange This function returns the area that contains the range’s trough and its steppers, in widget->window coordinates. This function is useful mainly for #GtkRange subclasses. a #GtkRange return location for the range rectangle Gets whether the range is restricted to the fill level. %TRUE if @range is restricted to the fill level. A #GtkRange Gets the number of digits to round the value to when it changes. See #GtkRange::change-value. the number of digits to round to a #GtkRange Gets whether the range displays the fill level graphically. %TRUE if @range shows the fill level. A #GtkRange This function returns sliders range along the long dimension, in widget->window coordinates. This function is useful mainly for #GtkRange subclasses. a #GtkRange return location for the slider's start, or %NULL return location for the slider's end, or %NULL This function is useful mainly for #GtkRange subclasses. See gtk_range_set_slider_size_fixed(). whether the range’s slider has a fixed size. a #GtkRange Gets the sensitivity policy for the stepper that points to the 'upper' end of the GtkRange’s adjustment. The upper stepper’s sensitivity policy. a #GtkRange Gets the current value of the range. current value of the range. a #GtkRange Sets the adjustment to be used as the “model” object for this range widget. The adjustment indicates the current range value, the minimum and maximum range values, the step/page increments used for keybindings and scrolling, and the page size. The page size is normally 0 for #GtkScale and nonzero for #GtkScrollbar, and indicates the size of the visible area of the widget being scrolled. The page size affects the size of the scrollbar slider. a #GtkRange a #GtkAdjustment Set the new position of the fill level indicator. The “fill level” is probably best described by its most prominent use case, which is an indicator for the amount of pre-buffering in a streaming media player. In that use case, the value of the range would indicate the current play position, and the fill level would be the position up to which the file/stream has been downloaded. This amount of prebuffering can be displayed on the range’s trough and is themeable separately from the trough. To enable fill level display, use gtk_range_set_show_fill_level(). The range defaults to not showing the fill level. Additionally, it’s possible to restrict the range’s slider position to values which are smaller than the fill level. This is controller by gtk_range_set_restrict_to_fill_level() and is by default enabled. a #GtkRange the new position of the fill level indicator If a range is flippable, it will switch its direction if it is horizontal and its direction is %GTK_TEXT_DIR_RTL. See gtk_widget_get_direction(). a #GtkRange %TRUE to make the range flippable Sets the step and page sizes for the range. The step size is used when the user clicks the #GtkScrollbar arrows or moves #GtkScale via arrow keys. The page size is used for example when moving via Page Up or Page Down keys. a #GtkRange step size page size Ranges normally move from lower to higher values as the slider moves from top to bottom or left to right. Inverted ranges have higher values at the top or on the right rather than on the bottom or left. a #GtkRange %TRUE to invert the range Sets the sensitivity policy for the stepper that points to the 'lower' end of the GtkRange’s adjustment. a #GtkRange the lower stepper’s sensitivity policy. Sets the minimum size of the range’s slider. This function is useful mainly for #GtkRange subclasses. Use the min-height/min-width CSS properties on the slider node. a #GtkRange The slider’s minimum size Sets the allowable values in the #GtkRange, and clamps the range value to be between @min and @max. (If the range has a non-zero page size, it is clamped between @min and @max - page-size.) a #GtkRange minimum range value maximum range value Sets whether the slider is restricted to the fill level. See gtk_range_set_fill_level() for a general description of the fill level concept. A #GtkRange Whether the fill level restricts slider movement. Sets the number of digits to round the value to when it changes. See #GtkRange::change-value. a #GtkRange the precision in digits, or -1 Sets whether a graphical fill level is show on the trough. See gtk_range_set_fill_level() for a general description of the fill level concept. A #GtkRange Whether a fill level indicator graphics is shown. Sets whether the range’s slider has a fixed size, or a size that depends on its adjustment’s page size. This function is useful mainly for #GtkRange subclasses. a #GtkRange %TRUE to make the slider size constant Sets the sensitivity policy for the stepper that points to the 'upper' end of the GtkRange’s adjustment. a #GtkRange the upper stepper’s sensitivity policy. Sets the current value of the range; if the value is outside the minimum or maximum range values, it will be clamped to fit inside them. The range emits the #GtkRange::value-changed signal if the value changes. a #GtkRange new value of the range The fill level (e.g. prebuffering of a network stream). See gtk_range_set_fill_level(). The restrict-to-fill-level property controls whether slider movement is restricted to an upper boundary set by the fill level. See gtk_range_set_restrict_to_fill_level(). The number of digits to round the value to when it changes, or -1. See #GtkRange::change-value. The show-fill-level property controls whether fill level indicator graphics are displayed on the trough. See gtk_range_set_show_fill_level(). Emitted before clamping a value, to give the application a chance to adjust the bounds. the value before we clamp The #GtkRange::change-value signal is emitted when a scroll action is performed on a range. It allows an application to determine the type of scroll event that occurred and the resultant new value. The application can handle the event itself and return %TRUE to prevent further processing. Or, by returning %FALSE, it can pass the event to other handlers until the default GTK+ handler is reached. The value parameter is unrounded. An application that overrides the GtkRange::change-value signal is responsible for clamping the value to the desired number of decimal digits; the default GTK+ handler clamps the value based on #GtkRange:round-digits. %TRUE to prevent other handlers from being invoked for the signal, %FALSE to propagate the signal further the type of scroll action that was performed the new value resulting from the scroll action Virtual function that moves the slider. Used for keybindings. how to move the slider Emitted when the range value changes. Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated quark-ified type identifier quark-ified property identifier like “GtkScrollbar::spacing” field similar to one found in #GtkSettingsValue field similar to one found in #GtkSettingsValue A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses borders in the form `"{ left, right, top, bottom }"` for integers left, right, top and bottom. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GtkBorder. a #GParamSpec the #GString to be parsed a #GValue which must hold boxed values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a color given either by its name or in the form `{ red, green, blue }` where red, green and blue are integers between 0 and 65535 or floating-point numbers between 0 and 1. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GdkColor. a #GParamSpec the #GString to be parsed a #GValue which must hold #GdkColor values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a single enumeration value. The enumeration value can be specified by its name, its nickname or its numeric value. For consistency with flags parsing, the value may be surrounded by parentheses. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GEnumValue. a #GParamSpec the #GString to be parsed a #GValue which must hold enum values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses flags. Flags can be specified by their name, their nickname or numerically. Multiple flags can be specified in the form `"( flag1 | flag2 | ... )"`. %TRUE if @gstring could be parsed and @property_value has been set to the resulting flags value. a #GParamSpec the #GString to be parsed a #GValue which must hold flags values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a requisition in the form `"{ width, height }"` for integers %width and %height. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GtkRequisition. a #GParamSpec the #GString to be parsed a #GValue which must hold boxed values. The #GtkRcStyle-struct is used to represent a set of information about the appearance of a widget. This can later be composited together with other #GtkRcStyle-struct<!-- -->s to form a #GtkStyle. Creates a new #GtkRcStyle with no fields set and a reference count of 1. Use #GtkCssProvider instead. the newly-created #GtkRcStyle Makes a copy of the specified #GtkRcStyle. This function will correctly copy an RC style that is a member of a class derived from #GtkRcStyle. Use #GtkCssProvider instead. the resulting #GtkRcStyle the style to copy Name Pixmap name A #PangoFontDescription #GtkRcFlags Foreground colors Background colors Text colors Base colors X thickness Y thickness The parent class. The #GtkRcTokenType enumeration represents the tokens in the RC file. It is exposed so that theme engines can reuse these tokens when parsing the theme-engine specific portions of a RC file. Use #GtkCssProvider instead. Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated A #GtkRecentAction represents a list of recently used files, which can be shown by widgets such as #GtkRecentChooserDialog or #GtkRecentChooserMenu. To construct a submenu showing recently used files, use a #GtkRecentAction as the action for a `<menuitem>`. To construct a menu toolbutton showing the recently used files in the popup menu, use a #GtkRecentAction as the action for a `<toolitem>` element. Creates a new #GtkRecentAction object. To add the action to a #GtkActionGroup and set the accelerator for the action, call gtk_action_group_add_action_with_accel(). the newly created #GtkRecentAction. a unique name for the action the label displayed in menu items and on buttons, or %NULL a tooltip for the action, or %NULL the stock icon to display in widgets representing the action, or %NULL Creates a new #GtkRecentAction object. To add the action to a #GtkActionGroup and set the accelerator for the action, call gtk_action_group_add_action_with_accel(). the newly created #GtkRecentAction a unique name for the action the label displayed in menu items and on buttons, or %NULL a tooltip for the action, or %NULL the stock icon to display in widgets representing the action, or %NULL a #GtkRecentManager, or %NULL for using the default #GtkRecentManager Returns the value set by gtk_recent_chooser_menu_set_show_numbers(). %TRUE if numbers should be shown. a #GtkRecentAction Sets whether a number should be added to the items shown by the widgets representing @action. The numbers are shown to provide a unique character for a mnemonic to be used inside the menu item's label. Only the first ten items get a number to avoid clashes. a #GtkRecentAction %TRUE if the shown items should be numbered Whether the items should be displayed with a number. #GtkRecentChooser is an interface that can be implemented by widgets displaying the list of recently used files. In GTK+, the main objects that implement this interface are #GtkRecentChooserWidget, #GtkRecentChooserDialog and #GtkRecentChooserMenu. Recently used files are supported since GTK+ 2.10. Adds @filter to the list of #GtkRecentFilter objects held by @chooser. If no previous filter objects were defined, this function will call gtk_recent_chooser_set_filter(). a #GtkRecentChooser a #GtkRecentFilter Gets the URI currently selected by @chooser. a newly allocated string holding a URI. a #GtkRecentChooser Gets the list of recently used resources in form of #GtkRecentInfo objects. The return value of this function is affected by the “sort-type” and “limit” properties of @chooser. A newly allocated list of #GtkRecentInfo objects. You should use gtk_recent_info_unref() on every item of the list, and then free the list itself using g_list_free(). a #GtkRecentChooser Gets the #GtkRecentManager used by chooser. Signal emitted when the user “activates” a recent item in the recent chooser. Gets the #GtkRecentFilter objects held by @chooser. A singly linked list of #GtkRecentFilter objects. You should just free the returned list using g_slist_free(). a #GtkRecentChooser Removes @filter from the list of #GtkRecentFilter objects held by @chooser. a #GtkRecentChooser a #GtkRecentFilter Selects all the items inside @chooser, if the @chooser supports multiple selection. a #GtkRecentChooser Selects @uri inside @chooser. %TRUE if @uri was found. a #GtkRecentChooser a URI Signal emitted when there is a change in the set of selected recently used resources. Sets @uri as the current URI for @chooser. %TRUE if the URI was found. a #GtkRecentChooser a URI Sets the comparison function used when sorting to be @sort_func. If the @chooser has the sort type set to #GTK_RECENT_SORT_CUSTOM then the chooser will sort using this function. To the comparison function will be passed two #GtkRecentInfo structs and @sort_data; @sort_func should return a positive integer if the first item comes before the second, zero if the two items are equal and a negative integer if the first item comes after the second. a #GtkRecentChooser the comparison function user data to pass to @sort_func, or %NULL destroy notifier for @sort_data, or %NULL Unselects all the items inside @chooser. a #GtkRecentChooser Unselects @uri inside @chooser. a #GtkRecentChooser a URI Adds @filter to the list of #GtkRecentFilter objects held by @chooser. If no previous filter objects were defined, this function will call gtk_recent_chooser_set_filter(). a #GtkRecentChooser a #GtkRecentFilter Gets the #GtkRecentInfo currently selected by @chooser. a #GtkRecentInfo. Use gtk_recent_info_unref() when when you have finished using it. a #GtkRecentChooser Gets the URI currently selected by @chooser. a newly allocated string holding a URI. a #GtkRecentChooser Gets the #GtkRecentFilter object currently used by @chooser to affect the display of the recently used resources. a #GtkRecentFilter object. a #GtkRecentChooser Gets the list of recently used resources in form of #GtkRecentInfo objects. The return value of this function is affected by the “sort-type” and “limit” properties of @chooser. A newly allocated list of #GtkRecentInfo objects. You should use gtk_recent_info_unref() on every item of the list, and then free the list itself using g_list_free(). a #GtkRecentChooser Gets the number of items returned by gtk_recent_chooser_get_items() and gtk_recent_chooser_get_uris(). A positive integer, or -1 meaning that all items are returned. a #GtkRecentChooser Gets whether only local resources should be shown in the recently used resources selector. See gtk_recent_chooser_set_local_only() %TRUE if only local resources should be shown. a #GtkRecentChooser Gets whether @chooser can select multiple items. %TRUE if @chooser can select more than one item. a #GtkRecentChooser Retrieves whether @chooser should show an icon near the resource. %TRUE if the icons should be displayed, %FALSE otherwise. a #GtkRecentChooser Retrieves whether @chooser should show the recently used resources that were not found. %TRUE if the resources not found should be displayed, and %FALSE otheriwse. a #GtkRecentChooser Returns whether @chooser should display recently used resources registered as private. %TRUE if the recent chooser should show private items, %FALSE otherwise. a #GtkRecentChooser Gets whether @chooser should display tooltips containing the full path of a recently user resource. %TRUE if the recent chooser should show tooltips, %FALSE otherwise. a #GtkRecentChooser Gets the value set by gtk_recent_chooser_set_sort_type(). the sorting order of the @chooser. a #GtkRecentChooser Gets the URI of the recently used resources. The return value of this function is affected by the “sort-type” and “limit” properties of @chooser. Since the returned array is %NULL terminated, @length may be %NULL. A newly allocated, %NULL-terminated array of strings. Use g_strfreev() to free it. a #GtkRecentChooser return location for a the length of the URI list, or %NULL Gets the #GtkRecentFilter objects held by @chooser. A singly linked list of #GtkRecentFilter objects. You should just free the returned list using g_slist_free(). a #GtkRecentChooser Removes @filter from the list of #GtkRecentFilter objects held by @chooser. a #GtkRecentChooser a #GtkRecentFilter Selects all the items inside @chooser, if the @chooser supports multiple selection. a #GtkRecentChooser Selects @uri inside @chooser. %TRUE if @uri was found. a #GtkRecentChooser a URI Sets @uri as the current URI for @chooser. %TRUE if the URI was found. a #GtkRecentChooser a URI Sets @filter as the current #GtkRecentFilter object used by @chooser to affect the displayed recently used resources. a #GtkRecentChooser a #GtkRecentFilter Sets the number of items that should be returned by gtk_recent_chooser_get_items() and gtk_recent_chooser_get_uris(). a #GtkRecentChooser a positive integer, or -1 for all items Sets whether only local resources, that is resources using the file:// URI scheme, should be shown in the recently used resources selector. If @local_only is %TRUE (the default) then the shown resources are guaranteed to be accessible through the operating system native file system. a #GtkRecentChooser %TRUE if only local files can be shown Sets whether @chooser can select multiple items. a #GtkRecentChooser %TRUE if @chooser can select more than one item Sets whether @chooser should show an icon near the resource when displaying it. a #GtkRecentChooser whether to show an icon near the resource Sets whether @chooser should display the recently used resources that it didn’t find. This only applies to local resources. a #GtkRecentChooser whether to show the local items we didn’t find Whether to show recently used resources marked registered as private. a #GtkRecentChooser %TRUE to show private items, %FALSE otherwise Sets whether to show a tooltips containing the full path of each recently used resource in a #GtkRecentChooser widget. a #GtkRecentChooser %TRUE if tooltips should be shown Sets the comparison function used when sorting to be @sort_func. If the @chooser has the sort type set to #GTK_RECENT_SORT_CUSTOM then the chooser will sort using this function. To the comparison function will be passed two #GtkRecentInfo structs and @sort_data; @sort_func should return a positive integer if the first item comes before the second, zero if the two items are equal and a negative integer if the first item comes after the second. a #GtkRecentChooser the comparison function user data to pass to @sort_func, or %NULL destroy notifier for @sort_data, or %NULL Changes the sorting order of the recently used resources list displayed by @chooser. a #GtkRecentChooser sort order that the chooser should use Unselects all the items inside @chooser. a #GtkRecentChooser Unselects @uri inside @chooser. a #GtkRecentChooser a URI The #GtkRecentFilter object to be used when displaying the recently used resources. The maximum number of recently used resources to be displayed, or -1 to display all items. Whether this #GtkRecentChooser should display only local (file:) resources. The #GtkRecentManager instance used by the #GtkRecentChooser to display the list of recently used resources. Allow the user to select multiple resources. Whether this #GtkRecentChooser should display an icon near the item. Whether this #GtkRecentChooser should display the recently used resources even if not present anymore. Setting this to %FALSE will perform a potentially expensive check on every local resource (every remote resource will always be displayed). Whether this #GtkRecentChooser should display a tooltip containing the full path of the recently used resources. Sorting order to be used when displaying the recently used resources. This signal is emitted when the user "activates" a recent item in the recent chooser. This can happen by double-clicking on an item in the recently used resources list, or by pressing `Enter`. This signal is emitted when there is a change in the set of selected recently used resources. This can happen when a user modifies the selection with the mouse or the keyboard, or when explicitly calling functions to change the selection. #GtkRecentChooserDialog is a dialog box suitable for displaying the recently used documents. This widgets works by putting a #GtkRecentChooserWidget inside a #GtkDialog. It exposes the #GtkRecentChooserIface interface, so you can use all the #GtkRecentChooser functions on the recent chooser dialog as well as those for #GtkDialog. Note that #GtkRecentChooserDialog does not have any methods of its own. Instead, you should use the functions that work on a #GtkRecentChooser. ## Typical usage ## {#gtkrecentchooser-typical-usage} In the simplest of cases, you can use the following code to use a #GtkRecentChooserDialog to select a recently used file: |[<!-- language="C" --> GtkWidget *dialog; gint res; dialog = gtk_recent_chooser_dialog_new ("Recent Documents", parent_window, _("_Cancel"), GTK_RESPONSE_CANCEL, _("_Open"), GTK_RESPONSE_ACCEPT, NULL); res = gtk_dialog_run (GTK_DIALOG (dialog)); if (res == GTK_RESPONSE_ACCEPT) { GtkRecentInfo *info; GtkRecentChooser *chooser = GTK_RECENT_CHOOSER (dialog); info = gtk_recent_chooser_get_current_item (chooser); open_file (gtk_recent_info_get_uri (info)); gtk_recent_info_unref (info); } gtk_widget_destroy (dialog); ]| Recently used files are supported since GTK+ 2.10. Creates a new #GtkRecentChooserDialog. This function is analogous to gtk_dialog_new_with_buttons(). a new #GtkRecentChooserDialog Title of the dialog, or %NULL Transient parent of the dialog, or %NULL, stock ID or text to go in the first button, or %NULL response ID for the first button, then additional (button, id) pairs, ending with %NULL Creates a new #GtkRecentChooserDialog with a specified recent manager. This is useful if you have implemented your own recent manager, or if you have a customized instance of a #GtkRecentManager object. a new #GtkRecentChooserDialog Title of the dialog, or %NULL Transient parent of the dialog, or %NULL, a #GtkRecentManager stock ID or text to go in the first button, or %NULL response ID for the first button, then additional (button, id) pairs, ending with %NULL These identify the various errors that can occur while calling #GtkRecentChooser functions. Indicates that a file does not exist Indicates a malformed URI Sets uri as the current URI for chooser. %TRUE if the URI was found. a #GtkRecentChooser a URI Gets the URI currently selected by chooser. a newly allocated string holding a URI. a #GtkRecentChooser Selects uri inside chooser. %TRUE if @uri was found. a #GtkRecentChooser a URI Unselects uri inside chooser. a #GtkRecentChooser a URI Selects all the items inside chooser, if the chooser supports multiple selection. a #GtkRecentChooser Unselects all the items inside chooser. a #GtkRecentChooser Gets the list of recently used resources in form of #GtkRecentInfo objects. A newly allocated list of #GtkRecentInfo objects. You should use gtk_recent_info_unref() on every item of the list, and then free the list itself using g_list_free(). a #GtkRecentChooser Gets the #GtkRecentManager used by chooser. Adds filter to the list of #GtkRecentFilter objects held by chooser. a #GtkRecentChooser a #GtkRecentFilter Removes filter from the list of #GtkRecentFilter objects held by chooser. a #GtkRecentChooser a #GtkRecentFilter Gets the #GtkRecentFilter objects held by chooser. A singly linked list of #GtkRecentFilter objects. You should just free the returned list using g_slist_free(). a #GtkRecentChooser Sets the comparison function used when sorting to be sort_func. a #GtkRecentChooser the comparison function user data to pass to @sort_func, or %NULL destroy notifier for @sort_data, or %NULL Signal emitted when the user “activates” a recent item in the recent chooser. Signal emitted when there is a change in the set of selected recently used resources. #GtkRecentChooserMenu is a widget suitable for displaying recently used files inside a menu. It can be used to set a sub-menu of a #GtkMenuItem using gtk_menu_item_set_submenu(), or as the menu of a #GtkMenuToolButton. Note that #GtkRecentChooserMenu does not have any methods of its own. Instead, you should use the functions that work on a #GtkRecentChooser. Note also that #GtkRecentChooserMenu does not support multiple filters, as it has no way to let the user choose between them as the #GtkRecentChooserWidget and #GtkRecentChooserDialog widgets do. Thus using gtk_recent_chooser_add_filter() on a #GtkRecentChooserMenu widget will yield the same effects as using gtk_recent_chooser_set_filter(), replacing any currently set filter with the supplied filter; gtk_recent_chooser_remove_filter() will remove any currently set #GtkRecentFilter object and will unset the current filter; gtk_recent_chooser_list_filters() will return a list containing a single #GtkRecentFilter object. Recently used files are supported since GTK+ 2.10. Creates a new #GtkRecentChooserMenu widget. This kind of widget shows the list of recently used resources as a menu, each item as a menu item. Each item inside the menu might have an icon, representing its MIME type, and a number, for mnemonic access. This widget implements the #GtkRecentChooser interface. This widget creates its own #GtkRecentManager object. See the gtk_recent_chooser_menu_new_for_manager() function to know how to create a #GtkRecentChooserMenu widget bound to another #GtkRecentManager object. a new #GtkRecentChooserMenu Creates a new #GtkRecentChooserMenu widget using @manager as the underlying recently used resources manager. This is useful if you have implemented your own recent manager, or if you have a customized instance of a #GtkRecentManager object or if you wish to share a common #GtkRecentManager object among multiple #GtkRecentChooser widgets. a new #GtkRecentChooserMenu, bound to @manager. a #GtkRecentManager Returns the value set by gtk_recent_chooser_menu_set_show_numbers(). %TRUE if numbers should be shown. a #GtkRecentChooserMenu Sets whether a number should be added to the items of @menu. The numbers are shown to provide a unique character for a mnemonic to be used inside ten menu item’s label. Only the first the items get a number to avoid clashes. a #GtkRecentChooserMenu whether to show numbers Whether the first ten items in the menu should be prepended by a number acting as a unique mnemonic. #GtkRecentChooserWidget is a widget suitable for selecting recently used files. It is the main building block of a #GtkRecentChooserDialog. Most applications will only need to use the latter; you can use #GtkRecentChooserWidget as part of a larger window if you have special needs. Note that #GtkRecentChooserWidget does not have any methods of its own. Instead, you should use the functions that work on a #GtkRecentChooser. Recently used files are supported since GTK+ 2.10. Creates a new #GtkRecentChooserWidget object. This is an embeddable widget used to access the recently used resources list. a new #GtkRecentChooserWidget Creates a new #GtkRecentChooserWidget with a specified recent manager. This is useful if you have implemented your own recent manager, or if you have a customized instance of a #GtkRecentManager object. a new #GtkRecentChooserWidget a #GtkRecentManager Meta-data to be passed to gtk_recent_manager_add_full() when registering a recently used resource. a UTF-8 encoded string, containing the name of the recently used resource to be displayed, or %NULL; a UTF-8 encoded string, containing a short description of the resource, or %NULL; the MIME type of the resource; the name of the application that is registering this recently used resource; command line used to launch this resource; may contain the “\%f” and “\%u” escape characters which will be expanded to the resource file path and URI respectively when the command line is retrieved; a vector of strings containing groups names; whether this resource should be displayed only by the applications that have registered it or not. A #GtkRecentFilter can be used to restrict the files being shown in a #GtkRecentChooser. Files can be filtered based on their name (with gtk_recent_filter_add_pattern()), on their mime type (with gtk_file_filter_add_mime_type()), on the application that has registered them (with gtk_recent_filter_add_application()), or by a custom filter function (with gtk_recent_filter_add_custom()). Filtering by mime type handles aliasing and subclassing of mime types; e.g. a filter for text/plain also matches a file with mime type application/rtf, since application/rtf is a subclass of text/plain. Note that #GtkRecentFilter allows wildcards for the subtype of a mime type, so you can e.g. filter for image/\*. Normally, filters are used by adding them to a #GtkRecentChooser, see gtk_recent_chooser_add_filter(), but it is also possible to manually use a filter on a file with gtk_recent_filter_filter(). Recently used files are supported since GTK+ 2.10. ## GtkRecentFilter as GtkBuildable The GtkRecentFilter implementation of the GtkBuildable interface supports adding rules using the `<mime-types>`, `<patterns>` and `<applications>` elements and listing the rules within. Specifying a `<mime-type>`, `<pattern>` or `<application>` has the same effect as calling gtk_recent_filter_add_mime_type(), gtk_recent_filter_add_pattern() or gtk_recent_filter_add_application(). An example of a UI definition fragment specifying `GtkRecentFilter` rules: |[<!-- language="xml" --> <object class="GtkRecentFilter"> <mime-types> <mime-type>text/plain</mime-type> <mime-type>image/png</mime-type> </mime-types> <patterns> <pattern>*.txt</pattern> <pattern>*.png</pattern> </patterns> <applications> <application>gimp</application> <application>gedit</application> <application>glade</application> </applications> </object> ]| Creates a new #GtkRecentFilter with no rules added to it. Such filter does not accept any recently used resources, so is not particularly useful until you add rules with gtk_recent_filter_add_pattern(), gtk_recent_filter_add_mime_type(), gtk_recent_filter_add_application(), gtk_recent_filter_add_age(). To create a filter that accepts any recently used resource, use: |[<!-- language="C" --> GtkRecentFilter *filter = gtk_recent_filter_new (); gtk_recent_filter_add_pattern (filter, "*"); ]| a new #GtkRecentFilter Adds a rule that allows resources based on their age - that is, the number of days elapsed since they were last modified. a #GtkRecentFilter number of days Adds a rule that allows resources based on the name of the application that has registered them. a #GtkRecentFilter an application name Adds a rule to a filter that allows resources based on a custom callback function. The bitfield @needed which is passed in provides information about what sorts of information that the filter function needs; this allows GTK+ to avoid retrieving expensive information when it isn’t needed by the filter. a #GtkRecentFilter bitfield of flags indicating the information that the custom filter function needs. callback function; if the function returns %TRUE, then the file will be displayed. data to pass to @func function to call to free @data when it is no longer needed. Adds a rule that allows resources based on the name of the group to which they belong a #GtkRecentFilter a group name Adds a rule that allows resources based on their registered MIME type. a #GtkRecentFilter a MIME type Adds a rule that allows resources based on a pattern matching their display name. a #GtkRecentFilter a file pattern Adds a rule allowing image files in the formats supported by GdkPixbuf. a #GtkRecentFilter Tests whether a file should be displayed according to @filter. The #GtkRecentFilterInfo @filter_info should include the fields returned from gtk_recent_filter_get_needed(), and must set the #GtkRecentFilterInfo.contains field of @filter_info to indicate which fields have been set. This function will not typically be used by applications; it is intended principally for use in the implementation of #GtkRecentChooser. %TRUE if the file should be displayed a #GtkRecentFilter a #GtkRecentFilterInfo containing information about a recently used resource Gets the human-readable name for the filter. See gtk_recent_filter_set_name(). the name of the filter, or %NULL. The returned string is owned by the filter object and should not be freed. a #GtkRecentFilter Gets the fields that need to be filled in for the #GtkRecentFilterInfo passed to gtk_recent_filter_filter() This function will not typically be used by applications; it is intended principally for use in the implementation of #GtkRecentChooser. bitfield of flags indicating needed fields when calling gtk_recent_filter_filter() a #GtkRecentFilter Sets the human-readable name of the filter; this is the string that will be displayed in the recently used resources selector user interface if there is a selectable list of filters. a #GtkRecentFilter then human readable name of @filter These flags indicate what parts of a #GtkRecentFilterInfo struct are filled or need to be filled. the URI of the file being tested the string that will be used to display the file in the recent chooser the mime type of the file the list of applications that have registered the file the groups to which the file belongs to the number of days elapsed since the file has been registered The type of function that is used with custom filters, see gtk_recent_filter_add_custom(). %TRUE if the file should be displayed a #GtkRecentFilterInfo that is filled according to the @needed flags passed to gtk_recent_filter_add_custom() user data passed to gtk_recent_filter_add_custom() A GtkRecentFilterInfo struct is used to pass information about the tested file to gtk_recent_filter_filter(). #GtkRecentFilterFlags to indicate which fields are set. The URI of the file being tested. The string that will be used to display the file in the recent chooser. MIME type of the file. The list of applications that have registered the file. The groups to which the file belongs to. The number of days elapsed since the file has been registered. #GtkRecentInfo-struct contains private data only, and should be accessed using the provided API. #GtkRecentInfo constains all the meta-data associated with an entry in the recently used files list. Creates a #GAppInfo for the specified #GtkRecentInfo the newly created #GAppInfo, or %NULL. In case of error, @error will be set either with a %GTK_RECENT_MANAGER_ERROR or a %G_IO_ERROR a #GtkRecentInfo the name of the application that should be mapped to a #GAppInfo; if %NULL is used then the default application for the MIME type is used Checks whether the resource pointed by @info still exists. At the moment this check is done only on resources pointing to local files. %TRUE if the resource exists a #GtkRecentInfo Gets the timestamp (seconds from system’s Epoch) when the resource was added to the recently used resources list. the number of seconds elapsed from system’s Epoch when the resource was added to the list, or -1 on failure. a #GtkRecentInfo Gets the number of days elapsed since the last update of the resource pointed by @info. a positive integer containing the number of days elapsed since the time this resource was last modified a #GtkRecentInfo Gets the data regarding the application that has registered the resource pointed by @info. If the command line contains any escape characters defined inside the storage specification, they will be expanded. %TRUE if an application with @app_name has registered this resource inside the recently used list, or %FALSE otherwise. The @app_exec string is owned by the #GtkRecentInfo and should not be modified or freed a #GtkRecentInfo the name of the application that has registered this item return location for the string containing the command line return location for the number of times this item was registered return location for the timestamp this item was last registered for this application Retrieves the list of applications that have registered this resource. a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. a #GtkRecentInfo return location for the length of the returned list Gets the (short) description of the resource. the description of the resource. The returned string is owned by the recent manager, and should not be freed. a #GtkRecentInfo Gets the name of the resource. If none has been defined, the basename of the resource is obtained. the display name of the resource. The returned string is owned by the recent manager, and should not be freed. a #GtkRecentInfo Retrieves the icon associated to the resource MIME type. a #GIcon containing the icon, or %NULL. Use g_object_unref() when finished using the icon a #GtkRecentInfo Returns all groups registered for the recently used item @info. The array of returned group names will be %NULL terminated, so length might optionally be %NULL. a newly allocated %NULL terminated array of strings. Use g_strfreev() to free it. a #GtkRecentInfo return location for the number of groups returned Retrieves the icon of size @size associated to the resource MIME type. a #GdkPixbuf containing the icon, or %NULL. Use g_object_unref() when finished using the icon. a #GtkRecentInfo the size of the icon in pixels Gets the MIME type of the resource. the MIME type of the resource. The returned string is owned by the recent manager, and should not be freed. a #GtkRecentInfo Gets the timestamp (seconds from system’s Epoch) when the meta-data for the resource was last modified. the number of seconds elapsed from system’s Epoch when the resource was last modified, or -1 on failure. a #GtkRecentInfo Gets the value of the “private” flag. Resources in the recently used list that have this flag set to %TRUE should only be displayed by the applications that have registered them. %TRUE if the private flag was found, %FALSE otherwise a #GtkRecentInfo Computes a valid UTF-8 string that can be used as the name of the item in a menu or list. For example, calling this function on an item that refers to “file:///foo/bar.txt” will yield “bar.txt”. A newly-allocated string in UTF-8 encoding free it with g_free() an #GtkRecentInfo Gets the URI of the resource. the URI of the resource. The returned string is owned by the recent manager, and should not be freed. a #GtkRecentInfo Gets a displayable version of the resource’s URI. If the resource is local, it returns a local path; if the resource is not local, it returns the UTF-8 encoded content of gtk_recent_info_get_uri(). a newly allocated UTF-8 string containing the resource’s URI or %NULL. Use g_free() when done using it. a #GtkRecentInfo Gets the timestamp (seconds from system’s Epoch) when the meta-data for the resource was last visited. the number of seconds elapsed from system’s Epoch when the resource was last visited, or -1 on failure. a #GtkRecentInfo Checks whether an application registered this resource using @app_name. %TRUE if an application with name @app_name was found, %FALSE otherwise a #GtkRecentInfo a string containing an application name Checks whether @group_name appears inside the groups registered for the recently used item @info. %TRUE if the group was found a #GtkRecentInfo name of a group Checks whether the resource is local or not by looking at the scheme of its URI. %TRUE if the resource is local a #GtkRecentInfo Gets the name of the last application that have registered the recently used resource represented by @info. an application name. Use g_free() to free it. a #GtkRecentInfo Checks whether two #GtkRecentInfo-struct point to the same resource. %TRUE if both #GtkRecentInfo-struct point to the same resource, %FALSE otherwise a #GtkRecentInfo a #GtkRecentInfo Increases the reference count of @recent_info by one. the recent info object with its reference count increased by one a #GtkRecentInfo Decreases the reference count of @info by one. If the reference count reaches zero, @info is deallocated, and the memory freed. a #GtkRecentInfo #GtkRecentManager provides a facility for adding, removing and looking up recently used files. Each recently used file is identified by its URI, and has meta-data associated to it, like the names and command lines of the applications that have registered it, the number of time each application has registered the same file, the mime type of the file and whether the file should be displayed only by the applications that have registered it. The recently used files list is per user. The #GtkRecentManager acts like a database of all the recently used files. You can create new #GtkRecentManager objects, but it is more efficient to use the default manager created by GTK+. Adding a new recently used file is as simple as: |[<!-- language="C" --> GtkRecentManager *manager; manager = gtk_recent_manager_get_default (); gtk_recent_manager_add_item (manager, file_uri); ]| The #GtkRecentManager will try to gather all the needed information from the file itself through GIO. Looking up the meta-data associated with a recently used file given its URI requires calling gtk_recent_manager_lookup_item(): |[<!-- language="C" --> GtkRecentManager *manager; GtkRecentInfo *info; GError *error = NULL; manager = gtk_recent_manager_get_default (); info = gtk_recent_manager_lookup_item (manager, file_uri, &error); if (error) { g_warning ("Could not find the file: %s", error->message); g_error_free (error); } else { // Use the info object gtk_recent_info_unref (info); } ]| In order to retrieve the list of recently used files, you can use gtk_recent_manager_get_items(), which returns a list of #GtkRecentInfo-structs. A #GtkRecentManager is the model used to populate the contents of one, or more #GtkRecentChooser implementations. Note that the maximum age of the recently used files list is controllable through the #GtkSettings:gtk-recent-files-max-age property. Recently used files are supported since GTK+ 2.10. Creates a new recent manager object. Recent manager objects are used to handle the list of recently used resources. A #GtkRecentManager object monitors the recently used resources list, and emits the “changed” signal each time something inside the list changes. #GtkRecentManager objects are expensive: be sure to create them only when needed. You should use gtk_recent_manager_get_default() instead. A newly created #GtkRecentManager object Gets a unique instance of #GtkRecentManager, that you can share in your application without caring about memory management. A unique #GtkRecentManager. Do not ref or unref it. Adds a new resource, pointed by @uri, into the recently used resources list, using the metadata specified inside the #GtkRecentData-struct passed in @recent_data. The passed URI will be used to identify this resource inside the list. In order to register the new recently used resource, metadata about the resource must be passed as well as the URI; the metadata is stored in a #GtkRecentData-struct, which must contain the MIME type of the resource pointed by the URI; the name of the application that is registering the item, and a command line to be used when launching the item. Optionally, a #GtkRecentData-struct might contain a UTF-8 string to be used when viewing the item instead of the last component of the URI; a short description of the item; whether the item should be considered private - that is, should be displayed only by the applications that have registered it. %TRUE if the new item was successfully added to the recently used resources list, %FALSE otherwise a #GtkRecentManager a valid URI metadata of the resource Adds a new resource, pointed by @uri, into the recently used resources list. This function automatically retrieves some of the needed metadata and setting other metadata to common default values; it then feeds the data to gtk_recent_manager_add_full(). See gtk_recent_manager_add_full() if you want to explicitly define the metadata for the resource pointed by @uri. %TRUE if the new item was successfully added to the recently used resources list a #GtkRecentManager a valid URI Gets the list of recently used resources. a list of newly allocated #GtkRecentInfo objects. Use gtk_recent_info_unref() on each item inside the list, and then free the list itself using g_list_free(). a #GtkRecentManager Checks whether there is a recently used resource registered with @uri inside the recent manager. %TRUE if the resource was found, %FALSE otherwise a #GtkRecentManager a URI Searches for a URI inside the recently used resources list, and returns a #GtkRecentInfo-struct containing informations about the resource like its MIME type, or its display name. a #GtkRecentInfo-struct containing information about the resource pointed by @uri, or %NULL if the URI was not registered in the recently used resources list. Free with gtk_recent_info_unref(). a #GtkRecentManager a URI Changes the location of a recently used resource from @uri to @new_uri. Please note that this function will not affect the resource pointed by the URIs, but only the URI used in the recently used resources list. %TRUE on success a #GtkRecentManager the URI of a recently used resource the new URI of the recently used resource, or %NULL to remove the item pointed by @uri in the list Purges every item from the recently used resources list. the number of items that have been removed from the recently used resources list a #GtkRecentManager Removes a resource pointed by @uri from the recently used resources list handled by a recent manager. %TRUE if the item pointed by @uri has been successfully removed by the recently used resources list, and %FALSE otherwise a #GtkRecentManager the URI of the item you wish to remove The full path to the file to be used to store and read the recently used resources list The size of the recently used resources list. Emitted when the current recently used resources manager changes its contents, either by calling gtk_recent_manager_add_item() or by another application. #GtkRecentManagerClass contains only private data. Error codes for #GtkRecentManager operations the URI specified does not exists in the recently used resources list. the URI specified is not valid. the supplied string is not UTF-8 encoded. no application has registered the specified item. failure while reading the recently used resources file. failure while writing the recently used resources file. unspecified error. Used to specify the sorting method to be applyed to the recently used resource list. Do not sort the returned list of recently used resources. Sort the returned list with the most recently used items first. Sort the returned list with the least recently used items first. Sort the returned list using a custom sorting function passed using gtk_recent_chooser_set_sort_func(). Describes a region within a widget. Region has an even number within a set. Region has an odd number within a set. Region is the first one within a set. Region is the last one within a set. Region is the only one within a set. Region is part of a sorted area. Indicated the relief to be drawn around a #GtkButton. Draw a normal relief. A half relief. Deprecated in 3.14, does the same as @GTK_RELIEF_NORMAL No relief. Represents a request of a screen object in a given orientation. These are primarily used in container implementations when allocating a natural size for children calling. See gtk_distribute_natural_allocation(). A client pointer The minimum size needed for allocation in a given orientation The natural size for allocation in a given orientation A #GtkRequisition-struct represents the desired size of a widget. See [GtkWidget’s geometry management section][geometry-management] for more information. the widget’s desired width the widget’s desired height Allocates a new #GtkRequisition-struct and initializes its elements to zero. a new empty #GtkRequisition. The newly allocated #GtkRequisition should be freed with gtk_requisition_free(). Copies a #GtkRequisition. a copy of @requisition a #GtkRequisition Frees a #GtkRequisition. a #GtkRequisition Pass resize request to the parent Queue resizes on this widget Resize immediately. Deprecated. Predefined values for use as response ids in gtk_dialog_add_button(). All predefined values are negative; GTK+ leaves values of 0 or greater for application-defined response ids. Returned if an action widget has no response id, or if the dialog gets programmatically hidden or destroyed Generic response id, not used by GTK+ dialogs Generic response id, not used by GTK+ dialogs Returned if the dialog is deleted Returned by OK buttons in GTK+ dialogs Returned by Cancel buttons in GTK+ dialogs Returned by Close buttons in GTK+ dialogs Returned by Yes buttons in GTK+ dialogs Returned by No buttons in GTK+ dialogs Returned by Apply buttons in GTK+ dialogs Returned by Help buttons in GTK+ dialogs The GtkRevealer widget is a container which animates the transition of its child from invisible to visible. The style of transition can be controlled with gtk_revealer_set_transition_type(). These animations respect the #GtkSettings:gtk-enable-animations setting. # CSS nodes GtkRevealer has a single CSS node with name revealer. The GtkRevealer widget was added in GTK+ 3.10. Creates a new #GtkRevealer. a newly created #GtkRevealer Returns whether the child is fully revealed, in other words whether the transition to the revealed state is completed. %TRUE if the child is fully revealed a #GtkRevealer Returns whether the child is currently revealed. See gtk_revealer_set_reveal_child(). This function returns %TRUE as soon as the transition is to the revealed state is started. To learn whether the child is fully revealed (ie the transition is completed), use gtk_revealer_get_child_revealed(). %TRUE if the child is revealed. a #GtkRevealer Returns the amount of time (in milliseconds) that transitions will take. the transition duration a #GtkRevealer Gets the type of animation that will be used for transitions in @revealer. the current transition type of @revealer a #GtkRevealer Tells the #GtkRevealer to reveal or conceal its child. The transition will be animated with the current transition type of @revealer. a #GtkRevealer %TRUE to reveal the child Sets the duration that transitions will take. a #GtkRevealer the new duration, in milliseconds Sets the type of animation that will be used for transitions in @revealer. Available types include various kinds of fades and slides. a #GtkRevealer the new transition type The parent class. These enumeration values describe the possible transitions when the child of a #GtkRevealer widget is shown or hidden. No transition Fade in Slide in from the left Slide in from the right Slide in from the bottom Slide in from the top The “About” item. ![](help-about.png) Use named icon &quot;help-about&quot; or the label &quot;_About&quot;. The “Add” item and icon. Use named icon &quot;list-add&quot; or the label &quot;_Add&quot;. The “Apply” item and icon. Do not use an icon. Use label &quot;_Apply&quot;. The “Bold” item and icon. Use named icon &quot;format-text-bold&quot;. The “Cancel” item and icon. Do not use an icon. Use label &quot;_Cancel&quot;. The “Caps Lock Warning” icon. Use named icon &quot;dialog-warning-symbolic&quot;. The “CD-Rom” item and icon. Use named icon &quot;media-optical&quot;. The “Clear” item and icon. Use named icon &quot;edit-clear&quot;. The “Close” item and icon. Use named icon &quot;window-close&quot; or the label &quot;_Close&quot;. The “Color Picker” item and icon. The “Connect” icon. The “Convert” item and icon. The “Copy” item and icon. Use the named icon &quot;edit-copy&quot; or the label &quot;_Copy&quot;. The “Cut” item and icon. Use the named icon &quot;edit-cut&quot; or the label &quot;Cu_t&quot;. The “Delete” item and icon. Use the named icon &quot;edit-delete&quot; or the label &quot;_Delete&quot;. The “Authentication” item and icon. Use named icon &quot;dialog-password&quot;. The “Error” item and icon. Use named icon &quot;dialog-error&quot;. The “Information” item and icon. Use named icon &quot;dialog-information&quot;. The “Question” item and icon. Use named icon &quot;dialog-question&quot;. The “Warning” item and icon. Use named icon &quot;dialog-warning&quot;. The “Directory” icon. Use named icon &quot;folder&quot;. The “Discard” item. The “Disconnect” icon. The “Drag-And-Drop” icon. The “Drag-And-Drop multiple” icon. The “Edit” item and icon. The “Execute” item and icon. Use named icon &quot;system-run&quot;. The “File” item and icon. Since 3.0, this item has a label, before it only had an icon. Use named icon &quot;text-x-generic&quot;. The “Find” item and icon. Use named icon &quot;edit-find&quot;. The “Find and Replace” item and icon. Use named icon &quot;edit-find-replace&quot;. The “Floppy” item and icon. The “Fullscreen” item and icon. Use named icon &quot;view-fullscreen&quot;. The “Bottom” item and icon. Use named icon &quot;go-bottom&quot;. The “First” item and icon. The icon has an RTL variant. Use named icon &quot;go-first&quot;. The “Last” item and icon. The icon has an RTL variant. Use named icon &quot;go-last&quot;. The “Top” item and icon. Use named icon &quot;go-top&quot;. The “Back” item and icon. The icon has an RTL variant. Use named icon &quot;go-previous&quot;. The “Down” item and icon. Use named icon &quot;go-down&quot;. The “Forward” item and icon. The icon has an RTL variant. Use named icon &quot;go-next&quot;. The “Up” item and icon. Use named icon &quot;go-up&quot;. The “Harddisk” item and icon. Use named icon &quot;drive-harddisk&quot;. The “Help” item and icon. Use named icon &quot;help-browser&quot;. The “Home” item and icon. Use named icon &quot;go-home&quot;. The “Indent” item and icon. The icon has an RTL variant. Use named icon &quot;format-indent-more&quot;. The “Index” item and icon. The “Info” item and icon. Use named icon &quot;dialog-information&quot;. The “Italic” item and icon. Use named icon &quot;format-text-italic&quot;. The “Jump to” item and icon. The icon has an RTL variant. Use named icon &quot;go-jump&quot;. The “Center” item and icon. Use named icon &quot;format-justify-center&quot;. The “Fill” item and icon. Use named icon &quot;format-justify-fill&quot;. The “Left” item and icon. Use named icon &quot;format-justify-left&quot;. The “Right” item and icon. Use named icon &quot;format-justify-right&quot;. The “Leave Fullscreen” item and icon. Use named icon &quot;view-restore&quot;. The “Media Forward” item and icon. The icon has an RTL variant. Use named icon &quot;media-seek-forward&quot; or the label &quot;_Forward&quot;. The “Media Next” item and icon. The icon has an RTL variant. Use named icon &quot;media-skip-forward&quot; or the label &quot;_Next&quot;. The “Media Pause” item and icon. Use named icon &quot;media-playback-pause&quot; or the label &quot;P_ause&quot;. The “Media Play” item and icon. The icon has an RTL variant. Use named icon &quot;media-playback-start&quot; or the label &quot;_Play&quot;. The “Media Previous” item and icon. The icon has an RTL variant. Use named icon &quot;media-skip-backward&quot; or the label &quot;Pre_vious&quot;. The “Media Record” item and icon. Use named icon &quot;media-record&quot; or the label &quot;_Record&quot;. The “Media Rewind” item and icon. The icon has an RTL variant. Use named icon &quot;media-seek-backward&quot; or the label &quot;R_ewind&quot;. The “Media Stop” item and icon. Use named icon &quot;media-playback-stop&quot; or the label &quot;_Stop&quot;. The “Missing image” icon. Use named icon &quot;image-missing&quot;. The “Network” item and icon. Use named icon &quot;network-workgroup&quot;. The “New” item and icon. Use named icon &quot;document-new&quot; or the label &quot;_New&quot;. The “No” item and icon. The “OK” item and icon. Do not use an icon. Use label &quot;_OK&quot;. The “Open” item and icon. Use named icon &quot;document-open&quot; or the label &quot;_Open&quot;. The “Landscape Orientation” item and icon. The “Portrait Orientation” item and icon. The “Reverse Landscape Orientation” item and icon. The “Reverse Portrait Orientation” item and icon. The “Page Setup” item and icon. Use named icon &quot;document-page-setup&quot; or the label &quot;Page Set_up&quot;. The “Paste” item and icon. Use named icon &quot;edit-paste&quot; or the label &quot;_Paste&quot;. The “Preferences” item and icon. Use named icon &quot;preferences-system&quot; or the label &quot;_Preferences&quot;. The “Print” item and icon. Use named icon &quot;document-print&quot; or the label &quot;_Print&quot;. The “Print Error” icon. Use named icon &quot;printer-error&quot;. The “Print Paused” icon. The “Print Preview” item and icon. Use label &quot;Pre_view&quot;. The “Print Report” icon. The “Print Warning” icon. The “Properties” item and icon. Use named icon &quot;document-properties&quot; or the label &quot;_Properties&quot;. The “Quit” item and icon. Use named icon &quot;application-exit&quot; or the label &quot;_Quit&quot;. The “Redo” item and icon. The icon has an RTL variant. Use named icon &quot;edit-redo&quot; or the label &quot;_Redo&quot;. The “Refresh” item and icon. Use named icon &quot;view-refresh&quot; or the label &quot;_Refresh&quot;. The “Remove” item and icon. Use named icon &quot;list-remove&quot; or the label &quot;_Remove&quot;. The “Revert” item and icon. The icon has an RTL variant. Use named icon &quot;document-revert&quot; or the label &quot;_Revert&quot;. The “Save” item and icon. Use named icon &quot;document-save&quot; or the label &quot;_Save&quot;. The “Save As” item and icon. Use named icon &quot;document-save-as&quot; or the label &quot;Save _As&quot;. The “Select All” item and icon. Use named icon &quot;edit-select-all&quot; or the label &quot;Select _All&quot;. The “Color” item and icon. The “Font” item and icon. The “Ascending” item and icon. Use named icon &quot;view-sort-ascending&quot;. The “Descending” item and icon. Use named icon &quot;view-sort-descending&quot;. The “Spell Check” item and icon. Use named icon &quot;tools-check-spelling&quot;. The “Stop” item and icon. Use named icon &quot;process-stop&quot; or the label &quot;_Stop&quot;. The “Strikethrough” item and icon. Use named icon &quot;format-text-strikethrough&quot; or the label &quot;_Strikethrough&quot;. The “Undelete” item and icon. The icon has an RTL variant. The “Underline” item and icon. Use named icon &quot;format-text-underline&quot; or the label &quot;_Underline&quot;. The “Undo” item and icon. The icon has an RTL variant. Use named icon &quot;edit-undo&quot; or the label &quot;_Undo&quot;. The “Unindent” item and icon. The icon has an RTL variant. Use named icon &quot;format-indent-less&quot;. The “Yes” item and icon. The “Zoom 100%” item and icon. Use named icon &quot;zoom-original&quot; or the label &quot;_Normal Size&quot;. The “Zoom to Fit” item and icon. Use named icon &quot;zoom-fit-best&quot; or the label &quot;Best _Fit&quot;. The “Zoom In” item and icon. Use named icon &quot;zoom-in&quot; or the label &quot;Zoom _In&quot;. The “Zoom Out” item and icon. Use named icon &quot;zoom-out&quot; or the label &quot;Zoom _Out&quot;. a #GtkStyle. A CSS class to match an accelerator. Refer to individual widget documentation for used style classes. A CSS class used when rendering an arrow element. Refer to individual widget documentation for used style classes. A CSS class to match the window background. Refer to individual widget documentation for used style classes. A CSS class to indicate an area at the bottom of a widget. Refer to individual widget documentation for used style classes. A CSS class to match buttons. Refer to individual widget documentation for used style classes. A CSS class to match calendars. Refer to individual widget documentation for used style classes. A CSS class to match content rendered in cell views. Refer to individual widget documentation for used style classes. A CSS class to match check boxes. Refer to individual widget documentation for used style classes. A CSS class to match combobox entries. Refer to individual widget documentation for used style classes. A CSS class to match context menus. Refer to individual widget documentation for used style classes. A CSS class that gets added to windows which have client-side decorations. Refer to individual widget documentation for used style classes. A CSS class used when rendering a drag handle for text selection. Refer to individual widget documentation for used style classes. A CSS class to match the default widget. Refer to individual widget documentation for used style classes. A CSS class used when an action (usually a button) is one that is expected to remove or destroy something visible to the user. Refer to individual widget documentation for used style classes. A CSS class to match dimmed labels. Refer to individual widget documentation for used style classes. A CSS class for a drag-and-drop indicator. Refer to individual widget documentation for used style classes. A CSS class defining a dock area. Refer to individual widget documentation for used style classes. A CSS class to match text entries. Refer to individual widget documentation for used style classes. A CSS class for an area displaying an error message, such as those in infobars. Refer to individual widget documentation for used style classes. A CSS class defining an expander, such as those in treeviews. Refer to individual widget documentation for used style classes. A CSS class that is added when widgets that usually have a frame or border (like buttons or entries) should appear without it. Refer to individual widget documentation for used style classes. A CSS class defining a frame delimiting content, such as #GtkFrame or the scrolled window frame around the scrollable area. Refer to individual widget documentation for used style classes. A CSS class defining a resize grip. Refer to individual widget documentation for used style classes. A CSS class to match a header element. Refer to individual widget documentation for used style classes. A CSS class defining a highlighted area, such as headings in assistants and calendars. Refer to individual widget documentation for used style classes. A CSS class for horizontally layered widgets. Refer to individual widget documentation for used style classes. A CSS class defining an image, such as the icon in an entry. Refer to individual widget documentation for used style classes. A CSS class for an area displaying an informational message, such as those in infobars. Refer to individual widget documentation for used style classes. A CSS class to match inline toolbars. Refer to individual widget documentation for used style classes. A CSS class used when rendering a drag handle for the insertion cursor position. Refer to individual widget documentation for used style classes. A CSS class to match labels. Refer to individual widget documentation for used style classes. A CSS class to indicate an area at the left of a widget. Refer to individual widget documentation for used style classes. A CSS class used when rendering a level indicator, such as a battery charge level, or a password strength. Refer to individual widget documentation for used style classes. A CSS class to match a linked area, such as a box containing buttons belonging to the same control. Refer to individual widget documentation for used style classes. A CSS class to match lists. Refer to individual widget documentation for used style classes. A CSS class to match list rows. Refer to individual widget documentation for used style classes. A CSS class defining marks in a widget, such as in scales. Refer to individual widget documentation for used style classes. A CSS class to match menus. Refer to individual widget documentation for used style classes. A CSS class to menubars. Refer to individual widget documentation for used style classes. A CSS class to match menu items. Refer to individual widget documentation for used style classes. A CSS class that is added to message dialogs. Refer to individual widget documentation for used style classes. A CSS class that is added to text view that should use a monospace font. Refer to individual widget documentation for used style classes. A CSS class used when an element needs the user attention, for instance a button in a stack switcher corresponding to a hidden page that changed state. Refer to individual widget documentation for used style classes. A CSS class defining a notebook. Refer to individual widget documentation for used style classes. A CSS class used when rendering an OSD (On Screen Display) element, on top of another container. Refer to individual widget documentation for used style classes. A CSS class that is added on the visual hints that happen when scrolling is attempted past the limits of a scrollable area. Refer to individual widget documentation for used style classes. A CSS class for a pane separator, such as those in #GtkPaned. Refer to individual widget documentation for used style classes. A CSS class that is added to areas that should look like paper. This is used in print previews and themes are encouraged to style it as black text on white background. Refer to individual widget documentation for used style classes. A CSS class that matches popovers. Refer to individual widget documentation for used style classes. A CSS class that is added to the toplevel windows used for menus. Refer to individual widget documentation for used style classes. A CSS class to match primary toolbars. Refer to individual widget documentation for used style classes. A CSS class to use when rendering activity as a progressbar. Refer to individual widget documentation for used style classes. A CSS class to use when rendering a pulse in an indeterminate progress bar. Refer to individual widget documentation for used style classes. A CSS class for an area displaying a question to the user, such as those in infobars. Refer to individual widget documentation for used style classes. A CSS class to match radio buttons. Refer to individual widget documentation for used style classes. A CSS class to match a raised control, such as a raised button on a toolbar. Refer to individual widget documentation for used style classes. A CSS class used to indicate a read-only state. Refer to individual widget documentation for used style classes. A CSS class to indicate an area at the right of a widget. Refer to individual widget documentation for used style classes. A CSS class to match the rubberband selection rectangle. Refer to individual widget documentation for used style classes. A CSS class to match scale widgets. Refer to individual widget documentation for used style classes. A CSS class to match scale widgets with marks attached, all the marks are above for horizontal #GtkScale. left for vertical #GtkScale. Refer to individual widget documentation for used style classes. A CSS class to match scale widgets with marks attached, all the marks are below for horizontal #GtkScale, right for vertical #GtkScale. Refer to individual widget documentation for used style classes. A CSS class to match scrollbars. Refer to individual widget documentation for used style classes. A CSS class to match the junction area between an horizontal and vertical scrollbar, when they’re both shown. Refer to individual widget documentation for used style classes. A CSS class for a separator. Refer to individual widget documentation for used style classes. A CSS class defining a sidebar, such as the left side in a file chooser. Refer to individual widget documentation for used style classes. A CSS class to match sliders. Refer to individual widget documentation for used style classes. A CSS class defining an spinbutton. Refer to individual widget documentation for used style classes. A CSS class to use when rendering activity as a “spinner”. Refer to individual widget documentation for used style classes. A CSS class to match statusbars. Refer to individual widget documentation for used style classes. A CSS class used for the subtitle label in a titlebar in a toplevel window. Refer to individual widget documentation for used style classes. A CSS class used when an action (usually a button) is the primary suggested action in a specific context. Refer to individual widget documentation for used style classes. A CSS class used for the title label in a titlebar in a toplevel window. Refer to individual widget documentation for used style classes. A CSS class used when rendering a titlebar in a toplevel window. Refer to individual widget documentation for used style classes. A CSS class to match toolbars. Refer to individual widget documentation for used style classes. A CSS class to match tooltip windows. Refer to individual widget documentation for used style classes. A CSS class to indicate an area at the top of a widget. Refer to individual widget documentation for used style classes. A CSS class for touch selection popups on entries and text views. Refer to individual widget documentation for used style classes. A CSS class to match troughs, as in scrollbars and progressbars. Refer to individual widget documentation for used style classes. A CSS class that is added on the visual hints that happen where content is 'scrolled off' and can be made visible by scrolling. Refer to individual widget documentation for used style classes. A CSS class for vertically layered widgets. Refer to individual widget documentation for used style classes. A CSS class defining a view, such as iconviews or treeviews. Refer to individual widget documentation for used style classes. A CSS class for an area displaying a warning message, such as those in infobars. Refer to individual widget documentation for used style classes. A CSS class to indicate that a UI element should be 'wide'. Used by #GtkPaned. Refer to individual widget documentation for used style classes. A property holding the background color of rendered elements as a #GdkRGBA. A property holding the element’s background as a #cairo_pattern_t. A property holding the element’s border color as a #GdkRGBA. A property holding the rendered element’s border radius in pixels as a #gint. A property holding the element’s border style as a #GtkBorderStyle. A property holding the rendered element’s border width in pixels as a #GtkBorder. The border is the intermediary spacing property of the padding/border/margin series. gtk_render_frame() uses this property to find out the frame line width, so #GtkWidgets rendering frames may need to add up this padding when requesting size A property holding the foreground color of rendered elements as a #GdkRGBA. A property holding the font properties used when rendering text as a #PangoFontDescription. A property holding the rendered element’s margin as a #GtkBorder. The margin is defined as the spacing between the border of the element and its surrounding elements. It is external to #GtkWidget's size allocations, and the most external spacing property of the padding/border/margin series. A property holding the rendered element’s padding as a #GtkBorder. The padding is defined as the spacing between the inner part of the element border and its child. It’s the innermost spacing property of the padding/border/margin series. A priority that can be used when adding a #GtkStyleProvider for application-specific style information. The priority used for default style information that is used in the absence of themes. Note that this is not very useful for providing default styling for custom style classes - themes are likely to override styling provided at this priority with catch-all `* {...}` rules. The priority used for style information provided via #GtkSettings. This priority is higher than #GTK_STYLE_PROVIDER_PRIORITY_THEME to let settings override themes. The priority used for style information provided by themes. The priority used for the style information from `XDG_CONFIG_HOME/gtk-3.0/gtk.css`. You should not use priorities higher than this, to give the user the last word. A widget region name to define a treeview column. Don't use regions. A widget region name to define a treeview column header. Don't use regions. A widget region name to define a treeview row. Don't use regions. A widget region name to define a notebook tab. Don't use regions. A GtkScale is a slider control used to select a numeric value. To use it, you’ll probably want to investigate the methods on its base class, #GtkRange, in addition to the methods for GtkScale itself. To set the value of a scale, you would normally use gtk_range_set_value(). To detect changes to the value, you would normally use the #GtkRange::value-changed signal. Note that using the same upper and lower bounds for the #GtkScale (through the #GtkRange methods) will hide the slider itself. This is useful for applications that want to show an undeterminate value on the scale, without changing the layout of the application (such as movie or music players). # GtkScale as GtkBuildable GtkScale supports a custom `<marks>` element, which can contain multiple `<mark>` elements. The “value” and “position” attributes have the same meaning as gtk_scale_add_mark() parameters of the same name. If the element is not empty, its content is taken as the markup to show at the mark. It can be translated with the usual ”translatable” and “context” attributes. # CSS nodes |[<!-- language="plain" --> scale[.fine-tune][.marks-before][.marks-after] ├── marks.top │ ├── mark │ ┊ ├── [label] │ ┊ ╰── indicator ┊ ┊ │ ╰── mark ├── [value] ├── contents │ ╰── trough │ ├── slider │ ├── [highlight] │ ╰── [fill] ╰── marks.bottom ├── mark ┊ ├── indicator ┊ ╰── [label] ╰── mark ]| GtkScale has a main CSS node with name scale and a subnode for its contents, with subnodes named trough and slider. The main node gets the style class .fine-tune added when the scale is in 'fine-tuning' mode. If the scale has an origin (see gtk_scale_set_has_origin()), there is a subnode with name highlight below the trough node that is used for rendering the highlighted part of the trough. If the scale is showing a fill level (see gtk_range_set_show_fill_level()), there is a subnode with name fill below the trough node that is used for rendering the filled in part of the trough. If marks are present, there is a marks subnode before or after the contents node, below which each mark gets a node with name mark. The marks nodes get either the .top or .bottom style class. The mark node has a subnode named indicator. If the mark has text, it also has a subnode named label. When the mark is either above or left of the scale, the label subnode is the first when present. Otherwise, the indicator subnode is the first. The main CSS node gets the 'marks-before' and/or 'marks-after' style classes added depending on what marks are present. If the scale is displaying the value (see #GtkScale:draw-value), there is subnode with name value. Creates a new #GtkScale. a new #GtkScale the scale’s orientation. the #GtkAdjustment which sets the range of the scale, or %NULL to create a new adjustment. Creates a new scale widget with the given orientation that lets the user input a number between @min and @max (including @min and @max) with the increment @step. @step must be nonzero; it’s the distance the slider moves when using the arrow keys to adjust the scale value. Note that the way in which the precision is derived works best if @step is a power of ten. If the resulting precision is not suitable for your needs, use gtk_scale_set_digits() to correct it. a new #GtkScale the scale’s orientation. minimum value maximum value step increment (tick size) used with keyboard shortcuts Obtains the coordinates where the scale will draw the #PangoLayout representing the text in the scale. Remember when using the #PangoLayout function you need to convert to and from pixels using PANGO_PIXELS() or #PANGO_SCALE. If the #GtkScale:draw-value property is %FALSE, the return values are undefined. a #GtkScale location to store X offset of layout, or %NULL location to store Y offset of layout, or %NULL Adds a mark at @value. A mark is indicated visually by drawing a tick mark next to the scale, and GTK+ makes it easy for the user to position the scale exactly at the marks value. If @markup is not %NULL, text is shown next to the tick mark. To remove marks from a scale, use gtk_scale_clear_marks(). a #GtkScale the value at which the mark is placed, must be between the lower and upper limits of the scales’ adjustment where to draw the mark. For a horizontal scale, #GTK_POS_TOP and %GTK_POS_LEFT are drawn above the scale, anything else below. For a vertical scale, #GTK_POS_LEFT and %GTK_POS_TOP are drawn to the left of the scale, anything else to the right. Text to be shown at the mark, using [Pango markup][PangoMarkupFormat], or %NULL Removes any marks that have been added with gtk_scale_add_mark(). a #GtkScale Gets the number of decimal places that are displayed in the value. the number of decimal places that are displayed a #GtkScale Returns whether the current value is displayed as a string next to the slider. whether the current value is displayed as a string a #GtkScale Returns whether the scale has an origin. %TRUE if the scale has an origin. a #GtkScale Gets the #PangoLayout used to display the scale. The returned object is owned by the scale so does not need to be freed by the caller. the #PangoLayout for this scale, or %NULL if the #GtkScale:draw-value property is %FALSE. A #GtkScale Obtains the coordinates where the scale will draw the #PangoLayout representing the text in the scale. Remember when using the #PangoLayout function you need to convert to and from pixels using PANGO_PIXELS() or #PANGO_SCALE. If the #GtkScale:draw-value property is %FALSE, the return values are undefined. a #GtkScale location to store X offset of layout, or %NULL location to store Y offset of layout, or %NULL Gets the position in which the current value is displayed. the position in which the current value is displayed a #GtkScale Sets the number of decimal places that are displayed in the value. Also causes the value of the adjustment to be rounded to this number of digits, so the retrieved value matches the displayed one, if #GtkScale:draw-value is %TRUE when the value changes. If you want to enforce rounding the value when #GtkScale:draw-value is %FALSE, you can set #GtkRange:round-digits instead. Note that rounding to a small number of digits can interfere with the smooth autoscrolling that is built into #GtkScale. As an alternative, you can use the #GtkScale::format-value signal to format the displayed value yourself. a #GtkScale the number of decimal places to display, e.g. use 1 to display 1.0, 2 to display 1.00, etc Specifies whether the current value is displayed as a string next to the slider. a #GtkScale %TRUE to draw the value If #GtkScale:has-origin is set to %TRUE (the default), the scale will highlight the part of the trough between the origin (bottom or left side) and the current value. a #GtkScale %TRUE if the scale has an origin Sets the position in which the current value is displayed. a #GtkScale the position in which the current value is displayed Signal which allows you to change how the scale value is displayed. Connect a signal handler which returns an allocated string representing @value. That string will then be used to display the scale's value. If no user-provided handlers are installed, the value will be displayed on its own, rounded according to the value of the #GtkScale:digits property. Here's an example signal handler which displays a value 1.0 as with "-->1.0<--". |[<!-- language="C" --> static gchar* format_value_callback (GtkScale *scale, gdouble value) { return g_strdup_printf ("-->\%0.*g<--", gtk_scale_get_digits (scale), value); } ]| allocated string representing @value the value to format #GtkScaleButton provides a button which pops up a scale widget. This kind of widget is commonly used for volume controls in multimedia applications, and GTK+ provides a #GtkVolumeButton subclass that is tailored for this use case. # CSS nodes GtkScaleButton has a single CSS node with name button. To differentiate it from a plain #GtkButton, it gets the .scale style class. The popup widget that contains the scale has a .scale-popup style class. Creates a #GtkScaleButton, with a range between @min and @max, with a stepping of @step. a new #GtkScaleButton a stock icon size (#GtkIconSize) the minimum value of the scale (usually 0) the maximum value of the scale (usually 100) the stepping of value when a scroll-wheel event, or up/down arrow event occurs (usually 2) a %NULL-terminated array of icon names, or %NULL if you want to set the list later with gtk_scale_button_set_icons() Gets the #GtkAdjustment associated with the #GtkScaleButton’s scale. See gtk_range_get_adjustment() for details. the adjustment associated with the scale a #GtkScaleButton Retrieves the minus button of the #GtkScaleButton. the minus button of the #GtkScaleButton as a #GtkButton a #GtkScaleButton Retrieves the plus button of the #GtkScaleButton. the plus button of the #GtkScaleButton as a #GtkButton a #GtkScaleButton Retrieves the popup of the #GtkScaleButton. the popup of the #GtkScaleButton a #GtkScaleButton Gets the current value of the scale button. current value of the scale button a #GtkScaleButton Sets the #GtkAdjustment to be used as a model for the #GtkScaleButton’s scale. See gtk_range_set_adjustment() for details. a #GtkScaleButton a #GtkAdjustment Sets the icons to be used by the scale button. For details, see the #GtkScaleButton:icons property. a #GtkScaleButton a %NULL-terminated array of icon names Sets the current value of the scale; if the value is outside the minimum or maximum range values, it will be clamped to fit inside them. The scale button emits the #GtkScaleButton::value-changed signal if the value changes. a #GtkScaleButton new value of the scale button The names of the icons to be used by the scale button. The first item in the array will be used in the button when the current value is the lowest value, the second item for the highest value. All the subsequent icons will be used for all the other values, spread evenly over the range of values. If there's only one icon name in the @icons array, it will be used for all the values. If only two icon names are in the @icons array, the first one will be used for the bottom 50% of the scale, and the second one for the top 50%. It is recommended to use at least 3 icons so that the #GtkScaleButton reflects the current value of the scale better for the users. The ::popdown signal is a [keybinding signal][GtkBindingSignal] which gets emitted to popdown the scale widget. The default binding for this signal is Escape. The ::popup signal is a [keybinding signal][GtkBindingSignal] which gets emitted to popup the scale widget. The default bindings for this signal are Space, Enter and Return. The ::value-changed signal is emitted when the value field has changed. the new value a #GtkScale location to store X offset of layout, or %NULL location to store Y offset of layout, or %NULL Scroll in steps. Scroll by pages. Scroll to ends. Scroll in horizontal steps. Scroll by horizontal pages. Scroll to the horizontal ends. Scrolling types. No scrolling. Jump to new location. Step backward. Step forward. Page backward. Page forward. Step up. Step down. Page up. Page down. Step to the left. Step to the right. Page to the left. Page to the right. Scroll to start. Scroll to end. #GtkScrollable is an interface that is implemented by widgets with native scrolling ability. To implement this interface you should override the #GtkScrollable:hadjustment and #GtkScrollable:vadjustment properties. ## Creating a scrollable widget All scrollable widgets should do the following. - When a parent widget sets the scrollable child widget’s adjustments, the widget should populate the adjustments’ #GtkAdjustment:lower, #GtkAdjustment:upper, #GtkAdjustment:step-increment, #GtkAdjustment:page-increment and #GtkAdjustment:page-size properties and connect to the #GtkAdjustment::value-changed signal. - Because its preferred size is the size for a fully expanded widget, the scrollable widget must be able to cope with underallocations. This means that it must accept any value passed to its #GtkWidgetClass.size_allocate() function. - When the parent allocates space to the scrollable child widget, the widget should update the adjustments’ properties with new values. - When any of the adjustments emits the #GtkAdjustment::value-changed signal, the scrollable widget should scroll its contents. Returns the size of a non-scrolling border around the outside of the scrollable. An example for this would be treeview headers. GTK+ can use this information to display overlayed graphics, like the overshoot indication, at the right position. %TRUE if @border has been set a #GtkScrollable return location for the results Returns the size of a non-scrolling border around the outside of the scrollable. An example for this would be treeview headers. GTK+ can use this information to display overlayed graphics, like the overshoot indication, at the right position. %TRUE if @border has been set a #GtkScrollable return location for the results Retrieves the #GtkAdjustment used for horizontal scrolling. horizontal #GtkAdjustment. a #GtkScrollable Gets the horizontal #GtkScrollablePolicy. The horizontal #GtkScrollablePolicy. a #GtkScrollable Retrieves the #GtkAdjustment used for vertical scrolling. vertical #GtkAdjustment. a #GtkScrollable Gets the vertical #GtkScrollablePolicy. The vertical #GtkScrollablePolicy. a #GtkScrollable Sets the horizontal adjustment of the #GtkScrollable. a #GtkScrollable a #GtkAdjustment Sets the #GtkScrollablePolicy to determine whether horizontal scrolling should start below the minimum width or below the natural width. a #GtkScrollable the horizontal #GtkScrollablePolicy Sets the vertical adjustment of the #GtkScrollable. a #GtkScrollable a #GtkAdjustment Sets the #GtkScrollablePolicy to determine whether vertical scrolling should start below the minimum height or below the natural height. a #GtkScrollable the vertical #GtkScrollablePolicy Horizontal #GtkAdjustment of the scrollable widget. This adjustment is shared between the scrollable widget and its parent. Determines whether horizontal scrolling should start once the scrollable widget is allocated less than its minimum width or less than its natural width. Verical #GtkAdjustment of the scrollable widget. This adjustment is shared between the scrollable widget and its parent. Determines whether vertical scrolling should start once the scrollable widget is allocated less than its minimum height or less than its natural height. %TRUE if @border has been set a #GtkScrollable return location for the results Defines the policy to be used in a scrollable widget when updating the scrolled window adjustments in a given orientation. Scrollable adjustments are based on the minimum size Scrollable adjustments are based on the natural size The #GtkScrollbar widget is a horizontal or vertical scrollbar, depending on the value of the #GtkOrientable:orientation property. Its position and movement are controlled by the adjustment that is passed to or created by gtk_scrollbar_new(). See #GtkAdjustment for more details. The #GtkAdjustment:value field sets the position of the thumb and must be between #GtkAdjustment:lower and #GtkAdjustment:upper - #GtkAdjustment:page-size. The #GtkAdjustment:page-size represents the size of the visible scrollable area. The fields #GtkAdjustment:step-increment and #GtkAdjustment:page-increment fields are added to or subtracted from the #GtkAdjustment:value when the user asks to move by a step (using e.g. the cursor arrow keys or, if present, the stepper buttons) or by a page (using e.g. the Page Down/Up keys). # CSS nodes |[<!-- language="plain" --> scrollbar[.fine-tune] ╰── contents ├── [button.up] ├── [button.down] ├── trough │ ╰── slider ├── [button.up] ╰── [button.down] ]| GtkScrollbar has a main CSS node with name scrollbar and a subnode for its contents, with subnodes named trough and slider. The main node gets the style class .fine-tune added when the scrollbar is in 'fine-tuning' mode. If steppers are enabled, they are represented by up to four additional subnodes with name button. These get the style classes .up and .down to indicate in which direction they are moving. Other style classes that may be added to scrollbars inside #GtkScrolledWindow include the positional classes (.left, .right, .top, .bottom) and style classes related to overlay scrolling (.overlay-indicator, .dragging, .hovering). Creates a new scrollbar with the given orientation. the new #GtkScrollbar. the scrollbar’s orientation. the #GtkAdjustment to use, or %NULL to create a new adjustment. GtkScrolledWindow is a container that accepts a single child widget and makes that child scrollable using either internally added scrollbars or externally associated adjustments. Widgets with native scrolling support, i.e. those whose classes implement the #GtkScrollable interface, are added directly. For other types of widget, the class #GtkViewport acts as an adaptor, giving scrollability to other widgets. GtkScrolledWindow’s implementation of gtk_container_add() intelligently accounts for whether or not the added child is a #GtkScrollable. If it isn’t, #GtkScrolledWindow wraps the child in a #GtkViewport and adds that for you. Therefore, you can just add any child widget and not worry about the details. If gtk_container_add() has added a #GtkViewport for you, you can remove both your added child widget from the #GtkViewport, and the #GtkViewport from the GtkScrolledWindow, like this: |[<!-- language="C" --> GtkWidget *scrolled_window = gtk_scrolled_window_new (NULL, NULL); GtkWidget *child_widget = gtk_button_new (); // GtkButton is not a GtkScrollable, so GtkScrolledWindow will automatically // add a GtkViewport. gtk_container_add (GTK_CONTAINER (scrolled_window), child_widget); // Either of these will result in child_widget being unparented: gtk_container_remove (GTK_CONTAINER (scrolled_window), child_widget); // or gtk_container_remove (GTK_CONTAINER (scrolled_window), gtk_bin_get_child (GTK_BIN (scrolled_window))); ]| Unless #GtkScrolledWindow:policy is GTK_POLICY_NEVER or GTK_POLICY_EXTERNAL, GtkScrolledWindow adds internal #GtkScrollbar widgets around its child. The scroll position of the child, and if applicable the scrollbars, is controlled by the #GtkScrolledWindow:hadjustment and #GtkScrolledWindow:vadjustment that are associated with the GtkScrolledWindow. See the docs on #GtkScrollbar for the details, but note that the “step_increment” and “page_increment” fields are only effective if the policy causes scrollbars to be present. If a GtkScrolledWindow doesn’t behave quite as you would like, or doesn’t have exactly the right layout, it’s very possible to set up your own scrolling with #GtkScrollbar and for example a #GtkGrid. # Touch support GtkScrolledWindow has built-in support for touch devices. When a touchscreen is used, swiping will move the scrolled window, and will expose 'kinetic' behavior. This can be turned off with the #GtkScrolledWindow:kinetic-scrolling property if it is undesired. GtkScrolledWindow also displays visual 'overshoot' indication when the content is pulled beyond the end, and this situation can be captured with the #GtkScrolledWindow::edge-overshot signal. If no mouse device is present, the scrollbars will overlayed as narrow, auto-hiding indicators over the content. If traditional scrollbars are desired although no mouse is present, this behaviour can be turned off with the #GtkScrolledWindow:overlay-scrolling property. # CSS nodes GtkScrolledWindow has a main CSS node with name scrolledwindow. It uses subnodes with names overshoot and undershoot to draw the overflow and underflow indications. These nodes get the .left, .right, .top or .bottom style class added depending on where the indication is drawn. GtkScrolledWindow also sets the positional style classes (.left, .right, .top, .bottom) and style classes related to overlay scrolling (.overlay-indicator, .dragging, .hovering) on its scrollbars. If both scrollbars are visible, the area where they meet is drawn with a subnode named junction. Creates a new scrolled window. The two arguments are the scrolled window’s adjustments; these will be shared with the scrollbars and the child widget to keep the bars in sync with the child. Usually you want to pass %NULL for the adjustments, which will cause the scrolled window to create them for you. a new scrolled window horizontal adjustment vertical adjustment Keybinding signal which gets emitted when focus is moved away from the scrolled window by a keybinding. Keybinding signal which gets emitted when a keybinding that scrolls is pressed. Used to add children without native scrolling capabilities. This is simply a convenience function; it is equivalent to adding the unscrollable child to a viewport, then adding the viewport to the scrolled window. If a child has native scrolling, use gtk_container_add() instead of this function. The viewport scrolls the child by moving its #GdkWindow, and takes the size of the child to be the size of its toplevel #GdkWindow. This will be very wrong for most widgets that support native scrolling; for example, if you add a widget such as #GtkTreeView with a viewport, the whole widget will scroll, including the column headings. Thus, widgets with native scrolling support should not be used with the #GtkViewport proxy. A widget supports scrolling natively if it implements the #GtkScrollable interface. gtk_container_add() will automatically add a #GtkViewport if the child doesn’t implement #GtkScrollable. a #GtkScrolledWindow the widget you want to scroll Return whether button presses are captured during kinetic scrolling. See gtk_scrolled_window_set_capture_button_press(). %TRUE if button presses are captured during kinetic scrolling a #GtkScrolledWindow Returns the horizontal scrollbar’s adjustment, used to connect the horizontal scrollbar to the child widget’s horizontal scroll functionality. the horizontal #GtkAdjustment a #GtkScrolledWindow Returns the horizontal scrollbar of @scrolled_window. the horizontal scrollbar of the scrolled window. a #GtkScrolledWindow Returns the specified kinetic scrolling behavior. the scrolling behavior flags. a #GtkScrolledWindow Returns the maximum content height set. the maximum content height, or -1 a #GtkScrolledWindow Returns the maximum content width set. the maximum content width, or -1 a #GtkScrolledWindow Gets the minimal content height of @scrolled_window, or -1 if not set. the minimal content height a #GtkScrolledWindow Gets the minimum content width of @scrolled_window, or -1 if not set. the minimum content width a #GtkScrolledWindow Returns whether overlay scrolling is enabled for this scrolled window. %TRUE if overlay scrolling is enabled a #GtkScrolledWindow Gets the placement of the contents with respect to the scrollbars for the scrolled window. See gtk_scrolled_window_set_placement(). the current placement value. See also gtk_scrolled_window_set_placement() and gtk_scrolled_window_unset_placement(). a #GtkScrolledWindow Retrieves the current policy values for the horizontal and vertical scrollbars. See gtk_scrolled_window_set_policy(). a #GtkScrolledWindow location to store the policy for the horizontal scrollbar, or %NULL location to store the policy for the vertical scrollbar, or %NULL Reports whether the natural height of the child will be calculated and propagated through the scrolled window’s requested natural height. whether natural height propagation is enabled. a #GtkScrolledWindow Reports whether the natural width of the child will be calculated and propagated through the scrolled window’s requested natural width. whether natural width propagation is enabled. a #GtkScrolledWindow Gets the shadow type of the scrolled window. See gtk_scrolled_window_set_shadow_type(). the current shadow type a #GtkScrolledWindow Returns the vertical scrollbar’s adjustment, used to connect the vertical scrollbar to the child widget’s vertical scroll functionality. the vertical #GtkAdjustment a #GtkScrolledWindow Returns the vertical scrollbar of @scrolled_window. the vertical scrollbar of the scrolled window. a #GtkScrolledWindow Changes the behaviour of @scrolled_window with regard to the initial event that possibly starts kinetic scrolling. When @capture_button_press is set to %TRUE, the event is captured by the scrolled window, and then later replayed if it is meant to go to the child widget. This should be enabled if any child widgets perform non-reversible actions on #GtkWidget::button-press-event. If they don't, and handle additionally handle #GtkWidget::grab-broken-event, it might be better to set @capture_button_press to %FALSE. This setting only has an effect if kinetic scrolling is enabled. a #GtkScrolledWindow %TRUE to capture button presses Sets the #GtkAdjustment for the horizontal scrollbar. a #GtkScrolledWindow the #GtkAdjustment to use, or %NULL to create a new one Turns kinetic scrolling on or off. Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN. a #GtkScrolledWindow %TRUE to enable kinetic scrolling Sets the maximum height that @scrolled_window should keep visible. The @scrolled_window will grow up to this height before it starts scrolling the content. It is a programming error to set the maximum content height to a value smaller than #GtkScrolledWindow:min-content-height. a #GtkScrolledWindow the maximum content height Sets the maximum width that @scrolled_window should keep visible. The @scrolled_window will grow up to this width before it starts scrolling the content. It is a programming error to set the maximum content width to a value smaller than #GtkScrolledWindow:min-content-width. a #GtkScrolledWindow the maximum content width Sets the minimum height that @scrolled_window should keep visible. Note that this can and (usually will) be smaller than the minimum size of the content. It is a programming error to set the minimum content height to a value greater than #GtkScrolledWindow:max-content-height. a #GtkScrolledWindow the minimal content height Sets the minimum width that @scrolled_window should keep visible. Note that this can and (usually will) be smaller than the minimum size of the content. It is a programming error to set the minimum content width to a value greater than #GtkScrolledWindow:max-content-width. a #GtkScrolledWindow the minimal content width Enables or disables overlay scrolling for this scrolled window. a #GtkScrolledWindow whether to enable overlay scrolling Sets the placement of the contents with respect to the scrollbars for the scrolled window. The default is %GTK_CORNER_TOP_LEFT, meaning the child is in the top left, with the scrollbars underneath and to the right. Other values in #GtkCornerType are %GTK_CORNER_TOP_RIGHT, %GTK_CORNER_BOTTOM_LEFT, and %GTK_CORNER_BOTTOM_RIGHT. See also gtk_scrolled_window_get_placement() and gtk_scrolled_window_unset_placement(). a #GtkScrolledWindow position of the child window Sets the scrollbar policy for the horizontal and vertical scrollbars. The policy determines when the scrollbar should appear; it is a value from the #GtkPolicyType enumeration. If %GTK_POLICY_ALWAYS, the scrollbar is always present; if %GTK_POLICY_NEVER, the scrollbar is never present; if %GTK_POLICY_AUTOMATIC, the scrollbar is present only if needed (that is, if the slider part of the bar would be smaller than the trough — the display is larger than the page size). a #GtkScrolledWindow policy for horizontal bar policy for vertical bar Sets whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height. a #GtkScrolledWindow whether to propagate natural height Sets whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width. a #GtkScrolledWindow whether to propagate natural width Changes the type of shadow drawn around the contents of @scrolled_window. a #GtkScrolledWindow kind of shadow to draw around scrolled window contents Sets the #GtkAdjustment for the vertical scrollbar. a #GtkScrolledWindow the #GtkAdjustment to use, or %NULL to create a new one Unsets the placement of the contents with respect to the scrollbars for the scrolled window. If no window placement is set for a scrolled window, it defaults to %GTK_CORNER_TOP_LEFT. See also gtk_scrolled_window_set_placement() and gtk_scrolled_window_get_placement(). a #GtkScrolledWindow Whether kinetic scrolling is enabled or not. Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN. The maximum content height of @scrolled_window, or -1 if not set. The maximum content width of @scrolled_window, or -1 if not set. The minimum content height of @scrolled_window, or -1 if not set. The minimum content width of @scrolled_window, or -1 if not set. Whether overlay scrolling is enabled or not. If it is, the scrollbars are only added as traditional widgets when a mouse is present. Otherwise, they are overlayed on top of the content, as narrow indicators. Note that overlay scrolling can also be globally disabled, with the #GtkSettings::gtk-overlay-scrolling setting. Whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height. This is useful in cases where an attempt should be made to allocate exactly enough space for the natural size of the child. Whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width. This is useful in cases where an attempt should be made to allocate exactly enough space for the natural size of the child. Whether "window-placement" should be used to determine the location of the contents with respect to the scrollbars. This value is ignored and #GtkScrolledWindow:window-placement value is always honored. The ::edge-overshot signal is emitted whenever user initiated scrolling makes the scrolled window firmly surpass (i.e. with some edge resistance) the lower or upper limits defined by the adjustment in that orientation. A similar behavior without edge resistance is provided by the #GtkScrolledWindow::edge-reached signal. Note: The @pos argument is LTR/RTL aware, so callers should be aware too if intending to provide behavior on horizontal edges. edge side that was hit The ::edge-reached signal is emitted whenever user-initiated scrolling makes the scrolled window exactly reach the lower or upper limits defined by the adjustment in that orientation. A similar behavior with edge resistance is provided by the #GtkScrolledWindow::edge-overshot signal. Note: The @pos argument is LTR/RTL aware, so callers should be aware too if intending to provide behavior on horizontal edges. edge side that was reached The ::move-focus-out signal is a [keybinding signal][GtkBindingSignal] which gets emitted when focus is moved away from the scrolled window by a keybinding. The #GtkWidget::move-focus signal is emitted with @direction_type on this scrolled window’s toplevel parent in the container hierarchy. The default bindings for this signal are `Ctrl + Tab` to move forward and `Ctrl + Shift + Tab` to move backward. either %GTK_DIR_TAB_FORWARD or %GTK_DIR_TAB_BACKWARD The ::scroll-child signal is a [keybinding signal][GtkBindingSignal] which gets emitted when a keybinding that scrolls is pressed. The horizontal or vertical adjustment is updated which triggers a signal that the scrolled window’s child may listen to and scroll itself. a #GtkScrollType describing how much to scroll whether the keybinding scrolls the child horizontally or not The parent class. Keybinding signal which gets emitted when a keybinding that scrolls is pressed. Keybinding signal which gets emitted when focus is moved away from the scrolled window by a keybinding. #GtkSearchBar is a container made to have a search entry (possibly with additional connex widgets, such as drop-down menus, or buttons) built-in. The search bar would appear when a search is started through typing on the keyboard, or the application’s search mode is toggled on. For keyboard presses to start a search, events will need to be forwarded from the top-level window that contains the search bar. See gtk_search_bar_handle_event() for example code. Common shortcuts such as Ctrl+F should be handled as an application action, or through the menu items. You will also need to tell the search bar about which entry you are using as your search entry using gtk_search_bar_connect_entry(). The following example shows you how to create a more complex search entry. # CSS nodes GtkSearchBar has a single CSS node with name searchbar. ## Creating a search bar [A simple example](https://gitlab.gnome.org/GNOME/gtk/blob/gtk-3-24/examples/search-bar.c) Creates a #GtkSearchBar. You will need to tell it about which widget is going to be your text entry using gtk_search_bar_connect_entry(). a new #GtkSearchBar Connects the #GtkEntry widget passed as the one to be used in this search bar. The entry should be a descendant of the search bar. This is only required if the entry isn’t the direct child of the search bar (as in our main example). a #GtkSearchBar a #GtkEntry Returns whether the search mode is on or off. whether search mode is toggled on a #GtkSearchBar Returns whether the close button is shown. whether the close button is shown a #GtkSearchBar This function should be called when the top-level window which contains the search bar received a key event. If the key event is handled by the search bar, the bar will be shown, the entry populated with the entered text and %GDK_EVENT_STOP will be returned. The caller should ensure that events are not propagated further. If no entry has been connected to the search bar, using gtk_search_bar_connect_entry(), this function will return immediately with a warning. ## Showing the search bar on key presses |[<!-- language="C" --> static gboolean on_key_press_event (GtkWidget *widget, GdkEvent *event, gpointer user_data) { GtkSearchBar *bar = GTK_SEARCH_BAR (user_data); return gtk_search_bar_handle_event (bar, event); } static void create_toplevel (void) { GtkWidget *window = gtk_window_new (GTK_WINDOW_TOPLEVEL); GtkWindow *search_bar = gtk_search_bar_new (); // Add more widgets to the window... g_signal_connect (window, "key-press-event", G_CALLBACK (on_key_press_event), search_bar); } ]| %GDK_EVENT_STOP if the key press event resulted in text being entered in the search entry (and revealing the search bar if necessary), %GDK_EVENT_PROPAGATE otherwise. a #GtkSearchBar a #GdkEvent containing key press events Switches the search mode on or off. a #GtkSearchBar the new state of the search mode Shows or hides the close button. Applications that already have a “search” toggle button should not show a close button in their search bar, as it duplicates the role of the toggle button. a #GtkSearchBar whether the close button will be shown or not The parent class. #GtkSearchEntry is a subclass of #GtkEntry that has been tailored for use as a search entry. It will show an inactive symbolic “find” icon when the search entry is empty, and a symbolic “clear” icon when there is text. Clicking on the “clear” icon will empty the search entry. Note that the search/clear icon is shown using a secondary icon, and thus does not work if you are using the secondary icon position for some other purpose. To make filtering appear more reactive, it is a good idea to not react to every change in the entry text immediately, but only after a short delay. To support this, #GtkSearchEntry emits the #GtkSearchEntry::search-changed signal which can be used instead of the #GtkEditable::changed signal. The #GtkSearchEntry::previous-match, #GtkSearchEntry::next-match and #GtkSearchEntry::stop-search signals can be used to implement moving between search results and ending the search. Often, GtkSearchEntry will be fed events by means of being placed inside a #GtkSearchBar. If that is not the case, you can use gtk_search_entry_handle_event() to pass events. Creates a #GtkSearchEntry, with a find icon when the search field is empty, and a clear icon when it isn't. a new #GtkSearchEntry This function should be called when the top-level window which contains the search entry received a key event. If the entry is part of a #GtkSearchBar, it is preferable to call gtk_search_bar_handle_event() instead, which will reveal the entry in addition to passing the event to this function. If the key event is handled by the search entry and starts or continues a search, %GDK_EVENT_STOP will be returned. The caller should ensure that the entry is shown in this case, and not propagate the event further. %GDK_EVENT_STOP if the key press event resulted in a search beginning or continuing, %GDK_EVENT_PROPAGATE otherwise. a #GtkSearchEntry a key event The ::next-match signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a move to the next match for the current search string. Applications should connect to it, to implement moving between matches. The default bindings for this signal is Ctrl-g. The ::previous-match signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a move to the previous match for the current search string. Applications should connect to it, to implement moving between matches. The default bindings for this signal is Ctrl-Shift-g. The #GtkSearchEntry::search-changed signal is emitted with a short delay of 150 milliseconds after the last change to the entry text. The ::stop-search signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user stops a search via keyboard input. Applications should connect to it, to implement hiding the search entry in this case. The default bindings for this signal is Escape. Makes a copy of a #GtkSelectionData-struct and its data. a pointer to a copy of @data. a pointer to a #GtkSelectionData-struct. Frees a #GtkSelectionData-struct returned from gtk_selection_data_copy(). a pointer to a #GtkSelectionData-struct. Retrieves the raw data of the selection. the raw data of the selection. a pointer to a #GtkSelectionData-struct. Retrieves the data type of the selection. the data type of the selection. a pointer to a #GtkSelectionData-struct. Retrieves the raw data of the selection along with its length. the raw data of the selection a pointer to a #GtkSelectionData-struct. return location for length of the data segment Retrieves the display of the selection. the display of the selection. a pointer to a #GtkSelectionData-struct. Retrieves the format of the selection. the format of the selection. a pointer to a #GtkSelectionData-struct. Retrieves the length of the raw data of the selection. the length of the data of the selection. a pointer to a #GtkSelectionData-struct. Gets the contents of the selection data as a #GdkPixbuf. if the selection data contained a recognized image type and it could be converted to a #GdkPixbuf, a newly allocated pixbuf is returned, otherwise %NULL. If the result is non-%NULL it must be freed with g_object_unref(). a #GtkSelectionData Retrieves the selection #GdkAtom of the selection data. the selection #GdkAtom of the selection data. a pointer to a #GtkSelectionData-struct. Retrieves the target of the selection. the target of the selection. a pointer to a #GtkSelectionData-struct. Gets the contents of @selection_data as an array of targets. This can be used to interpret the results of getting the standard TARGETS target that is always supplied for any selection. %TRUE if @selection_data contains a valid array of targets, otherwise %FALSE. a #GtkSelectionData object location to store an array of targets. The result stored here must be freed with g_free(). location to store number of items in @targets. Gets the contents of the selection data as a UTF-8 string. if the selection data contained a recognized text type and it could be converted to UTF-8, a newly allocated string containing the converted text, otherwise %NULL. If the result is non-%NULL it must be freed with g_free(). a #GtkSelectionData Gets the contents of the selection data as array of URIs. Since 3.24.37, this may involve using the FileTransfer portal to send files between sandboxed apps. if the selection data contains a list of URIs, a newly allocated %NULL-terminated string array containing the URIs, otherwise %NULL. If the result is non-%NULL it must be freed with g_strfreev(). a #GtkSelectionData Stores new data into a #GtkSelectionData object. Should only be called from a selection handler callback. Zero-terminates the stored data. a pointer to a #GtkSelectionData-struct. the type of selection data format (number of bits in a unit) pointer to the data (will be copied) length of the data Sets the contents of the selection from a #GdkPixbuf The pixbuf is converted to the form determined by @selection_data->target. %TRUE if the selection was successfully set, otherwise %FALSE. a #GtkSelectionData a #GdkPixbuf Sets the contents of the selection from a UTF-8 encoded string. The string is converted to the form determined by @selection_data->target. %TRUE if the selection was successfully set, otherwise %FALSE. a #GtkSelectionData a UTF-8 string the length of @str, or -1 if @str is nul-terminated. Sets the contents of the selection from a list of URIs. The string is converted to the form determined by @selection_data->target. Since 3.24.37, this may involve using the FileTransfer portal to send files between sandboxed apps. %TRUE if the selection was successfully set, otherwise %FALSE. a #GtkSelectionData a %NULL-terminated array of strings holding URIs Given a #GtkSelectionData object holding a list of targets, determines if any of the targets in @targets can be used to provide a #GdkPixbuf. %TRUE if @selection_data holds a list of targets, and a suitable target for images is included, otherwise %FALSE. a #GtkSelectionData object whether to accept only targets for which GTK+ knows how to convert a pixbuf into the format Given a #GtkSelectionData object holding a list of targets, determines if any of the targets in @targets can be used to provide rich text. %TRUE if @selection_data holds a list of targets, and a suitable target for rich text is included, otherwise %FALSE. a #GtkSelectionData object a #GtkTextBuffer Given a #GtkSelectionData object holding a list of targets, determines if any of the targets in @targets can be used to provide text. %TRUE if @selection_data holds a list of targets, and a suitable target for text is included, otherwise %FALSE. a #GtkSelectionData object Given a #GtkSelectionData object holding a list of targets, determines if any of the targets in @targets can be used to provide a list or URIs. %TRUE if @selection_data holds a list of targets, and a suitable target for URI lists is included, otherwise %FALSE. a #GtkSelectionData object Used to control what selections users are allowed to make. No selection is possible. Zero or one element may be selected. Exactly one element is selected. In some circumstances, such as initially or during a search operation, it’s possible for no element to be selected with %GTK_SELECTION_BROWSE. What is really enforced is that the user can’t deselect a currently selected element except by selecting another element. Any number of elements may be selected. The Ctrl key may be used to enlarge the selection, and Shift key to select between the focus and the child pointed to. Some widgets may also allow Click-drag to select a range of elements. Determines how GTK+ handles the sensitivity of stepper arrows at the end of range widgets. The arrow is made insensitive if the thumb is at the end The arrow is always sensitive The arrow is always insensitive GtkSeparator is a horizontal or vertical separator widget, depending on the value of the #GtkOrientable:orientation property, used to group the widgets within a window. It displays a line with a shadow to make it appear sunken into the interface. # CSS nodes GtkSeparator has a single CSS node with name separator. The node gets one of the .horizontal or .vertical style classes. Creates a new #GtkSeparator with the given orientation. a new #GtkSeparator. the separator’s orientation. The #GtkSeparatorMenuItem is a separator used to group items within a menu. It displays a horizontal line with a shadow to make it appear sunken into the interface. # CSS nodes GtkSeparatorMenuItem has a single CSS node with name separator. Creates a new #GtkSeparatorMenuItem. a new #GtkSeparatorMenuItem. The parent class. A #GtkSeparatorToolItem is a #GtkToolItem that separates groups of other #GtkToolItems. Depending on the theme, a #GtkSeparatorToolItem will often look like a vertical line on horizontally docked toolbars. If the #GtkToolbar child property “expand” is %TRUE and the property #GtkSeparatorToolItem:draw is %FALSE, a #GtkSeparatorToolItem will act as a “spring” that forces other items to the ends of the toolbar. Use gtk_separator_tool_item_new() to create a new #GtkSeparatorToolItem. # CSS nodes GtkSeparatorToolItem has a single CSS node with name separator. Create a new #GtkSeparatorToolItem the new #GtkSeparatorToolItem Returns whether @item is drawn as a line, or just blank. See gtk_separator_tool_item_set_draw(). %TRUE if @item is drawn as a line, or just blank. a #GtkSeparatorToolItem Whether @item is drawn as a vertical line, or just blank. Setting this to %FALSE along with gtk_tool_item_set_expand() is useful to create an item that forces following items to the end of the toolbar. a #GtkSeparatorToolItem whether @item is drawn as a vertical line The parent class. GtkSettings provide a mechanism to share global settings between applications. On the X window system, this sharing is realized by an [XSettings](http://www.freedesktop.org/wiki/Specifications/xsettings-spec) manager that is usually part of the desktop environment, along with utilities that let the user change these settings. In the absence of an Xsettings manager, GTK+ reads default values for settings from `settings.ini` files in `/etc/gtk-3.0`, `$XDG_CONFIG_DIRS/gtk-3.0` and `$XDG_CONFIG_HOME/gtk-3.0`. These files must be valid key files (see #GKeyFile), and have a section called Settings. Themes can also provide default values for settings by installing a `settings.ini` file next to their `gtk.css` file. Applications can override system-wide settings by setting the property of the GtkSettings object with g_object_set(). This should be restricted to special cases though; GtkSettings are not meant as an application configuration facility. When doing so, you need to be aware that settings that are specific to individual widgets may not be available before the widget type has been realized at least once. The following example demonstrates a way to do this: |[<!-- language="C" --> gtk_init (&argc, &argv); // make sure the type is realized g_type_class_unref (g_type_class_ref (GTK_TYPE_IMAGE_MENU_ITEM)); g_object_set (gtk_settings_get_default (), "gtk-enable-animations", FALSE, NULL); ]| There is one GtkSettings instance per screen. It can be obtained with gtk_settings_get_for_screen(), but in many cases, it is more convenient to use gtk_widget_get_settings(). gtk_settings_get_default() returns the GtkSettings instance for the default screen. Gets the #GtkSettings object for the default GDK screen, creating it if necessary. See gtk_settings_get_for_screen(). a #GtkSettings object. If there is no default screen, then returns %NULL. Gets the #GtkSettings object for @screen, creating it if necessary. a #GtkSettings object. a #GdkScreen. This function is not useful outside GTK+. This function is not useful outside GTK+. Undoes the effect of calling g_object_set() to install an application-specific value for a setting. After this call, the setting will again follow the session-wide value for this setting. a #GtkSettings object the name of the setting to reset Use g_object_set() instead. Use g_object_set() instead. Use g_object_set() instead. Use g_object_set() instead. Holds a hash table representation of the #GtkSettings:gtk-color-scheme setting, mapping color names to #GdkColors. Will always return an empty hash table. Controls the direction of the sort indicators in sorted list and tree views. By default an arrow pointing down means the column is sorted in ascending order. When set to %TRUE, this order will be inverted. Whether the application prefers to use a dark theme. If a GTK+ theme includes a dark variant, it will be used instead of the configured theme. Some applications benefit from minimizing the amount of light pollution that interferes with the content. Good candidates for dark themes are photo and video editors that make the actual content get all the attention and minimize the distraction of the chrome. Dark themes should not be used for documents, where large spaces are white/light and the dark chrome creates too much contrast (web browser, text editor...). Whether mnemonics should be automatically shown and hidden when the user presses the mnemonic activator. This setting is ignored Whether images should be shown on buttons This setting is deprecated. Application developers control whether a button should show an icon or not, on a per-button basis. If a #GtkButton should show an icon, use the #GtkButton:always-show-image property of #GtkButton, and pack a #GtkImage inside the #GtkButton Whether menu accelerators can be changed by pressing a key over the menu item. This setting is ignored. Palette to use in the deprecated color selector. Only used by the deprecated color selector widget. A palette of named colors for use in themes. The format of the string is |[ name1: color1 name2: color2 ... ]| Color names must be acceptable as identifiers in the [gtkrc][gtk3-Resource-Files] syntax, and color specifications must be in the format accepted by gdk_color_parse(). Note that due to the way the color tables from different sources are merged, color specifications will be converted to hexadecimal form when getting this property. Starting with GTK+ 2.12, the entries can alternatively be separated by ';' instead of newlines: |[ name1: color1; name2: color2; ... ]| Color scheme support was dropped and is no longer supported. You can still set this property, but it will be ignored. Whether the cursor should blink. Also see the #GtkSettings:gtk-cursor-blink-timeout setting, which allows more flexible control over cursor blinking. Time after which the cursor stops blinking, in seconds. The timer is reset after each user interaction. Setting this to zero has the same effect as setting #GtkSettings:gtk-cursor-blink to %FALSE. This setting determines which buttons should be put in the titlebar of client-side decorated windows, and whether they should be placed at the left of right. The format of the string is button names, separated by commas. A colon separates the buttons that should appear on the left from those on the right. Recognized button names are minimize, maximize, close, icon (the window icon) and menu (a menu button for the fallback app menu). For example, "menu:minimize,maximize,close" specifies a menu on the left, and minimize, maximize and close buttons on the right. Note that buttons will only be shown when they are meaningful. E.g. a menu button only appears when the desktop shell does not show the app menu, and a close button only appears on a window that can be closed. Also note that the setting can be overridden with the #GtkHeaderBar:decoration-layout property. Whether builtin GTK+ dialogs such as the file chooser, the color chooser or the font chooser will use a header bar at the top to show action widgets, or an action area at the bottom. This setting does not affect custom dialogs using GtkDialog directly, or message dialogs. Whether menu items should have visible accelerators which can be activated. Whether to play any event sounds at all. See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec) for more information on event sounds and sound themes. GTK+ itself does not support event sounds, you have to use a loadable module like the one that comes with libcanberra. Whether to play event sounds as feedback to user input. See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec) for more information on event sounds and sound themes. GTK+ itself does not support event sounds, you have to use a loadable module like the one that comes with libcanberra. Whether labels and menu items should have visible mnemonics which can be activated. This setting can still be used for application overrides, but will be ignored in the future Whether a middle click on a mouse should paste the 'PRIMARY' clipboard content at the cursor location. Whether tooltips should be shown on widgets. This setting is ignored. How long to show the last input character in hidden entries. This value is in milliseconds. 0 disables showing the last char. 600 is a good value for enabling it. When %TRUE, keyboard navigation and other input-related errors will cause a beep. Since the error bell is implemented using gdk_window_beep(), the windowing system may offer ways to configure the error bell in many ways, such as flashing the window or similar visual effects. Name of a icon theme to fall back to. This setting is ignored. Name of the GtkFileChooser backend to use by default. This setting is ignored. #GtkFileChooser uses GIO by default. The default font to use. GTK+ uses the family name and size from this string. A list of icon sizes. The list is separated by colons, and item has the form: `size-name` = `width` , `height` E.g. "gtk-menu=16,16:gtk-button=20,20:gtk-dialog=48,48". GTK+ itself use the following named icon sizes: gtk-menu, gtk-button, gtk-small-toolbar, gtk-large-toolbar, gtk-dnd, gtk-dialog. Applications can register their own named icon sizes with gtk_icon_size_register(). This setting is ignored. Which IM (input method) module should be used by default. This is the input method that will be used if the user has not explicitly chosen another input method from the IM context menu. This also can be a colon-separated list of input methods, which GTK+ will try in turn until it finds one available on the system. See #GtkIMContext. How to draw the input method preedit string. This setting is ignored. How to draw the input method statusbar. This setting is ignored. When %TRUE, keyboard navigation should be able to reach all widgets by using the cursor keys only. Tab, Shift etc. keys can't be expected to be present on the used input device. Generally, the behavior for touchscreen input should be performed dynamically based on gdk_event_get_source_device(). Whether GTK+ should make sure that text can be navigated with a caret, even if it is not editable. This is useful when using a screen reader. When %TRUE, some widgets will wrap around when doing keyboard navigation, such as menus, menubars and notebooks. This setting is ignored. The time for a button or touch press to be considered a "long press". Keybinding to activate the menu bar. This setting can still be used for application overrides, but will be ignored in the future Delay before the submenus of a menu bar appear. This setting is ignored. Whether images should be shown in menu items This setting is deprecated. Application developers control whether or not a #GtkMenuItem should have an icon or not, on a per widget basis. Either use a #GtkMenuItem with a #GtkBox containing a #GtkImage and a #GtkAccelLabel, or describe your menus using a #GMenu XML description The time before hiding a submenu when the pointer is moving towards the submenu. This setting is ignored. Minimum time the pointer must stay over a menu item before the submenu appear. This setting is ignored. Whether scrolled windows may use overlayed scrolling indicators. If this is set to %FALSE, scrolled windows will have permanent scrollbars. If the value of this setting is %TRUE, clicking the primary button in a #GtkRange trough will move the slider, and hence set the range’s value, to the point that you clicked. If it is %FALSE, a primary click will cause the slider/value to move by the range’s page-size towards the point clicked. Whichever action you choose for the primary button, the other action will be available by holding Shift and primary-clicking, or (since GTK+ 3.22.25) clicking the middle mouse button. A comma-separated list of print backends to use in the print dialog. Available print backends depend on the GTK+ installation, and may include "file", "cups", "lpr" or "papi". A command to run for displaying the print preview. The command should contain a `%f` placeholder, which will get replaced by the path to the pdf file. The command may also contain a `%s` placeholder, which will get replaced by the path to a file containing the print settings in the format produced by gtk_print_settings_to_file(). The preview application is responsible for removing the pdf file and the print settings file when it is done. Whether GTK+ should keep track of items inside the recently used resources list. If set to %FALSE, the list will always be empty. The number of recently used files that should be displayed by default by #GtkRecentChooser implementations and by the #GtkFileChooser. A value of -1 means every recently used file stored. This setting is ignored The maximum age, in days, of the items inside the recently used resources list. Items older than this setting will be excised from the list. If set to 0, the list will always be empty; if set to -1, no item will be removed. Where the contents of scrolled windows are located with respect to the scrollbars, if not overridden by the scrolled window's own placement. This setting is ignored. This setting is ignored. This setting is ignored. The XDG sound theme to use for event sounds. See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec) for more information on event sounds and sound themes. GTK+ itself does not support event sounds, you have to use a loadable module like the one that comes with libcanberra. This setting is ignored. This setting is ignored. This setting is ignored. This setting determines the action to take when a double-click occurs on the titlebar of client-side decorated windows. Recognized actions are minimize, toggle-maximize, menu, lower or none. This setting determines the action to take when a middle-click occurs on the titlebar of client-side decorated windows. Recognized actions are minimize, toggle-maximize, menu, lower or none. This setting determines the action to take when a right-click occurs on the titlebar of client-side decorated windows. Recognized actions are minimize, toggle-maximize, menu, lower or none. The size of icons in default toolbars. This setting is ignored. The size of icons in default toolbars. This setting is ignored. Amount of time, in milliseconds, after which the browse mode will be disabled. See #GtkSettings:gtk-tooltip-browse-timeout for more information about browse mode. This setting is ignored. Controls the time after which tooltips will appear when browse mode is enabled, in milliseconds. Browse mode is enabled when the mouse pointer moves off an object where a tooltip was currently being displayed. If the mouse pointer hits another object before the browse mode timeout expires (see #GtkSettings:gtk-tooltip-browse-mode-timeout), it will take the amount of milliseconds specified by this setting to popup the tooltip for the new object. This setting is ignored. Time, in milliseconds, after which a tooltip could appear if the cursor is hovering on top of a widget. This setting is ignored. When %TRUE, there are no motion notify events delivered on this screen, and widgets can't use the pointer hovering them for any essential functionality. Generally, the behavior for touchscreen input should be performed dynamically based on gdk_event_get_source_device(). Whether 'focus rectangles' should be always visible, never visible, or hidden until the user starts to use the keyboard. This setting is ignored Origin should be something like “filename:linenumber” for rc files, or e.g. “XProperty” for other sources. Valid types are LONG, DOUBLE and STRING corresponding to the token parsed, or a GSTRING holding an unparsed statement Used to change the appearance of an outline typically provided by a #GtkFrame. Note that many themes do not differentiate the appearance of the various shadow types: Either their is no visible shadow (@GTK_SHADOW_NONE), or there is (any other value). No outline. The outline is bevelled inwards. The outline is bevelled outwards like a button. The outline has a sunken 3d appearance. The outline has a raised 3d appearance. #GtkShortcutLabel is a widget that represents a single keyboard shortcut or gesture in the user interface. Creates a new #GtkShortcutLabel with @accelerator set. a newly-allocated #GtkShortcutLabel the initial accelerator Retrieves the current accelerator of @self. the current accelerator. a #GtkShortcutLabel Retrieves the text that is displayed when no accelerator is set. the current text displayed when no accelerator is set. a #GtkShortcutLabel Sets the accelerator to be displayed by @self. a #GtkShortcutLabel the new accelerator Sets the text to be displayed by @self when no accelerator is set. a #GtkShortcutLabel the text to be displayed when no accelerator is set The accelerator that @self displays. See #GtkShortcutsShortcut:accelerator for the accepted syntax. The text that is displayed when no accelerator is set. GtkShortcutType specifies the kind of shortcut that is being described. More values may be added to this enumeration over time. The shortcut is a keyboard accelerator. The #GtkShortcutsShortcut:accelerator property will be used. The shortcut is a pinch gesture. GTK+ provides an icon and subtitle. The shortcut is a stretch gesture. GTK+ provides an icon and subtitle. The shortcut is a clockwise rotation gesture. GTK+ provides an icon and subtitle. The shortcut is a counterclockwise rotation gesture. GTK+ provides an icon and subtitle. The shortcut is a two-finger swipe gesture. GTK+ provides an icon and subtitle. The shortcut is a two-finger swipe gesture. GTK+ provides an icon and subtitle. The shortcut is a gesture. The #GtkShortcutsShortcut:icon property will be used. A GtkShortcutsGroup represents a group of related keyboard shortcuts or gestures. The group has a title. It may optionally be associated with a view of the application, which can be used to show only relevant shortcuts depending on the application context. This widget is only meant to be used with #GtkShortcutsWindow. The size group for the accelerator portion of shortcuts in this group. This is used internally by GTK+, and must not be modified by applications. A rough measure for the number of lines in this group. This is used internally by GTK+, and is not useful for applications. The title for this group of shortcuts. The size group for the textual portion of shortcuts in this group. This is used internally by GTK+, and must not be modified by applications. An optional view that the shortcuts in this group are relevant for. The group will be hidden if the #GtkShortcutsWindow:view-name property does not match the view of this group. Set this to %NULL to make the group always visible. A GtkShortcutsSection collects all the keyboard shortcuts and gestures for a major application mode. If your application needs multiple sections, you should give each section a unique #GtkShortcutsSection:section-name and a #GtkShortcutsSection:title that can be shown in the section selector of the GtkShortcutsWindow. The #GtkShortcutsSection:max-height property can be used to influence how the groups in the section are distributed over pages and columns. This widget is only meant to be used with #GtkShortcutsWindow. The maximum number of lines to allow per column. This property can be used to influence how the groups in this section are distributed across pages and columns. The default value of 15 should work in most cases. A unique name to identify this section among the sections added to the GtkShortcutsWindow. Setting the #GtkShortcutsWindow:section-name property to this string will make this section shown in the GtkShortcutsWindow. The string to show in the section selector of the GtkShortcutsWindow for this section. If there is only one section, you don't need to set a title, since the section selector will not be shown in this case. A view name to filter the groups in this section by. See #GtkShortcutsGroup:view. Applications are expected to use the #GtkShortcutsWindow:view-name property for this purpose. A GtkShortcutsShortcut represents a single keyboard shortcut or gesture with a short text. This widget is only meant to be used with #GtkShortcutsWindow. The size group for the accelerator portion of this shortcut. This is used internally by GTK+, and must not be modified by applications. The accelerator(s) represented by this object. This property is used if #GtkShortcutsShortcut:shortcut-type is set to #GTK_SHORTCUT_ACCELERATOR. The syntax of this property is (an extension of) the syntax understood by gtk_accelerator_parse(). Multiple accelerators can be specified by separating them with a space, but keep in mind that the available width is limited. It is also possible to specify ranges of shortcuts, using `...` between the keys. Sequences of keys can be specified using a `+` or `&` between the keys. Examples: - A single shortcut: `<ctl><alt>delete` - Two alternative shortcuts: `<shift>a Home` - A range of shortcuts: `<alt>1...<alt>9` - Several keys pressed together: `Control_L&Control_R` - A sequence of shortcuts or keys: `<ctl>c+<ctl>x` Use + instead of & when the keys may (or have to be) pressed sequentially (e.g use t+t for 'press the t key twice'). Note that `<`, `>` and `&` need to be escaped as &lt;, &gt; and &amp; when used in .ui files. A detailed action name. If this is set for a shortcut of type %GTK_SHORTCUT_ACCELERATOR, then GTK+ will use the accelerators that are associated with the action via gtk_application_set_accels_for_action(), and setting #GtkShortcutsShortcut::accelerator is not necessary. The text direction for which this shortcut is active. If the shortcut is used regardless of the text direction, set this property to #GTK_TEXT_DIR_NONE. An icon to represent the shortcut or gesture. This property is used if #GtkShortcutsShortcut:shortcut-type is set to #GTK_SHORTCUT_GESTURE. For the other predefined gesture types, GTK+ provides an icon on its own. %TRUE if an icon has been set. The type of shortcut that is represented. The subtitle for the shortcut or gesture. This is typically used for gestures and should be a short, one-line text that describes the gesture itself. For the predefined gesture types, GTK+ provides a subtitle on its own. %TRUE if a subtitle has been set. The textual description for the shortcut or gesture represented by this object. This should be a short string that can fit in a single line. The size group for the textual portion of this shortcut. This is used internally by GTK+, and must not be modified by applications. A GtkShortcutsWindow shows brief information about the keyboard shortcuts and gestures of an application. The shortcuts can be grouped, and you can have multiple sections in this window, corresponding to the major modes of your application. Additionally, the shortcuts can be filtered by the current view, to avoid showing information that is not relevant in the current application context. The recommended way to construct a GtkShortcutsWindow is with GtkBuilder, by populating a #GtkShortcutsWindow with one or more #GtkShortcutsSection objects, which contain #GtkShortcutsGroups that in turn contain objects of class #GtkShortcutsShortcut. # A simple example: ![](gedit-shortcuts.png) This example has as single section. As you can see, the shortcut groups are arranged in columns, and spread across several pages if there are too many to find on a single page. The .ui file for this example can be found [here](https://git.gnome.org/browse/gtk+/tree/demos/gtk-demo/shortcuts-gedit.ui). # An example with multiple views: ![](clocks-shortcuts.png) This example shows a #GtkShortcutsWindow that has been configured to show only the shortcuts relevant to the "stopwatch" view. The .ui file for this example can be found [here](https://git.gnome.org/browse/gtk+/tree/demos/gtk-demo/shortcuts-clocks.ui). # An example with multiple sections: ![](builder-shortcuts.png) This example shows a #GtkShortcutsWindow with two sections, "Editor Shortcuts" and "Terminal Shortcuts". The .ui file for this example can be found [here](https://git.gnome.org/browse/gtk+/tree/demos/gtk-demo/shortcuts-builder.ui). The name of the section to show. This should be the section-name of one of the #GtkShortcutsSection objects that are in this shortcuts window. The view name by which to filter the contents. This should correspond to the #GtkShortcutsGroup:view property of some of the #GtkShortcutsGroup objects that are inside this shortcuts window. Set this to %NULL to show all groups. The ::close signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user uses a keybinding to close the window. The default binding for this signal is the Escape key. The ::search signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user uses a keybinding to start a search. The default binding for this signal is Control-F. #GtkSizeGroup provides a mechanism for grouping a number of widgets together so they all request the same amount of space. This is typically useful when you want a column of widgets to have the same size, but you can’t use a #GtkGrid widget. In detail, the size requested for each widget in a #GtkSizeGroup is the maximum of the sizes that would have been requested for each widget in the size group if they were not in the size group. The mode of the size group (see gtk_size_group_set_mode()) determines whether this applies to the horizontal size, the vertical size, or both sizes. Note that size groups only affect the amount of space requested, not the size that the widgets finally receive. If you want the widgets in a #GtkSizeGroup to actually be the same size, you need to pack them in such a way that they get the size they request and not more. For example, if you are packing your widgets into a table, you would not include the %GTK_FILL flag. #GtkSizeGroup objects are referenced by each widget in the size group, so once you have added all widgets to a #GtkSizeGroup, you can drop the initial reference to the size group with g_object_unref(). If the widgets in the size group are subsequently destroyed, then they will be removed from the size group and drop their references on the size group; when all widgets have been removed, the size group will be freed. Widgets can be part of multiple size groups; GTK+ will compute the horizontal size of a widget from the horizontal requisition of all widgets that can be reached from the widget by a chain of size groups of type %GTK_SIZE_GROUP_HORIZONTAL or %GTK_SIZE_GROUP_BOTH, and the vertical size from the vertical requisition of all widgets that can be reached from the widget by a chain of size groups of type %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH. Note that only non-contextual sizes of every widget are ever consulted by size groups (since size groups have no knowledge of what size a widget will be allocated in one dimension, it cannot derive how much height a widget will receive for a given width). When grouping widgets that trade height for width in mode %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH: the height for the minimum width will be the requested height for all widgets in the group. The same is of course true when horizontally grouping width for height widgets. Widgets that trade height-for-width should set a reasonably large minimum width by way of #GtkLabel:width-chars for instance. Widgets with static sizes as well as widgets that grow (such as ellipsizing text) need no such considerations. # GtkSizeGroup as GtkBuildable Size groups can be specified in a UI definition by placing an `<object>` element with `class="GtkSizeGroup"` somewhere in the UI definition. The widgets that belong to the size group are specified by a `<widgets>` element that may contain multiple `<widget>` elements, one for each member of the size group. The ”name” attribute gives the id of the widget. An example of a UI definition fragment with GtkSizeGroup: |[<!-- language="xml" --> <object class="GtkSizeGroup"> <property name="mode">GTK_SIZE_GROUP_HORIZONTAL</property> <widgets> <widget name="radio1"/> <widget name="radio2"/> </widgets> </object> ]| Create a new #GtkSizeGroup. a newly created #GtkSizeGroup the mode for the new size group. Adds a widget to a #GtkSizeGroup. In the future, the requisition of the widget will be determined as the maximum of its requisition and the requisition of the other widgets in the size group. Whether this applies horizontally, vertically, or in both directions depends on the mode of the size group. See gtk_size_group_set_mode(). When the widget is destroyed or no longer referenced elsewhere, it will be removed from the size group. a #GtkSizeGroup the #GtkWidget to add Returns if invisible widgets are ignored when calculating the size. Measuring the size of hidden widgets has not worked reliably for a long time. In most cases, they will report a size of 0 nowadays, and thus, their size will not affect the other size group members. In effect, size groups will always operate as if this property was %TRUE. Use a #GtkStack instead to hide widgets while still having their size taken into account. %TRUE if invisible widgets are ignored. a #GtkSizeGroup Gets the current mode of the size group. See gtk_size_group_set_mode(). the current mode of the size group. a #GtkSizeGroup Returns the list of widgets associated with @size_group. a #GSList of widgets. The list is owned by GTK+ and should not be modified. a #GtkSizeGroup Removes a widget from a #GtkSizeGroup. a #GtkSizeGroup the #GtkWidget to remove Sets whether unmapped widgets should be ignored when calculating the size. Measuring the size of hidden widgets has not worked reliably for a long time. In most cases, they will report a size of 0 nowadays, and thus, their size will not affect the other size group members. In effect, size groups will always operate as if this property was %TRUE. Use a #GtkStack instead to hide widgets while still having their size taken into account. a #GtkSizeGroup whether unmapped widgets should be ignored when calculating the size Sets the #GtkSizeGroupMode of the size group. The mode of the size group determines whether the widgets in the size group should all have the same horizontal requisition (%GTK_SIZE_GROUP_HORIZONTAL) all have the same vertical requisition (%GTK_SIZE_GROUP_VERTICAL), or should all have the same requisition in both directions (%GTK_SIZE_GROUP_BOTH). a #GtkSizeGroup the mode to set for the size group. If %TRUE, unmapped widgets are ignored when determining the size of the group. Measuring the size of hidden widgets has not worked reliably for a long time. In most cases, they will report a size of 0 nowadays, and thus, their size will not affect the other size group members. In effect, size groups will always operate as if this property was %TRUE. Use a #GtkStack instead to hide widgets while still having their size taken into account. The mode of the size group determines the directions in which the size group affects the requested sizes of its component widgets. group has no effect group affects horizontal requisition group affects vertical requisition group affects both horizontal and vertical requisition Specifies a preference for height-for-width or width-for-height geometry management. Prefer height-for-width geometry management Prefer width-for-height geometry management Don’t trade height-for-width or width-for-height Together with #GtkPlug, #GtkSocket provides the ability to embed widgets from one process into another process in a fashion that is transparent to the user. One process creates a #GtkSocket widget and passes that widget’s window ID to the other process, which then creates a #GtkPlug with that window ID. Any widgets contained in the #GtkPlug then will appear inside the first application’s window. The socket’s window ID is obtained by using gtk_socket_get_id(). Before using this function, the socket must have been realized, and for hence, have been added to its parent. ## Obtaining the window ID of a socket. |[<!-- language="C" --> GtkWidget *socket = gtk_socket_new (); gtk_widget_show (socket); gtk_container_add (GTK_CONTAINER (parent), socket); // The following call is only necessary if one of // the ancestors of the socket is not yet visible. gtk_widget_realize (socket); g_print ("The ID of the sockets window is %#x\n", gtk_socket_get_id (socket)); ]| Note that if you pass the window ID of the socket to another process that will create a plug in the socket, you must make sure that the socket widget is not destroyed until that plug is created. Violating this rule will cause unpredictable consequences, the most likely consequence being that the plug will appear as a separate toplevel window. You can check if the plug has been created by using gtk_socket_get_plug_window(). If it returns a non-%NULL value, then the plug has been successfully created inside of the socket. When GTK+ is notified that the embedded window has been destroyed, then it will destroy the socket as well. You should always, therefore, be prepared for your sockets to be destroyed at any time when the main event loop is running. To prevent this from happening, you can connect to the #GtkSocket::plug-removed signal. The communication between a #GtkSocket and a #GtkPlug follows the [XEmbed Protocol](http://www.freedesktop.org/Standards/xembed-spec). This protocol has also been implemented in other toolkits, e.g. Qt, allowing the same level of integration when embedding a Qt widget in GTK or vice versa. The #GtkPlug and #GtkSocket widgets are only available when GTK+ is compiled for the X11 platform and %GDK_WINDOWING_X11 is defined. They can only be used on a #GdkX11Display. To use #GtkPlug and #GtkSocket, you need to include the `gtk/gtkx.h` header. Create a new empty #GtkSocket. the new #GtkSocket. Adds an XEMBED client, such as a #GtkPlug, to the #GtkSocket. The client may be in the same process or in a different process. To embed a #GtkPlug in a #GtkSocket, you can either create the #GtkPlug with `gtk_plug_new (0)`, call gtk_plug_get_id() to get the window ID of the plug, and then pass that to the gtk_socket_add_id(), or you can call gtk_socket_get_id() to get the window ID for the socket, and call gtk_plug_new() passing in that ID. The #GtkSocket must have already be added into a toplevel window before you can make this call. a #GtkSocket the Window of a client participating in the XEMBED protocol. Gets the window ID of a #GtkSocket widget, which can then be used to create a client embedded inside the socket, for instance with gtk_plug_new(). The #GtkSocket must have already be added into a toplevel window before you can make this call. the window ID for the socket a #GtkSocket. Retrieves the window of the plug. Use this to check if the plug has been created inside of the socket. the window of the plug if available, or %NULL a #GtkSocket. This signal is emitted when a client is successfully added to the socket. This signal is emitted when a client is removed from the socket. The default action is to destroy the #GtkSocket widget, so if you want to reuse it you must add a signal handler that returns %TRUE. %TRUE to stop other handlers from being invoked. Determines the direction of a sort. Sorting is in ascending order. Sorting is in descending order. A #GtkSpinButton is an ideal way to allow the user to set the value of some attribute. Rather than having to directly type a number into a #GtkEntry, GtkSpinButton allows the user to click on one of two arrows to increment or decrement the displayed value. A value can still be typed in, with the bonus that it can be checked to ensure it is in a given range. The main properties of a GtkSpinButton are through an adjustment. See the #GtkAdjustment section for more details about an adjustment's properties. Note that GtkSpinButton will by default make its entry large enough to accomodate the lower and upper bounds of the adjustment, which can lead to surprising results. Best practice is to set both the #GtkEntry:width-chars and #GtkEntry:max-width-chars poperties to the desired number of characters to display in the entry. # CSS nodes |[<!-- language="plain" --> spinbutton.horizontal ├── undershoot.left ├── undershoot.right ├── entry │ ╰── ... ├── button.down ╰── button.up ]| |[<!-- language="plain" --> spinbutton.vertical ├── undershoot.left ├── undershoot.right ├── button.up ├── entry │ ╰── ... ╰── button.down ]| GtkSpinButtons main CSS node has the name spinbutton. It creates subnodes for the entry and the two buttons, with these names. The button nodes have the style classes .up and .down. The GtkEntry subnodes (if present) are put below the entry node. The orientation of the spin button is reflected in the .vertical or .horizontal style class on the main node. ## Using a GtkSpinButton to get an integer |[<!-- language="C" --> // Provides a function to retrieve an integer value from a GtkSpinButton // and creates a spin button to model percentage values. gint grab_int_value (GtkSpinButton *button, gpointer user_data) { return gtk_spin_button_get_value_as_int (button); } void create_integer_spin_button (void) { GtkWidget *window, *button; GtkAdjustment *adjustment; adjustment = gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 0.0); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_container_set_border_width (GTK_CONTAINER (window), 5); // creates the spinbutton, with no decimal places button = gtk_spin_button_new (adjustment, 1.0, 0); gtk_container_add (GTK_CONTAINER (window), button); gtk_widget_show_all (window); } ]| ## Using a GtkSpinButton to get a floating point value |[<!-- language="C" --> // Provides a function to retrieve a floating point value from a // GtkSpinButton, and creates a high precision spin button. gfloat grab_float_value (GtkSpinButton *button, gpointer user_data) { return gtk_spin_button_get_value (button); } void create_floating_spin_button (void) { GtkWidget *window, *button; GtkAdjustment *adjustment; adjustment = gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.0); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_container_set_border_width (GTK_CONTAINER (window), 5); // creates the spinbutton, with three decimal places button = gtk_spin_button_new (adjustment, 0.001, 3); gtk_container_add (GTK_CONTAINER (window), button); gtk_widget_show_all (window); } ]| Creates a new #GtkSpinButton. The new spin button as a #GtkWidget the #GtkAdjustment object that this spin button should use, or %NULL specifies by how much the rate of change in the value will accelerate if you continue to hold down an up/down button or arrow key the number of decimal places to display This is a convenience constructor that allows creation of a numeric #GtkSpinButton without manually creating an adjustment. The value is initially set to the minimum value and a page increment of 10 * @step is the default. The precision of the spin button is equivalent to the precision of @step. Note that the way in which the precision is derived works best if @step is a power of ten. If the resulting precision is not suitable for your needs, use gtk_spin_button_set_digits() to correct it. The new spin button as a #GtkWidget Minimum allowable value Maximum allowable value Increment added or subtracted by spinning the widget Changes the properties of an existing spin button. The adjustment, climb rate, and number of decimal places are updated accordingly. a #GtkSpinButton a #GtkAdjustment to replace the spin button’s existing adjustment, or %NULL to leave its current adjustment unchanged the new climb rate the number of decimal places to display in the spin button Get the adjustment associated with a #GtkSpinButton the #GtkAdjustment of @spin_button a #GtkSpinButton Fetches the precision of @spin_button. See gtk_spin_button_set_digits(). the current precision a #GtkSpinButton Gets the current step and page the increments used by @spin_button. See gtk_spin_button_set_increments(). a #GtkSpinButton location to store step increment, or %NULL location to store page increment, or %NULL Returns whether non-numeric text can be typed into the spin button. See gtk_spin_button_set_numeric(). %TRUE if only numeric text can be entered a #GtkSpinButton Gets the range allowed for @spin_button. See gtk_spin_button_set_range(). a #GtkSpinButton location to store minimum allowed value, or %NULL location to store maximum allowed value, or %NULL Returns whether the values are corrected to the nearest step. See gtk_spin_button_set_snap_to_ticks(). %TRUE if values are snapped to the nearest step a #GtkSpinButton Gets the update behavior of a spin button. See gtk_spin_button_set_update_policy(). the current update policy a #GtkSpinButton Get the value in the @spin_button. the value of @spin_button a #GtkSpinButton Get the value @spin_button represented as an integer. the value of @spin_button a #GtkSpinButton Returns whether the spin button’s value wraps around to the opposite limit when the upper or lower limit of the range is exceeded. See gtk_spin_button_set_wrap(). %TRUE if the spin button wraps around a #GtkSpinButton Replaces the #GtkAdjustment associated with @spin_button. a #GtkSpinButton a #GtkAdjustment to replace the existing adjustment Set the precision to be displayed by @spin_button. Up to 20 digit precision is allowed. a #GtkSpinButton the number of digits after the decimal point to be displayed for the spin button’s value Sets the step and page increments for spin_button. This affects how quickly the value changes when the spin button’s arrows are activated. a #GtkSpinButton increment applied for a button 1 press. increment applied for a button 2 press. Sets the flag that determines if non-numeric text can be typed into the spin button. a #GtkSpinButton flag indicating if only numeric entry is allowed Sets the minimum and maximum allowable values for @spin_button. If the current value is outside this range, it will be adjusted to fit within the range, otherwise it will remain unchanged. a #GtkSpinButton minimum allowable value maximum allowable value Sets the policy as to whether values are corrected to the nearest step increment when a spin button is activated after providing an invalid value. a #GtkSpinButton a flag indicating if invalid values should be corrected Sets the update behavior of a spin button. This determines whether the spin button is always updated or only when a valid value is set. a #GtkSpinButton a #GtkSpinButtonUpdatePolicy value Sets the value of @spin_button. a #GtkSpinButton the new value Sets the flag that determines if a spin button value wraps around to the opposite limit when the upper or lower limit of the range is exceeded. a #GtkSpinButton a flag indicating if wrapping behavior is performed Increment or decrement a spin button’s value in a specified direction by a specified amount. a #GtkSpinButton a #GtkSpinType indicating the direction to spin step increment to apply in the specified direction Manually force an update of the spin button. a #GtkSpinButton The ::change-value signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a value change. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal are Up/Down and PageUp and/PageDown. a #GtkScrollType to specify the speed and amount of change The ::input signal can be used to influence the conversion of the users input into a double value. The signal handler is expected to use gtk_entry_get_text() to retrieve the text of the entry and set @new_value to the new value. The default conversion uses g_strtod(). %TRUE for a successful conversion, %FALSE if the input was not handled, and %GTK_INPUT_ERROR if the conversion failed. return location for the new value The ::output signal can be used to change to formatting of the value that is displayed in the spin buttons entry. |[<!-- language="C" --> // show leading zeros static gboolean on_output (GtkSpinButton *spin, gpointer data) { GtkAdjustment *adjustment; gchar *text; int value; adjustment = gtk_spin_button_get_adjustment (spin); value = (int)gtk_adjustment_get_value (adjustment); text = g_strdup_printf ("%02d", value); gtk_entry_set_text (GTK_ENTRY (spin), text); g_free (text); return TRUE; } ]| %TRUE if the value has been displayed The ::value-changed signal is emitted when the value represented by @spinbutton changes. Also see the #GtkSpinButton::output signal. The ::wrapped signal is emitted right after the spinbutton wraps from its maximum to minimum value or vice-versa. The spin button update policy determines whether the spin button displays values even if they are outside the bounds of its adjustment. See gtk_spin_button_set_update_policy(). When refreshing your #GtkSpinButton, the value is always displayed When refreshing your #GtkSpinButton, the value is only displayed if it is valid within the bounds of the spin button's adjustment The values of the GtkSpinType enumeration are used to specify the change to make in gtk_spin_button_spin(). Increment by the adjustments step increment. Decrement by the adjustments step increment. Increment by the adjustments page increment. Decrement by the adjustments page increment. Go to the adjustments lower bound. Go to the adjustments upper bound. Change by a specified amount. A GtkSpinner widget displays an icon-size spinning animation. It is often used as an alternative to a #GtkProgressBar for displaying indefinite activity, instead of actual progress. To start the animation, use gtk_spinner_start(), to stop it use gtk_spinner_stop(). # CSS nodes GtkSpinner has a single CSS node with the name spinner. When the animation is active, the :checked pseudoclass is added to this node. Returns a new spinner widget. Not yet started. a new #GtkSpinner Starts the animation of the spinner. a #GtkSpinner Stops the animation of the spinner. a #GtkSpinner The GtkStack widget is a container which only shows one of its children at a time. In contrast to GtkNotebook, GtkStack does not provide a means for users to change the visible child. Instead, the #GtkStackSwitcher widget can be used with GtkStack to provide this functionality. Transitions between pages can be animated as slides or fades. This can be controlled with gtk_stack_set_transition_type(). These animations respect the #GtkSettings:gtk-enable-animations setting. The GtkStack widget was added in GTK+ 3.10. # CSS nodes GtkStack has a single CSS node named stack. Creates a new #GtkStack container. a new #GtkStack Adds a child to @stack. The child is identified by the @name. a #GtkStack the widget to add the name for @child Adds a child to @stack. The child is identified by the @name. The @title will be used by #GtkStackSwitcher to represent @child in a tab bar, so it should be short. a #GtkStack the widget to add the name for @child a human-readable title for @child Finds the child of the #GtkStack with the name given as the argument. Returns %NULL if there is no child with this name. the requested child of the #GtkStack a #GtkStack the name of the child to find Gets whether @stack is horizontally homogeneous. See gtk_stack_set_hhomogeneous(). whether @stack is horizontally homogeneous. a #GtkStack Gets whether @stack is homogeneous. See gtk_stack_set_homogeneous(). whether @stack is homogeneous. a #GtkStack Returns wether the #GtkStack is set up to interpolate between the sizes of children on page switch. %TRUE if child sizes are interpolated A #GtkStack Returns the amount of time (in milliseconds) that transitions between pages in @stack will take. the transition duration a #GtkStack Returns whether the @stack is currently in a transition from one page to another. %TRUE if the transition is currently running, %FALSE otherwise. a #GtkStack Gets the type of animation that will be used for transitions between pages in @stack. the current transition type of @stack a #GtkStack Gets whether @stack is vertically homogeneous. See gtk_stack_set_vhomogeneous(). whether @stack is vertically homogeneous. a #GtkStack Gets the currently visible child of @stack, or %NULL if there are no visible children. the visible child of the #GtkStack a #GtkStack Returns the name of the currently visible child of @stack, or %NULL if there is no visible child. the name of the visible child of the #GtkStack a #GtkStack Sets the #GtkStack to be horizontally homogeneous or not. If it is homogeneous, the #GtkStack will request the same width for all its children. If it isn't, the stack may change width when a different child becomes visible. a #GtkStack %TRUE to make @stack horizontally homogeneous Sets the #GtkStack to be homogeneous or not. If it is homogeneous, the #GtkStack will request the same size for all its children. If it isn't, the stack may change size when a different child becomes visible. Since 3.16, homogeneity can be controlled separately for horizontal and vertical size, with the #GtkStack:hhomogeneous and #GtkStack:vhomogeneous. a #GtkStack %TRUE to make @stack homogeneous Sets whether or not @stack will interpolate its size when changing the visible child. If the #GtkStack:interpolate-size property is set to %TRUE, @stack will interpolate its size between the current one and the one it'll take after changing the visible child, according to the set transition duration. A #GtkStack the new value Sets the duration that transitions between pages in @stack will take. a #GtkStack the new duration, in milliseconds Sets the type of animation that will be used for transitions between pages in @stack. Available types include various kinds of fades and slides. The transition type can be changed without problems at runtime, so it is possible to change the animation based on the page that is about to become current. a #GtkStack the new transition type Sets the #GtkStack to be vertically homogeneous or not. If it is homogeneous, the #GtkStack will request the same height for all its children. If it isn't, the stack may change height when a different child becomes visible. a #GtkStack %TRUE to make @stack vertically homogeneous Makes @child the visible child of @stack. If @child is different from the currently visible child, the transition between the two will be animated with the current transition type of @stack. Note that the @child widget has to be visible itself (see gtk_widget_show()) in order to become the visible child of @stack. a #GtkStack a child of @stack Makes the child with the given name visible. Note that the child widget has to be visible itself (see gtk_widget_show()) in order to become the visible child of @stack. a #GtkStack the name of the child to make visible the transition type to use Makes the child with the given name visible. If @child is different from the currently visible child, the transition between the two will be animated with the current transition type of @stack. Note that the child widget has to be visible itself (see gtk_widget_show()) in order to become the visible child of @stack. a #GtkStack the name of the child to make visible %TRUE if the stack allocates the same width for all children. %TRUE if the stack allocates the same height for all children. A GtkStackSidebar enables you to quickly and easily provide a consistent "sidebar" object for your user interface. In order to use a GtkStackSidebar, you simply use a GtkStack to organize your UI flow, and add the sidebar to your sidebar area. You can use gtk_stack_sidebar_set_stack() to connect the #GtkStackSidebar to the #GtkStack. # CSS nodes GtkStackSidebar has a single CSS node with name stacksidebar and style class .sidebar. When circumstances require it, GtkStackSidebar adds the .needs-attention style class to the widgets representing the stack pages. Creates a new sidebar. the new #GtkStackSidebar Retrieves the stack. See gtk_stack_sidebar_set_stack(). the associated #GtkStack or %NULL if none has been set explicitly a #GtkStackSidebar Set the #GtkStack associated with this #GtkStackSidebar. The sidebar widget will automatically update according to the order (packing) and items within the given #GtkStack. a #GtkStackSidebar a #GtkStack The GtkStackSwitcher widget acts as a controller for a #GtkStack; it shows a row of buttons to switch between the various pages of the associated stack widget. All the content for the buttons comes from the child properties of the #GtkStack; the button visibility in a #GtkStackSwitcher widget is controlled by the visibility of the child in the #GtkStack. It is possible to associate multiple #GtkStackSwitcher widgets with the same #GtkStack widget. The GtkStackSwitcher widget was added in 3.10. # CSS nodes GtkStackSwitcher has a single CSS node named stackswitcher and style class .stack-switcher. When circumstances require it, GtkStackSwitcher adds the .needs-attention style class to the widgets representing the stack pages. Create a new #GtkStackSwitcher. a new #GtkStackSwitcher. Retrieves the stack. See gtk_stack_switcher_set_stack(). the stack, or %NULL if none has been set explicitly. a #GtkStackSwitcher Sets the stack to control. a #GtkStackSwitcher a #GtkStack Use the "icon-size" property to change the size of the image displayed when a #GtkStackSwitcher is displaying icons. These enumeration values describe the possible transitions between pages in a #GtkStack widget. New values may be added to this enumeration over time. No transition A cross-fade Slide from left to right Slide from right to left Slide from bottom up Slide from top down Slide from left or right according to the children order Slide from top down or bottom up according to the order Cover the old page by sliding up. Since 3.12 Cover the old page by sliding down. Since: 3.12 Cover the old page by sliding to the left. Since: 3.12 Cover the old page by sliding to the right. Since: 3.12 Uncover the new page by sliding up. Since 3.12 Uncover the new page by sliding down. Since: 3.12 Uncover the new page by sliding to the left. Since: 3.12 Uncover the new page by sliding to the right. Since: 3.12 Cover the old page sliding up or uncover the new page sliding down, according to order. Since: 3.12 Cover the old page sliding down or uncover the new page sliding up, according to order. Since: 3.14 Cover the old page sliding left or uncover the new page sliding right, according to order. Since: 3.14 Cover the old page sliding right or uncover the new page sliding left, according to order. Since: 3.14 Describes a widget state. Widget states are used to match the widget against CSS pseudo-classes. Note that GTK extends the regular CSS classes and sometimes uses different names. State during normal operation. Widget is active. Widget has a mouse pointer over it. Widget is selected. Widget is insensitive. Widget is inconsistent. Widget has the keyboard focus. Widget is in a background toplevel window. Widget is in left-to-right text direction. Since 3.8 Widget is in right-to-left text direction. Since 3.8 Widget is a link. Since 3.12 The location the widget points to has already been visited. Since 3.12 Widget is checked. Since 3.14 Widget is highlighted as a drop target for DND. Since 3.20 This type indicates the current state of a widget; the state determines how the widget is drawn. The #GtkStateType enumeration is also used to identify different colors in a #GtkStyle for drawing, so states can be used for subparts of a widget as well as entire widgets. All APIs that are using this enumeration have been deprecated in favor of alternatives using #GtkStateFlags. State during normal operation. State of a currently active widget, such as a depressed button. State indicating that the mouse pointer is over the widget and the widget will respond to mouse clicks. State of a selected item, such the selected row in a list. State indicating that the widget is unresponsive to user actions. The widget is inconsistent, such as checkbuttons or radiobuttons that aren’t either set to %TRUE nor %FALSE, or buttons requiring the user attention. The widget has the keyboard focus. The “system tray” or notification area is normally used for transient icons that indicate some special state. For example, a system tray icon might appear to tell the user that they have new mail, or have an incoming instant message, or something along those lines. The basic idea is that creating an icon in the notification area is less annoying than popping up a dialog. A #GtkStatusIcon object can be used to display an icon in a “system tray”. The icon can have a tooltip, and the user can interact with it by activating it or popping up a context menu. It is very important to notice that status icons depend on the existence of a notification area being available to the user; you should not use status icons as the only way to convey critical information regarding your application, as the notification area may not exist on the user's environment, or may have been removed. You should always check that a status icon has been embedded into a notification area by using gtk_status_icon_is_embedded(), and gracefully recover if the function returns %FALSE. On X11, the implementation follows the [FreeDesktop System Tray Specification](http://www.freedesktop.org/wiki/Specifications/systemtray-spec). Implementations of the “tray” side of this specification can be found e.g. in the GNOME 2 and KDE panel applications. Note that a GtkStatusIcon is not a widget, but just a #GObject. Making it a widget would be impractical, since the system tray on Windows doesn’t allow to embed arbitrary widgets. GtkStatusIcon has been deprecated in 3.14. You should consider using notifications or more modern platform-specific APIs instead. GLib provides the #GNotification API which works well with #GtkApplication on multiple platforms and environments, and should be the preferred mechanism to notify the users of transient status updates. See this [HowDoI](https://wiki.gnome.org/HowDoI/GNotification) for code examples. Creates an empty status icon object. Use #GNotification and #GtkApplication to provide status notifications a new #GtkStatusIcon Creates a status icon displaying the file @filename. The image will be scaled down to fit in the available space in the notification area, if necessary. Use #GNotification and #GtkApplication to provide status notifications a new #GtkStatusIcon a filename Creates a status icon displaying a #GIcon. If the icon is a themed icon, it will be updated when the theme changes. Use #GNotification and #GtkApplication to provide status notifications a new #GtkStatusIcon a #GIcon Creates a status icon displaying an icon from the current icon theme. If the current icon theme is changed, the icon will be updated appropriately. Use #GNotification and #GtkApplication to provide status notifications a new #GtkStatusIcon an icon name Creates a status icon displaying @pixbuf. The image will be scaled down to fit in the available space in the notification area, if necessary. Use #GNotification and #GtkApplication to provide status notifications a new #GtkStatusIcon a #GdkPixbuf Creates a status icon displaying a stock icon. Sample stock icon names are #GTK_STOCK_OPEN, #GTK_STOCK_QUIT. You can register your own stock icon names, see gtk_icon_factory_add_default() and gtk_icon_factory_add(). Use #GNotification and #GtkApplication to provide status notifications a new #GtkStatusIcon a stock icon id Menu positioning function to use with gtk_menu_popup() to position @menu aligned to the status icon @user_data. Use #GNotification and #GtkApplication to provide status notifications; notifications do not have menus, but can have buttons, and actions associated with each button the #GtkMenu return location for the x position return location for the y position whether the first menu item should be offset (pushed in) to be aligned with the menu popup position (only useful for GtkOptionMenu). the status icon to position the menu on Obtains information about the location of the status icon on screen. This information can be used to e.g. position popups like notification bubbles. See gtk_status_icon_position_menu() for a more convenient alternative for positioning menus. Note that some platforms do not allow GTK+ to provide this information, and even on platforms that do allow it, the information is not reliable unless the status icon is embedded in a notification area, see gtk_status_icon_is_embedded(). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, as the platform is responsible for the presentation of notifications %TRUE if the location information has been filled in a #GtkStatusIcon return location for the screen, or %NULL if the information is not needed return location for the area occupied by the status icon, or %NULL return location for the orientation of the panel in which the status icon is embedded, or %NULL. A panel at the top or bottom of the screen is horizontal, a panel at the left or right is vertical. Retrieves the #GIcon being displayed by the #GtkStatusIcon. The storage type of the status icon must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_GICON (see gtk_status_icon_get_storage_type()). The caller of this function does not own a reference to the returned #GIcon. If this function fails, @icon is left unchanged; Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function the displayed icon, or %NULL if the image is empty a #GtkStatusIcon Returns the current value of the has-tooltip property. See #GtkStatusIcon:has-tooltip for more information. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function current value of has-tooltip on @status_icon. a #GtkStatusIcon Gets the name of the icon being displayed by the #GtkStatusIcon. The storage type of the status icon must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_ICON_NAME (see gtk_status_icon_get_storage_type()). The returned string is owned by the #GtkStatusIcon and should not be freed or modified. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function name of the displayed icon, or %NULL if the image is empty. a #GtkStatusIcon Gets the #GdkPixbuf being displayed by the #GtkStatusIcon. The storage type of the status icon must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_PIXBUF (see gtk_status_icon_get_storage_type()). The caller of this function does not own a reference to the returned pixbuf. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function the displayed pixbuf, or %NULL if the image is empty. a #GtkStatusIcon Returns the #GdkScreen associated with @status_icon. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, as notifications are managed by the platform a #GdkScreen. a #GtkStatusIcon Gets the size in pixels that is available for the image. Stock icons and named icons adapt their size automatically if the size of the notification area changes. For other storage types, the size-changed signal can be used to react to size changes. Note that the returned size is only meaningful while the status icon is embedded (see gtk_status_icon_is_embedded()). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, as the representation of a notification is left to the platform the size that is available for the image a #GtkStatusIcon Gets the id of the stock icon being displayed by the #GtkStatusIcon. The storage type of the status icon must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_STOCK (see gtk_status_icon_get_storage_type()). The returned string is owned by the #GtkStatusIcon and should not be freed or modified. Use gtk_status_icon_get_icon_name() instead. stock id of the displayed stock icon, or %NULL if the image is empty. a #GtkStatusIcon Gets the type of representation being used by the #GtkStatusIcon to store image data. If the #GtkStatusIcon has no image data, the return value will be %GTK_IMAGE_EMPTY. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, and #GNotification only supports #GIcon instances the image representation being used a #GtkStatusIcon Gets the title of this tray icon. See gtk_status_icon_set_title(). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function the title of the status icon a #GtkStatusIcon Gets the contents of the tooltip for @status_icon. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function the tooltip text, or %NULL. You should free the returned string with g_free() when done. a #GtkStatusIcon Gets the contents of the tooltip for @status_icon. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function the tooltip text, or %NULL. You should free the returned string with g_free() when done. a #GtkStatusIcon Returns whether the status icon is visible or not. Note that being visible does not guarantee that the user can actually see the icon, see also gtk_status_icon_is_embedded(). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function %TRUE if the status icon is visible a #GtkStatusIcon This function is only useful on the X11/freedesktop.org platform. It returns a window ID for the widget in the underlying status icon implementation. This is useful for the Galago notification service, which can send a window ID in the protocol in order for the server to position notification windows pointing to a status icon reliably. This function is not intended for other use cases which are more likely to be met by one of the non-X11 specific methods, such as gtk_status_icon_position_menu(). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function An 32 bit unsigned integer identifier for the underlying X11 Window a #GtkStatusIcon Returns whether the status icon is embedded in a notification area. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function %TRUE if the status icon is embedded in a notification area. a #GtkStatusIcon Makes @status_icon display the file @filename. See gtk_status_icon_new_from_file() for details. Use #GNotification and #GtkApplication to provide status notifications; you can use g_notification_set_icon() to associate a #GIcon with a notification a #GtkStatusIcon a filename Makes @status_icon display the #GIcon. See gtk_status_icon_new_from_gicon() for details. Use #GNotification and #GtkApplication to provide status notifications; you can use g_notification_set_icon() to associate a #GIcon with a notification a #GtkStatusIcon a GIcon Makes @status_icon display the icon named @icon_name from the current icon theme. See gtk_status_icon_new_from_icon_name() for details. Use #GNotification and #GtkApplication to provide status notifications; you can use g_notification_set_icon() to associate a #GIcon with a notification a #GtkStatusIcon an icon name Makes @status_icon display @pixbuf. See gtk_status_icon_new_from_pixbuf() for details. Use #GNotification and #GtkApplication to provide status notifications; you can use g_notification_set_icon() to associate a #GIcon with a notification a #GtkStatusIcon a #GdkPixbuf or %NULL Makes @status_icon display the stock icon with the id @stock_id. See gtk_status_icon_new_from_stock() for details. Use gtk_status_icon_set_from_icon_name() instead. a #GtkStatusIcon a stock icon id Sets the has-tooltip property on @status_icon to @has_tooltip. See #GtkStatusIcon:has-tooltip for more information. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, but notifications can display an arbitrary amount of text using g_notification_set_body() a #GtkStatusIcon whether or not @status_icon has a tooltip Sets the name of this tray icon. This should be a string identifying this icon. It is may be used for sorting the icons in the tray and will not be shown to the user. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, as notifications are associated with a unique application identifier by #GApplication a #GtkStatusIcon the name Sets the #GdkScreen where @status_icon is displayed; if the icon is already mapped, it will be unmapped, and then remapped on the new screen. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, as GTK typically only has one #GdkScreen and notifications are managed by the platform a #GtkStatusIcon a #GdkScreen Sets the title of this tray icon. This should be a short, human-readable, localized string describing the tray icon. It may be used by tools like screen readers to render the tray icon. Use #GNotification and #GtkApplication to provide status notifications; you should use g_notification_set_title() and g_notification_set_body() to present text inside your notification a #GtkStatusIcon the title Sets @markup as the contents of the tooltip, which is marked up with the [Pango text markup language][PangoMarkupFormat]. This function will take care of setting #GtkStatusIcon:has-tooltip to %TRUE and of the default handler for the #GtkStatusIcon::query-tooltip signal. See also the #GtkStatusIcon:tooltip-markup property and gtk_tooltip_set_markup(). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function a #GtkStatusIcon the contents of the tooltip for @status_icon, or %NULL Sets @text as the contents of the tooltip. This function will take care of setting #GtkStatusIcon:has-tooltip to %TRUE and of the default handler for the #GtkStatusIcon::query-tooltip signal. See also the #GtkStatusIcon:tooltip-text property and gtk_tooltip_set_text(). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function a #GtkStatusIcon the contents of the tooltip for @status_icon Shows or hides a status icon. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, as notifications are managed by the platform a #GtkStatusIcon %TRUE to show the status icon, %FALSE to hide it %TRUE if the statusicon is embedded in a notification area. The #GIcon displayed in the #GtkStatusIcon. For themed icons, the image will be updated automatically if the theme changes. Enables or disables the emission of #GtkStatusIcon::query-tooltip on @status_icon. A value of %TRUE indicates that @status_icon can have a tooltip, in this case the status icon will be queried using #GtkStatusIcon::query-tooltip to determine whether it will provide a tooltip or not. Note that setting this property to %TRUE for the first time will change the event masks of the windows of this status icon to include leave-notify and motion-notify events. This will not be undone when the property is set to %FALSE again. Whether this property is respected is platform dependent. For plain text tooltips, use #GtkStatusIcon:tooltip-text in preference. The orientation of the tray in which the statusicon is embedded. Use #GtkStatusIcon:icon-name instead. The title of this tray icon. This should be a short, human-readable, localized string describing the tray icon. It may be used by tools like screen readers to render the tray icon. Sets the text of tooltip to be the given string, which is marked up with the [Pango text markup language][PangoMarkupFormat]. Also see gtk_tooltip_set_markup(). This is a convenience property which will take care of getting the tooltip shown if the given string is not %NULL. #GtkStatusIcon:has-tooltip will automatically be set to %TRUE and the default handler for the #GtkStatusIcon::query-tooltip signal will take care of displaying the tooltip. On some platforms, embedded markup will be ignored. Sets the text of tooltip to be the given string. Also see gtk_tooltip_set_text(). This is a convenience property which will take care of getting the tooltip shown if the given string is not %NULL. #GtkStatusIcon:has-tooltip will automatically be set to %TRUE and the default handler for the #GtkStatusIcon::query-tooltip signal will take care of displaying the tooltip. Note that some platforms have limitations on the length of tooltips that they allow on status icons, e.g. Windows only shows the first 64 characters. Gets emitted when the user activates the status icon. If and how status icons can activated is platform-dependent. Unlike most G_SIGNAL_ACTION signals, this signal is meant to be used by applications and should be wrapped by language bindings. The ::button-press-event signal will be emitted when a button (typically from a mouse) is pressed. Whether this event is emitted is platform-dependent. Use the ::activate and ::popup-menu signals in preference. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventButton which triggered this signal The ::button-release-event signal will be emitted when a button (typically from a mouse) is released. Whether this event is emitted is platform-dependent. Use the ::activate and ::popup-menu signals in preference. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventButton which triggered this signal Gets emitted when the user brings up the context menu of the status icon. Whether status icons can have context menus and how these are activated is platform-dependent. The @button and @activate_time parameters should be passed as the last to arguments to gtk_menu_popup(). Unlike most G_SIGNAL_ACTION signals, this signal is meant to be used by applications and should be wrapped by language bindings. the button that was pressed, or 0 if the signal is not emitted in response to a button press event the timestamp of the event that triggered the signal emission Emitted when the hover timeout has expired with the cursor hovering above @status_icon; or emitted when @status_icon got focus in keyboard mode. Using the given coordinates, the signal handler should determine whether a tooltip should be shown for @status_icon. If this is the case %TRUE should be returned, %FALSE otherwise. Note that if @keyboard_mode is %TRUE, the values of @x and @y are undefined and should not be used. The signal handler is free to manipulate @tooltip with the therefore destined function calls. Whether this signal is emitted is platform-dependent. For plain text tooltips, use #GtkStatusIcon:tooltip-text in preference. %TRUE if @tooltip should be shown right now, %FALSE otherwise. the x coordinate of the cursor position where the request has been emitted, relative to @status_icon the y coordinate of the cursor position where the request has been emitted, relative to @status_icon %TRUE if the tooltip was trigged using the keyboard a #GtkTooltip The ::scroll-event signal is emitted when a button in the 4 to 7 range is pressed. Wheel mice are usually configured to generate button press events for buttons 4 and 5 when the wheel is turned. Whether this event is emitted is platform-dependent. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventScroll which triggered this signal Gets emitted when the size available for the image changes, e.g. because the notification area got resized. %TRUE if the icon was updated for the new size. Otherwise, GTK+ will scale the icon as necessary. the new size A #GtkStatusbar is usually placed along the bottom of an application's main #GtkWindow. It may provide a regular commentary of the application's status (as is usually the case in a web browser, for example), or may be used to simply output a message when the status changes, (when an upload is complete in an FTP client, for example). Status bars in GTK+ maintain a stack of messages. The message at the top of the each bar’s stack is the one that will currently be displayed. Any messages added to a statusbar’s stack must specify a context id that is used to uniquely identify the source of a message. This context id can be generated by gtk_statusbar_get_context_id(), given a message and the statusbar that it will be added to. Note that messages are stored in a stack, and when choosing which message to display, the stack structure is adhered to, regardless of the context identifier of a message. One could say that a statusbar maintains one stack of messages for display purposes, but allows multiple message producers to maintain sub-stacks of the messages they produced (via context ids). Status bars are created using gtk_statusbar_new(). Messages are added to the bar’s stack with gtk_statusbar_push(). The message at the top of the stack can be removed using gtk_statusbar_pop(). A message can be removed from anywhere in the stack if its message id was recorded at the time it was added. This is done using gtk_statusbar_remove(). # CSS node GtkStatusbar has a single CSS node with name statusbar. Creates a new #GtkStatusbar ready for messages. the new #GtkStatusbar Returns a new context identifier, given a description of the actual context. Note that the description is not shown in the UI. an integer id a #GtkStatusbar textual description of what context the new message is being used in Retrieves the box containing the label widget. a #GtkBox a #GtkStatusbar Removes the first message in the #GtkStatusbar’s stack with the given context id. Note that this may not change the displayed message, if the message at the top of the stack has a different context id. a #GtkStatusbar a context identifier Pushes a new message onto a statusbar’s stack. a message id that can be used with gtk_statusbar_remove(). a #GtkStatusbar the message’s context id, as returned by gtk_statusbar_get_context_id() the message to add to the statusbar Forces the removal of a message from a statusbar’s stack. The exact @context_id and @message_id must be specified. a #GtkStatusbar a context identifier a message identifier, as returned by gtk_statusbar_push() Forces the removal of all messages from a statusbar's stack with the exact @context_id. a #GtkStatusbar a context identifier Is emitted whenever a new message is popped off a statusbar's stack. the context id of the relevant message/statusbar the message that was just popped Is emitted whenever a new message gets pushed onto a statusbar's stack. the context id of the relevant message/statusbar the message that was pushed Identifier. User visible label. Modifier type for keyboard accelerator Keyboard accelerator Translation domain of the menu or toolbar item Copies a stock item, mostly useful for language bindings and not in applications. a new #GtkStockItem a #GtkStockItem Frees a stock item allocated on the heap, such as one returned by gtk_stock_item_copy(). Also frees the fields inside the stock item, if they are not %NULL. a #GtkStockItem A #GtkStyle object encapsulates the information that provides the look and feel for a widget. > In GTK+ 3.0, GtkStyle has been deprecated and replaced by > #GtkStyleContext. Each #GtkWidget has an associated #GtkStyle object that is used when rendering that widget. Also, a #GtkStyle holds information for the five possible widget states though not every widget supports all five states; see #GtkStateType. Usually the #GtkStyle for a widget is the same as the default style that is set by GTK+ and modified the theme engine. Usually applications should not need to use or modify the #GtkStyle of their widgets. Creates a new #GtkStyle. Use #GtkStyleContext a new #GtkStyle. Renders the icon specified by @source at the given @size according to the given parameters and returns the result in a pixbuf. Use gtk_render_icon_pixbuf() instead a newly-created #GdkPixbuf containing the rendered icon a #GtkStyle the #GtkIconSource specifying the icon to render a text direction a state the size to render the icon at (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale. the widget a style detail Sets the background of @window to the background color or pixmap specified by @style for the given state. Use gtk_style_context_set_background() instead a #GtkStyle a #GdkWindow a state Use #GtkStyleContext instead Attaches a style to a window; this process allocates the colors and creates the GC’s for the style - it specializes it to a particular visual. The process may involve the creation of a new style if the style has already been attached to a window with a different style and visual. Since this function may return a new object, you have to use it in the following way: `style = gtk_style_attach (style, window)` Use gtk_widget_style_attach() instead Either @style, or a newly-created #GtkStyle. If the style is newly created, the style parameter will be unref'ed, and the new style will have a reference count belonging to the caller. a #GtkStyle. a #GdkWindow. Creates a copy of the passed in #GtkStyle object. Use #GtkStyleContext instead a copy of @style a #GtkStyle Detaches a style from a window. If the style is not attached to any windows anymore, it is unrealized. See gtk_style_attach(). Use #GtkStyleContext instead a #GtkStyle Gets the values of a multiple style properties for @widget_type from @style. a #GtkStyle the #GType of a descendant of #GtkWidget the name of the first style property to get pairs of property names and locations to return the property values, starting with the location for @first_property_name, terminated by %NULL. Queries the value of a style property corresponding to a widget class is in the given style. a #GtkStyle the #GType of a descendant of #GtkWidget the name of the style property to get a #GValue where the value of the property being queried will be stored Non-vararg variant of gtk_style_get(). Used primarily by language bindings. a #GtkStyle the #GType of a descendant of #GtkWidget the name of the first style property to get a va_list of pairs of property names and locations to return the property values, starting with the location for @first_property_name. Returns whether @style has an associated #GtkStyleContext. %TRUE if @style has a #GtkStyleContext a #GtkStyle Looks up @color_name in the style’s logical color mappings, filling in @color and returning %TRUE if found, otherwise returning %FALSE. Do not cache the found mapping, because it depends on the #GtkStyle and might change when a theme switch occurs. Use gtk_style_context_lookup_color() instead %TRUE if the mapping was found. a #GtkStyle the name of the logical color to look up the #GdkColor to fill in Looks up @stock_id in the icon factories associated with @style and the default icon factory, returning an icon set if found, otherwise %NULL. Use gtk_style_context_lookup_icon_set() instead icon set of @stock_id a #GtkStyle an icon name Renders the icon specified by @source at the given @size according to the given parameters and returns the result in a pixbuf. Use gtk_render_icon_pixbuf() instead a newly-created #GdkPixbuf containing the rendered icon a #GtkStyle the #GtkIconSource specifying the icon to render a text direction a state the size to render the icon at (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale. the widget a style detail Sets the background of @window to the background color or pixmap specified by @style for the given state. Use gtk_style_context_set_background() instead a #GtkStyle a #GdkWindow a state Set of foreground #GdkColor Set of background #GdkColor Set of light #GdkColor Set of dark #GdkColor Set of mid #GdkColor Set of text #GdkColor Set of base #GdkColor Color halfway between text/base #GdkColor to use for black #GdkColor to use for white #PangoFontDescription Thickness in X direction Thickness in Y direction Set of background #cairo_pattern_t Emitted when the style has been initialized for a particular visual. Connecting to this signal is probably seldom useful since most of the time applications and widgets only deal with styles that have been already realized. Emitted when the aspects of the style specific to a particular visual is being cleaned up. A connection to this signal can be useful if a widget wants to cache objects as object data on #GtkStyle. This signal provides a convenient place to free such cached objects. The parent class. a #GtkStyle a #GdkWindow a state a newly-created #GdkPixbuf containing the rendered icon a #GtkStyle the #GtkIconSource specifying the icon to render a text direction a state the size to render the icon at (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale. the widget a style detail #GtkStyleContext is an object that stores styling information affecting a widget defined by #GtkWidgetPath. In order to construct the final style information, #GtkStyleContext queries information from all attached #GtkStyleProviders. Style providers can be either attached explicitly to the context through gtk_style_context_add_provider(), or to the screen through gtk_style_context_add_provider_for_screen(). The resulting style is a combination of all providers’ information in priority order. For GTK+ widgets, any #GtkStyleContext returned by gtk_widget_get_style_context() will already have a #GtkWidgetPath, a #GdkScreen and RTL/LTR information set. The style context will also be updated automatically if any of these settings change on the widget. If you are using the theming layer standalone, you will need to set a widget path and a screen yourself to the created style context through gtk_style_context_set_path() and possibly gtk_style_context_set_screen(). See the “Foreign drawing“ example in gtk3-demo. # Style Classes # {#gtkstylecontext-classes} Widgets can add style classes to their context, which can be used to associate different styles by class. The documentation for individual widgets lists which style classes it uses itself, and which style classes may be added by applications to affect their appearance. GTK+ defines macros for a number of style classes. # Style Regions Widgets can also add regions with flags to their context. This feature is deprecated and will be removed in a future GTK+ update. Please use style classes instead. GTK+ defines macros for a number of style regions. # Custom styling in UI libraries and applications If you are developing a library with custom #GtkWidgets that render differently than standard components, you may need to add a #GtkStyleProvider yourself with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK priority, either a #GtkCssProvider or a custom object implementing the #GtkStyleProvider interface. This way themes may still attempt to style your UI elements in a different way if needed so. If you are using custom styling on an applications, you probably want then to make your style information prevail to the theme’s, so you must use a #GtkStyleProvider with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION priority, keep in mind that the user settings in `XDG_CONFIG_HOME/gtk-3.0/gtk.css` will still take precedence over your changes, as it uses the %GTK_STYLE_PROVIDER_PRIORITY_USER priority. Creates a standalone #GtkStyleContext, this style context won’t be attached to any widget, so you may want to call gtk_style_context_set_path() yourself. This function is only useful when using the theming layer separated from GTK+, if you are using #GtkStyleContext to theme #GtkWidgets, use gtk_widget_get_style_context() in order to get a style context ready to theme the widget. A newly created #GtkStyleContext. Adds a global style provider to @screen, which will be used in style construction for all #GtkStyleContexts under @screen. GTK+ uses this to make styling information from #GtkSettings available. Note: If both priorities are the same, A #GtkStyleProvider added through gtk_style_context_add_provider() takes precedence over another added through this function. a #GdkScreen a #GtkStyleProvider the priority of the style provider. The lower it is, the earlier it will be used in the style construction. Typically this will be in the range between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and %GTK_STYLE_PROVIDER_PRIORITY_USER Removes @provider from the global style providers list in @screen. a #GdkScreen a #GtkStyleProvider This function recomputes the styles for all widgets under a particular #GdkScreen. This is useful when some global parameter has changed that affects the appearance of all widgets, because when a widget gets a new style, it will both redraw and recompute any cached information about its appearance. As an example, it is used when the color scheme changes in the related #GtkSettings object. a #GdkScreen Adds a style class to @context, so posterior calls to gtk_style_context_get() or any of the gtk_render_*() functions will make use of this new class for styling. In the CSS file format, a #GtkEntry defining a “search” class, would be matched by: |[ <!-- language="CSS" --> entry.search { ... } ]| While any widget defining a “search” class would be matched by: |[ <!-- language="CSS" --> .search { ... } ]| a #GtkStyleContext class name to use in styling Adds a style provider to @context, to be used in style construction. Note that a style provider added by this function only affects the style of the widget to which @context belongs. If you want to affect the style of all widgets, use gtk_style_context_add_provider_for_screen(). Note: If both priorities are the same, a #GtkStyleProvider added through this function takes precedence over another added through gtk_style_context_add_provider_for_screen(). a #GtkStyleContext a #GtkStyleProvider the priority of the style provider. The lower it is, the earlier it will be used in the style construction. Typically this will be in the range between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and %GTK_STYLE_PROVIDER_PRIORITY_USER Adds a region to @context, so posterior calls to gtk_style_context_get() or any of the gtk_render_*() functions will make use of this new region for styling. In the CSS file format, a #GtkTreeView defining a “row” region, would be matched by: |[ <!-- language="CSS" --> treeview row { ... } ]| Pseudo-classes are used for matching @flags, so the two following rules: |[ <!-- language="CSS" --> treeview row:nth-child(even) { ... } treeview row:nth-child(odd) { ... } ]| would apply to even and odd rows, respectively. Region names must only contain lowercase letters and “-”, starting always with a lowercase letter. a #GtkStyleContext region name to use in styling flags that apply to the region Stops all running animations for @region_id and all animatable regions underneath. A %NULL @region_id will stop all ongoing animations in @context, when dealing with a #GtkStyleContext obtained through gtk_widget_get_style_context(), this is normally done for you in all circumstances you would expect all widget to be stopped, so this should be only used in complex widgets with different animatable regions. This function does nothing. a #GtkStyleContext animatable region to stop, or %NULL. See gtk_style_context_push_animatable_region() Retrieves several style property values from @context for a given state. See gtk_style_context_get_property() for details. For the property name / return value pairs, it works similarly as g_object_get(). Example: |[<!-- language="C" --> GdkRGBA *background_color = NULL; PangoFontDescription *font_desc = NULL; gint border_radius = 0; gtk_style_context_get (style_context, gtk_style_context_get_state (style_context), GTK_STYLE_PROPERTY_BACKGROUND_COLOR, &background_color, GTK_STYLE_PROPERTY_FONT, &font_desc, GTK_STYLE_PROPERTY_BORDER_RADIUS, &border_radius, NULL); // Do something with the property values. if (background_color != NULL) gdk_rgba_free (background_color); if (font_desc != NULL) pango_font_description_free (font_desc); ]| a #GtkStyleContext state to retrieve the property values for property name / return value pairs, followed by %NULL Gets the background color for a given state. This function is far less useful than it seems, and it should not be used in newly written code. CSS has no concept of "background color", as a background can be an image, or a gradient, or any other pattern including solid colors. The only reason why you would call gtk_style_context_get_background_color() is to use the returned value to draw the background with it; the correct way to achieve this result is to use gtk_render_background() instead, along with CSS style classes to modify the color to be rendered. Use gtk_render_background() instead. a #GtkStyleContext state to retrieve the color for return value for the background color Gets the border for a given state as a #GtkBorder. See gtk_style_context_get_property() and #GTK_STYLE_PROPERTY_BORDER_WIDTH for details. a #GtkStyleContext state to retrieve the border for return value for the border settings Gets the border color for a given state. Use gtk_render_frame() instead. a #GtkStyleContext state to retrieve the color for return value for the border color Gets the foreground color for a given state. See gtk_style_context_get_property() and #GTK_STYLE_PROPERTY_COLOR for details. a #GtkStyleContext state to retrieve the color for return value for the foreground color Returns the widget direction used for rendering. Use gtk_style_context_get_state() and check for #GTK_STATE_FLAG_DIR_LTR and #GTK_STATE_FLAG_DIR_RTL instead. the widget direction a #GtkStyleContext Returns the font description for a given state. The returned object is const and will remain valid until the #GtkStyleContext::changed signal happens. Use gtk_style_context_get() for "font" or subproperties instead. the #PangoFontDescription for the given state. This object is owned by GTK+ and should not be freed. a #GtkStyleContext state to retrieve the font for Returns the #GdkFrameClock to which @context is attached. a #GdkFrameClock, or %NULL if @context does not have an attached frame clock. a #GtkStyleContext Returns the sides where rendered elements connect visually with others. the junction sides a #GtkStyleContext Gets the margin for a given state as a #GtkBorder. See gtk_style_property_get() and #GTK_STYLE_PROPERTY_MARGIN for details. a #GtkStyleContext state to retrieve the border for return value for the margin settings Gets the padding for a given state as a #GtkBorder. See gtk_style_context_get() and #GTK_STYLE_PROPERTY_PADDING for details. a #GtkStyleContext state to retrieve the padding for return value for the padding settings Gets the parent context set via gtk_style_context_set_parent(). See that function for details. the parent context or %NULL a #GtkStyleContext Returns the widget path used for style matching. A #GtkWidgetPath a #GtkStyleContext Gets a style property from @context for the given state. Note that not all CSS properties that are supported by GTK+ can be retrieved in this way, since they may not be representable as #GValue. GTK+ defines macros for a number of properties that can be used with this function. Note that passing a state other than the current state of @context is not recommended unless the style context has been saved with gtk_style_context_save(). When @value is no longer needed, g_value_unset() must be called to free any allocated memory. a #GtkStyleContext style property name state to retrieve the property value for return location for the style property value Returns the scale used for assets. the scale a #GtkStyleContext Returns the #GdkScreen to which @context is attached. a #GdkScreen. a #GtkStyleContext Queries the location in the CSS where @property was defined for the current @context. Note that the state to be queried is taken from gtk_style_context_get_state(). If the location is not available, %NULL will be returned. The location might not be available for various reasons, such as the property being overridden, @property not naming a supported CSS property or tracking of definitions being disabled for performance reasons. Shorthand CSS properties cannot be queried for a location and will always return %NULL. %NULL or the section where a value for @property was defined a #GtkStyleContext style property name Returns the state used for style matching. This method should only be used to retrieve the #GtkStateFlags to pass to #GtkStyleContext methods, like gtk_style_context_get_padding(). If you need to retrieve the current state of a #GtkWidget, use gtk_widget_get_state_flags(). the state flags a #GtkStyleContext Retrieves several widget style properties from @context according to the current style. a #GtkStyleContext property name /return value pairs, followed by %NULL Gets the value for a widget style property. When @value is no longer needed, g_value_unset() must be called to free any allocated memory. a #GtkStyleContext the name of the widget style property Return location for the property value Retrieves several widget style properties from @context according to the current style. a #GtkStyleContext va_list of property name/return location pairs, followed by %NULL Retrieves several style property values from @context for a given state. See gtk_style_context_get_property() for details. a #GtkStyleContext state to retrieve the property values for va_list of property name/return location pairs, followed by %NULL Returns %TRUE if @context currently has defined the given class name. %TRUE if @context has @class_name defined a #GtkStyleContext a class name Returns %TRUE if @context has the region defined. If @flags_return is not %NULL, it is set to the flags affecting the region. %TRUE if region is defined a #GtkStyleContext a region name return location for region flags Invalidates @context style information, so it will be reconstructed again. It is useful if you modify the @context and need the new information immediately. Style contexts are invalidated automatically. a #GtkStyleContext. Returns the list of classes currently defined in @context. a #GList of strings with the currently defined classes. The contents of the list are owned by GTK+, but you must free the list itself with g_list_free() when you are done with it. a #GtkStyleContext Returns the list of regions currently defined in @context. a #GList of strings with the currently defined regions. The contents of the list are owned by GTK+, but you must free the list itself with g_list_free() when you are done with it. a #GtkStyleContext Looks up and resolves a color name in the @context color map. %TRUE if @color_name was found and resolved, %FALSE otherwise a #GtkStyleContext color name to lookup Return location for the looked up color Looks up @stock_id in the icon factories associated to @context and the default icon factory, returning an icon set if found, otherwise %NULL. Use gtk_icon_theme_lookup_icon() instead. The looked up %GtkIconSet, or %NULL a #GtkStyleContext an icon name Notifies a state change on @context, so if the current style makes use of transition animations, one will be started so all rendered elements under @region_id are animated for state @state being set to value @state_value. The @window parameter is used in order to invalidate the rendered area as the animation runs, so make sure it is the same window that is being rendered on by the gtk_render_*() functions. If @region_id is %NULL, all rendered elements using @context will be affected by this state transition. As a practical example, a #GtkButton notifying a state transition on the prelight state: |[ <!-- language="C" --> gtk_style_context_notify_state_change (context, gtk_widget_get_window (widget), NULL, GTK_STATE_PRELIGHT, button->in_button); ]| Can be handled in the CSS file like this: |[ <!-- language="CSS" --> button { background-color: #f00 } button:hover { background-color: #fff; transition: 200ms linear } ]| This combination will animate the button background from red to white if a pointer enters the button, and back to red if the pointer leaves the button. Note that @state is used when finding the transition parameters, which is why the style places the transition under the :hover pseudo-class. This function does nothing. a #GtkStyleContext a #GdkWindow animatable region to notify on, or %NULL. See gtk_style_context_push_animatable_region() state to trigger transition for %TRUE if @state is the state we are changing to, %FALSE if we are changing away from it Pops an animatable region from @context. See gtk_style_context_push_animatable_region(). This function does nothing. a #GtkStyleContext Pushes an animatable region, so all further gtk_render_*() calls between this call and the following gtk_style_context_pop_animatable_region() will potentially show transition animations for this region if gtk_style_context_notify_state_change() is called for a given state, and the current theme/style defines transition animations for state changes. The @region_id used must be unique in @context so the themes can uniquely identify rendered elements subject to a state transition. This function does nothing. a #GtkStyleContext unique identifier for the animatable region Removes @class_name from @context. a #GtkStyleContext class name to remove Removes @provider from the style providers list in @context. a #GtkStyleContext a #GtkStyleProvider Removes a region from @context. a #GtkStyleContext region name to unset Restores @context state to a previous stage. See gtk_style_context_save(). a #GtkStyleContext Saves the @context state, so temporary modifications done through gtk_style_context_add_class(), gtk_style_context_remove_class(), gtk_style_context_set_state(), etc. can quickly be reverted in one go through gtk_style_context_restore(). The matching call to gtk_style_context_restore() must be done before GTK returns to the main loop. a #GtkStyleContext This function is analogous to gdk_window_scroll(), and should be called together with it so the invalidation areas for any ongoing animation are scrolled together with it. This function does nothing. a #GtkStyleContext a #GdkWindow used previously in gtk_style_context_notify_state_change() Amount to scroll in the X axis Amount to scroll in the Y axis Sets the background of @window to the background pattern or color specified in @context for its current state. Use gtk_render_background() instead. Note that clients still using this function are now responsible for calling this function again whenever @context is invalidated. a #GtkStyleContext a #GdkWindow Sets the reading direction for rendering purposes. If you are using a #GtkStyleContext returned from gtk_widget_get_style_context(), you do not need to call this yourself. Use gtk_style_context_set_state() with #GTK_STATE_FLAG_DIR_LTR and #GTK_STATE_FLAG_DIR_RTL instead. a #GtkStyleContext the new direction. Attaches @context to the given frame clock. The frame clock is used for the timing of animations. If you are using a #GtkStyleContext returned from gtk_widget_get_style_context(), you do not need to call this yourself. a #GdkFrameClock a #GdkFrameClock Sets the sides where rendered elements (mostly through gtk_render_frame()) will visually connect with other visual elements. This is merely a hint that may or may not be honored by themes. Container widgets are expected to set junction hints as appropriate for their children, so it should not normally be necessary to call this function manually. a #GtkStyleContext sides where rendered elements are visually connected to other elements Sets the parent style context for @context. The parent style context is used to implement [inheritance](http://www.w3.org/TR/css3-cascade/#inheritance) of properties. If you are using a #GtkStyleContext returned from gtk_widget_get_style_context(), the parent will be set for you. a #GtkStyleContext the new parent or %NULL Sets the #GtkWidgetPath used for style matching. As a consequence, the style will be regenerated to match the new given path. If you are using a #GtkStyleContext returned from gtk_widget_get_style_context(), you do not need to call this yourself. a #GtkStyleContext a #GtkWidgetPath Sets the scale to use when getting image assets for the style. a #GtkStyleContext scale Attaches @context to the given screen. The screen is used to add style information from “global” style providers, such as the screen’s #GtkSettings instance. If you are using a #GtkStyleContext returned from gtk_widget_get_style_context(), you do not need to call this yourself. a #GtkStyleContext a #GdkScreen Sets the state to be used for style matching. a #GtkStyleContext state to represent Returns %TRUE if there is a transition animation running for the current region (see gtk_style_context_push_animatable_region()). If @progress is not %NULL, the animation progress will be returned there, 0.0 means the state is closest to being unset, while 1.0 means it’s closest to being set. This means transition animation will run from 0 to 1 when @state is being set and from 1 to 0 when it’s being unset. This function always returns %FALSE %TRUE if there is a running transition animation for @state. a #GtkStyleContext a widget state return location for the transition progress Converts the style context into a string representation. The string representation always includes information about the name, state, id, visibility and style classes of the CSS node that is backing @context. Depending on the flags, more information may be included. This function is intended for testing and debugging of the CSS implementation in GTK+. There are no guarantees about the format of the returned string, it may change. a newly allocated string representing @context a #GtkStyleContext Flags that determine what to print Sets or gets the style context’s parent. See gtk_style_context_set_parent() for details. The ::changed signal is emitted when there is a change in the #GtkStyleContext. For a #GtkStyleContext returned by gtk_widget_get_style_context(), the #GtkWidget::style-updated signal/vfunc might be more convenient to use. This signal is useful when using the theming layer standalone. Flags that modify the behavior of gtk_style_context_to_string(). New values may be added to this enumeration. Print the entire tree of CSS nodes starting at the style context's node Show the values of the CSS properties for each node GtkStyleProperties provides the storage for style information that is used by #GtkStyleContext and other #GtkStyleProvider implementations. Before style properties can be stored in GtkStyleProperties, they must be registered with gtk_style_properties_register_property(). Unless you are writing a #GtkStyleProvider implementation, you are unlikely to use this API directly, as gtk_style_context_get() and its variants are the preferred way to access styling information from widget implementations and theming engine implementations should use the APIs provided by #GtkThemingEngine instead. #GtkStyleProperties has been deprecated in GTK 3.16. The CSS machinery does not use it anymore and all users of this object have been deprecated. Returns a newly created #GtkStyleProperties #GtkStyleProperties are deprecated. a new #GtkStyleProperties Returns %TRUE if a property has been registered, if @pspec or @parse_func are not %NULL, the #GParamSpec and parsing function will be respectively returned. This code could only look up custom properties and those are deprecated. %TRUE if the property is registered, %FALSE otherwise property name to look up return location for the parse function return location for the #GParamSpec Registers a property so it can be used in the CSS file format. This function is the low-level equivalent of gtk_theming_engine_register_property(), if you are implementing a theming engine, you want to use that function instead. Code should use the default properties provided by CSS. parsing function to use, or %NULL the #GParamSpec for the new property Clears all style information from @props. #GtkStyleProperties are deprecated. a #GtkStyleProperties Retrieves several style property values from @props for a given state. #GtkStyleProperties are deprecated. a #GtkStyleProperties state to retrieve the property values for property name /return value pairs, followed by %NULL Gets a style property from @props for the given state. When done with @value, g_value_unset() needs to be called to free any allocated memory. #GtkStyleProperties are deprecated. %TRUE if the property exists in @props, %FALSE otherwise a #GtkStyleProperties style property name state to retrieve the property value for return location for the style property value. Retrieves several style property values from @props for a given state. #GtkStyleProperties are deprecated. a #GtkStyleProperties state to retrieve the property values for va_list of property name/return location pairs, followed by %NULL Returns the symbolic color that is mapped to @name. #GtkSymbolicColor is deprecated. The mapped color a #GtkStyleProperties color name to lookup Maps @color so it can be referenced by @name. See gtk_style_properties_lookup_color() #GtkSymbolicColor is deprecated. a #GtkStyleProperties color name #GtkSymbolicColor to map @name to Merges into @props all the style information contained in @props_to_merge. If @replace is %TRUE, the values will be overwritten, if it is %FALSE, the older values will prevail. #GtkStyleProperties are deprecated. a #GtkStyleProperties a second #GtkStyleProperties whether to replace values or not Sets several style properties on @props. #GtkStyleProperties are deprecated. a #GtkStyleProperties state to set the values for property name/value pairs, followed by %NULL Sets a styling property in @props. #GtkStyleProperties are deprecated. a #GtkStyleProperties styling property to set state to set the value for new value for the property Sets several style properties on @props. #GtkStyleProperties are deprecated. a #GtkStyleProperties state to set the values for va_list of property name/value pairs, followed by %NULL Unsets a style property in @props. #GtkStyleProperties are deprecated. a #GtkStyleProperties property to unset state to unset GtkStyleProvider is an interface used to provide style information to a #GtkStyleContext. See gtk_style_context_add_provider() and gtk_style_context_add_provider_for_screen(). Returns the #GtkIconFactory defined to be in use for @path, or %NULL if none is defined. Will always return %NULL for all GTK-provided style providers. The icon factory to use for @path, or %NULL a #GtkStyleProvider #GtkWidgetPath to query Returns the style settings affecting a widget defined by @path, or %NULL if @provider doesn’t contemplate styling @path. Will always return %NULL for all GTK-provided style providers as the interface cannot correctly work the way CSS is specified. a #GtkStyleProperties containing the style settings affecting @path a #GtkStyleProvider #GtkWidgetPath to query Looks up a widget style property as defined by @provider for the widget represented by @path. %TRUE if the property was found and has a value, %FALSE otherwise a #GtkStyleProvider #GtkWidgetPath to query state to query the style property for The #GParamSpec to query return location for the property value Returns the #GtkIconFactory defined to be in use for @path, or %NULL if none is defined. Will always return %NULL for all GTK-provided style providers. The icon factory to use for @path, or %NULL a #GtkStyleProvider #GtkWidgetPath to query Returns the style settings affecting a widget defined by @path, or %NULL if @provider doesn’t contemplate styling @path. Will always return %NULL for all GTK-provided style providers as the interface cannot correctly work the way CSS is specified. a #GtkStyleProperties containing the style settings affecting @path a #GtkStyleProvider #GtkWidgetPath to query Looks up a widget style property as defined by @provider for the widget represented by @path. %TRUE if the property was found and has a value, %FALSE otherwise a #GtkStyleProvider #GtkWidgetPath to query state to query the style property for The #GParamSpec to query return location for the property value Gets a set of style information that applies to a widget path. a #GtkStyleProperties containing the style settings affecting @path a #GtkStyleProvider #GtkWidgetPath to query Gets the value of a widget style property that applies to a widget path. %TRUE if the property was found and has a value, %FALSE otherwise a #GtkStyleProvider #GtkWidgetPath to query state to query the style property for The #GParamSpec to query return location for the property value Gets the icon factory that applies to a widget path. The icon factory to use for @path, or %NULL a #GtkStyleProvider #GtkWidgetPath to query #GtkSwitch is a widget that has two states: on or off. The user can control which state should be active by clicking the empty area, or by dragging the handle. GtkSwitch can also handle situations where the underlying state changes with a delay. See #GtkSwitch::state-set for details. # CSS nodes |[<!-- language="plain" --> switch ╰── slider ]| GtkSwitch has two css nodes, the main node with the name switch and a subnode named slider. Neither of them is using any style classes. Creates a new #GtkSwitch widget. the newly created #GtkSwitch instance An action signal and emitting it causes the switch to animate. Class handler for the ::state-set signal. Gets whether the #GtkSwitch is in its “on” or “off” state. %TRUE if the #GtkSwitch is active, and %FALSE otherwise a #GtkSwitch Gets the underlying state of the #GtkSwitch. the underlying state a #GtkSwitch Changes the state of @sw to the desired one. a #GtkSwitch %TRUE if @sw should be active, and %FALSE otherwise Sets the underlying state of the #GtkSwitch. Normally, this is the same as #GtkSwitch:active, unless the switch is set up for delayed state changes. This function is typically called from a #GtkSwitch::state-set signal handler. See #GtkSwitch::state-set for details. a #GtkSwitch the new state Whether the #GtkSwitch widget is in its on or off state. The backend state that is controlled by the switch. See #GtkSwitch::state-set for details. The ::activate signal on GtkSwitch is an action signal and emitting it causes the switch to animate. Applications should never connect to this signal, but use the notify::active signal. The ::state-set signal on GtkSwitch is emitted to change the underlying state. It is emitted when the user changes the switch position. The default handler keeps the state in sync with the #GtkSwitch:active property. To implement delayed state change, applications can connect to this signal, initiate the change of the underlying state, and call gtk_switch_set_state() when the underlying state change is complete. The signal handler should return %TRUE to prevent the default handler from running. Visually, the underlying state is represented by the trough color of the switch, while the #GtkSwitch:active property is represented by the position of the switch. %TRUE to stop the signal emission the new state of the switch The parent class. An action signal and emitting it causes the switch to animate. Class handler for the ::state-set signal. GtkSymbolicColor is a boxed type that represents a symbolic color. It is the result of parsing a [color expression][gtkcssprovider-symbolic-colors]. To obtain the color represented by a GtkSymbolicColor, it has to be resolved with gtk_symbolic_color_resolve(), which replaces all symbolic color references by the colors they refer to (in a given context) and evaluates mix, shade and other expressions, resulting in a #GdkRGBA value. It is not normally necessary to deal directly with #GtkSymbolicColors, since they are mostly used behind the scenes by #GtkStyleContext and #GtkCssProvider. #GtkSymbolicColor is deprecated. Symbolic colors are considered an implementation detail of GTK+. Creates a symbolic color by modifying the relative alpha value of @color. A factor < 1.0 would resolve to a more transparent color, while > 1.0 would resolve to a more opaque color. #GtkSymbolicColor is deprecated. A newly created #GtkSymbolicColor another #GtkSymbolicColor factor to apply to @color alpha Creates a symbolic color pointing to a literal color. #GtkSymbolicColor is deprecated. a newly created #GtkSymbolicColor a #GdkRGBA Creates a symbolic color defined as a mix of another two colors. a mix factor of 0 would resolve to @color1, while a factor of 1 would resolve to @color2. #GtkSymbolicColor is deprecated. A newly created #GtkSymbolicColor color to mix another color to mix mix factor Creates a symbolic color pointing to an unresolved named color. See gtk_style_context_lookup_color() and gtk_style_properties_lookup_color(). #GtkSymbolicColor is deprecated. a newly created #GtkSymbolicColor color name Creates a symbolic color defined as a shade of another color. A factor > 1.0 would resolve to a brighter color, while < 1.0 would resolve to a darker color. #GtkSymbolicColor is deprecated. A newly created #GtkSymbolicColor another #GtkSymbolicColor shading factor to apply to @color Creates a symbolic color based on the current win32 theme. Note that while this call is available on all platforms the actual value returned is not reliable on non-win32 platforms. #GtkSymbolicColor is deprecated. A newly created #GtkSymbolicColor The theme class to pull color from The color id Increases the reference count of @color #GtkSymbolicColor is deprecated. the same @color a #GtkSymbolicColor If @color is resolvable, @resolved_color will be filled in with the resolved color, and %TRUE will be returned. Generally, if @color can’t be resolved, it is due to it being defined on top of a named color that doesn’t exist in @props. When @props is %NULL, resolving of named colors will fail, so if your @color is or references such a color, this function will return %FALSE. #GtkSymbolicColor is deprecated. %TRUE if the color has been resolved a #GtkSymbolicColor #GtkStyleProperties to use when resolving named colors, or %NULL return location for the resolved color Converts the given @color to a string representation. This is useful both for debugging and for serialization of strings. The format of the string may change between different versions of GTK, but it is guaranteed that the GTK css parser is able to read the string and create the same symbolic color from it. #GtkSymbolicColor is deprecated. a new string representing @color color to convert to a string Decreases the reference count of @color, freeing its memory if the reference count reaches 0. #GtkSymbolicColor is deprecated. a #GtkSymbolicColor The priority at which the text view validates onscreen lines in an idle job in the background. The GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID can be used to make a #GtkTreeSortable use the default sort function. See also gtk_tree_sortable_set_sort_column_id() The GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID can be used to make a #GtkTreeSortable use no sorting. See also gtk_tree_sortable_set_sort_column_id() The #GtkTable functions allow the programmer to arrange widgets in rows and columns, making it easy to align many widgets next to each other, horizontally and vertically. Tables are created with a call to gtk_table_new(), the size of which can later be changed with gtk_table_resize(). Widgets can be added to a table using gtk_table_attach() or the more convenient (but slightly less flexible) gtk_table_attach_defaults(). To alter the space next to a specific row, use gtk_table_set_row_spacing(), and for a column, gtk_table_set_col_spacing(). The gaps between all rows or columns can be changed by calling gtk_table_set_row_spacings() or gtk_table_set_col_spacings() respectively. Note that spacing is added between the children, while padding added by gtk_table_attach() is added on either side of the widget it belongs to. gtk_table_set_homogeneous(), can be used to set whether all cells in the table will resize themselves to the size of the largest widget in the table. > #GtkTable has been deprecated. Use #GtkGrid instead. It provides the same > capabilities as GtkTable for arranging widgets in a rectangular grid, but > does support height-for-width geometry management. Used to create a new table widget. An initial size must be given by specifying how many rows and columns the table should have, although this can be changed later with gtk_table_resize(). @rows and @columns must both be in the range 1 .. 65535. For historical reasons, 0 is accepted as well and is silently interpreted as 1. Use gtk_grid_new(). A pointer to the newly created table widget. The number of rows the new table should have. The number of columns the new table should have. If set to %TRUE, all table cells are resized to the size of the cell containing the largest widget. Adds a widget to a table. The number of “cells” that a widget will occupy is specified by @left_attach, @right_attach, @top_attach and @bottom_attach. These each represent the leftmost, rightmost, uppermost and lowest column and row numbers of the table. (Columns and rows are indexed from zero). To make a button occupy the lower right cell of a 2x2 table, use |[ gtk_table_attach (table, button, 1, 2, // left, right attach 1, 2, // top, bottom attach xoptions, yoptions, xpadding, ypadding); ]| If you want to make the button span the entire bottom row, use @left_attach == 0 and @right_attach = 2 instead. Use gtk_grid_attach() with #GtkGrid. Note that the attach arguments differ between those two functions. The #GtkTable to add a new widget to. The widget to add. the column number to attach the left side of a child widget to. the column number to attach the right side of a child widget to. the row number to attach the top of a child widget to. the row number to attach the bottom of a child widget to. Used to specify the properties of the child widget when the table is resized. The same as xoptions, except this field determines behaviour of vertical resizing. An integer value specifying the padding on the left and right of the widget being added to the table. The amount of padding above and below the child widget. As there are many options associated with gtk_table_attach(), this convenience function provides the programmer with a means to add children to a table with identical padding and expansion options. The values used for the #GtkAttachOptions are `GTK_EXPAND | GTK_FILL`, and the padding is set to 0. Use gtk_grid_attach() with #GtkGrid. Note that the attach arguments differ between those two functions. The table to add a new child widget to. The child widget to add. The column number to attach the left side of the child widget to. The column number to attach the right side of the child widget to. The row number to attach the top of the child widget to. The row number to attach the bottom of the child widget to. Gets the amount of space between column @col, and column @col + 1. See gtk_table_set_col_spacing(). #GtkGrid does not offer a replacement for this functionality. the column spacing a #GtkTable a column in the table, 0 indicates the first column Gets the default column spacing for the table. This is the spacing that will be used for newly added columns. (See gtk_table_set_col_spacings()) Use gtk_grid_get_column_spacing() with #GtkGrid. the default column spacing a #GtkTable Gets the default row spacing for the table. This is the spacing that will be used for newly added rows. (See gtk_table_set_row_spacings()) Use gtk_grid_get_row_spacing() with #GtkGrid. the default row spacing a #GtkTable Returns whether the table cells are all constrained to the same width and height. (See gtk_table_set_homogeneous ()) Use gtk_grid_get_row_homogeneous() and gtk_grid_get_column_homogeneous() with #GtkGrid. %TRUE if the cells are all constrained to the same size a #GtkTable Gets the amount of space between row @row, and row @row + 1. See gtk_table_set_row_spacing(). #GtkGrid does not offer a replacement for this functionality. the row spacing a #GtkTable a row in the table, 0 indicates the first row Gets the number of rows and columns in the table. #GtkGrid does not expose the number of columns and rows. a #GtkTable return location for the number of rows, or %NULL return location for the number of columns, or %NULL If you need to change a table’s size after it has been created, this function allows you to do so. #GtkGrid resizes automatically. The #GtkTable you wish to change the size of. The new number of rows. The new number of columns. Alters the amount of space between a given table column and the following column. Use gtk_widget_set_margin_start() and gtk_widget_set_margin_end() on the widgets contained in the row if you need this functionality. #GtkGrid does not support per-row spacing. a #GtkTable. the column whose spacing should be changed. number of pixels that the spacing should take up. Sets the space between every column in @table equal to @spacing. Use gtk_grid_set_column_spacing() with #GtkGrid. a #GtkTable. the number of pixels of space to place between every column in the table. Changes the homogenous property of table cells, ie. whether all cells are an equal size or not. Use gtk_grid_set_row_homogeneous() and gtk_grid_set_column_homogeneous() with #GtkGrid. The #GtkTable you wish to set the homogeneous properties of. Set to %TRUE to ensure all table cells are the same size. Set to %FALSE if this is not your desired behaviour. Changes the space between a given table row and the subsequent row. Use gtk_widget_set_margin_top() and gtk_widget_set_margin_bottom() on the widgets contained in the row if you need this functionality. #GtkGrid does not support per-row spacing. a #GtkTable containing the row whose properties you wish to change. row number whose spacing will be changed. number of pixels that the spacing should take up. Sets the space between every row in @table equal to @spacing. Use gtk_grid_set_row_spacing() with #GtkGrid. a #GtkTable. the number of pixels of space to place between every row in the table. A #GtkTargetEntry represents a single type of data than can be supplied for by a widget for a selection or for supplied or received during drag-and-drop. a string representation of the target type #GtkTargetFlags for DND an application-assigned integer ID which will get passed as a parameter to e.g the #GtkWidget::selection-get signal. It allows the application to identify the target type without extensive string compares. Makes a new #GtkTargetEntry. a pointer to a new #GtkTargetEntry. Free with gtk_target_entry_free() String identifier for target Set of flags, see #GtkTargetFlags an ID that will be passed back to the application Makes a copy of a #GtkTargetEntry and its data. a pointer to a copy of @data. Free with gtk_target_entry_free() a pointer to a #GtkTargetEntry Frees a #GtkTargetEntry returned from gtk_target_entry_new() or gtk_target_entry_copy(). a pointer to a #GtkTargetEntry. The #GtkTargetFlags enumeration is used to specify constraints on a #GtkTargetEntry. If this is set, the target will only be selected for drags within a single application. If this is set, the target will only be selected for drags within a single widget. If this is set, the target will not be selected for drags within a single application. If this is set, the target will not be selected for drags withing a single widget. A #GtkTargetList-struct is a reference counted list of #GtkTargetPair and should be treated as opaque. Creates a new #GtkTargetList from an array of #GtkTargetEntry. the new #GtkTargetList. Pointer to an array of #GtkTargetEntry number of entries in @targets. Appends another target to a #GtkTargetList. a #GtkTargetList the interned atom representing the target the flags for this target an ID that will be passed back to the application Appends the image targets supported by #GtkSelectionData to the target list. All targets are added with the same @info. a #GtkTargetList an ID that will be passed back to the application whether to add only targets for which GTK+ knows how to convert a pixbuf into the format Appends the rich text targets registered with gtk_text_buffer_register_serialize_format() or gtk_text_buffer_register_deserialize_format() to the target list. All targets are added with the same @info. a #GtkTargetList an ID that will be passed back to the application if %TRUE, then deserializable rich text formats will be added, serializable formats otherwise. a #GtkTextBuffer. Prepends a table of #GtkTargetEntry to a target list. a #GtkTargetList the table of #GtkTargetEntry number of targets in the table Appends the text targets supported by #GtkSelectionData to the target list. All targets are added with the same @info. a #GtkTargetList an ID that will be passed back to the application Appends the URI targets supported by #GtkSelectionData to the target list. All targets are added with the same @info. Since 3.24.37, this includes the application/vnd.portal.files target when possible, to allow sending files between sandboxed apps via the FileTransfer portal. a #GtkTargetList an ID that will be passed back to the application Looks up a given target in a #GtkTargetList. %TRUE if the target was found, otherwise %FALSE a #GtkTargetList an interned atom representing the target to search for a pointer to the location to store application info for target, or %NULL Increases the reference count of a #GtkTargetList by one. the passed in #GtkTargetList. a #GtkTargetList Removes a target from a target list. a #GtkTargetList the interned atom representing the target Decreases the reference count of a #GtkTargetList by one. If the resulting reference count is zero, frees the list. a #GtkTargetList A #GtkTargetPair is used to represent the same information as a table of #GtkTargetEntry, but in an efficient form. #GdkAtom representation of the target type #GtkTargetFlags for DND an application-assigned integer ID which will get passed as a parameter to e.g the #GtkWidget::selection-get signal. It allows the application to identify the target type without extensive string compares. A #GtkTearoffMenuItem is a special #GtkMenuItem which is used to tear off and reattach its menu. When its menu is shown normally, the #GtkTearoffMenuItem is drawn as a dotted line indicating that the menu can be torn off. Activating it causes its menu to be torn off and displayed in its own window as a tearoff menu. When its menu is shown as a tearoff menu, the #GtkTearoffMenuItem is drawn as a dotted line which has a left pointing arrow graphic indicating that the tearoff menu can be reattached. Activating it will erase the tearoff menu window. > #GtkTearoffMenuItem is deprecated and should not be used in newly > written code. Menus are not meant to be torn around. Creates a new #GtkTearoffMenuItem. #GtkTearoffMenuItem is deprecated and should not be used in newly written code. a new #GtkTearoffMenuItem. The parent class. Background #GdkColor. Foreground #GdkColor. Super/subscript rise, can be negative. #PangoUnderline Strikethrough style Whether to use background-related values; this is irrelevant for the values struct when in a tag, but is used for the composite values struct; it’s true if any of the tags being composited had background stuff set. This are only used when we are actually laying out and rendering a paragraph; not when a #GtkTextAppearance is part of a #GtkTextAttributes. This are only used when we are actually laying out and rendering a paragraph; not when a #GtkTextAppearance is part of a #GtkTextAttributes. Using #GtkTextAttributes directly should rarely be necessary. It’s primarily useful with gtk_text_iter_get_attributes(). As with most GTK+ structs, the fields in this struct should only be read, never modified directly. #GtkTextAppearance for text. #GtkJustification for text. #GtkTextDirection for text. #PangoFontDescription for text. Font scale factor. Width of the left margin in pixels. Width of the right margin in pixels. Amount to indent the paragraph, in pixels. Pixels of blank space above paragraphs. Pixels of blank space below paragraphs. Pixels of blank space between wrapped lines in a paragraph. Custom #PangoTabArray for this text. #GtkWrapMode for text. #PangoLanguage for text. Hide the text. Background is fit to full line height rather than baseline +/- ascent/descent (font height). Can edit this text. Whether to disable font fallback. Extra space to insert between graphemes, in Pango units Creates a #GtkTextAttributes, which describes a set of properties on some text. a new #GtkTextAttributes, free with gtk_text_attributes_unref(). Copies @src and returns a new #GtkTextAttributes. a copy of @src, free with gtk_text_attributes_unref() a #GtkTextAttributes to be copied Copies the values from @src to @dest so that @dest has the same values as @src. Frees existing values in @dest. a #GtkTextAttributes another #GtkTextAttributes Increments the reference count on @values. the #GtkTextAttributes that were passed in a #GtkTextAttributes Decrements the reference count on @values, freeing the structure if the reference count reaches 0. a #GtkTextAttributes You may wish to begin by reading the [text widget conceptual overview](TextWidget.html) which gives an overview of all the objects and data types related to the text widget and how they work together. Creates a new text buffer. a new text buffer a tag table, or %NULL to create a new one Emits the “apply-tag” signal on @buffer. The default handler for the signal applies @tag to the given range. @start and @end do not have to be in order. a #GtkTextBuffer a #GtkTextTag one bound of range to be tagged other bound of range to be tagged Called to indicate that the buffer operations between here and a call to gtk_text_buffer_end_user_action() are part of a single user-visible operation. The operations between gtk_text_buffer_begin_user_action() and gtk_text_buffer_end_user_action() can then be grouped when creating an undo stack. #GtkTextBuffer maintains a count of calls to gtk_text_buffer_begin_user_action() that have not been closed with a call to gtk_text_buffer_end_user_action(), and emits the “begin-user-action” and “end-user-action” signals only for the outermost pair of calls. This allows you to build user actions from other user actions. The “interactive” buffer mutation functions, such as gtk_text_buffer_insert_interactive(), automatically call begin/end user action around the buffer operations they perform, so there's no need to add extra calls if you user action consists solely of a single call to one of those functions. a #GtkTextBuffer The class handler for the #GtkTextBuffer::changed signal. The class handler for the #GtkTextBuffer::delete-range signal. Should be paired with a call to gtk_text_buffer_begin_user_action(). See that function for a full explanation. a #GtkTextBuffer Inserts a child widget anchor into the text buffer at @iter. The anchor will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode “object replacement character” 0xFFFC. Note that the “slice” variants for obtaining portions of the buffer as a string include this character for child anchors, but the “text” variants do not. E.g. see gtk_text_buffer_get_slice() and gtk_text_buffer_get_text(). Consider gtk_text_buffer_create_child_anchor() as a more convenient alternative to this function. The buffer will add a reference to the anchor, so you can unref it after insertion. a #GtkTextBuffer location to insert the anchor a #GtkTextChildAnchor Inserts an image into the text buffer at @iter. The image will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode “object replacement character” 0xFFFC. Note that the “slice” variants for obtaining portions of the buffer as a string include this character for pixbufs, but the “text” variants do not. e.g. see gtk_text_buffer_get_slice() and gtk_text_buffer_get_text(). a #GtkTextBuffer location to insert the pixbuf a #GdkPixbuf The class handler for the #GtkTextBuffer::insert-text signal. The class handler for the #GtkTextBuffer::mark-deleted signal. The class handler for the #GtkTextBuffer::mark-set signal. The class handler for the #GtkTextBuffer::modified-changed signal. The class handler for the #GtkTextBuffer::paste-done signal. Emits the “remove-tag” signal. The default handler for the signal removes all occurrences of @tag from the given range. @start and @end don’t have to be in order. a #GtkTextBuffer a #GtkTextTag one bound of range to be untagged other bound of range to be untagged Adds the mark at position @where. The mark must not be added to another buffer, and if its name is not %NULL then there must not be another mark in the buffer with the same name. Emits the #GtkTextBuffer::mark-set signal as notification of the mark's initial placement. a #GtkTextBuffer the mark to add location to place mark Adds @clipboard to the list of clipboards in which the selection contents of @buffer are available. In most cases, @clipboard will be the #GtkClipboard of type %GDK_SELECTION_PRIMARY for a view of @buffer. a #GtkTextBuffer a #GtkClipboard Emits the “apply-tag” signal on @buffer. The default handler for the signal applies @tag to the given range. @start and @end do not have to be in order. a #GtkTextBuffer a #GtkTextTag one bound of range to be tagged other bound of range to be tagged Calls gtk_text_tag_table_lookup() on the buffer’s tag table to get a #GtkTextTag, then calls gtk_text_buffer_apply_tag(). a #GtkTextBuffer name of a named #GtkTextTag one bound of range to be tagged other bound of range to be tagged Performs the appropriate action as if the user hit the delete key with the cursor at the position specified by @iter. In the normal case a single character will be deleted, but when combining accents are involved, more than one character can be deleted, and when precomposed character and accent combinations are involved, less than one character will be deleted. Because the buffer is modified, all outstanding iterators become invalid after calling this function; however, the @iter will be re-initialized to point to the location where text was deleted. %TRUE if the buffer was modified a #GtkTextBuffer a position in @buffer whether the deletion is caused by user interaction whether the buffer is editable by default Called to indicate that the buffer operations between here and a call to gtk_text_buffer_end_user_action() are part of a single user-visible operation. The operations between gtk_text_buffer_begin_user_action() and gtk_text_buffer_end_user_action() can then be grouped when creating an undo stack. #GtkTextBuffer maintains a count of calls to gtk_text_buffer_begin_user_action() that have not been closed with a call to gtk_text_buffer_end_user_action(), and emits the “begin-user-action” and “end-user-action” signals only for the outermost pair of calls. This allows you to build user actions from other user actions. The “interactive” buffer mutation functions, such as gtk_text_buffer_insert_interactive(), automatically call begin/end user action around the buffer operations they perform, so there's no need to add extra calls if you user action consists solely of a single call to one of those functions. a #GtkTextBuffer Copies the currently-selected text to a clipboard. a #GtkTextBuffer the #GtkClipboard object to copy to This is a convenience function which simply creates a child anchor with gtk_text_child_anchor_new() and inserts it into the buffer with gtk_text_buffer_insert_child_anchor(). The new anchor is owned by the buffer; no reference count is returned to the caller of gtk_text_buffer_create_child_anchor(). the created child anchor a #GtkTextBuffer location in the buffer Creates a mark at position @where. If @mark_name is %NULL, the mark is anonymous; otherwise, the mark can be retrieved by name using gtk_text_buffer_get_mark(). If a mark has left gravity, and text is inserted at the mark’s current location, the mark will be moved to the left of the newly-inserted text. If the mark has right gravity (@left_gravity = %FALSE), the mark will end up on the right of newly-inserted text. The standard left-to-right cursor is a mark with right gravity (when you type, the cursor stays on the right side of the text you’re typing). The caller of this function does not own a reference to the returned #GtkTextMark, so you can ignore the return value if you like. Marks are owned by the buffer and go away when the buffer does. Emits the #GtkTextBuffer::mark-set signal as notification of the mark's initial placement. the new #GtkTextMark object a #GtkTextBuffer name for mark, or %NULL location to place mark whether the mark has left gravity Creates a tag and adds it to the tag table for @buffer. Equivalent to calling gtk_text_tag_new() and then adding the tag to the buffer’s tag table. The returned tag is owned by the buffer’s tag table, so the ref count will be equal to one. If @tag_name is %NULL, the tag is anonymous. If @tag_name is non-%NULL, a tag called @tag_name must not already exist in the tag table for this buffer. The @first_property_name argument and subsequent arguments are a list of properties to set on the tag, as with g_object_set(). a new tag a #GtkTextBuffer name of the new tag, or %NULL name of first property to set, or %NULL %NULL-terminated list of property names and values Copies the currently-selected text to a clipboard, then deletes said text if it’s editable. a #GtkTextBuffer the #GtkClipboard object to cut to default editability of the buffer Deletes text between @start and @end. The order of @start and @end is not actually relevant; gtk_text_buffer_delete() will reorder them. This function actually emits the “delete-range” signal, and the default handler of that signal deletes the text. Because the buffer is modified, all outstanding iterators become invalid after calling this function; however, the @start and @end will be re-initialized to point to the location where text was deleted. a #GtkTextBuffer a position in @buffer another position in @buffer Deletes all editable text in the given range. Calls gtk_text_buffer_delete() for each editable sub-range of [@start,@end). @start and @end are revalidated to point to the location of the last deleted range, or left untouched if no text was deleted. whether some text was actually deleted a #GtkTextBuffer start of range to delete end of range whether the buffer is editable by default Deletes @mark, so that it’s no longer located anywhere in the buffer. Removes the reference the buffer holds to the mark, so if you haven’t called g_object_ref() on the mark, it will be freed. Even if the mark isn’t freed, most operations on @mark become invalid, until it gets added to a buffer again with gtk_text_buffer_add_mark(). Use gtk_text_mark_get_deleted() to find out if a mark has been removed from its buffer. The #GtkTextBuffer::mark-deleted signal will be emitted as notification after the mark is deleted. a #GtkTextBuffer a #GtkTextMark in @buffer Deletes the mark named @name; the mark must exist. See gtk_text_buffer_delete_mark() for details. a #GtkTextBuffer name of a mark in @buffer Deletes the range between the “insert” and “selection_bound” marks, that is, the currently-selected text. If @interactive is %TRUE, the editability of the selection will be considered (users can’t delete uneditable text). whether there was a non-empty selection to delete a #GtkTextBuffer whether the deletion is caused by user interaction whether the buffer is editable by default This function deserializes rich text in format @format and inserts it at @iter. @formats to be used must be registered using gtk_text_buffer_register_deserialize_format() or gtk_text_buffer_register_deserialize_tagset() beforehand. %TRUE on success, %FALSE otherwise. the #GtkTextBuffer @format is registered with the #GtkTextBuffer to deserialize into the rich text format to use for deserializing insertion point for the deserialized text data to deserialize length of @data This functions returns the value set with gtk_text_buffer_deserialize_set_can_create_tags() whether deserializing this format may create tags a #GtkTextBuffer a #GdkAtom representing a registered rich text format Use this function to allow a rich text deserialization function to create new tags in the receiving buffer. Note that using this function is almost always a bad idea, because the rich text functions you register should know how to map the rich text format they handler to your text buffers set of tags. The ability of creating new (arbitrary!) tags in the receiving buffer is meant for special rich text formats like the internal one that is registered using gtk_text_buffer_register_deserialize_tagset(), because that format is essentially a dump of the internal structure of the source buffer, including its tag names. You should allow creation of tags only if you know what you are doing, e.g. if you defined a tagset name for your application suite’s text buffers and you know that it’s fine to receive new tags from these buffers, because you know that your application can handle the newly created tags. a #GtkTextBuffer a #GdkAtom representing a registered rich text format whether deserializing this format may create tags Should be paired with a call to gtk_text_buffer_begin_user_action(). See that function for a full explanation. a #GtkTextBuffer Retrieves the first and last iterators in the buffer, i.e. the entire buffer lies within the range [@start,@end). a #GtkTextBuffer iterator to initialize with first position in the buffer iterator to initialize with the end iterator Gets the number of characters in the buffer; note that characters and bytes are not the same, you can’t e.g. expect the contents of the buffer in string form to be this many bytes long. The character count is cached, so this function is very fast. number of characters in the buffer a #GtkTextBuffer This function returns the list of targets this text buffer can provide for copying and as DND source. The targets in the list are added with @info values from the #GtkTextBufferTargetInfo enum, using gtk_target_list_add_rich_text_targets() and gtk_target_list_add_text_targets(). the #GtkTargetList a #GtkTextBuffer This function returns the rich text deserialize formats registered with @buffer using gtk_text_buffer_register_deserialize_format() or gtk_text_buffer_register_deserialize_tagset() an array of #GdkAtoms representing the registered formats. a #GtkTextBuffer return location for the number of formats Initializes @iter with the “end iterator,” one past the last valid character in the text buffer. If dereferenced with gtk_text_iter_get_char(), the end iterator has a character value of 0. The entire buffer lies in the range from the first position in the buffer (call gtk_text_buffer_get_start_iter() to get character position 0) to the end iterator. a #GtkTextBuffer iterator to initialize Indicates whether the buffer has some text currently selected. %TRUE if the there is text selected a #GtkTextBuffer Returns the mark that represents the cursor (insertion point). Equivalent to calling gtk_text_buffer_get_mark() to get the mark named “insert”, but very slightly more efficient, and involves less typing. insertion point mark a #GtkTextBuffer Obtains the location of @anchor within @buffer. a #GtkTextBuffer an iterator to be initialized a child anchor that appears in @buffer Initializes @iter to the start of the given line. If @line_number is greater than the number of lines in the @buffer, the end iterator is returned. a #GtkTextBuffer iterator to initialize line number counting from 0 Obtains an iterator pointing to @byte_index within the given line. @byte_index must be the start of a UTF-8 character. Note bytes, not characters; UTF-8 may encode one character as multiple bytes. Before the 3.20 version, it was not allowed to pass an invalid location. Since the 3.20 version, if @line_number is greater than the number of lines in the @buffer, the end iterator is returned. And if @byte_index is off the end of the line, the iterator at the end of the line is returned. a #GtkTextBuffer iterator to initialize line number counting from 0 byte index from start of line Obtains an iterator pointing to @char_offset within the given line. Note characters, not bytes; UTF-8 may encode one character as multiple bytes. Before the 3.20 version, it was not allowed to pass an invalid location. Since the 3.20 version, if @line_number is greater than the number of lines in the @buffer, the end iterator is returned. And if @char_offset is off the end of the line, the iterator at the end of the line is returned. a #GtkTextBuffer iterator to initialize line number counting from 0 char offset from start of line Initializes @iter with the current position of @mark. a #GtkTextBuffer iterator to initialize a #GtkTextMark in @buffer Initializes @iter to a position @char_offset chars from the start of the entire buffer. If @char_offset is -1 or greater than the number of characters in the buffer, @iter is initialized to the end iterator, the iterator one past the last valid character in the buffer. a #GtkTextBuffer iterator to initialize char offset from start of buffer, counting from 0, or -1 Obtains the number of lines in the buffer. This value is cached, so the function is very fast. number of lines in the buffer a #GtkTextBuffer Returns the mark named @name in buffer @buffer, or %NULL if no such mark exists in the buffer. a #GtkTextMark, or %NULL a #GtkTextBuffer a mark name Indicates whether the buffer has been modified since the last call to gtk_text_buffer_set_modified() set the modification flag to %FALSE. Used for example to enable a “save” function in a text editor. %TRUE if the buffer has been modified a #GtkTextBuffer This function returns the list of targets this text buffer supports for pasting and as DND destination. The targets in the list are added with @info values from the #GtkTextBufferTargetInfo enum, using gtk_target_list_add_rich_text_targets() and gtk_target_list_add_text_targets(). the #GtkTargetList a #GtkTextBuffer Returns the mark that represents the selection bound. Equivalent to calling gtk_text_buffer_get_mark() to get the mark named “selection_bound”, but very slightly more efficient, and involves less typing. The currently-selected text in @buffer is the region between the “selection_bound” and “insert” marks. If “selection_bound” and “insert” are in the same place, then there is no current selection. gtk_text_buffer_get_selection_bounds() is another convenient function for handling the selection, if you just want to know whether there’s a selection and what its bounds are. selection bound mark a #GtkTextBuffer Returns %TRUE if some text is selected; places the bounds of the selection in @start and @end (if the selection has length 0, then @start and @end are filled in with the same value). @start and @end will be in ascending order. If @start and @end are NULL, then they are not filled in, but the return value still indicates whether text is selected. whether the selection has nonzero length a #GtkTextBuffer a #GtkTextBuffer iterator to initialize with selection start iterator to initialize with selection end This function returns the rich text serialize formats registered with @buffer using gtk_text_buffer_register_serialize_format() or gtk_text_buffer_register_serialize_tagset() an array of #GdkAtoms representing the registered formats. a #GtkTextBuffer return location for the number of formats Returns the text in the range [@start,@end). Excludes undisplayed text (text marked with tags that set the invisibility attribute) if @include_hidden_chars is %FALSE. The returned string includes a 0xFFFC character whenever the buffer contains embedded images, so byte and character indexes into the returned string do correspond to byte and character indexes into the buffer. Contrast with gtk_text_buffer_get_text(). Note that 0xFFFC can occur in normal text as well, so it is not a reliable indicator that a pixbuf or widget is in the buffer. an allocated UTF-8 string a #GtkTextBuffer start of a range end of a range whether to include invisible text Initialized @iter with the first position in the text buffer. This is the same as using gtk_text_buffer_get_iter_at_offset() to get the iter at character offset 0. a #GtkTextBuffer iterator to initialize Get the #GtkTextTagTable associated with this buffer. the buffer’s tag table a #GtkTextBuffer Returns the text in the range [@start,@end). Excludes undisplayed text (text marked with tags that set the invisibility attribute) if @include_hidden_chars is %FALSE. Does not include characters representing embedded images, so byte and character indexes into the returned string do not correspond to byte and character indexes into the buffer. Contrast with gtk_text_buffer_get_slice(). an allocated UTF-8 string a #GtkTextBuffer start of a range end of a range whether to include invisible text Inserts @len bytes of @text at position @iter. If @len is -1, @text must be nul-terminated and will be inserted in its entirety. Emits the “insert-text” signal; insertion actually occurs in the default handler for the signal. @iter is invalidated when insertion occurs (because the buffer contents change), but the default signal handler revalidates it to point to the end of the inserted text. a #GtkTextBuffer a position in the buffer text in UTF-8 format length of text in bytes, or -1 Simply calls gtk_text_buffer_insert(), using the current cursor position as the insertion point. a #GtkTextBuffer text in UTF-8 format length of text, in bytes Inserts a child widget anchor into the text buffer at @iter. The anchor will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode “object replacement character” 0xFFFC. Note that the “slice” variants for obtaining portions of the buffer as a string include this character for child anchors, but the “text” variants do not. E.g. see gtk_text_buffer_get_slice() and gtk_text_buffer_get_text(). Consider gtk_text_buffer_create_child_anchor() as a more convenient alternative to this function. The buffer will add a reference to the anchor, so you can unref it after insertion. a #GtkTextBuffer location to insert the anchor a #GtkTextChildAnchor Like gtk_text_buffer_insert(), but the insertion will not occur if @iter is at a non-editable location in the buffer. Usually you want to prevent insertions at ineditable locations if the insertion results from a user action (is interactive). @default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. Typically the result of gtk_text_view_get_editable() is appropriate here. whether text was actually inserted a #GtkTextBuffer a position in @buffer some UTF-8 text length of text in bytes, or -1 default editability of buffer Calls gtk_text_buffer_insert_interactive() at the cursor position. @default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. Typically the result of gtk_text_view_get_editable() is appropriate here. whether text was actually inserted a #GtkTextBuffer text in UTF-8 format length of text in bytes, or -1 default editability of buffer Inserts the text in @markup at position @iter. @markup will be inserted in its entirety and must be nul-terminated and valid UTF-8. Emits the #GtkTextBuffer::insert-text signal, possibly multiple times; insertion actually occurs in the default handler for the signal. @iter will point to the end of the inserted text on return. a #GtkTextBuffer location to insert the markup a nul-terminated UTF-8 string containing [Pango markup][PangoMarkupFormat] length of @markup in bytes, or -1 Inserts an image into the text buffer at @iter. The image will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode “object replacement character” 0xFFFC. Note that the “slice” variants for obtaining portions of the buffer as a string include this character for pixbufs, but the “text” variants do not. e.g. see gtk_text_buffer_get_slice() and gtk_text_buffer_get_text(). a #GtkTextBuffer location to insert the pixbuf a #GdkPixbuf Copies text, tags, and pixbufs between @start and @end (the order of @start and @end doesn’t matter) and inserts the copy at @iter. Used instead of simply getting/inserting text because it preserves images and tags. If @start and @end are in a different buffer from @buffer, the two buffers must share the same tag table. Implemented via emissions of the insert_text and apply_tag signals, so expect those. a #GtkTextBuffer a position in @buffer a position in a #GtkTextBuffer another position in the same buffer as @start Same as gtk_text_buffer_insert_range(), but does nothing if the insertion point isn’t editable. The @default_editable parameter indicates whether the text is editable at @iter if no tags enclosing @iter affect editability. Typically the result of gtk_text_view_get_editable() is appropriate here. whether an insertion was possible at @iter a #GtkTextBuffer a position in @buffer a position in a #GtkTextBuffer another position in the same buffer as @start default editability of the buffer Inserts @text into @buffer at @iter, applying the list of tags to the newly-inserted text. The last tag specified must be %NULL to terminate the list. Equivalent to calling gtk_text_buffer_insert(), then gtk_text_buffer_apply_tag() on the inserted text; gtk_text_buffer_insert_with_tags() is just a convenience function. a #GtkTextBuffer an iterator in @buffer UTF-8 text length of @text, or -1 first tag to apply to @text %NULL-terminated list of tags to apply Same as gtk_text_buffer_insert_with_tags(), but allows you to pass in tag names instead of tag objects. a #GtkTextBuffer position in @buffer UTF-8 text length of @text, or -1 name of a tag to apply to @text more tag names Moves @mark to the new location @where. Emits the #GtkTextBuffer::mark-set signal as notification of the move. a #GtkTextBuffer a #GtkTextMark new location for @mark in @buffer Moves the mark named @name (which must exist) to location @where. See gtk_text_buffer_move_mark() for details. a #GtkTextBuffer name of a mark new location for mark Pastes the contents of a clipboard. If @override_location is %NULL, the pasted text will be inserted at the cursor position, or the buffer selection will be replaced if the selection is non-empty. Note: pasting is asynchronous, that is, we’ll ask for the paste data and return, and at some point later after the main loop runs, the paste data will be inserted. a #GtkTextBuffer the #GtkClipboard to paste from location to insert pasted text, or %NULL whether the buffer is editable by default This function moves the “insert” and “selection_bound” marks simultaneously. If you move them to the same place in two steps with gtk_text_buffer_move_mark(), you will temporarily select a region in between their old and new locations, which can be pretty inefficient since the temporarily-selected region will force stuff to be recalculated. This function moves them as a unit, which can be optimized. a #GtkTextBuffer where to put the cursor This function registers a rich text deserialization @function along with its @mime_type with the passed @buffer. the #GdkAtom that corresponds to the newly registered format’s mime-type. a #GtkTextBuffer the format’s mime-type the deserialize function to register @function’s user_data a function to call when @user_data is no longer needed This function registers GTK+’s internal rich text serialization format with the passed @buffer. See gtk_text_buffer_register_serialize_tagset() for details. the #GdkAtom that corresponds to the newly registered format’s mime-type. a #GtkTextBuffer an optional tagset name, on %NULL This function registers a rich text serialization @function along with its @mime_type with the passed @buffer. the #GdkAtom that corresponds to the newly registered format’s mime-type. a #GtkTextBuffer the format’s mime-type the serialize function to register @function’s user_data a function to call when @user_data is no longer needed This function registers GTK+’s internal rich text serialization format with the passed @buffer. The internal format does not comply to any standard rich text format and only works between #GtkTextBuffer instances. It is capable of serializing all of a text buffer’s tags and embedded pixbufs. This function is just a wrapper around gtk_text_buffer_register_serialize_format(). The mime type used for registering is “application/x-gtk-text-buffer-rich-text”, or “application/x-gtk-text-buffer-rich-text;format=@tagset_name” if a @tagset_name was passed. The @tagset_name can be used to restrict the transfer of rich text to buffers with compatible sets of tags, in order to avoid unknown tags from being pasted. It is probably the common case to pass an identifier != %NULL here, since the %NULL tagset requires the receiving buffer to deal with with pasting of arbitrary tags. the #GdkAtom that corresponds to the newly registered format’s mime-type. a #GtkTextBuffer an optional tagset name, on %NULL Removes all tags in the range between @start and @end. Be careful with this function; it could remove tags added in code unrelated to the code you’re currently writing. That is, using this function is probably a bad idea if you have two or more unrelated code sections that add tags. a #GtkTextBuffer one bound of range to be untagged other bound of range to be untagged Removes a #GtkClipboard added with gtk_text_buffer_add_selection_clipboard(). a #GtkTextBuffer a #GtkClipboard added to @buffer by gtk_text_buffer_add_selection_clipboard() Emits the “remove-tag” signal. The default handler for the signal removes all occurrences of @tag from the given range. @start and @end don’t have to be in order. a #GtkTextBuffer a #GtkTextTag one bound of range to be untagged other bound of range to be untagged Calls gtk_text_tag_table_lookup() on the buffer’s tag table to get a #GtkTextTag, then calls gtk_text_buffer_remove_tag(). a #GtkTextBuffer name of a #GtkTextTag one bound of range to be untagged other bound of range to be untagged This function moves the “insert” and “selection_bound” marks simultaneously. If you move them in two steps with gtk_text_buffer_move_mark(), you will temporarily select a region in between their old and new locations, which can be pretty inefficient since the temporarily-selected region will force stuff to be recalculated. This function moves them as a unit, which can be optimized. a #GtkTextBuffer where to put the “insert” mark where to put the “selection_bound” mark This function serializes the portion of text between @start and @end in the rich text format represented by @format. @formats to be used must be registered using gtk_text_buffer_register_serialize_format() or gtk_text_buffer_register_serialize_tagset() beforehand. the serialized data, encoded as @format the #GtkTextBuffer @format is registered with the #GtkTextBuffer to serialize the rich text format to use for serializing start of block of text to serialize end of block of test to serialize return location for the length of the serialized data Used to keep track of whether the buffer has been modified since the last time it was saved. Whenever the buffer is saved to disk, call gtk_text_buffer_set_modified (@buffer, FALSE). When the buffer is modified, it will automatically toggled on the modified bit again. When the modified bit flips, the buffer emits the #GtkTextBuffer::modified-changed signal. a #GtkTextBuffer modification flag setting Deletes current contents of @buffer, and inserts @text instead. If @len is -1, @text must be nul-terminated. @text must be valid UTF-8. a #GtkTextBuffer UTF-8 text to insert length of @text in bytes This function unregisters a rich text format that was previously registered using gtk_text_buffer_register_deserialize_format() or gtk_text_buffer_register_deserialize_tagset(). a #GtkTextBuffer a #GdkAtom representing a registered rich text format. This function unregisters a rich text format that was previously registered using gtk_text_buffer_register_serialize_format() or gtk_text_buffer_register_serialize_tagset() a #GtkTextBuffer a #GdkAtom representing a registered rich text format. The list of targets this buffer supports for clipboard copying and as DND source. The position of the insert mark (as offset from the beginning of the buffer). It is useful for getting notified when the cursor moves. Whether the buffer has some text currently selected. The list of targets this buffer supports for clipboard pasting and as DND destination. The text content of the buffer. Without child widgets and images, see gtk_text_buffer_get_text() for more information. The ::apply-tag signal is emitted to apply a tag to a range of text in a #GtkTextBuffer. Applying actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @start and @end iters (or has to revalidate them). See also: gtk_text_buffer_apply_tag(), gtk_text_buffer_insert_with_tags(), gtk_text_buffer_insert_range(). the applied tag the start of the range the tag is applied to the end of the range the tag is applied to The ::begin-user-action signal is emitted at the beginning of a single user-visible operation on a #GtkTextBuffer. See also: gtk_text_buffer_begin_user_action(), gtk_text_buffer_insert_interactive(), gtk_text_buffer_insert_range_interactive(), gtk_text_buffer_delete_interactive(), gtk_text_buffer_backspace(), gtk_text_buffer_delete_selection(). The ::changed signal is emitted when the content of a #GtkTextBuffer has changed. The ::delete-range signal is emitted to delete a range from a #GtkTextBuffer. Note that if your handler runs before the default handler it must not invalidate the @start and @end iters (or has to revalidate them). The default signal handler revalidates the @start and @end iters to both point to the location where text was deleted. Handlers which run after the default handler (see g_signal_connect_after()) do not have access to the deleted text. See also: gtk_text_buffer_delete(). the start of the range to be deleted the end of the range to be deleted The ::end-user-action signal is emitted at the end of a single user-visible operation on the #GtkTextBuffer. See also: gtk_text_buffer_end_user_action(), gtk_text_buffer_insert_interactive(), gtk_text_buffer_insert_range_interactive(), gtk_text_buffer_delete_interactive(), gtk_text_buffer_backspace(), gtk_text_buffer_delete_selection(), gtk_text_buffer_backspace(). The ::insert-child-anchor signal is emitted to insert a #GtkTextChildAnchor in a #GtkTextBuffer. Insertion actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @location iter (or has to revalidate it). The default signal handler revalidates it to be placed after the inserted @anchor. See also: gtk_text_buffer_insert_child_anchor(). position to insert @anchor in @textbuffer the #GtkTextChildAnchor to be inserted The ::insert-pixbuf signal is emitted to insert a #GdkPixbuf in a #GtkTextBuffer. Insertion actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @location iter (or has to revalidate it). The default signal handler revalidates it to be placed after the inserted @pixbuf. See also: gtk_text_buffer_insert_pixbuf(). position to insert @pixbuf in @textbuffer the #GdkPixbuf to be inserted The ::insert-text signal is emitted to insert text in a #GtkTextBuffer. Insertion actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @location iter (or has to revalidate it). The default signal handler revalidates it to point to the end of the inserted text. See also: gtk_text_buffer_insert(), gtk_text_buffer_insert_range(). position to insert @text in @textbuffer the UTF-8 text to be inserted length of the inserted text in bytes The ::mark-deleted signal is emitted as notification after a #GtkTextMark is deleted. See also: gtk_text_buffer_delete_mark(). The mark that was deleted The ::mark-set signal is emitted as notification after a #GtkTextMark is set. See also: gtk_text_buffer_create_mark(), gtk_text_buffer_move_mark(). The location of @mark in @textbuffer The mark that is set The ::modified-changed signal is emitted when the modified bit of a #GtkTextBuffer flips. See also: gtk_text_buffer_set_modified(). The paste-done signal is emitted after paste operation has been completed. This is useful to properly scroll the view to the end of the pasted text. See gtk_text_buffer_paste_clipboard() for more details. the #GtkClipboard pasted from The ::remove-tag signal is emitted to remove all occurrences of @tag from a range of text in a #GtkTextBuffer. Removal actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @start and @end iters (or has to revalidate them). See also: gtk_text_buffer_remove_tag(). the tag to be removed the start of the range the tag is removed from the end of the range the tag is removed from The object class structure needs to be the first. The class handler for the #GtkTextBuffer::insert-text signal. The class handler for the #GtkTextBuffer::insert-pixbuf signal. a #GtkTextBuffer location to insert the pixbuf a #GdkPixbuf The class handler for the #GtkTextBuffer::insert-child-anchor signal. a #GtkTextBuffer location to insert the anchor a #GtkTextChildAnchor The class handler for the #GtkTextBuffer::delete-range signal. The class handler for the #GtkTextBuffer::changed signal. The class handler for the #GtkTextBuffer::modified-changed signal. The class handler for the #GtkTextBuffer::mark-set signal. The class handler for the #GtkTextBuffer::mark-deleted signal. The class handler for the #GtkTextBuffer::apply-tag signal. a #GtkTextBuffer a #GtkTextTag one bound of range to be tagged other bound of range to be tagged The class handler for the #GtkTextBuffer::remove-tag signal. a #GtkTextBuffer a #GtkTextTag one bound of range to be untagged other bound of range to be untagged The class handler for the #GtkTextBuffer::begin-user-action signal. a #GtkTextBuffer The class handler for the #GtkTextBuffer::end-user-action signal. a #GtkTextBuffer The class handler for the #GtkTextBuffer::paste-done signal. A function that is called to deserialize rich text that has been serialized with gtk_text_buffer_serialize(), and insert it at @iter. %TRUE on success, %FALSE otherwise the #GtkTextBuffer the format is registered with the #GtkTextBuffer to deserialize into insertion point for the deserialized text data to deserialize length of @data %TRUE if deserializing may create tags user data that was specified when registering the format A function that is called to serialize the content of a text buffer. It must return the serialized form of the content. a newly-allocated array of guint8 which contains the serialized data, or %NULL if an error occurred the #GtkTextBuffer for which the format is registered the #GtkTextBuffer to serialize start of the block of text to serialize end of the block of text to serialize return location for the length of the serialized data user data that was specified when registering the format These values are used as “info” for the targets contained in the lists returned by gtk_text_buffer_get_copy_target_list() and gtk_text_buffer_get_paste_target_list(). The values counts down from `-1` to avoid clashes with application added drag destinations which usually start at 0. Buffer contents Rich text Text A #GtkTextChildAnchor is a spot in the buffer where child widgets can be “anchored” (inserted inline, as if they were characters). The anchor can have multiple widgets anchored, to allow for multiple views. Creates a new #GtkTextChildAnchor. Usually you would then insert it into a #GtkTextBuffer with gtk_text_buffer_insert_child_anchor(). To perform the creation and insertion in one step, use the convenience function gtk_text_buffer_create_child_anchor(). a new #GtkTextChildAnchor Determines whether a child anchor has been deleted from the buffer. Keep in mind that the child anchor will be unreferenced when removed from the buffer, so you need to hold your own reference (with g_object_ref()) if you plan to use this function — otherwise all deleted child anchors will also be finalized. %TRUE if the child anchor has been deleted from its buffer a #GtkTextChildAnchor Gets a list of all widgets anchored at this child anchor. The returned list should be freed with g_list_free(). list of widgets anchored at @anchor a #GtkTextChildAnchor Reading directions for text. No direction. Left to right text direction. Right to left text direction. Granularity types that extend the text selection. Use the #GtkTextView::extend-selection signal to customize the selection. Selects the current word. It is triggered by a double-click for example. Selects the current line. It is triggered by a triple-click for example. You may wish to begin by reading the [text widget conceptual overview](TextWidget.html) which gives an overview of all the objects and data types related to the text widget and how they work together. Assigns the value of @other to @iter. This function is not useful in applications, because iterators can be assigned with `GtkTextIter i = j;`. The function is used by language bindings. a #GtkTextIter another #GtkTextIter Moves backward by one character offset. Returns %TRUE if movement was possible; if @iter was the first in the buffer (character offset 0), gtk_text_iter_backward_char() returns %FALSE for convenience when writing loops. whether movement was possible an iterator Moves @count characters backward, if possible (if @count would move past the start or end of the buffer, moves to the start or end of the buffer). The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. whether @iter moved and is dereferenceable an iterator number of characters to move Like gtk_text_iter_forward_cursor_position(), but moves backward. %TRUE if we moved a #GtkTextIter Moves up to @count cursor positions. See gtk_text_iter_forward_cursor_position() for details. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter number of positions to move Same as gtk_text_iter_forward_find_char(), but goes backward from @iter. whether a match was found a #GtkTextIter function to be called on each character user data for @pred search limit, or %NULL for none Moves @iter to the start of the previous line. Returns %TRUE if @iter could be moved; i.e. if @iter was at character offset 0, this function returns %FALSE. Therefore if @iter was already on line 0, but not at the start of the line, @iter is snapped to the start of the line and the function returns %TRUE. (Note that this implies that in a loop calling this function, the line number may not change on every iteration, if your first iteration is on line 0.) whether @iter moved an iterator Moves @count lines backward, if possible (if @count would move past the start or end of the buffer, moves to the start or end of the buffer). The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. If @count is negative, moves forward by 0 - @count lines. whether @iter moved and is dereferenceable a #GtkTextIter number of lines to move backward Same as gtk_text_iter_forward_search(), but moves backward. @match_end will never be set to a #GtkTextIter located after @iter, even if there is a possible @match_start before or at @iter. whether a match was found a #GtkTextIter where the search begins search string bitmask of flags affecting the search return location for start of match, or %NULL return location for end of match, or %NULL location of last possible @match_start, or %NULL for start of buffer Moves backward to the previous sentence start; if @iter is already at the start of a sentence, moves backward to the next one. Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms). %TRUE if @iter moved and is not the end iterator a #GtkTextIter Calls gtk_text_iter_backward_sentence_start() up to @count times, or until it returns %FALSE. If @count is negative, moves forward instead of backward. %TRUE if @iter moved and is not the end iterator a #GtkTextIter number of sentences to move Moves backward to the next toggle (on or off) of the #GtkTextTag @tag, or to the next toggle of any tag if @tag is %NULL. If no matching tag toggles are found, returns %FALSE, otherwise %TRUE. Does not return toggles located at @iter, only toggles before @iter. Sets @iter to the location of the toggle, or the start of the buffer if no toggle is found. whether we found a tag toggle before @iter a #GtkTextIter a #GtkTextTag, or %NULL Moves @iter forward to the previous visible cursor position. See gtk_text_iter_backward_cursor_position() for details. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter Moves up to @count visible cursor positions. See gtk_text_iter_backward_cursor_position() for details. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter number of positions to move Moves @iter to the start of the previous visible line. Returns %TRUE if @iter could be moved; i.e. if @iter was at character offset 0, this function returns %FALSE. Therefore if @iter was already on line 0, but not at the start of the line, @iter is snapped to the start of the line and the function returns %TRUE. (Note that this implies that in a loop calling this function, the line number may not change on every iteration, if your first iteration is on line 0.) whether @iter moved an iterator Moves @count visible lines backward, if possible (if @count would move past the start or end of the buffer, moves to the start or end of the buffer). The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. If @count is negative, moves forward by 0 - @count lines. whether @iter moved and is dereferenceable a #GtkTextIter number of lines to move backward Moves backward to the previous visible word start. (If @iter is currently on a word start, moves backward to the next one after that.) Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms). %TRUE if @iter moved and is not the end iterator a #GtkTextIter Calls gtk_text_iter_backward_visible_word_start() up to @count times. %TRUE if @iter moved and is not the end iterator a #GtkTextIter number of times to move Moves backward to the previous word start. (If @iter is currently on a word start, moves backward to the next one after that.) Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms). %TRUE if @iter moved and is not the end iterator a #GtkTextIter Calls gtk_text_iter_backward_word_start() up to @count times. %TRUE if @iter moved and is not the end iterator a #GtkTextIter number of times to move Returns %TRUE if @tag is toggled on at exactly this point. If @tag is %NULL, returns %TRUE if any tag is toggled on at this point. Note that if gtk_text_iter_begins_tag() returns %TRUE, it means that @iter is at the beginning of the tagged range, and that the character at @iter is inside the tagged range. In other words, unlike gtk_text_iter_ends_tag(), if gtk_text_iter_begins_tag() returns %TRUE, gtk_text_iter_has_tag() will also return %TRUE for the same parameters. Use gtk_text_iter_starts_tag() instead. whether @iter is the start of a range tagged with @tag an iterator a #GtkTextTag, or %NULL Considering the default editability of the buffer, and tags that affect editability, determines whether text inserted at @iter would be editable. If text inserted at @iter would be editable then the user should be allowed to insert text at @iter. gtk_text_buffer_insert_interactive() uses this function to decide whether insertions are allowed at a given position. whether text inserted at @iter would be editable an iterator %TRUE if text is editable by default A qsort()-style function that returns negative if @lhs is less than @rhs, positive if @lhs is greater than @rhs, and 0 if they’re equal. Ordering is in character offset order, i.e. the first character in the buffer is less than the second character in the buffer. -1 if @lhs is less than @rhs, 1 if @lhs is greater, 0 if they are equal a #GtkTextIter another #GtkTextIter Creates a dynamically-allocated copy of an iterator. This function is not useful in applications, because iterators can be copied with a simple assignment (`GtkTextIter i = j;`). The function is used by language bindings. a copy of the @iter, free with gtk_text_iter_free() an iterator Returns whether the character at @iter is within an editable region of text. Non-editable text is “locked” and can’t be changed by the user via #GtkTextView. This function is simply a convenience wrapper around gtk_text_iter_get_attributes(). If no tags applied to this text affect editability, @default_setting will be returned. You don’t want to use this function to decide whether text can be inserted at @iter, because for insertion you don’t want to know whether the char at @iter is inside an editable range, you want to know whether a new character inserted at @iter would be inside an editable range. Use gtk_text_iter_can_insert() to handle this case. whether @iter is inside an editable range an iterator %TRUE if text is editable by default Returns %TRUE if @iter points to the start of the paragraph delimiter characters for a line (delimiters will be either a newline, a carriage return, a carriage return followed by a newline, or a Unicode paragraph separator character). Note that an iterator pointing to the \n of a \r\n pair will not be counted as the end of a line, the line ends before the \r. The end iterator is considered to be at the end of a line, even though there are no paragraph delimiter chars there. whether @iter is at the end of a line an iterator Determines whether @iter ends a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms). %TRUE if @iter is at the end of a sentence. a #GtkTextIter Returns %TRUE if @tag is toggled off at exactly this point. If @tag is %NULL, returns %TRUE if any tag is toggled off at this point. Note that if gtk_text_iter_ends_tag() returns %TRUE, it means that @iter is at the end of the tagged range, but that the character at @iter is outside the tagged range. In other words, unlike gtk_text_iter_starts_tag(), if gtk_text_iter_ends_tag() returns %TRUE, gtk_text_iter_has_tag() will return %FALSE for the same parameters. whether @iter is the end of a range tagged with @tag an iterator a #GtkTextTag, or %NULL Determines whether @iter ends a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms). %TRUE if @iter is at the end of a word a #GtkTextIter Tests whether two iterators are equal, using the fastest possible mechanism. This function is very fast; you can expect it to perform better than e.g. getting the character offset for each iterator and comparing the offsets yourself. Also, it’s a bit faster than gtk_text_iter_compare(). %TRUE if the iterators point to the same place in the buffer a #GtkTextIter another #GtkTextIter Moves @iter forward by one character offset. Note that images embedded in the buffer occupy 1 character slot, so gtk_text_iter_forward_char() may actually move onto an image instead of a character, if you have images in your buffer. If @iter is the end iterator or one character before it, @iter will now point at the end iterator, and gtk_text_iter_forward_char() returns %FALSE for convenience when writing loops. whether @iter moved and is dereferenceable an iterator Moves @count characters if possible (if @count would move past the start or end of the buffer, moves to the start or end of the buffer). The return value indicates whether the new position of @iter is different from its original position, and dereferenceable (the last iterator in the buffer is not dereferenceable). If @count is 0, the function does nothing and returns %FALSE. whether @iter moved and is dereferenceable an iterator number of characters to move, may be negative Moves @iter forward by a single cursor position. Cursor positions are (unsurprisingly) positions where the cursor can appear. Perhaps surprisingly, there may not be a cursor position between all characters. The most common example for European languages would be a carriage return/newline sequence. For some Unicode characters, the equivalent of say the letter “a” with an accent mark will be represented as two characters, first the letter then a "combining mark" that causes the accent to be rendered; so the cursor can’t go between those two characters. See also the #PangoLogAttr-struct and pango_break() function. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter Moves up to @count cursor positions. See gtk_text_iter_forward_cursor_position() for details. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter number of positions to move Advances @iter, calling @pred on each character. If @pred returns %TRUE, returns %TRUE and stops scanning. If @pred never returns %TRUE, @iter is set to @limit if @limit is non-%NULL, otherwise to the end iterator. whether a match was found a #GtkTextIter a function to be called on each character user data for @pred search limit, or %NULL for none Moves @iter to the start of the next line. If the iter is already on the last line of the buffer, moves the iter to the end of the current line. If after the operation, the iter is at the end of the buffer and not dereferencable, returns %FALSE. Otherwise, returns %TRUE. whether @iter can be dereferenced an iterator Moves @count lines forward, if possible (if @count would move past the start or end of the buffer, moves to the start or end of the buffer). The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. If @count is negative, moves backward by 0 - @count lines. whether @iter moved and is dereferenceable a #GtkTextIter number of lines to move forward Searches forward for @str. Any match is returned by setting @match_start to the first character of the match and @match_end to the first character after the match. The search will not continue past @limit. Note that a search is a linear or O(n) operation, so you may wish to use @limit to avoid locking up your UI on large buffers. @match_start will never be set to a #GtkTextIter located before @iter, even if there is a possible @match_end after or at @iter. whether a match was found start of search a search string flags affecting how the search is done return location for start of match, or %NULL return location for end of match, or %NULL location of last possible @match_end, or %NULL for the end of the buffer Moves forward to the next sentence end. (If @iter is at the end of a sentence, moves to the next end of sentence.) Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms). %TRUE if @iter moved and is not the end iterator a #GtkTextIter Calls gtk_text_iter_forward_sentence_end() @count times (or until gtk_text_iter_forward_sentence_end() returns %FALSE). If @count is negative, moves backward instead of forward. %TRUE if @iter moved and is not the end iterator a #GtkTextIter number of sentences to move Moves @iter forward to the “end iterator,” which points one past the last valid character in the buffer. gtk_text_iter_get_char() called on the end iterator returns 0, which is convenient for writing loops. a #GtkTextIter Moves the iterator to point to the paragraph delimiter characters, which will be either a newline, a carriage return, a carriage return/newline in sequence, or the Unicode paragraph separator character. If the iterator is already at the paragraph delimiter characters, moves to the paragraph delimiter characters for the next line. If @iter is on the last line in the buffer, which does not end in paragraph delimiters, moves to the end iterator (end of the last line), and returns %FALSE. %TRUE if we moved and the new location is not the end iterator a #GtkTextIter Moves forward to the next toggle (on or off) of the #GtkTextTag @tag, or to the next toggle of any tag if @tag is %NULL. If no matching tag toggles are found, returns %FALSE, otherwise %TRUE. Does not return toggles located at @iter, only toggles after @iter. Sets @iter to the location of the toggle, or to the end of the buffer if no toggle is found. whether we found a tag toggle after @iter a #GtkTextIter a #GtkTextTag, or %NULL Moves @iter forward to the next visible cursor position. See gtk_text_iter_forward_cursor_position() for details. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter Moves up to @count visible cursor positions. See gtk_text_iter_forward_cursor_position() for details. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter number of positions to move Moves @iter to the start of the next visible line. Returns %TRUE if there was a next line to move to, and %FALSE if @iter was simply moved to the end of the buffer and is now not dereferenceable, or if @iter was already at the end of the buffer. whether @iter can be dereferenced an iterator Moves @count visible lines forward, if possible (if @count would move past the start or end of the buffer, moves to the start or end of the buffer). The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. If @count is negative, moves backward by 0 - @count lines. whether @iter moved and is dereferenceable a #GtkTextIter number of lines to move forward Moves forward to the next visible word end. (If @iter is currently on a word end, moves forward to the next one after that.) Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms). %TRUE if @iter moved and is not the end iterator a #GtkTextIter Calls gtk_text_iter_forward_visible_word_end() up to @count times. %TRUE if @iter moved and is not the end iterator a #GtkTextIter number of times to move Moves forward to the next word end. (If @iter is currently on a word end, moves forward to the next one after that.) Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms). %TRUE if @iter moved and is not the end iterator a #GtkTextIter Calls gtk_text_iter_forward_word_end() up to @count times. %TRUE if @iter moved and is not the end iterator a #GtkTextIter number of times to move Free an iterator allocated on the heap. This function is intended for use in language bindings, and is not especially useful for applications, because iterators can simply be allocated on the stack. a dynamically-allocated iterator Computes the effect of any tags applied to this spot in the text. The @values parameter should be initialized to the default settings you wish to use if no tags are in effect. You’d typically obtain the defaults from gtk_text_view_get_default_attributes(). gtk_text_iter_get_attributes() will modify @values, applying the effects of any tags present at @iter. If any tags affected @values, the function returns %TRUE. %TRUE if @values was modified an iterator a #GtkTextAttributes to be filled in Returns the #GtkTextBuffer this iterator is associated with. the buffer an iterator Returns the number of bytes in the line containing @iter, including the paragraph delimiters. number of bytes in the line an iterator The Unicode character at this iterator is returned. (Equivalent to operator* on a C++ iterator.) If the element at this iterator is a non-character element, such as an image embedded in the buffer, the Unicode “unknown” character 0xFFFC is returned. If invoked on the end iterator, zero is returned; zero is not a valid Unicode character. So you can write a loop which ends when gtk_text_iter_get_char() returns 0. a Unicode character, or 0 if @iter is not dereferenceable an iterator Returns the number of characters in the line containing @iter, including the paragraph delimiters. number of characters in the line an iterator If the location at @iter contains a child anchor, the anchor is returned (with no new reference count added). Otherwise, %NULL is returned. the anchor at @iter an iterator A convenience wrapper around gtk_text_iter_get_attributes(), which returns the language in effect at @iter. If no tags affecting language apply to @iter, the return value is identical to that of gtk_get_default_language(). language in effect at @iter an iterator Returns the line number containing the iterator. Lines in a #GtkTextBuffer are numbered beginning with 0 for the first line in the buffer. a line number an iterator Returns the byte index of the iterator, counting from the start of a newline-terminated line. Remember that #GtkTextBuffer encodes text in UTF-8, and that characters can require a variable number of bytes to represent. distance from start of line, in bytes an iterator Returns the character offset of the iterator, counting from the start of a newline-terminated line. The first character on the line has offset 0. offset from start of line an iterator Returns a list of all #GtkTextMark at this location. Because marks are not iterable (they don’t take up any "space" in the buffer, they are just marks in between iterable locations), multiple marks can exist in the same place. The returned list is not in any meaningful order. list of #GtkTextMark an iterator Returns the character offset of an iterator. Each character in a #GtkTextBuffer has an offset, starting with 0 for the first character in the buffer. Use gtk_text_buffer_get_iter_at_offset() to convert an offset back into an iterator. a character offset an iterator If the element at @iter is a pixbuf, the pixbuf is returned (with no new reference count added). Otherwise, %NULL is returned. the pixbuf at @iter an iterator Returns the text in the given range. A “slice” is an array of characters encoded in UTF-8 format, including the Unicode “unknown” character 0xFFFC for iterable non-character elements in the buffer, such as images. Because images are encoded in the slice, byte and character offsets in the returned array will correspond to byte offsets in the text buffer. Note that 0xFFFC can occur in normal text as well, so it is not a reliable indicator that a pixbuf or widget is in the buffer. slice of text from the buffer iterator at start of a range iterator at end of a range Returns a list of tags that apply to @iter, in ascending order of priority (highest-priority tags are last). The #GtkTextTag in the list don’t have a reference added, but you have to free the list itself. list of #GtkTextTag a #GtkTextIter Returns text in the given range. If the range contains non-text elements such as images, the character and byte offsets in the returned string will not correspond to character and byte offsets in the buffer. If you want offsets to correspond, see gtk_text_iter_get_slice(). array of characters from the buffer iterator at start of a range iterator at end of a range Returns a list of #GtkTextTag that are toggled on or off at this point. (If @toggled_on is %TRUE, the list contains tags that are toggled on.) If a tag is toggled on at @iter, then some non-empty range of characters following @iter has that tag applied to it. If a tag is toggled off, then some non-empty range following @iter does not have the tag applied to it. tags toggled at this point an iterator %TRUE to get toggled-on tags Returns the number of bytes from the start of the line to the given @iter, not counting bytes that are invisible due to tags with the “invisible” flag toggled on. byte index of @iter with respect to the start of the line a #GtkTextIter Returns the offset in characters from the start of the line to the given @iter, not counting characters that are invisible due to tags with the “invisible” flag toggled on. offset in visible characters from the start of the line a #GtkTextIter Like gtk_text_iter_get_slice(), but invisible text is not included. Invisible text is usually invisible because a #GtkTextTag with the “invisible” attribute turned on has been applied to it. slice of text from the buffer iterator at start of range iterator at end of range Like gtk_text_iter_get_text(), but invisible text is not included. Invisible text is usually invisible because a #GtkTextTag with the “invisible” attribute turned on has been applied to it. string containing visible text in the range iterator at start of range iterator at end of range Returns %TRUE if @iter points to a character that is part of a range tagged with @tag. See also gtk_text_iter_starts_tag() and gtk_text_iter_ends_tag(). whether @iter is tagged with @tag an iterator a #GtkTextTag Checks whether @iter falls in the range [@start, @end). @start and @end must be in ascending order. %TRUE if @iter is in the range a #GtkTextIter start of range end of range Determines whether @iter is inside a sentence (as opposed to in between two sentences, e.g. after a period and before the first letter of the next sentence). Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms). %TRUE if @iter is inside a sentence. a #GtkTextIter Determines whether the character pointed by @iter is part of a natural-language word (as opposed to say inside some whitespace). Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms). Note that if gtk_text_iter_starts_word() returns %TRUE, then this function returns %TRUE too, since @iter points to the first character of the word. %TRUE if @iter is inside a word a #GtkTextIter See gtk_text_iter_forward_cursor_position() or #PangoLogAttr or pango_break() for details on what a cursor position is. %TRUE if the cursor can be placed at @iter a #GtkTextIter Returns %TRUE if @iter is the end iterator, i.e. one past the last dereferenceable iterator in the buffer. gtk_text_iter_is_end() is the most efficient way to check whether an iterator is the end iterator. whether @iter is the end iterator an iterator Returns %TRUE if @iter is the first iterator in the buffer, that is if @iter has a character offset of 0. whether @iter is the first in the buffer an iterator Swaps the value of @first and @second if @second comes before @first in the buffer. That is, ensures that @first and @second are in sequence. Most text buffer functions that take a range call this automatically on your behalf, so there’s no real reason to call it yourself in those cases. There are some exceptions, such as gtk_text_iter_in_range(), that expect a pre-sorted range. a #GtkTextIter another #GtkTextIter Moves iterator @iter to the start of the line @line_number. If @line_number is negative or larger than the number of lines in the buffer, moves @iter to the start of the last line in the buffer. a #GtkTextIter line number (counted from 0) Same as gtk_text_iter_set_line_offset(), but works with a byte index. The given byte index must be at the start of a character, it can’t be in the middle of a UTF-8 encoded character. a #GtkTextIter a byte index relative to the start of @iter’s current line Moves @iter within a line, to a new character (not byte) offset. The given character offset must be less than or equal to the number of characters in the line; if equal, @iter moves to the start of the next line. See gtk_text_iter_set_line_index() if you have a byte index rather than a character offset. a #GtkTextIter a character offset relative to the start of @iter’s current line Sets @iter to point to @char_offset. @char_offset counts from the start of the entire text buffer, starting with 0. a #GtkTextIter a character number Like gtk_text_iter_set_line_index(), but the index is in visible bytes, i.e. text with a tag making it invisible is not counted in the index. a #GtkTextIter a byte index Like gtk_text_iter_set_line_offset(), but the offset is in visible characters, i.e. text with a tag making it invisible is not counted in the offset. a #GtkTextIter a character offset Returns %TRUE if @iter begins a paragraph, i.e. if gtk_text_iter_get_line_offset() would return 0. However this function is potentially more efficient than gtk_text_iter_get_line_offset() because it doesn’t have to compute the offset, it just has to see whether it’s 0. whether @iter begins a line an iterator Determines whether @iter begins a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms). %TRUE if @iter is at the start of a sentence. a #GtkTextIter Returns %TRUE if @tag is toggled on at exactly this point. If @tag is %NULL, returns %TRUE if any tag is toggled on at this point. Note that if gtk_text_iter_starts_tag() returns %TRUE, it means that @iter is at the beginning of the tagged range, and that the character at @iter is inside the tagged range. In other words, unlike gtk_text_iter_ends_tag(), if gtk_text_iter_starts_tag() returns %TRUE, gtk_text_iter_has_tag() will also return %TRUE for the same parameters. whether @iter is the start of a range tagged with @tag an iterator a #GtkTextTag, or %NULL Determines whether @iter begins a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms). %TRUE if @iter is at the start of a word a #GtkTextIter This is equivalent to (gtk_text_iter_starts_tag() || gtk_text_iter_ends_tag()), i.e. it tells you whether a range with @tag applied to it begins or ends at @iter. whether @tag is toggled on or off at @iter an iterator a #GtkTextTag, or %NULL You may wish to begin by reading the [text widget conceptual overview](TextWidget.html) which gives an overview of all the objects and data types related to the text widget and how they work together. A #GtkTextMark is like a bookmark in a text buffer; it preserves a position in the text. You can convert the mark to an iterator using gtk_text_buffer_get_iter_at_mark(). Unlike iterators, marks remain valid across buffer mutations, because their behavior is defined when text is inserted or deleted. When text containing a mark is deleted, the mark remains in the position originally occupied by the deleted text. When text is inserted at a mark, a mark with “left gravity” will be moved to the beginning of the newly-inserted text, and a mark with “right gravity” will be moved to the end. Note that “left” and “right” here refer to logical direction (left is the toward the start of the buffer); in some languages such as Hebrew the logically-leftmost text is not actually on the left when displayed. Marks are reference counted, but the reference count only controls the validity of the memory; marks can be deleted from the buffer at any time with gtk_text_buffer_delete_mark(). Once deleted from the buffer, a mark is essentially useless. Marks optionally have names; these can be convenient to avoid passing the #GtkTextMark object around. Marks are typically created using the gtk_text_buffer_create_mark() function. Creates a text mark. Add it to a buffer using gtk_text_buffer_add_mark(). If @name is %NULL, the mark is anonymous; otherwise, the mark can be retrieved by name using gtk_text_buffer_get_mark(). If a mark has left gravity, and text is inserted at the mark’s current location, the mark will be moved to the left of the newly-inserted text. If the mark has right gravity (@left_gravity = %FALSE), the mark will end up on the right of newly-inserted text. The standard left-to-right cursor is a mark with right gravity (when you type, the cursor stays on the right side of the text you’re typing). new #GtkTextMark mark name or %NULL whether the mark should have left gravity Gets the buffer this mark is located inside, or %NULL if the mark is deleted. the mark’s #GtkTextBuffer a #GtkTextMark Returns %TRUE if the mark has been removed from its buffer with gtk_text_buffer_delete_mark(). See gtk_text_buffer_add_mark() for a way to add it to a buffer again. whether the mark is deleted a #GtkTextMark Determines whether the mark has left gravity. %TRUE if the mark has left gravity, %FALSE otherwise a #GtkTextMark Returns the mark name; returns NULL for anonymous marks. mark name a #GtkTextMark Returns %TRUE if the mark is visible (i.e. a cursor is displayed for it). %TRUE if visible a #GtkTextMark Sets the visibility of @mark; the insertion point is normally visible, i.e. you can see it as a vertical bar. Also, the text widget uses a visible mark to indicate where a drop will occur when dragging-and-dropping text. Most other marks are not visible. Marks are not visible by default. a #GtkTextMark visibility of mark Whether the mark has left gravity. When text is inserted at the mark’s current location, if the mark has left gravity it will be moved to the left of the newly-inserted text, otherwise to the right. The name of the mark or %NULL if the mark is anonymous. Flags affecting how a search is done. If neither #GTK_TEXT_SEARCH_VISIBLE_ONLY nor #GTK_TEXT_SEARCH_TEXT_ONLY are enabled, the match must be exact; the special 0xFFFC character will match embedded pixbufs or child widgets. Search only visible data. A search match may have invisible text interspersed. Search only text. A match may have pixbufs or child widgets mixed inside the matched range. The text will be matched regardless of what case it is in. You may wish to begin by reading the [text widget conceptual overview](TextWidget.html) which gives an overview of all the objects and data types related to the text widget and how they work together. Tags should be in the #GtkTextTagTable for a given #GtkTextBuffer before using them with that buffer. gtk_text_buffer_create_tag() is the best way to create tags. See “gtk3-demo” for numerous examples. For each property of #GtkTextTag, there is a “set” property, e.g. “font-set” corresponds to “font”. These “set” properties reflect whether a property has been set or not. They are maintained by GTK+ and you should not set them independently. Creates a #GtkTextTag. Configure the tag using object arguments, i.e. using g_object_set(). a new #GtkTextTag tag name, or %NULL Emits the “event” signal on the #GtkTextTag. result of signal emission (whether the event was handled) a #GtkTextTag object that received the event, such as a widget the event location where the event was received Emits the #GtkTextTagTable::tag-changed signal on the #GtkTextTagTable where the tag is included. The signal is already emitted when setting a #GtkTextTag property. This function is useful for a #GtkTextTag subclass. a #GtkTextTag. whether the change affects the #GtkTextView layout. Emits the “event” signal on the #GtkTextTag. result of signal emission (whether the event was handled) a #GtkTextTag object that received the event, such as a widget the event location where the event was received Get the tag priority. The tag’s priority. a #GtkTextTag Sets the priority of a #GtkTextTag. Valid priorities start at 0 and go to one less than gtk_text_tag_table_get_size(). Each tag in a table has a unique priority; setting the priority of one tag shifts the priorities of all the other tags in the table to maintain a unique priority for each tag. Higher priority tags “win” if two tags both set the same text attribute. When adding a tag to a tag table, it will be assigned the highest priority in the table by default; so normally the precedence of a set of tags is the order in which they were added to the table, or created with gtk_text_buffer_create_tag(), which adds the tag to the buffer’s table automatically. a #GtkTextTag the new priority Whether the margins accumulate or override each other. When set to %TRUE the margins of this tag are added to the margins of any other non-accumulative margins present. When set to %FALSE the margins override one another (the default). Background color as a #GdkColor. Use #GtkTextTag:background-rgba instead. Background color as a #GdkRGBA. Whether font fallback is enabled. When set to %TRUE, other fonts will be substituted where the current font is missing glyphs. Font description as string, e.g. \"Sans Italic 12\". Note that the initial value of this property depends on the internals of #PangoFontDescription. OpenType font features, as a string. Foreground color as a #GdkColor. Use #GtkTextTag:foreground-rgba instead. Foreground color as a #GdkRGBA. Whether this text is hidden. Note that there may still be problems with the support for invisible text, in particular when navigating programmatically inside a buffer containing invisible segments. The language this text is in, as an ISO code. Pango can use this as a hint when rendering the text. If not set, an appropriate default will be used. Note that the initial value of this property depends on the current locale, see also gtk_get_default_language(). Extra spacing between graphemes, in Pango units. The paragraph background color as a string. The paragraph background color as a #GdkColor. Use #GtkTextTag:paragraph-background-rgba instead. The paragraph background color as a #GdkRGBA. This property modifies the color of strikeouts. If not set, strikeouts will use the forground color. If the #GtkTextTag:strikethrough-rgba property has been set. This property modifies the color of underlines. If not set, underlines will use the forground color. If #GtkTextTag:underline is set to %PANGO_UNDERLINE_ERROR, an alternate color may be applied instead of the foreground. Setting this property will always override those defaults. If the #GtkTextTag:underline-rgba property has been set. The ::event signal is emitted when an event occurs on a region of the buffer marked with this tag. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the object the event was fired from (typically a #GtkTextView) the event which triggered the signal a #GtkTextIter pointing at the location the event occurred result of signal emission (whether the event was handled) a #GtkTextTag object that received the event, such as a widget the event location where the event was received You may wish to begin by reading the [text widget conceptual overview](TextWidget.html) which gives an overview of all the objects and data types related to the text widget and how they work together. # GtkTextTagTables as GtkBuildable The GtkTextTagTable implementation of the GtkBuildable interface supports adding tags by specifying “tag” as the “type” attribute of a `<child>` element. An example of a UI definition fragment specifying tags: |[<!-- language="xml" --> <object class="GtkTextTagTable"> <child type="tag"> <object class="GtkTextTag"/> </child> </object> ]| Creates a new #GtkTextTagTable. The table contains no tags by default. a new #GtkTextTagTable Add a tag to the table. The tag is assigned the highest priority in the table. @tag must not be in a tag table already, and may not have the same name as an already-added tag. %TRUE on success. a #GtkTextTagTable a #GtkTextTag Calls @func on each tag in @table, with user data @data. Note that the table may not be modified while iterating over it (you can’t add/remove tags). a #GtkTextTagTable a function to call on each tag user data Returns the size of the table (number of tags) number of tags in @table a #GtkTextTagTable Look up a named tag. The tag, or %NULL if none by that name is in the table. a #GtkTextTagTable name of a tag Remove a tag from the table. If a #GtkTextBuffer has @table as its tag table, the tag is removed from the buffer. The table’s reference to the tag is removed, so the tag will end up destroyed if you don’t have a reference to it. a #GtkTextTagTable a #GtkTextTag the added tag. the changed tag. whether the change affects the #GtkTextView layout. the removed tag. the #GtkTextTag data passed to gtk_text_tag_table_foreach() You may wish to begin by reading the [text widget conceptual overview](TextWidget.html) which gives an overview of all the objects and data types related to the text widget and how they work together. # CSS nodes |[<!-- language="plain" --> textview.view ├── border.top ├── border.left ├── text │ ╰── [selection] ├── border.right ├── border.bottom ╰── [window.popup] ]| GtkTextView has a main css node with name textview and style class .view, and subnodes for each of the border windows, and the main text area, with names border and text, respectively. The border nodes each get one of the style classes .left, .right, .top or .bottom. A node representing the selection will appear below the text node. If a context menu is opened, the window node will appear as a subnode of the main node. Creates a new #GtkTextView. If you don’t call gtk_text_view_set_buffer() before using the text view, an empty default buffer will be created for you. Get the buffer with gtk_text_view_get_buffer(). If you want to specify your own buffer, consider gtk_text_view_new_with_buffer(). a new #GtkTextView Creates a new #GtkTextView widget displaying the buffer @buffer. One buffer can be shared among many widgets. @buffer may be %NULL to create a default buffer, in which case this function is equivalent to gtk_text_view_new(). The text view adds its own reference count to the buffer; it does not take over an existing reference. a new #GtkTextView. a #GtkTextBuffer The class handler for the #GtkTextView::backspace keybinding signal. The class handler for the #GtkTextview::copy-clipboard keybinding signal. The create_buffer vfunc is called to create a #GtkTextBuffer for the text view. The default implementation is to just call gtk_text_buffer_new(). Since: 3.10 The class handler for the #GtkTextView::cut-clipboard keybinding signal The class handler for the #GtkTextView::delete-from-cursor keybinding signal. The draw_layer vfunc is called before and after the text view is drawing its own text. Applications can override this vfunc in a subclass to draw customized content underneath or above the text. In the %GTK_TEXT_VIEW_LAYER_BELOW_TEXT and %GTK_TEXT_VIEW_LAYER_ABOVE_TEXT the drawing is done in the buffer coordinate space, but the older (deprecated) layers %GTK_TEXT_VIEW_LAYER_BELOW and %GTK_TEXT_VIEW_LAYER_ABOVE work in viewport coordinates, which makes them unnecessarily hard to use. Since: 3.14 The class handler for the #GtkTextView::extend-selection signal. Since 3.16 The class handler for the #GtkTextView::insert-at-cursor keybinding signal. The class handler for the #GtkTextView::move-cursor keybinding signal. The class handler for the #GtkTextView::paste-clipboard keybinding signal. The class handler for the #GtkTextView::populate-popup signal. The class handler for the #GtkTextView::set-anchor keybinding signal. The class handler for the #GtkTextView::toggle-overwrite keybinding signal. Adds a child widget in the text buffer, at the given @anchor. a #GtkTextView a #GtkWidget a #GtkTextChildAnchor in the #GtkTextBuffer for @text_view Adds a child at fixed coordinates in one of the text widget's windows. The window must have nonzero size (see gtk_text_view_set_border_window_size()). Note that the child coordinates are given relative to scrolling. When placing a child in #GTK_TEXT_WINDOW_WIDGET, scrolling is irrelevant, the child floats above all scrollable areas. But when placing a child in one of the scrollable windows (border windows or text window) it will move with the scrolling as needed. a #GtkTextView a #GtkWidget which window the child should appear in X position of child in window coordinates Y position of child in window coordinates Moves the given @iter backward by one display (wrapped) line. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the #GtkTextBuffer. %TRUE if @iter was moved and is not on the end iterator a #GtkTextView a #GtkTextIter Moves the given @iter backward to the next display line start. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the #GtkTextBuffer. %TRUE if @iter was moved and is not on the end iterator a #GtkTextView a #GtkTextIter Converts coordinate (@buffer_x, @buffer_y) to coordinates for the window @win, and stores the result in (@window_x, @window_y). Note that you can’t convert coordinates for a nonexisting window (see gtk_text_view_set_border_window_size()). a #GtkTextView a #GtkTextWindowType, except %GTK_TEXT_WINDOW_PRIVATE buffer x coordinate buffer y coordinate window x coordinate return location or %NULL window y coordinate return location or %NULL Moves the given @iter forward by one display (wrapped) line. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the #GtkTextBuffer. %TRUE if @iter was moved and is not on the end iterator a #GtkTextView a #GtkTextIter Moves the given @iter forward to the next display line end. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the #GtkTextBuffer. %TRUE if @iter was moved and is not on the end iterator a #GtkTextView a #GtkTextIter Returns whether pressing the Tab key inserts a tab characters. gtk_text_view_set_accepts_tab(). %TRUE if pressing the Tab key inserts a tab character, %FALSE if pressing the Tab key moves the keyboard focus. A #GtkTextView Gets the width of the specified border window. See gtk_text_view_set_border_window_size(). width of window a #GtkTextView window to return size from Gets the bottom margin for text in the @text_view. bottom margin in pixels a #GtkTextView Returns the #GtkTextBuffer being displayed by this text view. The reference count on the buffer is not incremented; the caller of this function won’t own a new reference. a #GtkTextBuffer a #GtkTextView Given an @iter within a text layout, determine the positions of the strong and weak cursors if the insertion point is at that iterator. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction of the paragraph are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the paragraph are inserted. If @iter is %NULL, the actual cursor position is used. Note that if @iter happens to be the actual cursor position, and there is currently an IM preedit sequence being entered, the returned locations will be adjusted to account for the preedit cursor’s offset within the preedit sequence. The rectangle position is in buffer coordinates; use gtk_text_view_buffer_to_window_coords() to convert these coordinates to coordinates for one of the windows in the text view. a #GtkTextView a #GtkTextIter location to store the strong cursor position (may be %NULL) location to store the weak cursor position (may be %NULL) Find out whether the cursor should be displayed. whether the insertion mark is visible a #GtkTextView Obtains a copy of the default text attributes. These are the attributes used for text unless a tag overrides them. You’d typically pass the default attributes in to gtk_text_iter_get_attributes() in order to get the attributes in effect at a given text position. The return value is a copy owned by the caller of this function, and should be freed with gtk_text_attributes_unref(). a new #GtkTextAttributes a #GtkTextView Returns the default editability of the #GtkTextView. Tags in the buffer may override this setting for some ranges of text. whether text is editable by default a #GtkTextView Gets the horizontal-scrolling #GtkAdjustment. Use gtk_scrollable_get_hadjustment() pointer to the horizontal #GtkAdjustment a #GtkTextView Gets the default indentation of paragraphs in @text_view. Tags in the view’s buffer may override the default. The indentation may be negative. number of pixels of indentation a #GtkTextView Gets the value of the #GtkTextView:input-hints property. a #GtkTextView Gets the value of the #GtkTextView:input-purpose property. a #GtkTextView Retrieves the iterator at buffer coordinates @x and @y. Buffer coordinates are coordinates for the entire buffer, not just the currently-displayed portion. If you have coordinates from an event, you have to convert those to buffer coordinates with gtk_text_view_window_to_buffer_coords(). %TRUE if the position is over text a #GtkTextView a #GtkTextIter x position, in buffer coordinates y position, in buffer coordinates Retrieves the iterator pointing to the character at buffer coordinates @x and @y. Buffer coordinates are coordinates for the entire buffer, not just the currently-displayed portion. If you have coordinates from an event, you have to convert those to buffer coordinates with gtk_text_view_window_to_buffer_coords(). Note that this is different from gtk_text_view_get_iter_at_location(), which returns cursor locations, i.e. positions between characters. %TRUE if the position is over text a #GtkTextView a #GtkTextIter if non-%NULL, location to store an integer indicating where in the grapheme the user clicked. It will either be zero, or the number of characters in the grapheme. 0 represents the trailing edge of the grapheme. x position, in buffer coordinates y position, in buffer coordinates Gets a rectangle which roughly contains the character at @iter. The rectangle position is in buffer coordinates; use gtk_text_view_buffer_to_window_coords() to convert these coordinates to coordinates for one of the windows in the text view. a #GtkTextView a #GtkTextIter bounds of the character at @iter Gets the default justification of paragraphs in @text_view. Tags in the buffer may override the default. default justification a #GtkTextView Gets the default left margin size of paragraphs in the @text_view. Tags in the buffer may override the default. left margin in pixels a #GtkTextView Gets the #GtkTextIter at the start of the line containing the coordinate @y. @y is in buffer coordinates, convert from window coordinates with gtk_text_view_window_to_buffer_coords(). If non-%NULL, @line_top will be filled with the coordinate of the top edge of the line. a #GtkTextView a #GtkTextIter a y coordinate return location for top coordinate of the line Gets the y coordinate of the top of the line containing @iter, and the height of the line. The coordinate is a buffer coordinate; convert to window coordinates with gtk_text_view_buffer_to_window_coords(). a #GtkTextView a #GtkTextIter return location for a y coordinate return location for a height Gets the value of the #GtkTextView:monospace property. %TRUE if monospace fonts are desired a #GtkTextView Returns whether the #GtkTextView is in overwrite mode or not. whether @text_view is in overwrite mode or not. a #GtkTextView Gets the default number of pixels to put above paragraphs. Adding this function with gtk_text_view_get_pixels_below_lines() is equal to the line space between each paragraph. default number of pixels above paragraphs a #GtkTextView Gets the value set by gtk_text_view_set_pixels_below_lines(). The line space is the sum of the value returned by this function and the value returned by gtk_text_view_get_pixels_above_lines(). default number of blank pixels below paragraphs a #GtkTextView Gets the value set by gtk_text_view_set_pixels_inside_wrap(). default number of pixels of blank space between wrapped lines a #GtkTextView Gets the default right margin for text in @text_view. Tags in the buffer may override the default. right margin in pixels a #GtkTextView Gets the default tabs for @text_view. Tags in the buffer may override the defaults. The returned array will be %NULL if “standard” (8-space) tabs are used. Free the return value with pango_tab_array_free(). copy of default tab array, or %NULL if “standard" tabs are used; must be freed with pango_tab_array_free(). a #GtkTextView Gets the top margin for text in the @text_view. top margin in pixels a #GtkTextView Gets the vertical-scrolling #GtkAdjustment. Use gtk_scrollable_get_vadjustment() pointer to the vertical #GtkAdjustment a #GtkTextView Fills @visible_rect with the currently-visible region of the buffer, in buffer coordinates. Convert to window coordinates with gtk_text_view_buffer_to_window_coords(). a #GtkTextView rectangle to fill Retrieves the #GdkWindow corresponding to an area of the text view; possible windows include the overall widget window, child windows on the left, right, top, bottom, and the window that displays the text buffer. Windows are %NULL and nonexistent if their width or height is 0, and are nonexistent before the widget has been realized. a #GdkWindow, or %NULL a #GtkTextView window to get Usually used to find out which window an event corresponds to. If you connect to an event signal on @text_view, this function should be called on `event->window` to see which window it was. the window type. a #GtkTextView a window type Gets the line wrapping for the view. the line wrap setting a #GtkTextView Allow the #GtkTextView input method to internally handle key press and release events. If this function returns %TRUE, then no further processing should be done for this key event. See gtk_im_context_filter_keypress(). Note that you are expected to call this function from your handler when overriding key event handling. This is needed in the case when you need to insert your own key handling between the input method and the default key event handling of the #GtkTextView. |[<!-- language="C" --> static gboolean gtk_foo_bar_key_press_event (GtkWidget *widget, GdkEventKey *event) { guint keyval; gdk_event_get_keyval ((GdkEvent*)event, &keyval); if (keyval == GDK_KEY_Return || keyval == GDK_KEY_KP_Enter) { if (gtk_text_view_im_context_filter_keypress (GTK_TEXT_VIEW (widget), event)) return TRUE; } // Do some stuff return GTK_WIDGET_CLASS (gtk_foo_bar_parent_class)->key_press_event (widget, event); } ]| %TRUE if the input method handled the key event. a #GtkTextView the key event Updates the position of a child, as for gtk_text_view_add_child_in_window(). a #GtkTextView child widget already added to the text view new X position in window coordinates new Y position in window coordinates Moves a mark within the buffer so that it's located within the currently-visible text area. %TRUE if the mark moved (wasn’t already onscreen) a #GtkTextView a #GtkTextMark Move the iterator a given number of characters visually, treating it as the strong cursor position. If @count is positive, then the new strong cursor position will be @count positions to the right of the old cursor position. If @count is negative then the new strong cursor position will be @count positions to the left of the old cursor position. In the presence of bi-directional text, the correspondence between logical and visual order will depend on the direction of the current run, and there may be jumps when the cursor is moved off of the end of a run. %TRUE if @iter moved and is not on the end iterator a #GtkTextView a #GtkTextIter number of characters to move (negative moves left, positive moves right) Moves the cursor to the currently visible region of the buffer, it it isn’t there already. %TRUE if the cursor had to be moved. a #GtkTextView Ensures that the cursor is shown (i.e. not in an 'off' blink interval) and resets the time that it will stay blinking (or visible, in case blinking is disabled). This function should be called in response to user input (e.g. from derived classes that override the textview's #GtkWidget::key-press-event handler). a #GtkTextView Reset the input method context of the text view if needed. This can be necessary in the case where modifying the buffer would confuse on-going input method behavior. a #GtkTextView Scrolls @text_view the minimum distance such that @mark is contained within the visible area of the widget. a #GtkTextView a mark in the buffer for @text_view Scrolls @text_view so that @iter is on the screen in the position indicated by @xalign and @yalign. An alignment of 0.0 indicates left or top, 1.0 indicates right or bottom, 0.5 means center. If @use_align is %FALSE, the text scrolls the minimal distance to get the mark onscreen, possibly not scrolling at all. The effective screen for purposes of this function is reduced by a margin of size @within_margin. Note that this function uses the currently-computed height of the lines in the text buffer. Line heights are computed in an idle handler; so this function may not have the desired effect if it’s called before the height computations. To avoid oddness, consider using gtk_text_view_scroll_to_mark() which saves a point to be scrolled to after line validation. %TRUE if scrolling occurred a #GtkTextView a #GtkTextIter margin as a [0.0,0.5) fraction of screen size whether to use alignment arguments (if %FALSE, just get the mark onscreen) horizontal alignment of mark within visible area vertical alignment of mark within visible area Scrolls @text_view so that @mark is on the screen in the position indicated by @xalign and @yalign. An alignment of 0.0 indicates left or top, 1.0 indicates right or bottom, 0.5 means center. If @use_align is %FALSE, the text scrolls the minimal distance to get the mark onscreen, possibly not scrolling at all. The effective screen for purposes of this function is reduced by a margin of size @within_margin. a #GtkTextView a #GtkTextMark margin as a [0.0,0.5) fraction of screen size whether to use alignment arguments (if %FALSE, just get the mark onscreen) horizontal alignment of mark within visible area vertical alignment of mark within visible area Sets the behavior of the text widget when the Tab key is pressed. If @accepts_tab is %TRUE, a tab character is inserted. If @accepts_tab is %FALSE the keyboard focus is moved to the next widget in the focus chain. A #GtkTextView %TRUE if pressing the Tab key should insert a tab character, %FALSE, if pressing the Tab key should move the keyboard focus. Sets the width of %GTK_TEXT_WINDOW_LEFT or %GTK_TEXT_WINDOW_RIGHT, or the height of %GTK_TEXT_WINDOW_TOP or %GTK_TEXT_WINDOW_BOTTOM. Automatically destroys the corresponding window if the size is set to 0, and creates the window if the size is set to non-zero. This function can only be used for the “border windows”, and it won’t work with %GTK_TEXT_WINDOW_WIDGET, %GTK_TEXT_WINDOW_TEXT, or %GTK_TEXT_WINDOW_PRIVATE. a #GtkTextView window to affect width or height of the window Sets the bottom margin for text in @text_view. Note that this function is confusingly named. In CSS terms, the value set here is padding. a #GtkTextView bottom margin in pixels Sets @buffer as the buffer being displayed by @text_view. The previous buffer displayed by the text view is unreferenced, and a reference is added to @buffer. If you owned a reference to @buffer before passing it to this function, you must remove that reference yourself; #GtkTextView will not “adopt” it. a #GtkTextView a #GtkTextBuffer Toggles whether the insertion point should be displayed. A buffer with no editable text probably shouldn’t have a visible cursor, so you may want to turn the cursor off. Note that this property may be overridden by the #GtkSettings:gtk-keynave-use-caret settings. a #GtkTextView whether to show the insertion cursor Sets the default editability of the #GtkTextView. You can override this default setting with tags in the buffer, using the “editable” attribute of tags. a #GtkTextView whether it’s editable Sets the default indentation for paragraphs in @text_view. Tags in the buffer may override the default. a #GtkTextView indentation in pixels Sets the #GtkTextView:input-hints property, which allows input methods to fine-tune their behaviour. a #GtkTextView the hints Sets the #GtkTextView:input-purpose property which can be used by on-screen keyboards and other input methods to adjust their behaviour. a #GtkTextView the purpose Sets the default justification of text in @text_view. Tags in the view’s buffer may override the default. a #GtkTextView justification Sets the default left margin for text in @text_view. Tags in the buffer may override the default. Note that this function is confusingly named. In CSS terms, the value set here is padding. a #GtkTextView left margin in pixels Sets the #GtkTextView:monospace property, which indicates that the text view should use monospace fonts. a #GtkTextView %TRUE to request monospace styling Changes the #GtkTextView overwrite mode. a #GtkTextView %TRUE to turn on overwrite mode, %FALSE to turn it off Sets the default number of blank pixels above paragraphs in @text_view. Tags in the buffer for @text_view may override the defaults. a #GtkTextView pixels above paragraphs Sets the default number of pixels of blank space to put below paragraphs in @text_view. May be overridden by tags applied to @text_view’s buffer. a #GtkTextView pixels below paragraphs Sets the default number of pixels of blank space to leave between display/wrapped lines within a paragraph. May be overridden by tags in @text_view’s buffer. a #GtkTextView default number of pixels between wrapped lines Sets the default right margin for text in the text view. Tags in the buffer may override the default. Note that this function is confusingly named. In CSS terms, the value set here is padding. a #GtkTextView right margin in pixels Sets the default tab stops for paragraphs in @text_view. Tags in the buffer may override the default. a #GtkTextView tabs as a #PangoTabArray Sets the top margin for text in @text_view. Note that this function is confusingly named. In CSS terms, the value set here is padding. a #GtkTextView top margin in pixels Sets the line wrapping for the view. a #GtkTextView a #GtkWrapMode Determines whether @iter is at the start of a display line. See gtk_text_view_forward_display_line() for an explanation of display lines vs. paragraphs. %TRUE if @iter begins a wrapped line a #GtkTextView a #GtkTextIter Converts coordinates on the window identified by @win to buffer coordinates, storing the result in (@buffer_x,@buffer_y). Note that you can’t convert coordinates for a nonexisting window (see gtk_text_view_set_border_window_size()). a #GtkTextView a #GtkTextWindowType except %GTK_TEXT_WINDOW_PRIVATE window x coordinate window y coordinate buffer x coordinate return location or %NULL buffer y coordinate return location or %NULL The bottom margin for text in the text view. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Don't confuse this property with #GtkWidget:margin-bottom. Which IM (input method) module should be used for this text_view. See #GtkIMContext. Setting this to a non-%NULL value overrides the system-wide IM module setting. See the GtkSettings #GtkSettings:gtk-im-module property. Additional hints (beyond #GtkTextView:input-purpose) that allow input methods to fine-tune their behaviour. The purpose of this text field. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. The default left margin for text in the text view. Tags in the buffer may override the default. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Don't confuse this property with #GtkWidget:margin-left. If :populate-all is %TRUE, the #GtkTextView::populate-popup signal is also emitted for touch popups. The default right margin for text in the text view. Tags in the buffer may override the default. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Don't confuse this property with #GtkWidget:margin-right. The top margin for text in the text view. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Don't confuse this property with #GtkWidget:margin-top. The ::backspace signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. The default bindings for this signal are Backspace and Shift-Backspace. The ::copy-clipboard signal is a [keybinding signal][GtkBindingSignal] which gets emitted to copy the selection to the clipboard. The default bindings for this signal are Ctrl-c and Ctrl-Insert. The ::cut-clipboard signal is a [keybinding signal][GtkBindingSignal] which gets emitted to cut the selection to the clipboard. The default bindings for this signal are Ctrl-x and Shift-Delete. The ::delete-from-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a text deletion. If the @type is %GTK_DELETE_CHARS, GTK+ deletes the selection if there is one, otherwise it deletes the requested number of characters. The default bindings for this signal are Delete for deleting a character, Ctrl-Delete for deleting a word and Ctrl-Backspace for deleting a word backwords. the granularity of the deletion, as a #GtkDeleteType the number of @type units to delete The ::extend-selection signal is emitted when the selection needs to be extended at @location. %GDK_EVENT_STOP to stop other handlers from being invoked for the event. %GDK_EVENT_PROPAGATE to propagate the event further. the granularity type the location where to extend the selection where the selection should start where the selection should end The ::insert-at-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates the insertion of a fixed string at the cursor. This signal has no default bindings. the string to insert The ::insert-emoji signal is a [keybinding signal][GtkBindingSignal] which gets emitted to present the Emoji chooser for the @text_view. The default bindings for this signal are Ctrl-. and Ctrl-; The ::move-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a cursor movement. If the cursor is not visible in @text_view, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifer does not. There are too many key combinations to list them all here. - Arrow keys move by individual characters/lines - Ctrl-arrow key combinations move by words/paragraphs - Home/End keys move to the ends of the buffer - PageUp/PageDown keys move vertically by pages - Ctrl-PageUp/PageDown keys move horizontally by pages the granularity of the move, as a #GtkMovementStep the number of @step units to move %TRUE if the move should extend the selection The ::move-viewport signal is a [keybinding signal][GtkBindingSignal] which can be bound to key combinations to allow the user to move the viewport, i.e. change what part of the text view is visible in a containing scrolled window. There are no default bindings for this signal. the granularity of the movement, as a #GtkScrollStep the number of @step units to move The ::paste-clipboard signal is a [keybinding signal][GtkBindingSignal] which gets emitted to paste the contents of the clipboard into the text view. The default bindings for this signal are Ctrl-v and Shift-Insert. The ::populate-popup signal gets emitted before showing the context menu of the text view. If you need to add items to the context menu, connect to this signal and append your items to the @popup, which will be a #GtkMenu in this case. If #GtkTextView:populate-all is %TRUE, this signal will also be emitted to populate touch popups. In this case, @popup will be a different container, e.g. a #GtkToolbar. The signal handler should not make assumptions about the type of @widget, but check whether @popup is a #GtkMenu or #GtkToolbar or another kind of container. the container that is being populated If an input method is used, the typed text will not immediately be committed to the buffer. So if you are interested in the text, connect to this signal. This signal is only emitted if the text at the given position is actually editable. the current preedit string The ::select-all signal is a [keybinding signal][GtkBindingSignal] which gets emitted to select or unselect the complete contents of the text view. The default bindings for this signal are Ctrl-a and Ctrl-/ for selecting and Shift-Ctrl-a and Ctrl-\ for unselecting. %TRUE to select, %FALSE to unselect The ::set-anchor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates setting the "anchor" mark. The "anchor" mark gets placed at the same position as the "insert" mark. This signal has no default bindings. The ::toggle-cursor-visible signal is a [keybinding signal][GtkBindingSignal] which gets emitted to toggle the #GtkTextView:cursor-visible property. The default binding for this signal is F7. The ::toggle-overwrite signal is a [keybinding signal][GtkBindingSignal] which gets emitted to toggle the overwrite mode of the text view. The default bindings for this signal is Insert. The object class structure needs to be the first The class handler for the #GtkTextView::populate-popup signal. The class handler for the #GtkTextView::move-cursor keybinding signal. The class handler for the #GtkTextView::set-anchor keybinding signal. The class handler for the #GtkTextView::insert-at-cursor keybinding signal. The class handler for the #GtkTextView::delete-from-cursor keybinding signal. The class handler for the #GtkTextView::backspace keybinding signal. The class handler for the #GtkTextView::cut-clipboard keybinding signal The class handler for the #GtkTextview::copy-clipboard keybinding signal. The class handler for the #GtkTextView::paste-clipboard keybinding signal. The class handler for the #GtkTextView::toggle-overwrite keybinding signal. The create_buffer vfunc is called to create a #GtkTextBuffer for the text view. The default implementation is to just call gtk_text_buffer_new(). Since: 3.10 The draw_layer vfunc is called before and after the text view is drawing its own text. Applications can override this vfunc in a subclass to draw customized content underneath or above the text. In the %GTK_TEXT_VIEW_LAYER_BELOW_TEXT and %GTK_TEXT_VIEW_LAYER_ABOVE_TEXT the drawing is done in the buffer coordinate space, but the older (deprecated) layers %GTK_TEXT_VIEW_LAYER_BELOW and %GTK_TEXT_VIEW_LAYER_ABOVE work in viewport coordinates, which makes them unnecessarily hard to use. Since: 3.14 The class handler for the #GtkTextView::extend-selection signal. Since 3.16 Used to reference the layers of #GtkTextView for the purpose of customized drawing with the ::draw_layer vfunc. Old deprecated layer, use %GTK_TEXT_VIEW_LAYER_BELOW_TEXT instead Old deprecated layer, use %GTK_TEXT_VIEW_LAYER_ABOVE_TEXT instead The layer rendered below the text (but above the background). Since: 3.20 The layer rendered above the text. Since: 3.20 Used to reference the parts of #GtkTextView. Invalid value, used as a marker Window that floats over scrolling areas. Scrollable text window. Left side border window. Right side border window. Top border window. Bottom border window. #GtkThemingEngine was the object used for rendering themed content in GTK+ widgets. It used to allow overriding GTK+'s default implementation of rendering functions by allowing engines to be loaded as modules. #GtkThemingEngine has been deprecated in GTK+ 3.14 and will be ignored for rendering. The advancements in CSS theming are good enough to allow themers to achieve their goals without the need to modify source code. Loads and initializes a theming engine module from the standard directories. A theming engine, or %NULL if the engine @name doesn’t exist. Theme engine name to load Registers a property so it can be used in the CSS file format, on the CSS file the property will look like "-${@name_space}-${property_name}". being ${property_name} the given to @pspec. @name_space will usually be the theme engine name. For any type a @parse_func may be provided, being this function used for turning any property value (between “:” and “;”) in CSS to the #GValue needed. For basic types there is already builtin parsing support, so %NULL may be provided for these cases. Engines must ensure property registration happens exactly once, usually GTK+ deals with theming engines as singletons, so this should be guaranteed to happen once, but bear this in mind when creating #GtkThemeEngines yourself. In order to make use of the custom registered properties in the CSS file, make sure the engine is loaded first by specifying the engine property, either in a previous rule or within the same one. |[ * { engine: someengine; -SomeEngine-custom-property: 2; } ]| Code should use the default properties provided by CSS. namespace for the property name parsing function to use, or %NULL the #GParamSpec for the new property Renders an area displaying activity, such as in #GtkSpinner, or #GtkProgressBar. Renders an arrow pointing to a certain direction. Renders the background area of a widget region. Renders a checkmark, as in #GtkCheckButton. Renders an element what will expose/expand part of the UI, as in #GtkExpander. Renders a extension to a box, usually a notebook tab. Renders the focus indicator. Renders the frame around a widget area. Renders the frame around a widget area with a gap in it. Renders a handle to drag UI elements, as in #GtkPaned. Renders an icon given as a #GdkPixbuf. Renders an icon as a #GdkPixbuf. Renders an icon given as a #cairo_surface_t. Renders a #PangoLayout Renders a line between two points. Renders an option, as in #GtkRadioButton. Renders a slider control, as in #GtkScale. Retrieves several style property values that apply to the currently rendered element. a #GtkThemingEngine state to retrieve values for property name /return value pairs, followed by %NULL Gets the background color for a given state. a #GtkThemingEngine state to retrieve the color for return value for the background color Gets the border for a given state as a #GtkBorder. a #GtkThemingEngine state to retrieve the border for return value for the border settings Gets the border color for a given state. a #GtkThemingEngine state to retrieve the color for return value for the border color Gets the foreground color for a given state. a #GtkThemingEngine state to retrieve the color for return value for the foreground color Returns the widget direction used for rendering. Use gtk_theming_engine_get_state() and check for #GTK_STATE_FLAG_DIR_LTR and #GTK_STATE_FLAG_DIR_RTL instead. the widget direction a #GtkThemingEngine Returns the font description for a given state. Use gtk_theming_engine_get() the #PangoFontDescription for the given state. This object is owned by GTK+ and should not be freed. a #GtkThemingEngine state to retrieve the font for Returns the widget direction used for rendering. the widget direction a #GtkThemingEngine Gets the margin for a given state as a #GtkBorder. a #GtkThemingEngine state to retrieve the border for return value for the margin settings Gets the padding for a given state as a #GtkBorder. a #GtkThemingEngine state to retrieve the padding for return value for the padding settings Returns the widget path used for style matching. A #GtkWidgetPath a #GtkThemingEngine Gets a property value as retrieved from the style settings that apply to the currently rendered element. a #GtkThemingEngine the property name state to retrieve the value for return location for the property value, you must free this memory using g_value_unset() once you are done with it. Returns the #GdkScreen to which @engine currently rendering to. a #GdkScreen, or %NULL. a #GtkThemingEngine returns the state used when rendering. the state flags a #GtkThemingEngine Retrieves several widget style properties from @engine according to the currently rendered content’s style. a #GtkThemingEngine property name /return value pairs, followed by %NULL Gets the value for a widget style property. a #GtkThemingEngine the name of the widget style property Return location for the property value, free with g_value_unset() after use. Retrieves several widget style properties from @engine according to the currently rendered content’s style. a #GtkThemingEngine va_list of property name/return location pairs, followed by %NULL Retrieves several style property values that apply to the currently rendered element. a #GtkThemingEngine state to retrieve values for va_list of property name/return location pairs, followed by %NULL Returns %TRUE if the currently rendered contents have defined the given class name. %TRUE if @engine has @class_name defined a #GtkThemingEngine class name to look up Returns %TRUE if the currently rendered contents have the region defined. If @flags_return is not %NULL, it is set to the flags affecting the region. %TRUE if region is defined a #GtkThemingEngine a region name return location for region flags Looks up and resolves a color name in the current style’s color map. %TRUE if @color_name was found and resolved, %FALSE otherwise a #GtkThemingEngine color name to lookup Return location for the looked up color Returns %TRUE if there is a transition animation running for the current region (see gtk_style_context_push_animatable_region()). If @progress is not %NULL, the animation progress will be returned there, 0.0 means the state is closest to being %FALSE, while 1.0 means it’s closest to being %TRUE. This means transition animations will run from 0 to 1 when @state is being set to %TRUE and from 1 to 0 when it’s being set to %FALSE. Always returns %FALSE %TRUE if there is a running transition animation for @state. a #GtkThemingEngine a widget state return location for the transition progress The theming engine name, this name will be used when registering custom properties, for a theming engine named "Clearlooks" registering a "glossy" custom property, it could be referenced in the CSS file as |[ -Clearlooks-glossy: true; ]| Base class for theming engines. The parent class. Renders a line between two points. Renders the background area of a widget region. Renders the frame around a widget area. Renders the frame around a widget area with a gap in it. Renders a extension to a box, usually a notebook tab. Renders a checkmark, as in #GtkCheckButton. Renders an option, as in #GtkRadioButton. Renders an arrow pointing to a certain direction. Renders an element what will expose/expand part of the UI, as in #GtkExpander. Renders the focus indicator. Renders a #PangoLayout Renders a slider control, as in #GtkScale. Renders a handle to drag UI elements, as in #GtkPaned. Renders an area displaying activity, such as in #GtkSpinner, or #GtkProgressBar. Renders an icon as a #GdkPixbuf. Renders an icon given as a #GdkPixbuf. Renders an icon given as a #cairo_surface_t. Callback type for adding a function to update animations. See gtk_widget_add_tick_callback(). %G_SOURCE_CONTINUE if the tick callback should continue to be called, %G_SOURCE_REMOVE if the tick callback should be removed. the widget the frame clock for the widget (same as calling gtk_widget_get_frame_clock()) user data passed to gtk_widget_add_tick_callback(). A #GtkToggleAction corresponds roughly to a #GtkCheckMenuItem. It has an “active” state specifying whether the action has been checked or not. Creates a new #GtkToggleAction object. To add the action to a #GtkActionGroup and set the accelerator for the action, call gtk_action_group_add_action_with_accel(). a new #GtkToggleAction A unique name for the action The label displayed in menu items and on buttons, or %NULL A tooltip for the action, or %NULL The stock icon to display in widgets representing the action, or %NULL Emits the “toggled” signal on the toggle action. the action object Returns the checked state of the toggle action. the checked state of the toggle action the action object Returns whether the action should have proxies like a radio action. whether the action should have proxies like a radio action. the action object Sets the checked state on the toggle action. the action object whether the action should be checked or not Sets whether the action should have proxies like a radio action. the action object whether the action should have proxies like a radio action Emits the “toggled” signal on the toggle action. the action object Whether the toggle action should be active. Whether the proxies for this action look like radio action proxies. This is an appearance property and thus only applies if #GtkActivatable:use-action-appearance is %TRUE. Should be connected if you wish to perform an action whenever the #GtkToggleAction state is changed. the action object #GtkToggleActionEntry structs are used with gtk_action_group_add_toggle_actions() to construct toggle actions. The name of the action. The stock id for the action, or the name of an icon from the icon theme. The label for the action. This field should typically be marked for translation, see gtk_action_group_set_translation_domain(). The accelerator for the action, in the format understood by gtk_accelerator_parse(). The tooltip for the action. This field should typically be marked for translation, see gtk_action_group_set_translation_domain(). The function to call when the action is activated. The initial state of the toggle action. A #GtkToggleButton is a #GtkButton which will remain “pressed-in” when clicked. Clicking again will cause the toggle button to return to its normal state. A toggle button is created by calling either gtk_toggle_button_new() or gtk_toggle_button_new_with_label(). If using the former, it is advisable to pack a widget, (such as a #GtkLabel and/or a #GtkImage), into the toggle button’s container. (See #GtkButton for more information). The state of a #GtkToggleButton can be set specifically using gtk_toggle_button_set_active(), and retrieved using gtk_toggle_button_get_active(). To simply switch the state of a toggle button, use gtk_toggle_button_toggled(). # CSS nodes GtkToggleButton has a single CSS node with name button. To differentiate it from a plain #GtkButton, it gets the .toggle style class. ## Creating two #GtkToggleButton widgets. |[<!-- language="C" --> static void output_state (GtkToggleButton *source, gpointer user_data) { printf ("Active: %d\n", gtk_toggle_button_get_active (source)); } void make_toggles (void) { GtkWidget *window, *toggle1, *toggle2; GtkWidget *box; const char *text; window = gtk_window_new (GTK_WINDOW_TOPLEVEL); box = gtk_box_new (GTK_ORIENTATION_VERTICAL, 12); text = "Hi, I’m a toggle button."; toggle1 = gtk_toggle_button_new_with_label (text); // Makes this toggle button invisible gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle1), TRUE); g_signal_connect (toggle1, "toggled", G_CALLBACK (output_state), NULL); gtk_container_add (GTK_CONTAINER (box), toggle1); text = "Hi, I’m a toggle button."; toggle2 = gtk_toggle_button_new_with_label (text); gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle2), FALSE); g_signal_connect (toggle2, "toggled", G_CALLBACK (output_state), NULL); gtk_container_add (GTK_CONTAINER (box), toggle2); gtk_container_add (GTK_CONTAINER (window), box); gtk_widget_show_all (window); } ]| Creates a new toggle button. A widget should be packed into the button, as in gtk_button_new(). a new toggle button. Creates a new toggle button with a text label. a new toggle button. a string containing the message to be placed in the toggle button. Creates a new #GtkToggleButton containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the button. a new #GtkToggleButton the text of the button, with an underscore in front of the mnemonic character Emits the #GtkToggleButton::toggled signal on the #GtkToggleButton. There is no good reason for an application ever to call this function. a #GtkToggleButton. Queries a #GtkToggleButton and returns its current state. Returns %TRUE if the toggle button is pressed in and %FALSE if it is raised. a #gboolean value. a #GtkToggleButton. Gets the value set by gtk_toggle_button_set_inconsistent(). %TRUE if the button is displayed as inconsistent, %FALSE otherwise a #GtkToggleButton Retrieves whether the button is displayed as a separate indicator and label. See gtk_toggle_button_set_mode(). %TRUE if the togglebutton is drawn as a separate indicator and label. a #GtkToggleButton Sets the status of the toggle button. Set to %TRUE if you want the GtkToggleButton to be “pressed in”, and %FALSE to raise it. This action causes the #GtkToggleButton::toggled signal and the #GtkButton::clicked signal to be emitted. a #GtkToggleButton. %TRUE or %FALSE. If the user has selected a range of elements (such as some text or spreadsheet cells) that are affected by a toggle button, and the current values in that range are inconsistent, you may want to display the toggle in an “in between” state. This function turns on “in between” display. Normally you would turn off the inconsistent state again if the user toggles the toggle button. This has to be done manually, gtk_toggle_button_set_inconsistent() only affects visual appearance, it doesn’t affect the semantics of the button. a #GtkToggleButton %TRUE if state is inconsistent Sets whether the button is displayed as a separate indicator and label. You can call this function on a checkbutton or a radiobutton with @draw_indicator = %FALSE to make the button look like a normal button. This can be used to create linked strip of buttons that work like a #GtkStackSwitcher. This function only affects instances of classes like #GtkCheckButton and #GtkRadioButton that derive from #GtkToggleButton, not instances of #GtkToggleButton itself. a #GtkToggleButton if %TRUE, draw the button as a separate indicator and label; if %FALSE, draw the button like a normal button Emits the #GtkToggleButton::toggled signal on the #GtkToggleButton. There is no good reason for an application ever to call this function. a #GtkToggleButton. Should be connected if you wish to perform an action whenever the #GtkToggleButton's state is changed. a #GtkToggleButton. A #GtkToggleToolButton is a #GtkToolItem that contains a toggle button. Use gtk_toggle_tool_button_new() to create a new GtkToggleToolButton. # CSS nodes GtkToggleToolButton has a single CSS node with name togglebutton. Returns a new #GtkToggleToolButton a newly created #GtkToggleToolButton Creates a new #GtkToggleToolButton containing the image and text from a stock item. Some stock ids have preprocessor macros like #GTK_STOCK_OK and #GTK_STOCK_APPLY. It is an error if @stock_id is not a name of a stock item. Use gtk_toggle_tool_button_new() instead. A new #GtkToggleToolButton the name of the stock item Signal emitted whenever the toggle tool button changes state. Queries a #GtkToggleToolButton and returns its current state. Returns %TRUE if the toggle button is pressed in and %FALSE if it is raised. %TRUE if the toggle tool button is pressed in, %FALSE if not a #GtkToggleToolButton Sets the status of the toggle tool button. Set to %TRUE if you want the GtkToggleButton to be “pressed in”, and %FALSE to raise it. This action causes the toggled signal to be emitted. a #GtkToggleToolButton whether @button should be active If the toggle tool button should be pressed in. Emitted whenever the toggle tool button changes state. The parent class. Signal emitted whenever the toggle tool button changes state. #GtkToolButtons are #GtkToolItems containing buttons. Use gtk_tool_button_new() to create a new #GtkToolButton. The label of a #GtkToolButton is determined by the properties #GtkToolButton:label-widget, #GtkToolButton:label, and #GtkToolButton:stock-id. If #GtkToolButton:label-widget is non-%NULL, then that widget is used as the label. Otherwise, if #GtkToolButton:label is non-%NULL, that string is used as the label. Otherwise, if #GtkToolButton:stock-id is non-%NULL, the label is determined by the stock item. Otherwise, the button does not have a label. The icon of a #GtkToolButton is determined by the properties #GtkToolButton:icon-widget and #GtkToolButton:stock-id. If #GtkToolButton:icon-widget is non-%NULL, then that widget is used as the icon. Otherwise, if #GtkToolButton:stock-id is non-%NULL, the icon is determined by the stock item. Otherwise, the button does not have a icon. # CSS nodes GtkToolButton has a single CSS node with name toolbutton. Creates a new #GtkToolButton using @icon_widget as contents and @label as label. A new #GtkToolButton a widget that will be used as the button contents, or %NULL a string that will be used as label, or %NULL Creates a new #GtkToolButton containing the image and text from a stock item. Some stock ids have preprocessor macros like #GTK_STOCK_OK and #GTK_STOCK_APPLY. It is an error if @stock_id is not a name of a stock item. Use gtk_tool_button_new() together with gtk_image_new_from_icon_name() instead. A new #GtkToolButton the name of the stock item Signal emitted when the tool button is clicked with the mouse or activated with the keyboard. Returns the name of the themed icon for the tool button, see gtk_tool_button_set_icon_name(). the icon name or %NULL if the tool button has no themed icon a #GtkToolButton Return the widget used as icon widget on @button. See gtk_tool_button_set_icon_widget(). The widget used as icon on @button, or %NULL. a #GtkToolButton Returns the label used by the tool button, or %NULL if the tool button doesn’t have a label. or uses a the label from a stock item. The returned string is owned by GTK+, and must not be modified or freed. The label, or %NULL a #GtkToolButton Returns the widget used as label on @button. See gtk_tool_button_set_label_widget(). The widget used as label on @button, or %NULL. a #GtkToolButton Returns the name of the stock item. See gtk_tool_button_set_stock_id(). The returned string is owned by GTK+ and must not be freed or modifed. Use gtk_tool_button_get_icon_name() instead. the name of the stock item for @button. a #GtkToolButton Returns whether underscores in the label property are used as mnemonics on menu items on the overflow menu. See gtk_tool_button_set_use_underline(). %TRUE if underscores in the label property are used as mnemonics on menu items on the overflow menu. a #GtkToolButton Sets the icon for the tool button from a named themed icon. See the docs for #GtkIconTheme for more details. The #GtkToolButton:icon-name property only has an effect if not overridden by non-%NULL #GtkToolButton:label-widget, #GtkToolButton:icon-widget and #GtkToolButton:stock-id properties. a #GtkToolButton the name of the themed icon Sets @icon as the widget used as icon on @button. If @icon_widget is %NULL the icon is determined by the #GtkToolButton:stock-id property. If the #GtkToolButton:stock-id property is also %NULL, @button will not have an icon. a #GtkToolButton the widget used as icon, or %NULL Sets @label as the label used for the tool button. The #GtkToolButton:label property only has an effect if not overridden by a non-%NULL #GtkToolButton:label-widget property. If both the #GtkToolButton:label-widget and #GtkToolButton:label properties are %NULL, the label is determined by the #GtkToolButton:stock-id property. If the #GtkToolButton:stock-id property is also %NULL, @button will not have a label. a #GtkToolButton a string that will be used as label, or %NULL. Sets @label_widget as the widget that will be used as the label for @button. If @label_widget is %NULL the #GtkToolButton:label property is used as label. If #GtkToolButton:label is also %NULL, the label in the stock item determined by the #GtkToolButton:stock-id property is used as label. If #GtkToolButton:stock-id is also %NULL, @button does not have a label. a #GtkToolButton the widget used as label, or %NULL Sets the name of the stock item. See gtk_tool_button_new_from_stock(). The stock_id property only has an effect if not overridden by non-%NULL #GtkToolButton:label-widget and #GtkToolButton:icon-widget properties. Use gtk_tool_button_set_icon_name() instead. a #GtkToolButton a name of a stock item, or %NULL If set, an underline in the label property indicates that the next character should be used for the mnemonic accelerator key in the overflow menu. For example, if the label property is “_Open” and @use_underline is %TRUE, the label on the tool button will be “Open” and the item on the overflow menu will have an underlined “O”. Labels shown on tool buttons never have mnemonics on them; this property only affects the menu item on the overflow menu. a #GtkToolButton whether the button label has the form “_Open” The name of the themed icon displayed on the item. This property only has an effect if not overridden by #GtkToolButton:label-widget, #GtkToolButton:icon-widget or #GtkToolButton:stock-id properties. Use #GtkToolButton:icon-name instead. This signal is emitted when the tool button is clicked with the mouse or activated with the keyboard. The parent class. Signal emitted when the tool button is clicked with the mouse or activated with the keyboard. #GtkToolItems are widgets that can appear on a toolbar. To create a toolbar item that contain something else than a button, use gtk_tool_item_new(). Use gtk_container_add() to add a child widget to the tool item. For toolbar items that contain buttons, see the #GtkToolButton, #GtkToggleToolButton and #GtkRadioToolButton classes. See the #GtkToolbar class for a description of the toolbar widget, and #GtkToolShell for a description of the tool shell interface. Creates a new #GtkToolItem the new #GtkToolItem Signal emitted when the toolbar needs information from tool_item about whether the item should appear in the toolbar overflow menu. Emits the signal #GtkToolItem::toolbar_reconfigured on @tool_item. #GtkToolbar and other #GtkToolShell implementations use this function to notify children, when some aspect of their configuration changes. a #GtkToolItem Returns the ellipsize mode used for @tool_item. Custom subclasses of #GtkToolItem should call this function to find out how text should be ellipsized. a #PangoEllipsizeMode indicating how text in @tool_item should be ellipsized. a #GtkToolItem Returns whether @tool_item is allocated extra space. See gtk_tool_item_set_expand(). %TRUE if @tool_item is allocated extra space. a #GtkToolItem Returns whether @tool_item is the same size as other homogeneous items. See gtk_tool_item_set_homogeneous(). %TRUE if the item is the same size as other homogeneous items. a #GtkToolItem Returns the icon size used for @tool_item. Custom subclasses of #GtkToolItem should call this function to find out what size icons they should use. a #GtkIconSize indicating the icon size used for @tool_item a #GtkToolItem Returns whether @tool_item is considered important. See gtk_tool_item_set_is_important() %TRUE if @tool_item is considered important. a #GtkToolItem Returns the orientation used for @tool_item. Custom subclasses of #GtkToolItem should call this function to find out what size icons they should use. a #GtkOrientation indicating the orientation used for @tool_item a #GtkToolItem If @menu_item_id matches the string passed to gtk_tool_item_set_proxy_menu_item() return the corresponding #GtkMenuItem. Custom subclasses of #GtkToolItem should use this function to update their menu item when the #GtkToolItem changes. That the @menu_item_ids must match ensures that a #GtkToolItem will not inadvertently change a menu item that they did not create. The #GtkMenuItem passed to gtk_tool_item_set_proxy_menu_item(), if the @menu_item_ids match. a #GtkToolItem a string used to identify the menu item Returns the relief style of @tool_item. See gtk_button_set_relief(). Custom subclasses of #GtkToolItem should call this function in the handler of the #GtkToolItem::toolbar_reconfigured signal to find out the relief style of buttons. a #GtkReliefStyle indicating the relief style used for @tool_item. a #GtkToolItem Returns the text alignment used for @tool_item. Custom subclasses of #GtkToolItem should call this function to find out how text should be aligned. a #gfloat indicating the horizontal text alignment used for @tool_item a #GtkToolItem: Returns the text orientation used for @tool_item. Custom subclasses of #GtkToolItem should call this function to find out how text should be orientated. a #GtkOrientation indicating the text orientation used for @tool_item a #GtkToolItem Returns the size group used for labels in @tool_item. Custom subclasses of #GtkToolItem should call this function and use the size group for labels. a #GtkSizeGroup a #GtkToolItem Returns the toolbar style used for @tool_item. Custom subclasses of #GtkToolItem should call this function in the handler of the GtkToolItem::toolbar_reconfigured signal to find out in what style the toolbar is displayed and change themselves accordingly Possibilities are: - %GTK_TOOLBAR_BOTH, meaning the tool item should show both an icon and a label, stacked vertically - %GTK_TOOLBAR_ICONS, meaning the toolbar shows only icons - %GTK_TOOLBAR_TEXT, meaning the tool item should only show text - %GTK_TOOLBAR_BOTH_HORIZ, meaning the tool item should show both an icon and a label, arranged horizontally A #GtkToolbarStyle indicating the toolbar style used for @tool_item. a #GtkToolItem Returns whether @tool_item has a drag window. See gtk_tool_item_set_use_drag_window(). %TRUE if @tool_item uses a drag window. a #GtkToolItem Returns whether the @tool_item is visible on toolbars that are docked horizontally. %TRUE if @tool_item is visible on toolbars that are docked horizontally. a #GtkToolItem Returns whether @tool_item is visible when the toolbar is docked vertically. See gtk_tool_item_set_visible_vertical(). Whether @tool_item is visible when the toolbar is docked vertically a #GtkToolItem Calling this function signals to the toolbar that the overflow menu item for @tool_item has changed. If the overflow menu is visible when this function it called, the menu will be rebuilt. The function must be called when the tool item changes what it will do in response to the #GtkToolItem::create-menu-proxy signal. a #GtkToolItem Returns the #GtkMenuItem that was last set by gtk_tool_item_set_proxy_menu_item(), ie. the #GtkMenuItem that is going to appear in the overflow menu. The #GtkMenuItem that is going to appear in the overflow menu for @tool_item. a #GtkToolItem Sets whether @tool_item is allocated extra space when there is more room on the toolbar then needed for the items. The effect is that the item gets bigger when the toolbar gets bigger and smaller when the toolbar gets smaller. a #GtkToolItem Whether @tool_item is allocated extra space Sets whether @tool_item is to be allocated the same size as other homogeneous items. The effect is that all homogeneous items will have the same width as the widest of the items. a #GtkToolItem whether @tool_item is the same size as other homogeneous items Sets whether @tool_item should be considered important. The #GtkToolButton class uses this property to determine whether to show or hide its label when the toolbar style is %GTK_TOOLBAR_BOTH_HORIZ. The result is that only tool buttons with the “is_important” property set have labels, an effect known as “priority text” a #GtkToolItem whether the tool item should be considered important Sets the #GtkMenuItem used in the toolbar overflow menu. The @menu_item_id is used to identify the caller of this function and should also be used with gtk_tool_item_get_proxy_menu_item(). See also #GtkToolItem::create-menu-proxy. a #GtkToolItem a string used to identify @menu_item a #GtkMenuItem to use in the overflow menu, or %NULL Sets the markup text to be displayed as tooltip on the item. See gtk_widget_set_tooltip_markup(). a #GtkToolItem markup text to be used as tooltip for @tool_item Sets the text to be displayed as tooltip on the item. See gtk_widget_set_tooltip_text(). a #GtkToolItem text to be used as tooltip for @tool_item Sets whether @tool_item has a drag window. When %TRUE the toolitem can be used as a drag source through gtk_drag_source_set(). When @tool_item has a drag window it will intercept all events, even those that would otherwise be sent to a child of @tool_item. a #GtkToolItem Whether @tool_item has a drag window. Sets whether @tool_item is visible when the toolbar is docked horizontally. a #GtkToolItem Whether @tool_item is visible when in horizontal mode Sets whether @tool_item is visible when the toolbar is docked vertically. Some tool items, such as text entries, are too wide to be useful on a vertically docked toolbar. If @visible_vertical is %FALSE @tool_item will not appear on toolbars that are docked vertically. a #GtkToolItem whether @tool_item is visible when the toolbar is in vertical mode Emits the signal #GtkToolItem::toolbar_reconfigured on @tool_item. #GtkToolbar and other #GtkToolShell implementations use this function to notify children, when some aspect of their configuration changes. a #GtkToolItem This signal is emitted when the toolbar needs information from @tool_item about whether the item should appear in the toolbar overflow menu. In response the tool item should either - call gtk_tool_item_set_proxy_menu_item() with a %NULL pointer and return %TRUE to indicate that the item should not appear in the overflow menu - call gtk_tool_item_set_proxy_menu_item() with a new menu item and return %TRUE, or - return %FALSE to indicate that the signal was not handled by the item. This means that the item will not appear in the overflow menu unless a later handler installs a menu item. The toolbar may cache the result of this signal. When the tool item changes how it will respond to this signal it must call gtk_tool_item_rebuild_menu() to invalidate the cache and ensure that the toolbar rebuilds its overflow menu. %TRUE if the signal was handled, %FALSE if not This signal is emitted when some property of the toolbar that the item is a child of changes. For custom subclasses of #GtkToolItem, the default handler of this signal use the functions - gtk_tool_shell_get_orientation() - gtk_tool_shell_get_style() - gtk_tool_shell_get_icon_size() - gtk_tool_shell_get_relief_style() to find out what the toolbar should look like and change themselves accordingly. The parent class. Signal emitted when the toolbar needs information from tool_item about whether the item should appear in the toolbar overflow menu. Signal emitted when some property of the toolbar that the item is a child of changes. a #GtkToolItem A #GtkToolItemGroup is used together with #GtkToolPalette to add #GtkToolItems to a palette like container with different categories and drag and drop support. # CSS nodes GtkToolItemGroup has a single CSS node named toolitemgroup. Creates a new tool item group with label @label. a new #GtkToolItemGroup. the label of the new group Gets whether @group is collapsed or expanded. %TRUE if @group is collapsed, %FALSE if it is expanded a GtkToolItemGroup Gets the tool item at position (x, y). the #GtkToolItem at position (x, y) a #GtkToolItemGroup the x position the y position Gets the ellipsization mode of @group. the #PangoEllipsizeMode of @group a #GtkToolItemGroup Gets the relief mode of the header button of @group. the #GtkReliefStyle a #GtkToolItemGroup Gets the position of @item in @group as index. the index of @item in @group or -1 if @item is no child of @group a #GtkToolItemGroup a #GtkToolItem Gets the label of @group. the label of @group. The label is an internal string of @group and must not be modified. Note that %NULL is returned if a custom label has been set with gtk_tool_item_group_set_label_widget() a #GtkToolItemGroup Gets the label widget of @group. See gtk_tool_item_group_set_label_widget(). the label widget of @group a #GtkToolItemGroup Gets the number of tool items in @group. the number of tool items in @group a #GtkToolItemGroup Gets the tool item at @index in group. the #GtkToolItem at index a #GtkToolItemGroup the index Inserts @item at @position in the list of children of @group. a #GtkToolItemGroup the #GtkToolItem to insert into @group the position of @item in @group, starting with 0. The position -1 means end of list. Sets whether the @group should be collapsed or expanded. a #GtkToolItemGroup whether the @group should be collapsed or expanded Sets the ellipsization mode which should be used by labels in @group. a #GtkToolItemGroup the #PangoEllipsizeMode labels in @group should use Set the button relief of the group header. See gtk_button_set_relief() for details. a #GtkToolItemGroup the #GtkReliefStyle Sets the position of @item in the list of children of @group. a #GtkToolItemGroup the #GtkToolItem to move to a new position, should be a child of @group. the new position of @item in @group, starting with 0. The position -1 means end of list. Sets the label of the tool item group. The label is displayed in the header of the group. a #GtkToolItemGroup the new human-readable label of of the group Sets the label of the tool item group. The label widget is displayed in the header of the group, in place of the usual label. a #GtkToolItemGroup the widget to be displayed in place of the usual label The parent class. A #GtkToolPalette allows you to add #GtkToolItems to a palette-like container with different categories and drag and drop support. A #GtkToolPalette is created with a call to gtk_tool_palette_new(). #GtkToolItems cannot be added directly to a #GtkToolPalette - instead they are added to a #GtkToolItemGroup which can than be added to a #GtkToolPalette. To add a #GtkToolItemGroup to a #GtkToolPalette, use gtk_container_add(). |[<!-- language="C" --> GtkWidget *palette, *group; GtkToolItem *item; palette = gtk_tool_palette_new (); group = gtk_tool_item_group_new (_("Test Category")); gtk_container_add (GTK_CONTAINER (palette), group); item = gtk_tool_button_new (NULL, _("_Open")); gtk_tool_button_set_icon_name (GTK_TOOL_BUTTON (item), "document-open"); gtk_tool_item_group_insert (GTK_TOOL_ITEM_GROUP (group), item, -1); ]| The easiest way to use drag and drop with #GtkToolPalette is to call gtk_tool_palette_add_drag_dest() with the desired drag source @palette and the desired drag target @widget. Then gtk_tool_palette_get_drag_item() can be used to get the dragged item in the #GtkWidget::drag-data-received signal handler of the drag target. |[<!-- language="C" --> static void passive_canvas_drag_data_received (GtkWidget *widget, GdkDragContext *context, gint x, gint y, GtkSelectionData *selection, guint info, guint time, gpointer data) { GtkWidget *palette; GtkWidget *item; // Get the dragged item palette = gtk_widget_get_ancestor (gtk_drag_get_source_widget (context), GTK_TYPE_TOOL_PALETTE); if (palette != NULL) item = gtk_tool_palette_get_drag_item (GTK_TOOL_PALETTE (palette), selection); // Do something with item } GtkWidget *target, palette; palette = gtk_tool_palette_new (); target = gtk_drawing_area_new (); g_signal_connect (G_OBJECT (target), "drag-data-received", G_CALLBACK (passive_canvas_drag_data_received), NULL); gtk_tool_palette_add_drag_dest (GTK_TOOL_PALETTE (palette), target, GTK_DEST_DEFAULT_ALL, GTK_TOOL_PALETTE_DRAG_ITEMS, GDK_ACTION_COPY); ]| # CSS nodes GtkToolPalette has a single CSS node named toolpalette. Creates a new tool palette. a new #GtkToolPalette Get the target entry for a dragged #GtkToolItemGroup. the #GtkTargetEntry for a dragged group Gets the target entry for a dragged #GtkToolItem. the #GtkTargetEntry for a dragged item. Sets @palette as drag source (see gtk_tool_palette_set_drag_source()) and sets @widget as a drag destination for drags from @palette. See gtk_drag_dest_set(). a #GtkToolPalette a #GtkWidget which should be a drag destination for @palette the flags that specify what actions GTK+ should take for drops on that widget the #GtkToolPaletteDragTargets which the widget should support the #GdkDragActions which the widget should suppport Get the dragged item from the selection. This could be a #GtkToolItem or a #GtkToolItemGroup. the dragged item in selection a #GtkToolPalette a #GtkSelectionData Gets the group at position (x, y). the #GtkToolItemGroup at position or %NULL if there is no such group a #GtkToolPalette the x position the y position Gets the item at position (x, y). See gtk_tool_palette_get_drop_group(). the #GtkToolItem at position or %NULL if there is no such item a #GtkToolPalette the x position the y position Gets whether @group is exclusive or not. See gtk_tool_palette_set_exclusive(). %TRUE if @group is exclusive a #GtkToolPalette a #GtkToolItemGroup which is a child of palette Gets whether group should be given extra space. See gtk_tool_palette_set_expand(). %TRUE if group should be given extra space, %FALSE otherwise a #GtkToolPalette a #GtkToolItemGroup which is a child of palette Gets the position of @group in @palette as index. See gtk_tool_palette_set_group_position(). the index of group or -1 if @group is not a child of @palette a #GtkToolPalette a #GtkToolItemGroup Gets the horizontal adjustment of the tool palette. Use gtk_scrollable_get_hadjustment() the horizontal adjustment of @palette a #GtkToolPalette Gets the size of icons in the tool palette. See gtk_tool_palette_set_icon_size(). the #GtkIconSize of icons in the tool palette a #GtkToolPalette Gets the style (icons, text or both) of items in the tool palette. the #GtkToolbarStyle of items in the tool palette. a #GtkToolPalette Gets the vertical adjustment of the tool palette. Use gtk_scrollable_get_vadjustment() the vertical adjustment of @palette a #GtkToolPalette Sets the tool palette as a drag source. Enables all groups and items in the tool palette as drag sources on button 1 and button 3 press with copy and move actions. See gtk_drag_source_set(). a #GtkToolPalette the #GtkToolPaletteDragTargets which the widget should support Sets whether the group should be exclusive or not. If an exclusive group is expanded all other groups are collapsed. a #GtkToolPalette a #GtkToolItemGroup which is a child of palette whether the group should be exclusive or not Sets whether the group should be given extra space. a #GtkToolPalette a #GtkToolItemGroup which is a child of palette whether the group should be given extra space Sets the position of the group as an index of the tool palette. If position is 0 the group will become the first child, if position is -1 it will become the last child. a #GtkToolPalette a #GtkToolItemGroup which is a child of palette a new index for group Sets the size of icons in the tool palette. a #GtkToolPalette the #GtkIconSize that icons in the tool palette shall have Sets the style (text, icons or both) of items in the tool palette. a #GtkToolPalette the #GtkToolbarStyle that items in the tool palette shall have Unsets the tool palette icon size set with gtk_tool_palette_set_icon_size(), so that user preferences will be used to determine the icon size. a #GtkToolPalette Unsets a toolbar style set with gtk_tool_palette_set_style(), so that user preferences will be used to determine the toolbar style. a #GtkToolPalette The size of the icons in a tool palette. When this property is set, it overrides the default setting. This should only be used for special-purpose tool palettes, normal application tool palettes should respect the user preferences for the size of icons. Is %TRUE if the #GtkToolPalette:icon-size property has been set. The style of items in the tool palette. The parent class. Flags used to specify the supported drag targets. Support drag of items. Support drag of groups. The #GtkToolShell interface allows container widgets to provide additional information when embedding #GtkToolItem widgets. Retrieves the current ellipsize mode for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_ellipsize_mode() instead. the current ellipsize mode of @shell a #GtkToolShell mandatory implementation of gtk_tool_shell_get_icon_size(). Retrieves the current orientation for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_orientation() instead. the current orientation of @shell a #GtkToolShell Returns the relief style of buttons on @shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_relief_style() instead. The relief style of buttons on @shell. a #GtkToolShell Retrieves whether the tool shell has text, icons, or both. Tool items must not call this function directly, but rely on gtk_tool_item_get_toolbar_style() instead. the current style of @shell a #GtkToolShell Retrieves the current text alignment for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_text_alignment() instead. the current text alignment of @shell a #GtkToolShell Retrieves the current text orientation for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_text_orientation() instead. the current text orientation of @shell a #GtkToolShell Retrieves the current text size group for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_text_size_group() instead. the current text size group of @shell a #GtkToolShell Calling this function signals the tool shell that the overflow menu item for tool items have changed. If there is an overflow menu and if it is visible when this function it called, the menu will be rebuilt. Tool items must not call this function directly, but rely on gtk_tool_item_rebuild_menu() instead. a #GtkToolShell Retrieves the current ellipsize mode for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_ellipsize_mode() instead. the current ellipsize mode of @shell a #GtkToolShell Retrieves the icon size for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_icon_size() instead. the current size (#GtkIconSize) for icons of @shell a #GtkToolShell Retrieves the current orientation for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_orientation() instead. the current orientation of @shell a #GtkToolShell Returns the relief style of buttons on @shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_relief_style() instead. The relief style of buttons on @shell. a #GtkToolShell Retrieves whether the tool shell has text, icons, or both. Tool items must not call this function directly, but rely on gtk_tool_item_get_toolbar_style() instead. the current style of @shell a #GtkToolShell Retrieves the current text alignment for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_text_alignment() instead. the current text alignment of @shell a #GtkToolShell Retrieves the current text orientation for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_text_orientation() instead. the current text orientation of @shell a #GtkToolShell Retrieves the current text size group for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_text_size_group() instead. the current text size group of @shell a #GtkToolShell Calling this function signals the tool shell that the overflow menu item for tool items have changed. If there is an overflow menu and if it is visible when this function it called, the menu will be rebuilt. Tool items must not call this function directly, but rely on gtk_tool_item_rebuild_menu() instead. a #GtkToolShell Virtual function table for the #GtkToolShell interface. mandatory implementation of gtk_tool_shell_get_icon_size(). mandatory implementation of gtk_tool_shell_get_orientation(). the current orientation of @shell a #GtkToolShell mandatory implementation of gtk_tool_shell_get_style(). the current style of @shell a #GtkToolShell optional implementation of gtk_tool_shell_get_relief_style(). The relief style of buttons on @shell. a #GtkToolShell optional implementation of gtk_tool_shell_rebuild_menu(). a #GtkToolShell optional implementation of gtk_tool_shell_get_text_orientation(). the current text orientation of @shell a #GtkToolShell optional implementation of gtk_tool_shell_get_text_alignment(). the current text alignment of @shell a #GtkToolShell optional implementation of gtk_tool_shell_get_ellipsize_mode(). the current ellipsize mode of @shell a #GtkToolShell optional implementation of gtk_tool_shell_get_text_size_group(). the current text size group of @shell a #GtkToolShell A toolbar is created with a call to gtk_toolbar_new(). A toolbar can contain instances of a subclass of #GtkToolItem. To add a #GtkToolItem to the a toolbar, use gtk_toolbar_insert(). To remove an item from the toolbar use gtk_container_remove(). To add a button to the toolbar, add an instance of #GtkToolButton. Toolbar items can be visually grouped by adding instances of #GtkSeparatorToolItem to the toolbar. If the GtkToolbar child property “expand” is #TRUE and the property #GtkSeparatorToolItem:draw is set to #FALSE, the effect is to force all following items to the end of the toolbar. By default, a toolbar can be shrunk, upon which it will add an arrow button to show an overflow menu offering access to any #GtkToolItem child that has a proxy menu item. To disable this and request enough size for all children, call gtk_toolbar_set_show_arrow() to set #GtkToolbar:show-arrow to %FALSE. Creating a context menu for the toolbar can be done by connecting to the #GtkToolbar::popup-context-menu signal. # CSS nodes GtkToolbar has a single CSS node with name toolbar. Creates a new toolbar. the newly-created toolbar. Returns the position corresponding to the indicated point on @toolbar. This is useful when dragging items to the toolbar: this function returns the position a new item should be inserted. @x and @y are in @toolbar coordinates. The position corresponding to the point (@x, @y) on the toolbar. a #GtkToolbar x coordinate of a point on the toolbar y coordinate of a point on the toolbar Retrieves the icon size for the toolbar. See gtk_toolbar_set_icon_size(). the current icon size for the icons on the toolbar. a #GtkToolbar Returns the position of @item on the toolbar, starting from 0. It is an error if @item is not a child of the toolbar. the position of item on the toolbar. a #GtkToolbar a #GtkToolItem that is a child of @toolbar Returns the number of items on the toolbar. the number of items on the toolbar a #GtkToolbar Returns the @n'th item on @toolbar, or %NULL if the toolbar does not contain an @n'th item. The @n'th #GtkToolItem on @toolbar, or %NULL if there isn’t an @n'th item. a #GtkToolbar A position on the toolbar Returns the relief style of buttons on @toolbar. See gtk_button_set_relief(). The relief style of buttons on @toolbar. a #GtkToolbar Returns whether the toolbar has an overflow menu. See gtk_toolbar_set_show_arrow(). %TRUE if the toolbar has an overflow menu. a #GtkToolbar Retrieves whether the toolbar has text, icons, or both . See gtk_toolbar_set_style(). the current style of @toolbar a #GtkToolbar Insert a #GtkToolItem into the toolbar at position @pos. If @pos is 0 the item is prepended to the start of the toolbar. If @pos is negative, the item is appended to the end of the toolbar. a #GtkToolbar a #GtkToolItem the position of the new item Highlights @toolbar to give an idea of what it would look like if @item was added to @toolbar at the position indicated by @index_. If @item is %NULL, highlighting is turned off. In that case @index_ is ignored. The @tool_item passed to this function must not be part of any widget hierarchy. When an item is set as drop highlight item it can not added to any widget hierarchy or used as highlight item for another toolbar. a #GtkToolbar a #GtkToolItem, or %NULL to turn of highlighting a position on @toolbar This function sets the size of stock icons in the toolbar. You can call it both before you add the icons and after they’ve been added. The size you set will override user preferences for the default icon size. This should only be used for special-purpose toolbars, normal application toolbars should respect the user preferences for the size of icons. A #GtkToolbar The #GtkIconSize that stock icons in the toolbar shall have. Sets whether to show an overflow menu when @toolbar isn’t allocated enough size to show all of its items. If %TRUE, items which can’t fit in @toolbar, and which have a proxy menu item set by gtk_tool_item_set_proxy_menu_item() or #GtkToolItem::create-menu-proxy, will be available in an overflow menu, which can be opened by an added arrow button. If %FALSE, @toolbar will request enough size to fit all of its child items without any overflow. a #GtkToolbar Whether to show an overflow menu Alters the view of @toolbar to display either icons only, text only, or both. a #GtkToolbar. the new style for @toolbar. Unsets toolbar icon size set with gtk_toolbar_set_icon_size(), so that user preferences will be used to determine the icon size. a #GtkToolbar Unsets a toolbar style set with gtk_toolbar_set_style(), so that user preferences will be used to determine the toolbar style. a #GtkToolbar The size of the icons in a toolbar is normally determined by the toolbar-icon-size setting. When this property is set, it overrides the setting. This should only be used for special-purpose toolbars, normal application toolbars should respect the user preferences for the size of icons. Is %TRUE if the icon-size property has been set. A keybinding signal used internally by GTK+. This signal can't be used in application code %TRUE if the signal was handled, %FALSE if not %TRUE if the first item should be focused Emitted when the orientation of the toolbar changes. the new #GtkOrientation of the toolbar Emitted when the user right-clicks the toolbar or uses the keybinding to display a popup menu. Application developers should handle this signal if they want to display a context menu on the toolbar. The context-menu should appear at the coordinates given by @x and @y. The mouse button number is given by the @button parameter. If the menu was popped up using the keybaord, @button is -1. return %TRUE if the signal was handled, %FALSE if not the x coordinate of the point where the menu should appear the y coordinate of the point where the menu should appear the mouse button the user pressed, or -1 Emitted when the style of the toolbar changes. the new #GtkToolbarStyle of the toolbar Whether spacers are vertical lines or just blank. Use blank spacers. Use vertical lines for spacers. Used to customize the appearance of a #GtkToolbar. Note that setting the toolbar style overrides the user’s preferences for the default toolbar style. Note that if the button has only a label set and GTK_TOOLBAR_ICONS is used, the label will be visible, and vice versa. Buttons display only icons in the toolbar. Buttons display only text labels in the toolbar. Buttons display text and icons in the toolbar. Buttons display icons and text alongside each other, rather than vertically stacked Basic tooltips can be realized simply by using gtk_widget_set_tooltip_text() or gtk_widget_set_tooltip_markup() without any explicit tooltip object. When you need a tooltip with a little more fancy contents, like adding an image, or you want the tooltip to have different contents per #GtkTreeView row or cell, you will have to do a little more work: - Set the #GtkWidget:has-tooltip property to %TRUE, this will make GTK+ monitor the widget for motion and related events which are needed to determine when and where to show a tooltip. - Connect to the #GtkWidget::query-tooltip signal. This signal will be emitted when a tooltip is supposed to be shown. One of the arguments passed to the signal handler is a GtkTooltip object. This is the object that we are about to display as a tooltip, and can be manipulated in your callback using functions like gtk_tooltip_set_icon(). There are functions for setting the tooltip’s markup, setting an image from a named icon, or even putting in a custom widget. Return %TRUE from your query-tooltip handler. This causes the tooltip to be show. If you return %FALSE, it will not be shown. In the probably rare case where you want to have even more control over the tooltip that is about to be shown, you can set your own #GtkWindow which will be used as tooltip window. This works as follows: - Set #GtkWidget:has-tooltip and connect to #GtkWidget::query-tooltip as before. Use gtk_widget_set_tooltip_window() to set a #GtkWindow created by you as tooltip window. - In the #GtkWidget::query-tooltip callback you can access your window using gtk_widget_get_tooltip_window() and manipulate as you wish. The semantics of the return value are exactly as before, return %TRUE to show the window, %FALSE to not show it. Triggers a new tooltip query on @display, in order to update the current visible tooltip, or to show/hide the current tooltip. This function is useful to call when, for example, the state of the widget changed by a key press. a #GdkDisplay Replaces the widget packed into the tooltip with @custom_widget. @custom_widget does not get destroyed when the tooltip goes away. By default a box with a #GtkImage and #GtkLabel is embedded in the tooltip, which can be configured using gtk_tooltip_set_markup() and gtk_tooltip_set_icon(). a #GtkTooltip a #GtkWidget, or %NULL to unset the old custom widget. Sets the icon of the tooltip (which is in front of the text) to be @pixbuf. If @pixbuf is %NULL, the image will be hidden. a #GtkTooltip a #GdkPixbuf, or %NULL Sets the icon of the tooltip (which is in front of the text) to be the icon indicated by @gicon with the size indicated by @size. If @gicon is %NULL, the image will be hidden. a #GtkTooltip a #GIcon representing the icon, or %NULL a stock icon size (#GtkIconSize) Sets the icon of the tooltip (which is in front of the text) to be the icon indicated by @icon_name with the size indicated by @size. If @icon_name is %NULL, the image will be hidden. a #GtkTooltip an icon name, or %NULL a stock icon size (#GtkIconSize) Sets the icon of the tooltip (which is in front of the text) to be the stock item indicated by @stock_id with the size indicated by @size. If @stock_id is %NULL, the image will be hidden. Use gtk_tooltip_set_icon_from_icon_name() instead. a #GtkTooltip a stock id, or %NULL a stock icon size (#GtkIconSize) Sets the text of the tooltip to be @markup, which is marked up with the [Pango text markup language][PangoMarkupFormat]. If @markup is %NULL, the label will be hidden. a #GtkTooltip a markup string (see [Pango markup format][PangoMarkupFormat]) or %NULL Sets the text of the tooltip to be @text. If @text is %NULL, the label will be hidden. See also gtk_tooltip_set_markup(). a #GtkTooltip a text string or %NULL Sets the area of the widget, where the contents of this tooltip apply, to be @rect (in widget coordinates). This is especially useful for properly setting tooltips on #GtkTreeView rows and cells, #GtkIconViews, etc. For setting tooltips on #GtkTreeView, please refer to the convenience functions for this: gtk_tree_view_set_tooltip_row() and gtk_tree_view_set_tooltip_cell(). a #GtkTooltip a #GdkRectangle List of children. The function used to translate messages in e.g. #GtkIconFactory and #GtkActionGroup. the translated message The id of the message. In #GtkActionGroup this will be a label or tooltip from a #GtkActionEntry. user data passed in when registering the function A function to set the properties of a cell instead of just using the straight mapping between the cell and the model. This is useful for customizing the cell renderer. For example, a function might get an integer from the @tree_model, and render it to the “text” attribute of “cell” by converting it to its written equivalent. This is set by calling gtk_tree_view_column_set_cell_data_func() A #GtkTreeViewColumn The #GtkCellRenderer that is being rendered by @tree_column The #GtkTreeModel being rendered A #GtkTreeIter of the current row rendered user data Asks the #GtkTreeDragDest to insert a row before the path @dest, deriving the contents of the row from @selection_data. If @dest is outside the tree so that inserting before it is impossible, %FALSE will be returned. Also, %FALSE may be returned if the new row is not created for some model-specific reason. Should robustly handle a @dest no longer found in the model! whether a new row was created before position @dest a #GtkTreeDragDest row to drop in front of data to drop Determines whether a drop is possible before the given @dest_path, at the same depth as @dest_path. i.e., can we drop the data in @selection_data at that location. @dest_path does not have to exist; the return value will almost certainly be %FALSE if the parent of @dest_path doesn’t exist, though. %TRUE if a drop is possible before @dest_path a #GtkTreeDragDest destination row the data being dragged Asks the #GtkTreeDragDest to insert a row before the path @dest, deriving the contents of the row from @selection_data. If @dest is outside the tree so that inserting before it is impossible, %FALSE will be returned. Also, %FALSE may be returned if the new row is not created for some model-specific reason. Should robustly handle a @dest no longer found in the model! whether a new row was created before position @dest a #GtkTreeDragDest row to drop in front of data to drop Determines whether a drop is possible before the given @dest_path, at the same depth as @dest_path. i.e., can we drop the data in @selection_data at that location. @dest_path does not have to exist; the return value will almost certainly be %FALSE if the parent of @dest_path doesn’t exist, though. %TRUE if a drop is possible before @dest_path a #GtkTreeDragDest destination row the data being dragged Asks the #GtkTreeDragDest to insert a row before the path dest, deriving the contents of the row from selection_data. whether a new row was created before position @dest a #GtkTreeDragDest row to drop in front of data to drop Determines whether a drop is possible before the given dest_path, at the same depth as dest_path. %TRUE if a drop is possible before @dest_path a #GtkTreeDragDest destination row the data being dragged Asks the #GtkTreeDragSource to delete the row at @path, because it was moved somewhere else via drag-and-drop. Returns %FALSE if the deletion fails because @path no longer exists, or for some model-specific reason. Should robustly handle a @path no longer found in the model! %TRUE if the row was successfully deleted a #GtkTreeDragSource row that was being dragged Asks the #GtkTreeDragSource to fill in @selection_data with a representation of the row at @path. @selection_data->target gives the required type of the data. Should robustly handle a @path no longer found in the model! %TRUE if data of the required type was provided a #GtkTreeDragSource row that was dragged a #GtkSelectionData to fill with data from the dragged row Asks the #GtkTreeDragSource whether a particular row can be used as the source of a DND operation. If the source doesn’t implement this interface, the row is assumed draggable. %TRUE if the row can be dragged a #GtkTreeDragSource row on which user is initiating a drag Asks the #GtkTreeDragSource to delete the row at @path, because it was moved somewhere else via drag-and-drop. Returns %FALSE if the deletion fails because @path no longer exists, or for some model-specific reason. Should robustly handle a @path no longer found in the model! %TRUE if the row was successfully deleted a #GtkTreeDragSource row that was being dragged Asks the #GtkTreeDragSource to fill in @selection_data with a representation of the row at @path. @selection_data->target gives the required type of the data. Should robustly handle a @path no longer found in the model! %TRUE if data of the required type was provided a #GtkTreeDragSource row that was dragged a #GtkSelectionData to fill with data from the dragged row Asks the #GtkTreeDragSource whether a particular row can be used as the source of a DND operation. If the source doesn’t implement this interface, the row is assumed draggable. %TRUE if the row can be dragged a #GtkTreeDragSource row on which user is initiating a drag Asks the #GtkTreeDragSource whether a particular row can be used as the source of a DND operation. %TRUE if the row can be dragged a #GtkTreeDragSource row on which user is initiating a drag Asks the #GtkTreeDragSource to fill in selection_data with a representation of the row at path. %TRUE if data of the required type was provided a #GtkTreeDragSource row that was dragged a #GtkSelectionData to fill with data from the dragged row Asks the #GtkTreeDragSource to delete the row at path, because it was moved somewhere else via drag-and-drop. %TRUE if the row was successfully deleted a #GtkTreeDragSource row that was being dragged The #GtkTreeIter is the primary structure for accessing a #GtkTreeModel. Models are expected to put a unique integer in the @stamp member, and put model-specific data in the three @user_data members. a unique stamp to catch invalid iterators model-specific data model-specific data model-specific data Creates a dynamically allocated tree iterator as a copy of @iter. This function is not intended for use in applications, because you can just copy the structs by value (`GtkTreeIter new_iter = iter;`). You must free this iter with gtk_tree_iter_free(). a newly-allocated copy of @iter a #GtkTreeIter-struct Frees an iterator that has been allocated by gtk_tree_iter_copy(). This function is mainly used for language bindings. a dynamically allocated tree iterator A GtkTreeIterCompareFunc should return a negative integer, zero, or a positive integer if @a sorts before @b, @a sorts with @b, or @a sorts after @b respectively. If two iters compare as equal, their order in the sorted model is undefined. In order to ensure that the #GtkTreeSortable behaves as expected, the GtkTreeIterCompareFunc must define a partial order on the model, i.e. it must be reflexive, antisymmetric and transitive. For example, if @model is a product catalogue, then a compare function for the “price” column could be one which returns `price_of(@a) - price_of(@b)`. a negative integer, zero or a positive integer depending on whether @a sorts before, with or after @b The #GtkTreeModel the comparison is within A #GtkTreeIter in @model Another #GtkTreeIter in @model Data passed when the compare func is assigned e.g. by gtk_tree_sortable_set_sort_func() The #GtkTreeModel interface defines a generic tree interface for use by the #GtkTreeView widget. It is an abstract interface, and is designed to be usable with any appropriate data structure. The programmer just has to implement this interface on their own data type for it to be viewable by a #GtkTreeView widget. The model is represented as a hierarchical tree of strongly-typed, columned data. In other words, the model can be seen as a tree where every node has different values depending on which column is being queried. The type of data found in a column is determined by using the GType system (ie. #G_TYPE_INT, #GTK_TYPE_BUTTON, #G_TYPE_POINTER, etc). The types are homogeneous per column across all nodes. It is important to note that this interface only provides a way of examining a model and observing changes. The implementation of each individual model decides how and if changes are made. In order to make life simpler for programmers who do not need to write their own specialized model, two generic models are provided — the #GtkTreeStore and the #GtkListStore. To use these, the developer simply pushes data into these models as necessary. These models provide the data structure as well as all appropriate tree interfaces. As a result, implementing drag and drop, sorting, and storing data is trivial. For the vast majority of trees and lists, these two models are sufficient. Models are accessed on a node/column level of granularity. One can query for the value of a model at a certain node and a certain column on that node. There are two structures used to reference a particular node in a model. They are the #GtkTreePath-struct and the #GtkTreeIter-struct (“iter” is short for iterator). Most of the interface consists of operations on a #GtkTreeIter-struct. A path is essentially a potential node. It is a location on a model that may or may not actually correspond to a node on a specific model. The #GtkTreePath-struct can be converted into either an array of unsigned integers or a string. The string form is a list of numbers separated by a colon. Each number refers to the offset at that level. Thus, the path `0` refers to the root node and the path `2:4` refers to the fifth child of the third node. By contrast, a #GtkTreeIter-struct is a reference to a specific node on a specific model. It is a generic struct with an integer and three generic pointers. These are filled in by the model in a model-specific way. One can convert a path to an iterator by calling gtk_tree_model_get_iter(). These iterators are the primary way of accessing a model and are similar to the iterators used by #GtkTextBuffer. They are generally statically allocated on the stack and only used for a short time. The model interface defines a set of operations using them for navigating the model. It is expected that models fill in the iterator with private data. For example, the #GtkListStore model, which is internally a simple linked list, stores a list node in one of the pointers. The #GtkTreeModelSort stores an array and an offset in two of the pointers. Additionally, there is an integer field. This field is generally filled with a unique stamp per model. This stamp is for catching errors resulting from using invalid iterators with a model. The lifecycle of an iterator can be a little confusing at first. Iterators are expected to always be valid for as long as the model is unchanged (and doesn’t emit a signal). The model is considered to own all outstanding iterators and nothing needs to be done to free them from the user’s point of view. Additionally, some models guarantee that an iterator is valid for as long as the node it refers to is valid (most notably the #GtkTreeStore and #GtkListStore). Although generally uninteresting, as one always has to allow for the case where iterators do not persist beyond a signal, some very important performance enhancements were made in the sort model. As a result, the #GTK_TREE_MODEL_ITERS_PERSIST flag was added to indicate this behavior. To help show some common operation of a model, some examples are provided. The first example shows three ways of getting the iter at the location `3:2:5`. While the first method shown is easier, the second is much more common, as you often get paths from callbacks. ## Acquiring a #GtkTreeIter-struct |[<!-- language="C" --> // Three ways of getting the iter pointing to the location GtkTreePath *path; GtkTreeIter iter; GtkTreeIter parent_iter; // get the iterator from a string gtk_tree_model_get_iter_from_string (model, &iter, "3:2:5"); // get the iterator from a path path = gtk_tree_path_new_from_string ("3:2:5"); gtk_tree_model_get_iter (model, &iter, path); gtk_tree_path_free (path); // walk the tree to find the iterator gtk_tree_model_iter_nth_child (model, &iter, NULL, 3); parent_iter = iter; gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 2); parent_iter = iter; gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 5); ]| This second example shows a quick way of iterating through a list and getting a string and an integer from each row. The populate_model() function used below is not shown, as it is specific to the #GtkListStore. For information on how to write such a function, see the #GtkListStore documentation. ## Reading data from a #GtkTreeModel |[<!-- language="C" --> enum { STRING_COLUMN, INT_COLUMN, N_COLUMNS }; ... GtkTreeModel *list_store; GtkTreeIter iter; gboolean valid; gint row_count = 0; // make a new list_store list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT); // Fill the list store with data populate_model (list_store); // Get the first iter in the list, check it is valid and walk // through the list, reading each row. valid = gtk_tree_model_get_iter_first (list_store, &iter); while (valid) { gchar *str_data; gint int_data; // Make sure you terminate calls to gtk_tree_model_get() with a “-1” value gtk_tree_model_get (list_store, &iter, STRING_COLUMN, &str_data, INT_COLUMN, &int_data, -1); // Do something with the data g_print ("Row %d: (%s,%d)\n", row_count, str_data, int_data); g_free (str_data); valid = gtk_tree_model_iter_next (list_store, &iter); row_count++; } ]| The #GtkTreeModel interface contains two methods for reference counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node(). These two methods are optional to implement. The reference counting is meant as a way for views to let models know when nodes are being displayed. #GtkTreeView will take a reference on a node when it is visible, which means the node is either in the toplevel or expanded. Being displayed does not mean that the node is currently directly visible to the user in the viewport. Based on this reference counting scheme a caching model, for example, can decide whether or not to cache a node based on the reference count. A file-system based model would not want to keep the entire file hierarchy in memory, but just the folders that are currently expanded in every current view. When working with reference counting, the following rules must be taken into account: - Never take a reference on a node without owning a reference on its parent. This means that all parent nodes of a referenced node must be referenced as well. - Outstanding references on a deleted node are not released. This is not possible because the node has already been deleted by the time the row-deleted signal is received. - Models are not obligated to emit a signal on rows of which none of its siblings are referenced. To phrase this differently, signals are only required for levels in which nodes are referenced. For the root level however, signals must be emitted at all times (however the root level is always referenced when any view is attached). Returns the type of the column. the type of the column a #GtkTreeModel the column index Returns a set of flags supported by this interface. The flags are a bitwise combination of #GtkTreeModelFlags. The flags supported should not change during the lifetime of the @tree_model. the flags supported by this interface a #GtkTreeModel Sets @iter to a valid iterator pointing to @path. If @path does not exist, @iter is set to an invalid iterator and %FALSE is returned. %TRUE, if @iter was set a #GtkTreeModel the uninitialized #GtkTreeIter-struct the #GtkTreePath-struct Returns the number of columns supported by @tree_model. the number of columns a #GtkTreeModel Returns a newly-created #GtkTreePath-struct referenced by @iter. This path should be freed with gtk_tree_path_free(). a newly-created #GtkTreePath-struct a #GtkTreeModel the #GtkTreeIter-struct Initializes and sets @value to that at @column. When done with @value, g_value_unset() needs to be called to free any allocated memory. a #GtkTreeModel the #GtkTreeIter-struct the column to lookup the value at an empty #GValue to set Sets @iter to point to the first child of @parent. If @parent has no children, %FALSE is returned and @iter is set to be invalid. @parent will remain a valid node after this function has been called. If @parent is %NULL returns the first node, equivalent to `gtk_tree_model_get_iter_first (tree_model, iter);` %TRUE, if @iter has been set to the first child a #GtkTreeModel the new #GtkTreeIter-struct to be set to the child the #GtkTreeIter-struct, or %NULL Returns %TRUE if @iter has children, %FALSE otherwise. %TRUE if @iter has children a #GtkTreeModel the #GtkTreeIter-struct to test for children Returns the number of children that @iter has. As a special case, if @iter is %NULL, then the number of toplevel nodes is returned. the number of children of @iter a #GtkTreeModel the #GtkTreeIter-struct, or %NULL Sets @iter to point to the node following it at the current level. If there is no next @iter, %FALSE is returned and @iter is set to be invalid. %TRUE if @iter has been changed to the next node a #GtkTreeModel the #GtkTreeIter-struct Sets @iter to be the child of @parent, using the given index. The first index is 0. If @n is too big, or @parent has no children, @iter is set to an invalid iterator and %FALSE is returned. @parent will remain a valid node after this function has been called. As a special case, if @parent is %NULL, then the @n-th root node is set. %TRUE, if @parent has an @n-th child a #GtkTreeModel the #GtkTreeIter-struct to set to the nth child the #GtkTreeIter-struct to get the child from, or %NULL. the index of the desired child Sets @iter to be the parent of @child. If @child is at the toplevel, and doesn’t have a parent, then @iter is set to an invalid iterator and %FALSE is returned. @child will remain a valid node after this function has been called. @iter will be initialized before the lookup is performed, so @child and @iter cannot point to the same memory location. %TRUE, if @iter is set to the parent of @child a #GtkTreeModel the new #GtkTreeIter-struct to set to the parent the #GtkTreeIter-struct Sets @iter to point to the previous node at the current level. If there is no previous @iter, %FALSE is returned and @iter is set to be invalid. %TRUE if @iter has been changed to the previous node a #GtkTreeModel the #GtkTreeIter-struct Lets the tree ref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. This function is primarily meant as a way for views to let caching models know when nodes are being displayed (and hence, whether or not to cache that node). Being displayed means a node is in an expanded branch, regardless of whether the node is currently visible in the viewport. For example, a file-system based model would not want to keep the entire file-hierarchy in memory, just the sections that are currently being displayed by every current view. A model should be expected to be able to get an iter independent of its reffed state. a #GtkTreeModel the #GtkTreeIter-struct Emits the #GtkTreeModel::row-changed signal on @tree_model. a #GtkTreeModel a #GtkTreePath-struct pointing to the changed row a valid #GtkTreeIter-struct pointing to the changed row Emits the #GtkTreeModel::row-deleted signal on @tree_model. This should be called by models after a row has been removed. The location pointed to by @path should be the location that the row previously was at. It may not be a valid location anymore. Nodes that are deleted are not unreffed, this means that any outstanding references on the deleted node should not be released. a #GtkTreeModel a #GtkTreePath-struct pointing to the previous location of the deleted row Emits the #GtkTreeModel::row-has-child-toggled signal on @tree_model. This should be called by models after the child state of a node changes. a #GtkTreeModel a #GtkTreePath-struct pointing to the changed row a valid #GtkTreeIter-struct pointing to the changed row Emits the #GtkTreeModel::row-inserted signal on @tree_model. a #GtkTreeModel a #GtkTreePath-struct pointing to the inserted row a valid #GtkTreeIter-struct pointing to the inserted row Emits the #GtkTreeModel::rows-reordered signal on @tree_model. This should be called by models when their rows have been reordered. a #GtkTreeModel a #GtkTreePath-struct pointing to the tree node whose children have been reordered a valid #GtkTreeIter-struct pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` Lets the tree unref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. For more information on what this means, see gtk_tree_model_ref_node(). Please note that nodes that are deleted are not unreffed. a #GtkTreeModel the #GtkTreeIter-struct Creates a new #GtkTreeModel, with @child_model as the child_model and @root as the virtual root. A new #GtkTreeModel. A #GtkTreeModel. A #GtkTreePath or %NULL. Calls func on each node in model in a depth-first fashion. If @func returns %TRUE, then the tree ceases to be walked, and gtk_tree_model_foreach() returns. a #GtkTreeModel a function to be called on each row user data to passed to @func Gets the value of one or more cells in the row referenced by @iter. The variable argument list should contain integer column numbers, each column number followed by a place to store the value being retrieved. The list is terminated by a -1. For example, to get a value from column 0 with type %G_TYPE_STRING, you would write: `gtk_tree_model_get (model, iter, 0, &place_string_here, -1)`, where `place_string_here` is a #gchararray to be filled with the string. Returned values with type %G_TYPE_OBJECT have to be unreferenced, values with type %G_TYPE_STRING or %G_TYPE_BOXED have to be freed. Other values are passed by value. a #GtkTreeModel a row in @tree_model pairs of column number and value return locations, terminated by -1 Returns the type of the column. the type of the column a #GtkTreeModel the column index Returns a set of flags supported by this interface. The flags are a bitwise combination of #GtkTreeModelFlags. The flags supported should not change during the lifetime of the @tree_model. the flags supported by this interface a #GtkTreeModel Sets @iter to a valid iterator pointing to @path. If @path does not exist, @iter is set to an invalid iterator and %FALSE is returned. %TRUE, if @iter was set a #GtkTreeModel the uninitialized #GtkTreeIter-struct the #GtkTreePath-struct Initializes @iter with the first iterator in the tree (the one at the path "0") and returns %TRUE. Returns %FALSE if the tree is empty. %TRUE, if @iter was set a #GtkTreeModel the uninitialized #GtkTreeIter-struct Sets @iter to a valid iterator pointing to @path_string, if it exists. Otherwise, @iter is left invalid and %FALSE is returned. %TRUE, if @iter was set a #GtkTreeModel an uninitialized #GtkTreeIter-struct a string representation of a #GtkTreePath-struct Returns the number of columns supported by @tree_model. the number of columns a #GtkTreeModel Returns a newly-created #GtkTreePath-struct referenced by @iter. This path should be freed with gtk_tree_path_free(). a newly-created #GtkTreePath-struct a #GtkTreeModel the #GtkTreeIter-struct Generates a string representation of the iter. This string is a “:” separated list of numbers. For example, “4:10:0:3” would be an acceptable return value for this string. a newly-allocated string. Must be freed with g_free(). a #GtkTreeModel a #GtkTreeIter-struct See gtk_tree_model_get(), this version takes a va_list for language bindings to use. a #GtkTreeModel a row in @tree_model va_list of column/return location pairs Initializes and sets @value to that at @column. When done with @value, g_value_unset() needs to be called to free any allocated memory. a #GtkTreeModel the #GtkTreeIter-struct the column to lookup the value at an empty #GValue to set Sets @iter to point to the first child of @parent. If @parent has no children, %FALSE is returned and @iter is set to be invalid. @parent will remain a valid node after this function has been called. If @parent is %NULL returns the first node, equivalent to `gtk_tree_model_get_iter_first (tree_model, iter);` %TRUE, if @iter has been set to the first child a #GtkTreeModel the new #GtkTreeIter-struct to be set to the child the #GtkTreeIter-struct, or %NULL Returns %TRUE if @iter has children, %FALSE otherwise. %TRUE if @iter has children a #GtkTreeModel the #GtkTreeIter-struct to test for children Returns the number of children that @iter has. As a special case, if @iter is %NULL, then the number of toplevel nodes is returned. the number of children of @iter a #GtkTreeModel the #GtkTreeIter-struct, or %NULL Sets @iter to point to the node following it at the current level. If there is no next @iter, %FALSE is returned and @iter is set to be invalid. %TRUE if @iter has been changed to the next node a #GtkTreeModel the #GtkTreeIter-struct Sets @iter to be the child of @parent, using the given index. The first index is 0. If @n is too big, or @parent has no children, @iter is set to an invalid iterator and %FALSE is returned. @parent will remain a valid node after this function has been called. As a special case, if @parent is %NULL, then the @n-th root node is set. %TRUE, if @parent has an @n-th child a #GtkTreeModel the #GtkTreeIter-struct to set to the nth child the #GtkTreeIter-struct to get the child from, or %NULL. the index of the desired child Sets @iter to be the parent of @child. If @child is at the toplevel, and doesn’t have a parent, then @iter is set to an invalid iterator and %FALSE is returned. @child will remain a valid node after this function has been called. @iter will be initialized before the lookup is performed, so @child and @iter cannot point to the same memory location. %TRUE, if @iter is set to the parent of @child a #GtkTreeModel the new #GtkTreeIter-struct to set to the parent the #GtkTreeIter-struct Sets @iter to point to the previous node at the current level. If there is no previous @iter, %FALSE is returned and @iter is set to be invalid. %TRUE if @iter has been changed to the previous node a #GtkTreeModel the #GtkTreeIter-struct Lets the tree ref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. This function is primarily meant as a way for views to let caching models know when nodes are being displayed (and hence, whether or not to cache that node). Being displayed means a node is in an expanded branch, regardless of whether the node is currently visible in the viewport. For example, a file-system based model would not want to keep the entire file-hierarchy in memory, just the sections that are currently being displayed by every current view. A model should be expected to be able to get an iter independent of its reffed state. a #GtkTreeModel the #GtkTreeIter-struct Emits the #GtkTreeModel::row-changed signal on @tree_model. a #GtkTreeModel a #GtkTreePath-struct pointing to the changed row a valid #GtkTreeIter-struct pointing to the changed row Emits the #GtkTreeModel::row-deleted signal on @tree_model. This should be called by models after a row has been removed. The location pointed to by @path should be the location that the row previously was at. It may not be a valid location anymore. Nodes that are deleted are not unreffed, this means that any outstanding references on the deleted node should not be released. a #GtkTreeModel a #GtkTreePath-struct pointing to the previous location of the deleted row Emits the #GtkTreeModel::row-has-child-toggled signal on @tree_model. This should be called by models after the child state of a node changes. a #GtkTreeModel a #GtkTreePath-struct pointing to the changed row a valid #GtkTreeIter-struct pointing to the changed row Emits the #GtkTreeModel::row-inserted signal on @tree_model. a #GtkTreeModel a #GtkTreePath-struct pointing to the inserted row a valid #GtkTreeIter-struct pointing to the inserted row Emits the #GtkTreeModel::rows-reordered signal on @tree_model. This should be called by models when their rows have been reordered. a #GtkTreeModel a #GtkTreePath-struct pointing to the tree node whose children have been reordered a valid #GtkTreeIter-struct pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` Emits the #GtkTreeModel::rows-reordered signal on @tree_model. This should be called by models when their rows have been reordered. a #GtkTreeModel a #GtkTreePath-struct pointing to the tree node whose children have been reordered a valid #GtkTreeIter-struct pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` length of @new_order array Lets the tree unref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. For more information on what this means, see gtk_tree_model_ref_node(). Please note that nodes that are deleted are not unreffed. a #GtkTreeModel the #GtkTreeIter-struct This signal is emitted when a row in the model has changed. a #GtkTreePath-struct identifying the changed row a valid #GtkTreeIter-struct pointing to the changed row This signal is emitted when a row has been deleted. Note that no iterator is passed to the signal handler, since the row is already deleted. This should be called by models after a row has been removed. The location pointed to by @path should be the location that the row previously was at. It may not be a valid location anymore. a #GtkTreePath-struct identifying the row This signal is emitted when a row has gotten the first child row or lost its last child row. a #GtkTreePath-struct identifying the row a valid #GtkTreeIter-struct pointing to the row This signal is emitted when a new row has been inserted in the model. Note that the row may still be empty at this point, since it is a common pattern to first insert an empty row, and then fill it with the desired values. a #GtkTreePath-struct identifying the new row a valid #GtkTreeIter-struct pointing to the new row This signal is emitted when the children of a node in the #GtkTreeModel have been reordered. Note that this signal is not emitted when rows are reordered by DND, since this is implemented by removing and then reinserting the row. a #GtkTreePath-struct identifying the tree node whose children have been reordered a valid #GtkTreeIter-struct pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` A #GtkTreeModelFilter is a tree model which wraps another tree model, and can do the following things: - Filter specific rows, based on data from a “visible column”, a column storing booleans indicating whether the row should be filtered or not, or based on the return value of a “visible function”, which gets a model, iter and user_data and returns a boolean indicating whether the row should be filtered or not. - Modify the “appearance” of the model, using a modify function. This is extremely powerful and allows for just changing some values and also for creating a completely different model based on the given child model. - Set a different root node, also known as a “virtual root”. You can pass in a #GtkTreePath indicating the root node for the filter at construction time. The basic API is similar to #GtkTreeModelSort. For an example on its usage, see the section on #GtkTreeModelSort. When using #GtkTreeModelFilter, it is important to realize that #GtkTreeModelFilter maintains an internal cache of all nodes which are visible in its clients. The cache is likely to be a subtree of the tree exposed by the child model. #GtkTreeModelFilter will not cache the entire child model when unnecessary to not compromise the caching mechanism that is exposed by the reference counting scheme. If the child model implements reference counting, unnecessary signals may not be emitted because of reference counting rule 3, see the #GtkTreeModel documentation. (Note that e.g. #GtkTreeStore does not implement reference counting and will always emit all signals, even when the receiving node is not visible). Because of this, limitations for possible visible functions do apply. In general, visible functions should only use data or properties from the node for which the visibility state must be determined, its siblings or its parents. Usually, having a dependency on the state of any child node is not possible, unless references are taken on these explicitly. When no such reference exists, no signals may be received for these child nodes (see reference couting rule number 3 in the #GtkTreeModel section). Determining the visibility state of a given node based on the state of its child nodes is a frequently occurring use case. Therefore, #GtkTreeModelFilter explicitly supports this. For example, when a node does not have any children, you might not want the node to be visible. As soon as the first row is added to the node’s child level (or the last row removed), the node’s visibility should be updated. This introduces a dependency from the node on its child nodes. In order to accommodate this, #GtkTreeModelFilter must make sure the necessary signals are received from the child model. This is achieved by building, for all nodes which are exposed as visible nodes to #GtkTreeModelFilter's clients, the child level (if any) and take a reference on the first node in this level. Furthermore, for every row-inserted, row-changed or row-deleted signal (also these which were not handled because the node was not cached), #GtkTreeModelFilter will check if the visibility state of any parent node has changed. Beware, however, that this explicit support is limited to these two cases. For example, if you want a node to be visible only if two nodes in a child’s child level (2 levels deeper) are visible, you are on your own. In this case, either rely on #GtkTreeStore to emit all signals because it does not implement reference counting, or for models that do implement reference counting, obtain references on these child levels yourself. This function should almost never be called. It clears the @filter of any cached iterators that haven’t been reffed with gtk_tree_model_ref_node(). This might be useful if the child model being filtered is static (and doesn’t change often) and there has been a lot of unreffed access to nodes. As a side effect of this function, all unreffed iters will be invalid. A #GtkTreeModelFilter. Sets @filter_iter to point to the row in @filter that corresponds to the row pointed at by @child_iter. If @filter_iter was not set, %FALSE is returned. %TRUE, if @filter_iter was set, i.e. if @child_iter is a valid iterator pointing to a visible row in child model. A #GtkTreeModelFilter. An uninitialized #GtkTreeIter. A valid #GtkTreeIter pointing to a row on the child model. Converts @child_path to a path relative to @filter. That is, @child_path points to a path in the child model. The rerturned path will point to the same row in the filtered model. If @child_path isn’t a valid path on the child model or points to a row which is not visible in @filter, then %NULL is returned. A newly allocated #GtkTreePath, or %NULL. A #GtkTreeModelFilter. A #GtkTreePath to convert. Sets @child_iter to point to the row pointed to by @filter_iter. A #GtkTreeModelFilter. An uninitialized #GtkTreeIter. A valid #GtkTreeIter pointing to a row on @filter. Converts @filter_path to a path on the child model of @filter. That is, @filter_path points to a location in @filter. The returned path will point to the same location in the model not being filtered. If @filter_path does not point to a location in the child model, %NULL is returned. A newly allocated #GtkTreePath, or %NULL. A #GtkTreeModelFilter. A #GtkTreePath to convert. Returns a pointer to the child model of @filter. A pointer to a #GtkTreeModel. A #GtkTreeModelFilter. Emits ::row_changed for each row in the child model, which causes the filter to re-evaluate whether a row is visible or not. A #GtkTreeModelFilter. With the @n_columns and @types parameters, you give an array of column types for this model (which will be exposed to the parent model/view). The @func, @data and @destroy parameters are for specifying the modify function. The modify function will get called for each data access, the goal of the modify function is to return the data which should be displayed at the location specified using the parameters of the modify function. Note that gtk_tree_model_filter_set_modify_func() can only be called once for a given filter model. A #GtkTreeModelFilter. The number of columns in the filter model. The #GTypes of the columns. A #GtkTreeModelFilterModifyFunc User data to pass to the modify function, or %NULL. Destroy notifier of @data, or %NULL. Sets @column of the child_model to be the column where @filter should look for visibility information. @columns should be a column of type %G_TYPE_BOOLEAN, where %TRUE means that a row is visible, and %FALSE if not. Note that gtk_tree_model_filter_set_visible_func() or gtk_tree_model_filter_set_visible_column() can only be called once for a given filter model. A #GtkTreeModelFilter A #gint which is the column containing the visible information Sets the visible function used when filtering the @filter to be @func. The function should return %TRUE if the given row should be visible and %FALSE otherwise. If the condition calculated by the function changes over time (e.g. because it depends on some global parameters), you must call gtk_tree_model_filter_refilter() to keep the visibility information of the model up-to-date. Note that @func is called whenever a row is inserted, when it may still be empty. The visible function should therefore take special care of empty rows, like in the example below. |[<!-- language="C" --> static gboolean visible_func (GtkTreeModel *model, GtkTreeIter *iter, gpointer data) { // Visible if row is non-empty and first column is “HI” gchar *str; gboolean visible = FALSE; gtk_tree_model_get (model, iter, 0, &str, -1); if (str && strcmp (str, "HI") == 0) visible = TRUE; g_free (str); return visible; } ]| Note that gtk_tree_model_filter_set_visible_func() or gtk_tree_model_filter_set_visible_column() can only be called once for a given filter model. A #GtkTreeModelFilter A #GtkTreeModelFilterVisibleFunc, the visible function User data to pass to the visible function, or %NULL Destroy notifier of @data, or %NULL A function which calculates display values from raw values in the model. It must fill @value with the display value for the column @column in the row indicated by @iter. Since this function is called for each data access, it’s not a particularly efficient operation. the #GtkTreeModelFilter a #GtkTreeIter pointing to the row whose display values are determined A #GValue which is already initialized for with the correct type for the column @column. the column whose display value is determined user data given to gtk_tree_model_filter_set_modify_func() A function which decides whether the row indicated by @iter is visible. Whether the row indicated by @iter is visible. the child model of the #GtkTreeModelFilter a #GtkTreeIter pointing to the row in @model whose visibility is determined user data given to gtk_tree_model_filter_set_visible_func() These flags indicate various properties of a #GtkTreeModel. They are returned by gtk_tree_model_get_flags(), and must be static for the lifetime of the object. A more complete description of #GTK_TREE_MODEL_ITERS_PERSIST can be found in the overview of this section. iterators survive all signals emitted by the tree the model is a list only, and never has children Type of the callback passed to gtk_tree_model_foreach() to iterate over the rows in a tree model. %TRUE to stop iterating, %FALSE to continue the #GtkTreeModel being iterated the current #GtkTreePath the current #GtkTreeIter The user data passed to gtk_tree_model_foreach() Signal emitted when a row in the model has changed. a #GtkTreeModel a #GtkTreePath-struct pointing to the changed row a valid #GtkTreeIter-struct pointing to the changed row Signal emitted when a new row has been inserted in the model. a #GtkTreeModel a #GtkTreePath-struct pointing to the inserted row a valid #GtkTreeIter-struct pointing to the inserted row Signal emitted when a row has gotten the first child row or lost its last child row. a #GtkTreeModel a #GtkTreePath-struct pointing to the changed row a valid #GtkTreeIter-struct pointing to the changed row Signal emitted when a row has been deleted. a #GtkTreeModel a #GtkTreePath-struct pointing to the previous location of the deleted row Signal emitted when the children of a node in the GtkTreeModel have been reordered. a #GtkTreeModel a #GtkTreePath-struct pointing to the tree node whose children have been reordered a valid #GtkTreeIter-struct pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` Get #GtkTreeModelFlags supported by this interface. the flags supported by this interface a #GtkTreeModel Get the number of columns supported by the model. the number of columns a #GtkTreeModel Get the type of the column. the type of the column a #GtkTreeModel the column index Sets iter to a valid iterator pointing to path. %TRUE, if @iter was set a #GtkTreeModel the uninitialized #GtkTreeIter-struct the #GtkTreePath-struct Gets a newly-created #GtkTreePath referenced by iter. a newly-created #GtkTreePath-struct a #GtkTreeModel the #GtkTreeIter-struct Initializes and sets value to that at column. a #GtkTreeModel the #GtkTreeIter-struct the column to lookup the value at an empty #GValue to set Sets iter to point to the node following it at the current level. %TRUE if @iter has been changed to the next node a #GtkTreeModel the #GtkTreeIter-struct Sets iter to point to the previous node at the current level. %TRUE if @iter has been changed to the previous node a #GtkTreeModel the #GtkTreeIter-struct Sets iter to point to the first child of parent. %TRUE, if @iter has been set to the first child a #GtkTreeModel the new #GtkTreeIter-struct to be set to the child the #GtkTreeIter-struct, or %NULL %TRUE if iter has children, %FALSE otherwise. %TRUE if @iter has children a #GtkTreeModel the #GtkTreeIter-struct to test for children Gets the number of children that iter has. the number of children of @iter a #GtkTreeModel the #GtkTreeIter-struct, or %NULL Sets iter to be the child of parent, using the given index. %TRUE, if @parent has an @n-th child a #GtkTreeModel the #GtkTreeIter-struct to set to the nth child the #GtkTreeIter-struct to get the child from, or %NULL. the index of the desired child Sets iter to be the parent of child. %TRUE, if @iter is set to the parent of @child a #GtkTreeModel the new #GtkTreeIter-struct to set to the parent the #GtkTreeIter-struct Lets the tree ref the node. a #GtkTreeModel the #GtkTreeIter-struct Lets the tree unref the node. a #GtkTreeModel the #GtkTreeIter-struct The #GtkTreeModelSort is a model which implements the #GtkTreeSortable interface. It does not hold any data itself, but rather is created with a child model and proxies its data. It has identical column types to this child model, and the changes in the child are propagated. The primary purpose of this model is to provide a way to sort a different model without modifying it. Note that the sort function used by #GtkTreeModelSort is not guaranteed to be stable. The use of this is best demonstrated through an example. In the following sample code we create two #GtkTreeView widgets each with a view of the same data. As the model is wrapped here by a #GtkTreeModelSort, the two #GtkTreeViews can each sort their view of the data without affecting the other. By contrast, if we simply put the same model in each widget, then sorting the first would sort the second. ## Using a #GtkTreeModelSort |[<!-- language="C" --> { GtkTreeView *tree_view1; GtkTreeView *tree_view2; GtkTreeModel *sort_model1; GtkTreeModel *sort_model2; GtkTreeModel *child_model; // get the child model child_model = get_my_model (); // Create the first tree sort_model1 = gtk_tree_model_sort_new_with_model (child_model); tree_view1 = gtk_tree_view_new_with_model (sort_model1); // Create the second tree sort_model2 = gtk_tree_model_sort_new_with_model (child_model); tree_view2 = gtk_tree_view_new_with_model (sort_model2); // Now we can sort the two models independently gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1), COLUMN_1, GTK_SORT_ASCENDING); gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2), COLUMN_1, GTK_SORT_DESCENDING); } ]| To demonstrate how to access the underlying child model from the sort model, the next example will be a callback for the #GtkTreeSelection #GtkTreeSelection::changed signal. In this callback, we get a string from COLUMN_1 of the model. We then modify the string, find the same selected row on the child model, and change the row there. ## Accessing the child model of in a selection changed callback |[<!-- language="C" --> void selection_changed (GtkTreeSelection *selection, gpointer data) { GtkTreeModel *sort_model = NULL; GtkTreeModel *child_model; GtkTreeIter sort_iter; GtkTreeIter child_iter; char *some_data = NULL; char *modified_data; // Get the current selected row and the model. if (! gtk_tree_selection_get_selected (selection, &sort_model, &sort_iter)) return; // Look up the current value on the selected row and get // a new value to change it to. gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter, COLUMN_1, &some_data, -1); modified_data = change_the_data (some_data); g_free (some_data); // Get an iterator on the child model, instead of the sort model. gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model), &child_iter, &sort_iter); // Get the child model and change the value of the row. In this // example, the child model is a GtkListStore. It could be any other // type of model, though. child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model)); gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter, COLUMN_1, &modified_data, -1); g_free (modified_data); } ]| Creates a new #GtkTreeModelSort, with @child_model as the child model. A new #GtkTreeModelSort. A #GtkTreeModel This function should almost never be called. It clears the @tree_model_sort of any cached iterators that haven’t been reffed with gtk_tree_model_ref_node(). This might be useful if the child model being sorted is static (and doesn’t change often) and there has been a lot of unreffed access to nodes. As a side effect of this function, all unreffed iters will be invalid. A #GtkTreeModelSort Sets @sort_iter to point to the row in @tree_model_sort that corresponds to the row pointed at by @child_iter. If @sort_iter was not set, %FALSE is returned. Note: a boolean is only returned since 2.14. %TRUE, if @sort_iter was set, i.e. if @sort_iter is a valid iterator pointer to a visible row in the child model. A #GtkTreeModelSort An uninitialized #GtkTreeIter. A valid #GtkTreeIter pointing to a row on the child model Converts @child_path to a path relative to @tree_model_sort. That is, @child_path points to a path in the child model. The returned path will point to the same row in the sorted model. If @child_path isn’t a valid path on the child model, then %NULL is returned. A newly allocated #GtkTreePath, or %NULL A #GtkTreeModelSort A #GtkTreePath to convert Sets @child_iter to point to the row pointed to by @sorted_iter. A #GtkTreeModelSort An uninitialized #GtkTreeIter A valid #GtkTreeIter pointing to a row on @tree_model_sort. Converts @sorted_path to a path on the child model of @tree_model_sort. That is, @sorted_path points to a location in @tree_model_sort. The returned path will point to the same location in the model not being sorted. If @sorted_path does not point to a location in the child model, %NULL is returned. A newly allocated #GtkTreePath, or %NULL A #GtkTreeModelSort A #GtkTreePath to convert Returns the model the #GtkTreeModelSort is sorting. the "child model" being sorted a #GtkTreeModelSort > This function is slow. Only use it for debugging and/or testing > purposes. Checks if the given iter is a valid iter for this #GtkTreeModelSort. %TRUE if the iter is valid, %FALSE if the iter is invalid. A #GtkTreeModelSort. A #GtkTreeIter. This resets the default sort function to be in the “unsorted” state. That is, it is in the same order as the child model. It will re-sort the model to be in the same order as the child model only if the #GtkTreeModelSort is in “unsorted” state. A #GtkTreeModelSort Creates a new #GtkTreePath-struct. This refers to a row. A newly created #GtkTreePath-struct. Creates a new #GtkTreePath-struct. The string representation of this path is “0”. A new #GtkTreePath-struct Creates a new path with @first_index and @varargs as indices. A newly created #GtkTreePath-struct first integer list of integers terminated by -1 Creates a new path with the given @indices array of @length. A newly created #GtkTreePath-struct array of indices length of @indices array Creates a new #GtkTreePath-struct initialized to @path. @path is expected to be a colon separated list of numbers. For example, the string “10:4:0” would create a path of depth 3 pointing to the 11th child of the root node, the 5th child of that 11th child, and the 1st child of that 5th child. If an invalid path string is passed in, %NULL is returned. A newly-created #GtkTreePath-struct, or %NULL The string representation of a path Appends a new index to a path. As a result, the depth of the path is increased. a #GtkTreePath-struct the index Compares two paths. If @a appears before @b in a tree, then -1 is returned. If @b appears before @a, then 1 is returned. If the two nodes are equal, then 0 is returned. the relative positions of @a and @b a #GtkTreePath-struct a #GtkTreePath-struct to compare with Creates a new #GtkTreePath-struct as a copy of @path. a new #GtkTreePath-struct a #GtkTreePath-struct Moves @path to point to the first child of the current path. a #GtkTreePath-struct Frees @path. If @path is %NULL, it simply returns. a #GtkTreePath-struct Returns the current depth of @path. The depth of @path a #GtkTreePath-struct Returns the current indices of @path. This is an array of integers, each representing a node in a tree. This value should not be freed. The length of the array can be obtained with gtk_tree_path_get_depth(). The current indices, or %NULL a #GtkTreePath-struct Returns the current indices of @path. This is an array of integers, each representing a node in a tree. It also returns the number of elements in the array. The array should not be freed. The current indices, or %NULL a #GtkTreePath-struct return location for number of elements returned in the integer array, or %NULL Returns %TRUE if @descendant is a descendant of @path. %TRUE if @descendant is contained inside @path a #GtkTreePath-struct another #GtkTreePath-struct Returns %TRUE if @path is a descendant of @ancestor. %TRUE if @ancestor contains @path somewhere below it a #GtkTreePath-struct another #GtkTreePath-struct Moves the @path to point to the next node at the current depth. a #GtkTreePath-struct Prepends a new index to a path. As a result, the depth of the path is increased. a #GtkTreePath-struct the index Moves the @path to point to the previous node at the current depth, if it exists. %TRUE if @path has a previous node, and the move was made a #GtkTreePath-struct Generates a string representation of the path. This string is a “:” separated list of numbers. For example, “4:10:0:3” would be an acceptable return value for this string. A newly-allocated string. Must be freed with g_free(). A #GtkTreePath-struct Moves the @path to point to its parent node, if it has a parent. %TRUE if @path has a parent, and the move was made a #GtkTreePath-struct A GtkTreeRowReference tracks model changes so that it always refers to the same row (a #GtkTreePath refers to a position, not a fixed row). Create a new GtkTreeRowReference with gtk_tree_row_reference_new(). Creates a row reference based on @path. This reference will keep pointing to the node pointed to by @path, so long as it exists. Any changes that occur on @model are propagated, and the path is updated appropriately. If @path isn’t a valid path in @model, then %NULL is returned. a newly allocated #GtkTreeRowReference, or %NULL a #GtkTreeModel a valid #GtkTreePath-struct to monitor You do not need to use this function. Creates a row reference based on @path. This reference will keep pointing to the node pointed to by @path, so long as it exists. If @path isn’t a valid path in @model, then %NULL is returned. However, unlike references created with gtk_tree_row_reference_new(), it does not listen to the model for changes. The creator of the row reference must do this explicitly using gtk_tree_row_reference_inserted(), gtk_tree_row_reference_deleted(), gtk_tree_row_reference_reordered(). These functions must be called exactly once per proxy when the corresponding signal on the model is emitted. This single call updates all row references for that proxy. Since built-in GTK+ objects like #GtkTreeView already use this mechanism internally, using them as the proxy object will produce unpredictable results. Further more, passing the same object as @model and @proxy doesn’t work for reasons of internal implementation. This type of row reference is primarily meant by structures that need to carefully monitor exactly when a row reference updates itself, and is not generally needed by most applications. a newly allocated #GtkTreeRowReference, or %NULL a proxy #GObject a #GtkTreeModel a valid #GtkTreePath-struct to monitor Copies a #GtkTreeRowReference. a copy of @reference a #GtkTreeRowReference Free’s @reference. @reference may be %NULL a #GtkTreeRowReference, or %NULL Returns the model that the row reference is monitoring. the model a #GtkTreeRowReference Returns a path that the row reference currently points to, or %NULL if the path pointed to is no longer valid. a current path, or %NULL a #GtkTreeRowReference Returns %TRUE if the @reference is non-%NULL and refers to a current valid path. %TRUE if @reference points to a valid path a #GtkTreeRowReference, or %NULL Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the #GtkTreeModel::row-deleted signal. a #GObject the path position that was deleted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the #GtkTreeModel::row-inserted signal. a #GObject the row position that was inserted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the #GtkTreeModel::rows-reordered signal. a #GObject the parent path of the reordered signal the iter pointing to the parent of the reordered the new order of rows The #GtkTreeSelection object is a helper object to manage the selection for a #GtkTreeView widget. The #GtkTreeSelection object is automatically created when a new #GtkTreeView widget is created, and cannot exist independently of this widget. The primary reason the #GtkTreeSelection objects exists is for cleanliness of code and API. That is, there is no conceptual reason all these functions could not be methods on the #GtkTreeView widget instead of a separate function. The #GtkTreeSelection object is gotten from a #GtkTreeView by calling gtk_tree_view_get_selection(). It can be manipulated to check the selection status of the tree, as well as select and deselect individual rows. Selection is done completely view side. As a result, multiple views of the same model can have completely different selections. Additionally, you cannot change the selection of a row on the model that is not currently displayed by the view without expanding its parents first. One of the important things to remember when monitoring the selection of a view is that the #GtkTreeSelection::changed signal is mostly a hint. That is, it may only emit one signal when a range of rows is selected. Additionally, it may on occasion emit a #GtkTreeSelection::changed signal when nothing has happened (mostly as a result of programmers calling select_row on an already selected row). Signal emitted whenever the selection has (possibly) changed. Returns the number of rows that have been selected in @tree. The number of rows selected. A #GtkTreeSelection. Gets the selection mode for @selection. See gtk_tree_selection_set_mode(). the current selection mode a #GtkTreeSelection Returns the current selection function. The function. A #GtkTreeSelection. Sets @iter to the currently selected node, if @selection is set to %GTK_SELECTION_SINGLE or %GTK_SELECTION_BROWSE. The @iter argument may be %NULL if you just want to test if @selection has any selected nodes. The @model argument is filled with the current model as a convenience. This function will not work with %GTK_SELECTION_MULTIPLE. See gtk_tree_selection_get_selected_rows() instead. %TRUE, if there is a selected node. A #GtkTreeSelection. the model the iterator for the selected row Creates a list of path of all selected rows. Additionally, if you are planning on modifying the model after calling this function, you may want to convert the returned list into a list of #GtkTreeRowReferences. To do this, you can use gtk_tree_row_reference_new(). To free the return value, use: |[<!-- language="C" --> g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); ]| the selected paths A #GtkTreeSelection. A pointer to set to the #GtkTreeModel, or %NULL. Returns the tree view associated with @selection. A #GtkTreeView A #GtkTreeSelection Returns the user data for the selection function. The user data. A #GtkTreeSelection. Returns %TRUE if the row at @iter is currently selected. %TRUE, if @iter is selected A #GtkTreeSelection A valid #GtkTreeIter Returns %TRUE if the row pointed to by @path is currently selected. If @path does not point to a valid location, %FALSE is returned %TRUE if @path is selected. A #GtkTreeSelection. A #GtkTreePath to check selection on. Selects all the nodes. @selection must be set to #GTK_SELECTION_MULTIPLE mode. A #GtkTreeSelection. Selects the specified iterator. A #GtkTreeSelection. The #GtkTreeIter to be selected. Select the row at @path. A #GtkTreeSelection. The #GtkTreePath to be selected. Selects a range of nodes, determined by @start_path and @end_path inclusive. @selection must be set to #GTK_SELECTION_MULTIPLE mode. A #GtkTreeSelection. The initial node of the range. The final node of the range. Calls a function for each selected node. Note that you cannot modify the tree or selection from within this function. As a result, gtk_tree_selection_get_selected_rows() might be more useful. A #GtkTreeSelection. The function to call for each selected node. user data to pass to the function. Sets the selection mode of the @selection. If the previous type was #GTK_SELECTION_MULTIPLE, then the anchor is kept selected, if it was previously selected. A #GtkTreeSelection. The selection mode Sets the selection function. If set, this function is called before any node is selected or unselected, giving some control over which nodes are selected. The select function should return %TRUE if the state of the node may be toggled, and %FALSE if the state of the node should be left unchanged. A #GtkTreeSelection. The selection function. May be %NULL The selection function’s data. May be %NULL The destroy function for user data. May be %NULL Unselects all the nodes. A #GtkTreeSelection. Unselects the specified iterator. A #GtkTreeSelection. The #GtkTreeIter to be unselected. Unselects the row at @path. A #GtkTreeSelection. The #GtkTreePath to be unselected. Unselects a range of nodes, determined by @start_path and @end_path inclusive. A #GtkTreeSelection. The initial node of the range. The initial node of the range. Selection mode. See gtk_tree_selection_set_mode() for more information on this property. Emitted whenever the selection has (possibly) changed. Please note that this signal is mostly a hint. It may only be emitted once when a range of rows are selected, and it may occasionally be emitted when nothing has happened. The parent class. Signal emitted whenever the selection has (possibly) changed. A function used by gtk_tree_selection_selected_foreach() to map all selected rows. It will be called on every selected row in the view. The #GtkTreeModel being viewed The #GtkTreePath of a selected row A #GtkTreeIter pointing to a selected row user data A function used by gtk_tree_selection_set_select_function() to filter whether or not a row may be selected. It is called whenever a row's state might change. A return value of %TRUE indicates to @selection that it is okay to change the selection. %TRUE, if the selection state of the row can be toggled A #GtkTreeSelection A #GtkTreeModel being viewed The #GtkTreePath of the row in question %TRUE, if the path is currently selected user data #GtkTreeSortable is an interface to be implemented by tree models which support sorting. The #GtkTreeView uses the methods provided by this interface to sort the model. Fills in @sort_column_id and @order with the current sort column and the order. It returns %TRUE unless the @sort_column_id is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID or %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID. %TRUE if the sort column is not one of the special sort column ids. A #GtkTreeSortable The sort column id to be filled in The #GtkSortType to be filled in Returns %TRUE if the model has a default sort function. This is used primarily by GtkTreeViewColumns in order to determine if a model can go back to the default state, or not. %TRUE, if the model has a default sort function A #GtkTreeSortable Sets the default comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the model will sort using this function. If @sort_func is %NULL, then there will be no default comparison function. This means that once the model has been sorted, it can’t go back to the default state. In this case, when the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted. A #GtkTreeSortable The comparison function User data to pass to @sort_func, or %NULL Destroy notifier of @user_data, or %NULL Sets the current sort column to be @sort_column_id. The @sortable will resort itself to reflect this change, after emitting a #GtkTreeSortable::sort-column-changed signal. @sort_column_id may either be a regular column id, or one of the following special values: - %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID: the default sort function will be used, if it is set - %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID: no sorting will occur A #GtkTreeSortable the sort column id to set The sort order of the column Sets the comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is the same as @sort_column_id, then the model will sort using this function. A #GtkTreeSortable the sort column id to set the function for The comparison function User data to pass to @sort_func, or %NULL Destroy notifier of @user_data, or %NULL Emits a #GtkTreeSortable::sort-column-changed signal on @sortable. A #GtkTreeSortable Fills in @sort_column_id and @order with the current sort column and the order. It returns %TRUE unless the @sort_column_id is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID or %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID. %TRUE if the sort column is not one of the special sort column ids. A #GtkTreeSortable The sort column id to be filled in The #GtkSortType to be filled in Returns %TRUE if the model has a default sort function. This is used primarily by GtkTreeViewColumns in order to determine if a model can go back to the default state, or not. %TRUE, if the model has a default sort function A #GtkTreeSortable Sets the default comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the model will sort using this function. If @sort_func is %NULL, then there will be no default comparison function. This means that once the model has been sorted, it can’t go back to the default state. In this case, when the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted. A #GtkTreeSortable The comparison function User data to pass to @sort_func, or %NULL Destroy notifier of @user_data, or %NULL Sets the current sort column to be @sort_column_id. The @sortable will resort itself to reflect this change, after emitting a #GtkTreeSortable::sort-column-changed signal. @sort_column_id may either be a regular column id, or one of the following special values: - %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID: the default sort function will be used, if it is set - %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID: no sorting will occur A #GtkTreeSortable the sort column id to set The sort order of the column Sets the comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is the same as @sort_column_id, then the model will sort using this function. A #GtkTreeSortable the sort column id to set the function for The comparison function User data to pass to @sort_func, or %NULL Destroy notifier of @user_data, or %NULL Emits a #GtkTreeSortable::sort-column-changed signal on @sortable. A #GtkTreeSortable The ::sort-column-changed signal is emitted when the sort column or sort order of @sortable is changed. The signal is emitted before the contents of @sortable are resorted. Signal emitted when the sort column or sort order of sortable is changed. A #GtkTreeSortable Fills in sort_column_id and order with the current sort column and the order. %TRUE if the sort column is not one of the special sort column ids. A #GtkTreeSortable The sort column id to be filled in The #GtkSortType to be filled in Sets the current sort column to be sort_column_id. A #GtkTreeSortable the sort column id to set The sort order of the column Sets the comparison function used when sorting to be sort_func. A #GtkTreeSortable the sort column id to set the function for The comparison function User data to pass to @sort_func, or %NULL Destroy notifier of @user_data, or %NULL Sets the default comparison function used when sorting to be sort_func. A #GtkTreeSortable The comparison function User data to pass to @sort_func, or %NULL Destroy notifier of @user_data, or %NULL %TRUE if the model has a default sort function. %TRUE, if the model has a default sort function A #GtkTreeSortable The #GtkTreeStore object is a list model for use with a #GtkTreeView widget. It implements the #GtkTreeModel interface, and consequentially, can use all of the methods available there. It also implements the #GtkTreeSortable interface so it can be sorted by the view. Finally, it also implements the tree [drag and drop][gtk3-GtkTreeView-drag-and-drop] interfaces. # GtkTreeStore as GtkBuildable The GtkTreeStore implementation of the #GtkBuildable interface allows to specify the model columns with a `<columns>` element that may contain multiple `<column>` elements, each specifying one model column. The “type” attribute specifies the data type for the column. An example of a UI Definition fragment for a tree store: |[<!-- language="xml" --> <object class="GtkTreeStore"> <columns> <column type="gchararray"/> <column type="gchararray"/> <column type="gint"/> </columns> </object> ]| Creates a new tree store as with @n_columns columns each of the types passed in. Note that only types derived from standard GObject fundamental types are supported. As an example, `gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING, GDK_TYPE_PIXBUF);` will create a new #GtkTreeStore with three columns, of type #gint, #gchararray, and #GdkPixbuf respectively. a new #GtkTreeStore number of columns in the tree store all #GType types for the columns, from first to last Non vararg creation function. Used primarily by language bindings. a new #GtkTreeStore number of columns in the tree store an array of #GType types for the columns, from first to last Appends a new row to @tree_store. If @parent is non-%NULL, then it will append the new row after the last child of @parent, otherwise it will append a row to the top level. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). A #GtkTreeStore An unset #GtkTreeIter to set to the appended row A valid #GtkTreeIter, or %NULL Removes all rows from @tree_store a #GtkTreeStore Creates a new row at @position. If parent is non-%NULL, then the row will be made a child of @parent. Otherwise, the row will be created at the toplevel. If @position is -1 or is larger than the number of rows at that level, then the new row will be inserted to the end of the list. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). A #GtkTreeStore An unset #GtkTreeIter to set to the new row A valid #GtkTreeIter, or %NULL position to insert the new row, or -1 for last Inserts a new row after @sibling. If @sibling is %NULL, then the row will be prepended to @parent ’s children. If @parent and @sibling are %NULL, then the row will be prepended to the toplevel. If both @sibling and @parent are set, then @parent must be the parent of @sibling. When @sibling is set, @parent is optional. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). A #GtkTreeStore An unset #GtkTreeIter to set to the new row A valid #GtkTreeIter, or %NULL A valid #GtkTreeIter, or %NULL Inserts a new row before @sibling. If @sibling is %NULL, then the row will be appended to @parent ’s children. If @parent and @sibling are %NULL, then the row will be appended to the toplevel. If both @sibling and @parent are set, then @parent must be the parent of @sibling. When @sibling is set, @parent is optional. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). A #GtkTreeStore An unset #GtkTreeIter to set to the new row A valid #GtkTreeIter, or %NULL A valid #GtkTreeIter, or %NULL Creates a new row at @position. @iter will be changed to point to this new row. If @position is -1, or larger than the number of rows on the list, then the new row will be appended to the list. The row will be filled with the values given to this function. Calling `gtk_tree_store_insert_with_values (tree_store, iter, position, ...)` has the same effect as calling |[<!-- language="C" --> gtk_tree_store_insert (tree_store, iter, position); gtk_tree_store_set (tree_store, iter, ...); ]| with the different that the former will only emit a row_inserted signal, while the latter will emit row_inserted, row_changed and if the tree store is sorted, rows_reordered. Since emitting the rows_reordered signal repeatedly can affect the performance of the program, gtk_tree_store_insert_with_values() should generally be preferred when inserting rows in a sorted tree store. A #GtkTreeStore An unset #GtkTreeIter to set the new row, or %NULL. A valid #GtkTreeIter, or %NULL position to insert the new row, or -1 to append after existing rows pairs of column number and value, terminated with -1 A variant of gtk_tree_store_insert_with_values() which takes the columns and values as two arrays, instead of varargs. This function is mainly intended for language bindings. A #GtkTreeStore An unset #GtkTreeIter to set the new row, or %NULL. A valid #GtkTreeIter, or %NULL position to insert the new row, or -1 for last an array of column numbers an array of GValues the length of the @columns and @values arrays Returns %TRUE if @iter is an ancestor of @descendant. That is, @iter is the parent (or grandparent or great-grandparent) of @descendant. %TRUE, if @iter is an ancestor of @descendant A #GtkTreeStore A valid #GtkTreeIter A valid #GtkTreeIter Returns the depth of @iter. This will be 0 for anything on the root level, 1 for anything down a level, etc. The depth of @iter A #GtkTreeStore A valid #GtkTreeIter WARNING: This function is slow. Only use it for debugging and/or testing purposes. Checks if the given iter is a valid iter for this #GtkTreeStore. %TRUE if the iter is valid, %FALSE if the iter is invalid. A #GtkTreeStore. A #GtkTreeIter. Moves @iter in @tree_store to the position after @position. @iter and @position should be in the same level. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the start of the level. A #GtkTreeStore. A #GtkTreeIter. A #GtkTreeIter. Moves @iter in @tree_store to the position before @position. @iter and @position should be in the same level. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the end of the level. A #GtkTreeStore. A #GtkTreeIter. A #GtkTreeIter or %NULL. Prepends a new row to @tree_store. If @parent is non-%NULL, then it will prepend the new row before the first child of @parent, otherwise it will prepend a row to the top level. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). A #GtkTreeStore An unset #GtkTreeIter to set to the prepended row A valid #GtkTreeIter, or %NULL Removes @iter from @tree_store. After being removed, @iter is set to the next valid row at that level, or invalidated if it previously pointed to the last one. %TRUE if @iter is still valid, %FALSE if not. A #GtkTreeStore A valid #GtkTreeIter Reorders the children of @parent in @tree_store to follow the order indicated by @new_order. Note that this function only works with unsorted stores. A #GtkTreeStore A #GtkTreeIter, or %NULL an array of integers mapping the new position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos`. Sets the value of one or more cells in the row referenced by @iter. The variable argument list should contain integer column numbers, each column number followed by the value to be set. The list is terminated by a -1. For example, to set column 0 with type %G_TYPE_STRING to “Foo”, you would write `gtk_tree_store_set (store, iter, 0, "Foo", -1)`. The value will be referenced by the store if it is a %G_TYPE_OBJECT, and it will be copied if it is a %G_TYPE_STRING or %G_TYPE_BOXED. A #GtkTreeStore A valid #GtkTreeIter for the row being modified pairs of column number and value, terminated with -1 This function is meant primarily for #GObjects that inherit from #GtkTreeStore, and should only be used when constructing a new #GtkTreeStore. It will not function after a row has been added, or a method on the #GtkTreeModel interface is called. A #GtkTreeStore Number of columns for the tree store An array of #GType types, one for each column See gtk_tree_store_set(); this version takes a va_list for use by language bindings. A #GtkTreeStore A valid #GtkTreeIter for the row being modified va_list of column/value pairs Sets the data in the cell specified by @iter and @column. The type of @value must be convertible to the type of the column. a #GtkTreeStore A valid #GtkTreeIter for the row being modified column number to modify new value for the cell A variant of gtk_tree_store_set_valist() which takes the columns and values as two arrays, instead of varargs. This function is mainly intended for language bindings or in case the number of columns to change is not known until run-time. A #GtkTreeStore A valid #GtkTreeIter for the row being modified an array of column numbers an array of GValues the length of the @columns and @values arrays Swaps @a and @b in the same level of @tree_store. Note that this function only works with unsorted stores. A #GtkTreeStore. A #GtkTreeIter. Another #GtkTreeIter. Widget that displays any object that implements the #GtkTreeModel interface. Please refer to the [tree widget conceptual overview](TreeWidget.html) for an overview of all the objects and data types related to the tree widget and how they work together. Several different coordinate systems are exposed in the GtkTreeView API. These are: ![](tree-view-coordinates.png) Coordinate systems in GtkTreeView API: - Widget coordinates: Coordinates relative to the widget (usually `widget->window`). - Bin window coordinates: Coordinates relative to the window that GtkTreeView renders to. - Tree coordinates: Coordinates relative to the entire scrollable area of GtkTreeView. These coordinates start at (0, 0) for row 0 of the tree. Several functions are available for converting between the different coordinate systems. The most common translations are between widget and bin window coordinates and between bin window and tree coordinates. For the former you can use gtk_tree_view_convert_widget_to_bin_window_coords() (and vice versa), for the latter gtk_tree_view_convert_bin_window_to_tree_coords() (and vice versa). # GtkTreeView as GtkBuildable The GtkTreeView implementation of the GtkBuildable interface accepts #GtkTreeViewColumn objects as `<child>` elements and exposes the internal #GtkTreeSelection in UI definitions. An example of a UI definition fragment with GtkTreeView: |[<!-- language="xml" --> <object class="GtkTreeView" id="treeview"> <property name="model">liststore1</property> <child> <object class="GtkTreeViewColumn" id="test-column"> <property name="title">Test</property> <child> <object class="GtkCellRendererText" id="test-renderer"/> <attributes> <attribute name="text">1</attribute> </attributes> </child> </object> </child> <child internal-child="selection"> <object class="GtkTreeSelection" id="selection"> <signal name="changed" handler="on_treeview_selection_changed"/> </object> </child> </object> ]| # CSS nodes |[<!-- language="plain" --> treeview.view ├── header │ ├── <column header> ┊ ┊ │ ╰── <column header> │ ╰── [rubberband] ]| GtkTreeView has a main CSS node with name treeview and style class .view. It has a subnode with name header, which is the parent for all the column header widgets' CSS nodes. For rubberband selection, a subnode with name rubberband is used. Creates a new #GtkTreeView widget. A newly created #GtkTreeView widget. Creates a new #GtkTreeView widget with the model initialized to @model. A newly created #GtkTreeView widget. the model. Activates the cell determined by @path and @column. A #GtkTreeView The #GtkTreePath to be activated. The #GtkTreeViewColumn to be activated. Appends @column to the list of columns. If @tree_view has “fixed_height” mode enabled, then @column must have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. The number of columns in @tree_view after appending. A #GtkTreeView. The #GtkTreeViewColumn to add. Recursively collapses all visible, expanded nodes in @tree_view. A #GtkTreeView. Collapses a row (hides its child rows, if they exist). %TRUE if the row was collapsed. a #GtkTreeView path to a row in the @tree_view Resizes all columns to their optimal width. Only works after the treeview has been realized. A #GtkTreeView. Converts bin_window coordinates to coordinates for the tree (the full scrollable area of the tree). a #GtkTreeView X coordinate relative to bin_window Y coordinate relative to bin_window return location for tree X coordinate return location for tree Y coordinate Converts bin_window coordinates (see gtk_tree_view_get_bin_window()) to widget relative coordinates. a #GtkTreeView bin_window X coordinate bin_window Y coordinate return location for widget X coordinate return location for widget Y coordinate Converts tree coordinates (coordinates in full scrollable area of the tree) to bin_window coordinates. a #GtkTreeView tree X coordinate tree Y coordinate return location for X coordinate relative to bin_window return location for Y coordinate relative to bin_window Converts tree coordinates (coordinates in full scrollable area of the tree) to widget coordinates. a #GtkTreeView X coordinate relative to the tree Y coordinate relative to the tree return location for widget X coordinate return location for widget Y coordinate Converts widget coordinates to coordinates for the bin_window (see gtk_tree_view_get_bin_window()). a #GtkTreeView X coordinate relative to the widget Y coordinate relative to the widget return location for bin_window X coordinate return location for bin_window Y coordinate Converts widget coordinates to coordinates for the tree (the full scrollable area of the tree). a #GtkTreeView X coordinate relative to the widget Y coordinate relative to the widget return location for tree X coordinate return location for tree Y coordinate Creates a #cairo_surface_t representation of the row at @path. This image is used for a drag icon. a newly-allocated surface of the drag icon. a #GtkTreeView a #GtkTreePath in @tree_view Turns @tree_view into a drop destination for automatic DND. Calling this method sets #GtkTreeView:reorderable to %FALSE. a #GtkTreeView the table of targets that the drag will support the number of items in @targets the bitmask of possible actions for a drag from this widget Turns @tree_view into a drag source for automatic DND. Calling this method sets #GtkTreeView:reorderable to %FALSE. a #GtkTreeView Mask of allowed buttons to start drag the table of targets that the drag will support the number of items in @targets the bitmask of possible actions for a drag from this widget Recursively expands all nodes in the @tree_view. A #GtkTreeView. Opens the row so its children are visible. %TRUE if the row existed and had children a #GtkTreeView path to a row whether to recursively expand, or just expand immediate children Expands the row at @path. This will also expand all parent rows of @path as necessary. A #GtkTreeView. path to a row. Gets the setting set by gtk_tree_view_set_activate_on_single_click(). %TRUE if row-activated will be emitted on a single click a #GtkTreeView Fills the bounding rectangle in bin_window coordinates for the cell at the row specified by @path and the column specified by @column. If @path is %NULL, or points to a node not found in the tree, the @y and @height fields of the rectangle will be filled with 0. If @column is %NULL, the @x and @width fields will be filled with 0. The returned rectangle is equivalent to the @background_area passed to gtk_cell_renderer_render(). These background areas tile to cover the entire bin window. Contrast with the @cell_area, returned by gtk_tree_view_get_cell_area(), which returns only the cell itself, excluding surrounding borders and the tree expander area. a #GtkTreeView a #GtkTreePath for the row, or %NULL to get only horizontal coordinates a #GtkTreeViewColumn for the column, or %NULL to get only vertical coordiantes rectangle to fill with cell background rect Returns the window that @tree_view renders to. This is used primarily to compare to `event->window` to confirm that the event on @tree_view is on the right window. A #GdkWindow, or %NULL when @tree_view hasn’t been realized yet. A #GtkTreeView Fills the bounding rectangle in bin_window coordinates for the cell at the row specified by @path and the column specified by @column. If @path is %NULL, or points to a path not currently displayed, the @y and @height fields of the rectangle will be filled with 0. If @column is %NULL, the @x and @width fields will be filled with 0. The sum of all cell rects does not cover the entire tree; there are extra pixels in between rows, for example. The returned rectangle is equivalent to the @cell_area passed to gtk_cell_renderer_render(). This function is only valid if @tree_view is realized. a #GtkTreeView a #GtkTreePath for the row, or %NULL to get only horizontal coordinates a #GtkTreeViewColumn for the column, or %NULL to get only vertical coordinates rectangle to fill with cell rect Gets the #GtkTreeViewColumn at the given position in the #tree_view. The #GtkTreeViewColumn, or %NULL if the position is outside the range of columns. A #GtkTreeView. The position of the column, counting from 0. Returns a #GList of all the #GtkTreeViewColumn s currently in @tree_view. The returned list must be freed with g_list_free (). A list of #GtkTreeViewColumn s A #GtkTreeView Fills in @path and @focus_column with the current path and focus column. If the cursor isn’t currently set, then *@path will be %NULL. If no column currently has focus, then *@focus_column will be %NULL. The returned #GtkTreePath must be freed with gtk_tree_path_free() when you are done with it. A #GtkTreeView A pointer to be filled with the current cursor path, or %NULL A pointer to be filled with the current focus column, or %NULL Determines the destination row for a given position. @drag_x and @drag_y are expected to be in widget coordinates. This function is only meaningful if @tree_view is realized. Therefore this function will always return %FALSE if @tree_view is not realized or does not have a model. whether there is a row at the given position, %TRUE if this is indeed the case. a #GtkTreeView the position to determine the destination row for the position to determine the destination row for Return location for the path of the highlighted row, or %NULL. Return location for the drop position, or %NULL Gets information about the row that is highlighted for feedback. a #GtkTreeView Return location for the path of the highlighted row, or %NULL. Return location for the drop position, or %NULL Returns whether or not the tree allows to start interactive searching by typing in text. whether or not to let the user search interactively A #GtkTreeView Returns whether or not tree lines are drawn in @tree_view. %TRUE if tree lines are drawn in @tree_view, %FALSE otherwise. a #GtkTreeView. Returns the column that is the current expander column. This column has the expander arrow drawn next to it. The expander column. A #GtkTreeView Returns whether fixed height mode is turned on for @tree_view. %TRUE if @tree_view is in fixed height mode a #GtkTreeView Returns which grid lines are enabled in @tree_view. a #GtkTreeViewGridLines value indicating which grid lines are enabled. a #GtkTreeView Gets the #GtkAdjustment currently being used for the horizontal aspect. Use gtk_scrollable_get_hadjustment() A #GtkAdjustment object, or %NULL if none is currently being used. A #GtkTreeView Returns whether all header columns are clickable. %TRUE if all header columns are clickable, otherwise %FALSE A #GtkTreeView. Returns %TRUE if the headers on the @tree_view are visible. Whether the headers are visible or not. A #GtkTreeView. Returns whether hover expansion mode is turned on for @tree_view. %TRUE if @tree_view is in hover expansion mode a #GtkTreeView Returns whether hover selection mode is turned on for @tree_view. %TRUE if @tree_view is in hover selection mode a #GtkTreeView Returns the amount, in pixels, of extra indentation for child levels in @tree_view. the amount of extra indentation for child levels in @tree_view. A return value of 0 means that this feature is disabled. a #GtkTreeView. Returns the model the #GtkTreeView is based on. Returns %NULL if the model is unset. A #GtkTreeModel, or %NULL if none is currently being used. a #GtkTreeView Queries the number of columns in the given @tree_view. The number of columns in the @tree_view a #GtkTreeView Finds the path at the point (@x, @y), relative to bin_window coordinates (please see gtk_tree_view_get_bin_window()). That is, @x and @y are relative to an events coordinates. @x and @y must come from an event on the @tree_view only where `event->window == gtk_tree_view_get_bin_window ()`. It is primarily for things like popup menus. If @path is non-%NULL, then it will be filled with the #GtkTreePath at that point. This path should be freed with gtk_tree_path_free(). If @column is non-%NULL, then it will be filled with the column at that point. @cell_x and @cell_y return the coordinates relative to the cell background (i.e. the @background_area passed to gtk_cell_renderer_render()). This function is only meaningful if @tree_view is realized. Therefore this function will always return %FALSE if @tree_view is not realized or does not have a model. For converting widget coordinates (eg. the ones you get from GtkWidget::query-tooltip), please see gtk_tree_view_convert_widget_to_bin_window_coords(). %TRUE if a row exists at that coordinate. A #GtkTreeView. The x position to be identified (relative to bin_window). The y position to be identified (relative to bin_window). A pointer to a #GtkTreePath pointer to be filled in, or %NULL A pointer to a #GtkTreeViewColumn pointer to be filled in, or %NULL A pointer where the X coordinate relative to the cell can be placed, or %NULL A pointer where the Y coordinate relative to the cell can be placed, or %NULL Retrieves whether the user can reorder the tree via drag-and-drop. See gtk_tree_view_set_reorderable(). %TRUE if the tree can be reordered. a #GtkTreeView Returns the current row separator function. the current row separator function. a #GtkTreeView Returns whether rubber banding is turned on for @tree_view. If the selection mode is #GTK_SELECTION_MULTIPLE, rubber banding will allow the user to select multiple rows by dragging the mouse. %TRUE if rubber banding in @tree_view is enabled. a #GtkTreeView Gets the setting set by gtk_tree_view_set_rules_hint(). %TRUE if the hint is set a #GtkTreeView Gets the column searched on by the interactive search code. the column the interactive search code searches in. A #GtkTreeView Returns the #GtkEntry which is currently in use as interactive search entry for @tree_view. In case the built-in entry is being used, %NULL will be returned. the entry currently in use as search entry. A #GtkTreeView Returns the compare function currently in use. the currently used compare function for the search code. A #GtkTreeView Returns the positioning function currently in use. the currently used function for positioning the search dialog. A #GtkTreeView Gets the #GtkTreeSelection associated with @tree_view. A #GtkTreeSelection object. A #GtkTreeView. Returns whether or not expanders are drawn in @tree_view. %TRUE if expanders are drawn in @tree_view, %FALSE otherwise. a #GtkTreeView. Returns the column of @tree_view’s model which is being used for displaying tooltips on @tree_view’s rows. the index of the tooltip column that is currently being used, or -1 if this is disabled. a #GtkTreeView This function is supposed to be used in a #GtkWidget::query-tooltip signal handler for #GtkTreeView. The @x, @y and @keyboard_tip values which are received in the signal handler, should be passed to this function without modification. The return value indicates whether there is a tree view row at the given coordinates (%TRUE) or not (%FALSE) for mouse tooltips. For keyboard tooltips the row returned will be the cursor row. When %TRUE, then any of @model, @path and @iter which have been provided will be set to point to that row and the corresponding model. @x and @y will always be converted to be relative to @tree_view’s bin_window if @keyboard_tooltip is %FALSE. whether or not the given tooltip context points to a row. a #GtkTreeView the x coordinate (relative to widget coordinates) the y coordinate (relative to widget coordinates) whether this is a keyboard tooltip or not a pointer to receive a #GtkTreeModel or %NULL a pointer to receive a #GtkTreePath or %NULL a pointer to receive a #GtkTreeIter or %NULL Gets the #GtkAdjustment currently being used for the vertical aspect. Use gtk_scrollable_get_vadjustment() A #GtkAdjustment object, or %NULL if none is currently being used. A #GtkTreeView Sets @start_path and @end_path to be the first and last visible path. Note that there may be invisible paths in between. The paths should be freed with gtk_tree_path_free() after use. %TRUE, if valid paths were placed in @start_path and @end_path. A #GtkTreeView Return location for start of region, or %NULL. Return location for end of region, or %NULL. Fills @visible_rect with the currently-visible region of the buffer, in tree coordinates. Convert to bin_window coordinates with gtk_tree_view_convert_tree_to_bin_window_coords(). Tree coordinates start at 0,0 for row 0 of the tree, and cover the entire scrollable area of the tree. a #GtkTreeView rectangle to fill This inserts the @column into the @tree_view at @position. If @position is -1, then the column is inserted at the end. If @tree_view has “fixed_height” mode enabled, then @column must have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. The number of columns in @tree_view after insertion. A #GtkTreeView. The #GtkTreeViewColumn to be inserted. The position to insert @column in. Creates a new #GtkTreeViewColumn and inserts it into the @tree_view at @position. If @position is -1, then the newly created column is inserted at the end. The column is initialized with the attributes given. If @tree_view has “fixed_height” mode enabled, then the new column will have its sizing property set to be GTK_TREE_VIEW_COLUMN_FIXED. The number of columns in @tree_view after insertion. A #GtkTreeView The position to insert the new column in The title to set the header to The #GtkCellRenderer A %NULL-terminated list of attributes Convenience function that inserts a new column into the #GtkTreeView with the given cell renderer and a #GtkTreeCellDataFunc to set cell renderer attributes (normally using data from the model). See also gtk_tree_view_column_set_cell_data_func(), gtk_tree_view_column_pack_start(). If @tree_view has “fixed_height” mode enabled, then the new column will have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. number of columns in the tree view post-insert a #GtkTreeView Position to insert, -1 for append column title cell renderer for column function to set attributes of cell renderer data for @func destroy notifier for @data Determine whether the point (@x, @y) in @tree_view is blank, that is no cell content nor an expander arrow is drawn at the location. If so, the location can be considered as the background. You might wish to take special action on clicks on the background, such as clearing a current selection, having a custom context menu or starting rubber banding. The @x and @y coordinate that are provided must be relative to bin_window coordinates. That is, @x and @y must come from an event on @tree_view where `event->window == gtk_tree_view_get_bin_window ()`. For converting widget coordinates (eg. the ones you get from GtkWidget::query-tooltip), please see gtk_tree_view_convert_widget_to_bin_window_coords(). The @path, @column, @cell_x and @cell_y arguments will be filled in likewise as for gtk_tree_view_get_path_at_pos(). Please see gtk_tree_view_get_path_at_pos() for more information. %TRUE if the area at the given coordinates is blank, %FALSE otherwise. A #GtkTreeView The x position to be identified (relative to bin_window) The y position to be identified (relative to bin_window) A pointer to a #GtkTreePath pointer to be filled in, or %NULL A pointer to a #GtkTreeViewColumn pointer to be filled in, or %NULL A pointer where the X coordinate relative to the cell can be placed, or %NULL A pointer where the Y coordinate relative to the cell can be placed, or %NULL Returns whether a rubber banding operation is currently being done in @tree_view. %TRUE if a rubber banding operation is currently being done in @tree_view. a #GtkTreeView Calls @func on all expanded rows. A #GtkTreeView A function to be called User data to be passed to the function. Moves @column to be after to @base_column. If @base_column is %NULL, then @column is placed in the first position. A #GtkTreeView The #GtkTreeViewColumn to be moved. The #GtkTreeViewColumn to be moved relative to, or %NULL. Removes @column from @tree_view. The number of columns in @tree_view after removing. A #GtkTreeView. The #GtkTreeViewColumn to remove. Activates the cell determined by @path and @column. A #GtkTreeView The #GtkTreePath to be activated. The #GtkTreeViewColumn to be activated. Returns %TRUE if the node pointed to by @path is expanded in @tree_view. %TRUE if #path is expanded. A #GtkTreeView. A #GtkTreePath to test expansion state. Moves the alignments of @tree_view to the position specified by @column and @path. If @column is %NULL, then no horizontal scrolling occurs. Likewise, if @path is %NULL no vertical scrolling occurs. At a minimum, one of @column or @path need to be non-%NULL. @row_align determines where the row is placed, and @col_align determines where @column is placed. Both are expected to be between 0.0 and 1.0. 0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 means center. If @use_align is %FALSE, then the alignment arguments are ignored, and the tree does the minimum amount of work to scroll the cell onto the screen. This means that the cell will be scrolled to the edge closest to its current position. If the cell is currently visible on the screen, nothing is done. This function only works if the model is set, and @path is a valid row on the model. If the model changes before the @tree_view is realized, the centered path will be modified to reflect this change. A #GtkTreeView. The path of the row to move to, or %NULL. The #GtkTreeViewColumn to move horizontally to, or %NULL. whether to use alignment arguments, or %FALSE. The vertical alignment of the row specified by @path. The horizontal alignment of the column specified by @column. Scrolls the tree view such that the top-left corner of the visible area is @tree_x, @tree_y, where @tree_x and @tree_y are specified in tree coordinates. The @tree_view must be realized before this function is called. If it isn't, you probably want to be using gtk_tree_view_scroll_to_cell(). If either @tree_x or @tree_y are -1, then that direction isn’t scrolled. a #GtkTreeView X coordinate of new top-left pixel of visible area, or -1 Y coordinate of new top-left pixel of visible area, or -1 Cause the #GtkTreeView::row-activated signal to be emitted on a single click instead of a double click. a #GtkTreeView %TRUE to emit row-activated on a single click Sets a user function for determining where a column may be dropped when dragged. This function is called on every column pair in turn at the beginning of a column drag to determine where a drop can take place. The arguments passed to @func are: the @tree_view, the #GtkTreeViewColumn being dragged, the two #GtkTreeViewColumn s determining the drop spot, and @user_data. If either of the #GtkTreeViewColumn arguments for the drop spot are %NULL, then they indicate an edge. If @func is set to be %NULL, then @tree_view reverts to the default behavior of allowing all columns to be dropped everywhere. A #GtkTreeView. A function to determine which columns are reorderable, or %NULL. User data to be passed to @func, or %NULL Destroy notifier for @user_data, or %NULL Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular row. If @focus_column is not %NULL, then focus is given to the column specified by it. Additionally, if @focus_column is specified, and @start_editing is %TRUE, then editing should be started in the specified cell. This function is often followed by @gtk_widget_grab_focus (@tree_view) in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized. If @path is invalid for @model, the current cursor (if any) will be unset and the function will return without failing. A #GtkTreeView A #GtkTreePath A #GtkTreeViewColumn, or %NULL %TRUE if the specified cell should start being edited. Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular row. If @focus_column is not %NULL, then focus is given to the column specified by it. If @focus_column and @focus_cell are not %NULL, and @focus_column contains 2 or more editable or activatable cells, then focus is given to the cell specified by @focus_cell. Additionally, if @focus_column is specified, and @start_editing is %TRUE, then editing should be started in the specified cell. This function is often followed by @gtk_widget_grab_focus (@tree_view) in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized. If @path is invalid for @model, the current cursor (if any) will be unset and the function will return without failing. A #GtkTreeView A #GtkTreePath A #GtkTreeViewColumn, or %NULL A #GtkCellRenderer, or %NULL %TRUE if the specified cell should start being edited. This function should almost never be used. It is meant for private use by ATK for determining the number of visible children that are removed when the user collapses a row, or a row is deleted. Accessibility does not need the function anymore. A #GtkTreeView Function to be called when a view row is destroyed, or %NULL User data to be passed to @func, or %NULL Destroy notifier for @data, or %NULL Sets the row that is highlighted for feedback. If @path is %NULL, an existing highlight is removed. a #GtkTreeView The path of the row to highlight, or %NULL Specifies whether to drop before, after or into the row If @enable_search is set, then the user can type in text to search through the tree interactively (this is sometimes called "typeahead find"). Note that even if this is %FALSE, the user can still initiate a search using the “start-interactive-search” key binding. A #GtkTreeView %TRUE, if the user can search interactively Sets whether to draw lines interconnecting the expanders in @tree_view. This does not have any visible effects for lists. a #GtkTreeView %TRUE to enable tree line drawing, %FALSE otherwise. Sets the column to draw the expander arrow at. It must be in @tree_view. If @column is %NULL, then the expander arrow is always at the first visible column. If you do not want expander arrow to appear in your tree, set the expander column to a hidden column. A #GtkTreeView %NULL, or the column to draw the expander arrow at. Enables or disables the fixed height mode of @tree_view. Fixed height mode speeds up #GtkTreeView by assuming that all rows have the same height. Only enable this option if all rows are the same height and all columns are of type %GTK_TREE_VIEW_COLUMN_FIXED. a #GtkTreeView %TRUE to enable fixed height mode Sets which grid lines to draw in @tree_view. a #GtkTreeView a #GtkTreeViewGridLines value indicating which grid lines to enable. Sets the #GtkAdjustment for the current horizontal aspect. Use gtk_scrollable_set_hadjustment() A #GtkTreeView The #GtkAdjustment to set, or %NULL Allow the column title buttons to be clicked. A #GtkTreeView. %TRUE if the columns are clickable. Sets the visibility state of the headers. A #GtkTreeView. %TRUE if the headers are visible Enables or disables the hover expansion mode of @tree_view. Hover expansion makes rows expand or collapse if the pointer moves over them. a #GtkTreeView %TRUE to enable hover selection mode Enables or disables the hover selection mode of @tree_view. Hover selection makes the selected row follow the pointer. Currently, this works only for the selection modes %GTK_SELECTION_SINGLE and %GTK_SELECTION_BROWSE. a #GtkTreeView %TRUE to enable hover selection mode Sets the amount of extra indentation for child levels to use in @tree_view in addition to the default indentation. The value should be specified in pixels, a value of 0 disables this feature and in this case only the default indentation will be used. This does not have any visible effects for lists. a #GtkTreeView the amount, in pixels, of extra indentation in @tree_view. Sets the model for a #GtkTreeView. If the @tree_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. A #GtkTreeView. The model. This function is a convenience function to allow you to reorder models that support the #GtkTreeDragSourceIface and the #GtkTreeDragDestIface. Both #GtkTreeStore and #GtkListStore support these. If @reorderable is %TRUE, then the user can reorder the model by dragging and dropping rows. The developer can listen to these changes by connecting to the model’s #GtkTreeModel::row-inserted and #GtkTreeModel::row-deleted signals. The reordering is implemented by setting up the tree view as a drag source and destination. Therefore, drag and drop can not be used in a reorderable view for any other purpose. This function does not give you any degree of control over the order -- any reordering is allowed. If more control is needed, you should probably handle drag and drop manually. A #GtkTreeView. %TRUE, if the tree can be reordered. Sets the row separator function, which is used to determine whether a row should be drawn as a separator. If the row separator function is %NULL, no separators are drawn. This is the default value. a #GtkTreeView a #GtkTreeViewRowSeparatorFunc user data to pass to @func, or %NULL destroy notifier for @data, or %NULL Enables or disables rubber banding in @tree_view. If the selection mode is #GTK_SELECTION_MULTIPLE, rubber banding will allow the user to select multiple rows by dragging the mouse. a #GtkTreeView %TRUE to enable rubber banding Sets a hint for the theme to draw even/odd rows in the @tree_view with different colors, also known as "zebra striping". This function tells the GTK+ theme that the user interface for your application requires users to read across tree rows and associate cells with one another. Do not use it just because you prefer the appearance of the ruled tree; that’s a question for the theme. Some themes will draw tree rows in alternating colors even when rules are turned off, and users who prefer that appearance all the time can choose those themes. You should call this function only as a semantic hint to the theme engine that your tree makes alternating colors useful from a functional standpoint (since it has lots of columns, generally). a #GtkTreeView %TRUE if the tree requires reading across rows Sets @column as the column where the interactive search code should search in for the current model. If the search column is set, users can use the “start-interactive-search” key binding to bring up search popup. The enable-search property controls whether simply typing text will also start an interactive search. Note that @column refers to a column of the current model. The search column is reset to -1 when the model is changed. A #GtkTreeView the column of the model to search in, or -1 to disable searching Sets the entry which the interactive search code will use for this @tree_view. This is useful when you want to provide a search entry in our interface at all time at a fixed position. Passing %NULL for @entry will make the interactive search code use the built-in popup entry again. A #GtkTreeView the entry the interactive search code of @tree_view should use or %NULL Sets the compare function for the interactive search capabilities; note that somewhat like strcmp() returning 0 for equality #GtkTreeViewSearchEqualFunc returns %FALSE on matches. A #GtkTreeView the compare function to use during the search user data to pass to @search_equal_func, or %NULL Destroy notifier for @search_user_data, or %NULL Sets the function to use when positioning the search dialog. A #GtkTreeView the function to use to position the search dialog, or %NULL to use the default search position function user data to pass to @func, or %NULL Destroy notifier for @data, or %NULL Sets whether to draw and enable expanders and indent child rows in @tree_view. When disabled there will be no expanders visible in trees and there will be no way to expand and collapse rows by default. Also note that hiding the expanders will disable the default indentation. You can set a custom indentation in this case using gtk_tree_view_set_level_indentation(). This does not have any visible effects for lists. a #GtkTreeView %TRUE to enable expander drawing, %FALSE otherwise. Sets the tip area of @tooltip to the area @path, @column and @cell have in common. For example if @path is %NULL and @column is set, the tip area will be set to the full area covered by @column. See also gtk_tooltip_set_tip_area(). Note that if @path is not specified and @cell is set and part of a column containing the expander, the tooltip might not show and hide at the correct position. In such cases @path must be set to the current node under the mouse cursor for this function to operate correctly. See also gtk_tree_view_set_tooltip_column() for a simpler alternative. a #GtkTreeView a #GtkTooltip a #GtkTreePath or %NULL a #GtkTreeViewColumn or %NULL a #GtkCellRenderer or %NULL If you only plan to have simple (text-only) tooltips on full rows, you can use this function to have #GtkTreeView handle these automatically for you. @column should be set to the column in @tree_view’s model containing the tooltip texts, or -1 to disable this feature. When enabled, #GtkWidget:has-tooltip will be set to %TRUE and @tree_view will connect a #GtkWidget::query-tooltip signal handler. Note that the signal handler sets the text with gtk_tooltip_set_markup(), so &, <, etc have to be escaped in the text. a #GtkTreeView an integer, which is a valid column number for @tree_view’s model Sets the tip area of @tooltip to be the area covered by the row at @path. See also gtk_tree_view_set_tooltip_column() for a simpler alternative. See also gtk_tooltip_set_tip_area(). a #GtkTreeView a #GtkTooltip a #GtkTreePath Sets the #GtkAdjustment for the current vertical aspect. Use gtk_scrollable_set_vadjustment() A #GtkTreeView The #GtkAdjustment to set, or %NULL Undoes the effect of gtk_tree_view_enable_model_drag_dest(). Calling this method sets #GtkTreeView:reorderable to %FALSE. a #GtkTreeView Undoes the effect of gtk_tree_view_enable_model_drag_source(). Calling this method sets #GtkTreeView:reorderable to %FALSE. a #GtkTreeView The activate-on-single-click property specifies whether the "row-activated" signal will be emitted after a single click. Setting the ::fixed-height-mode property to %TRUE speeds up #GtkTreeView by assuming that all rows have the same height. Only enable this option if all rows are the same height. Please see gtk_tree_view_set_fixed_height_mode() for more information on this option. Enables or disables the hover expansion mode of @tree_view. Hover expansion makes rows expand or collapse if the pointer moves over them. This mode is primarily intended for treeviews in popups, e.g. in #GtkComboBox or #GtkEntryCompletion. Enables or disables the hover selection mode of @tree_view. Hover selection makes the selected row follow the pointer. Currently, this works only for the selection modes %GTK_SELECTION_SINGLE and %GTK_SELECTION_BROWSE. This mode is primarily intended for treeviews in popups, e.g. in #GtkComboBox or #GtkEntryCompletion. Extra indentation for each level. Sets a hint to the theme to draw rows in alternating colors. The theme is responsible for drawing rows using zebra striping %TRUE if the view has expanders. The number of columns of the treeview has changed. The position of the cursor (focused cell) has changed. The #GtkTreeView::move-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user presses one of the cursor keys. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. In contrast to gtk_tree_view_set_cursor() and gtk_tree_view_set_cursor_on_cell() when moving horizontally #GtkTreeView::move-cursor does not reset the current selection. %TRUE if @step is supported, %FALSE otherwise. the granularity of the move, as a #GtkMovementStep. %GTK_MOVEMENT_LOGICAL_POSITIONS, %GTK_MOVEMENT_VISUAL_POSITIONS, %GTK_MOVEMENT_DISPLAY_LINES, %GTK_MOVEMENT_PAGES and %GTK_MOVEMENT_BUFFER_ENDS are supported. %GTK_MOVEMENT_LOGICAL_POSITIONS and %GTK_MOVEMENT_VISUAL_POSITIONS are treated identically. the direction to move: +1 to move forwards; -1 to move backwards. The resulting movement is undefined for all other values. The "row-activated" signal is emitted when the method gtk_tree_view_row_activated() is called, when the user double clicks a treeview row with the "activate-on-single-click" property set to %FALSE, or when the user single clicks a row when the "activate-on-single-click" property set to %TRUE. It is also emitted when a non-editable row is selected and one of the keys: Space, Shift+Space, Return or Enter is pressed. For selection handling refer to the [tree widget conceptual overview](TreeWidget.html) as well as #GtkTreeSelection. the #GtkTreePath for the activated row the #GtkTreeViewColumn in which the activation occurred The given row has been collapsed (child nodes are hidden). the tree iter of the collapsed row a tree path that points to the row The given row has been expanded (child nodes are shown). the tree iter of the expanded row a tree path that points to the row The given row is about to be collapsed (hide its children nodes). Use this signal if you need to control the collapsibility of individual rows. %FALSE to allow collapsing, %TRUE to reject the tree iter of the row to collapse a tree path that points to the row The given row is about to be expanded (show its children nodes). Use this signal if you need to control the expandability of individual rows. %FALSE to allow expansion, %TRUE to reject the tree iter of the row to expand a tree path that points to the row A #GtkTreeView The #GtkTreePath to be activated. The #GtkTreeViewColumn to be activated. The GtkTreeViewColumn object represents a visible column in a #GtkTreeView widget. It allows to set properties of the column header, and functions as a holding pen for the cell renderers which determine how the data in the column is displayed. Please refer to the [tree widget conceptual overview](TreeWidget.html) for an overview of all the objects and data types related to the tree widget and how they work together. Creates a new #GtkTreeViewColumn. A newly created #GtkTreeViewColumn. Creates a new #GtkTreeViewColumn using @area to render its cells. A newly created #GtkTreeViewColumn. the #GtkCellArea that the newly created column should use to layout cells. Creates a new #GtkTreeViewColumn with a number of default values. This is equivalent to calling gtk_tree_view_column_set_title(), gtk_tree_view_column_pack_start(), and gtk_tree_view_column_set_attributes() on the newly created #GtkTreeViewColumn. Here’s a simple example: |[<!-- language="C" --> enum { TEXT_COLUMN, COLOR_COLUMN, N_COLUMNS }; // ... { GtkTreeViewColumn *column; GtkCellRenderer *renderer = gtk_cell_renderer_text_new (); column = gtk_tree_view_column_new_with_attributes ("Title", renderer, "text", TEXT_COLUMN, "foreground", COLOR_COLUMN, NULL); } ]| A newly created #GtkTreeViewColumn. The title to set the header to The #GtkCellRenderer A %NULL-terminated list of attributes Emits the “clicked” signal on the column. This function will only work if @tree_column is clickable. a #GtkTreeViewColumn Adds an attribute mapping to the list in @tree_column. The @column is the column of the model to get a value from, and the @attribute is the parameter on @cell_renderer to be set from the value. So for example if column 2 of the model contains strings, you could have the “text” attribute of a #GtkCellRendererText get its values from column 2. A #GtkTreeViewColumn. the #GtkCellRenderer to set attributes on An attribute on the renderer The column position on the model to get the attribute from. Obtains the horizontal position and size of a cell in a column. If the cell is not found in the column, @start_pos and @width are not changed and %FALSE is returned. %TRUE if @cell belongs to @tree_column. a #GtkTreeViewColumn a #GtkCellRenderer return location for the horizontal position of @cell within @tree_column, may be %NULL return location for the width of @cell, may be %NULL Obtains the width and height needed to render the column. This is used primarily by the #GtkTreeView. A #GtkTreeViewColumn. The area a cell in the column will be allocated, or %NULL location to return x offset of a cell relative to @cell_area, or %NULL location to return y offset of a cell relative to @cell_area, or %NULL location to return width needed to render a cell, or %NULL location to return height needed to render a cell, or %NULL Returns %TRUE if any of the cells packed into the @tree_column are visible. For this to be meaningful, you must first initialize the cells with gtk_tree_view_column_cell_set_cell_data() %TRUE, if any of the cells packed into the @tree_column are currently visible A #GtkTreeViewColumn Sets the cell renderer based on the @tree_model and @iter. That is, for every attribute mapping in @tree_column, it will get a value from the set column on the @iter, and use that value to set the attribute on the cell renderer. This is used primarily by the #GtkTreeView. A #GtkTreeViewColumn. The #GtkTreeModel to to get the cell renderers attributes from. The #GtkTreeIter to to get the cell renderer’s attributes from. %TRUE, if the row has children %TRUE, if the row has visible children Unsets all the mappings on all renderers on the @tree_column. A #GtkTreeViewColumn Clears all existing attributes previously set with gtk_tree_view_column_set_attributes(). a #GtkTreeViewColumn a #GtkCellRenderer to clear the attribute mapping on. Emits the “clicked” signal on the column. This function will only work if @tree_column is clickable. a #GtkTreeViewColumn Sets the current keyboard focus to be at @cell, if the column contains 2 or more editable and activatable cells. A #GtkTreeViewColumn A #GtkCellRenderer Returns the current x alignment of @tree_column. This value can range between 0.0 and 1.0. The current alignent of @tree_column. A #GtkTreeViewColumn. Returns the button used in the treeview column header The button for the column header. A #GtkTreeViewColumn Returns %TRUE if the user can click on the header for the column. %TRUE if user can click the column header. a #GtkTreeViewColumn Returns %TRUE if the column expands to fill available space. %TRUE if the column expands to fill available space. A #GtkTreeViewColumn. Gets the fixed width of the column. This may not be the actual displayed width of the column; for that, use gtk_tree_view_column_get_width(). The fixed width of the column. A #GtkTreeViewColumn. Returns the maximum width in pixels of the @tree_column, or -1 if no maximum width is set. The maximum width of the @tree_column. A #GtkTreeViewColumn. Returns the minimum width in pixels of the @tree_column, or -1 if no minimum width is set. The minimum width of the @tree_column. A #GtkTreeViewColumn. Returns %TRUE if the @tree_column can be reordered by the user. %TRUE if the @tree_column can be reordered by the user. A #GtkTreeViewColumn Returns %TRUE if the @tree_column can be resized by the end user. %TRUE, if the @tree_column can be resized. A #GtkTreeViewColumn Returns the current type of @tree_column. The type of @tree_column. A #GtkTreeViewColumn. Gets the logical @sort_column_id that the model sorts on when this column is selected for sorting. See gtk_tree_view_column_set_sort_column_id(). the current @sort_column_id for this column, or -1 if this column can’t be used for sorting. a #GtkTreeViewColumn Gets the value set by gtk_tree_view_column_set_sort_indicator(). whether the sort indicator arrow is displayed a #GtkTreeViewColumn Gets the value set by gtk_tree_view_column_set_sort_order(). the sort order the sort indicator is indicating a #GtkTreeViewColumn Returns the spacing of @tree_column. the spacing of @tree_column. A #GtkTreeViewColumn. Returns the title of the widget. the title of the column. This string should not be modified or freed. A #GtkTreeViewColumn. Returns the #GtkTreeView wherein @tree_column has been inserted. If @column is currently not inserted in any tree view, %NULL is returned. The tree view wherein @column has been inserted if any, %NULL otherwise. A #GtkTreeViewColumn Returns %TRUE if @tree_column is visible. whether the column is visible or not. If it is visible, then the tree will show the column. A #GtkTreeViewColumn. Returns the #GtkWidget in the button on the column header. If a custom widget has not been set then %NULL is returned. The #GtkWidget in the column header, or %NULL A #GtkTreeViewColumn. Returns the current size of @tree_column in pixels. The current width of @tree_column. A #GtkTreeViewColumn. Returns the current X offset of @tree_column in pixels. The current X offset of @tree_column. A #GtkTreeViewColumn. Adds the @cell to end of the column. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. A #GtkTreeViewColumn. The #GtkCellRenderer. %TRUE if @cell is to be given extra space allocated to @tree_column. Packs the @cell into the beginning of the column. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. A #GtkTreeViewColumn. The #GtkCellRenderer. %TRUE if @cell is to be given extra space allocated to @tree_column. Flags the column, and the cell renderers added to this column, to have their sizes renegotiated. A #GtkTreeViewColumn Sets the alignment of the title or custom widget inside the column header. The alignment determines its location inside the button -- 0.0 for left, 0.5 for center, 1.0 for right. A #GtkTreeViewColumn. The alignment, which is between [0.0 and 1.0] inclusive. Sets the attributes in the list as the attributes of @tree_column. The attributes should be in attribute/column order, as in gtk_tree_view_column_add_attribute(). All existing attributes are removed, and replaced with the new attributes. A #GtkTreeViewColumn the #GtkCellRenderer we’re setting the attributes of A %NULL-terminated list of attributes Sets the #GtkTreeCellDataFunc to use for the column. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of @tree_column's cell renderer as appropriate. @func may be %NULL to remove an older one. A #GtkTreeViewColumn A #GtkCellRenderer The #GtkTreeCellDataFunc to use. The user data for @func. The destroy notification for @func_data Sets the header to be active if @clickable is %TRUE. When the header is active, then it can take keyboard focus, and can be clicked. A #GtkTreeViewColumn. %TRUE if the header is active. Sets the column to take available extra space. This space is shared equally amongst all columns that have the expand set to %TRUE. If no column has this option set, then the last column gets all extra space. By default, every column is created with this %FALSE. Along with “fixed-width”, the “expand” property changes when the column is resized by the user. A #GtkTreeViewColumn. %TRUE if the column should expand to fill available space. If @fixed_width is not -1, sets the fixed width of @tree_column; otherwise unsets it. The effective value of @fixed_width is clamped between the minimum and maximum width of the column; however, the value stored in the “fixed-width” property is not clamped. If the column sizing is #GTK_TREE_VIEW_COLUMN_GROW_ONLY or #GTK_TREE_VIEW_COLUMN_AUTOSIZE, setting a fixed width overrides the automatically calculated width. Note that @fixed_width is only a hint to GTK+; the width actually allocated to the column may be greater or less than requested. Along with “expand”, the “fixed-width” property changes when the column is resized by the user. A #GtkTreeViewColumn. The new fixed width, in pixels, or -1. Sets the maximum width of the @tree_column. If @max_width is -1, then the maximum width is unset. Note, the column can actually be wider than max width if it’s the last column in a view. In this case, the column expands to fill any extra space. A #GtkTreeViewColumn. The maximum width of the column in pixels, or -1. Sets the minimum width of the @tree_column. If @min_width is -1, then the minimum width is unset. A #GtkTreeViewColumn. The minimum width of the column in pixels, or -1. If @reorderable is %TRUE, then the column can be reordered by the end user dragging the header. A #GtkTreeViewColumn %TRUE, if the column can be reordered. If @resizable is %TRUE, then the user can explicitly resize the column by grabbing the outer edge of the column button. If resizable is %TRUE and sizing mode of the column is #GTK_TREE_VIEW_COLUMN_AUTOSIZE, then the sizing mode is changed to #GTK_TREE_VIEW_COLUMN_GROW_ONLY. A #GtkTreeViewColumn %TRUE, if the column can be resized Sets the growth behavior of @tree_column to @type. A #GtkTreeViewColumn. The #GtkTreeViewColumnSizing. Sets the logical @sort_column_id that this column sorts on when this column is selected for sorting. Doing so makes the column header clickable. a #GtkTreeViewColumn The @sort_column_id of the model to sort on. Call this function with a @setting of %TRUE to display an arrow in the header button indicating the column is sorted. Call gtk_tree_view_column_set_sort_order() to change the direction of the arrow. a #GtkTreeViewColumn %TRUE to display an indicator that the column is sorted Changes the appearance of the sort indicator. This does not actually sort the model. Use gtk_tree_view_column_set_sort_column_id() if you want automatic sorting support. This function is primarily for custom sorting behavior, and should be used in conjunction with gtk_tree_sortable_set_sort_column_id() to do that. For custom models, the mechanism will vary. The sort indicator changes direction to indicate normal sort or reverse sort. Note that you must have the sort indicator enabled to see anything when calling this function; see gtk_tree_view_column_set_sort_indicator(). a #GtkTreeViewColumn sort order that the sort indicator should indicate Sets the spacing field of @tree_column, which is the number of pixels to place between cell renderers packed into it. A #GtkTreeViewColumn. distance between cell renderers in pixels. Sets the title of the @tree_column. If a custom widget has been set, then this value is ignored. A #GtkTreeViewColumn. The title of the @tree_column. Sets the visibility of @tree_column. A #GtkTreeViewColumn. %TRUE if the @tree_column is visible. Sets the widget in the header to be @widget. If widget is %NULL, then the header button is set with a #GtkLabel set to the title of @tree_column. A #GtkTreeViewColumn. A child #GtkWidget, or %NULL. The #GtkCellArea used to layout cell renderers for this column. If no area is specified when creating the tree view column with gtk_tree_view_column_new_with_area() a horizontally oriented #GtkCellAreaBox will be used. Logical sort column ID this column sorts on when selected for sorting. Setting the sort column ID makes the column header clickable. Set to -1 to make the column unsortable. a #GtkTreeViewColumn Function type for determining whether @column can be dropped in a particular spot (as determined by @prev_column and @next_column). In left to right locales, @prev_column is on the left of the potential drop spot, and @next_column is on the right. In right to left mode, this is reversed. This function should return %TRUE if the spot is a valid drop spot. Please note that returning %TRUE does not actually indicate that the column drop was made, but is meant only to indicate a possible drop spot to the user. %TRUE, if @column can be dropped in this spot A #GtkTreeView The #GtkTreeViewColumn being dragged A #GtkTreeViewColumn on one side of @column A #GtkTreeViewColumn on the other side of @column user data The sizing method the column uses to determine its width. Please note that @GTK_TREE_VIEW_COLUMN_AUTOSIZE are inefficient for large views, and can make columns appear choppy. Columns only get bigger in reaction to changes in the model Columns resize to be the optimal size everytime the model changes. Columns are a fixed numbers of pixels wide. An enum for determining where a dropped row goes. dropped row is inserted before dropped row is inserted after dropped row becomes a child or is inserted before dropped row becomes a child or is inserted after Used to indicate which grid lines to draw in a tree view. No grid lines. Horizontal grid lines. Vertical grid lines. Horizontal and vertical grid lines. Function used for gtk_tree_view_map_expanded_rows(). A #GtkTreeView The path that’s expanded user data Function type for determining whether the row pointed to by @iter should be rendered as a separator. A common way to implement this is to have a boolean column in the model, whose values the #GtkTreeViewRowSeparatorFunc returns. %TRUE if the row is a separator the #GtkTreeModel a #GtkTreeIter pointing at a row in @model user data A function used for checking whether a row in @model matches a search key string entered by the user. Note the return value is reversed from what you would normally expect, though it has some similarity to strcmp() returning 0 for equal strings. %FALSE if the row matches, %TRUE otherwise. the #GtkTreeModel being searched the search column set by gtk_tree_view_set_search_column() the key string to compare with a #GtkTreeIter pointing the row of @model that should be compared with @key. user data from gtk_tree_view_set_search_equal_func() A #GtkUIManager constructs a user interface (menus and toolbars) from one or more UI definitions, which reference actions from one or more action groups. > GtkUIManager is deprecated since GTK+ 3.10. To construct user interfaces > from XML definitions, you should use #GtkBuilder, #GMenuModel, et al. To > work with actions, use #GAction, #GtkActionable et al. These newer classes > support richer functionality and integration with various desktop shells. > It should be possible to migrate most/all functionality from GtkUIManager. # UI Definitions # {#XML-UI} The UI definitions are specified in an XML format which can be roughly described by the following DTD. > Do not confuse the GtkUIManager UI Definitions described here with > the similarly named [GtkBuilder UI Definitions][BUILDER-UI]. |[ <!ELEMENT ui (menubar|toolbar|popup|accelerator)* > <!ELEMENT menubar (menuitem|separator|placeholder|menu)* > <!ELEMENT menu (menuitem|separator|placeholder|menu)* > <!ELEMENT popup (menuitem|separator|placeholder|menu)* > <!ELEMENT toolbar (toolitem|separator|placeholder)* > <!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* > <!ELEMENT menuitem EMPTY > <!ELEMENT toolitem (menu?) > <!ELEMENT separator EMPTY > <!ELEMENT accelerator EMPTY > <!ATTLIST menubar name #IMPLIED action #IMPLIED > <!ATTLIST toolbar name #IMPLIED action #IMPLIED > <!ATTLIST popup name #IMPLIED action #IMPLIED accelerators (true|false) #IMPLIED > <!ATTLIST placeholder name #IMPLIED action #IMPLIED > <!ATTLIST separator name #IMPLIED action #IMPLIED expand (true|false) #IMPLIED > <!ATTLIST menu name #IMPLIED action #REQUIRED position (top|bot) #IMPLIED > <!ATTLIST menuitem name #IMPLIED action #REQUIRED position (top|bot) #IMPLIED always-show-image (true|false) #IMPLIED > <!ATTLIST toolitem name #IMPLIED action #REQUIRED position (top|bot) #IMPLIED > <!ATTLIST accelerator name #IMPLIED action #REQUIRED > ]| There are some additional restrictions beyond those specified in the DTD, e.g. every toolitem must have a toolbar in its anchestry and every menuitem must have a menubar or popup in its anchestry. Since a #GMarkupParser is used to parse the UI description, it must not only be valid XML, but valid markup. If a name is not specified, it defaults to the action. If an action is not specified either, the element name is used. The name and action attributes must not contain “/” characters after parsing (since that would mess up path lookup) and must be usable as XML attributes when enclosed in doublequotes, thus they must not “"” characters or references to the &quot; entity. # A UI definition # |[<!-- language="xml" --> <ui> <menubar> <menu name="FileMenu" action="FileMenuAction"> <menuitem name="New" action="New2Action" /> <placeholder name="FileMenuAdditions" /> </menu> <menu name="JustifyMenu" action="JustifyMenuAction"> <menuitem name="Left" action="justify-left"/> <menuitem name="Centre" action="justify-center"/> <menuitem name="Right" action="justify-right"/> <menuitem name="Fill" action="justify-fill"/> </menu> </menubar> <toolbar action="toolbar1"> <placeholder name="JustifyToolItems"> <separator/> <toolitem name="Left" action="justify-left"/> <toolitem name="Centre" action="justify-center"/> <toolitem name="Right" action="justify-right"/> <toolitem name="Fill" action="justify-fill"/> <separator/> </placeholder> </toolbar> </ui> ]| The constructed widget hierarchy is very similar to the element tree of the XML, with the exception that placeholders are merged into their parents. The correspondence of XML elements to widgets should be almost obvious: - menubar a #GtkMenuBar - toolbar a #GtkToolbar - popup a toplevel #GtkMenu - menu a #GtkMenu attached to a menuitem - menuitem a #GtkMenuItem subclass, the exact type depends on the action - toolitem a #GtkToolItem subclass, the exact type depends on the action. Note that toolitem elements may contain a menu element, but only if their associated action specifies a #GtkMenuToolButton as proxy. - separator a #GtkSeparatorMenuItem or #GtkSeparatorToolItem - accelerator a keyboard accelerator The “position” attribute determines where a constructed widget is positioned wrt. to its siblings in the partially constructed tree. If it is “top”, the widget is prepended, otherwise it is appended. # UI Merging # {#UI-Merging} The most remarkable feature of #GtkUIManager is that it can overlay a set of menuitems and toolitems over another one, and demerge them later. Merging is done based on the names of the XML elements. Each element is identified by a path which consists of the names of its anchestors, separated by slashes. For example, the menuitem named “Left” in the example above has the path `/ui/menubar/JustifyMenu/Left` and the toolitem with the same name has path `/ui/toolbar1/JustifyToolItems/Left`. # Accelerators # Every action has an accelerator path. Accelerators are installed together with menuitem proxies, but they can also be explicitly added with `<accelerator>` elements in the UI definition. This makes it possible to have accelerators for actions even if they have no visible proxies. # Smart Separators # {#Smart-Separators} The separators created by #GtkUIManager are “smart”, i.e. they do not show up in the UI unless they end up between two visible menu or tool items. Separators which are located at the very beginning or end of the menu or toolbar containing them, or multiple separators next to each other, are hidden. This is a useful feature, since the merging of UI elements from multiple sources can make it hard or impossible to determine in advance whether a separator will end up in such an unfortunate position. For separators in toolbars, you can set `expand="true"` to turn them from a small, visible separator to an expanding, invisible one. Toolitems following an expanding separator are effectively right-aligned. # Empty Menus Submenus pose similar problems to separators inconnection with merging. It is impossible to know in advance whether they will end up empty after merging. #GtkUIManager offers two ways to treat empty submenus: - make them disappear by hiding the menu item they’re attached to - add an insensitive “Empty” item The behaviour is chosen based on the “hide_if_empty” property of the action to which the submenu is associated. # GtkUIManager as GtkBuildable # {#GtkUIManager-BUILDER-UI} The GtkUIManager implementation of the GtkBuildable interface accepts GtkActionGroup objects as `<child>` elements in UI definitions. A GtkUIManager UI definition as described above can be embedded in an GtkUIManager `<object>` element in a GtkBuilder UI definition. The widgets that are constructed by a GtkUIManager can be embedded in other parts of the constructed user interface with the help of the “constructor” attribute. See the example below. ## An embedded GtkUIManager UI definition |[<!-- language="xml" --> <object class="GtkUIManager" id="uiman"> <child> <object class="GtkActionGroup" id="actiongroup"> <child> <object class="GtkAction" id="file"> <property name="label">_File</property> </object> </child> </object> </child> <ui> <menubar name="menubar1"> <menu action="file"> </menu> </menubar> </ui> </object> <object class="GtkWindow" id="main-window"> <child> <object class="GtkMenuBar" id="menubar1" constructor="uiman"/> </child> </object> ]| Creates a new ui manager object. a new ui manager object. Looks up an action by following a path. See gtk_ui_manager_get_widget() for more information about paths. the action whose proxy widget is found by following the path, or %NULL if no widget was found. a #GtkUIManager a path Looks up a widget by following a path. The path consists of the names specified in the XML description of the UI. separated by “/”. Elements which don’t have a name or action attribute in the XML (e.g. `<popup>`) can be addressed by their XML element name (e.g. "popup"). The root element ("/ui") can be omitted in the path. Note that the widget found by following a path that ends in a `<menu>`; element is the menuitem to which the menu is attached, not the menu it manages. Also note that the widgets constructed by a ui manager are not tied to the lifecycle of the ui manager. If you add the widgets returned by this function to some container or explicitly ref them, they will survive the destruction of the ui manager. the widget found by following the path, or %NULL if no widget was found a #GtkUIManager a path Adds a UI element to the current contents of @manager. If @type is %GTK_UI_MANAGER_AUTO, GTK+ inserts a menuitem, toolitem or separator if such an element can be inserted at the place determined by @path. Otherwise @type must indicate an element that can be inserted at the place determined by @path. If @path points to a menuitem or toolitem, the new element will be inserted before or after this item, depending on @top. a #GtkUIManager the merge id for the merged UI, see gtk_ui_manager_new_merge_id() a path the name for the added UI element the name of the action to be proxied, or %NULL to add a separator the type of UI element to add. if %TRUE, the UI element is added before its siblings, otherwise it is added after its siblings. Parses a file containing a [UI definition][XML-UI] and merges it with the current contents of @manager. The merge id for the merged UI. The merge id can be used to unmerge the UI with gtk_ui_manager_remove_ui(). If an error occurred, the return value is 0. a #GtkUIManager object the name of the file to parse Parses a resource file containing a [UI definition][XML-UI] and merges it with the current contents of @manager. The merge id for the merged UI. The merge id can be used to unmerge the UI with gtk_ui_manager_remove_ui(). If an error occurred, the return value is 0. a #GtkUIManager object the resource path of the file to parse Parses a string containing a [UI definition][XML-UI] and merges it with the current contents of @manager. An enclosing `<ui>` element is added if it is missing. The merge id for the merged UI. The merge id can be used to unmerge the UI with gtk_ui_manager_remove_ui(). If an error occurred, the return value is 0. a #GtkUIManager object the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) Makes sure that all pending updates to the UI have been completed. This may occasionally be necessary, since #GtkUIManager updates the UI in an idle function. A typical example where this function is useful is to enforce that the menubar and toolbar have been added to the main window before showing it: |[<!-- language="C" --> gtk_container_add (GTK_CONTAINER (window), vbox); g_signal_connect (merge, "add-widget", G_CALLBACK (add_widget), vbox); gtk_ui_manager_add_ui_from_file (merge, "my-menus"); gtk_ui_manager_add_ui_from_file (merge, "my-toolbars"); gtk_ui_manager_ensure_update (merge); gtk_widget_show (window); ]| a #GtkUIManager Returns the #GtkAccelGroup associated with @manager. the #GtkAccelGroup. a #GtkUIManager object Looks up an action by following a path. See gtk_ui_manager_get_widget() for more information about paths. the action whose proxy widget is found by following the path, or %NULL if no widget was found. a #GtkUIManager a path Returns the list of action groups associated with @manager. a #GList of action groups. The list is owned by GTK+ and should not be modified. a #GtkUIManager object Returns whether menus generated by this #GtkUIManager will have tearoff menu items. Tearoff menus are deprecated and should not be used in newly written code. whether tearoff menu items are added a #GtkUIManager Obtains a list of all toplevel widgets of the requested types. a newly-allocated #GSList of all toplevel widgets of the requested types. Free the returned list with g_slist_free(). a #GtkUIManager specifies the types of toplevel widgets to include. Allowed types are #GTK_UI_MANAGER_MENUBAR, #GTK_UI_MANAGER_TOOLBAR and #GTK_UI_MANAGER_POPUP. Creates a [UI definition][XML-UI] of the merged UI. A newly allocated string containing an XML representation of the merged UI. a #GtkUIManager Looks up a widget by following a path. The path consists of the names specified in the XML description of the UI. separated by “/”. Elements which don’t have a name or action attribute in the XML (e.g. `<popup>`) can be addressed by their XML element name (e.g. "popup"). The root element ("/ui") can be omitted in the path. Note that the widget found by following a path that ends in a `<menu>`; element is the menuitem to which the menu is attached, not the menu it manages. Also note that the widgets constructed by a ui manager are not tied to the lifecycle of the ui manager. If you add the widgets returned by this function to some container or explicitly ref them, they will survive the destruction of the ui manager. the widget found by following the path, or %NULL if no widget was found a #GtkUIManager a path Inserts an action group into the list of action groups associated with @manager. Actions in earlier groups hide actions with the same name in later groups. If @pos is larger than the number of action groups in @manager, or negative, @action_group will be inserted at the end of the internal list. a #GtkUIManager object the action group to be inserted the position at which the group will be inserted. Returns an unused merge id, suitable for use with gtk_ui_manager_add_ui(). an unused merge id. a #GtkUIManager Removes an action group from the list of action groups associated with @manager. a #GtkUIManager object the action group to be removed Unmerges the part of @manager's content identified by @merge_id. a #GtkUIManager object a merge id as returned by gtk_ui_manager_add_ui_from_string() Sets the “add_tearoffs” property, which controls whether menus generated by this #GtkUIManager will have tearoff menu items. Note that this only affects regular menus. Generated popup menus never have tearoff menu items. Tearoff menus are deprecated and should not be used in newly written code. a #GtkUIManager whether tearoff menu items are added The "add-tearoffs" property controls whether generated menus have tearoff menu items. Note that this only affects regular menus. Generated popup menus never have tearoff menu items. Tearoff menus are deprecated and should not be used in newly written code. The ::actions-changed signal is emitted whenever the set of actions changes. The ::add-widget signal is emitted for each generated menubar and toolbar. It is not emitted for generated popup menus, which can be obtained by gtk_ui_manager_get_widget(). the added widget The ::connect-proxy signal is emitted after connecting a proxy to an action in the group. This is intended for simple customizations for which a custom action class would be too clumsy, e.g. showing tooltips for menuitems in the statusbar. the action the proxy The ::disconnect-proxy signal is emitted after disconnecting a proxy from an action in the group. the action the proxy The ::post-activate signal is emitted just after the @action is activated. This is intended for applications to get notification just after any action is activated. the action The ::pre-activate signal is emitted just before the @action is activated. This is intended for applications to get notification just before any action is activated. the action the widget found by following the path, or %NULL if no widget was found a #GtkUIManager a path the action whose proxy widget is found by following the path, or %NULL if no widget was found. a #GtkUIManager a path These enumeration values are used by gtk_ui_manager_add_ui() to determine what UI element to create. Pick the type of the UI element according to context. Create a menubar. Create a menu. Create a toolbar. Insert a placeholder. Create a popup menu. Create a menuitem. Create a toolitem. Create a separator. Install an accelerator. Same as %GTK_UI_MANAGER_POPUP, but the actions’ accelerators are shown. See also gtk_print_settings_set_paper_width(). No units. Dimensions in points. Dimensions in inches. Dimensions in millimeters A #GtkVBox is a container that organizes child widgets into a single column. Use the #GtkBox packing interface to determine the arrangement, spacing, height, and alignment of #GtkVBox children. All children are allocated the same width. GtkVBox has been deprecated. You can use #GtkBox with a #GtkOrientable:orientation set to %GTK_ORIENTATION_VERTICAL instead when calling gtk_box_new(), which is a very quick and easy change. If you have derived your own classes from GtkVBox, you can change the inheritance to derive directly from #GtkBox, and set the #GtkOrientable:orientation property to %GTK_ORIENTATION_VERTICAL in your instance init function, with a call like: |[<!-- language="C" --> gtk_orientable_set_orientation (GTK_ORIENTABLE (object), GTK_ORIENTATION_VERTICAL); ]| If you have a grid-like layout composed of nested boxes, and you don’t need first-child or last-child styling, the recommendation is to switch to #GtkGrid. For more information about migrating to #GtkGrid, see [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid]. Creates a new #GtkVBox. You should use gtk_box_new() with a %GTK_ORIENTATION_VERTICAL #GtkOrientable:orientation instead a new #GtkVBox. %TRUE if all children are to be given equal space allotments. the number of pixels to place by default between children. Creates a new vertical button box. Use gtk_button_box_new() with %GTK_ORIENTATION_VERTICAL instead a new button box #GtkWidget. The VPaned widget is a container widget with two children arranged vertically. The division between the two panes is adjustable by the user by dragging a handle. See #GtkPaned for details. GtkVPaned has been deprecated, use #GtkPaned instead. Create a new #GtkVPaned Use gtk_paned_new() with %GTK_ORIENTATION_VERTICAL instead the new #GtkVPaned The #GtkVScale widget is used to allow the user to select a value using a vertical slider. To create one, use gtk_hscale_new_with_range(). The position to show the current value, and the number of decimal places shown can be set using the parent #GtkScale class’s functions. GtkVScale has been deprecated, use #GtkScale instead. Creates a new #GtkVScale. Use gtk_scale_new() with %GTK_ORIENTATION_VERTICAL instead a new #GtkVScale. the #GtkAdjustment which sets the range of the scale. Creates a new vertical scale widget that lets the user input a number between @min and @max (including @min and @max) with the increment @step. @step must be nonzero; it’s the distance the slider moves when using the arrow keys to adjust the scale value. Note that the way in which the precision is derived works best if @step is a power of ten. If the resulting precision is not suitable for your needs, use gtk_scale_set_digits() to correct it. Use gtk_scale_new_with_range() with %GTK_ORIENTATION_VERTICAL instead a new #GtkVScale minimum value maximum value step increment (tick size) used with keyboard shortcuts The #GtkVScrollbar widget is a widget arranged vertically creating a scrollbar. See #GtkScrollbar for details on scrollbars. #GtkAdjustment pointers may be added to handle the adjustment of the scrollbar or it may be left %NULL in which case one will be created for you. See #GtkScrollbar for a description of what the fields in an adjustment represent for a scrollbar. GtkVScrollbar has been deprecated, use #GtkScrollbar instead. Creates a new vertical scrollbar. Use gtk_scrollbar_new() with %GTK_ORIENTATION_VERTICAL instead the new #GtkVScrollbar the #GtkAdjustment to use, or %NULL to create a new adjustment The #GtkVSeparator widget is a vertical separator, used to group the widgets within a window. It displays a vertical line with a shadow to make it appear sunken into the interface. GtkVSeparator has been deprecated, use #GtkSeparator instead. Creates a new #GtkVSeparator. Use gtk_separator_new() with %GTK_ORIENTATION_VERTICAL instead a new #GtkVSeparator. The #GtkViewport widget acts as an adaptor class, implementing scrollability for child widgets that lack their own scrolling capabilities. Use GtkViewport to scroll child widgets such as #GtkGrid, #GtkBox, and so on. If a widget has native scrolling abilities, such as #GtkTextView, #GtkTreeView or #GtkIconView, it can be added to a #GtkScrolledWindow with gtk_container_add(). If a widget does not, you must first add the widget to a #GtkViewport, then add the viewport to the scrolled window. gtk_container_add() does this automatically if a child that does not implement #GtkScrollable is added to a #GtkScrolledWindow, so you can ignore the presence of the viewport. The GtkViewport will start scrolling content only if allocated less than the child widget’s minimum size in a given orientation. # CSS nodes GtkViewport has a single CSS node with name viewport. Creates a new #GtkViewport with the given adjustments, or with default adjustments if none are given. a new #GtkViewport horizontal adjustment vertical adjustment Gets the bin window of the #GtkViewport. a #GdkWindow a #GtkViewport Returns the horizontal adjustment of the viewport. Use gtk_scrollable_get_hadjustment() the horizontal adjustment of @viewport. a #GtkViewport. Gets the shadow type of the #GtkViewport. See gtk_viewport_set_shadow_type(). the shadow type a #GtkViewport Returns the vertical adjustment of the viewport. Use gtk_scrollable_get_vadjustment() the vertical adjustment of @viewport. a #GtkViewport. Gets the view window of the #GtkViewport. a #GdkWindow a #GtkViewport Sets the horizontal adjustment of the viewport. Use gtk_scrollable_set_hadjustment() a #GtkViewport. a #GtkAdjustment. Sets the shadow type of the viewport. a #GtkViewport. the new shadow type. Sets the vertical adjustment of the viewport. Use gtk_scrollable_set_vadjustment() a #GtkViewport. a #GtkAdjustment. The parent class. #GtkVolumeButton is a subclass of #GtkScaleButton that has been tailored for use as a volume control widget with suitable icons, tooltips and accessible labels. Creates a #GtkVolumeButton, with a range between 0.0 and 1.0, with a stepping of 0.02. Volume values can be obtained and modified using the functions from #GtkScaleButton. a new #GtkVolumeButton Whether to use symbolic icons as the icons. Note that if the symbolic icons are not available in your installed theme, then the normal (potentially colorful) icons will be used. GtkWidget is the base class all widgets in GTK+ derive from. It manages the widget lifecycle, states and style. # Height-for-width Geometry Management # {#geometry-management} GTK+ uses a height-for-width (and width-for-height) geometry management system. Height-for-width means that a widget can change how much vertical space it needs, depending on the amount of horizontal space that it is given (and similar for width-for-height). The most common example is a label that reflows to fill up the available width, wraps to fewer lines, and therefore needs less height. Height-for-width geometry management is implemented in GTK+ by way of five virtual methods: - #GtkWidgetClass.get_request_mode() - #GtkWidgetClass.get_preferred_width() - #GtkWidgetClass.get_preferred_height() - #GtkWidgetClass.get_preferred_height_for_width() - #GtkWidgetClass.get_preferred_width_for_height() - #GtkWidgetClass.get_preferred_height_and_baseline_for_width() There are some important things to keep in mind when implementing height-for-width and when using it in container implementations. The geometry management system will query a widget hierarchy in only one orientation at a time. When widgets are initially queried for their minimum sizes it is generally done in two initial passes in the #GtkSizeRequestMode chosen by the toplevel. For example, when queried in the normal %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH mode: First, the default minimum and natural width for each widget in the interface will be computed using gtk_widget_get_preferred_width(). Because the preferred widths for each container depend on the preferred widths of their children, this information propagates up the hierarchy, and finally a minimum and natural width is determined for the entire toplevel. Next, the toplevel will use the minimum width to query for the minimum height contextual to that width using gtk_widget_get_preferred_height_for_width(), which will also be a highly recursive operation. The minimum height for the minimum width is normally used to set the minimum size constraint on the toplevel (unless gtk_window_set_geometry_hints() is explicitly used instead). After the toplevel window has initially requested its size in both dimensions it can go on to allocate itself a reasonable size (or a size previously specified with gtk_window_set_default_size()). During the recursive allocation process it’s important to note that request cycles will be recursively executed while container widgets allocate their children. Each container widget, once allocated a size, will go on to first share the space in one orientation among its children and then request each child's height for its target allocated width or its width for allocated height, depending. In this way a #GtkWidget will typically be requested its size a number of times before actually being allocated a size. The size a widget is finally allocated can of course differ from the size it has requested. For this reason, #GtkWidget caches a small number of results to avoid re-querying for the same sizes in one allocation cycle. See [GtkContainer’s geometry management section][container-geometry-management] to learn more about how height-for-width allocations are performed by container widgets. If a widget does move content around to intelligently use up the allocated size then it must support the request in both #GtkSizeRequestModes even if the widget in question only trades sizes in a single orientation. For instance, a #GtkLabel that does height-for-width word wrapping will not expect to have #GtkWidgetClass.get_preferred_height() called because that call is specific to a width-for-height request. In this case the label must return the height required for its own minimum possible width. By following this rule any widget that handles height-for-width or width-for-height requests will always be allocated at least enough space to fit its own content. Here are some examples of how a %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH widget generally deals with width-for-height requests, for #GtkWidgetClass.get_preferred_height() it will do: |[<!-- language="C" --> static void foo_widget_get_preferred_height (GtkWidget *widget, gint *min_height, gint *nat_height) { if (i_am_in_height_for_width_mode) { gint min_width, nat_width; GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget, &min_width, &nat_width); GTK_WIDGET_GET_CLASS (widget)->get_preferred_height_for_width (widget, min_width, min_height, nat_height); } else { ... some widgets do both. For instance, if a GtkLabel is rotated to 90 degrees it will return the minimum and natural height for the rotated label here. } } ]| And in #GtkWidgetClass.get_preferred_width_for_height() it will simply return the minimum and natural width: |[<!-- language="C" --> static void foo_widget_get_preferred_width_for_height (GtkWidget *widget, gint for_height, gint *min_width, gint *nat_width) { if (i_am_in_height_for_width_mode) { GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget, min_width, nat_width); } else { ... again if a widget is sometimes operating in width-for-height mode (like a rotated GtkLabel) it can go ahead and do its real width for height calculation here. } } ]| Often a widget needs to get its own request during size request or allocation. For example, when computing height it may need to also compute width. Or when deciding how to use an allocation, the widget may need to know its natural size. In these cases, the widget should be careful to call its virtual methods directly, like this: |[<!-- language="C" --> GTK_WIDGET_GET_CLASS(widget)->get_preferred_width (widget, &min, &natural); ]| It will not work to use the wrapper functions, such as gtk_widget_get_preferred_width() inside your own size request implementation. These return a request adjusted by #GtkSizeGroup and by the #GtkWidgetClass.adjust_size_request() virtual method. If a widget used the wrappers inside its virtual method implementations, then the adjustments (such as widget margins) would be applied twice. GTK+ therefore does not allow this and will warn if you try to do it. Of course if you are getting the size request for another widget, such as a child of a container, you must use the wrapper APIs. Otherwise, you would not properly consider widget margins, #GtkSizeGroup, and so forth. Since 3.10 GTK+ also supports baseline vertical alignment of widgets. This means that widgets are positioned such that the typographical baseline of widgets in the same row are aligned. This happens if a widget supports baselines, has a vertical alignment of %GTK_ALIGN_BASELINE, and is inside a container that supports baselines and has a natural “row” that it aligns to the baseline, or a baseline assigned to it by the grandparent. Baseline alignment support for a widget is done by the #GtkWidgetClass.get_preferred_height_and_baseline_for_width() virtual function. It allows you to report a baseline in combination with the minimum and natural height. If there is no baseline you can return -1 to indicate this. The default implementation of this virtual function calls into the #GtkWidgetClass.get_preferred_height() and #GtkWidgetClass.get_preferred_height_for_width(), so if baselines are not supported it doesn’t need to be implemented. If a widget ends up baseline aligned it will be allocated all the space in the parent as if it was %GTK_ALIGN_FILL, but the selected baseline can be found via gtk_widget_get_allocated_baseline(). If this has a value other than -1 you need to align the widget such that the baseline appears at the position. # Style Properties #GtkWidget introduces “style properties” - these are basically object properties that are stored not on the object, but in the style object associated to the widget. Style properties are set in [resource files][gtk3-Resource-Files]. This mechanism is used for configuring such things as the location of the scrollbar arrows through the theme, giving theme authors more control over the look of applications without the need to write a theme engine in C. Use gtk_widget_class_install_style_property() to install style properties for a widget class, gtk_widget_class_find_style_property() or gtk_widget_class_list_style_properties() to get information about existing style properties and gtk_widget_style_get_property(), gtk_widget_style_get() or gtk_widget_style_get_valist() to obtain the value of a style property. # GtkWidget as GtkBuildable The GtkWidget implementation of the GtkBuildable interface supports a custom `<accelerator>` element, which has attributes named ”key”, ”modifiers” and ”signal” and allows to specify accelerators. An example of a UI definition fragment specifying an accelerator: |[<!-- language="xml" --> <object class="GtkButton"> <accelerator key="q" modifiers="GDK_CONTROL_MASK" signal="clicked"/> </object> ]| In addition to accelerators, GtkWidget also support a custom `<accessible>` element, which supports actions and relations. Properties on the accessible implementation of an object can be set by accessing the internal child “accessible” of a #GtkWidget. An example of a UI definition fragment specifying an accessible: |[<!-- language="xml" --> <object class="GtkLabel" id="label1"/> <property name="label">I am a Label for a Button</property> </object> <object class="GtkButton" id="button1"> <accessibility> <action action_name="click" translatable="yes">Click the button.</action> <relation target="label1" type="labelled-by"/> </accessibility> <child internal-child="accessible"> <object class="AtkObject" id="a11y-button1"> <property name="accessible-name">Clickable Button</property> </object> </child> </object> ]| Finally, GtkWidget allows style information such as style classes to be associated with widgets, using the custom `<style>` element: |[<!-- language="xml" --> <object class="GtkButton" id="button1"> <style> <class name="my-special-button-class"/> <class name="dark-button"/> </style> </object> ]| # Building composite widgets from template XML ## {#composite-templates} GtkWidget exposes some facilities to automate the procedure of creating composite widgets using #GtkBuilder interface description language. To create composite widgets with #GtkBuilder XML, one must associate the interface description with the widget class at class initialization time using gtk_widget_class_set_template(). The interface description semantics expected in composite template descriptions is slightly different from regular #GtkBuilder XML. Unlike regular interface descriptions, gtk_widget_class_set_template() will expect a `<template>` tag as a direct child of the toplevel `<interface>` tag. The `<template>` tag must specify the “class” attribute which must be the type name of the widget. Optionally, the “parent” attribute may be specified to specify the direct parent type of the widget type, this is ignored by the GtkBuilder but required for Glade to introspect what kind of properties and internal children exist for a given type when the actual type does not exist. The XML which is contained inside the `<template>` tag behaves as if it were added to the `<object>` tag defining "widget" itself. You may set properties on @widget by inserting `<property>` tags into the `<template>` tag, and also add `<child>` tags to add children and extend "widget" in the normal way you would with `<object>` tags. Additionally, `<object>` tags can also be added before and after the initial `<template>` tag in the normal way, allowing one to define auxiliary objects which might be referenced by other widgets declared as children of the `<template>` tag. An example of a GtkBuilder Template Definition: |[<!-- language="xml" --> <interface> <template class="FooWidget" parent="GtkBox"> <property name="orientation">GTK_ORIENTATION_HORIZONTAL</property> <property name="spacing">4</property> <child> <object class="GtkButton" id="hello_button"> <property name="label">Hello World</property> <signal name="clicked" handler="hello_button_clicked" object="FooWidget" swapped="yes"/> </object> </child> <child> <object class="GtkButton" id="goodbye_button"> <property name="label">Goodbye World</property> </object> </child> </template> </interface> ]| Typically, you'll place the template fragment into a file that is bundled with your project, using #GResource. In order to load the template, you need to call gtk_widget_class_set_template_from_resource() from the class initialization of your #GtkWidget type: |[<!-- language="C" --> static void foo_widget_class_init (FooWidgetClass *klass) { // ... gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass), "/com/example/ui/foowidget.ui"); } ]| You will also need to call gtk_widget_init_template() from the instance initialization function: |[<!-- language="C" --> static void foo_widget_init (FooWidget *self) { // ... gtk_widget_init_template (GTK_WIDGET (self)); } ]| You can access widgets defined in the template using the gtk_widget_get_template_child() function, but you will typically declare a pointer in the instance private data structure of your type using the same name as the widget in the template definition, and call gtk_widget_class_bind_template_child_private() with that name, e.g. |[<!-- language="C" --> typedef struct { GtkWidget *hello_button; GtkWidget *goodbye_button; } FooWidgetPrivate; G_DEFINE_TYPE_WITH_PRIVATE (FooWidget, foo_widget, GTK_TYPE_BOX) static void foo_widget_class_init (FooWidgetClass *klass) { // ... gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass), "/com/example/ui/foowidget.ui"); gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (klass), FooWidget, hello_button); gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (klass), FooWidget, goodbye_button); } static void foo_widget_init (FooWidget *widget) { } ]| You can also use gtk_widget_class_bind_template_callback() to connect a signal callback defined in the template with a function visible in the scope of the class, e.g. |[<!-- language="C" --> // the signal handler has the instance and user data swapped // because of the swapped="yes" attribute in the template XML static void hello_button_clicked (FooWidget *self, GtkButton *button) { g_print ("Hello, world!\n"); } static void foo_widget_class_init (FooWidgetClass *klass) { // ... gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass), "/com/example/ui/foowidget.ui"); gtk_widget_class_bind_template_callback (GTK_WIDGET_CLASS (klass), hello_button_clicked); } ]| This is a convenience function for creating a widget and setting its properties in one go. For example you might write: `gtk_widget_new (GTK_TYPE_LABEL, "label", "Hello World", "xalign", 0.0, NULL)` to create a left-aligned label. Equivalent to g_object_new(), but returns a widget so you don’t have to cast the object yourself. a new #GtkWidget of type @widget_type type ID of the widget to create name of first property to set value of first property, followed by more properties, %NULL-terminated Obtains the current default reading direction. See gtk_widget_set_default_direction(). the current default direction. Returns the default style used by all widgets initially. Use #GtkStyleContext instead, and gtk_css_provider_get_default() to obtain a #GtkStyleProvider with the default widget style information. the default style. This #GtkStyle object is owned by GTK+ and should not be modified or freed. Cancels the effect of a previous call to gtk_widget_push_composite_child(). Use gtk_widget_class_set_template(), or don’t use this API at all. Makes all newly-created widgets as composite children until the corresponding gtk_widget_pop_composite_child() call. A composite child is a child that’s an implementation detail of the container it’s inside and should not be visible to people using the container. Composite children aren’t treated differently by GTK+ (but see gtk_container_foreach() vs. gtk_container_forall()), but e.g. GUI builders might want to treat them in a different way. This API never really worked well and was mostly unused, now we have a more complete mechanism for composite children, see gtk_widget_class_set_template(). Sets the default reading direction for widgets where the direction has not been explicitly set by gtk_widget_set_direction(). the new default direction. This cannot be %GTK_TEXT_DIR_NONE. Convert an initial size allocation assigned by a #GtkContainer using gtk_widget_size_allocate(), into an actual size allocation to be used by the widget. adjust_size_allocation adjusts to a child widget’s actual allocation from what a parent container computed for the child. The adjusted allocation must be entirely within the original allocation. In any custom implementation, chain up to the default #GtkWidget implementation of this method, which applies the margin and alignment properties of #GtkWidget. Chain up before performing your own adjustments so your own adjustments remove more allocation after the #GtkWidget base class has already removed margin and alignment. The natural size passed in should be adjusted in the same way as the allocated size, which allows adjustments to perform alignments or other changes based on natural size. Convert an initial size request from a widget's #GtkSizeRequestMode virtual method implementations into a size request to be used by parent containers in laying out the widget. adjust_size_request adjusts from a child widget's original request to what a parent container should use for layout. The @for_size argument will be -1 if the request should not be for a particular size in the opposing orientation, i.e. if the request is not height-for-width or width-for-height. If @for_size is greater than -1, it is the proposed allocation in the opposing orientation that we need the request for. Implementations of adjust_size_request should chain up to the default implementation, which applies #GtkWidget’s margin properties and imposes any values from gtk_widget_set_size_request(). Chaining up should be last, after your subclass adjusts the request, so #GtkWidget can apply constraints and add the margin properly. Signal will be emitted when a button (typically from a mouse) is pressed. Signal will be emitted when a button (typically from a mouse) is released. Determines whether an accelerator that activates the signal identified by @signal_id can currently be activated. This is done by emitting the #GtkWidget::can-activate-accel signal on @widget; if the signal isn’t overridden by a handler or in a derived widget, then the default check is that the widget must be sensitive, and the widget and all its ancestors mapped. %TRUE if the accelerator can be activated. a #GtkWidget the ID of a signal installed on @widget Emits a #GtkWidget::child-notify signal for the [child property][child-properties] @child_property on @widget. This is the analogue of g_object_notify() for child properties. Also see gtk_container_child_notify(). a #GtkWidget the name of a child property installed on the class of @widget’s parent Signal emitted when the composited status of widgets screen changes. See gdk_screen_is_composited(). Computes whether a container should give this widget extra space when possible. Signal will be emitted when the size, position or stacking of the widget’s window has changed. Signal emitted when a redirected window belonging to widget gets drawn into. Signal emitted if a user requests that a toplevel window is closed. Destroys a widget. When a widget is destroyed all references it holds on other objects will be released: - if the widget is inside a container, it will be removed from its parent - if the widget is a container, all its children will be destroyed, recursively - if the widget is a top level, it will be removed from the list of top level widgets that GTK+ maintains internally It's expected that all references held on the widget will also be released; you should connect to the #GtkWidget::destroy signal if you hold a reference to @widget and you wish to remove it when this function is called. It is not necessary to do so if you are implementing a #GtkContainer, as you'll be able to use the #GtkContainerClass.remove() virtual function for that. It's important to notice that gtk_widget_destroy() will only cause the @widget to be finalized if no additional references, acquired using g_object_ref(), are held on it. In case additional references are in place, the @widget will be in an "inert" state after calling this function; @widget will still point to valid memory, allowing you to release the references you hold, but you may not query the widget's own state. You should typically call this function on top level widgets, and rarely on child widgets. See also: gtk_container_remove() a #GtkWidget Signal is emitted when a #GdkWindow is destroyed. Signal emitted when the text direction of a widget changes. Seldomly overidden. Signal emitted on the drag source when a drag is started. Signal emitted on the drag source when a drag with the action %GDK_ACTION_MOVE is successfully completed. Signal emitted on the drag source when the drop site requests the data which is dragged. Signal emitted on the drop site when the dragged data has been received. Signal emitted on the drop site when the user drops the data onto the widget. Signal emitted on the drag source when a drag is finished. Signal emitted on the drag source when a drag has failed. Signal emitted on the drop site when the cursor leaves the widget. signal emitted on the drop site when the user moves the cursor over the widget during a drag. Signal emitted when a widget is supposed to render itself. Signal event will be emitted when the pointer enters the widget’s window. Rarely-used function. This function is used to emit the event signals on a widget (those signals should never be emitted without using this function to do so). If you want to synthesize an event though, don’t use this function; instead, use gtk_main_do_event() so the event will behave as if it were in the event queue. Don’t synthesize expose events; instead, use gdk_window_invalidate_rect() to invalidate a region of the window. return from the event signal emission (%TRUE if the event was handled) a #GtkWidget a #GdkEvent Signal emitted when the keyboard focus enters the widget’s window. Signal emitted when the keyboard focus leaves the widget’s window. Returns the accessible object that describes the widget to an assistive technology. If accessibility support is not available, this #AtkObject instance may be a no-op. Likewise, if no class-specific #AtkObject implementation is available for the widget instance in question, it will inherit an #AtkObject implementation from the first ancestor class for which such an implementation is defined. The documentation of the [ATK](http://developer.gnome.org/atk/stable/) library contains more information about accessible objects and their uses. the #AtkObject associated with @widget a #GtkWidget Retrieves a widget’s initial minimum and natural height. This call is specific to width-for-height requests. The returned request will be modified by the GtkWidgetClass::adjust_size_request virtual method and by any #GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself. a #GtkWidget instance location to store the minimum height, or %NULL location to store the natural height, or %NULL Retrieves a widget’s minimum and natural height and the corresponding baselines if it would be given the specified @width, or the default height if @width is -1. The baselines may be -1 which means that no baseline is requested for this widget. The returned request will be modified by the GtkWidgetClass::adjust_size_request and GtkWidgetClass::adjust_baseline_request virtual methods and by any #GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself. a #GtkWidget instance the width which is available for allocation, or -1 if none location for storing the minimum height, or %NULL location for storing the natural height, or %NULL location for storing the baseline for the minimum height, or %NULL location for storing the baseline for the natural height, or %NULL Retrieves a widget’s minimum and natural height if it would be given the specified @width. The returned request will be modified by the GtkWidgetClass::adjust_size_request virtual method and by any #GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself. a #GtkWidget instance the width which is available for allocation location for storing the minimum height, or %NULL location for storing the natural height, or %NULL Retrieves a widget’s initial minimum and natural width. This call is specific to height-for-width requests. The returned request will be modified by the GtkWidgetClass::adjust_size_request virtual method and by any #GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself. a #GtkWidget instance location to store the minimum width, or %NULL location to store the natural width, or %NULL Retrieves a widget’s minimum and natural width if it would be given the specified @height. The returned request will be modified by the GtkWidgetClass::adjust_size_request virtual method and by any #GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself. a #GtkWidget instance the height which is available for allocation location for storing the minimum width, or %NULL location for storing the natural width, or %NULL Gets whether the widget prefers a height-for-width layout or a width-for-height layout. #GtkBin widgets generally propagate the preference of their child, container widgets need to request something either in context of their children or in context of their allocation capabilities. The #GtkSizeRequestMode preferred by @widget. a #GtkWidget instance Signal emitted when a pointer or keyboard grab on a window belonging to widget gets broken. Causes @widget to have the keyboard focus for the #GtkWindow it's inside. @widget must be a focusable widget, such as a #GtkEntry; something like #GtkFrame won’t work. More precisely, it must have the %GTK_CAN_FOCUS flag set. Use gtk_widget_set_can_focus() to modify that flag. The widget also needs to be realized and mapped. This is indicated by the related signals. Grabbing the focus immediately after creating the widget will likely fail and cause critical warnings. a #GtkWidget Signal emitted when a widget becomes shadowed by a GTK+ grab (not a pointer or keyboard grab) on another widget, or when it becomes unshadowed due to a grab being removed. Reverses the effects of gtk_widget_show(), causing the widget to be hidden (invisible to the user). a #GtkWidget Signal emitted when the anchored state of a widget changes. Signal emitted when a key is pressed. Signal is emitted when a key is released. This function should be called whenever keyboard navigation within a single widget hits a boundary. The function emits the #GtkWidget::keynav-failed signal on the widget and its return value should be interpreted in a way similar to the return value of gtk_widget_child_focus(): When %TRUE is returned, stay in the widget, the failed keyboard navigation is OK and/or there is nowhere we can/should move the focus to. When %FALSE is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling gtk_widget_child_focus() on the widget’s toplevel. The default ::keynav-failed handler returns %FALSE for %GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. For the other values of #GtkDirectionType it returns %TRUE. Whenever the default handler returns %TRUE, it also calls gtk_widget_error_bell() to notify the user of the failed keyboard navigation. A use case for providing an own implementation of ::keynav-failed (either by connecting to it or by overriding it) would be a row of #GtkEntry widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys. %TRUE if stopping keyboard navigation is fine, %FALSE if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s). a #GtkWidget direction of focus movement Will be emitted when the pointer leaves the widget’s window. This function is only for use in widget implementations. Causes a widget to be mapped if it isn’t already. a #GtkWidget Signal emitted when the widget’s window is mapped. Emits the #GtkWidget::mnemonic-activate signal. %TRUE if the signal has been handled a #GtkWidget %TRUE if there are other widgets with the same mnemonic Signal emitted when the pointer moves over the widget’s #GdkWindow. Signal emitted when a change of focus is requested Signal emitted when a new parent has been set on a widget. Signal emitted whenever a widget should pop up a context menu. Signal will be emitted when a property on the widget’s window has been changed or deleted. Signal emitted when “has-tooltip” is %TRUE and the hover timeout has expired with the cursor hovering “above” widget; or emitted when widget got focus in keyboard mode. Invalidates the area of @widget defined by @region by calling gdk_window_invalidate_region() on the widget’s window and all its child windows. Once the main loop becomes idle (after the current batch of events has been processed, roughly), the window will receive expose events for the union of all regions that have been invalidated. Normally you would only use this function in widget implementations. You might also use it to schedule a redraw of a #GtkDrawingArea or some portion thereof. a #GtkWidget region to draw Creates the GDK (windowing system) resources associated with a widget. For example, @widget->window will be created when a widget is realized. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped automatically. Realizing a widget requires all the widget’s parent widgets to be realized; calling gtk_widget_realize() realizes the widget’s parents in addition to @widget itself. If a widget is not yet inside a toplevel window when you realize it, bad things will happen. This function is primarily used in widget implementations, and isn’t very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as #GtkWidget::draw. Or simply g_signal_connect () to the #GtkWidget::realize signal. a #GtkWidget Signal emitted when the screen of a widget has changed. Signal emitted when a button in the 4 to 7 range is pressed. Signal will be emitted when the the widget’s window has lost ownership of a selection. Signal will be emitted when another client requests ownership of the selection owned by the widget's window. Flags a widget to be displayed. Any widget that isn’t shown will not appear on the screen. If you want to show all the widgets in a container, it’s easier to call gtk_widget_show_all() on the container, instead of individually showing the widgets. Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen. When a toplevel container is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their toplevel container is realized and mapped. a #GtkWidget Recursively shows a widget, and any child widgets (if the widget is a container). a #GtkWidget This function is only used by #GtkContainer subclasses, to assign a size and position to their child widgets. In this function, the allocation may be adjusted. It will be forced to a 1x1 minimum size, and the adjust_size_allocation virtual method on the child will be used to adjust the allocation. Standard adjustments include removing the widget’s margins, and applying the widget’s #GtkWidget:halign and #GtkWidget:valign properties. For baseline support in containers you need to use gtk_widget_size_allocate_with_baseline() instead. a #GtkWidget position and size to be allocated to @widget Signal emitted when the widget state changes. Deprecated: 3.0 Signal emitted when the widget state changes, see gtk_widget_get_state_flags(). Signal emitted when a new style has been set on a widget. Deprecated: 3.0 Signal emitted when the GtkStyleContext of a widget is changed. Signal emitted when a touch event happens This function is only for use in widget implementations. Causes a widget to be unmapped if it’s currently mapped. a #GtkWidget Signal will be emitted when the widget’s window is unmapped. This function is only useful in widget implementations. Causes a widget to be unrealized (frees all GDK resources associated with the widget, such as @widget->window). a #GtkWidget Signal emitted when the widget’s window is obscured or unobscured. Signal emitted when the state of the toplevel window associated to the widget changes. For widgets that can be “activated” (buttons, menu items, etc.) this function activates them. Activation is what happens when you press Enter on a widget during key navigation. If @widget isn't activatable, the function returns %FALSE. %TRUE if the widget was activatable a #GtkWidget that’s activatable Installs an accelerator for this @widget in @accel_group that causes @accel_signal to be emitted if the accelerator is activated. The @accel_group needs to be added to the widget’s toplevel via gtk_window_add_accel_group(), and the signal must be of type %G_SIGNAL_ACTION. Accelerators added through this function are not user changeable during runtime. If you want to support accelerators that can be changed by the user, use gtk_accel_map_add_entry() and gtk_widget_set_accel_path() or gtk_menu_item_set_accel_path() instead. widget to install an accelerator on widget signal to emit on accelerator activation accel group for this widget, added to its toplevel GDK keyval of the accelerator modifier key combination of the accelerator flag accelerators, e.g. %GTK_ACCEL_VISIBLE Adds the device events in the bitfield @events to the event mask for @widget. See gtk_widget_set_device_events() for details. a #GtkWidget a #GdkDevice an event mask, see #GdkEventMask Adds the events in the bitfield @events to the event mask for @widget. See gtk_widget_set_events() and the [input handling overview][event-masks] for details. a #GtkWidget an event mask, see #GdkEventMask Adds a widget to the list of mnemonic labels for this widget. (See gtk_widget_list_mnemonic_labels()). Note the list of mnemonic labels for the widget is cleared when the widget is destroyed, so the caller must make sure to update its internal state at this point as well, by using a connection to the #GtkWidget::destroy signal or a weak notifier. a #GtkWidget a #GtkWidget that acts as a mnemonic label for @widget Queues an animation frame update and adds a callback to be called before each frame. Until the tick callback is removed, it will be called frequently (usually at the frame rate of the output device or as quickly as the application can be repainted, whichever is slower). For this reason, is most suitable for handling graphics that change every frame or every few frames. The tick callback does not automatically imply a relayout or repaint. If you want a repaint or relayout, and aren’t changing widget properties that would trigger that (for example, changing the text of a #GtkLabel), then you will have to call gtk_widget_queue_resize() or gtk_widget_queue_draw_area() yourself. gdk_frame_clock_get_frame_time() should generally be used for timing continuous animations and gdk_frame_timings_get_predicted_presentation_time() if you are trying to display isolated frames at particular times. This is a more convenient alternative to connecting directly to the #GdkFrameClock::update signal of #GdkFrameClock, since you don't have to worry about when a #GdkFrameClock is assigned to a widget. an id for the connection of this callback. Remove the callback by passing it to gtk_widget_remove_tick_callback() a #GtkWidget function to call for updating animations data to pass to @callback function to call to free @user_data when the callback is removed. Determines whether an accelerator that activates the signal identified by @signal_id can currently be activated. This is done by emitting the #GtkWidget::can-activate-accel signal on @widget; if the signal isn’t overridden by a handler or in a derived widget, then the default check is that the widget must be sensitive, and the widget and all its ancestors mapped. %TRUE if the accelerator can be activated. a #GtkWidget the ID of a signal installed on @widget This function is used by custom widget implementations; if you're writing an app, you’d use gtk_widget_grab_focus() to move the focus to a particular widget, and gtk_container_set_focus_chain() to change the focus tab order. So you may want to investigate those functions instead. gtk_widget_child_focus() is called by containers as the user moves around the window using keyboard shortcuts. @direction indicates what kind of motion is taking place (up, down, left, right, tab forward, tab backward). gtk_widget_child_focus() emits the #GtkWidget::focus signal; widgets override the default handler for this signal in order to implement appropriate focus behavior. The default ::focus handler for a widget should return %TRUE if moving in @direction left the focus on a focusable location inside that widget, and %FALSE if moving in @direction moved the focus outside the widget. If returning %TRUE, widgets normally call gtk_widget_grab_focus() to place the focus accordingly; if returning %FALSE, they don’t modify the current focus location. %TRUE if focus ended up inside @widget a #GtkWidget direction of focus movement Emits a #GtkWidget::child-notify signal for the [child property][child-properties] @child_property on @widget. This is the analogue of g_object_notify() for child properties. Also see gtk_container_child_notify(). a #GtkWidget the name of a child property installed on the class of @widget’s parent Same as gtk_widget_path(), but always uses the name of a widget’s type, never uses a custom name set with gtk_widget_set_name(). Use gtk_widget_get_path() instead a #GtkWidget location to store the length of the class path, or %NULL location to store the class path as an allocated string, or %NULL location to store the reverse class path as an allocated string, or %NULL Computes whether a container should give this widget extra space when possible. Containers should check this, rather than looking at gtk_widget_get_hexpand() or gtk_widget_get_vexpand(). This function already checks whether the widget is visible, so visibility does not need to be checked separately. Non-visible widgets are not expanded. The computed expand value uses either the expand setting explicitly set on the widget itself, or, if none has been explicitly set, the widget may expand if some of its children do. whether widget tree rooted here should be expanded the widget expand direction Creates a new #PangoContext with the appropriate font map, font options, font description, and base direction for drawing text for this widget. See also gtk_widget_get_pango_context(). the new #PangoContext a #GtkWidget Creates a new #PangoLayout with the appropriate font map, font description, and base direction for drawing text for this widget. If you keep a #PangoLayout created in this way around, you need to re-create it when the widget #PangoContext is replaced. This can be tracked by using the #GtkWidget::screen-changed signal on the widget. the new #PangoLayout a #GtkWidget text to set on the layout (can be %NULL) Destroys a widget. When a widget is destroyed all references it holds on other objects will be released: - if the widget is inside a container, it will be removed from its parent - if the widget is a container, all its children will be destroyed, recursively - if the widget is a top level, it will be removed from the list of top level widgets that GTK+ maintains internally It's expected that all references held on the widget will also be released; you should connect to the #GtkWidget::destroy signal if you hold a reference to @widget and you wish to remove it when this function is called. It is not necessary to do so if you are implementing a #GtkContainer, as you'll be able to use the #GtkContainerClass.remove() virtual function for that. It's important to notice that gtk_widget_destroy() will only cause the @widget to be finalized if no additional references, acquired using g_object_ref(), are held on it. In case additional references are in place, the @widget will be in an "inert" state after calling this function; @widget will still point to valid memory, allowing you to release the references you hold, but you may not query the widget's own state. You should typically call this function on top level widgets, and rarely on child widgets. See also: gtk_container_remove() a #GtkWidget This function sets *@widget_pointer to %NULL if @widget_pointer != %NULL. It’s intended to be used as a callback connected to the “destroy” signal of a widget. You connect gtk_widget_destroyed() as a signal handler, and pass the address of your widget variable as user data. Then when the widget is destroyed, the variable will be set to %NULL. Useful for example to avoid multiple copies of the same dialog. a #GtkWidget address of a variable that contains @widget Returns %TRUE if @device has been shadowed by a GTK+ device grab on another widget, so it would stop sending events to @widget. This may be used in the #GtkWidget::grab-notify signal to check for specific devices. See gtk_device_grab_add(). %TRUE if there is an ongoing grab on @device by another #GtkWidget than @widget. a #GtkWidget a #GdkDevice This function is equivalent to gtk_drag_begin_with_coordinates(), passing -1, -1 as coordinates. Use gtk_drag_begin_with_coordinates() instead the context for this drag the source widget The targets (data formats) in which the source can provide the data A bitmask of the allowed drag actions for this drag The button the user clicked to start the drag The event that triggered the start of the drag, or %NULL if none can be obtained. Initiates a drag on the source side. The function only needs to be used when the application is starting drags itself, and is not needed when gtk_drag_source_set() is used. The @event is used to retrieve the timestamp that will be used internally to grab the pointer. If @event is %NULL, then %GDK_CURRENT_TIME will be used. However, you should try to pass a real event in all cases, since that can be used to get information about the drag. Generally there are three cases when you want to start a drag by hand by calling this function: 1. During a #GtkWidget::button-press-event handler, if you want to start a drag immediately when the user presses the mouse button. Pass the @event that you have in your #GtkWidget::button-press-event handler. 2. During a #GtkWidget::motion-notify-event handler, if you want to start a drag when the mouse moves past a certain threshold distance after a button-press. Pass the @event that you have in your #GtkWidget::motion-notify-event handler. 3. During a timeout handler, if you want to start a drag after the mouse button is held down for some time. Try to save the last event that you got from the mouse, using gdk_event_copy(), and pass it to this function (remember to free the event with gdk_event_free() when you are done). If you really cannot pass a real event, pass %NULL instead. the context for this drag the source widget The targets (data formats) in which the source can provide the data A bitmask of the allowed drag actions for this drag The button the user clicked to start the drag The event that triggered the start of the drag, or %NULL if none can be obtained. The initial x coordinate to start dragging from, in the coordinate space of @widget. If -1 is passed, the coordinates are retrieved from @event or the current pointer position The initial y coordinate to start dragging from, in the coordinate space of @widget. If -1 is passed, the coordinates are retrieved from @event or the current pointer position Checks to see if a mouse drag starting at (@start_x, @start_y) and ending at (@current_x, @current_y) has passed the GTK+ drag threshold, and thus should trigger the beginning of a drag-and-drop operation. %TRUE if the drag threshold has been passed. a #GtkWidget X coordinate of start of drag Y coordinate of start of drag current X coordinate current Y coordinate Add the image targets supported by #GtkSelectionData to the target list of the drag destination. The targets are added with @info = 0. If you need another value, use gtk_target_list_add_image_targets() and gtk_drag_dest_set_target_list(). a #GtkWidget that’s a drag destination Add the text targets supported by #GtkSelectionData to the target list of the drag destination. The targets are added with @info = 0. If you need another value, use gtk_target_list_add_text_targets() and gtk_drag_dest_set_target_list(). a #GtkWidget that’s a drag destination Add the URI targets supported by #GtkSelectionData to the target list of the drag destination. The targets are added with @info = 0. If you need another value, use gtk_target_list_add_uri_targets() and gtk_drag_dest_set_target_list(). a #GtkWidget that’s a drag destination Looks for a match between the supported targets of @context and the @dest_target_list, returning the first matching target, otherwise returning %GDK_NONE. @dest_target_list should usually be the return value from gtk_drag_dest_get_target_list(), but some widgets may have different valid targets for different parts of the widget; in that case, they will have to implement a drag_motion handler that passes the correct target list to this function. first target that the source offers and the dest can accept, or %GDK_NONE drag destination widget drag context list of droppable targets, or %NULL to use gtk_drag_dest_get_target_list (@widget). Returns the list of targets this widget can accept from drag-and-drop. the #GtkTargetList, or %NULL if none a #GtkWidget Returns whether the widget has been configured to always emit #GtkWidget::drag-motion signals. %TRUE if the widget always emits #GtkWidget::drag-motion events a #GtkWidget that’s a drag destination Sets a widget as a potential drop destination, and adds default behaviors. The default behaviors listed in @flags have an effect similar to installing default handlers for the widget’s drag-and-drop signals (#GtkWidget::drag-motion, #GtkWidget::drag-drop, ...). They all exist for convenience. When passing #GTK_DEST_DEFAULT_ALL for instance it is sufficient to connect to the widget’s #GtkWidget::drag-data-received signal to get primitive, but consistent drag-and-drop support. Things become more complicated when you try to preview the dragged data, as described in the documentation for #GtkWidget::drag-motion. The default behaviors described by @flags make some assumptions, that can conflict with your own signal handlers. For instance #GTK_DEST_DEFAULT_DROP causes invokations of gdk_drag_status() in the context of #GtkWidget::drag-motion, and invokations of gtk_drag_finish() in #GtkWidget::drag-data-received. Especially the later is dramatic, when your own #GtkWidget::drag-motion handler calls gtk_drag_get_data() to inspect the dragged data. There’s no way to set a default action here, you can use the #GtkWidget::drag-motion callback for that. Here’s an example which selects the action to use depending on whether the control key is pressed or not: |[<!-- language="C" --> static void drag_motion (GtkWidget *widget, GdkDragContext *context, gint x, gint y, guint time) { GdkModifierType mask; gdk_window_get_pointer (gtk_widget_get_window (widget), NULL, NULL, &mask); if (mask & GDK_CONTROL_MASK) gdk_drag_status (context, GDK_ACTION_COPY, time); else gdk_drag_status (context, GDK_ACTION_MOVE, time); } ]| a #GtkWidget which types of default drag behavior to use a pointer to an array of #GtkTargetEntrys indicating the drop types that this @widget will accept, or %NULL. Later you can access the list with gtk_drag_dest_get_target_list() and gtk_drag_dest_find_target(). the number of entries in @targets a bitmask of possible actions for a drop onto this @widget. Sets this widget as a proxy for drops to another window. a #GtkWidget the window to which to forward drag events the drag protocol which the @proxy_window accepts (You can use gdk_drag_get_protocol() to determine this) If %TRUE, send the same coordinates to the destination, because it is an embedded subwindow. Sets the target types that this widget can accept from drag-and-drop. The widget must first be made into a drag destination with gtk_drag_dest_set(). a #GtkWidget that’s a drag destination list of droppable targets, or %NULL for none Tells the widget to emit #GtkWidget::drag-motion and #GtkWidget::drag-leave events regardless of the targets and the %GTK_DEST_DEFAULT_MOTION flag. This may be used when a widget wants to do generic actions regardless of the targets that the source offers. a #GtkWidget that’s a drag destination whether to accept all targets Clears information about a drop destination set with gtk_drag_dest_set(). The widget will no longer receive notification of drags. a #GtkWidget Gets the data associated with a drag. When the data is received or the retrieval fails, GTK+ will emit a #GtkWidget::drag-data-received signal. Failure of the retrieval is indicated by the length field of the @selection_data signal parameter being negative. However, when gtk_drag_get_data() is called implicitely because the %GTK_DEST_DEFAULT_DROP was set, then the widget will not receive notification of failed drops. the widget that will receive the #GtkWidget::drag-data-received signal the drag context the target (form of the data) to retrieve a timestamp for retrieving the data. This will generally be the time received in a #GtkWidget::drag-motion or #GtkWidget::drag-drop signal Highlights a widget as a currently hovered drop target. To end the highlight, call gtk_drag_unhighlight(). GTK+ calls this automatically if %GTK_DEST_DEFAULT_HIGHLIGHT is set. a widget to highlight Add the writable image targets supported by #GtkSelectionData to the target list of the drag source. The targets are added with @info = 0. If you need another value, use gtk_target_list_add_image_targets() and gtk_drag_source_set_target_list(). a #GtkWidget that’s is a drag source Add the text targets supported by #GtkSelectionData to the target list of the drag source. The targets are added with @info = 0. If you need another value, use gtk_target_list_add_text_targets() and gtk_drag_source_set_target_list(). a #GtkWidget that’s is a drag source Add the URI targets supported by #GtkSelectionData to the target list of the drag source. The targets are added with @info = 0. If you need another value, use gtk_target_list_add_uri_targets() and gtk_drag_source_set_target_list(). a #GtkWidget that’s is a drag source Gets the list of targets this widget can provide for drag-and-drop. the #GtkTargetList, or %NULL if none a #GtkWidget Sets up a widget so that GTK+ will start a drag operation when the user clicks and drags on the widget. The widget must have a window. a #GtkWidget the bitmask of buttons that can start the drag the table of targets that the drag will support, may be %NULL the number of items in @targets the bitmask of possible actions for a drag from this widget Sets the icon that will be used for drags from a particular source to @icon. See the docs for #GtkIconTheme for more details. a #GtkWidget A #GIcon Sets the icon that will be used for drags from a particular source to a themed icon. See the docs for #GtkIconTheme for more details. a #GtkWidget name of icon to use Sets the icon that will be used for drags from a particular widget from a #GdkPixbuf. GTK+ retains a reference for @pixbuf and will release it when it is no longer needed. a #GtkWidget the #GdkPixbuf for the drag icon Sets the icon that will be used for drags from a particular source to a stock icon. Use gtk_drag_source_set_icon_name() instead. a #GtkWidget the ID of the stock icon to use Changes the target types that this widget offers for drag-and-drop. The widget must first be made into a drag source with gtk_drag_source_set(). a #GtkWidget that’s a drag source list of draggable targets, or %NULL for none Undoes the effects of gtk_drag_source_set(). a #GtkWidget Removes a highlight set by gtk_drag_highlight() from a widget. a widget to remove the highlight from Draws @widget to @cr. The top left corner of the widget will be drawn to the currently set origin point of @cr. You should pass a cairo context as @cr argument that is in an original state. Otherwise the resulting drawing is undefined. For example changing the operator using cairo_set_operator() or the line width using cairo_set_line_width() might have unwanted side effects. You may however change the context’s transform matrix - like with cairo_scale(), cairo_translate() or cairo_set_matrix() and clip region with cairo_clip() prior to calling this function. Also, it is fine to modify the context with cairo_save() and cairo_push_group() prior to calling this function. Note that special-purpose widgets may contain special code for rendering to the screen and might appear differently on screen and when rendered using gtk_widget_draw(). the widget to draw. It must be drawable (see gtk_widget_is_drawable()) and a size must have been allocated. a cairo context to draw to Ensures that @widget has a style (@widget->style). Not a very useful function; most of the time, if you want the style, the widget is realized, and realized widgets are guaranteed to have a style already. Use #GtkStyleContext instead a #GtkWidget Notifies the user about an input-related error on this widget. If the #GtkSettings:gtk-error-bell setting is %TRUE, it calls gdk_window_beep(), otherwise it does nothing. Note that the effect of gdk_window_beep() can be configured in many ways, depending on the windowing backend and the desktop environment or window manager that is used. a #GtkWidget Rarely-used function. This function is used to emit the event signals on a widget (those signals should never be emitted without using this function to do so). If you want to synthesize an event though, don’t use this function; instead, use gtk_main_do_event() so the event will behave as if it were in the event queue. Don’t synthesize expose events; instead, use gdk_window_invalidate_rect() to invalidate a region of the window. return from the event signal emission (%TRUE if the event was handled) a #GtkWidget a #GdkEvent Stops emission of #GtkWidget::child-notify signals on @widget. The signals are queued until gtk_widget_thaw_child_notify() is called on @widget. This is the analogue of g_object_freeze_notify() for child properties. a #GtkWidget Returns the accessible object that describes the widget to an assistive technology. If accessibility support is not available, this #AtkObject instance may be a no-op. Likewise, if no class-specific #AtkObject implementation is available for the widget instance in question, it will inherit an #AtkObject implementation from the first ancestor class for which such an implementation is defined. The documentation of the [ATK](http://developer.gnome.org/atk/stable/) library contains more information about accessible objects and their uses. the #AtkObject associated with @widget a #GtkWidget Retrieves the #GActionGroup that was registered using @prefix. The resulting #GActionGroup may have been registered to @widget or any #GtkWidget in its ancestry. If no action group was found matching @prefix, then %NULL is returned. A #GActionGroup or %NULL. A #GtkWidget The “prefix” of the action group. Returns the baseline that has currently been allocated to @widget. This function is intended to be used when implementing handlers for the #GtkWidget::draw function, and when allocating child widgets in #GtkWidget::size_allocate. the baseline of the @widget, or -1 if none the widget to query Returns the height that has currently been allocated to @widget. This function is intended to be used when implementing handlers for the #GtkWidget::draw function. the height of the @widget the widget to query Retrieves the widget’s allocated size. This function returns the last values passed to gtk_widget_size_allocate_with_baseline(). The value differs from the size returned in gtk_widget_get_allocation() in that functions like gtk_widget_set_halign() can adjust the allocation, but not the value returned by this function. If a widget is not visible, its allocated size is 0. a #GtkWidget a pointer to a #GtkAllocation to copy to a pointer to an integer to copy to Returns the width that has currently been allocated to @widget. This function is intended to be used when implementing handlers for the #GtkWidget::draw function. the width of the @widget the widget to query Retrieves the widget’s allocation. Note, when implementing a #GtkContainer: a widget’s allocation will be its “adjusted” allocation, that is, the widget’s parent container typically calls gtk_widget_size_allocate() with an allocation, and that allocation is then adjusted (to handle margin and alignment for example) before assignment to the widget. gtk_widget_get_allocation() returns the adjusted allocation that was actually assigned to the widget. The adjusted allocation is guaranteed to be completely contained within the gtk_widget_size_allocate() allocation, however. So a #GtkContainer is guaranteed that its children stay inside the assigned bounds, but not that they have exactly the bounds the container assigned. There is no way to get the original allocation assigned by gtk_widget_size_allocate(), since it isn’t stored; if a container implementation needs that information it will have to track it itself. a #GtkWidget a pointer to a #GtkAllocation to copy to Gets the first ancestor of @widget with type @widget_type. For example, `gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)` gets the first #GtkBox that’s an ancestor of @widget. No reference will be added to the returned widget; it should not be unreferenced. See note about checking for a toplevel #GtkWindow in the docs for gtk_widget_get_toplevel(). Note that unlike gtk_widget_is_ancestor(), gtk_widget_get_ancestor() considers @widget to be an ancestor of itself. the ancestor widget, or %NULL if not found a #GtkWidget ancestor type Determines whether the application intends to draw on the widget in an #GtkWidget::draw handler. See gtk_widget_set_app_paintable() %TRUE if the widget is app paintable a #GtkWidget Determines whether @widget can be a default widget. See gtk_widget_set_can_default(). %TRUE if @widget can be a default widget, %FALSE otherwise a #GtkWidget Determines whether @widget can own the input focus. See gtk_widget_set_can_focus(). %TRUE if @widget can own the input focus, %FALSE otherwise a #GtkWidget This function is only for use in widget implementations. Obtains @widget->requisition, unless someone has forced a particular geometry on the widget (e.g. with gtk_widget_set_size_request()), in which case it returns that geometry instead of the widget's requisition. This function differs from gtk_widget_size_request() in that it retrieves the last size request value from @widget->requisition, while gtk_widget_size_request() actually calls the "size_request" method on @widget to compute the size request and fill in @widget->requisition, and only then returns @widget->requisition. Because this function does not call the “size_request” method, it can only be used when you know that @widget->requisition is up-to-date, that is, gtk_widget_size_request() has been called since the last time a resize was queued. In general, only container implementations have this information; applications should use gtk_widget_size_request(). Use gtk_widget_get_preferred_size() instead. a #GtkWidget a #GtkRequisition to be filled in Gets the value set with gtk_widget_set_child_visible(). If you feel a need to use this function, your code probably needs reorganization. This function is only useful for container implementations and never should be called by an application. %TRUE if the widget is mapped with the parent. a #GtkWidget Retrieves the widget’s clip area. The clip area is the area in which all of @widget's drawing will happen. Other toolkits call it the bounding box. Historically, in GTK+ the clip area has been equal to the allocation retrieved via gtk_widget_get_allocation(). a #GtkWidget a pointer to a #GtkAllocation to copy to Returns the clipboard object for the given selection to be used with @widget. @widget must have a #GdkDisplay associated with it, so must be attached to a toplevel window. the appropriate clipboard object. If no clipboard already exists, a new one will be created. Once a clipboard object has been created, it is persistent for all time. a #GtkWidget a #GdkAtom which identifies the clipboard to use. %GDK_SELECTION_CLIPBOARD gives the default clipboard. Another common value is %GDK_SELECTION_PRIMARY, which gives the primary X selection. Obtains the composite name of a widget. Use gtk_widget_class_set_template(), or don’t use this API at all. the composite name of @widget, or %NULL if @widget is not a composite child. The string should be freed when it is no longer needed. a #GtkWidget Returns whether @device can interact with @widget and its children. See gtk_widget_set_device_enabled(). %TRUE is @device is enabled for @widget a #GtkWidget a #GdkDevice Returns the events mask for the widget corresponding to an specific device. These are the events that the widget will receive when @device operates on it. device event mask for @widget a #GtkWidget a #GdkDevice Gets the reading direction for a particular widget. See gtk_widget_set_direction(). the reading direction for the widget. a #GtkWidget Get the #GdkDisplay for the toplevel window associated with this widget. This function can only be called after the widget has been added to a widget hierarchy with a #GtkWindow at the top. In general, you should only create display specific resources when a widget has been realized, and you should free those resources when the widget is unrealized. the #GdkDisplay for the toplevel for this widget. a #GtkWidget Determines whether the widget is double buffered. See gtk_widget_set_double_buffered() %TRUE if the widget is double buffered a #GtkWidget Returns the event mask (see #GdkEventMask) for the widget. These are the events that the widget will receive. Note: Internally, the widget event mask will be the logical OR of the event mask set through gtk_widget_set_events() or gtk_widget_add_events(), and the event mask necessary to cater for every #GtkEventController created for the widget. event mask for @widget a #GtkWidget Returns whether the widget should grab focus when it is clicked with the mouse. See gtk_widget_set_focus_on_click(). %TRUE if the widget should grab focus when it is clicked with the mouse. a #GtkWidget Gets the font map that has been set with gtk_widget_set_font_map(). A #PangoFontMap, or %NULL a #GtkWidget Returns the #cairo_font_options_t used for Pango rendering. When not set, the defaults font options for the #GdkScreen will be used. the #cairo_font_options_t or %NULL if not set a #GtkWidget Obtains the frame clock for a widget. The frame clock is a global “ticker” that can be used to drive animations and repaints. The most common reason to get the frame clock is to call gdk_frame_clock_get_frame_time(), in order to get a time to use for animating. For example you might record the start of the animation with an initial value from gdk_frame_clock_get_frame_time(), and then update the animation by calling gdk_frame_clock_get_frame_time() again during each repaint. gdk_frame_clock_request_phase() will result in a new frame on the clock, but won’t necessarily repaint any widgets. To repaint a widget, you have to use gtk_widget_queue_draw() which invalidates the widget (thus scheduling it to receive a draw on the next frame). gtk_widget_queue_draw() will also end up requesting a frame on the appropriate frame clock. A widget’s frame clock will not change while the widget is mapped. Reparenting a widget (which implies a temporary unmap) can change the widget’s frame clock. Unrealized widgets do not have a frame clock. a #GdkFrameClock, or %NULL if widget is unrealized a #GtkWidget Gets the value of the #GtkWidget:halign property. For backwards compatibility reasons this method will never return %GTK_ALIGN_BASELINE, but instead it will convert it to %GTK_ALIGN_FILL. Baselines are not supported for horizontal alignment. the horizontal alignment of @widget a #GtkWidget Returns the current value of the has-tooltip property. See #GtkWidget:has-tooltip for more information. current value of has-tooltip on @widget. a #GtkWidget Determines whether @widget has a #GdkWindow of its own. See gtk_widget_set_has_window(). %TRUE if @widget has a window, %FALSE otherwise a #GtkWidget Gets whether the widget would like any available extra horizontal space. When a user resizes a #GtkWindow, widgets with expand=TRUE generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand. Containers should use gtk_widget_compute_expand() rather than this function, to see whether a widget, or any of its children, has the expand flag set. If any child of a widget wants to expand, the parent may ask to expand also. This function only looks at the widget’s own hexpand flag, rather than computing whether the entire widget tree rooted at this widget wants to expand. whether hexpand flag is set the widget Gets whether gtk_widget_set_hexpand() has been used to explicitly set the expand flag on this widget. If hexpand is set, then it overrides any computed expand value based on child widgets. If hexpand is not set, then the expand value depends on whether any children of the widget would like to expand. There are few reasons to use this function, but it’s here for completeness and consistency. whether hexpand has been explicitly set the widget Whether the widget is mapped. %TRUE if the widget is mapped, %FALSE otherwise. a #GtkWidget Gets the value of the #GtkWidget:margin-bottom property. The bottom margin of @widget a #GtkWidget Gets the value of the #GtkWidget:margin-end property. The end margin of @widget a #GtkWidget Gets the value of the #GtkWidget:margin-left property. Use gtk_widget_get_margin_start() instead. The left margin of @widget a #GtkWidget Gets the value of the #GtkWidget:margin-right property. Use gtk_widget_get_margin_end() instead. The right margin of @widget a #GtkWidget Gets the value of the #GtkWidget:margin-start property. The start margin of @widget a #GtkWidget Gets the value of the #GtkWidget:margin-top property. The top margin of @widget a #GtkWidget Returns the modifier mask the @widget’s windowing system backend uses for a particular purpose. See gdk_keymap_get_modifier_mask(). the modifier mask used for @intent. a #GtkWidget the use case for the modifier mask Returns the current modifier style for the widget. (As set by gtk_widget_modify_style().) If no style has previously set, a new #GtkRcStyle will be created with all values unset, and set as the modifier style for the widget. If you make changes to this rc style, you must call gtk_widget_modify_style(), passing in the returned rc style, to make sure that your changes take effect. Caution: passing the style back to gtk_widget_modify_style() will normally end up destroying it, because gtk_widget_modify_style() copies the passed-in style and sets the copy as the new modifier style, thus dropping any reference to the old modifier style. Add a reference to the modifier style if you want to keep it alive. Use #GtkStyleContext with a custom #GtkStyleProvider instead the modifier style for the widget. This rc style is owned by the widget. If you want to keep a pointer to value this around, you must add a refcount using g_object_ref(). a #GtkWidget Retrieves the name of a widget. See gtk_widget_set_name() for the significance of widget names. name of the widget. This string is owned by GTK+ and should not be modified or freed a #GtkWidget Returns the current value of the #GtkWidget:no-show-all property, which determines whether calls to gtk_widget_show_all() will affect this widget. the current value of the “no-show-all” property. a #GtkWidget Fetches the requested opacity for this widget. See gtk_widget_set_opacity(). the requested opacity for this widget. a #GtkWidget Gets a #PangoContext with the appropriate font map, font description, and base direction for this widget. Unlike the context returned by gtk_widget_create_pango_context(), this context is owned by the widget (it can be used until the screen for the widget changes or the widget is removed from its toplevel), and will be updated to match any changes to the widget’s attributes. This can be tracked by using the #GtkWidget::screen-changed signal on the widget. the #PangoContext for the widget. a #GtkWidget Returns the parent container of @widget. the parent container of @widget, or %NULL a #GtkWidget Gets @widget’s parent window, or %NULL if it does not have one. the parent window of @widget, or %NULL if it does not have a parent window. a #GtkWidget. Returns the #GtkWidgetPath representing @widget, if the widget is not connected to a toplevel widget, a partial path will be created. The #GtkWidgetPath representing @widget a #GtkWidget Obtains the location of the mouse pointer in widget coordinates. Widget coordinates are a bit odd; for historical reasons, they are defined as @widget->window coordinates for widgets that return %TRUE for gtk_widget_get_has_window(); and are relative to @widget->allocation.x, @widget->allocation.y otherwise. Use gdk_window_get_device_position() instead. a #GtkWidget return location for the X coordinate, or %NULL return location for the Y coordinate, or %NULL Retrieves a widget’s initial minimum and natural height. This call is specific to width-for-height requests. The returned request will be modified by the GtkWidgetClass::adjust_size_request virtual method and by any #GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself. a #GtkWidget instance location to store the minimum height, or %NULL location to store the natural height, or %NULL Retrieves a widget’s minimum and natural height and the corresponding baselines if it would be given the specified @width, or the default height if @width is -1. The baselines may be -1 which means that no baseline is requested for this widget. The returned request will be modified by the GtkWidgetClass::adjust_size_request and GtkWidgetClass::adjust_baseline_request virtual methods and by any #GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself. a #GtkWidget instance the width which is available for allocation, or -1 if none location for storing the minimum height, or %NULL location for storing the natural height, or %NULL location for storing the baseline for the minimum height, or %NULL location for storing the baseline for the natural height, or %NULL Retrieves a widget’s minimum and natural height if it would be given the specified @width. The returned request will be modified by the GtkWidgetClass::adjust_size_request virtual method and by any #GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself. a #GtkWidget instance the width which is available for allocation location for storing the minimum height, or %NULL location for storing the natural height, or %NULL Retrieves the minimum and natural size of a widget, taking into account the widget’s preference for height-for-width management. This is used to retrieve a suitable size by container widgets which do not impose any restrictions on the child placement. It can be used to deduce toplevel window and menu sizes as well as child widgets in free-form containers such as GtkLayout. Handle with care. Note that the natural height of a height-for-width widget will generally be a smaller size than the minimum height, since the required height for the natural width is generally smaller than the required height for the minimum width. Use gtk_widget_get_preferred_height_and_baseline_for_width() if you want to support baseline alignment. a #GtkWidget instance location for storing the minimum size, or %NULL location for storing the natural size, or %NULL Retrieves a widget’s initial minimum and natural width. This call is specific to height-for-width requests. The returned request will be modified by the GtkWidgetClass::adjust_size_request virtual method and by any #GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself. a #GtkWidget instance location to store the minimum width, or %NULL location to store the natural width, or %NULL Retrieves a widget’s minimum and natural width if it would be given the specified @height. The returned request will be modified by the GtkWidgetClass::adjust_size_request virtual method and by any #GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself. a #GtkWidget instance the height which is available for allocation location for storing the minimum width, or %NULL location for storing the natural width, or %NULL Determines whether @widget is realized. %TRUE if @widget is realized, %FALSE otherwise a #GtkWidget Determines whether @widget is always treated as the default widget within its toplevel when it has the focus, even if another widget is the default. See gtk_widget_set_receives_default(). %TRUE if @widget acts as the default widget when focused, %FALSE otherwise a #GtkWidget Gets whether the widget prefers a height-for-width layout or a width-for-height layout. #GtkBin widgets generally propagate the preference of their child, container widgets need to request something either in context of their children or in context of their allocation capabilities. The #GtkSizeRequestMode preferred by @widget. a #GtkWidget instance Retrieves the widget’s requisition. This function should only be used by widget implementations in order to figure whether the widget’s requisition has actually changed after some internal state change (so that they can call gtk_widget_queue_resize() instead of gtk_widget_queue_draw()). Normally, gtk_widget_size_request() should be used. The #GtkRequisition cache on the widget was removed, If you need to cache sizes across requests and allocations, add an explicit cache to the widget in question instead. a #GtkWidget a pointer to a #GtkRequisition to copy to Get the root window where this widget is located. This function can only be called after the widget has been added to a widget hierarchy with #GtkWindow at the top. The root window is useful for such purposes as creating a popup #GdkWindow associated with the window. In general, you should only create display specific resources when a widget has been realized, and you should free those resources when the widget is unrealized. Use gdk_screen_get_root_window() instead the #GdkWindow root window for the toplevel for this widget. a #GtkWidget Retrieves the internal scale factor that maps from window coordinates to the actual device pixels. On traditional systems this is 1, on high density outputs, it can be a higher value (typically 2). See gdk_window_get_scale_factor(). the scale factor for @widget a #GtkWidget Get the #GdkScreen from the toplevel window associated with this widget. This function can only be called after the widget has been added to a widget hierarchy with a #GtkWindow at the top. In general, you should only create screen specific resources when a widget has been realized, and you should free those resources when the widget is unrealized. the #GdkScreen for the toplevel for this widget. a #GtkWidget Returns the widget’s sensitivity (in the sense of returning the value that has been set using gtk_widget_set_sensitive()). The effective sensitivity of a widget is however determined by both its own and its parent widget’s sensitivity. See gtk_widget_is_sensitive(). %TRUE if the widget is sensitive a #GtkWidget Gets the settings object holding the settings used for this widget. Note that this function can only be called when the #GtkWidget is attached to a toplevel, since the settings object is specific to a particular #GdkScreen. the relevant #GtkSettings object a #GtkWidget Gets the size request that was explicitly set for the widget using gtk_widget_set_size_request(). A value of -1 stored in @width or @height indicates that that dimension has not been set explicitly and the natural requisition of the widget will be used instead. See gtk_widget_set_size_request(). To get the size a widget will actually request, call gtk_widget_get_preferred_size() instead of this function. a #GtkWidget return location for width, or %NULL return location for height, or %NULL Returns the widget’s state. See gtk_widget_set_state(). Use gtk_widget_get_state_flags() instead. the state of @widget. a #GtkWidget Returns the widget state as a flag set. It is worth mentioning that the effective %GTK_STATE_FLAG_INSENSITIVE state will be returned, that is, also based on parent insensitivity, even if @widget itself is sensitive. Also note that if you are looking for a way to obtain the #GtkStateFlags to pass to a #GtkStyleContext method, you should look at gtk_style_context_get_state(). The state flags for widget a #GtkWidget Simply an accessor function that returns @widget->style. Use #GtkStyleContext instead the widget’s #GtkStyle a #GtkWidget Returns the style context associated to @widget. The returned object is guaranteed to be the same for the lifetime of @widget. a #GtkStyleContext. This memory is owned by @widget and must not be freed. a #GtkWidget Returns %TRUE if @widget is multiple pointer aware. See gtk_widget_set_support_multidevice() for more information. %TRUE if @widget is multidevice aware. a #GtkWidget Fetch an object build from the template XML for @widget_type in this @widget instance. This will only report children which were previously declared with gtk_widget_class_bind_template_child_full() or one of its variants. This function is only meant to be called for code which is private to the @widget_type which declared the child and is meant for language bindings which cannot easily make use of the GObject structure offsets. The object built in the template XML with the id @name A #GtkWidget The #GType to get a template child for The “id” of the child defined in the template XML Gets the contents of the tooltip for @widget. the tooltip text, or %NULL. You should free the returned string with g_free() when done. a #GtkWidget Gets the contents of the tooltip for @widget. the tooltip text, or %NULL. You should free the returned string with g_free() when done. a #GtkWidget Returns the #GtkWindow of the current tooltip. This can be the GtkWindow created by default, or the custom tooltip window set using gtk_widget_set_tooltip_window(). The #GtkWindow of the current tooltip. a #GtkWidget This function returns the topmost widget in the container hierarchy @widget is a part of. If @widget has no parent widgets, it will be returned as the topmost widget. No reference will be added to the returned widget; it should not be unreferenced. Note the difference in behavior vs. gtk_widget_get_ancestor(); `gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW)` would return %NULL if @widget wasn’t inside a toplevel window, and if the window was inside a #GtkWindow-derived widget which was in turn inside the toplevel #GtkWindow. While the second case may seem unlikely, it actually happens when a #GtkPlug is embedded inside a #GtkSocket within the same application. To reliably find the toplevel #GtkWindow, use gtk_widget_get_toplevel() and call GTK_IS_WINDOW() on the result. For instance, to get the title of a widget's toplevel window, one might use: |[<!-- language="C" --> static const char * get_widget_toplevel_title (GtkWidget *widget) { GtkWidget *toplevel = gtk_widget_get_toplevel (widget); if (GTK_IS_WINDOW (toplevel)) { return gtk_window_get_title (GTK_WINDOW (toplevel)); } return NULL; } ]| the topmost ancestor of @widget, or @widget itself if there’s no ancestor. a #GtkWidget Gets the value of the #GtkWidget:valign property. For backwards compatibility reasons this method will never return %GTK_ALIGN_BASELINE, but instead it will convert it to %GTK_ALIGN_FILL. If your widget want to support baseline aligned children it must use gtk_widget_get_valign_with_baseline(), or `g_object_get (widget, "valign", &value, NULL)`, which will also report the true value. the vertical alignment of @widget, ignoring baseline alignment a #GtkWidget Gets the value of the #GtkWidget:valign property, including %GTK_ALIGN_BASELINE. the vertical alignment of @widget a #GtkWidget Gets whether the widget would like any available extra vertical space. See gtk_widget_get_hexpand() for more detail. whether vexpand flag is set the widget Gets whether gtk_widget_set_vexpand() has been used to explicitly set the expand flag on this widget. See gtk_widget_get_hexpand_set() for more detail. whether vexpand has been explicitly set the widget Determines whether the widget is visible. If you want to take into account whether the widget’s parent is also marked as visible, use gtk_widget_is_visible() instead. This function does not check if the widget is obscured in any way. See gtk_widget_set_visible(). %TRUE if the widget is visible a #GtkWidget Gets the visual that will be used to render @widget. the visual for @widget a #GtkWidget Returns the widget’s window if it is realized, %NULL otherwise @widget’s window. a #GtkWidget Makes @widget the current grabbed widget. This means that interaction with other widgets in the same application is blocked and mouse as well as keyboard events are delivered to this widget. If @widget is not sensitive, it is not set as the current grabbed widget and this function does nothing. The widget that grabs keyboard and pointer events Causes @widget to become the default widget. @widget must be able to be a default widget; typically you would ensure this yourself by calling gtk_widget_set_can_default() with a %TRUE value. The default widget is activated when the user presses Enter in a window. Default widgets must be activatable, that is, gtk_widget_activate() should affect them. Note that #GtkEntry widgets require the “activates-default” property set to %TRUE before they activate the default widget when Enter is pressed and the #GtkEntry is focused. a #GtkWidget Causes @widget to have the keyboard focus for the #GtkWindow it's inside. @widget must be a focusable widget, such as a #GtkEntry; something like #GtkFrame won’t work. More precisely, it must have the %GTK_CAN_FOCUS flag set. Use gtk_widget_set_can_focus() to modify that flag. The widget also needs to be realized and mapped. This is indicated by the related signals. Grabbing the focus immediately after creating the widget will likely fail and cause critical warnings. a #GtkWidget Removes the grab from the given widget. You have to pair calls to gtk_grab_add() and gtk_grab_remove(). If @widget does not have the grab, this function does nothing. The widget which gives up the grab Determines whether @widget is the current default widget within its toplevel. See gtk_widget_set_can_default(). %TRUE if @widget is the current default widget within its toplevel, %FALSE otherwise a #GtkWidget Determines if the widget has the global input focus. See gtk_widget_is_focus() for the difference between having the global input focus, and only having the focus within a toplevel. %TRUE if the widget has the global input focus. a #GtkWidget Determines whether the widget is currently grabbing events, so it is the only widget receiving input events (keyboard and mouse). See also gtk_grab_add(). %TRUE if the widget is in the grab_widgets stack a #GtkWidget Determines if the widget style has been looked up through the rc mechanism. Use #GtkStyleContext instead %TRUE if the widget has been looked up through the rc mechanism, %FALSE otherwise. a #GtkWidget Checks whether there is a #GdkScreen is associated with this widget. All toplevel widgets have an associated screen, and all widgets added into a hierarchy with a toplevel window at the top. %TRUE if there is a #GdkScreen associated with the widget. a #GtkWidget Determines if the widget should show a visible indication that it has the global input focus. This is a convenience function for use in ::draw handlers that takes into account whether focus indication should currently be shown in the toplevel window of @widget. See gtk_window_get_focus_visible() for more information about focus indication. To find out if the widget has the global input focus, use gtk_widget_has_focus(). %TRUE if the widget should display a “focus rectangle” a #GtkWidget Reverses the effects of gtk_widget_show(), causing the widget to be hidden (invisible to the user). a #GtkWidget Utility function; intended to be connected to the #GtkWidget::delete-event signal on a #GtkWindow. The function calls gtk_widget_hide() on its argument, then returns %TRUE. If connected to ::delete-event, the result is that clicking the close button for a window (on the window frame, top right corner usually) will hide but not destroy the window. By default, GTK+ destroys windows when ::delete-event is received. %TRUE a #GtkWidget Returns whether the widget is currently being destroyed. This information can sometimes be used to avoid doing unnecessary work. %TRUE if @widget is being destroyed a #GtkWidget Creates and initializes child widgets defined in templates. This function must be called in the instance initializer for any class which assigned itself a template using gtk_widget_class_set_template() It is important to call this function in the instance initializer of a #GtkWidget subclass and not in #GObject.constructed() or #GObject.constructor() for two reasons. One reason is that generally derived widgets will assume that parent class composite widgets have been created in their instance initializers. Another reason is that when calling g_object_new() on a widget with composite templates, it’s important to build the composite widgets before the construct properties are set. Properties passed to g_object_new() should take precedence over properties set in the private template XML. a #GtkWidget Sets an input shape for this widget’s GDK window. This allows for windows which react to mouse click in a nonrectangular region, see gdk_window_input_shape_combine_region() for more information. a #GtkWidget shape to be added, or %NULL to remove an existing shape Inserts @group into @widget. Children of @widget that implement #GtkActionable can then be associated with actions in @group by setting their “action-name” to @prefix.`action-name`. If @group is %NULL, a previously inserted group for @name is removed from @widget. a #GtkWidget the prefix for actions in @group a #GActionGroup, or %NULL Computes the intersection of a @widget’s area and @area, storing the intersection in @intersection, and returns %TRUE if there was an intersection. @intersection may be %NULL if you’re only interested in whether there was an intersection. %TRUE if there was an intersection a #GtkWidget a rectangle rectangle to store intersection of @widget and @area Determines whether @widget is somewhere inside @ancestor, possibly with intermediate containers. %TRUE if @ancestor contains @widget as a child, grandchild, great grandchild, etc. a #GtkWidget another #GtkWidget Whether @widget can rely on having its alpha channel drawn correctly. On X11 this function returns whether a compositing manager is running for @widget’s screen. Please note that the semantics of this call will change in the future if used on a widget that has a composited window in its hierarchy (as set by gdk_window_set_composited()). Use gdk_screen_is_composited() instead. %TRUE if the widget can rely on its alpha channel being drawn correctly. a #GtkWidget Determines whether @widget can be drawn to. A widget can be drawn to if it is mapped and visible. %TRUE if @widget is drawable, %FALSE otherwise a #GtkWidget Determines if the widget is the focus widget within its toplevel. (This does not mean that the #GtkWidget:has-focus property is necessarily set; #GtkWidget:has-focus will only be set if the toplevel widget additionally has the global input focus.) %TRUE if the widget is the focus widget. a #GtkWidget Returns the widget’s effective sensitivity, which means it is sensitive itself and also its parent widget is sensitive %TRUE if the widget is effectively sensitive a #GtkWidget Determines whether @widget is a toplevel widget. Currently only #GtkWindow and #GtkInvisible (and out-of-process #GtkPlugs) are toplevel widgets. Toplevel widgets have no parent widget. %TRUE if @widget is a toplevel, %FALSE otherwise a #GtkWidget Determines whether the widget and all its parents are marked as visible. This function does not check if the widget is obscured in any way. See also gtk_widget_get_visible() and gtk_widget_set_visible() %TRUE if the widget and all its parents are visible a #GtkWidget This function should be called whenever keyboard navigation within a single widget hits a boundary. The function emits the #GtkWidget::keynav-failed signal on the widget and its return value should be interpreted in a way similar to the return value of gtk_widget_child_focus(): When %TRUE is returned, stay in the widget, the failed keyboard navigation is OK and/or there is nowhere we can/should move the focus to. When %FALSE is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling gtk_widget_child_focus() on the widget’s toplevel. The default ::keynav-failed handler returns %FALSE for %GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. For the other values of #GtkDirectionType it returns %TRUE. Whenever the default handler returns %TRUE, it also calls gtk_widget_error_bell() to notify the user of the failed keyboard navigation. A use case for providing an own implementation of ::keynav-failed (either by connecting to it or by overriding it) would be a row of #GtkEntry widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys. %TRUE if stopping keyboard navigation is fine, %FALSE if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s). a #GtkWidget direction of focus movement Lists the closures used by @widget for accelerator group connections with gtk_accel_group_connect_by_path() or gtk_accel_group_connect(). The closures can be used to monitor accelerator changes on @widget, by connecting to the @GtkAccelGroup::accel-changed signal of the #GtkAccelGroup of a closure which can be found out with gtk_accel_group_from_accel_closure(). a newly allocated #GList of closures widget to list accelerator closures for Retrieves a %NULL-terminated array of strings containing the prefixes of #GActionGroup's available to @widget. a %NULL-terminated array of strings. A #GtkWidget Returns a newly allocated list of the widgets, normally labels, for which this widget is the target of a mnemonic (see for example, gtk_label_set_mnemonic_widget()). The widgets in the list are not individually referenced. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets, you must call `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first, and then unref all the widgets afterwards. the list of mnemonic labels; free this list with g_list_free() when you are done with it. a #GtkWidget This function is only for use in widget implementations. Causes a widget to be mapped if it isn’t already. a #GtkWidget Emits the #GtkWidget::mnemonic-activate signal. %TRUE if the signal has been handled a #GtkWidget %TRUE if there are other widgets with the same mnemonic Sets the base color for a widget in a particular state. All other style values are left untouched. The base color is the background color used along with the text color (see gtk_widget_modify_text()) for widgets such as #GtkEntry and #GtkTextView. See also gtk_widget_modify_style(). > Note that “no window” widgets (which have the %GTK_NO_WINDOW > flag set) draw on their parent container’s window and thus may > not draw any background themselves. This is the case for e.g. > #GtkLabel. > > To modify the background of such widgets, you have to set the > base color on their parent; if you want to set the background > of a rectangular area around a label, try placing the label in > a #GtkEventBox widget and setting the base color on that. Use gtk_widget_override_background_color() instead a #GtkWidget the state for which to set the base color the color to assign (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_modify_base(). Sets the background color for a widget in a particular state. All other style values are left untouched. See also gtk_widget_modify_style(). > Note that “no window” widgets (which have the %GTK_NO_WINDOW > flag set) draw on their parent container’s window and thus may > not draw any background themselves. This is the case for e.g. > #GtkLabel. > > To modify the background of such widgets, you have to set the > background color on their parent; if you want to set the background > of a rectangular area around a label, try placing the label in > a #GtkEventBox widget and setting the background color on that. Use gtk_widget_override_background_color() instead a #GtkWidget the state for which to set the background color the color to assign (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_modify_bg(). Sets the cursor color to use in a widget, overriding the #GtkWidget cursor-color and secondary-cursor-color style properties. All other style values are left untouched. See also gtk_widget_modify_style(). Use gtk_widget_override_cursor() instead. a #GtkWidget the color to use for primary cursor (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_modify_cursor(). the color to use for secondary cursor (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_modify_cursor(). Sets the foreground color for a widget in a particular state. All other style values are left untouched. See also gtk_widget_modify_style(). Use gtk_widget_override_color() instead a #GtkWidget the state for which to set the foreground color the color to assign (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_modify_fg(). Sets the font to use for a widget. All other style values are left untouched. See also gtk_widget_modify_style(). Use gtk_widget_override_font() instead a #GtkWidget the font description to use, or %NULL to undo the effect of previous calls to gtk_widget_modify_font() Modifies style values on the widget. Modifications made using this technique take precedence over style values set via an RC file, however, they will be overridden if a style is explicitly set on the widget using gtk_widget_set_style(). The #GtkRcStyle-struct is designed so each field can either be set or unset, so it is possible, using this function, to modify some style values and leave the others unchanged. Note that modifications made with this function are not cumulative with previous calls to gtk_widget_modify_style() or with such functions as gtk_widget_modify_fg(). If you wish to retain previous values, you must first call gtk_widget_get_modifier_style(), make your modifications to the returned style, then call gtk_widget_modify_style() with that style. On the other hand, if you first call gtk_widget_modify_style(), subsequent calls to such functions gtk_widget_modify_fg() will have a cumulative effect with the initial modifications. Use #GtkStyleContext with a custom #GtkStyleProvider instead a #GtkWidget the #GtkRcStyle-struct holding the style modifications Sets the text color for a widget in a particular state. All other style values are left untouched. The text color is the foreground color used along with the base color (see gtk_widget_modify_base()) for widgets such as #GtkEntry and #GtkTextView. See also gtk_widget_modify_style(). Use gtk_widget_override_color() instead a #GtkWidget the state for which to set the text color the color to assign (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_modify_text(). Sets the background color to use for a widget. All other style values are left untouched. See gtk_widget_override_color(). This function is not useful in the context of CSS-based rendering. If you wish to change the way a widget renders its background you should use a custom CSS style, through an application-specific #GtkStyleProvider and a CSS style class. You can also override the default drawing of a widget through the #GtkWidget::draw signal, and use Cairo to draw a specific color, regardless of the CSS style. a #GtkWidget the state for which to set the background color the color to assign, or %NULL to undo the effect of previous calls to gtk_widget_override_background_color() Sets the color to use for a widget. All other style values are left untouched. This function does not act recursively. Setting the color of a container does not affect its children. Note that some widgets that you may not think of as containers, for instance #GtkButtons, are actually containers. This API is mostly meant as a quick way for applications to change a widget appearance. If you are developing a widgets library and intend this change to be themeable, it is better done by setting meaningful CSS classes in your widget/container implementation through gtk_style_context_add_class(). This way, your widget library can install a #GtkCssProvider with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK priority in order to provide a default styling for those widgets that need so, and this theming may fully overridden by the user’s theme. Note that for complex widgets this may bring in undesired results (such as uniform background color everywhere), in these cases it is better to fully style such widgets through a #GtkCssProvider with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION priority. Use a custom style provider and style classes instead a #GtkWidget the state for which to set the color the color to assign, or %NULL to undo the effect of previous calls to gtk_widget_override_color() Sets the cursor color to use in a widget, overriding the cursor-color and secondary-cursor-color style properties. All other style values are left untouched. See also gtk_widget_modify_style(). Note that the underlying properties have the #GdkColor type, so the alpha value in @primary and @secondary will be ignored. This function is not useful in the context of CSS-based rendering. If you wish to change the color used to render the primary and secondary cursors you should use a custom CSS style, through an application-specific #GtkStyleProvider and a CSS style class. a #GtkWidget the color to use for primary cursor (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_override_cursor(). the color to use for secondary cursor (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_override_cursor(). Sets the font to use for a widget. All other style values are left untouched. See gtk_widget_override_color(). This function is not useful in the context of CSS-based rendering. If you wish to change the font a widget uses to render its text you should use a custom CSS style, through an application-specific #GtkStyleProvider and a CSS style class. a #GtkWidget the font description to use, or %NULL to undo the effect of previous calls to gtk_widget_override_font() Sets a symbolic color for a widget. All other style values are left untouched. See gtk_widget_override_color() for overriding the foreground or background color. This function is not useful in the context of CSS-based rendering. If you wish to change the color used to render symbolic icons you should use a custom CSS style, through an application-specific #GtkStyleProvider and a CSS style class. a #GtkWidget the name of the symbolic color to modify the color to assign (does not need to be allocated), or %NULL to undo the effect of previous calls to gtk_widget_override_symbolic_color() Obtains the full path to @widget. The path is simply the name of a widget and all its parents in the container hierarchy, separated by periods. The name of a widget comes from gtk_widget_get_name(). Paths are used to apply styles to a widget in gtkrc configuration files. Widget names are the type of the widget by default (e.g. “GtkButton”) or can be set to an application-specific value with gtk_widget_set_name(). By setting the name of a widget, you allow users or theme authors to apply styles to that specific widget in their gtkrc file. @path_reversed_p fills in the path in reverse order, i.e. starting with @widget’s name instead of starting with the name of @widget’s outermost ancestor. Use gtk_widget_get_path() instead a #GtkWidget location to store length of the path, or %NULL location to store allocated path string, or %NULL location to store allocated reverse path string, or %NULL This function is only for use in widget implementations. Flags the widget for a rerun of the GtkWidgetClass::size_allocate function. Use this function instead of gtk_widget_queue_resize() when the @widget's size request didn't change but it wants to reposition its contents. An example user of this function is gtk_widget_set_halign(). a #GtkWidget Mark @widget as needing to recompute its expand flags. Call this function when setting legacy expand child properties on the child of a container. See gtk_widget_compute_expand(). a #GtkWidget Equivalent to calling gtk_widget_queue_draw_area() for the entire area of a widget. a #GtkWidget Convenience function that calls gtk_widget_queue_draw_region() on the region created from the given coordinates. The region here is specified in widget coordinates. Widget coordinates are a bit odd; for historical reasons, they are defined as @widget->window coordinates for widgets that return %TRUE for gtk_widget_get_has_window(), and are relative to @widget->allocation.x, @widget->allocation.y otherwise. @width or @height may be 0, in this case this function does nothing. Negative values for @width and @height are not allowed. a #GtkWidget x coordinate of upper-left corner of rectangle to redraw y coordinate of upper-left corner of rectangle to redraw width of region to draw height of region to draw Invalidates the area of @widget defined by @region by calling gdk_window_invalidate_region() on the widget’s window and all its child windows. Once the main loop becomes idle (after the current batch of events has been processed, roughly), the window will receive expose events for the union of all regions that have been invalidated. Normally you would only use this function in widget implementations. You might also use it to schedule a redraw of a #GtkDrawingArea or some portion thereof. a #GtkWidget region to draw This function is only for use in widget implementations. Flags a widget to have its size renegotiated; should be called when a widget for some reason has a new size request. For example, when you change the text in a #GtkLabel, #GtkLabel queues a resize to ensure there’s enough space for the new text. Note that you cannot call gtk_widget_queue_resize() on a widget from inside its implementation of the GtkWidgetClass::size_allocate virtual method. Calls to gtk_widget_queue_resize() from inside GtkWidgetClass::size_allocate will be silently ignored. a #GtkWidget This function works like gtk_widget_queue_resize(), except that the widget is not invalidated. a #GtkWidget Creates the GDK (windowing system) resources associated with a widget. For example, @widget->window will be created when a widget is realized. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped automatically. Realizing a widget requires all the widget’s parent widgets to be realized; calling gtk_widget_realize() realizes the widget’s parents in addition to @widget itself. If a widget is not yet inside a toplevel window when you realize it, bad things will happen. This function is primarily used in widget implementations, and isn’t very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as #GtkWidget::draw. Or simply g_signal_connect () to the #GtkWidget::realize signal. a #GtkWidget Computes the intersection of a @widget’s area and @region, returning the intersection. The result may be empty, use cairo_region_is_empty() to check. Use gtk_widget_get_allocation() and cairo_region_intersect_rectangle() to get the same behavior. A newly allocated region holding the intersection of @widget and @region. a #GtkWidget a #cairo_region_t, in the same coordinate system as @widget->allocation. That is, relative to @widget->window for widgets which return %FALSE from gtk_widget_get_has_window(); relative to the parent window of @widget->window otherwise. Registers a #GdkWindow with the widget and sets it up so that the widget receives events for it. Call gtk_widget_unregister_window() when destroying the window. Before 3.8 you needed to call gdk_window_set_user_data() directly to set this up. This is now deprecated and you should use gtk_widget_register_window() instead. Old code will keep working as is, although some new features like transparency might not work perfectly. a #GtkWidget a #GdkWindow Removes an accelerator from @widget, previously installed with gtk_widget_add_accelerator(). whether an accelerator was installed and could be removed widget to install an accelerator on accel group for this widget GDK keyval of the accelerator modifier key combination of the accelerator Removes a widget from the list of mnemonic labels for this widget. (See gtk_widget_list_mnemonic_labels()). The widget must have previously been added to the list with gtk_widget_add_mnemonic_label(). a #GtkWidget a #GtkWidget that was previously set as a mnemonic label for @widget with gtk_widget_add_mnemonic_label(). Removes a tick callback previously registered with gtk_widget_add_tick_callback(). a #GtkWidget an id returned by gtk_widget_add_tick_callback() A convenience function that uses the theme settings for @widget to look up @stock_id and render it to a pixbuf. @stock_id should be a stock icon ID such as #GTK_STOCK_OPEN or #GTK_STOCK_OK. @size should be a size such as #GTK_ICON_SIZE_MENU. @detail should be a string that identifies the widget or code doing the rendering, so that theme engines can special-case rendering for that widget or code. The pixels in the returned #GdkPixbuf are shared with the rest of the application and should not be modified. The pixbuf should be freed after use with g_object_unref(). Use gtk_widget_render_icon_pixbuf() instead. a new pixbuf, or %NULL if the stock ID wasn’t known a #GtkWidget a stock ID a stock size (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale (if there are multiple source sizes, GTK+ picks one of the available sizes). render detail to pass to theme engine A convenience function that uses the theme engine and style settings for @widget to look up @stock_id and render it to a pixbuf. @stock_id should be a stock icon ID such as #GTK_STOCK_OPEN or #GTK_STOCK_OK. @size should be a size such as #GTK_ICON_SIZE_MENU. The pixels in the returned #GdkPixbuf are shared with the rest of the application and should not be modified. The pixbuf should be freed after use with g_object_unref(). Use gtk_icon_theme_load_icon() instead. a new pixbuf, or %NULL if the stock ID wasn’t known a #GtkWidget a stock ID a stock size (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale (if there are multiple source sizes, GTK+ picks one of the available sizes). Moves a widget from one #GtkContainer to another, handling reference count issues to avoid destroying the widget. Use gtk_container_remove() and gtk_container_add(). a #GtkWidget a #GtkContainer to move the widget into Reset the styles of @widget and all descendents, so when they are looked up again, they get the correct values for the currently loaded RC file settings. This function is not useful for applications. Use #GtkStyleContext instead, and gtk_widget_reset_style() a #GtkWidget. Updates the style context of @widget and all descendants by updating its widget path. #GtkContainers may want to use this on a child when reordering it in a way that a different style might apply to it. See also gtk_container_get_path_for_child(). a #GtkWidget Very rarely-used function. This function is used to emit an expose event on a widget. This function is not normally used directly. The only time it is used is when propagating an expose event to a windowless child widget (gtk_widget_get_has_window() is %FALSE), and that is normally done using gtk_container_propagate_draw(). If you want to force an area of a window to be redrawn, use gdk_window_invalidate_rect() or gdk_window_invalidate_region(). To cause the redraw to be done immediately, follow that call with a call to gdk_window_process_updates(). Application and widget code should not handle expose events directly; invalidation should use the #GtkWidget API, and drawing should only happen inside #GtkWidget::draw implementations return from the event signal emission (%TRUE if the event was handled) a #GtkWidget a expose #GdkEvent Sends the focus change @event to @widget This function is not meant to be used by applications. The only time it should be used is when it is necessary for a #GtkWidget to assign focus to a widget that is semantically owned by the first widget even though it’s not a direct child - for instance, a search entry in a floating window similar to the quick search in #GtkTreeView. An example of its usage is: |[<!-- language="C" --> GdkEvent *fevent = gdk_event_new (GDK_FOCUS_CHANGE); fevent->focus_change.type = GDK_FOCUS_CHANGE; fevent->focus_change.in = TRUE; fevent->focus_change.window = _gtk_widget_get_window (widget); if (fevent->focus_change.window != NULL) g_object_ref (fevent->focus_change.window); gtk_widget_send_focus_change (widget, fevent); gdk_event_free (event); ]| the return value from the event signal emission: %TRUE if the event was handled, and %FALSE otherwise a #GtkWidget a #GdkEvent of type GDK_FOCUS_CHANGE Given an accelerator group, @accel_group, and an accelerator path, @accel_path, sets up an accelerator in @accel_group so whenever the key binding that is defined for @accel_path is pressed, @widget will be activated. This removes any accelerators (for any accelerator group) installed by previous calls to gtk_widget_set_accel_path(). Associating accelerators with paths allows them to be modified by the user and the modifications to be saved for future use. (See gtk_accel_map_save().) This function is a low level function that would most likely be used by a menu creation system like #GtkUIManager. If you use #GtkUIManager, setting up accelerator paths will be done automatically. Even when you you aren’t using #GtkUIManager, if you only want to set up accelerators on menu items gtk_menu_item_set_accel_path() provides a somewhat more convenient interface. Note that @accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). a #GtkWidget path used to look up the accelerator a #GtkAccelGroup. Sets the widget’s allocation. This should not be used directly, but from within a widget’s size_allocate method. The allocation set should be the “adjusted” or actual allocation. If you’re implementing a #GtkContainer, you want to use gtk_widget_size_allocate() instead of gtk_widget_set_allocation(). The GtkWidgetClass::adjust_size_allocation virtual method adjusts the allocation inside gtk_widget_size_allocate() to create an adjusted allocation. a #GtkWidget a pointer to a #GtkAllocation to copy from Sets whether the application intends to draw on the widget in an #GtkWidget::draw handler. This is a hint to the widget and does not affect the behavior of the GTK+ core; many widgets ignore this flag entirely. For widgets that do pay attention to the flag, such as #GtkEventBox and #GtkWindow, the effect is to suppress default themed drawing of the widget's background. (Children of the widget will still be drawn.) The application is then entirely responsible for drawing the widget background. Note that the background is still drawn when the widget is mapped. a #GtkWidget %TRUE if the application will paint on the widget Specifies whether @widget can be a default widget. See gtk_widget_grab_default() for details about the meaning of “default”. a #GtkWidget whether or not @widget can be a default widget. Specifies whether @widget can own the input focus. See gtk_widget_grab_focus() for actually setting the input focus on a widget. a #GtkWidget whether or not @widget can own the input focus. Sets whether @widget should be mapped along with its when its parent is mapped and @widget has been shown with gtk_widget_show(). The child visibility can be set for widget before it is added to a container with gtk_widget_set_parent(), to avoid mapping children unnecessary before immediately unmapping them. However it will be reset to its default state of %TRUE when the widget is removed from a container. Note that changing the child visibility of a widget does not queue a resize on the widget. Most of the time, the size of a widget is computed from all visible children, whether or not they are mapped. If this is not the case, the container can queue a resize itself. This function is only useful for container implementations and never should be called by an application. a #GtkWidget if %TRUE, @widget should be mapped along with its parent. Sets the widget’s clip. This must not be used directly, but from within a widget’s size_allocate method. It must be called after gtk_widget_set_allocation() (or after chaining up to the parent class), because that function resets the clip. The clip set should be the area that @widget draws on. If @widget is a #GtkContainer, the area must contain all children's clips. If this function is not called by @widget during a ::size-allocate handler, the clip will be set to @widget's allocation. a #GtkWidget a pointer to a #GtkAllocation to copy from Sets a widgets composite name. The widget must be a composite child of its parent; see gtk_widget_push_composite_child(). Use gtk_widget_class_set_template(), or don’t use this API at all. a #GtkWidget. the name to set Enables or disables a #GdkDevice to interact with @widget and all its children. It does so by descending through the #GdkWindow hierarchy and enabling the same mask that is has for core events (i.e. the one that gdk_window_get_events() returns). a #GtkWidget a #GdkDevice whether to enable the device Sets the device event mask (see #GdkEventMask) for a widget. The event mask determines which events a widget will receive from @device. Keep in mind that different widgets have different default event masks, and by changing the event mask you may disrupt a widget’s functionality, so be careful. This function must be called while a widget is unrealized. Consider gtk_widget_add_device_events() for widgets that are already realized, or if you want to preserve the existing event mask. This function can’t be used with windowless widgets (which return %FALSE from gtk_widget_get_has_window()); to get events on those widgets, place them inside a #GtkEventBox and receive events on the event box. a #GtkWidget a #GdkDevice event mask Sets the reading direction on a particular widget. This direction controls the primary direction for widgets containing text, and also the direction in which the children of a container are packed. The ability to set the direction is present in order so that correct localization into languages with right-to-left reading directions can be done. Generally, applications will let the default reading direction present, except for containers where the containers are arranged in an order that is explicitly visual rather than logical (such as buttons for text justification). If the direction is set to %GTK_TEXT_DIR_NONE, then the value set by gtk_widget_set_default_direction() will be used. a #GtkWidget the new direction Widgets are double buffered by default; you can use this function to turn off the buffering. “Double buffered” simply means that gdk_window_begin_draw_frame() and gdk_window_end_draw_frame() are called automatically around expose events sent to the widget. gdk_window_begin_draw_frame() diverts all drawing to a widget's window to an offscreen buffer, and gdk_window_end_draw_frame() draws the buffer to the screen. The result is that users see the window update in one smooth step, and don’t see individual graphics primitives being rendered. In very simple terms, double buffered widgets don’t flicker, so you would only use this function to turn off double buffering if you had special needs and really knew what you were doing. Note: if you turn off double-buffering, you have to handle expose events, since even the clearing to the background color or pixmap will not happen automatically (as it is done in gdk_window_begin_draw_frame()). In 3.10 GTK and GDK have been restructured for translucent drawing. Since then expose events for double-buffered widgets are culled into a single event to the toplevel GDK window. If you now unset double buffering, you will cause a separate rendering pass for every widget. This will likely cause rendering problems - in particular related to stacking - and usually increases rendering times significantly. This function does not work under non-X11 backends or with non-native windows. It should not be used in newly written code. a #GtkWidget %TRUE to double-buffer a widget Sets the event mask (see #GdkEventMask) for a widget. The event mask determines which events a widget will receive. Keep in mind that different widgets have different default event masks, and by changing the event mask you may disrupt a widget’s functionality, so be careful. This function must be called while a widget is unrealized. Consider gtk_widget_add_events() for widgets that are already realized, or if you want to preserve the existing event mask. This function can’t be used with widgets that have no window. (See gtk_widget_get_has_window()). To get events on those widgets, place them inside a #GtkEventBox and receive events on the event box. a #GtkWidget event mask Sets whether the widget should grab focus when it is clicked with the mouse. Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard focus removed from the main area of the application. a #GtkWidget whether the widget should grab focus when clicked with the mouse Sets the font map to use for Pango rendering. When not set, the widget will inherit the font map from its parent. a #GtkWidget a #PangoFontMap, or %NULL to unset any previously set font map Sets the #cairo_font_options_t used for Pango rendering in this widget. When not set, the default font options for the #GdkScreen will be used. a #GtkWidget a #cairo_font_options_t, or %NULL to unset any previously set default font options. Sets the horizontal alignment of @widget. See the #GtkWidget:halign property. a #GtkWidget the horizontal alignment Sets the has-tooltip property on @widget to @has_tooltip. See #GtkWidget:has-tooltip for more information. a #GtkWidget whether or not @widget has a tooltip. Specifies whether @widget has a #GdkWindow of its own. Note that all realized widgets have a non-%NULL “window” pointer (gtk_widget_get_window() never returns a %NULL window when a widget is realized), but for many of them it’s actually the #GdkWindow of one of its parent widgets. Widgets that do not create a %window for themselves in #GtkWidget::realize must announce this by calling this function with @has_window = %FALSE. This function should only be called by widget implementations, and they should call it in their init() function. a #GtkWidget whether or not @widget has a window. Sets whether the widget would like any available extra horizontal space. When a user resizes a #GtkWindow, widgets with expand=TRUE generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand. Call this function to set the expand flag if you would like your widget to become larger horizontally when the window has extra room. By default, widgets automatically expand if any of their children want to expand. (To see if a widget will automatically expand given its current children and state, call gtk_widget_compute_expand(). A container can decide how the expandability of children affects the expansion of the container by overriding the compute_expand virtual method on #GtkWidget.). Setting hexpand explicitly with this function will override the automatic expand behavior. This function forces the widget to expand or not to expand, regardless of children. The override occurs because gtk_widget_set_hexpand() sets the hexpand-set property (see gtk_widget_set_hexpand_set()) which causes the widget’s hexpand value to be used, rather than looking at children and widget state. the widget whether to expand Sets whether the hexpand flag (see gtk_widget_get_hexpand()) will be used. The hexpand-set property will be set automatically when you call gtk_widget_set_hexpand() to set hexpand, so the most likely reason to use this function would be to unset an explicit expand flag. If hexpand is set, then it overrides any computed expand value based on child widgets. If hexpand is not set, then the expand value depends on whether any children of the widget would like to expand. There are few reasons to use this function, but it’s here for completeness and consistency. the widget value for hexpand-set property Marks the widget as being mapped. This function should only ever be called in a derived widget's “map” or “unmap” implementation. a #GtkWidget %TRUE to mark the widget as mapped Sets the bottom margin of @widget. See the #GtkWidget:margin-bottom property. a #GtkWidget the bottom margin Sets the end margin of @widget. See the #GtkWidget:margin-end property. a #GtkWidget the end margin Sets the left margin of @widget. See the #GtkWidget:margin-left property. Use gtk_widget_set_margin_start() instead. a #GtkWidget the left margin Sets the right margin of @widget. See the #GtkWidget:margin-right property. Use gtk_widget_set_margin_end() instead. a #GtkWidget the right margin Sets the start margin of @widget. See the #GtkWidget:margin-start property. a #GtkWidget the start margin Sets the top margin of @widget. See the #GtkWidget:margin-top property. a #GtkWidget the top margin Widgets can be named, which allows you to refer to them from a CSS file. You can apply a style to widgets with a particular name in the CSS file. See the documentation for the CSS syntax (on the same page as the docs for #GtkStyleContext). Note that the CSS syntax has certain special characters to delimit and represent elements in a selector (period, #, >, *...), so using these will make your widget impossible to match by name. Any combination of alphanumeric symbols, dashes and underscores will suffice. a #GtkWidget name for the widget Sets the #GtkWidget:no-show-all property, which determines whether calls to gtk_widget_show_all() will affect this widget. This is mostly for use in constructing widget hierarchies with externally controlled visibility, see #GtkUIManager. a #GtkWidget the new value for the “no-show-all” property Request the @widget to be rendered partially transparent, with opacity 0 being fully transparent and 1 fully opaque. (Opacity values are clamped to the [0,1] range.). This works on both toplevel widget, and child widgets, although there are some limitations: For toplevel widgets this depends on the capabilities of the windowing system. On X11 this has any effect only on X screens with a compositing manager running. See gtk_widget_is_composited(). On Windows it should work always, although setting a window’s opacity after the window has been shown causes it to flicker once on Windows. For child widgets it doesn’t work if any affected widget has a native window, or disables double buffering. a #GtkWidget desired opacity, between 0 and 1 This function is useful only when implementing subclasses of #GtkContainer. Sets the container as the parent of @widget, and takes care of some details such as updating the state and style of the child to reflect its new location. The opposite function is gtk_widget_unparent(). a #GtkWidget parent container Sets a non default parent window for @widget. For #GtkWindow classes, setting a @parent_window effects whether the window is a toplevel window or can be embedded into other widgets. For #GtkWindow classes, this needs to be called before the window is realized. a #GtkWidget. the new parent window. Marks the widget as being realized. This function must only be called after all #GdkWindows for the @widget have been created and registered. This function should only ever be called in a derived widget's “realize” or “unrealize” implementation. a #GtkWidget %TRUE to mark the widget as realized Specifies whether @widget will be treated as the default widget within its toplevel when it has the focus, even if another widget is the default. See gtk_widget_grab_default() for details about the meaning of “default”. a #GtkWidget whether or not @widget can be a default widget. Sets whether the entire widget is queued for drawing when its size allocation changes. By default, this setting is %TRUE and the entire widget is redrawn on every size change. If your widget leaves the upper left unchanged when made bigger, turning this setting off will improve performance. Note that for widgets where gtk_widget_get_has_window() is %FALSE setting this flag to %FALSE turns off all allocation on resizing: the widget will not even redraw if its position changes; this is to allow containers that don’t draw anything to avoid excess invalidations. If you set this flag on a widget with no window that does draw on @widget->window, you are responsible for invalidating both the old and new allocation of the widget when the widget is moved and responsible for invalidating regions newly when the widget increases size. a #GtkWidget if %TRUE, the entire widget will be redrawn when it is allocated to a new size. Otherwise, only the new portion of the widget will be redrawn. Sets the sensitivity of a widget. A widget is sensitive if the user can interact with it. Insensitive widgets are “grayed out” and the user can’t interact with them. Insensitive widgets are known as “inactive”, “disabled”, or “ghosted” in some other toolkits. a #GtkWidget %TRUE to make the widget sensitive Sets the minimum size of a widget; that is, the widget’s size request will be at least @width by @height. You can use this function to force a widget to be larger than it normally would be. In most cases, gtk_window_set_default_size() is a better choice for toplevel windows than this function; setting the default size will still allow users to shrink the window. Setting the size request will force them to leave the window at least as large as the size request. When dealing with window sizes, gtk_window_set_geometry_hints() can be a useful function as well. Note the inherent danger of setting any fixed size - themes, translations into other languages, different fonts, and user action can all change the appropriate size for a given widget. So, it's basically impossible to hardcode a size that will always be correct. The size request of a widget is the smallest size a widget can accept while still functioning well and drawing itself correctly. However in some strange cases a widget may be allocated less than its requested size, and in many cases a widget may be allocated more space than it requested. If the size request in a given direction is -1 (unset), then the “natural” size request of the widget will be used instead. The size request set here does not include any margin from the #GtkWidget properties margin-left, margin-right, margin-top, and margin-bottom, but it does include pretty much all other padding or border properties set by any subclass of #GtkWidget. a #GtkWidget width @widget should request, or -1 to unset height @widget should request, or -1 to unset This function is for use in widget implementations. Sets the state of a widget (insensitive, prelighted, etc.) Usually you should set the state using wrapper functions such as gtk_widget_set_sensitive(). Use gtk_widget_set_state_flags() instead. a #GtkWidget new state for @widget This function is for use in widget implementations. Turns on flag values in the current widget state (insensitive, prelighted, etc.). This function accepts the values %GTK_STATE_FLAG_DIR_LTR and %GTK_STATE_FLAG_DIR_RTL but ignores them. If you want to set the widget's direction, use gtk_widget_set_direction(). It is worth mentioning that any other state than %GTK_STATE_FLAG_INSENSITIVE, will be propagated down to all non-internal children if @widget is a #GtkContainer, while %GTK_STATE_FLAG_INSENSITIVE itself will be propagated down to all #GtkContainer children by different means than turning on the state flag down the hierarchy, both gtk_widget_get_state_flags() and gtk_widget_is_sensitive() will make use of these. a #GtkWidget State flags to turn on Whether to clear state before turning on @flags Used to set the #GtkStyle for a widget (@widget->style). Since GTK 3, this function does nothing, the passed in style is ignored. Use #GtkStyleContext instead a #GtkWidget a #GtkStyle, or %NULL to remove the effect of a previous call to gtk_widget_set_style() and go back to the default style Enables or disables multiple pointer awareness. If this setting is %TRUE, @widget will start receiving multiple, per device enter/leave events. Note that if custom #GdkWindows are created in #GtkWidget::realize, gdk_window_set_support_multidevice() will have to be called manually on them. a #GtkWidget %TRUE to support input from multiple devices. Sets @markup as the contents of the tooltip, which is marked up with the [Pango text markup language][PangoMarkupFormat]. This function will take care of setting #GtkWidget:has-tooltip to %TRUE and of the default handler for the #GtkWidget::query-tooltip signal. See also the #GtkWidget:tooltip-markup property and gtk_tooltip_set_markup(). a #GtkWidget the contents of the tooltip for @widget, or %NULL Sets @text as the contents of the tooltip. This function will take care of setting #GtkWidget:has-tooltip to %TRUE and of the default handler for the #GtkWidget::query-tooltip signal. See also the #GtkWidget:tooltip-text property and gtk_tooltip_set_text(). a #GtkWidget the contents of the tooltip for @widget Replaces the default window used for displaying tooltips with @custom_window. GTK+ will take care of showing and hiding @custom_window at the right moment, to behave likewise as the default tooltip window. If @custom_window is %NULL, the default tooltip window will be used. a #GtkWidget a #GtkWindow, or %NULL Sets the vertical alignment of @widget. See the #GtkWidget:valign property. a #GtkWidget the vertical alignment Sets whether the widget would like any available extra vertical space. See gtk_widget_set_hexpand() for more detail. the widget whether to expand Sets whether the vexpand flag (see gtk_widget_get_vexpand()) will be used. See gtk_widget_set_hexpand_set() for more detail. the widget value for vexpand-set property Sets the visibility state of @widget. Note that setting this to %TRUE doesn’t mean the widget is actually viewable, see gtk_widget_get_visible(). This function simply calls gtk_widget_show() or gtk_widget_hide() but is nicer to use when the visibility of the widget depends on some condition. a #GtkWidget whether the widget should be shown or not Sets the visual that should be used for by widget and its children for creating #GdkWindows. The visual must be on the same #GdkScreen as returned by gtk_widget_get_screen(), so handling the #GtkWidget::screen-changed signal is necessary. Setting a new @visual will not cause @widget to recreate its windows, so you should call this function before @widget is realized. a #GtkWidget visual to be used or %NULL to unset a previous one Sets a widget’s window. This function should only be used in a widget’s #GtkWidget::realize implementation. The %window passed is usually either new window created with gdk_window_new(), or the window of its parent widget as returned by gtk_widget_get_parent_window(). Widgets must indicate whether they will create their own #GdkWindow by calling gtk_widget_set_has_window(). This is usually done in the widget’s init() function. Note that this function does not add any reference to @window. a #GtkWidget a #GdkWindow Sets a shape for this widget’s GDK window. This allows for transparent windows etc., see gdk_window_shape_combine_region() for more information. a #GtkWidget shape to be added, or %NULL to remove an existing shape Flags a widget to be displayed. Any widget that isn’t shown will not appear on the screen. If you want to show all the widgets in a container, it’s easier to call gtk_widget_show_all() on the container, instead of individually showing the widgets. Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen. When a toplevel container is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their toplevel container is realized and mapped. a #GtkWidget Recursively shows a widget, and any child widgets (if the widget is a container). a #GtkWidget Shows a widget. If the widget is an unmapped toplevel widget (i.e. a #GtkWindow that has not yet been shown), enter the main loop and wait for the window to actually be mapped. Be careful; because the main loop is running, anything can happen during this function. a #GtkWidget This function is only used by #GtkContainer subclasses, to assign a size and position to their child widgets. In this function, the allocation may be adjusted. It will be forced to a 1x1 minimum size, and the adjust_size_allocation virtual method on the child will be used to adjust the allocation. Standard adjustments include removing the widget’s margins, and applying the widget’s #GtkWidget:halign and #GtkWidget:valign properties. For baseline support in containers you need to use gtk_widget_size_allocate_with_baseline() instead. a #GtkWidget position and size to be allocated to @widget This function is only used by #GtkContainer subclasses, to assign a size, position and (optionally) baseline to their child widgets. In this function, the allocation and baseline may be adjusted. It will be forced to a 1x1 minimum size, and the adjust_size_allocation virtual and adjust_baseline_allocation methods on the child will be used to adjust the allocation and baseline. Standard adjustments include removing the widget's margins, and applying the widget’s #GtkWidget:halign and #GtkWidget:valign properties. If the child widget does not have a valign of %GTK_ALIGN_BASELINE the baseline argument is ignored and -1 is used instead. a #GtkWidget position and size to be allocated to @widget The baseline of the child, or -1 This function is typically used when implementing a #GtkContainer subclass. Obtains the preferred size of a widget. The container uses this information to arrange its child widgets and decide what size allocations to give them with gtk_widget_size_allocate(). You can also call this function from an application, with some caveats. Most notably, getting a size request requires the widget to be associated with a screen, because font information may be needed. Multihead-aware applications should keep this in mind. Also remember that the size request is not necessarily the size a widget will actually be allocated. Use gtk_widget_get_preferred_size() instead. a #GtkWidget a #GtkRequisition to be filled in This function attaches the widget’s #GtkStyle to the widget's #GdkWindow. It is a replacement for |[ widget->style = gtk_style_attach (widget->style, widget->window); ]| and should only ever be called in a derived widget’s “realize” implementation which does not chain up to its parent class' “realize” implementation, because one of the parent classes (finally #GtkWidget) would attach the style itself. This step is unnecessary with #GtkStyleContext. a #GtkWidget Gets the values of a multiple style properties of @widget. a #GtkWidget the name of the first property to get pairs of property names and locations to return the property values, starting with the location for @first_property_name, terminated by %NULL. Gets the value of a style property of @widget. a #GtkWidget the name of a style property location to return the property value Non-vararg variant of gtk_widget_style_get(). Used primarily by language bindings. a #GtkWidget the name of the first property to get a va_list of pairs of property names and locations to return the property values, starting with the location for @first_property_name. Reverts the effect of a previous call to gtk_widget_freeze_child_notify(). This causes all queued #GtkWidget::child-notify signals on @widget to be emitted. a #GtkWidget Translate coordinates relative to @src_widget’s allocation to coordinates relative to @dest_widget’s allocations. In order to perform this operation, both widgets must be realized, and must share a common toplevel. %FALSE if either widget was not realized, or there was no common ancestor. In this case, nothing is stored in *@dest_x and *@dest_y. Otherwise %TRUE. a #GtkWidget a #GtkWidget X position relative to @src_widget Y position relative to @src_widget location to store X position relative to @dest_widget location to store Y position relative to @dest_widget Triggers a tooltip query on the display where the toplevel of @widget is located. See gtk_tooltip_trigger_tooltip_query() for more information. a #GtkWidget This function is only for use in widget implementations. Causes a widget to be unmapped if it’s currently mapped. a #GtkWidget This function is only for use in widget implementations. Should be called by implementations of the remove method on #GtkContainer, to dissociate a child from the container. a #GtkWidget This function is only useful in widget implementations. Causes a widget to be unrealized (frees all GDK resources associated with the widget, such as @widget->window). a #GtkWidget Unregisters a #GdkWindow from the widget that was previously set up with gtk_widget_register_window(). You need to call this when the window is no longer used by the widget, such as when you destroy it. a #GtkWidget a #GdkWindow This function is for use in widget implementations. Turns off flag values for the current widget state (insensitive, prelighted, etc.). See gtk_widget_set_state_flags(). a #GtkWidget State flags to turn off Whether the widget is double buffered. Widgets should not use this property. Whether to expand in both directions. Setting this sets both #GtkWidget:hexpand and #GtkWidget:vexpand Whether the widget should grab focus when it is clicked with the mouse. This property is only relevant for widgets that can take focus. Before 3.20, several widgets (GtkButton, GtkFileChooserButton, GtkComboBox) implemented this property individually. How to distribute horizontal space if widget gets extra space, see #GtkAlign Enables or disables the emission of #GtkWidget::query-tooltip on @widget. A value of %TRUE indicates that @widget can have a tooltip, in this case the widget will be queried using #GtkWidget::query-tooltip to determine whether it will provide a tooltip or not. Note that setting this property to %TRUE for the first time will change the event masks of the GdkWindows of this widget to include leave-notify and motion-notify events. This cannot and will not be undone when the property is set to %FALSE again. Whether to expand horizontally. See gtk_widget_set_hexpand(). Whether to use the #GtkWidget:hexpand property. See gtk_widget_get_hexpand_set(). Sets all four sides' margin at once. If read, returns max margin on any side. Margin on bottom side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example. Margin on end of widget, horizontally. This property supports left-to-right and right-to-left text directions. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example. Margin on left side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example. Use #GtkWidget:margin-start instead. Margin on right side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example. Use #GtkWidget:margin-end instead. Margin on start of widget, horizontally. This property supports left-to-right and right-to-left text directions. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example. Margin on top side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example. The requested opacity of the widget. See gtk_widget_set_opacity() for more details about window opacity. Before 3.8 this was only available in GtkWindow The scale factor of the widget. See gtk_widget_get_scale_factor() for more details about widget scaling. The style of the widget, which contains information about how it will look (colors, etc). Use #GtkStyleContext instead Sets the text of tooltip to be the given string, which is marked up with the [Pango text markup language][PangoMarkupFormat]. Also see gtk_tooltip_set_markup(). This is a convenience property which will take care of getting the tooltip shown if the given string is not %NULL: #GtkWidget:has-tooltip will automatically be set to %TRUE and there will be taken care of #GtkWidget::query-tooltip in the default signal handler. Note that if both #GtkWidget:tooltip-text and #GtkWidget:tooltip-markup are set, the last one wins. Sets the text of tooltip to be the given string. Also see gtk_tooltip_set_text(). This is a convenience property which will take care of getting the tooltip shown if the given string is not %NULL: #GtkWidget:has-tooltip will automatically be set to %TRUE and there will be taken care of #GtkWidget::query-tooltip in the default signal handler. Note that if both #GtkWidget:tooltip-text and #GtkWidget:tooltip-markup are set, the last one wins. How to distribute vertical space if widget gets extra space, see #GtkAlign Whether to expand vertically. See gtk_widget_set_vexpand(). Whether to use the #GtkWidget:vexpand property. See gtk_widget_get_vexpand_set(). The widget's window if it is realized, %NULL otherwise. The ::button-press-event signal will be emitted when a button (typically from a mouse) is pressed. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_BUTTON_PRESS_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventButton which triggered this signal. The ::button-release-event signal will be emitted when a button (typically from a mouse) is released. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_BUTTON_RELEASE_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventButton which triggered this signal. Determines whether an accelerator that activates the signal identified by @signal_id can currently be activated. This signal is present to allow applications and derived widgets to override the default #GtkWidget handling for determining whether an accelerator can be activated. %TRUE if the signal can be activated. the ID of a signal installed on @widget The ::child-notify signal is emitted for each [child property][child-properties] that has changed on an object. The signal's detail holds the property name. the #GParamSpec of the changed child property The ::composited-changed signal is emitted when the composited status of @widgets screen changes. See gdk_screen_is_composited(). Use GdkScreen::composited-changed instead. The ::configure-event signal will be emitted when the size, position or stacking of the @widget's window has changed. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventConfigure which triggered this signal. Emitted when a redirected window belonging to @widget gets drawn into. The region/area members of the event shows what area of the redirected drawable was drawn into. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventExpose event The ::delete-event signal is emitted if a user requests that a toplevel window is closed. The default handler for this signal destroys the window. Connecting gtk_widget_hide_on_delete() to this signal will cause the window to be hidden instead, so that it can later be shown again without reconstructing it. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the event which triggered this signal Signals that all holders of a reference to the widget should release the reference that they hold. May result in finalization of the widget if all references are released. This signal is not suitable for saving widget state. The ::destroy-event signal is emitted when a #GdkWindow is destroyed. You rarely get this signal, because most widgets disconnect themselves from their window before they destroy it, so no widget owns the window at destroy time. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the event which triggered this signal The ::direction-changed signal is emitted when the text direction of a widget changes. the previous text direction of @widget The ::drag-begin signal is emitted on the drag source when a drag is started. A typical reason to connect to this signal is to set up a custom drag icon with e.g. gtk_drag_source_set_icon_pixbuf(). Note that some widgets set up a drag icon in the default handler of this signal, so you may have to use g_signal_connect_after() to override what the default handler did. the drag context The ::drag-data-delete signal is emitted on the drag source when a drag with the action %GDK_ACTION_MOVE is successfully completed. The signal handler is responsible for deleting the data that has been dropped. What "delete" means depends on the context of the drag operation. the drag context The ::drag-data-get signal is emitted on the drag source when the drop site requests the data which is dragged. It is the responsibility of the signal handler to fill @data with the data in the format which is indicated by @info. See gtk_selection_data_set() and gtk_selection_data_set_text(). the drag context the #GtkSelectionData to be filled with the dragged data the info that has been registered with the target in the #GtkTargetList the timestamp at which the data was requested The ::drag-data-received signal is emitted on the drop site when the dragged data has been received. If the data was received in order to determine whether the drop will be accepted, the handler is expected to call gdk_drag_status() and not finish the drag. If the data was received in response to a #GtkWidget::drag-drop signal (and this is the last target to be received), the handler for this signal is expected to process the received data and then call gtk_drag_finish(), setting the @success parameter depending on whether the data was processed successfully. Applications must create some means to determine why the signal was emitted and therefore whether to call gdk_drag_status() or gtk_drag_finish(). The handler may inspect the selected action with gdk_drag_context_get_selected_action() before calling gtk_drag_finish(), e.g. to implement %GDK_ACTION_ASK as shown in the following example: |[<!-- language="C" --> void drag_data_received (GtkWidget *widget, GdkDragContext *context, gint x, gint y, GtkSelectionData *data, guint info, guint time) { if ((data->length >= 0) && (data->format == 8)) { GdkDragAction action; // handle data here action = gdk_drag_context_get_selected_action (context); if (action == GDK_ACTION_ASK) { GtkWidget *dialog; gint response; dialog = gtk_message_dialog_new (NULL, GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT, GTK_MESSAGE_INFO, GTK_BUTTONS_YES_NO, "Move the data ?\n"); response = gtk_dialog_run (GTK_DIALOG (dialog)); gtk_widget_destroy (dialog); if (response == GTK_RESPONSE_YES) action = GDK_ACTION_MOVE; else action = GDK_ACTION_COPY; } gtk_drag_finish (context, TRUE, action == GDK_ACTION_MOVE, time); } else gtk_drag_finish (context, FALSE, FALSE, time); } ]| the drag context where the drop happened where the drop happened the received data the info that has been registered with the target in the #GtkTargetList the timestamp at which the data was received The ::drag-drop signal is emitted on the drop site when the user drops the data onto the widget. The signal handler must determine whether the cursor position is in a drop zone or not. If it is not in a drop zone, it returns %FALSE and no further processing is necessary. Otherwise, the handler returns %TRUE. In this case, the handler must ensure that gtk_drag_finish() is called to let the source know that the drop is done. The call to gtk_drag_finish() can be done either directly or in a #GtkWidget::drag-data-received handler which gets triggered by calling gtk_drag_get_data() to receive the data for one or more of the supported targets. whether the cursor position is in a drop zone the drag context the x coordinate of the current cursor position the y coordinate of the current cursor position the timestamp of the motion event The ::drag-end signal is emitted on the drag source when a drag is finished. A typical reason to connect to this signal is to undo things done in #GtkWidget::drag-begin. the drag context The ::drag-failed signal is emitted on the drag source when a drag has failed. The signal handler may hook custom code to handle a failed DnD operation based on the type of error, it returns %TRUE is the failure has been already handled (not showing the default "drag operation failed" animation), otherwise it returns %FALSE. %TRUE if the failed drag operation has been already handled. the drag context the result of the drag operation The ::drag-leave signal is emitted on the drop site when the cursor leaves the widget. A typical reason to connect to this signal is to undo things done in #GtkWidget::drag-motion, e.g. undo highlighting with gtk_drag_unhighlight(). Likewise, the #GtkWidget::drag-leave signal is also emitted before the ::drag-drop signal, for instance to allow cleaning up of a preview item created in the #GtkWidget::drag-motion signal handler. the drag context the timestamp of the motion event The ::drag-motion signal is emitted on the drop site when the user moves the cursor over the widget during a drag. The signal handler must determine whether the cursor position is in a drop zone or not. If it is not in a drop zone, it returns %FALSE and no further processing is necessary. Otherwise, the handler returns %TRUE. In this case, the handler is responsible for providing the necessary information for displaying feedback to the user, by calling gdk_drag_status(). If the decision whether the drop will be accepted or rejected can't be made based solely on the cursor position and the type of the data, the handler may inspect the dragged data by calling gtk_drag_get_data() and defer the gdk_drag_status() call to the #GtkWidget::drag-data-received handler. Note that you must pass #GTK_DEST_DEFAULT_DROP, #GTK_DEST_DEFAULT_MOTION or #GTK_DEST_DEFAULT_ALL to gtk_drag_dest_set() when using the drag-motion signal that way. Also note that there is no drag-enter signal. The drag receiver has to keep track of whether he has received any drag-motion signals since the last #GtkWidget::drag-leave and if not, treat the drag-motion signal as an "enter" signal. Upon an "enter", the handler will typically highlight the drop site with gtk_drag_highlight(). |[<!-- language="C" --> static void drag_motion (GtkWidget *widget, GdkDragContext *context, gint x, gint y, guint time) { GdkAtom target; PrivateData *private_data = GET_PRIVATE_DATA (widget); if (!private_data->drag_highlight) { private_data->drag_highlight = 1; gtk_drag_highlight (widget); } target = gtk_drag_dest_find_target (widget, context, NULL); if (target == GDK_NONE) gdk_drag_status (context, 0, time); else { private_data->pending_status = gdk_drag_context_get_suggested_action (context); gtk_drag_get_data (widget, context, target, time); } return TRUE; } static void drag_data_received (GtkWidget *widget, GdkDragContext *context, gint x, gint y, GtkSelectionData *selection_data, guint info, guint time) { PrivateData *private_data = GET_PRIVATE_DATA (widget); if (private_data->suggested_action) { private_data->suggested_action = 0; // We are getting this data due to a request in drag_motion, // rather than due to a request in drag_drop, so we are just // supposed to call gdk_drag_status(), not actually paste in // the data. str = gtk_selection_data_get_text (selection_data); if (!data_is_acceptable (str)) gdk_drag_status (context, 0, time); else gdk_drag_status (context, private_data->suggested_action, time); } else { // accept the drop } } ]| whether the cursor position is in a drop zone the drag context the x coordinate of the current cursor position the y coordinate of the current cursor position the timestamp of the motion event This signal is emitted when a widget is supposed to render itself. The @widget's top left corner must be painted at the origin of the passed in context and be sized to the values returned by gtk_widget_get_allocated_width() and gtk_widget_get_allocated_height(). Signal handlers connected to this signal can modify the cairo context passed as @cr in any way they like and don't need to restore it. The signal emission takes care of calling cairo_save() before and cairo_restore() after invoking the handler. The signal handler will get a @cr with a clip region already set to the widget's dirty region, i.e. to the area that needs repainting. Complicated widgets that want to avoid redrawing themselves completely can get the full extents of the clip region with gdk_cairo_get_clip_rectangle(), or they can get a finer-grained representation of the dirty region with cairo_copy_clip_rectangle_list(). %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the cairo context to draw to The ::enter-notify-event will be emitted when the pointer enters the @widget's window. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_ENTER_NOTIFY_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventCrossing which triggered this signal. The GTK+ main loop will emit three signals for each GDK event delivered to a widget: one generic ::event signal, another, more specific, signal that matches the type of event delivered (e.g. #GtkWidget::key-press-event) and finally a generic #GtkWidget::event-after signal. %TRUE to stop other handlers from being invoked for the event and to cancel the emission of the second specific ::event signal. %FALSE to propagate the event further and to allow the emission of the second signal. The ::event-after signal is emitted regardless of the return value. the #GdkEvent which triggered this signal After the emission of the #GtkWidget::event signal and (optionally) the second more specific signal, ::event-after will be emitted regardless of the previous two signals handlers return values. the #GdkEvent which triggered this signal %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. The ::focus-in-event signal will be emitted when the keyboard focus enters the @widget's window. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_FOCUS_CHANGE_MASK mask. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventFocus which triggered this signal. The ::focus-out-event signal will be emitted when the keyboard focus leaves the @widget's window. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_FOCUS_CHANGE_MASK mask. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventFocus which triggered this signal. Emitted when a pointer or keyboard grab on a window belonging to @widget gets broken. On X11, this happens when the grab window becomes unviewable (i.e. it or one of its ancestors is unmapped), or if the same application grabs the pointer or keyboard again. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventGrabBroken event The ::grab-notify signal is emitted when a widget becomes shadowed by a GTK+ grab (not a pointer or keyboard grab) on another widget, or when it becomes unshadowed due to a grab being removed. A widget is shadowed by a gtk_grab_add() when the topmost grab widget in the grab stack of its window group is not its ancestor. %FALSE if the widget becomes shadowed, %TRUE if it becomes unshadowed The ::hide signal is emitted when @widget is hidden, for example with gtk_widget_hide(). The ::hierarchy-changed signal is emitted when the anchored state of a widget changes. A widget is “anchored” when its toplevel ancestor is a #GtkWindow. This signal is emitted when a widget changes from un-anchored to anchored or vice-versa. the previous toplevel ancestor, or %NULL if the widget was previously unanchored The ::key-press-event signal is emitted when a key is pressed. The signal emission will reoccur at the key-repeat rate when the key is kept pressed. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_KEY_PRESS_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventKey which triggered this signal. The ::key-release-event signal is emitted when a key is released. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_KEY_RELEASE_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventKey which triggered this signal. Gets emitted if keyboard navigation fails. See gtk_widget_keynav_failed() for details. %TRUE if stopping keyboard navigation is fine, %FALSE if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s). the direction of movement The ::leave-notify-event will be emitted when the pointer leaves the @widget's window. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_LEAVE_NOTIFY_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventCrossing which triggered this signal. The ::map signal is emitted when @widget is going to be mapped, that is when the widget is visible (which is controlled with gtk_widget_set_visible()) and all its parents up to the toplevel widget are also visible. Once the map has occurred, #GtkWidget::map-event will be emitted. The ::map signal can be used to determine whether a widget will be drawn, for instance it can resume an animation that was stopped during the emission of #GtkWidget::unmap. The ::map-event signal will be emitted when the @widget's window is mapped. A window is mapped when it becomes visible on the screen. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventAny which triggered this signal. The default handler for this signal activates @widget if @group_cycling is %FALSE, or just makes @widget grab focus if @group_cycling is %TRUE. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. %TRUE if there are other widgets with the same mnemonic The ::motion-notify-event signal is emitted when the pointer moves over the widget's #GdkWindow. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_POINTER_MOTION_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventMotion which triggered this signal. The ::parent-set signal is emitted when a new parent has been set on a widget. the previous parent, or %NULL if the widget just got its initial parent. This signal gets emitted whenever a widget should pop up a context menu. This usually happens through the standard key binding mechanism; by pressing a certain key while a widget is focused, the user can cause the widget to pop up a menu. For example, the #GtkEntry widget creates a menu with clipboard commands. See the [Popup Menu Migration Checklist][checklist-popup-menu] for an example of how to use this signal. %TRUE if a menu was activated The ::property-notify-event signal will be emitted when a property on the @widget's window has been changed or deleted. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_PROPERTY_CHANGE_MASK mask. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventProperty which triggered this signal. To receive this signal the #GdkWindow associated to the widget needs to enable the #GDK_PROXIMITY_IN_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventProximity which triggered this signal. To receive this signal the #GdkWindow associated to the widget needs to enable the #GDK_PROXIMITY_OUT_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventProximity which triggered this signal. Emitted when #GtkWidget:has-tooltip is %TRUE and the hover timeout has expired with the cursor hovering "above" @widget; or emitted when @widget got focus in keyboard mode. Using the given coordinates, the signal handler should determine whether a tooltip should be shown for @widget. If this is the case %TRUE should be returned, %FALSE otherwise. Note that if @keyboard_mode is %TRUE, the values of @x and @y are undefined and should not be used. The signal handler is free to manipulate @tooltip with the therefore destined function calls. %TRUE if @tooltip should be shown right now, %FALSE otherwise. the x coordinate of the cursor position where the request has been emitted, relative to @widget's left side the y coordinate of the cursor position where the request has been emitted, relative to @widget's top %TRUE if the tooltip was triggered using the keyboard a #GtkTooltip The ::realize signal is emitted when @widget is associated with a #GdkWindow, which means that gtk_widget_realize() has been called or the widget has been mapped (that is, it is going to be drawn). The ::screen-changed signal gets emitted when the screen of a widget has changed. the previous screen, or %NULL if the widget was not associated with a screen before The ::scroll-event signal is emitted when a button in the 4 to 7 range is pressed. Wheel mice are usually configured to generate button press events for buttons 4 and 5 when the wheel is turned. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_SCROLL_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventScroll which triggered this signal. The ::selection-clear-event signal will be emitted when the the @widget's window has lost ownership of a selection. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventSelection which triggered this signal. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. The ::selection-request-event signal will be emitted when another client requests ownership of the selection owned by the @widget's window. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventSelection which triggered this signal. The ::show signal is emitted when @widget is shown, for example with gtk_widget_show(). %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the region which has been allocated to the widget. The ::state-changed signal is emitted when the widget state changes. See gtk_widget_get_state(). Use #GtkWidget::state-flags-changed instead. the previous state The ::state-flags-changed signal is emitted when the widget state changes, see gtk_widget_get_state_flags(). The previous state flags. The ::style-set signal is emitted when a new style has been set on a widget. Note that style-modifying functions like gtk_widget_modify_base() also cause this signal to be emitted. Note that this signal is emitted for changes to the deprecated #GtkStyle. To track changes to the #GtkStyleContext associated with a widget, use the #GtkWidget::style-updated signal. Use the #GtkWidget::style-updated signal the previous style, or %NULL if the widget just got its initial style The ::style-updated signal is a convenience signal that is emitted when the #GtkStyleContext::changed signal is emitted on the @widget's associated #GtkStyleContext as returned by gtk_widget_get_style_context(). Note that style-modifying functions like gtk_widget_override_color() also cause this signal to be emitted. The ::unmap signal is emitted when @widget is going to be unmapped, which means that either it or any of its parents up to the toplevel widget have been set as hidden. As ::unmap indicates that a widget will not be shown any longer, it can be used to, for example, stop an animation on the widget. The ::unmap-event signal will be emitted when the @widget's window is unmapped. A window is unmapped when it becomes invisible on the screen. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventAny which triggered this signal The ::unrealize signal is emitted when the #GdkWindow associated with @widget is destroyed, which means that gtk_widget_unrealize() has been called or the widget has been unmapped (that is, it is going to be hidden). The ::visibility-notify-event will be emitted when the @widget's window is obscured or unobscured. To receive this signal the #GdkWindow associated to the widget needs to enable the #GDK_VISIBILITY_NOTIFY_MASK mask. Modern composited windowing systems with pervasive transparency make it impossible to track the visibility of a window reliably, so this signal can not be guaranteed to provide useful information. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventVisibility which triggered this signal. The ::window-state-event will be emitted when the state of the toplevel window associated to the @widget changes. To receive this signal the #GdkWindow associated to the widget needs to enable the #GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventWindowState which triggered this signal. The object class structure needs to be the first element in the widget class structure in order for the class mechanism to work correctly. This allows a GtkWidgetClass pointer to be cast to a GObjectClass pointer. The signal to emit when a widget of this class is activated, gtk_widget_activate() handles the emission. Implementation of this signal is optional. Seldomly overidden. Signals that all holders of a reference to the widget should release the reference that they hold. a #GtkWidget Signal emitted when widget is shown a #GtkWidget Recursively shows a widget, and any child widgets (if the widget is a container). a #GtkWidget Signal emitted when widget is hidden. a #GtkWidget Signal emitted when widget is going to be mapped, that is when the widget is visible (which is controlled with gtk_widget_set_visible()) and all its parents up to the toplevel widget are also visible. a #GtkWidget Signal emitted when widget is going to be unmapped, which means that either it or any of its parents up to the toplevel widget have been set as hidden. a #GtkWidget Signal emitted when widget is associated with a #GdkWindow, which means that gtk_widget_realize() has been called or the widget has been mapped (that is, it is going to be drawn). a #GtkWidget Signal emitted when the GdkWindow associated with widget is destroyed, which means that gtk_widget_unrealize() has been called or the widget has been unmapped (that is, it is going to be hidden). a #GtkWidget Signal emitted to get the widget allocation. a #GtkWidget position and size to be allocated to @widget Signal emitted when the widget state changes. Deprecated: 3.0 Signal emitted when the widget state changes, see gtk_widget_get_state_flags(). Signal emitted when a new parent has been set on a widget. Signal emitted when the anchored state of a widget changes. Signal emitted when a new style has been set on a widget. Deprecated: 3.0 Signal emitted when the text direction of a widget changes. Signal emitted when a widget becomes shadowed by a GTK+ grab (not a pointer or keyboard grab) on another widget, or when it becomes unshadowed due to a grab being removed. Signal emitted for each child property that has changed on an object. a #GtkWidget the name of a child property installed on the class of @widget’s parent Signal emitted when a widget is supposed to render itself. This allows a widget to tell its parent container whether it prefers to be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH means the widget prefers to have #GtkWidgetClass.get_preferred_width() called and then #GtkWidgetClass.get_preferred_height_for_width(). %GTK_SIZE_REQUEST_CONSTANT_SIZE disables any height-for-width or width-for-height geometry management for a said widget and is the default return. It’s important to note (as described below) that any widget which trades height-for-width or width-for-height must respond properly to both of the virtual methods #GtkWidgetClass.get_preferred_height_for_width() and #GtkWidgetClass.get_preferred_width_for_height() since it might be queried in either #GtkSizeRequestMode by its parent container. The #GtkSizeRequestMode preferred by @widget. a #GtkWidget instance This is called by containers to obtain the minimum and natural height of a widget. A widget that does not actually trade any height for width or width for height only has to implement these two virtual methods (#GtkWidgetClass.get_preferred_width() and #GtkWidgetClass.get_preferred_height()). a #GtkWidget instance location to store the minimum height, or %NULL location to store the natural height, or %NULL This is analogous to #GtkWidgetClass.get_preferred_height_for_width() except that it operates in the oposite orientation. It’s rare that a widget actually does %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT requests but this can happen when, for example, a widget or container gets additional columns to compensate for a smaller allocated height. a #GtkWidget instance the height which is available for allocation location for storing the minimum width, or %NULL location for storing the natural width, or %NULL This is called by containers to obtain the minimum and natural width of a widget. A widget will never be allocated a width less than its minimum and will only ever be allocated a width greater than the natural width once all of the said widget’s siblings have received their natural widths. Furthermore, a widget will only ever be allocated a width greater than its natural width if it was configured to receive extra expand space from its parent container. a #GtkWidget instance location to store the minimum width, or %NULL location to store the natural width, or %NULL This is similar to #GtkWidgetClass.get_preferred_height() except that it is passed a contextual width to request height for. By implementing this virtual method it is possible for a #GtkLabel to tell its parent how much height would be required if the label were to be allocated a said width. a #GtkWidget instance the width which is available for allocation location for storing the minimum height, or %NULL location for storing the natural height, or %NULL Activates the @widget if @group_cycling is %FALSE, and just grabs the focus if @group_cycling is %TRUE. %TRUE if the signal has been handled a #GtkWidget %TRUE if there are other widgets with the same mnemonic Causes @widget to have the keyboard focus for the #GtkWindow it’s inside. a #GtkWidget Signal emitted when a change of focus is requested Signal emitted if keyboard navigation fails. %TRUE if stopping keyboard navigation is fine, %FALSE if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s). a #GtkWidget direction of focus movement The GTK+ main loop will emit three signals for each GDK event delivered to a widget: one generic ::event signal, another, more specific, signal that matches the type of event delivered (e.g. "key-press-event") and finally a generic "event-after" signal. return from the event signal emission (%TRUE if the event was handled) a #GtkWidget a #GdkEvent Signal will be emitted when a button (typically from a mouse) is pressed. Signal will be emitted when a button (typically from a mouse) is released. Signal emitted when a button in the 4 to 7 range is pressed. Signal emitted when the pointer moves over the widget’s #GdkWindow. Signal emitted if a user requests that a toplevel window is closed. Signal is emitted when a #GdkWindow is destroyed. Signal emitted when a key is pressed. Signal is emitted when a key is released. Signal event will be emitted when the pointer enters the widget’s window. Will be emitted when the pointer leaves the widget’s window. Signal will be emitted when the size, position or stacking of the widget’s window has changed. Signal emitted when the keyboard focus enters the widget’s window. Signal emitted when the keyboard focus leaves the widget’s window. Signal emitted when the widget’s window is mapped. Signal will be emitted when the widget’s window is unmapped. Signal will be emitted when a property on the widget’s window has been changed or deleted. Signal will be emitted when the the widget’s window has lost ownership of a selection. Signal will be emitted when another client requests ownership of the selection owned by the widget's window. Signal emitted when the widget’s window is obscured or unobscured. Signal emitted when the state of the toplevel window associated to the widget changes. Signal emitted when a redirected window belonging to widget gets drawn into. Signal emitted when a pointer or keyboard grab on a window belonging to widget gets broken. Signal emitted on the drag source when a drag is started. Signal emitted on the drag source when a drag is finished. Signal emitted on the drag source when the drop site requests the data which is dragged. Signal emitted on the drag source when a drag with the action %GDK_ACTION_MOVE is successfully completed. Signal emitted on the drop site when the cursor leaves the widget. signal emitted on the drop site when the user moves the cursor over the widget during a drag. Signal emitted on the drop site when the user drops the data onto the widget. Signal emitted on the drop site when the dragged data has been received. Signal emitted on the drag source when a drag has failed. Signal emitted whenever a widget should pop up a context menu. Returns the accessible object that describes the widget to an assistive technology. the #AtkObject associated with @widget a #GtkWidget Signal emitted when the screen of a widget has changed. Signal allows applications and derived widgets to override the default GtkWidget handling for determining whether an accelerator can be activated. %TRUE if the accelerator can be activated. a #GtkWidget the ID of a signal installed on @widget Signal emitted when the composited status of widgets screen changes. See gdk_screen_is_composited(). Signal emitted when “has-tooltip” is %TRUE and the hover timeout has expired with the cursor hovering “above” widget; or emitted when widget got focus in keyboard mode. Computes whether a container should give this widget extra space when possible. Convert an initial size request from a widget's #GtkSizeRequestMode virtual method implementations into a size request to be used by parent containers in laying out the widget. adjust_size_request adjusts from a child widget's original request to what a parent container should use for layout. The @for_size argument will be -1 if the request should not be for a particular size in the opposing orientation, i.e. if the request is not height-for-width or width-for-height. If @for_size is greater than -1, it is the proposed allocation in the opposing orientation that we need the request for. Implementations of adjust_size_request should chain up to the default implementation, which applies #GtkWidget’s margin properties and imposes any values from gtk_widget_set_size_request(). Chaining up should be last, after your subclass adjusts the request, so #GtkWidget can apply constraints and add the margin properly. Convert an initial size allocation assigned by a #GtkContainer using gtk_widget_size_allocate(), into an actual size allocation to be used by the widget. adjust_size_allocation adjusts to a child widget’s actual allocation from what a parent container computed for the child. The adjusted allocation must be entirely within the original allocation. In any custom implementation, chain up to the default #GtkWidget implementation of this method, which applies the margin and alignment properties of #GtkWidget. Chain up before performing your own adjustments so your own adjustments remove more allocation after the #GtkWidget base class has already removed margin and alignment. The natural size passed in should be adjusted in the same way as the allocated size, which allows adjustments to perform alignments or other changes based on natural size. Signal emitted when the GtkStyleContext of a widget is changed. Signal emitted when a touch event happens a #GtkWidget instance the width which is available for allocation, or -1 if none location for storing the minimum height, or %NULL location for storing the natural height, or %NULL location for storing the baseline for the minimum height, or %NULL location for storing the baseline for the natural height, or %NULL Invalidates the area of widget defined by region by calling gdk_window_invalidate_region() on the widget's window and all its child windows. a #GtkWidget region to draw Declares a @callback_symbol to handle @callback_name from the template XML defined for @widget_type. See gtk_builder_add_callback_symbol(). Note that this must be called from a composite widget classes class initializer after calling gtk_widget_class_set_template(). A #GtkWidgetClass The name of the callback as expected in the template XML The callback symbol Automatically assign an object declared in the class template XML to be set to a location on a freshly built instance’s private data, or alternatively accessible via gtk_widget_get_template_child(). The struct can point either into the public instance, then you should use G_STRUCT_OFFSET(WidgetType, member) for @struct_offset, or in the private struct, then you should use G_PRIVATE_OFFSET(WidgetType, member). An explicit strong reference will be held automatically for the duration of your instance’s life cycle, it will be released automatically when #GObjectClass.dispose() runs on your instance and if a @struct_offset that is != 0 is specified, then the automatic location in your instance public or private data will be set to %NULL. You can however access an automated child pointer the first time your classes #GObjectClass.dispose() runs, or alternatively in #GtkWidgetClass.destroy(). If @internal_child is specified, #GtkBuildableIface.get_internal_child() will be automatically implemented by the #GtkWidget class so there is no need to implement it manually. The wrapper macros gtk_widget_class_bind_template_child(), gtk_widget_class_bind_template_child_internal(), gtk_widget_class_bind_template_child_private() and gtk_widget_class_bind_template_child_internal_private() might be more convenient to use. Note that this must be called from a composite widget classes class initializer after calling gtk_widget_class_set_template(). A #GtkWidgetClass The “id” of the child defined in the template XML Whether the child should be accessible as an “internal-child” when this class is used in GtkBuilder XML The structure offset into the composite widget’s instance public or private structure where the automated child pointer should be set, or 0 to not assign the pointer. Finds a style property of a widget class by name. the #GParamSpec of the style property or %NULL if @class has no style property with that name. a #GtkWidgetClass the name of the style property to find Gets the name used by this class for matching in CSS code. See gtk_widget_class_set_css_name() for details. the CSS name of the given class class to set the name on Installs a style property on a widget class. The parser for the style property is determined by the value type of @pspec. a #GtkWidgetClass the #GParamSpec for the property Installs a style property on a widget class. a #GtkWidgetClass the #GParamSpec for the style property the parser for the style property Returns all style properties of a widget class. a newly allocated array of #GParamSpec*. The array must be freed with g_free(). a #GtkWidgetClass location to return the number of style properties found Sets the default #AtkRole to be set on accessibles created for widgets of @widget_class. Accessibles may decide to not honor this setting if their role reporting is more refined. Calls to gtk_widget_class_set_accessible_type() will reset this value. In cases where you want more fine-grained control over the role of accessibles created for @widget_class, you should provide your own accessible type and use gtk_widget_class_set_accessible_type() instead. If @role is #ATK_ROLE_INVALID, the default role will not be changed and the accessible’s default role will be used instead. This function should only be called from class init functions of widgets. class to set the accessible role for The role to use for accessibles created for @widget_class Sets the type to be used for creating accessibles for widgets of @widget_class. The given @type must be a subtype of the type used for accessibles of the parent class. This function should only be called from class init functions of widgets. class to set the accessible type for The object type that implements the accessible for @widget_class For use in language bindings, this will override the default #GtkBuilderConnectFunc to be used when parsing GtkBuilder XML from this class’s template data. Note that this must be called from a composite widget classes class initializer after calling gtk_widget_class_set_template(). A #GtkWidgetClass The #GtkBuilderConnectFunc to use when connecting signals in the class template The data to pass to @connect_func The #GDestroyNotify to free @connect_data, this will only be used at class finalization time, when no classes of type @widget_type are in use anymore. Sets the name to be used for CSS matching of widgets. If this function is not called for a given class, the name of the parent class is used. class to set the name on name to use This should be called at class initialization time to specify the GtkBuilder XML to be used to extend a widget. For convenience, gtk_widget_class_set_template_from_resource() is also provided. Note that any class that installs templates must call gtk_widget_init_template() in the widget’s instance initializer. A #GtkWidgetClass A #GBytes holding the #GtkBuilder XML A convenience function to call gtk_widget_class_set_template(). Note that any class that installs templates must call gtk_widget_init_template() in the widget’s instance initializer. A #GtkWidgetClass The name of the resource to load the template from Kinds of widget-specific help. Used by the ::show-help signal. Tooltip. What’s this. GtkWidgetPath is a boxed type that represents a widget hierarchy from the topmost widget, typically a toplevel, to any child. This widget path abstraction is used in #GtkStyleContext on behalf of the real widget in order to query style information. If you are using GTK+ widgets, you probably will not need to use this API directly, as there is gtk_widget_get_path(), and the style context returned by gtk_widget_get_style_context() will be automatically updated on widget hierarchy changes. The widget path generation is generally simple: ## Defining a button within a window |[<!-- language="C" --> { GtkWidgetPath *path; path = gtk_widget_path_new (); gtk_widget_path_append_type (path, GTK_TYPE_WINDOW); gtk_widget_path_append_type (path, GTK_TYPE_BUTTON); } ]| Although more complex information, such as widget names, or different classes (property that may be used by other widget types) and intermediate regions may be included: ## Defining the first tab widget in a notebook |[<!-- language="C" --> { GtkWidgetPath *path; guint pos; path = gtk_widget_path_new (); pos = gtk_widget_path_append_type (path, GTK_TYPE_NOTEBOOK); gtk_widget_path_iter_add_region (path, pos, "tab", GTK_REGION_EVEN | GTK_REGION_FIRST); pos = gtk_widget_path_append_type (path, GTK_TYPE_LABEL); gtk_widget_path_iter_set_name (path, pos, "first tab label"); } ]| All this information will be used to match the style information that applies to the described widget. Returns an empty widget path. A newly created, empty, #GtkWidgetPath Appends the data from @widget to the widget hierarchy represented by @path. This function is a shortcut for adding information from @widget to the given @path. This includes setting the name or adding the style classes from @widget. the position where the data was inserted a widget path the widget to append to the widget path Appends a widget type to the widget hierarchy represented by @path. the position where the element was inserted a #GtkWidgetPath widget type to append Appends a widget type with all its siblings to the widget hierarchy represented by @path. Using this function instead of gtk_widget_path_append_type() will allow the CSS theming to use sibling matches in selectors and apply :nth-child() pseudo classes. In turn, it requires a lot more care in widget implementations as widgets need to make sure to call gtk_widget_reset_style() on all involved widgets when the @siblings path changes. the position where the element was inserted. the widget path to append to a widget path describing a list of siblings. This path may not contain any siblings itself and it must not be modified afterwards. index into @siblings for where the added element is positioned. Returns a copy of @path a copy of @path a #GtkWidgetPath Decrements the reference count on @path, freeing the structure if the reference count reaches 0. a #GtkWidgetPath Returns the topmost object type, that is, the object type this path is representing. The object type a #GtkWidget Returns %TRUE if any of the parents of the widget represented in @path is of type @type, or any subtype of it. %TRUE if any parent is of type @type a #GtkWidgetPath widget type to check in parents Returns %TRUE if the widget type represented by this path is @type, or a subtype of it. %TRUE if the widget represented by @path is of type @type a #GtkWidgetPath widget type to match Adds the class @name to the widget at position @pos in the hierarchy defined in @path. See gtk_style_context_add_class(). a #GtkWidget position to modify, -1 for the path head a class name Adds the region @name to the widget at position @pos in the hierarchy defined in @path. See gtk_style_context_add_region(). Region names must only contain lowercase letters and “-”, starting always with a lowercase letter. The use of regions is deprecated. a #GtkWidgetPath position to modify, -1 for the path head region name flags affecting the region Removes all classes from the widget at position @pos in the hierarchy defined in @path. a #GtkWidget position to modify, -1 for the path head Removes all regions from the widget at position @pos in the hierarchy defined in @path. The use of regions is deprecated. a #GtkWidgetPath position to modify, -1 for the path head Returns the name corresponding to the widget found at the position @pos in the widget hierarchy defined by @path The widget name, or %NULL if none was set. a #GtkWidgetPath position to get the widget name for, -1 for the path head Returns the object name that is at position @pos in the widget hierarchy defined in @path. the name or %NULL a #GtkWidgetPath position to get the object name for, -1 for the path head Returns the object #GType that is at position @pos in the widget hierarchy defined in @path. a widget type a #GtkWidgetPath position to get the object type for, -1 for the path head Returns the index into the list of siblings for the element at @pos as returned by gtk_widget_path_iter_get_siblings(). If that function would return %NULL because the element at @pos has no siblings, this function will return 0. 0 or the index into the list of siblings for the element at @pos. a #GtkWidgetPath position to get the sibling index for, -1 for the path head Returns the list of siblings for the element at @pos. If the element was not added with siblings, %NULL is returned. %NULL or the list of siblings for the element at @pos. a #GtkWidgetPath position to get the siblings for, -1 for the path head Returns the state flags corresponding to the widget found at the position @pos in the widget hierarchy defined by @path The state flags a #GtkWidgetPath position to get the state for, -1 for the path head Returns %TRUE if the widget at position @pos has the class @name defined, %FALSE otherwise. %TRUE if the class @name is defined for the widget at @pos a #GtkWidgetPath position to query, -1 for the path head class name Returns %TRUE if the widget at position @pos has the name @name, %FALSE otherwise. %TRUE if the widget at @pos has this name a #GtkWidgetPath position to query, -1 for the path head a widget name See gtk_widget_path_iter_has_class(). This is a version that operates with GQuarks. %TRUE if the widget at @pos has the class defined. a #GtkWidgetPath position to query, -1 for the path head class name as a #GQuark See gtk_widget_path_iter_has_name(). This is a version that operates on #GQuarks. %TRUE if the widget at @pos has this name a #GtkWidgetPath position to query, -1 for the path head widget name as a #GQuark See gtk_widget_path_iter_has_region(). This is a version that operates with GQuarks. The use of regions is deprecated. %TRUE if the widget at @pos has the region defined. a #GtkWidgetPath position to query, -1 for the path head region name as a #GQuark return location for the region flags Returns %TRUE if the widget at position @pos has the class @name defined, %FALSE otherwise. The use of regions is deprecated. %TRUE if the class @name is defined for the widget at @pos a #GtkWidgetPath position to query, -1 for the path head region name return location for the region flags Returns a list with all the class names defined for the widget at position @pos in the hierarchy defined in @path. The list of classes, This is a list of strings, the #GSList contents are owned by GTK+, but you should use g_slist_free() to free the list itself. a #GtkWidgetPath position to query, -1 for the path head Returns a list with all the region names defined for the widget at position @pos in the hierarchy defined in @path. The use of regions is deprecated. The list of regions, This is a list of strings, the #GSList contents are owned by GTK+, but you should use g_slist_free() to free the list itself. a #GtkWidgetPath position to query, -1 for the path head Removes the class @name from the widget at position @pos in the hierarchy defined in @path. a #GtkWidgetPath position to modify, -1 for the path head class name Removes the region @name from the widget at position @pos in the hierarchy defined in @path. The use of regions is deprecated. a #GtkWidgetPath position to modify, -1 for the path head region name Sets the widget name for the widget found at position @pos in the widget hierarchy defined by @path. a #GtkWidgetPath position to modify, -1 for the path head widget name Sets the object name for a given position in the widget hierarchy defined by @path. When set, the object name overrides the object type when matching CSS. a #GtkWidgetPath position to modify, -1 for the path head object name to set or %NULL to unset Sets the object type for a given position in the widget hierarchy defined by @path. a #GtkWidgetPath position to modify, -1 for the path head object type to set Sets the widget name for the widget found at position @pos in the widget hierarchy defined by @path. If you want to update just a single state flag, you need to do this manually, as this function updates all state flags. ## Setting a flag |[<!-- language="C" --> gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) | flag); ]| ## Unsetting a flag |[<!-- language="C" --> gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) & ~flag); ]| a #GtkWidgetPath position to modify, -1 for the path head state flags Returns the number of #GtkWidget #GTypes between the represented widget and its topmost container. the number of elements in the path a #GtkWidgetPath Prepends a widget type to the widget hierachy represented by @path. a #GtkWidgetPath widget type to prepend Increments the reference count on @path. @path itself. a #GtkWidgetPath Dumps the widget path into a string representation. It tries to match the CSS style as closely as possible (Note that there might be paths that cannot be represented in CSS). The main use of this code is for debugging purposes, so that you can g_print() the path or dump it in a gdb session. A new string describing @path. the path Decrements the reference count on @path, freeing the structure if the reference count reaches 0. a #GtkWidgetPath A GtkWindow is a toplevel window which can contain other widgets. Windows normally have decorations that are under the control of the windowing system and allow the user to manipulate the window (resize it, move it, close it,...). # GtkWindow as GtkBuildable The GtkWindow implementation of the #GtkBuildable interface supports a custom `<accel-groups>` element, which supports any number of `<group>` elements representing the #GtkAccelGroup objects you want to add to your window (synonymous with gtk_window_add_accel_group(). It also supports the `<initial-focus>` element, whose name property names the widget to receive the focus when the window is mapped. An example of a UI definition fragment with accel groups: |[<!-- language="xml" --> <object class="GtkWindow"> <accel-groups> <group name="accelgroup1"/> </accel-groups> <initial-focus name="thunderclap"/> </object> ... <object class="GtkAccelGroup" id="accelgroup1"/> ]| The GtkWindow implementation of the #GtkBuildable interface supports setting a child as the titlebar by specifying “titlebar” as the “type” attribute of a `<child>` element. # CSS nodes |[<!-- language="plain" --> window.background ├── decoration ├── <titlebar child>.titlebar [.default-decoration] ╰── <child> ]| GtkWindow has a main CSS node with name window and style class .background, and a subnode with name decoration. Style classes that are typically used with the main CSS node are .csd (when client-side decorations are in use), .solid-csd (for client-side decorations without invisible borders), .ssd (used by mutter when rendering server-side decorations). GtkWindow also represents window states with the following style classes on the main node: .tiled, .maximized, .fullscreen. Specialized types of window often add their own discriminating style classes, such as .popup or .tooltip. GtkWindow adds the .titlebar and .default-decoration style classes to the widget that is added as a titlebar child. Creates a new #GtkWindow, which is a toplevel window that can contain other widgets. Nearly always, the type of the window should be #GTK_WINDOW_TOPLEVEL. If you’re implementing something like a popup menu from scratch (which is a bad idea, just use #GtkMenu), you might use #GTK_WINDOW_POPUP. #GTK_WINDOW_POPUP is not for dialogs, though in some other toolkits dialogs are called “popups”. In GTK+, #GTK_WINDOW_POPUP means a pop-up menu or pop-up tooltip. On X11, popup windows are not controlled by the [window manager][gtk-X11-arch]. If you simply want an undecorated window (no window borders), use gtk_window_set_decorated(), don’t use #GTK_WINDOW_POPUP. All top-level windows created by gtk_window_new() are stored in an internal top-level window list. This list can be obtained from gtk_window_list_toplevels(). Due to Gtk+ keeping a reference to the window internally, gtk_window_new() does not return a reference to the caller. To delete a #GtkWindow, call gtk_widget_destroy(). a new #GtkWindow. type of window Gets the value set by gtk_window_set_default_icon_list(). The list is a copy and should be freed with g_list_free(), but the pixbufs in the list have not had their reference count incremented. copy of default icon list Returns the fallback icon name for windows that has been set with gtk_window_set_default_icon_name(). The returned string is owned by GTK+ and should not be modified. It is only valid until the next call to gtk_window_set_default_icon_name(). the fallback icon name for windows Returns a list of all existing toplevel windows. The widgets in the list are not individually referenced. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets, you must call `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first, and then unref all the widgets afterwards. list of toplevel widgets By default, after showing the first #GtkWindow, GTK+ calls gdk_notify_startup_complete(). Call this function to disable the automatic startup notification. You might do this if your first window is a splash screen, and you want to delay notification until after your real main window has been shown, for example. In that example, you would disable startup notification temporarily, show your splash screen, then re-enable it so that showing the main window would automatically result in notification. %TRUE to automatically do startup notification Sets an icon to be used as fallback for windows that haven't had gtk_window_set_icon() called on them from a pixbuf. the icon Sets an icon to be used as fallback for windows that haven't had gtk_window_set_icon_list() called on them from a file on disk. Warns on failure if @err is %NULL. %TRUE if setting the icon succeeded. location of icon file Sets an icon list to be used as fallback for windows that haven't had gtk_window_set_icon_list() called on them to set up a window-specific icon list. This function allows you to set up the icon for all windows in your app at once. See gtk_window_set_icon_list() for more details. a list of #GdkPixbuf Sets an icon to be used as fallback for windows that haven't had gtk_window_set_icon_list() called on them from a named themed icon, see gtk_window_set_icon_name(). the name of the themed icon Opens or closes the [interactive debugger][interactive-debugging], which offers access to the widget hierarchy of the application and to useful debugging tools. %TRUE to enable interactive debugging Activates the default widget for the window. Activates the current focused widget within the window. Class handler for the #GtkWindow::enable-debugging keybinding signal. Since: 3.14 Signal gets emitted when the set of accelerators or mnemonics that are associated with window changes. If @focus is not the current focus widget, and is focusable, sets it as the focus widget for the window. If @focus is %NULL, unsets the focus widget for this window. To set the focus to a particular widget in the toplevel, it is usually more convenient to use gtk_widget_grab_focus() instead of this function. a #GtkWindow widget to be the new focus widget, or %NULL to unset any focus widget for the toplevel window. Activates the default widget for the window, unless the current focused widget has been configured to receive the default action (see gtk_widget_set_receives_default()), in which case the focused widget is activated. %TRUE if a widget got activated. a #GtkWindow Activates the current focused widget within the window. %TRUE if a widget got activated. a #GtkWindow Activates mnemonics and accelerators for this #GtkWindow. This is normally called by the default ::key_press_event handler for toplevel windows, however in some cases it may be useful to call this directly when overriding the standard key handling for a toplevel window. %TRUE if a mnemonic or accelerator was found and activated. a #GtkWindow a #GdkEventKey Associate @accel_group with @window, such that calling gtk_accel_groups_activate() on @window will activate accelerators in @accel_group. window to attach accelerator group to a #GtkAccelGroup Adds a mnemonic to this window. a #GtkWindow the mnemonic the widget that gets activated by the mnemonic Starts moving a window. This function is used if an application has window movement grips. When GDK can support it, the window movement will be done using the standard mechanism for the [window manager][gtk-X11-arch] or windowing system. Otherwise, GDK will try to emulate window movement, potentially not all that well, depending on the windowing system. a #GtkWindow mouse button that initiated the drag X position where the user clicked to initiate the drag, in root window coordinates Y position where the user clicked to initiate the drag timestamp from the click event that initiated the drag Starts resizing a window. This function is used if an application has window resizing controls. When GDK can support it, the resize will be done using the standard mechanism for the [window manager][gtk-X11-arch] or windowing system. Otherwise, GDK will try to emulate window resizing, potentially not all that well, depending on the windowing system. a #GtkWindow position of the resize control mouse button that initiated the drag X position where the user clicked to initiate the drag, in root window coordinates Y position where the user clicked to initiate the drag timestamp from the click event that initiated the drag Requests that the window is closed, similar to what happens when a window manager close button is clicked. This function can be used with close buttons in custom titlebars. a #GtkWindow Asks to deiconify (i.e. unminimize) the specified @window. Note that you shouldn’t assume the window is definitely deiconified afterward, because other entities (e.g. the user or [window manager][gtk-X11-arch])) could iconify it again before your code which assumes deiconification gets to run. You can track iconification via the “window-state-event” signal on #GtkWidget. a #GtkWindow Asks to place @window in the fullscreen state. Note that you shouldn’t assume the window is definitely full screen afterward, because other entities (e.g. the user or [window manager][gtk-X11-arch]) could unfullscreen it again, and not all window managers honor requests to fullscreen windows. But normally the window will end up fullscreen. Just don’t write code that crashes if not. You can track the fullscreen state via the “window-state-event” signal on #GtkWidget. a #GtkWindow Asks to place @window in the fullscreen state. Note that you shouldn't assume the window is definitely full screen afterward. You can track the fullscreen state via the "window-state-event" signal on #GtkWidget. a #GtkWindow a #GdkScreen to draw to which monitor to go fullscreen on Gets the value set by gtk_window_set_accept_focus(). %TRUE if window should receive the input focus a #GtkWindow Gets the #GtkApplication associated with the window (if any). a #GtkApplication, or %NULL a #GtkWindow Fetches the attach widget for this window. See gtk_window_set_attached_to(). the widget where the window is attached, or %NULL if the window is not attached to any widget. a #GtkWindow Returns whether the window has been set to have decorations such as a title bar via gtk_window_set_decorated(). %TRUE if the window has been set to have decorations a #GtkWindow Gets the default size of the window. A value of -1 for the width or height indicates that a default size has not been explicitly set for that dimension, so the “natural” size of the window will be used. a #GtkWindow location to store the default width, or %NULL location to store the default height, or %NULL Returns the default widget for @window. See gtk_window_set_default() for more details. the default widget, or %NULL if there is none. a #GtkWindow Returns whether the window has been set to have a close button via gtk_window_set_deletable(). %TRUE if the window has been set to have a close button a #GtkWindow Returns whether the window will be destroyed with its transient parent. See gtk_window_set_destroy_with_parent (). %TRUE if the window will be destroyed with its transient parent. a #GtkWindow Retrieves the current focused widget within the window. Note that this is the widget that would have the focus if the toplevel window focused; if the toplevel window is not focused then `gtk_widget_has_focus (widget)` will not be %TRUE for the widget. the currently focused widget, or %NULL if there is none. a #GtkWindow Gets the value set by gtk_window_set_focus_on_map(). %TRUE if window should receive the input focus when mapped. a #GtkWindow Gets the value of the #GtkWindow:focus-visible property. %TRUE if “focus rectangles” are supposed to be visible in this window. a #GtkWindow Gets the value set by gtk_window_set_gravity(). window gravity a #GtkWindow Returns the group for @window or the default group, if @window is %NULL or if @window does not have an explicit window group. the #GtkWindowGroup for a window or the default group a #GtkWindow, or %NULL Determines whether the window may have a resize grip. Resize grips have been removed. %TRUE if the window has a resize grip a #GtkWindow Returns whether the window has requested to have its titlebar hidden when maximized. See gtk_window_set_hide_titlebar_when_maximized (). %TRUE if the window has requested to have its titlebar hidden when maximized a #GtkWindow Gets the value set by gtk_window_set_icon() (or if you've called gtk_window_set_icon_list(), gets the first icon in the icon list). icon for window or %NULL if none a #GtkWindow Retrieves the list of icons set by gtk_window_set_icon_list(). The list is copied, but the reference count on each member won’t be incremented. copy of window’s icon list a #GtkWindow Returns the name of the themed icon for the window, see gtk_window_set_icon_name(). the icon name or %NULL if the window has no themed icon a #GtkWindow Returns the mnemonic modifier for this window. See gtk_window_set_mnemonic_modifier(). the modifier mask used to activate mnemonics on this window. a #GtkWindow Gets the value of the #GtkWindow:mnemonics-visible property. %TRUE if mnemonics are supposed to be visible in this window. a #GtkWindow Returns whether the window is modal. See gtk_window_set_modal(). %TRUE if the window is set to be modal and establishes a grab when shown a #GtkWindow Fetches the requested opacity for this window. See gtk_window_set_opacity(). Use gtk_widget_get_opacity instead. the requested opacity for this window. a #GtkWindow This function returns the position you need to pass to gtk_window_move() to keep @window in its current position. This means that the meaning of the returned value varies with window gravity. See gtk_window_move() for more details. The reliability of this function depends on the windowing system currently in use. Some windowing systems, such as Wayland, do not support a global coordinate system, and thus the position of the window will always be (0, 0). Others, like X11, do not have a reliable way to obtain the geometry of the decorations of a window if they are provided by the window manager. Additionally, on X11, window manager have been known to mismanage window gravity, which result in windows moving even if you use the coordinates of the current position as returned by this function. If you haven’t changed the window gravity, its gravity will be #GDK_GRAVITY_NORTH_WEST. This means that gtk_window_get_position() gets the position of the top-left corner of the window manager frame for the window. gtk_window_move() sets the position of this same top-left corner. If a window has gravity #GDK_GRAVITY_STATIC the window manager frame is not relevant, and thus gtk_window_get_position() will always produce accurate results. However you can’t use static gravity to do things like place a window in a corner of the screen, because static gravity ignores the window manager decorations. Ideally, this function should return appropriate values if the window has client side decorations, assuming that the windowing system supports global coordinates. In practice, saving the window position should not be left to applications, as they lack enough knowledge of the windowing system and the window manager state to effectively do so. The appropriate way to implement saving the window position is to use a platform-specific protocol, wherever that is available. a #GtkWindow return location for X coordinate of gravity-determined reference point, or %NULL return location for Y coordinate of gravity-determined reference point, or %NULL Gets the value set by gtk_window_set_resizable(). %TRUE if the user can resize the window a #GtkWindow If a window has a resize grip, this will retrieve the grip position, width and height into the specified #GdkRectangle. Resize grips have been removed. %TRUE if the resize grip’s area was retrieved a #GtkWindow a pointer to a #GdkRectangle which we should store the resize grip area Returns the role of the window. See gtk_window_set_role() for further explanation. the role of the window if set, or %NULL. The returned is owned by the widget and must not be modified or freed. a #GtkWindow Returns the #GdkScreen associated with @window. a #GdkScreen. a #GtkWindow. Obtains the current size of @window. If @window is not visible on screen, this function return the size GTK+ will suggest to the [window manager][gtk-X11-arch] for the initial window size (but this is not reliably the same as the size the window manager will actually select). See: gtk_window_set_default_size(). Depending on the windowing system and the window manager constraints, the size returned by this function may not match the size set using gtk_window_resize(); additionally, since gtk_window_resize() may be implemented as an asynchronous operation, GTK+ cannot guarantee in any way that this code: |[<!-- language="C" --> // width and height are set elsewhere gtk_window_resize (window, width, height); int new_width, new_height; gtk_window_get_size (window, &new_width, &new_height); ]| will result in `new_width` and `new_height` matching `width` and `height`, respectively. This function will return the logical size of the #GtkWindow, excluding the widgets used in client side decorations; there is, however, no guarantee that the result will be completely accurate because client side decoration may include widgets that depend on the user preferences and that may not be visibile at the time you call this function. The dimensions returned by this function are suitable for being stored across sessions; use gtk_window_set_default_size() to restore them when before showing the window. To avoid potential race conditions, you should only call this function in response to a size change notification, for instance inside a handler for the #GtkWidget::size-allocate signal, or inside a handler for the #GtkWidget::configure-event signal: |[<!-- language="C" --> static void on_size_allocate (GtkWidget *widget, GtkAllocation *allocation) { int new_width, new_height; gtk_window_get_size (GTK_WINDOW (widget), &new_width, &new_height); ... } ]| Note that, if you connect to the #GtkWidget::size-allocate signal, you should not use the dimensions of the #GtkAllocation passed to the signal handler, as the allocation may contain client side decorations added by GTK+, depending on the windowing system in use. If you are getting a window size in order to position the window on the screen, you should, instead, simply set the window’s semantic type with gtk_window_set_type_hint(), which allows the window manager to e.g. center dialogs. Also, if you set the transient parent of dialogs with gtk_window_set_transient_for() window managers will often center the dialog over its parent window. It's much preferred to let the window manager handle these cases rather than doing it yourself, because all apps will behave consistently and according to user or system preferences, if the window manager handles it. Also, the window manager can take into account the size of the window decorations and border that it may add, and of which GTK+ has no knowledge. Additionally, positioning windows in global screen coordinates may not be allowed by the windowing system. For more information, see: gtk_window_set_position(). a #GtkWindow return location for width, or %NULL return location for height, or %NULL Gets the value set by gtk_window_set_skip_pager_hint(). %TRUE if window shouldn’t be in pager a #GtkWindow Gets the value set by gtk_window_set_skip_taskbar_hint() %TRUE if window shouldn’t be in taskbar a #GtkWindow Retrieves the title of the window. See gtk_window_set_title(). the title of the window, or %NULL if none has been set explicitly. The returned string is owned by the widget and must not be modified or freed. a #GtkWindow Returns the custom titlebar that has been set with gtk_window_set_titlebar(). the custom titlebar, or %NULL a #GtkWindow Fetches the transient parent for this window. See gtk_window_set_transient_for(). the transient parent for this window, or %NULL if no transient parent has been set. a #GtkWindow Gets the type hint for this window. See gtk_window_set_type_hint(). the type hint for @window. a #GtkWindow Gets the value set by gtk_window_set_urgency_hint() %TRUE if window is urgent a #GtkWindow Gets the type of the window. See #GtkWindowType. the type of the window a #GtkWindow Returns whether @window has an explicit window group. %TRUE if @window has an explicit window group. Since 2.22 a #GtkWindow Returns whether the input focus is within this GtkWindow. For real toplevel windows, this is identical to gtk_window_is_active(), but for embedded windows, like #GtkPlug, the results will differ. %TRUE if the input focus is within this GtkWindow a #GtkWindow Asks to iconify (i.e. minimize) the specified @window. Note that you shouldn’t assume the window is definitely iconified afterward, because other entities (e.g. the user or [window manager][gtk-X11-arch]) could deiconify it again, or there may not be a window manager in which case iconification isn’t possible, etc. But normally the window will end up iconified. Just don’t write code that crashes if not. It’s permitted to call this function before showing a window, in which case the window will be iconified before it ever appears onscreen. You can track iconification via the “window-state-event” signal on #GtkWidget. a #GtkWindow Returns whether the window is part of the current active toplevel. (That is, the toplevel window receiving keystrokes.) The return value is %TRUE if the window is active toplevel itself, but also if it is, say, a #GtkPlug embedded in the active toplevel. You might use this function if you wanted to draw a widget differently in an active window from a widget in an inactive window. See gtk_window_has_toplevel_focus() %TRUE if the window part of the current active window. a #GtkWindow Retrieves the current maximized state of @window. Note that since maximization is ultimately handled by the window manager and happens asynchronously to an application request, you shouldn’t assume the return value of this function changing immediately (or at all), as an effect of calling gtk_window_maximize() or gtk_window_unmaximize(). whether the window has a maximized state. a #GtkWindow Asks to maximize @window, so that it becomes full-screen. Note that you shouldn’t assume the window is definitely maximized afterward, because other entities (e.g. the user or [window manager][gtk-X11-arch]) could unmaximize it again, and not all window managers support maximization. But normally the window will end up maximized. Just don’t write code that crashes if not. It’s permitted to call this function before showing a window, in which case the window will be maximized when it appears onscreen initially. You can track maximization via the “window-state-event” signal on #GtkWidget, or by listening to notifications on the #GtkWindow:is-maximized property. a #GtkWindow Activates the targets associated with the mnemonic. %TRUE if the activation is done. a #GtkWindow the mnemonic the modifiers Asks the [window manager][gtk-X11-arch] to move @window to the given position. Window managers are free to ignore this; most window managers ignore requests for initial window positions (instead using a user-defined placement algorithm) and honor requests after the window has already been shown. Note: the position is the position of the gravity-determined reference point for the window. The gravity determines two things: first, the location of the reference point in root window coordinates; and second, which point on the window is positioned at the reference point. By default the gravity is #GDK_GRAVITY_NORTH_WEST, so the reference point is simply the @x, @y supplied to gtk_window_move(). The top-left corner of the window decorations (aka window frame or border) will be placed at @x, @y. Therefore, to position a window at the top left of the screen, you want to use the default gravity (which is #GDK_GRAVITY_NORTH_WEST) and move the window to 0,0. To position a window at the bottom right corner of the screen, you would set #GDK_GRAVITY_SOUTH_EAST, which means that the reference point is at @x + the window width and @y + the window height, and the bottom-right corner of the window border will be placed at that reference point. So, to place a window in the bottom right corner you would first set gravity to south east, then write: `gtk_window_move (window, gdk_screen_width () - window_width, gdk_screen_height () - window_height)` (note that this example does not take multi-head scenarios into account). The [Extended Window Manager Hints Specification](http://www.freedesktop.org/Standards/wm-spec) has a nice table of gravities in the “implementation notes” section. The gtk_window_get_position() documentation may also be relevant. a #GtkWindow X coordinate to move window to Y coordinate to move window to Parses a standard X Window System geometry string - see the manual page for X (type “man X”) for details on this. gtk_window_parse_geometry() does work on all GTK+ ports including Win32 but is primarily intended for an X environment. If either a size or a position can be extracted from the geometry string, gtk_window_parse_geometry() returns %TRUE and calls gtk_window_set_default_size() and/or gtk_window_move() to resize/move the window. If gtk_window_parse_geometry() returns %TRUE, it will also set the #GDK_HINT_USER_POS and/or #GDK_HINT_USER_SIZE hints indicating to the window manager that the size/position of the window was user-specified. This causes most window managers to honor the geometry. Note that for gtk_window_parse_geometry() to work as expected, it has to be called when the window has its “final” size, i.e. after calling gtk_widget_show_all() on the contents and gtk_window_set_geometry_hints() on the window. |[<!-- language="C" --> #include <gtk/gtk.h> static void fill_with_content (GtkWidget *vbox) { // fill with content... } int main (int argc, char *argv[]) { GtkWidget *window, *vbox; GdkGeometry size_hints = { 100, 50, 0, 0, 100, 50, 10, 10, 0.0, 0.0, GDK_GRAVITY_NORTH_WEST }; gtk_init (&argc, &argv); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); vbox = gtk_box_new (GTK_ORIENTATION_VERTICAL, 0); gtk_container_add (GTK_CONTAINER (window), vbox); fill_with_content (vbox); gtk_widget_show_all (vbox); gtk_window_set_geometry_hints (GTK_WINDOW (window), NULL, &size_hints, GDK_HINT_MIN_SIZE | GDK_HINT_BASE_SIZE | GDK_HINT_RESIZE_INC); if (argc > 1) { gboolean res; res = gtk_window_parse_geometry (GTK_WINDOW (window), argv[1]); if (! res) fprintf (stderr, "Failed to parse “%s”\n", argv[1]); } gtk_widget_show_all (window); gtk_main (); return 0; } ]| Geometry handling in GTK is deprecated. %TRUE if string was parsed successfully a #GtkWindow geometry string Presents a window to the user. This function should not be used as when it is called, it is too late to gather a valid timestamp to allow focus stealing prevention to work correctly. a #GtkWindow Presents a window to the user. This may mean raising the window in the stacking order, deiconifying it, moving it to the current desktop, and/or giving it the keyboard focus, possibly dependent on the user’s platform, window manager, and preferences. If @window is hidden, this function calls gtk_widget_show() as well. This function should be used when the user tries to open a window that’s already open. Say for example the preferences dialog is currently open, and the user chooses Preferences from the menu a second time; use gtk_window_present() to move the already-open dialog where the user can see it. Presents a window to the user in response to a user interaction. The timestamp should be gathered when the window was requested to be shown (when clicking a link for example), rather than once the window is ready to be shown. a #GtkWindow the timestamp of the user interaction (typically a button or key press event) which triggered this call Propagate a key press or release event to the focus widget and up the focus container chain until a widget handles @event. This is normally called by the default ::key_press_event and ::key_release_event handlers for toplevel windows, however in some cases it may be useful to call this directly when overriding the standard key handling for a toplevel window. %TRUE if a widget in the focus chain handled the event. a #GtkWindow a #GdkEventKey Reverses the effects of gtk_window_add_accel_group(). a #GtkWindow a #GtkAccelGroup Removes a mnemonic from this window. a #GtkWindow the mnemonic the widget that gets activated by the mnemonic Hides @window, then reshows it, resetting the default size and position of the window. Used by GUI builders only. GUI builders can call gtk_widget_hide(), gtk_widget_unrealize() and then gtk_widget_show() on @window themselves, if they still need this functionality. a #GtkWindow Resizes the window as if the user had done so, obeying geometry constraints. The default geometry constraint is that windows may not be smaller than their size request; to override this constraint, call gtk_widget_set_size_request() to set the window's request to a smaller value. If gtk_window_resize() is called before showing a window for the first time, it overrides any default size set with gtk_window_set_default_size(). Windows may not be resized smaller than 1 by 1 pixels. When using client side decorations, GTK+ will do its best to adjust the given size so that the resulting window size matches the requested size without the title bar, borders and shadows added for the client side decorations, but there is no guarantee that the result will be totally accurate because these widgets added for client side decorations depend on the theme and may not be realized or visible at the time gtk_window_resize() is issued. If the GtkWindow has a titlebar widget (see gtk_window_set_titlebar()), then typically, gtk_window_resize() will compensate for the height of the titlebar widget only if the height is known when the resulting GtkWindow configuration is issued. For example, if new widgets are added after the GtkWindow configuration and cause the titlebar widget to grow in height, this will result in a window content smaller that specified by gtk_window_resize() and not a larger window. a #GtkWindow width in pixels to resize the window to height in pixels to resize the window to Determines whether a resize grip is visible for the specified window. Resize grips have been removed. %TRUE if a resize grip exists and is visible a #GtkWindow Like gtk_window_resize(), but @width and @height are interpreted in terms of the base size and increment set with gtk_window_set_geometry_hints. This function does nothing. Use gtk_window_resize() and compute the geometry yourself. a #GtkWindow width in resize increments to resize the window to height in resize increments to resize the window to Windows may set a hint asking the desktop environment not to receive the input focus. This function sets this hint. a #GtkWindow %TRUE to let this window receive input focus Sets or unsets the #GtkApplication associated with the window. The application will be kept alive for at least as long as it has any windows associated with it (see g_application_hold() for a way to keep it alive without windows). Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it by setting the @application to %NULL. This is equivalent to calling gtk_application_remove_window() and/or gtk_application_add_window() on the old/new applications as relevant. a #GtkWindow a #GtkApplication, or %NULL to unset Marks @window as attached to @attach_widget. This creates a logical binding between the window and the widget it belongs to, which is used by GTK+ to propagate information such as styling or accessibility to @window as if it was a children of @attach_widget. Examples of places where specifying this relation is useful are for instance a #GtkMenu created by a #GtkComboBox, a completion popup window created by #GtkEntry or a typeahead search entry created by #GtkTreeView. Note that this function should not be confused with gtk_window_set_transient_for(), which specifies a window manager relation between two toplevels instead. Passing %NULL for @attach_widget detaches the window. a #GtkWindow a #GtkWidget, or %NULL By default, windows are decorated with a title bar, resize controls, etc. Some [window managers][gtk-X11-arch] allow GTK+ to disable these decorations, creating a borderless window. If you set the decorated property to %FALSE using this function, GTK+ will do its best to convince the window manager not to decorate the window. Depending on the system, this function may not have any effect when called on a window that is already visible, so you should call it before calling gtk_widget_show(). On Windows, this function always works, since there’s no window manager policy involved. a #GtkWindow %TRUE to decorate the window The default widget is the widget that’s activated when the user presses Enter in a dialog (for example). This function sets or unsets the default widget for a #GtkWindow. When setting (rather than unsetting) the default widget it’s generally easier to call gtk_widget_grab_default() on the widget. Before making a widget the default widget, you must call gtk_widget_set_can_default() on the widget you’d like to make the default. a #GtkWindow widget to be the default, or %NULL to unset the default widget for the toplevel Like gtk_window_set_default_size(), but @width and @height are interpreted in terms of the base size and increment set with gtk_window_set_geometry_hints. This function does nothing. If you want to set a default size, use gtk_window_set_default_size() instead. a #GtkWindow width in resize increments, or -1 to unset the default width height in resize increments, or -1 to unset the default height Sets the default size of a window. If the window’s “natural” size (its size request) is larger than the default, the default will be ignored. More generally, if the default size does not obey the geometry hints for the window (gtk_window_set_geometry_hints() can be used to set these explicitly), the default size will be clamped to the nearest permitted size. Unlike gtk_widget_set_size_request(), which sets a size request for a widget and thus would keep users from shrinking the window, this function only sets the initial size, just as if the user had resized the window themselves. Users can still shrink the window again as they normally would. Setting a default size of -1 means to use the “natural” default size (the size request of the window). For more control over a window’s initial size and how resizing works, investigate gtk_window_set_geometry_hints(). For some uses, gtk_window_resize() is a more appropriate function. gtk_window_resize() changes the current size of the window, rather than the size to be used on initial display. gtk_window_resize() always affects the window itself, not the geometry widget. The default size of a window only affects the first time a window is shown; if a window is hidden and re-shown, it will remember the size it had prior to hiding, rather than using the default size. Windows can’t actually be 0x0 in size, they must be at least 1x1, but passing 0 for @width and @height is OK, resulting in a 1x1 default size. If you use this function to reestablish a previously saved window size, note that the appropriate size to save is the one returned by gtk_window_get_size(). Using the window allocation directly will not work in all circumstances and can lead to growing or shrinking windows. a #GtkWindow width in pixels, or -1 to unset the default width height in pixels, or -1 to unset the default height By default, windows have a close button in the window frame. Some [window managers][gtk-X11-arch] allow GTK+ to disable this button. If you set the deletable property to %FALSE using this function, GTK+ will do its best to convince the window manager not to show a close button. Depending on the system, this function may not have any effect when called on a window that is already visible, so you should call it before calling gtk_widget_show(). On Windows, this function always works, since there’s no window manager policy involved. a #GtkWindow %TRUE to decorate the window as deletable If @setting is %TRUE, then destroying the transient parent of @window will also destroy @window itself. This is useful for dialogs that shouldn’t persist beyond the lifetime of the main window they're associated with, for example. a #GtkWindow whether to destroy @window with its transient parent If @focus is not the current focus widget, and is focusable, sets it as the focus widget for the window. If @focus is %NULL, unsets the focus widget for this window. To set the focus to a particular widget in the toplevel, it is usually more convenient to use gtk_widget_grab_focus() instead of this function. a #GtkWindow widget to be the new focus widget, or %NULL to unset any focus widget for the toplevel window. Windows may set a hint asking the desktop environment not to receive the input focus when the window is mapped. This function sets this hint. a #GtkWindow %TRUE to let this window receive input focus on map Sets the #GtkWindow:focus-visible property. a #GtkWindow the new value This function sets up hints about how a window can be resized by the user. You can set a minimum and maximum size; allowed resize increments (e.g. for xterm, you can only resize by the size of a character); aspect ratios; and more. See the #GdkGeometry struct. a #GtkWindow widget the geometry hints used to be applied to or %NULL. Since 3.20 this argument is ignored and GTK behaves as if %NULL was set. struct containing geometry information or %NULL mask indicating which struct fields should be paid attention to Window gravity defines the meaning of coordinates passed to gtk_window_move(). See gtk_window_move() and #GdkGravity for more details. The default window gravity is #GDK_GRAVITY_NORTH_WEST which will typically “do what you mean.” a #GtkWindow window gravity Sets whether @window has a corner resize grip. Note that the resize grip is only shown if the window is actually resizable and not maximized. Use gtk_window_resize_grip_is_visible() to find out if the resize grip is currently shown. Resize grips have been removed. a #GtkWindow %TRUE to allow a resize grip Tells GTK+ whether to drop its extra reference to the window when gtk_widget_destroy() is called. This function is only exported for the benefit of language bindings which may need to keep the window alive until their wrapper object is garbage collected. There is no justification for ever calling this function in an application. a #GtkWindow the new value If @setting is %TRUE, then @window will request that it’s titlebar should be hidden when maximized. This is useful for windows that don’t convey any information other than the application name in the titlebar, to put the available screen space to better use. If the underlying window system does not support the request, the setting will not have any effect. Note that custom titlebars set with gtk_window_set_titlebar() are not affected by this. The application is in full control of their content and visibility anyway. a #GtkWindow whether to hide the titlebar when @window is maximized Sets up the icon representing a #GtkWindow. This icon is used when the window is minimized (also known as iconified). Some window managers or desktop environments may also place it in the window frame, or display it in other contexts. On others, the icon is not used at all, so your mileage may vary. The icon should be provided in whatever size it was naturally drawn; that is, don’t scale the image before passing it to GTK+. Scaling is postponed until the last minute, when the desired final size is known, to allow best quality. If you have your icon hand-drawn in multiple sizes, use gtk_window_set_icon_list(). Then the best size will be used. This function is equivalent to calling gtk_window_set_icon_list() with a 1-element list. See also gtk_window_set_default_icon_list() to set the icon for all windows in your application in one go. a #GtkWindow icon image, or %NULL Sets the icon for @window. Warns on failure if @err is %NULL. This function is equivalent to calling gtk_window_set_icon() with a pixbuf created by loading the image from @filename. %TRUE if setting the icon succeeded. a #GtkWindow location of icon file Sets up the icon representing a #GtkWindow. The icon is used when the window is minimized (also known as iconified). Some window managers or desktop environments may also place it in the window frame, or display it in other contexts. On others, the icon is not used at all, so your mileage may vary. gtk_window_set_icon_list() allows you to pass in the same icon in several hand-drawn sizes. The list should contain the natural sizes your icon is available in; that is, don’t scale the image before passing it to GTK+. Scaling is postponed until the last minute, when the desired final size is known, to allow best quality. By passing several sizes, you may improve the final image quality of the icon, by reducing or eliminating automatic image scaling. Recommended sizes to provide: 16x16, 32x32, 48x48 at minimum, and larger images (64x64, 128x128) if you have them. See also gtk_window_set_default_icon_list() to set the icon for all windows in your application in one go. Note that transient windows (those who have been set transient for another window using gtk_window_set_transient_for()) will inherit their icon from their transient parent. So there’s no need to explicitly set the icon on transient windows. a #GtkWindow list of #GdkPixbuf Sets the icon for the window from a named themed icon. See the docs for #GtkIconTheme for more details. On some platforms, the window icon is not used at all. Note that this has nothing to do with the WM_ICON_NAME property which is mentioned in the ICCCM. a #GtkWindow the name of the themed icon Asks to keep @window above, so that it stays on top. Note that you shouldn’t assume the window is definitely above afterward, because other entities (e.g. the user or [window manager][gtk-X11-arch]) could not keep it above, and not all window managers support keeping windows above. But normally the window will end kept above. Just don’t write code that crashes if not. It’s permitted to call this function before showing a window, in which case the window will be kept above when it appears onscreen initially. You can track the above state via the “window-state-event” signal on #GtkWidget. Note that, according to the [Extended Window Manager Hints Specification](http://www.freedesktop.org/Standards/wm-spec), the above state is mainly meant for user preferences and should not be used by applications e.g. for drawing attention to their dialogs. a #GtkWindow whether to keep @window above other windows Asks to keep @window below, so that it stays in bottom. Note that you shouldn’t assume the window is definitely below afterward, because other entities (e.g. the user or [window manager][gtk-X11-arch]) could not keep it below, and not all window managers support putting windows below. But normally the window will be kept below. Just don’t write code that crashes if not. It’s permitted to call this function before showing a window, in which case the window will be kept below when it appears onscreen initially. You can track the below state via the “window-state-event” signal on #GtkWidget. Note that, according to the [Extended Window Manager Hints Specification](http://www.freedesktop.org/Standards/wm-spec), the above state is mainly meant for user preferences and should not be used by applications e.g. for drawing attention to their dialogs. a #GtkWindow whether to keep @window below other windows Sets the mnemonic modifier for this window. a #GtkWindow the modifier mask used to activate mnemonics on this window. Sets the #GtkWindow:mnemonics-visible property. a #GtkWindow the new value Sets a window modal or non-modal. Modal windows prevent interaction with other windows in the same application. To keep modal dialogs on top of main application windows, use gtk_window_set_transient_for() to make the dialog transient for the parent; most [window managers][gtk-X11-arch] will then disallow lowering the dialog below the parent. a #GtkWindow whether the window is modal Request the windowing system to make @window partially transparent, with opacity 0 being fully transparent and 1 fully opaque. (Values of the opacity parameter are clamped to the [0,1] range.) On X11 this has any effect only on X screens with a compositing manager running. See gtk_widget_is_composited(). On Windows it should work always. Note that setting a window’s opacity after the window has been shown causes it to flicker once on Windows. Use gtk_widget_set_opacity instead. a #GtkWindow desired opacity, between 0 and 1 Sets a position constraint for this window. If the old or new constraint is %GTK_WIN_POS_CENTER_ALWAYS, this will also cause the window to be repositioned to satisfy the new constraint. a #GtkWindow. a position constraint. Sets whether the user can resize a window. Windows are user resizable by default. a #GtkWindow %TRUE if the user can resize this window This function is only useful on X11, not with other GTK+ targets. In combination with the window title, the window role allows a [window manager][gtk-X11-arch] to identify "the same" window when an application is restarted. So for example you might set the “toolbox” role on your app’s toolbox window, so that when the user restarts their session, the window manager can put the toolbox back in the same place. If a window already has a unique title, you don’t need to set the role, since the WM can use the title to identify the window when restoring the session. a #GtkWindow unique identifier for the window to be used when restoring a session Sets the #GdkScreen where the @window is displayed; if the window is already mapped, it will be unmapped, and then remapped on the new screen. a #GtkWindow. a #GdkScreen. Windows may set a hint asking the desktop environment not to display the window in the pager. This function sets this hint. (A "pager" is any desktop navigation tool such as a workspace switcher that displays a thumbnail representation of the windows on the screen.) a #GtkWindow %TRUE to keep this window from appearing in the pager Windows may set a hint asking the desktop environment not to display the window in the task bar. This function sets this hint. a #GtkWindow %TRUE to keep this window from appearing in the task bar Startup notification identifiers are used by desktop environment to track application startup, to provide user feedback and other features. This function changes the corresponding property on the underlying GdkWindow. Normally, startup identifier is managed automatically and you should only use this function in special cases like transferring focus from other processes. You should use this function before calling gtk_window_present() or any equivalent function generating a window map event. This function is only useful on X11, not with other GTK+ targets. a #GtkWindow a string with startup-notification identifier Sets the title of the #GtkWindow. The title of a window will be displayed in its title bar; on the X Window System, the title bar is rendered by the [window manager][gtk-X11-arch], so exactly how the title appears to users may vary according to a user’s exact configuration. The title should help a user distinguish this window from other windows they may have open. A good title might include the application name and current document filename, for example. a #GtkWindow title of the window Sets a custom titlebar for @window. A typical widget used here is #GtkHeaderBar, as it provides various features expected of a titlebar while allowing the addition of child widgets to it. If you set a custom titlebar, GTK+ will do its best to convince the window manager not to put its own titlebar on the window. Depending on the system, this function may not work for a window that is already visible, so you set the titlebar before calling gtk_widget_show(). a #GtkWindow the widget to use as titlebar Dialog windows should be set transient for the main application window they were spawned from. This allows [window managers][gtk-X11-arch] to e.g. keep the dialog on top of the main window, or center the dialog over the main window. gtk_dialog_new_with_buttons() and other convenience functions in GTK+ will sometimes call gtk_window_set_transient_for() on your behalf. Passing %NULL for @parent unsets the current transient window. On Wayland, this function can also be used to attach a new #GTK_WINDOW_POPUP to a #GTK_WINDOW_TOPLEVEL parent already mapped on screen so that the #GTK_WINDOW_POPUP will be created as a subsurface-based window #GDK_WINDOW_SUBSURFACE which can be positioned at will relatively to the #GTK_WINDOW_TOPLEVEL surface. On Windows, this function puts the child window on top of the parent, much as the window manager would have done on X. a #GtkWindow parent window, or %NULL By setting the type hint for the window, you allow the window manager to decorate and handle the window in a way which is suitable to the function of the window in your application. This function should be called before the window becomes visible. gtk_dialog_new_with_buttons() and other convenience functions in GTK+ will sometimes call gtk_window_set_type_hint() on your behalf. a #GtkWindow the window type Windows may set a hint asking the desktop environment to draw the users attention to the window. This function sets this hint. a #GtkWindow %TRUE to mark this window as urgent Don’t use this function. It sets the X Window System “class” and “name” hints for a window. According to the ICCCM, you should always set these to the same value for all windows in an application, and GTK+ sets them to that value by default, so calling this function is sort of pointless. However, you may want to call gtk_window_set_role() on each window in your application, for the benefit of the session manager. Setting the role allows the window manager to restore window positions when loading a saved session. a #GtkWindow window name hint window class hint Asks to stick @window, which means that it will appear on all user desktops. Note that you shouldn’t assume the window is definitely stuck afterward, because other entities (e.g. the user or [window manager][gtk-X11-arch] could unstick it again, and some window managers do not support sticking windows. But normally the window will end up stuck. Just don't write code that crashes if not. It’s permitted to call this function before showing a window. You can track stickiness via the “window-state-event” signal on #GtkWidget. a #GtkWindow Asks to toggle off the fullscreen state for @window. Note that you shouldn’t assume the window is definitely not full screen afterward, because other entities (e.g. the user or [window manager][gtk-X11-arch]) could fullscreen it again, and not all window managers honor requests to unfullscreen windows. But normally the window will end up restored to its normal state. Just don’t write code that crashes if not. You can track the fullscreen state via the “window-state-event” signal on #GtkWidget. a #GtkWindow Asks to unmaximize @window. Note that you shouldn’t assume the window is definitely unmaximized afterward, because other entities (e.g. the user or [window manager][gtk-X11-arch]) could maximize it again, and not all window managers honor requests to unmaximize. But normally the window will end up unmaximized. Just don’t write code that crashes if not. You can track maximization via the “window-state-event” signal on #GtkWidget. a #GtkWindow Asks to unstick @window, which means that it will appear on only one of the user’s desktops. Note that you shouldn’t assume the window is definitely unstuck afterward, because other entities (e.g. the user or [window manager][gtk-X11-arch]) could stick it again. But normally the window will end up unstuck. Just don’t write code that crashes if not. You can track stickiness via the “window-state-event” signal on #GtkWidget. a #GtkWindow Whether the window should receive the input focus. The #GtkApplication associated with the window. The application will be kept alive for at least as long as it has any windows associated with it (see g_application_hold() for a way to keep it alive without windows). Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it by setting the :application property to %NULL. The widget to which this window is attached. See gtk_window_set_attached_to(). Examples of places where specifying this relation is useful are for instance a #GtkMenu created by a #GtkComboBox, a completion popup window created by #GtkEntry or a typeahead search entry created by #GtkTreeView. Whether the window should be decorated by the window manager. Whether the window frame should have a close button. Whether the window should receive the input focus when mapped. Whether 'focus rectangles' are currently visible in this window. This property is maintained by GTK+ based on user input and should not be set by applications. The window gravity of the window. See gtk_window_move() and #GdkGravity for more details about window gravity. Whether the window has a corner resize grip. Note that the resize grip is only shown if the window is actually resizable and not maximized. Use #GtkWindow:resize-grip-visible to find out if the resize grip is currently shown. Resize grips have been removed. Whether the titlebar should be hidden during maximization. The :icon-name property specifies the name of the themed icon to use as the window icon. See #GtkIconTheme for more details. Whether mnemonics are currently visible in this window. This property is maintained by GTK+ based on user input, and should not be set by applications. Whether a corner resize grip is currently shown. Resize grips have been removed. The :startup-id is a write-only property for setting window's startup notification identifier. See gtk_window_set_startup_id() for more details. The transient parent of the window. See gtk_window_set_transient_for() for more details about transient windows. The ::activate-default signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user activates the default widget of @window. The ::activate-focus signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user activates the currently focused widget of @window. The ::enable-debugging signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user enables or disables interactive debugging. When @toggle is %TRUE, interactive debugging is toggled on or off, when it is %FALSE, the debugger will be pointed at the widget under the pointer. The default bindings for this signal are Ctrl-Shift-I and Ctrl-Shift-D. %TRUE if the key binding was handled toggle the debugger The ::keys-changed signal gets emitted when the set of accelerators or mnemonics that are associated with @window changes. This signal is emitted whenever the currently focused widget in this window changes. the newly focused widget (or %NULL for no focus) The parent class. Sets child as the focus widget for the window. a #GtkWindow widget to be the new focus widget, or %NULL to unset any focus widget for the toplevel window. Activates the current focused widget within the window. Activates the default widget for the window. Signal gets emitted when the set of accelerators or mnemonics that are associated with window changes. Class handler for the #GtkWindow::enable-debugging keybinding signal. Since: 3.14 A #GtkWindowGroup restricts the effect of grabs to windows in the same group, thereby making window groups almost behave like separate applications. A window can be a member in at most one window group at a time. Windows that have not been explicitly assigned to a group are implicitly treated like windows of the default window group. GtkWindowGroup objects are referenced by each window in the group, so once you have added all windows to a GtkWindowGroup, you can drop the initial reference to the window group with g_object_unref(). If the windows in the window group are subsequently destroyed, then they will be removed from the window group and drop their references on the window group; when all window have been removed, the window group will be freed. Creates a new #GtkWindowGroup object. Grabs added with gtk_grab_add() only affect windows within the same #GtkWindowGroup. a new #GtkWindowGroup. Adds a window to a #GtkWindowGroup. a #GtkWindowGroup the #GtkWindow to add Returns the current grab widget for @device, or %NULL if none. The grab widget, or %NULL a #GtkWindowGroup a #GdkDevice Gets the current grab widget of the given group, see gtk_grab_add(). the current grab widget of the group a #GtkWindowGroup Returns a list of the #GtkWindows that belong to @window_group. A newly-allocated list of windows inside the group. a #GtkWindowGroup Removes a window from a #GtkWindowGroup. a #GtkWindowGroup the #GtkWindow to remove Window placement can be influenced using this enumeration. Note that using #GTK_WIN_POS_CENTER_ALWAYS is almost always a bad idea. It won’t necessarily work well with all window managers or on all windowing systems. No influence is made on placement. Windows should be placed in the center of the screen. Windows should be placed at the current mouse position. Keep window centered as it changes size, etc. Center the window on its transient parent (see gtk_window_set_transient_for()). A #GtkWindow can be one of these types. Most things you’d consider a “window” should have type #GTK_WINDOW_TOPLEVEL; windows with this type are managed by the window manager and have a frame by default (call gtk_window_set_decorated() to toggle the frame). Windows with type #GTK_WINDOW_POPUP are ignored by the window manager; window manager keybindings won’t work on them, the window manager won’t decorate the window with a frame, many GTK+ features that rely on the window manager will not work (e.g. resize grips and maximization/minimization). #GTK_WINDOW_POPUP is used to implement widgets such as #GtkMenu or tooltips that you normally don’t think of as windows per se. Nearly all windows should be #GTK_WINDOW_TOPLEVEL. In particular, do not use #GTK_WINDOW_POPUP just to turn off the window borders; use gtk_window_set_decorated() for that. A regular window, such as a dialog. A special window such as a tooltip. Describes a type of line wrapping. do not wrap lines; just make the text area wider wrap text, breaking lines anywhere the cursor can appear (between characters, usually - if you want to be technical, between graphemes, see pango_get_log_attrs()) wrap text, breaking lines in between words wrap text, breaking lines in between words, or if that is not enough, also between graphemes This section contains code for working with the <link linkend="gdbus-interface-org-Gtk-MountOperationHandler.top_of_page">org.Gtk.MountOperationHandler</link> D-Bus interface in C. Abstract interface type for the D-Bus interface <link linkend="gdbus-interface-org-Gtk-MountOperationHandler.top_of_page">org.Gtk.MountOperationHandler</link>. Virtual table for the D-Bus interface <link linkend="gdbus-interface-org-Gtk-MountOperationHandler.top_of_page">org.Gtk.MountOperationHandler</link>. The parent interface. Handler for the #_GtkMountOperationHandler::handle-ask-password signal. Handler for the #_GtkMountOperationHandler::handle-ask-question signal. Handler for the #_GtkMountOperationHandler::handle-close signal. Handler for the #_GtkMountOperationHandler::handle-show-processes signal. The #_GtkMountOperationHandlerProxy structure contains only private data and should only be accessed using the provided API. Class structure for #_GtkMountOperationHandlerProxy. The parent class. The #_GtkMountOperationHandlerSkeleton structure contains only private data and should only be accessed using the provided API. Class structure for #_GtkMountOperationHandlerSkeleton. The parent class. Finds the first accelerator in any #GtkAccelGroup attached to @object that matches @accel_key and @accel_mods, and activates that accelerator. %TRUE if an accelerator was activated and handled this keypress the #GObject, usually a #GtkWindow, on which to activate the accelerator accelerator keyval from a key event keyboard state mask from a key event Gets a list of all accel groups which are attached to @object. a list of all accel groups which are attached to @object a #GObject, usually a #GtkWindow Gets the modifier mask. The modifier mask determines which modifiers are considered significant for keyboard accelerators. See gtk_accelerator_set_default_mod_mask(). the default accelerator modifier mask Converts an accelerator keyval and modifier mask into a string which can be used to represent the accelerator to the user. a newly-allocated string representing the accelerator. accelerator keyval accelerator modifier mask Converts an accelerator keyval and modifier mask into a (possibly translated) string that can be displayed to a user, similarly to gtk_accelerator_get_label(), but handling keycodes. This is only useful for system-level components, applications should use gtk_accelerator_parse() instead. a newly-allocated string representing the accelerator. a #GdkDisplay or %NULL to use the default display accelerator keyval accelerator keycode accelerator modifier mask Converts an accelerator keyval and modifier mask into a string parseable by gtk_accelerator_parse(). For example, if you pass in #GDK_KEY_q and #GDK_CONTROL_MASK, this function returns “<Control>q”. If you need to display accelerators in the user interface, see gtk_accelerator_get_label(). a newly-allocated accelerator name accelerator keyval accelerator modifier mask Converts an accelerator keyval and modifier mask into a string parseable by gtk_accelerator_parse_with_keycode(), similarly to gtk_accelerator_name() but handling keycodes. This is only useful for system-level components, applications should use gtk_accelerator_parse() instead. a newly allocated accelerator name. a #GdkDisplay or %NULL to use the default display accelerator keyval accelerator keycode accelerator modifier mask Parses a string representing an accelerator. The format looks like `<Control>a` or `<Shift><Alt>F1` or `<Release>z` (the last one is for key release). The parser is fairly liberal and allows lower or upper case, and also abbreviations such as `<Ctl>` and `<Ctrl>`. Key names are parsed using gdk_keyval_from_name(). For character keys the name is not the symbol, but the lowercase name, e.g. one would use `<Ctrl>minus` instead of `<Ctrl>-`. If the parse fails, @accelerator_key and @accelerator_mods will be set to 0 (zero). string representing an accelerator return location for accelerator keyval, or %NULL return location for accelerator modifier mask, %NULL Parses a string representing an accelerator, similarly to gtk_accelerator_parse() but handles keycodes as well. This is only useful for system-level components, applications should use gtk_accelerator_parse() instead. If @accelerator_codes is given and the result stored in it is non-%NULL, the result must be freed with g_free(). If a keycode is present in the accelerator and no @accelerator_codes is given, the parse will fail. If the parse fails, @accelerator_key, @accelerator_mods and @accelerator_codes will be set to 0 (zero). string representing an accelerator return location for accelerator keyval, or %NULL return location for accelerator keycodes, or %NULL return location for accelerator modifier mask, %NULL Sets the modifiers that will be considered significant for keyboard accelerators. The default mod mask depends on the GDK backend in use, but will typically include #GDK_CONTROL_MASK | #GDK_SHIFT_MASK | #GDK_MOD1_MASK | #GDK_SUPER_MASK | #GDK_HYPER_MASK | #GDK_META_MASK. In other words, Control, Shift, Alt, Super, Hyper and Meta. Other modifiers will by default be ignored by #GtkAccelGroup. You must include at least the three modifiers Control, Shift and Alt in any value you pass to this function. The default mod mask should be changed on application startup, before using any accelerator groups. accelerator modifier mask Determines whether a given keyval and modifier mask constitute a valid keyboard accelerator. For example, the #GDK_KEY_a keyval plus #GDK_CONTROL_MASK is valid - this is a “Ctrl+a” accelerator. But, you can't, for instance, use the #GDK_KEY_Control_L keyval as an accelerator. %TRUE if the accelerator is valid a GDK keyval modifier mask Returns %TRUE if dialogs are expected to use an alternative button order on the screen @screen. See gtk_dialog_set_alternative_button_order() for more details about alternative button order. If you need to use this function, you should probably connect to the ::notify:gtk-alternative-button-order signal on the #GtkSettings object associated to @screen, in order to be notified if the button order setting changes. Deprecated Whether the alternative button order should be used a #GdkScreen, or %NULL to use the default screen Parses a signal description from @signal_desc and incorporates it into @binding_set. Signal descriptions may either bind a key combination to one or more signals: |[ bind "key" { "signalname" (param, ...) ... } ]| Or they may also unbind a key combination: |[ unbind "key" ]| Key combinations must be in a format that can be parsed by gtk_accelerator_parse(). %G_TOKEN_NONE if the signal was successfully parsed and added, the expected token otherwise a #GtkBindingSet a signal description Override or install a new key binding for @keyval with @modifiers on @binding_set. a #GtkBindingSet to add a signal to key value key modifier signal name to be bound list of #GtkBindingArg signal arguments Remove a binding previously installed via gtk_binding_entry_add_signal() on @binding_set. a #GtkBindingSet to remove an entry of key value of binding to remove key modifier of binding to remove Install a binding on @binding_set which causes key lookups to be aborted, to prevent bindings from lower priority sets to be activated. a #GtkBindingSet to skip an entry of key value of binding to skip key modifier of binding to skip This function returns the binding set named after the type name of the passed in class structure. New binding sets are created on demand by this function. the binding set corresponding to @object_class a valid #GObject class Find a binding set by its globally unique name. The @set_name can either be a name used for gtk_binding_set_new() or the type name of a class used in gtk_binding_set_by_class(). %NULL or the specified binding set unique binding set name GTK+ maintains a global list of binding sets. Each binding set has a unique name which needs to be specified upon creation. new binding set unique name of this binding set Find a key binding matching @keyval and @modifiers and activate the binding on @object. %TRUE if a binding was found and activated object to activate when binding found key value of the binding key modifier of the binding Looks up key bindings for @object to find one matching @event, and if one was found, activate it. %TRUE if a matching key binding was found a #GObject (generally must be a widget) a #GdkEventKey This function is supposed to be called in #GtkWidget::draw implementations for widgets that support multiple windows. @cr must be untransformed from invoking of the draw function. This function will return %TRUE if the contents of the given @window are supposed to be drawn and %FALSE otherwise. Note that when the drawing was not initiated by the windowing system this function will return %TRUE for all windows, so you need to draw the bottommost window first. Also, do not use “else if” statements to check which window should be drawn. %TRUE if @window should be drawn a cairo context the window to check. @window may not be an input-only window. Transforms the given cairo context @cr that from @widget-relative coordinates to @window-relative coordinates. If the @widget’s window is not an ancestor of @window, no modification will be applied. This is the inverse to the transformation GTK applies when preparing an expose event to be emitted with the #GtkWidget::draw signal. It is intended to help porting multiwindow widgets from GTK+ 2 to the rendering architecture of GTK+ 3. the cairo context to transform the widget the context is currently centered for the window to transform the context to Checks that the GTK+ library in use is compatible with the given version. Generally you would pass in the constants #GTK_MAJOR_VERSION, #GTK_MINOR_VERSION, #GTK_MICRO_VERSION as the three arguments to this function; that produces a check that the library in use is compatible with the version of GTK+ the application or module was compiled against. Compatibility is defined by two things: first the version of the running library is newer than the version @required_major.required_minor.@required_micro. Second the running library must be binary compatible with the version @required_major.required_minor.@required_micro (same major version.) This function is primarily for GTK+ modules; the module can call this function to check that it wasn’t loaded into an incompatible version of GTK+. However, such a check isn’t completely reliable, since the module may be linked against an old version of GTK+ and calling the old version of gtk_check_version(), but still get loaded into an application using a newer version of GTK+. %NULL if the GTK+ library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by GTK+ and should not be modified or freed. the required major version the required minor version the required micro version Adds a GTK+ grab on @device, so all the events on @device and its associated pointer or keyboard (if any) are delivered to @widget. If the @block_others parameter is %TRUE, any other devices will be unable to interact with @widget during the grab. a #GtkWidget a #GdkDevice to grab on. %TRUE to prevent other devices to interact with @widget. Removes a device grab from the given widget. You have to pair calls to gtk_device_grab_add() and gtk_device_grab_remove(). a #GtkWidget a #GdkDevice Prevents gtk_init(), gtk_init_check(), gtk_init_with_args() and gtk_parse_args() from automatically calling `setlocale (LC_ALL, "")`. You would want to use this function if you wanted to set the locale for your program to something other than the user’s locale, or if you wanted to set different values for different locale categories. Most programs should not need to call this function. Distributes @extra_space to child @sizes by bringing smaller children up to natural size first. The remaining space will be added to the @minimum_size member of the GtkRequestedSize struct. If all sizes reach their natural size then the remaining space is returned. The remainder of @extra_space after redistributing space to @sizes. Extra space to redistribute among children after subtracting minimum sizes and any child padding from the overall allocation Number of requests to fit into the allocation An array of structs with a client pointer and a minimum/natural size in the orientation of the allocation. Cancels an ongoing drag operation on the source side. If you want to be able to cancel a drag operation in this way, you need to keep a pointer to the drag context, either from an explicit call to gtk_drag_begin_with_coordinates(), or by connecting to #GtkWidget::drag-begin. If @context does not refer to an ongoing drag operation, this function does nothing. If a drag is cancelled in this way, the @result argument of #GtkWidget::drag-failed is set to @GTK_DRAG_RESULT_ERROR. a #GdkDragContext, as e.g. returned by gtk_drag_begin_with_coordinates() Informs the drag source that the drop is finished, and that the data of the drag will no longer be required. the drag context a flag indicating whether the drop was successful a flag indicating whether the source should delete the original data. (This should be %TRUE for a move) the timestamp from the #GtkWidget::drag-drop signal Determines the source widget for a drag. if the drag is occurring within a single application, a pointer to the source widget. Otherwise, %NULL. a (destination side) drag context Sets the icon for a particular drag to the default icon. the context for a drag (This must be called with a context for the source side of a drag) Sets the icon for a given drag from the given @icon. See the documentation for gtk_drag_set_icon_name() for more details about using icons in drag and drop. the context for a drag (This must be called with a context for the source side of a drag) a #GIcon the X offset of the hotspot within the icon the Y offset of the hotspot within the icon Sets the icon for a given drag from a named themed icon. See the docs for #GtkIconTheme for more details. Note that the size of the icon depends on the icon theme (the icon is loaded at the symbolic size #GTK_ICON_SIZE_DND), thus @hot_x and @hot_y have to be used with care. the context for a drag (This must be called with a context for the source side of a drag) name of icon to use the X offset of the hotspot within the icon the Y offset of the hotspot within the icon Sets @pixbuf as the icon for a given drag. the context for a drag (This must be called with a context for the source side of a drag) the #GdkPixbuf to use as the drag icon the X offset within @widget of the hotspot the Y offset within @widget of the hotspot Sets the icon for a given drag from a stock ID. Use gtk_drag_set_icon_name() instead. the context for a drag (This must be called with a context for the source side of a drag) the ID of the stock icon to use for the drag the X offset within the icon of the hotspot the Y offset within the icon of the hotspot Sets @surface as the icon for a given drag. GTK+ retains references for the arguments, and will release them when they are no longer needed. To position the surface relative to the mouse, use cairo_surface_set_device_offset() on @surface. The mouse cursor will be positioned at the (0,0) coordinate of the surface. the context for a drag (This must be called with a context for the source side of a drag) the surface to use as icon Changes the icon for drag operation to a given widget. GTK+ will not destroy the widget, so if you don’t want it to persist, you should connect to the “drag-end” signal and destroy it yourself. the context for a drag. (This must be called with a context for the source side of a drag) a widget to use as an icon the X offset within @widget of the hotspot the Y offset within @widget of the hotspot Draws a text caret on @cr at @location. This is not a style function but merely a convenience function for drawing the standard cursor shape. Use gtk_render_insertion_cursor() instead. a #GtkWidget cairo context to draw to location where to draw the cursor (@location->width is ignored) if the cursor should be the primary cursor color. whether the cursor is left-to-right or right-to-left. Should never be #GTK_TEXT_DIR_NONE %TRUE to draw a directional arrow on the cursor. Should be %FALSE unless the cursor is split. Checks if any events are pending. This can be used to update the UI and invoke timeouts etc. while doing some time intensive computation. ## Updating the UI during a long computation |[<!-- language="C" --> // computation going on... while (gtk_events_pending ()) gtk_main_iteration (); // ...computation continued ]| %TRUE if any events are pending, %FALSE otherwise Analogical to gtk_true(), this function does nothing but always returns %FALSE. %FALSE Registers an error quark for #GtkFileChooser if necessary. The error quark used for #GtkFileChooser errors. The functions and objects described here make working with GTK+ and GIO more convenient. #GtkMountOperation is needed when mounting volumes: It is an implementation of #GMountOperation that can be used with GIO functions for mounting volumes such as g_file_mount_enclosing_volume(), g_file_mount_mountable(), g_volume_mount(), g_mount_unmount_with_operation() and others. When necessary, #GtkMountOperation shows dialogs to ask for passwords, questions or show processes blocking unmount. gtk_show_uri_on_window() is a convenient way to launch applications for URIs. Another object that is worth mentioning in this context is #GdkAppLaunchContext, which provides visual feedback when lauching applications. Returns the binary age as passed to `libtool` when building the GTK+ library the process is running against. If `libtool` means nothing to you, don't worry about it. the binary age of the GTK+ library Obtains a copy of the event currently being processed by GTK+. For example, if you are handling a #GtkButton::clicked signal, the current event will be the #GdkEventButton that triggered the ::clicked signal. a copy of the current event, or %NULL if there is no current event. The returned event must be freed with gdk_event_free(). If there is a current event and it has a device, return that device, otherwise return %NULL. a #GdkDevice, or %NULL If there is a current event and it has a state field, place that state field in @state and return %TRUE, otherwise return %FALSE. %TRUE if there was a current event and it had a state field a location to store the state of the current event If there is a current event and it has a timestamp, return that timestamp, otherwise return %GDK_CURRENT_TIME. the timestamp from the current event, or %GDK_CURRENT_TIME. Returns the GTK+ debug flags. This function is intended for GTK+ modules that want to adjust their debug output based on GTK+ debug flags. the GTK+ debug flags. Returns the #PangoLanguage for the default language currently in effect. (Note that this can change over the life of an application.) The default language is derived from the current locale. It determines, for example, whether GTK+ uses the right-to-left or left-to-right text direction. This function is equivalent to pango_language_get_default(). See that function for details. the default language as a #PangoLanguage, must not be freed If @event is %NULL or the event was not associated with any widget, returns %NULL, otherwise returns the widget that received the event originally. the widget that originally received @event, or %NULL a #GdkEvent Returns the interface age as passed to `libtool` when building the GTK+ library the process is running against. If `libtool` means nothing to you, don't worry about it. the interface age of the GTK+ library Get the direction of the current locale. This is the expected reading direction for text and UI. This function depends on the current locale being set with setlocale() and will default to setting the %GTK_TEXT_DIR_LTR direction otherwise. %GTK_TEXT_DIR_NONE will never be returned. GTK+ sets the default text direction according to the locale during gtk_init(), and you should normally use gtk_widget_get_direction() or gtk_widget_get_default_direction() to obtain the current direcion. This function is only needed rare cases when the locale is changed after GTK+ has already been initialized. In this case, you can use it to update the default text direction as follows: |[<!-- language="C" --> setlocale (LC_ALL, new_locale); direction = gtk_get_locale_direction (); gtk_widget_set_default_direction (direction); ]| the #GtkTextDirection of the current locale Returns the major version number of the GTK+ library. (e.g. in GTK+ version 3.1.5 this is 3.) This function is in the library, so it represents the GTK+ library your code is running against. Contrast with the #GTK_MAJOR_VERSION macro, which represents the major version of the GTK+ headers you have included when compiling your code. the major version number of the GTK+ library Returns the micro version number of the GTK+ library. (e.g. in GTK+ version 3.1.5 this is 5.) This function is in the library, so it represents the GTK+ library your code is are running against. Contrast with the #GTK_MICRO_VERSION macro, which represents the micro version of the GTK+ headers you have included when compiling your code. the micro version number of the GTK+ library Returns the minor version number of the GTK+ library. (e.g. in GTK+ version 3.1.5 this is 1.) This function is in the library, so it represents the GTK+ library your code is are running against. Contrast with the #GTK_MINOR_VERSION macro, which represents the minor version of the GTK+ headers you have included when compiling your code. the minor version number of the GTK+ library Returns a #GOptionGroup for the commandline arguments recognized by GTK+ and GDK. You should add this group to your #GOptionContext with g_option_context_add_group(), if you are using g_option_context_parse() to parse your commandline arguments. a #GOptionGroup for the commandline arguments recognized by GTK+ whether to open the default display when parsing the commandline arguments Queries the current grab of the default window group. The widget which currently has the grab or %NULL if no grab is active A button box should be used to provide a consistent layout of buttons throughout your application. The layout/spacing can be altered by the programmer, or if desired, by the user to alter the “feel” of a program to a small degree. gtk_button_box_get_layout() and gtk_button_box_set_layout() retrieve and alter the method used to spread the buttons in a button box across the container, respectively. The main purpose of GtkButtonBox is to make sure the children have all the same size. GtkButtonBox gives all children the same size, but it does allow 'outliers' to keep their own larger size. To exempt individual children from homogeneous sizing regardless of their 'outlier' status, you can set the non-homogeneous child property. # CSS nodes GtkButtonBox uses a single CSS node with name buttonbox. #GtkBindingSet provides a mechanism for configuring GTK+ key bindings through CSS files. This eases key binding adjustments for application developers as well as users and provides GTK+ users or administrators with high key binding configurability which requires no application or toolkit side changes. In order for bindings to work in a custom widget implementation, the widget’s #GtkWidget:can-focus and #GtkWidget:has-focus properties must both be true. For example, by calling gtk_widget_set_can_focus() in the widget’s initialisation function; and by calling gtk_widget_grab_focus() when the widget is clicked. # Installing a key binding A CSS file binding consists of a “binding-set” definition and a match statement to apply the binding set to specific widget types. Details on the matching mechanism are described under [Selectors][gtkcssprovider-selectors] in the #GtkCssProvider documentation. Inside the binding set definition, key combinations are bound to one or more specific signal emissions on the target widget. Key combinations are strings consisting of an optional #GdkModifierType name and [key names][gdk3-Keyboard-Handling] such as those defined in `gdk/gdkkeysyms.h` or returned from gdk_keyval_name(), they have to be parsable by gtk_accelerator_parse(). Specifications of signal emissions consist of a string identifying the signal name, and a list of signal specific arguments in parenthesis. For example for binding Control and the left or right cursor keys of a #GtkEntry widget to the #GtkEntry::move-cursor signal (so movement occurs in 3-character steps), the following binding can be used: |[ <!-- language="CSS" --> @binding-set MoveCursor3 { bind "<Control>Right" { "move-cursor" (visual-positions, 3, 0) }; bind "<Control>Left" { "move-cursor" (visual-positions, -3, 0) }; } entry { -gtk-key-bindings: MoveCursor3; } ]| # Unbinding existing key bindings GTK+ already defines a number of useful bindings for the widgets it provides. Because custom bindings set up in CSS files take precedence over the default bindings shipped with GTK+, overriding existing bindings as demonstrated in [Installing a key binding][gtk-bindings-install] works as expected. The same mechanism can not be used to “unbind” existing bindings, however. |[ <!-- language="CSS" --> @binding-set MoveCursor3 { bind "<Control>Right" { }; bind "<Control>Left" { }; } entry { -gtk-key-bindings: MoveCursor3; } ]| The above example will not have the desired effect of causing “<Control>Right” and “<Control>Left” key presses to be ignored by GTK+. Instead, it just causes any existing bindings from the bindings set “MoveCursor3” to be deleted, so when “<Control>Right” or “<Control>Left” are pressed, no binding for these keys is found in binding set “MoveCursor3”. GTK+ will thus continue to search for matching key bindings, and will eventually lookup and find the default GTK+ bindings for entries which implement word movement. To keep GTK+ from activating its default bindings, the “unbind” keyword can be used like this: |[ <!-- language="CSS" --> @binding-set MoveCursor3 { unbind "<Control>Right"; unbind "<Control>Left"; } entry { -gtk-key-bindings: MoveCursor3; } ]| Now, GTK+ will find a match when looking up “<Control>Right” and “<Control>Left” key presses before it resorts to its default bindings, and the match instructs it to abort (“unbind”) the search, so the key presses are not consumed by this widget. As usual, further processing of the key presses, e.g. by an entry’s parent widget, is now possible. The #GtkColorSelection is a widget that is used to select a color. It consists of a color wheel and number of sliders and entry boxes for color parameters such as hue, saturation, value, red, green, blue, and opacity. It is found on the standard color selection dialog box #GtkColorSelectionDialog. The #GtkColorSelectionDialog provides a standard dialog which allows the user to select a color much like the #GtkFileChooserDialog provides a standard dialog for file selection. Use gtk_color_selection_dialog_get_color_selection() to get the #GtkColorSelection widget contained within the dialog. Use this widget and its gtk_color_selection_get_current_color() function to gain access to the selected color. Connect a handler for this widget’s #GtkColorSelection::color-changed signal to be notified when the color changes. # GtkColorSelectionDialog as GtkBuildable # {#GtkColorSelectionDialog-BUILDER-UI} The GtkColorSelectionDialog implementation of the GtkBuildable interface exposes the embedded #GtkColorSelection as internal child with the name “color_selection”. It also exposes the buttons with the names “ok_button”, “cancel_button” and “help_button”. GTK+ has a rich set of functions for doing inter-process communication via the drag-and-drop metaphor. As well as the functions listed here, applications may need to use some facilities provided for [Selections][gtk3-Selections]. Also, the Drag and Drop API makes use of signals in the #GtkWidget class. GTK+ provides version information, primarily useful in configure checks for builds that have a configure script. Applications will not typically use the features described here. The #GtkFontSelection widget lists the available fonts, styles and sizes, allowing the user to select a font. It is used in the #GtkFontSelectionDialog widget to provide a dialog box for selecting fonts. To set the font which is initially selected, use gtk_font_selection_set_font_name(). To get the selected font use gtk_font_selection_get_font_name(). To change the text which is shown in the preview area, use gtk_font_selection_set_preview_text(). In GTK+ 3.2, #GtkFontSelection has been deprecated in favor of #GtkFontChooser. The #GtkFontSelectionDialog widget is a dialog box for selecting a font. To set the font which is initially selected, use gtk_font_selection_dialog_set_font_name(). To get the selected font use gtk_font_selection_dialog_get_font_name(). To change the text which is shown in the preview area, use gtk_font_selection_dialog_set_preview_text(). In GTK+ 3.2, #GtkFontSelectionDialog has been deprecated in favor of #GtkFontChooserDialog. # GtkFontSelectionDialog as GtkBuildable # {#GtkFontSelectionDialog-BUILDER-UI} The GtkFontSelectionDialog implementation of the GtkBuildable interface exposes the embedded #GtkFontSelection as internal child with the name “font_selection”. It also exposes the buttons with the names “ok_button”, “cancel_button” and “apply_button”. A button box should be used to provide a consistent layout of buttons throughout your application. The layout/spacing can be altered by the programmer, or if desired, by the user to alter the “feel” of a program to a small degree. A #GtkHButtonBox is created with gtk_hbutton_box_new(). Buttons are packed into a button box the same way widgets are added to any other container, using gtk_container_add(). You can also use gtk_box_pack_start() or gtk_box_pack_end(), but for button boxes both these functions work just like gtk_container_add(), ie., they pack the button in a way that depends on the current layout style and on whether the button has had gtk_button_box_set_child_secondary() called on it. The spacing between buttons can be set with gtk_box_set_spacing(). The arrangement and layout of the buttons can be changed with gtk_button_box_set_layout(). GtkHButtonBox has been deprecated, use #GtkButtonBox instead. Before using GTK+, you need to initialize it; initialization connects to the window system display, and parses some standard command line arguments. The gtk_init() macro initializes GTK+. gtk_init() exits the application if errors occur; to avoid this, use gtk_init_check(). gtk_init_check() allows you to recover from a failed GTK+ initialization - you might start up your application in text mode instead. Like all GUI toolkits, GTK+ uses an event-driven programming model. When the user is doing nothing, GTK+ sits in the “main loop” and waits for input. If the user performs some action - say, a mouse click - then the main loop “wakes up” and delivers an event to GTK+. GTK+ forwards the event to one or more widgets. When widgets receive an event, they frequently emit one or more “signals”. Signals notify your program that "something interesting happened" by invoking functions you’ve connected to the signal with g_signal_connect(). Functions connected to a signal are often termed “callbacks”. When your callbacks are invoked, you would typically take some action - for example, when an Open button is clicked you might display a #GtkFileChooserDialog. After a callback finishes, GTK+ will return to the main loop and await more user input. ## Typical main() function for a GTK+ application |[<!-- language="C" --> int main (int argc, char **argv) { GtkWidget *mainwin; // Initialize i18n support with bindtextdomain(), etc. // ... // Initialize the widget set gtk_init (&argc, &argv); // Create the main window mainwin = gtk_window_new (GTK_WINDOW_TOPLEVEL); // Set up our GUI elements // ... // Show the application window gtk_widget_show_all (mainwin); // Enter the main event loop, and wait for user interaction gtk_main (); // The user lost interest return 0; } ]| It’s OK to use the GLib main loop directly instead of gtk_main(), though it involves slightly more typing. See #GMainLoop in the GLib documentation. #GtkPageSetupUnixDialog implements a page setup dialog for platforms which don’t provide a native page setup dialog, like Unix. It can be used very much like any other GTK+ dialog, at the cost of the portability offered by the [high-level printing API][gtk3-High-level-Printing-API] Printing support was added in GTK+ 2.10. #GtkPlacesView is a stock widget that displays a list of persistent drives such as harddisk partitions and networks. #GtkPlacesView does not monitor removable devices. The places view displays drives and networks, and will automatically mount them when the user activates. Network addresses are stored even if they fail to connect. When the connection is successful, the connected network is shown at the network list. To make use of the places view, an application at least needs to connect to the #GtkPlacesView::open-location signal. This is emitted when the user selects a location to open in the view. A #GtkPrinter object represents a printer. You only need to deal directly with printers if you use the non-portable #GtkPrintUnixDialog API. A #GtkPrinter allows to get status information about the printer, such as its description, its location, the number of queued jobs, etc. Most importantly, a #GtkPrinter object can be used to create a #GtkPrintJob object, which lets you print to the printer. Printing support was added in GTK+ 2.10. A #GtkPrintJob object represents a job that is sent to a printer. You only need to deal directly with print jobs if you use the non-portable #GtkPrintUnixDialog API. Use gtk_print_job_get_surface() to obtain the cairo surface onto which the pages must be drawn. Use gtk_print_job_send() to send the finished job to the printer. If you don’t use cairo #GtkPrintJob also supports printing of manually generated postscript, via gtk_print_job_set_source_file(). GtkPrintUnixDialog implements a print dialog for platforms which don’t provide a native print dialog, like Unix. It can be used very much like any other GTK+ dialog, at the cost of the portability offered by the [high-level printing API][gtk3-High-level-Printing-API] In order to print something with #GtkPrintUnixDialog, you need to use gtk_print_unix_dialog_get_selected_printer() to obtain a #GtkPrinter object and use it to construct a #GtkPrintJob using gtk_print_job_new(). #GtkPrintUnixDialog uses the following response values: - %GTK_RESPONSE_OK: for the “Print” button - %GTK_RESPONSE_APPLY: for the “Preview” button - %GTK_RESPONSE_CANCEL: for the “Cancel” button Printing support was added in GTK+ 2.10. # GtkPrintUnixDialog as GtkBuildable The GtkPrintUnixDialog implementation of the GtkBuildable interface exposes its @notebook internal children with the name “notebook”. An example of a #GtkPrintUnixDialog UI definition fragment: |[ <object class="GtkPrintUnixDialog" id="dialog1"> <child internal-child="notebook"> <object class="GtkNotebook" id="notebook"> <child> <object class="GtkLabel" id="tabcontent"> <property name="label">Content on notebook tab</property> </object> </child> <child type="tab"> <object class="GtkLabel" id="tablabel"> <property name="label">Tab label</property> </object> <packing> <property name="tab_expand">False</property> <property name="tab_fill">False</property> </packing> </child> </object> </child> </object> ]| # CSS nodes GtkPrintUnixDialog has a single CSS node with name printdialog. GTK+ provides resource file mechanism for configuring various aspects of the operation of a GTK+ program at runtime. > In GTK+ 3.0, resource files have been deprecated and replaced by > CSS-like style sheets, which are understood by #GtkCssProvider. # Default Files # An application can cause GTK+ to parse a specific RC file by calling gtk_rc_parse(). In addition to this, certain files will be read at the end of gtk_init(). Unless modified, the files looked for will be `SYSCONFDIR/gtk-2.0/gtkrc` and `.gtkrc-3.0` in the users home directory. (`SYSCONFDIR` defaults to `/usr/local/etc`. It can be changed with the `--prefix` or `--sysconfdir` options when configuring GTK+.) The set of these “default” files can be retrieved with gtk_rc_get_default_files() and modified with gtk_rc_add_default_file() and gtk_rc_set_default_files(). Additionally, the `GTK2_RC_FILES` environment variable can be set to a #G_SEARCHPATH_SEPARATOR_S-separated list of files in order to overwrite the set of default files at runtime. # Locale Specific Files # {#locale-specific-rc} For each RC file, in addition to the file itself, GTK+ will look for a locale-specific file that will be parsed after the main file. For instance, if `LANG` is set to `ja_JP.ujis`, when loading the default file `~/.gtkrc` then GTK+ looks for `~/.gtkrc.ja_JP` and `~/.gtkrc.ja`, and parses the first of those that exists. # Pathnames and Patterns # A resource file defines a number of styles and key bindings and attaches them to particular widgets. The attachment is done by the `widget`, `widget_class`, and `class` declarations. As an example of such a statement: |[ widget "mywindow.*.GtkEntry" style "my-entry-class" ]| attaches the style `"my-entry-class"` to all widgets whose “widget path” matches the “pattern” `"mywindow.*.GtkEntry"`. That is, all #GtkEntry widgets which are part of a #GtkWindow named `"mywindow"`. The patterns here are given in the standard shell glob syntax. The `"?"` wildcard matches any character, while `"*"` matches zero or more of any character. The three types of matching are against the widget path, the “class path” and the class hierarchy. Both the widget path and the class path consist of a `"."` separated list of all the parents of the widget and the widget itself from outermost to innermost. The difference is that in the widget path, the name assigned by gtk_widget_set_name() is used if present, otherwise the class name of the widget, while for the class path, the class name is always used. Since GTK+ 2.10, `widget_class` paths can also contain <classname> substrings, which are matching the class with the given name and any derived classes. For instance, |[ widget_class "*<GtkMenuItem>.GtkLabel" style "my-style" ]| will match #GtkLabel widgets which are contained in any kind of menu item. So, if you have a #GtkEntry named `"myentry"`, inside of a horizontal box in a window named `"mywindow"`, then the widget path is: `"mywindow.GtkHBox.myentry"` while the class path is: `"GtkWindow.GtkHBox.GtkEntry"`. Matching against class is a little different. The pattern match is done against all class names in the widgets class hierarchy (not the layout hierarchy) in sequence, so the pattern: |[ class "GtkButton" style "my-style" ]| will match not just #GtkButton widgets, but also #GtkToggleButton and #GtkCheckButton widgets, since those classes derive from #GtkButton. Additionally, a priority can be specified for each pattern, and styles override other styles first by priority, then by pattern type and then by order of specification (later overrides earlier). The priorities that can be specified are (highest to lowest): - `highest` - `rc` - `theme` - `application` - `gtk` - `lowest` `rc` is the default for styles read from an RC file, `theme` is the default for styles read from theme RC files, `application` should be used for styles an application sets up, and `gtk` is used for styles that GTK+ creates internally. # Theme gtkrc Files # Theme RC files are loaded first from under the `~/.themes/`, then from the directory from gtk_rc_get_theme_dir(). The files looked at will be `gtk-3.0/gtkrc`. When the application prefers dark themes (see the #GtkSettings:gtk-application-prefer-dark-theme property for details), `gtk-3.0/gtkrc-dark` will be loaded first, and if not present `gtk-3.0/gtkrc` will be loaded. # Optimizing RC Style Matches # Everytime a widget is created and added to the layout hierarchy of a #GtkWindow ("anchored" to be exact), a list of matching RC styles out of all RC styles read in so far is composed. For this, every RC style is matched against the widgets class path, the widgets name path and widgets inheritance hierarchy. As a consequence, significant slowdown can be caused by utilization of many RC styles and by using RC style patterns that are slow or complicated to match against a given widget. The following ordered list provides a number of advices (prioritized by effectiveness) to reduce the performance overhead associated with RC style matches: 1. Move RC styles for specific applications into RC files dedicated to those applications and parse application specific RC files only from applications that are affected by them. This reduces the overall amount of RC styles that have to be considered for a match across a group of applications. 2. Merge multiple styles which use the same matching rule, for instance: |[ style "Foo" { foo_content } class "X" style "Foo" style "Bar" { bar_content } class "X" style "Bar" ]| is faster to match as: |[ style "FooBar" { foo_content bar_content } class "X" style "FooBar" ]| 3. Use of wildcards should be avoided, this can reduce the individual RC style match to a single integer comparison in most cases. 4. To avoid complex recursive matching, specification of full class names (for `class` matches) or full path names (for `widget` and `widget_class` matches) is to be preferred over shortened names containing `"*"` or `"?"`. 5. If at all necessary, wildcards should only be used at the tail or head of a pattern. This reduces the match complexity to a string comparison per RC style. 6. When using wildcards, use of `"?"` should be preferred over `"*"`. This can reduce the matching complexity from O(n^2) to O(n). For example `"Gtk*Box"` can be turned into `"Gtk?Box"` and will still match #GtkHBox and #GtkVBox. 7. The use of `"*"` wildcards should be restricted as much as possible, because matching `"A*B*C*RestString"` can result in matching complexities of O(n^2) worst case. # Toplevel Declarations # An RC file is a text file which is composed of a sequence of declarations. `“#”` characters delimit comments and the portion of a line after a `“#”` is ignored when parsing an RC file. The possible toplevel declarations are: * `binding name { ... }` Declares a binding set. * `class pattern [ style | binding ][ : priority ] name` Specifies a style or binding set for a particular branch of the inheritance hierarchy. * `include filename` Parses another file at this point. If filename is not an absolute filename, it is searched in the directories of the currently open RC files. GTK+ also tries to load a [locale-specific variant][locale-specific-rc] of the included file. * `module_path path` Sets a path (a list of directories separated by colons) that will be searched for theme engines referenced in RC files. * `pixmap_path path` Sets a path (a list of directories separated by colons) that will be searched for pixmaps referenced in RC files. * `im_module_file pathname` Sets the pathname for the IM modules file. Setting this from RC files is deprecated; you should use the environment variable `GTK_IM_MODULE_FILE` instead. * `style name [ = parent ] { ... }` Declares a style. * `widget pattern [ style | binding ][ : priority ] name` Specifies a style or binding set for a particular group of widgets by matching on the widget pathname. * `widget_class pattern [ style | binding ][ : priority ] name` Specifies a style or binding set for a particular group of widgets by matching on the class pathname. * setting = value Specifies a value for a [setting][GtkSettings]. Note that settings in RC files are overwritten by system-wide settings (which are managed by an XSettings manager on X11). # Styles # A RC style is specified by a `style` declaration in a RC file, and then bound to widgets with a `widget`, `widget_class`, or `class` declaration. All styles applying to a particular widget are composited together with `widget` declarations overriding `widget_class` declarations which, in turn, override `class` declarations. Within each type of declaration, later declarations override earlier ones. Within a `style` declaration, the possible elements are: * `bg[state] = color` Sets the color used for the background of most widgets. * `fg[state] = color` Sets the color used for the foreground of most widgets. * `base[state] = color` Sets the color used for the background of widgets displaying editable text. This color is used for the background of, among others, #GtkTextView, #GtkEntry. * `text[state] = color` Sets the color used for foreground of widgets using `base` for the background color. * `xthickness = number` Sets the xthickness, which is used for various horizontal padding values in GTK+. * `ythickness = number` Sets the ythickness, which is used for various vertical padding values in GTK+. * `bg_pixmap[state] = pixmap` Sets a background pixmap to be used in place of the `bg` color (or for #GtkText, in place of the `base` color. The special value `"<parent>"` may be used to indicate that the widget should use the same background pixmap as its parent. The special value `"<none>"` may be used to indicate no background pixmap. * `font = font` Starting with GTK+ 2.0, the “font” and “fontset” declarations are ignored; use “font_name” declarations instead. * `fontset = font` Starting with GTK+ 2.0, the “font” and “fontset” declarations are ignored; use “font_name” declarations instead. * `font_name = font` Sets the font for a widget. font must be a Pango font name, e.g. “Sans Italic 10” . For details about Pango font names, see pango_font_description_from_string(). * `stock["stock-id"] = { icon source specifications }` Defines the icon for a stock item. * `color["color-name"] = color specification` Since 2.10, this element can be used to defines symbolic colors. See below for the syntax of color specifications. * `engine "engine" { engine-specific settings }` Defines the engine to be used when drawing with this style. * `class::property = value` Sets a [style property][style-properties] for a widget class. The colors and background pixmaps are specified as a function of the state of the widget. The states are: * `NORMAL` A color used for a widget in its normal state. * `ACTIVE` A variant of the `NORMAL` color used when the widget is in the %GTK_STATE_ACTIVE state, and also for the trough of a ScrollBar, tabs of a NoteBook other than the current tab and similar areas. Frequently, this should be a darker variant of the `NORMAL` color. * `PRELIGHT` A color used for widgets in the %GTK_STATE_PRELIGHT state. This state is the used for Buttons and MenuItems that have the mouse cursor over them, and for their children. * `SELECTED` A color used to highlight data selected by the user. for instance, the selected items in a list widget, and the selection in an editable widget. * `INSENSITIVE` A color used for the background of widgets that have been set insensitive with gtk_widget_set_sensitive(). ## Color Format ## {#color-format} Colors can be specified as a string containing a color name (GTK+ knows all names from the X color database `/usr/lib/X11/rgb.txt`), in one of the hexadecimal forms `#rrrrggggbbbb`, `#rrrgggbbb`, `#rrggbb`, or `#rgb`, where `r`, `g` and `b` are hex digits, or they can be specified as a triplet `{ r, g, b}`, where `r`, `g` and `b` are either integers in the range 0-65535 or floats in the range 0.0-1.0. Since 2.10, colors can also be specified by refering to a symbolic color, as follows: `@color-name`, or by using expressions to combine colors. The following expressions are currently supported: * mix (factor, color1, color2) Computes a new color by mixing color1 and color2. The factor determines how close the new color is to color1. A factor of 1.0 gives pure color1, a factor of 0.0 gives pure color2. * shade (factor, color) Computes a lighter or darker variant of color. A factor of 1.0 leaves the color unchanged, smaller factors yield darker colors, larger factors yield lighter colors. * lighter (color) This is an abbreviation for `shade (1.3, color)`. * darker (color) This is an abbreviation for `shade (0.7, color)`. Here are some examples of color expressions: |[ mix (0.5, "red", "blue") shade (1.5, mix (0.3, "#0abbc0", { 0.3, 0.5, 0.9 })) lighter (@foreground) ]| In a `stock` definition, icon sources are specified as a 4-tuple of image filename or icon name, text direction, widget state, and size, in that order. Each icon source specifies an image filename or icon name to use with a given direction, state, and size. Filenames are specified as a string such as `"itemltr.png"`, while icon names (looked up in the current icon theme), are specified with a leading `@`, such as `@"item-ltr"`. The `*` character can be used as a wildcard, and if direction/state/size are omitted they default to `*`. So for example, the following specifies different icons to use for left-to-right and right-to-left languages: |[<!-- language="C" --> stock["my-stock-item"] = { { "itemltr.png", LTR, *, * }, { "itemrtl.png", RTL, *, * } } ]| This could be abbreviated as follows: |[<!-- language="C" --> stock["my-stock-item"] = { { "itemltr.png", LTR }, { "itemrtl.png", RTL } } ]| You can specify custom icons for specific sizes, as follows: |[<!-- language="C" --> stock["my-stock-item"] = { { "itemmenusize.png", *, *, "gtk-menu" }, { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" } { "itemgeneric.png" } // implicit *, *, * as a fallback } ]| The sizes that come with GTK+ itself are `"gtk-menu"`, `"gtk-small-toolbar"`, `"gtk-large-toolbar"`, `"gtk-button"`, `"gtk-dialog"`. Applications can define other sizes. It’s also possible to use custom icons for a given state, for example: |[<!-- language="C" --> stock["my-stock-item"] = { { "itemprelight.png", *, PRELIGHT }, { "iteminsensitive.png", *, INSENSITIVE }, { "itemgeneric.png" } // implicit *, *, * as a fallback } ]| When selecting an icon source to use, GTK+ will consider text direction most important, state second, and size third. It will select the best match based on those criteria. If an attribute matches exactly (e.g. you specified `PRELIGHT` or specified the size), GTK+ won’t modify the image; if the attribute matches with a wildcard, GTK+ will scale or modify the image to match the state and size the user requested. # Key bindings # Key bindings allow the user to specify actions to be taken on particular key presses. The form of a binding set declaration is: |[ binding name { bind key { signalname (param, ...) ... } ... } ]| `key` is a string consisting of a series of modifiers followed by the name of a key. The modifiers can be: - `<alt>` - `<ctl>` - `<control>` - `<meta>` - `<hyper>` - `<super>` - `<mod1>` - `<mod2>` - `<mod3>` - `<mod4>` - `<mod5>` - `<release>` - `<shft>` - `<shift>` `<shft>` is an alias for `<shift>`, `<ctl>` is an alias for `<control>`, and `<alt>` is an alias for `<mod1>`. The action that is bound to the key is a sequence of signal names (strings) followed by parameters for each signal. The signals must be action signals. (See g_signal_new()). Each parameter can be a float, integer, string, or unquoted string representing an enumeration value. The types of the parameters specified must match the types of the parameters of the signal. Binding sets are connected to widgets in the same manner as styles, with one difference: Binding sets override other binding sets first by pattern type, then by priority and then by order of specification. The priorities that can be specified and their default values are the same as for styles. The selection mechanism provides the basis for different types of communication between processes. In particular, drag and drop and #GtkClipboard work via selections. You will very seldom or never need to use most of the functions in this section directly; #GtkClipboard provides a nicer interface to the same functionality. If an application is expected to exchange image data and work on Windows, it is highly advised to support at least "image/bmp" target for the widest possible compatibility with third-party applications. #GtkClipboard already does that by using gtk_target_list_add_image_targets() and gtk_selection_data_set_pixbuf() or gtk_selection_data_get_pixbuf(), which is one of the reasons why it is advised to use #GtkClipboard. Some of the datatypes defined this section are used in the #GtkClipboard and drag-and-drop API’s as well. The #GtkTargetEntry and #GtkTargetList objects represent lists of data types that are supported when sending or receiving data. The #GtkSelectionData object is used to store a chunk of data along with the data type and other associated information. > Since GTK+ 3.10, stock items are deprecated. You should instead set > up whatever labels and/or icons you need using normal widget API, > rather than relying on GTK+ providing ready-made combinations of these. Stock items represent commonly-used menu or toolbar items such as “Open” or “Exit”. Each stock item is identified by a stock ID; stock IDs are just strings, but macros such as #GTK_STOCK_OPEN are provided to avoid typing mistakes in the strings. Applications can register their own stock items in addition to those built-in to GTK+. Each stock ID can be associated with a #GtkStockItem, which contains the user-visible label, keyboard accelerator, and translation domain of the menu or toolbar item; and/or with an icon stored in a #GtkIconFactory. The connection between a #GtkStockItem and stock icons is purely conventional (by virtue of using the same stock ID); it’s possible to register a stock item but no icon, and vice versa. Stock icons may have a RTL variant which gets used for right-to-left locales. GTK+ supports Drag-and-Drop in tree views with a high-level and a low-level API. The low-level API consists of the GTK+ DND API, augmented by some treeview utility functions: gtk_tree_view_set_drag_dest_row(), gtk_tree_view_get_drag_dest_row(), gtk_tree_view_get_dest_row_at_pos(), gtk_tree_view_create_row_drag_icon(), gtk_tree_set_row_drag_data() and gtk_tree_get_row_drag_data(). This API leaves a lot of flexibility, but nothing is done automatically, and implementing advanced features like hover-to-open-rows or autoscrolling on top of this API is a lot of work. On the other hand, if you write to the high-level API, then all the bookkeeping of rows is done for you, as well as things like hover-to-open and auto-scroll, but your models have to implement the #GtkTreeDragSource and #GtkTreeDragDest interfaces. A button box should be used to provide a consistent layout of buttons throughout your application. The layout/spacing can be altered by the programmer, or if desired, by the user to alter the “feel” of a program to a small degree. A #GtkVButtonBox is created with gtk_vbutton_box_new(). Buttons are packed into a button box the same way widgets are added to any other container, using gtk_container_add(). You can also use gtk_box_pack_start() or gtk_box_pack_end(), but for button boxes both these functions work just like gtk_container_add(), ie., they pack the button in a way that depends on the current layout style and on whether the button has had gtk_button_box_set_child_secondary() called on it. The spacing between buttons can be set with gtk_box_set_spacing(). The arrangement and layout of the buttons can be changed with gtk_button_box_set_layout(). GtkVButtonBox has been deprecated, use #GtkButtonBox instead. Looks up the icon size associated with @name. Use #GtkIconTheme instead. the icon size (#GtkIconSize) the name to look up. Gets the canonical name of the given icon size. The returned string is statically allocated and should not be freed. Use #GtkIconTheme instead. the name of the given icon size. a #GtkIconSize. Obtains the pixel size of a semantic icon size @size: #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_BUTTON, etc. This function isn’t normally needed, gtk_icon_theme_load_icon() is the usual way to get an icon for rendering, then just look at the size of the rendered pixbuf. The rendered pixbuf may not even correspond to the width/height returned by gtk_icon_size_lookup(), because themes are free to render the pixbuf however they like, including changing the usual size. %TRUE if @size was a valid size an icon size (#GtkIconSize) location to store icon width location to store icon height Obtains the pixel size of a semantic icon size, possibly modified by user preferences for a particular #GtkSettings. Normally @size would be #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_BUTTON, etc. This function isn’t normally needed, gtk_widget_render_icon_pixbuf() is the usual way to get an icon for rendering, then just look at the size of the rendered pixbuf. The rendered pixbuf may not even correspond to the width/height returned by gtk_icon_size_lookup(), because themes are free to render the pixbuf however they like, including changing the usual size. Use gtk_icon_size_lookup() instead. %TRUE if @size was a valid size a #GtkSettings object, used to determine which set of user preferences to used. an icon size (#GtkIconSize) location to store icon width location to store icon height Registers a new icon size, along the same lines as #GTK_ICON_SIZE_MENU, etc. Returns the integer value for the size. Use #GtkIconTheme instead. integer value representing the size (#GtkIconSize) name of the icon size the icon width the icon height Registers @alias as another name for @target. So calling gtk_icon_size_from_name() with @alias as argument will return @target. Use #GtkIconTheme instead. an alias for @target an existing icon size (#GtkIconSize) Call this function before using any other GTK+ functions in your GUI applications. It will initialize everything needed to operate the toolkit and parses some standard command line options. Although you are expected to pass the @argc, @argv parameters from main() to this function, it is possible to pass %NULL if @argv is not available or commandline handling is not required. @argc and @argv are adjusted accordingly so your own code will never see those standard arguments. Note that there are some alternative ways to initialize GTK+: if you are calling gtk_parse_args(), gtk_init_check(), gtk_init_with_args() or g_option_context_parse() with the option group returned by gtk_get_option_group(), you don’t have to call gtk_init(). And if you are using #GtkApplication, you don't have to call any of the initialization functions either; the #GtkApplication::startup handler does it for you. This function will terminate your program if it was unable to initialize the windowing system for some reason. If you want your program to fall back to a textual interface you want to call gtk_init_check() instead. Since 2.18, GTK+ calls `signal (SIGPIPE, SIG_IGN)` during initialization, to ignore SIGPIPE signals, since these are almost never wanted in graphical applications. If you do need to handle SIGPIPE for some reason, reset the handler after gtk_init(), but notice that other libraries (e.g. libdbus or gvfs) might do similar things. Address of the `argc` parameter of your main() function (or 0 if @argv is %NULL). This will be changed if any arguments were handled. Address of the `argv` parameter of main(), or %NULL. Any options understood by GTK+ are stripped before return. This function does the same work as gtk_init() with only a single change: It does not terminate the program if the commandline arguments couldn’t be parsed or the windowing system can’t be initialized. Instead it returns %FALSE on failure. This way the application can fall back to some other means of communication with the user - for example a curses or command line interface. Note that calling any GTK function or instantiating any GTK type after this function returns %FALSE results in undefined behavior. %TRUE if the commandline arguments (if any) were valid and the windowing system has been successfully initialized, %FALSE otherwise Address of the `argc` parameter of your main() function (or 0 if @argv is %NULL). This will be changed if any arguments were handled. Address of the `argv` parameter of main(), or %NULL. Any options understood by GTK+ are stripped before return. This function does the same work as gtk_init_check(). Additionally, it allows you to add your own commandline options, and it automatically generates nicely formatted `--help` output. Note that your program will be terminated after writing out the help output. %TRUE if the commandline arguments (if any) were valid and if the windowing system has been successfully initialized, %FALSE otherwise Address of the `argc` parameter of your main() function (or 0 if @argv is %NULL). This will be changed if any arguments were handled. Address of the `argv` parameter of main(), or %NULL. Any options understood by GTK+ are stripped before return. a string which is displayed in the first line of `--help` output, after `programname [OPTION...]` a %NULL-terminated array of #GOptionEntrys describing the options of your program a translation domain to use for translating the `--help` output for the options in @entries and the @parameter_string with gettext(), or %NULL Installs a key snooper function, which will get called on all key events before delivering them normally. Key snooping should not be done. Events should be handled by widgets. a unique id for this key snooper for use with gtk_key_snooper_remove(). a #GtkKeySnoopFunc data to pass to @snooper Removes the key snooper function with the given id. Key snooping should not be done. Events should be handled by widgets. Identifies the key snooper to remove Runs the main loop until gtk_main_quit() is called. You can nest calls to gtk_main(). In that case gtk_main_quit() will make the innermost invocation of the main loop return. Processes a single GDK event. This is public only to allow filtering of events between GDK and GTK+. You will not usually need to call this function directly. While you should not call this function directly, you might want to know how exactly events are handled. So here is what this function does with the event: 1. Compress enter/leave notify events. If the event passed build an enter/leave pair together with the next event (peeked from GDK), both events are thrown away. This is to avoid a backlog of (de-)highlighting widgets crossed by the pointer. 2. Find the widget which got the event. If the widget can’t be determined the event is thrown away unless it belongs to a INCR transaction. 3. Then the event is pushed onto a stack so you can query the currently handled event with gtk_get_current_event(). 4. The event is sent to a widget. If a grab is active all events for widgets that are not in the contained in the grab widget are sent to the latter with a few exceptions: - Deletion and destruction events are still sent to the event widget for obvious reasons. - Events which directly relate to the visual representation of the event widget. - Leave events are delivered to the event widget if there was an enter event delivered to it before without the paired leave event. - Drag events are not redirected because it is unclear what the semantics of that would be. Another point of interest might be that all key events are first passed through the key snooper functions if there are any. Read the description of gtk_key_snooper_install() if you need this feature. 5. After finishing the delivery the event is popped from the event stack. An event to process (normally passed by GDK) Runs a single iteration of the mainloop. If no events are waiting to be processed GTK+ will block until the next event is noticed. If you don’t want to block look at gtk_main_iteration_do() or check if any events are pending with gtk_events_pending() first. %TRUE if gtk_main_quit() has been called for the innermost mainloop Runs a single iteration of the mainloop. If no events are available either return or block depending on the value of @blocking. %TRUE if gtk_main_quit() has been called for the innermost mainloop %TRUE if you want GTK+ to block if no events are pending Asks for the current nesting level of the main loop. the nesting level of the current invocation of the main loop Makes the innermost invocation of the main loop return when it regains control. Draws an arrow in the given rectangle on @cr using the given parameters. @arrow_type determines the direction of the arrow. Use gtk_render_arrow() instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail the type of arrow to draw %TRUE if the arrow tip should be filled x origin of the rectangle to draw the arrow in y origin of the rectangle to draw the arrow in width of the rectangle to draw the arrow in height of the rectangle to draw the arrow in Draws a box on @cr with the given parameters. Use gtk_render_frame() and gtk_render_background() instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail x origin of the box y origin of the box the width of the box the height of the box Draws a box in @cr using the given style and state and shadow type, leaving a gap in one side. Use gtk_render_frame_gap() instead a #GtkStyle a #cairo_t a state type of shadow to draw the widget a style detail x origin of the rectangle y origin of the rectangle width of the rectangle width of the rectangle side in which to leave the gap starting position of the gap width of the gap Draws a check button indicator in the given rectangle on @cr with the given parameters. Use gtk_render_check() instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail x origin of the rectangle to draw the check in y origin of the rectangle to draw the check in the width of the rectangle to draw the check in the height of the rectangle to draw the check in Draws a diamond in the given rectangle on @window using the given parameters. Use cairo instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail x origin of the rectangle to draw the diamond in y origin of the rectangle to draw the diamond in width of the rectangle to draw the diamond in height of the rectangle to draw the diamond in Draws an expander as used in #GtkTreeView. @x and @y specify the center the expander. The size of the expander is determined by the “expander-size” style property of @widget. (If widget is not specified or doesn’t have an “expander-size” property, an unspecified default size will be used, since the caller doesn't have sufficient information to position the expander, this is likely not useful.) The expander is expander_size pixels tall in the collapsed position and expander_size pixels wide in the expanded position. Use gtk_render_expander() instead a #GtkStyle a #cairo_t a state the widget a style detail the x position to draw the expander at the y position to draw the expander at the style to draw the expander in; determines whether the expander is collapsed, expanded, or in an intermediate state. Draws an extension, i.e. a notebook tab. Use gtk_render_extension() instead a #GtkStyle a #cairo_t a state type of shadow to draw the widget a style detail x origin of the extension y origin of the extension width of the extension width of the extension the side on to which the extension is attached Draws a flat box on @cr with the given parameters. Use gtk_render_frame() and gtk_render_background() instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail x origin of the box y origin of the box the width of the box the height of the box Draws a focus indicator around the given rectangle on @cr using the given style. Use gtk_render_focus() instead a #GtkStyle a #cairo_t a state the widget a style detail the x origin of the rectangle around which to draw a focus indicator the y origin of the rectangle around which to draw a focus indicator the width of the rectangle around which to draw a focus indicator the height of the rectangle around which to draw a focus indicator Draws a handle as used in #GtkHandleBox and #GtkPaned. Use gtk_render_handle() instead a #GtkStyle a #cairo_t a state type of shadow to draw the widget a style detail x origin of the handle y origin of the handle with of the handle height of the handle the orientation of the handle Draws a horizontal line from (@x1, @y) to (@x2, @y) in @cr using the given style and state. Use gtk_render_line() instead a #GtkStyle a #caio_t a state the widget a style detail the starting x coordinate the ending x coordinate the y coordinate Draws a layout on @cr using the given parameters. Use gtk_render_layout() instead a #GtkStyle a #cairo_t a state whether to use the text or foreground graphics context of @style the widget a style detail x origin y origin the layout to draw Draws a radio button indicator in the given rectangle on @cr with the given parameters. Use gtk_render_option() instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail x origin of the rectangle to draw the option in y origin of the rectangle to draw the option in the width of the rectangle to draw the option in the height of the rectangle to draw the option in Draws a resize grip in the given rectangle on @cr using the given parameters. Use gtk_render_handle() instead a #GtkStyle a #cairo_t a state the widget a style detail the edge in which to draw the resize grip the x origin of the rectangle in which to draw the resize grip the y origin of the rectangle in which to draw the resize grip the width of the rectangle in which to draw the resize grip the height of the rectangle in which to draw the resize grip Draws a shadow around the given rectangle in @cr using the given style and state and shadow type. Use gtk_render_frame() instead a #GtkStyle a #cairo_t a state type of shadow to draw the widget a style detail x origin of the rectangle y origin of the rectangle width of the rectangle width of the rectangle Draws a shadow around the given rectangle in @cr using the given style and state and shadow type, leaving a gap in one side. Use gtk_render_frame_gap() instead a #GtkStyle a #cairo_t a state type of shadow to draw the widget a style detail x origin of the rectangle y origin of the rectangle width of the rectangle width of the rectangle side in which to leave the gap starting position of the gap width of the gap Draws a slider in the given rectangle on @cr using the given style and orientation. Use gtk_render_slider() instead a #GtkStyle a #cairo_t a state a shadow the widget a style detail the x origin of the rectangle in which to draw a slider the y origin of the rectangle in which to draw a slider the width of the rectangle in which to draw a slider the height of the rectangle in which to draw a slider the orientation to be used Draws a spinner on @window using the given parameters. Use gtk_render_icon() and the #GtkStyleContext you are drawing instead a #GtkStyle a #cairo_t a state the widget (may be %NULL) a style detail (may be %NULL) the nth step the x origin of the rectangle in which to draw the spinner the y origin of the rectangle in which to draw the spinner the width of the rectangle in which to draw the spinner the height of the rectangle in which to draw the spinner Draws an option menu tab (i.e. the up and down pointing arrows) in the given rectangle on @cr using the given parameters. Use cairo instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail x origin of the rectangle to draw the tab in y origin of the rectangle to draw the tab in the width of the rectangle to draw the tab in the height of the rectangle to draw the tab in Draws a vertical line from (@x, @y1_) to (@x, @y2_) in @cr using the given style and state. Use gtk_render_line() instead a #GtkStyle a #cairo_t a state the widget a style detail the starting y coordinate the ending y coordinate the x coordinate Returns the name of the default paper size, which depends on the current locale. the name of the default paper size. The string is owned by GTK+ and should not be modified. Creates a list of known paper sizes. a newly allocated list of newly allocated #GtkPaperSize objects whether to include custom paper sizes as defined in the page setup dialog Parses command line arguments, and initializes global attributes of GTK+, but does not actually open a connection to a display. (See gdk_display_open(), gdk_get_display_arg_name()) Any arguments used by GTK+ or GDK are removed from the array and @argc and @argv are updated accordingly. There is no need to call this function explicitly if you are using gtk_init(), or gtk_init_check(). Note that many aspects of GTK+ require a display connection to function, so this way of initializing GTK+ is really only useful for specialized use cases. %TRUE if initialization succeeded, otherwise %FALSE a pointer to the number of command line arguments a pointer to the array of command line arguments Registers an error quark for #GtkPrintOperation if necessary. The error quark used for #GtkPrintOperation errors. Runs a page setup dialog, letting the user modify the values from @page_setup. If the user cancels the dialog, the returned #GtkPageSetup is identical to the passed in @page_setup, otherwise it contains the modifications done in the dialog. Note that this function may use a recursive mainloop to show the page setup dialog. See gtk_print_run_page_setup_dialog_async() if this is a problem. a new #GtkPageSetup transient parent an existing #GtkPageSetup a #GtkPrintSettings Runs a page setup dialog, letting the user modify the values from @page_setup. In contrast to gtk_print_run_page_setup_dialog(), this function returns after showing the page setup dialog on platforms that support this, and calls @done_cb from a signal handler for the ::response signal of the dialog. transient parent, or %NULL an existing #GtkPageSetup, or %NULL a #GtkPrintSettings a function to call when the user saves the modified page setup user data to pass to @done_cb Sends an event to a widget, propagating the event to parent widgets if the event remains unhandled. Events received by GTK+ from GDK normally begin in gtk_main_do_event(). Depending on the type of event, existence of modal dialogs, grabs, etc., the event may be propagated; if so, this function is used. gtk_propagate_event() calls gtk_widget_event() on each widget it decides to send the event to. So gtk_widget_event() is the lowest-level function; it simply emits the #GtkWidget::event and possibly an event-specific signal on a widget. gtk_propagate_event() is a bit higher-level, and gtk_main_do_event() is the highest level. All that said, you most likely don’t want to use any of these functions; synthesizing events is rarely needed. There are almost certainly better ways to achieve your goals. For example, use gdk_window_invalidate_rect() or gtk_widget_queue_draw() instead of making up expose events. a #GtkWidget an event Adds a file to the list of files to be parsed at the end of gtk_init(). Use #GtkStyleContext with a custom #GtkStyleProvider instead the pathname to the file. If @filename is not absolute, it is searched in the current directory. Searches for a theme engine in the GTK+ search path. This function is not useful for applications and should not be used. Use #GtkCssProvider instead. The filename, if found (must be freed with g_free()), otherwise %NULL. name of a theme engine Looks up a file in pixmap path for the specified #GtkSettings. If the file is not found, it outputs a warning message using g_warning() and returns %NULL. Use #GtkCssProvider instead. the filename. a #GtkSettings Scanner used to get line number information for the warning message, or %NULL name of the pixmap file to locate. Retrieves the current list of RC files that will be parsed at the end of gtk_init(). Use #GtkStyleContext instead A %NULL-terminated array of filenames. This memory is owned by GTK+ and must not be freed by the application. If you want to store this information, you should make a copy. Obtains the path to the IM modules file. See the documentation of the `GTK_IM_MODULE_FILE` environment variable for more details. Use #GtkCssProvider instead. a newly-allocated string containing the name of the file listing the IM modules available for loading Obtains the path in which to look for IM modules. See the documentation of the `GTK_PATH` environment variable for more details about looking up modules. This function is useful solely for utilities supplied with GTK+ and should not be used by applications under normal circumstances. Use #GtkCssProvider instead. a newly-allocated string containing the path in which to look for IM modules. Returns a directory in which GTK+ looks for theme engines. For full information about the search for theme engines, see the docs for `GTK_PATH` in [Running GTK+ Applications][gtk-running]. Use #GtkCssProvider instead. the directory. (Must be freed with g_free()) Finds all matching RC styles for a given widget, composites them together, and then creates a #GtkStyle representing the composite appearance. (GTK+ actually keeps a cache of previously created styles, so a new style may not be created.) Use #GtkStyleContext instead the resulting style. No refcount is added to the returned style, so if you want to save this style around, you should add a reference yourself. a #GtkWidget Creates up a #GtkStyle from styles defined in a RC file by providing the raw components used in matching. This function may be useful when creating pseudo-widgets that should be themed like widgets but don’t actually have corresponding GTK+ widgets. An example of this would be items inside a GNOME canvas widget. The action of gtk_rc_get_style() is similar to: |[<!-- language="C" --> gtk_widget_path (widget, NULL, &path, NULL); gtk_widget_class_path (widget, NULL, &class_path, NULL); gtk_rc_get_style_by_paths (gtk_widget_get_settings (widget), path, class_path, G_OBJECT_TYPE (widget)); ]| Use #GtkStyleContext instead A style created by matching with the supplied paths, or %NULL if nothing matching was specified and the default style should be used. The returned value is owned by GTK+ as part of an internal cache, so you must call g_object_ref() on the returned value if you want to keep a reference to it. a #GtkSettings object the widget path to use when looking up the style, or %NULL if no matching against the widget path should be done the class path to use when looking up the style, or %NULL if no matching against the class path should be done. a type that will be used along with parent types of this type when matching against class styles, or #G_TYPE_NONE Returns the standard directory in which themes should be installed. (GTK+ does not actually use this directory itself.) Use #GtkCssProvider instead. The directory (must be freed with g_free()). Parses a given resource file. Use #GtkCssProvider instead. the filename of a file to parse. If @filename is not absolute, it is searched in the current directory. Parses a color in the format expected in a RC file. Note that theme engines should use gtk_rc_parse_color_full() in order to support symbolic colors. Use #GtkCssProvider instead %G_TOKEN_NONE if parsing succeeded, otherwise the token that was expected but not found a #GScanner a pointer to a #GdkColor in which to store the result Parses a color in the format expected in a RC file. If @style is not %NULL, it will be consulted to resolve references to symbolic colors. Use #GtkCssProvider instead %G_TOKEN_NONE if parsing succeeded, otherwise the token that was expected but not found a #GScanner a #GtkRcStyle, or %NULL a pointer to a #GdkColor in which to store the result Parses a #GtkPathPriorityType variable from the format expected in a RC file. Use #GtkCssProvider instead %G_TOKEN_NONE if parsing succeeded, otherwise the token that was expected but not found. a #GScanner (must be initialized for parsing an RC file) A pointer to #GtkPathPriorityType variable in which to store the result. Parses a #GtkStateType variable from the format expected in a RC file. Use #GtkCssProvider instead %G_TOKEN_NONE if parsing succeeded, otherwise the token that was expected but not found. a #GScanner (must be initialized for parsing an RC file) A pointer to a #GtkStateType variable in which to store the result. Parses resource information directly from a string. Use #GtkCssProvider instead. a string to parse. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses borders in the form `"{ left, right, top, bottom }"` for integers left, right, top and bottom. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GtkBorder. a #GParamSpec the #GString to be parsed a #GValue which must hold boxed values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a color given either by its name or in the form `{ red, green, blue }` where red, green and blue are integers between 0 and 65535 or floating-point numbers between 0 and 1. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GdkColor. a #GParamSpec the #GString to be parsed a #GValue which must hold #GdkColor values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a single enumeration value. The enumeration value can be specified by its name, its nickname or its numeric value. For consistency with flags parsing, the value may be surrounded by parentheses. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GEnumValue. a #GParamSpec the #GString to be parsed a #GValue which must hold enum values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses flags. Flags can be specified by their name, their nickname or numerically. Multiple flags can be specified in the form `"( flag1 | flag2 | ... )"`. %TRUE if @gstring could be parsed and @property_value has been set to the resulting flags value. a #GParamSpec the #GString to be parsed a #GValue which must hold flags values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a requisition in the form `"{ width, height }"` for integers %width and %height. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GtkRequisition. a #GParamSpec the #GString to be parsed a #GValue which must hold boxed values. If the modification time on any previously read file for the default #GtkSettings has changed, discard all style information and then reread all previously read RC files. Use #GtkCssProvider instead. %TRUE if the files were reread. If the modification time on any previously read file for the given #GtkSettings has changed, discard all style information and then reread all previously read RC files. Use #GtkCssProvider instead. %TRUE if the files were reread. a #GtkSettings load whether or not anything changed This function recomputes the styles for all widgets that use a particular #GtkSettings object. (There is one #GtkSettings object per #GdkScreen, see gtk_settings_get_for_screen()); It is useful when some global parameter has changed that affects the appearance of all widgets, because when a widget gets a new style, it will both redraw and recompute any cached information about its appearance. As an example, it is used when the default font size set by the operating system changes. Note that this function doesn’t affect widgets that have a style set explicitly on them with gtk_widget_set_style(). Use #GtkCssProvider instead. a #GtkSettings Use #GtkCssProvider instead Sets the list of files that GTK+ will read at the end of gtk_init(). Use #GtkStyleContext with a custom #GtkStyleProvider instead A %NULL-terminated list of filenames. Renders an activity indicator (such as in #GtkSpinner). The state %GTK_STATE_FLAG_CHECKED determines whether there is activity going on. a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders an arrow pointing to @angle. Typical arrow rendering at 0, 1⁄2 π;, π; and 3⁄2 π: ![](arrows.png) a #GtkStyleContext a #cairo_t arrow angle from 0 to 2 * %G_PI, being 0 the arrow pointing to the north X origin of the render area Y origin of the render area square side for render area Renders the background of an element. Typical background rendering, showing the effect of `background-image`, `border-width` and `border-radius`: ![](background.png) a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Returns the area that will be affected (i.e. drawn to) when calling gtk_render_background() for the given @context and rectangle. a #GtkStyleContext X origin of the rectangle Y origin of the rectangle rectangle width rectangle height return location for the clip Renders a checkmark (as in a #GtkCheckButton). The %GTK_STATE_FLAG_CHECKED state determines whether the check is on or off, and %GTK_STATE_FLAG_INCONSISTENT determines whether it should be marked as undefined. Typical checkmark rendering: ![](checks.png) a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders an expander (as used in #GtkTreeView and #GtkExpander) in the area defined by @x, @y, @width, @height. The state %GTK_STATE_FLAG_CHECKED determines whether the expander is collapsed or expanded. Typical expander rendering: ![](expanders.png) a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a extension (as in a #GtkNotebook tab) in the rectangle defined by @x, @y, @width, @height. The side where the extension connects to is defined by @gap_side. Typical extension rendering: ![](extensions.png) a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height side where the gap is Renders a focus indicator on the rectangle determined by @x, @y, @width, @height. Typical focus rendering: ![](focus.png) a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a frame around the rectangle defined by @x, @y, @width, @height. Examples of frame rendering, showing the effect of `border-image`, `border-color`, `border-width`, `border-radius` and junctions: ![](frames.png) a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a frame around the rectangle defined by (@x, @y, @width, @height), leaving a gap on one side. @xy0_gap and @xy1_gap will mean X coordinates for %GTK_POS_TOP and %GTK_POS_BOTTOM gap sides, and Y coordinates for %GTK_POS_LEFT and %GTK_POS_RIGHT. Typical rendering of a frame with a gap: ![](frame-gap.png) Use gtk_render_frame() instead. Themes can create gaps by omitting borders via CSS. a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height side where the gap is initial coordinate (X or Y depending on @gap_side) for the gap end coordinate (X or Y depending on @gap_side) for the gap Renders a handle (as in #GtkHandleBox, #GtkPaned and #GtkWindow’s resize grip), in the rectangle determined by @x, @y, @width, @height. Handles rendered for the paned and grip classes: ![](handles.png) a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders the icon in @pixbuf at the specified @x and @y coordinates. This function will render the icon in @pixbuf at exactly its size, regardless of scaling factors, which may not be appropriate when drawing on displays with high pixel densities. You probably want to use gtk_render_icon_surface() instead, if you already have a Cairo surface. a #GtkStyleContext a #cairo_t a #GdkPixbuf containing the icon to draw X position for the @pixbuf Y position for the @pixbuf Renders the icon specified by @source at the given @size, returning the result in a pixbuf. Use gtk_icon_theme_load_icon() instead. a newly-created #GdkPixbuf containing the rendered icon a #GtkStyleContext the #GtkIconSource specifying the icon to render the size (#GtkIconSize) to render the icon at. A size of `(GtkIconSize) -1` means render at the size of the source and don’t scale. Renders the icon in @surface at the specified @x and @y coordinates. a #GtkStyleContext a #cairo_t a #cairo_surface_t containing the icon to draw X position for the @icon Y position for the @incon Draws a text caret on @cr at the specified index of @layout. a #GtkStyleContext a #cairo_t X origin Y origin the #PangoLayout of the text the index in the #PangoLayout the #PangoDirection of the text Renders @layout on the coordinates @x, @y a #GtkStyleContext a #cairo_t X origin Y origin the #PangoLayout to render Renders a line from (x0, y0) to (x1, y1). a #GtkStyleContext a #cairo_t X coordinate for the origin of the line Y coordinate for the origin of the line X coordinate for the end of the line Y coordinate for the end of the line Renders an option mark (as in a #GtkRadioButton), the %GTK_STATE_FLAG_CHECKED state will determine whether the option is on or off, and %GTK_STATE_FLAG_INCONSISTENT whether it should be marked as undefined. Typical option mark rendering: ![](options.png) a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a slider (as in #GtkScale) in the rectangle defined by @x, @y, @width, @height. @orientation defines whether the slider is vertical or horizontal. Typical slider rendering: ![](sliders.png) a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height orientation of the slider Converts a color from RGB space to HSV. Input values must be in the [0.0, 1.0] range; output values will be in the same range. Red Green Blue Return value for the hue component Return value for the saturation component Return value for the value component Appends a specified target to the list of supported targets for a given widget and selection. a #GtkWidget the selection target to add. A unsigned integer which will be passed back to the application. Prepends a table of targets to the list of supported targets for a given widget and selection. a #GtkWidget the selection a table of targets to add number of entries in @targets Remove all targets registered for the given selection for the widget. a #GtkWidget an atom representing a selection Requests the contents of a selection. When received, a “selection-received” signal will be generated. %TRUE if requested succeeded. %FALSE if we could not process request. (e.g., there was already a request in process for this widget). The widget which acts as requestor Which selection to get Form of information desired (e.g., STRING) Time of request (usually of triggering event) In emergency, you could use #GDK_CURRENT_TIME Claims ownership of a given selection for a particular widget, or, if @widget is %NULL, release ownership of the selection. %TRUE if the operation succeeded a #GtkWidget, or %NULL. an interned atom representing the selection to claim timestamp with which to claim the selection Claim ownership of a given selection for a particular widget, or, if @widget is %NULL, release ownership of the selection. TRUE if the operation succeeded the #GdkDisplay where the selection is set new selection owner (a #GtkWidget), or %NULL. an interned atom representing the selection to claim. timestamp with which to claim the selection Removes all handlers and unsets ownership of all selections for a widget. Called when widget is being destroyed. This function will not generally be called by applications. a #GtkWidget Sets the GTK+ debug flags. This is a convenience function for showing an application’s about box. The constructed dialog is associated with the parent window and reused for future invocations of this function. transient parent, or %NULL for none the name of the first property value of first property, followed by more properties, %NULL-terminated A convenience function for launching the default application to show the uri. Like gtk_show_uri_on_window(), but takes a screen as transient parent instead of a window. Note that this function is deprecated as it does not pass the necessary information for helpers to parent their dialog properly, when run from sandboxed applications for example. Use gtk_show_uri_on_window() instead. %TRUE on success, %FALSE on error screen to show the uri on or %NULL for the default screen the uri to show a timestamp to prevent focus stealing This is a convenience function for launching the default application to show the uri. The uri must be of a form understood by GIO (i.e. you need to install gvfs to get support for uri schemes such as http:// or ftp://, as only local files are handled by GIO itself). Typical examples are - `file:///home/gnome/pict.jpg` - `http://www.gnome.org` - `mailto:me@gnome.org` Ideally the timestamp is taken from the event triggering the gtk_show_uri() call. If timestamp is not known you can take %GDK_CURRENT_TIME. This is the recommended call to be used as it passes information necessary for sandbox helpers to parent their dialogs properly. %TRUE on success, %FALSE on error parent window the uri to show a timestamp to prevent focus stealing Registers each of the stock items in @items. If an item already exists with the same stock ID as one of the @items, the old item gets replaced. The stock items are copied, so GTK+ does not hold any pointer into @items and @items can be freed. Use gtk_stock_add_static() if @items is persistent and GTK+ need not copy the array. a #GtkStockItem or array of items number of #GtkStockItem in @items Same as gtk_stock_add(), but doesn’t copy @items, so @items must persist until application exit. a #GtkStockItem or array of #GtkStockItem number of items Retrieves a list of all known stock IDs added to a #GtkIconFactory or registered with gtk_stock_add(). The list must be freed with g_slist_free(), and each string in the list must be freed with g_free(). a list of known stock IDs Fills @item with the registered values for @stock_id, returning %TRUE if @stock_id was known. %TRUE if @item was initialized a stock item name stock item to initialize with values Sets a function to be used for translating the @label of a stock item. If no function is registered for a translation domain, g_dgettext() is used. The function is used for all stock items whose @translation_domain matches @domain. Note that it is possible to use strings different from the actual gettext translation domain of your application for this, as long as your #GtkTranslateFunc uses the correct domain when calling dgettext(). This can be useful, e.g. when dealing with message contexts: |[<!-- language="C" --> GtkStockItem items[] = { { MY_ITEM1, NC_("odd items", "Item 1"), 0, 0, "odd-item-domain" }, { MY_ITEM2, NC_("even items", "Item 2"), 0, 0, "even-item-domain" }, }; gchar * my_translate_func (const gchar *msgid, gpointer data) { gchar *msgctxt = data; return (gchar*)g_dpgettext2 (GETTEXT_PACKAGE, msgctxt, msgid); } ... gtk_stock_add (items, G_N_ELEMENTS (items)); gtk_stock_set_translate_func ("odd-item-domain", my_translate_func, "odd items"); gtk_stock_set_translate_func ("even-item-domain", my_translate_func, "even items"); ]| the translation domain for which @func shall be used a #GtkTranslateFunc data to pass to @func a #GDestroyNotify that is called when @data is no longer needed This function frees a target table as returned by gtk_target_table_new_from_list() a #GtkTargetEntry array the number of entries in the array This function creates an #GtkTargetEntry array that contains the same targets as the passed %list. The returned table is newly allocated and should be freed using gtk_target_table_free() when no longer needed. the new table. a #GtkTargetList return location for the number ot targets in the table Determines if any of the targets in @targets can be used to provide a #GdkPixbuf. %TRUE if @targets include a suitable target for images, otherwise %FALSE. an array of #GdkAtoms the length of @targets whether to accept only targets for which GTK+ knows how to convert a pixbuf into the format Determines if any of the targets in @targets can be used to provide rich text. %TRUE if @targets include a suitable target for rich text, otherwise %FALSE. an array of #GdkAtoms the length of @targets a #GtkTextBuffer Determines if any of the targets in @targets can be used to provide text. %TRUE if @targets include a suitable target for text, otherwise %FALSE. an array of #GdkAtoms the length of @targets Determines if any of the targets in @targets can be used to provide an uri list. %TRUE if @targets include a suitable target for uri lists, otherwise %FALSE. an array of #GdkAtoms the length of @targets Create a simple window with window title @window_title and text contents @dialog_text. The window will quit any running gtk_main()-loop when destroyed, and it will automatically be destroyed upon test function teardown. This testing infrastructure is phased out in favor of reftests. a widget pointer to the newly created GtkWindow. Title of the window to be displayed. Text inside the window to be displayed. This function wraps g_object_new() for widget types. It’ll automatically show all created non window widgets, also g_object_ref_sink() them (to keep them alive across a running test) and set them up for destruction during the next test teardown phase. This testing infrastructure is phased out in favor of reftests. a newly created widget. a valid widget type. Name of first property to set or %NULL value to set the first property to, followed by more name-value pairs, terminated by %NULL Create a window with window title @window_title, text contents @dialog_text, and a number of buttons, according to the paired argument list given as @... parameters. Each button is created with a @label and a ::clicked signal handler that incremrents the integer stored in @nump. The window will be automatically shown with gtk_widget_show_now() after creation, so when this function returns it has already been mapped, resized and positioned on screen. The window will quit any running gtk_main()-loop when destroyed, and it will automatically be destroyed upon test function teardown. This testing infrastructure is phased out in favor of reftests. a widget pointer to the newly created GtkWindow. Title of the window to be displayed. Text inside the window to be displayed. %NULL terminated list of (const char *label, int *nump) pairs. This function will search @widget and all its descendants for a GtkLabel widget with a text string matching @label_pattern. The @label_pattern may contain asterisks “*” and question marks “?” as placeholders, g_pattern_match() is used for the matching. Note that locales other than "C“ tend to alter (translate” label strings, so this function is genrally only useful in test programs with predetermined locales, see gtk_test_init() for more details. a GtkLabel widget if any is found. Valid label or container widget. Shell-glob pattern to match a label string. This function will search siblings of @base_widget and siblings of its ancestors for all widgets matching @widget_type. Of the matching widgets, the one that is geometrically closest to @base_widget will be returned. The general purpose of this function is to find the most likely “action” widget, relative to another labeling widget. Such as finding a button or text entry widget, given its corresponding label widget. a widget of type @widget_type if any is found. Valid widget, part of a widget hierarchy Type of a aearched for sibling widget This function will search the descendants of @widget for a widget of type @widget_type that has a label matching @label_pattern next to it. This is most useful for automated GUI testing, e.g. to find the “OK” button in a dialog and synthesize clicks on it. However see gtk_test_find_label(), gtk_test_find_sibling() and gtk_test_widget_click() for possible caveats involving the search of such widgets and synthesizing widget events. a valid widget if any is found or %NULL. Container widget, usually a GtkWindow. Shell-glob pattern to match a label string. Type of a aearched for label sibling widget. This function is used to initialize a GTK+ test program. It will in turn call g_test_init() and gtk_init() to properly initialize the testing framework and graphical toolkit. It’ll also set the program’s locale to “C” and prevent loading of rc files and Gtk+ modules. This is done to make tets program environments as deterministic as possible. Like gtk_init() and g_test_init(), any known arguments will be processed and stripped from @argc and @argv. Address of the `argc` parameter of the main() function. Changed if any arguments were handled. Address of the `argv` parameter of main(). Any parameters understood by g_test_init() or gtk_init() are stripped before return. currently unused Return the type ids that have been registered after calling gtk_test_register_all_types(). 0-terminated array of type ids location to store number of types Force registration of all core Gtk+ and Gdk object types. This allowes to refer to any of those object types via g_type_from_name() after calling this function. Retrive the literal adjustment value for GtkRange based widgets and spin buttons. Note that the value returned by this function is anything between the lower and upper bounds of the adjustment belonging to @widget, and is not a percentage as passed in to gtk_test_slider_set_perc(). This testing infrastructure is phased out in favor of reftests. gtk_adjustment_get_value (adjustment) for an adjustment belonging to @widget. valid widget pointer. This function will adjust the slider position of all GtkRange based widgets, such as scrollbars or scales, it’ll also adjust spin buttons. The adjustment value of these widgets is set to a value between the lower and upper limits, according to the @percentage argument. This testing infrastructure is phased out in favor of reftests. valid widget pointer. value between 0 and 100. This function will generate a @button click in the upwards or downwards spin button arrow areas, usually leading to an increase or decrease of spin button’s value. This testing infrastructure is phased out in favor of reftests. whether all actions neccessary for the button click simulation were carried out successfully. valid GtkSpinButton widget. Number of the pointer button for the event, usually 1, 2 or 3. %TRUE for upwards arrow click, %FALSE for downwards arrow click. Retrive the text string of @widget if it is a GtkLabel, GtkEditable (entry and text widgets) or GtkTextView. This testing infrastructure is phased out in favor of reftests. new 0-terminated C string, needs to be released with g_free(). valid widget pointer. Set the text string of @widget to @string if it is a GtkLabel, GtkEditable (entry and text widgets) or GtkTextView. This testing infrastructure is phased out in favor of reftests. valid widget pointer. a 0-terminated C string This function will generate a @button click (button press and button release event) in the middle of the first GdkWindow found that belongs to @widget. For windowless widgets like #GtkButton (which returns %FALSE from gtk_widget_get_has_window()), this will often be an input-only event window. For other widgets, this is usually widget->window. Certain caveats should be considered when using this function, in particular because the mouse pointer is warped to the button click location, see gdk_test_simulate_button() for details. This testing infrastructure is phased out in favor of reftests. whether all actions neccessary for the button click simulation were carried out successfully. Widget to generate a button click on. Number of the pointer button for the event, usually 1, 2 or 3. Keyboard modifiers the event is setup with. This function will generate keyboard press and release events in the middle of the first GdkWindow found that belongs to @widget. For windowless widgets like #GtkButton (which returns %FALSE from gtk_widget_get_has_window()), this will often be an input-only event window. For other widgets, this is usually widget->window. Certain caveats should be considered when using this function, in particular because the mouse pointer is warped to the key press location, see gdk_test_simulate_key() for details. whether all actions neccessary for the key event simulation were carried out successfully. Widget to generate a key press and release on. A Gdk keyboard value. Keyboard modifiers the event is setup with. Enters the main loop and waits for @widget to be “drawn”. In this context that means it waits for the frame clock of @widget to have run a full styling, layout and drawing cycle. This function is intended to be used for syncing with actions that depend on @widget relayouting or on interaction with the display server. the widget to wait for Obtains a @tree_model and @path from selection data of target type %GTK_TREE_MODEL_ROW. Normally called from a drag_data_received handler. This function can only be used if @selection_data originates from the same process that’s calling this function, because a pointer to the tree model is being passed around. If you aren’t in the same process, then you'll get memory corruption. In the #GtkTreeDragDest drag_data_received handler, you can assume that selection data of type %GTK_TREE_MODEL_ROW is in from the current process. The returned path must be freed with gtk_tree_path_free(). %TRUE if @selection_data had target type %GTK_TREE_MODEL_ROW and is otherwise valid a #GtkSelectionData a #GtkTreeModel row in @tree_model Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the #GtkTreeModel::row-deleted signal. a #GObject the path position that was deleted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the #GtkTreeModel::row-inserted signal. a #GObject the row position that was inserted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the #GtkTreeModel::rows-reordered signal. a #GObject the parent path of the reordered signal the iter pointing to the parent of the reordered the new order of rows Sets selection data of target type %GTK_TREE_MODEL_ROW. Normally used in a drag_data_get handler. %TRUE if the #GtkSelectionData had the proper target type to allow us to set a tree row some #GtkSelectionData a #GtkTreeModel a row in @tree_model All this function does it to return %TRUE. This can be useful for example if you want to inhibit the deletion of a window. Of course you should not do this as the user expects a reaction from clicking the close icon of the window... ## A persistent window |[<!-- language="C" --> #include <gtk/gtk.h> int main (int argc, char **argv) { GtkWidget *win, *but; const char *text = "Close yourself. I mean it!"; gtk_init (&argc, &argv); win = gtk_window_new (GTK_WINDOW_TOPLEVEL); g_signal_connect (win, "delete-event", G_CALLBACK (gtk_true), NULL); g_signal_connect (win, "destroy", G_CALLBACK (gtk_main_quit), NULL); but = gtk_button_new_with_label (text); g_signal_connect_swapped (but, "clicked", G_CALLBACK (gtk_object_destroy), win); gtk_container_add (GTK_CONTAINER (win), but); gtk_widget_show_all (win); gtk_main (); return 0; } ]| %TRUE Binds a callback function defined in a template to the @widget_class. This macro is a convenience wrapper around the gtk_widget_class_bind_template_callback_full() function. a #GtkWidgetClass the callback symbol Binds a child widget defined in a template to the @widget_class. This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function. This macro will use the offset of the @member_name inside the @TypeName instance structure. a #GtkWidgetClass the type name of this widget name of the instance member in the instance struct for @data_type Binds a child widget defined in a template to the @widget_class, and also makes it available as an internal child in GtkBuilder, under the name @member_name. This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function. This macro will use the offset of the @member_name inside the @TypeName instance structure. a #GtkWidgetClass the type name, in CamelCase name of the instance member in the instance struct for @data_type Binds a child widget defined in a template to the @widget_class, and also makes it available as an internal child in GtkBuilder, under the name @member_name. This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function. This macro will use the offset of the @member_name inside the @TypeName private data structure. a #GtkWidgetClass the type name, in CamelCase name of the instance private member on the private struct for @data_type Binds a child widget defined in a template to the @widget_class. This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function. This macro will use the offset of the @member_name inside the @TypeName private data structure (it uses G_PRIVATE_OFFSET(), so the private struct must be added with G_ADD_PRIVATE()). a #GtkWidgetClass the type name of this widget name of the instance private member in the private struct for @data_type soup3-0.9.0/gir-files/Gtk-4.0.gir000064400000000000000000274531601046102023000143350ustar 00000000000000 The rectangle representing the area allocated for a widget by its parent. An attribute for the background color, expressed as an RGB value encoded in a string using the format: `{r8},{g8},{b8}`. An attribute for the font family name. An attribute for the foreground color, expressed as an RGB value encoded in a string using the format: `{r8},{g8},{b8}`. An attribute for the overline style. Possible values are: - [const@Gtk.ACCESSIBLE_ATTRIBUTE_OVERLINE_NONE] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_OVERLINE_SINGLE] The "none" overline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_OVERLINE]. The "single" overline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_OVERLINE]. An attribute for the font size, expressed in points. An attribute for the font stretch type. Possible values are: - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH_ULTRA_CONDENSED] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH_EXTRA_CONDENSED] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH_CONDENSED] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH_SEMI_CONDENSED] The "condensed" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "expanded" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "extra condensed" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "extra expanded" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "normal" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "semi condensed" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "semi expanded" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "ultra condensed" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "ultra expanded" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. An attribute for strikethrough text. Possible values are `true` or `false`. An attribute for the font style. Possible values are: - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE_NORMAL] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE_OBLIQUE] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE_ITALIC] The "italic" style value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE]. The "normal" style value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE]. The "oblique" style value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE]. An attribute for the underline style. Possible values are: - [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE_NONE] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE_SINGLE] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE_DOUBLE] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE_ERROR] The "double" underline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE]. The "error" underline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE]. The "none" underline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE]. The "single" underline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE]. An attribute for the font variant. Possible values are: - [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_SMALL_CAPS] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_ALL_SMALL_CAPS] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_PETITE_CAPS] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_ALL_PETITE_CAPS] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_UNICASE] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_TITLE_CAPS] The "all petite caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. The "all small caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. The "petite caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. The "small caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. The "title caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. The "unicase" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. An attribute for the font weight. An undefined value. The accessible attribute is either unset, or its value is undefined. Communicates with platform-specific assistive technologies API. Each platform supported by GTK implements a `GtkATContext` subclass, and is responsible for updating the accessible state in response to state changes in `GtkAccessible`. Creates a new `GtkATContext` instance for the given accessible role, accessible instance, and display connection. The `GtkATContext` implementation being instantiated will depend on the platform. the `GtkATContext` the accessible role used by the `GtkATContext` the `GtkAccessible` implementation using the `GtkATContext` the `GdkDisplay` used by the `GtkATContext` Retrieves the `GtkAccessible` using this context. a `GtkAccessible` a `GtkATContext` Retrieves the accessible role of this context. a `GtkAccessibleRole` a `GtkATContext` The `GtkAccessible` that created the `GtkATContext` instance. The accessible role used by the AT context. Depending on the given role, different states and properties can be set or retrieved. The `GdkDisplay` for the `GtkATContext`. Emitted when the attributes of the accessible for the `GtkATContext` instance change. Displays information about a program. The shown information includes the programs' logo, name, copyright, website and license. It is also possible to give credits to the authors, documenters, translators and artists who have worked on the program. An about dialog is typically opened when the user selects the `About` option from the `Help` menu. All parts of the dialog are optional. <picture> <source srcset="aboutdialot-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkAboutDialog" src="aboutdialog.png"> </picture> About dialogs often contain links and email addresses. `GtkAboutDialog` displays these as clickable links. By default, it calls [method@Gtk.FileLauncher.launch] when a user clicks one. The behaviour can be overridden with the [signal@Gtk.AboutDialog::activate-link] signal. To specify a person with an email address, use a string like `Edgar Allan Poe <edgar@poe.com>`. To specify a website with a title, use a string like `GTK team https://www.gtk.org`. To make constructing an about dialog as convenient as possible, you can use the function [func@Gtk.show_about_dialog] which constructs and shows a dialog and keeps it around so that it can be shown again. Note that GTK sets a default title of `_("About %s")` on the dialog window (where `%s` is replaced by the name of the application, but in order to ensure proper translation of the title, applications should set the title property explicitly when constructing an about dialog, as shown in the following example: ```c GFile *logo_file = g_file_new_for_path ("./logo.png"); GdkTexture *example_logo = gdk_texture_new_from_file (logo_file, NULL); g_object_unref (logo_file); gtk_show_about_dialog (NULL, "program-name", "ExampleCode", "logo", example_logo, "title", _("About ExampleCode"), NULL); ``` ## Shortcuts and Gestures `GtkAboutDialog` supports the following keyboard shortcuts: - <kbd>Escape</kbd> closes the window. ## CSS nodes `GtkAboutDialog` has a single CSS node with the name `window` and style class `.aboutdialog`. Creates a new `GtkAboutDialog`. a newly created `GtkAboutDialog` Creates a new section in the "Credits" page. an about dialog The name of the section the people who belong to that section Returns the names of the artists which are displayed in the credits page. A `NULL`-terminated string array containing the artists an about dialog Returns the names of the authors which are displayed in the credits page. A `NULL`-terminated string array containing the authors an about dialog Returns the comments string. The comments an about dialog Returns the copyright string. The copyright string an about dialog Returns the name of the documenters which are displayed in the credits page. A `NULL`-terminated string array containing the documenters an about dialog Returns the license information. The license information an about dialog Retrieves the license type. a [enum@Gtk.License] value an about dialog Returns the paintable displayed as logo in the about dialog. the paintable displayed as logo or `NULL` if the logo is unset or has been set via [method@Gtk.AboutDialog.set_logo_icon_name] an about dialog Returns the icon name displayed as logo in the about dialog. the icon name displayed as logo, or `NULL` if the logo has been set via [method@Gtk.AboutDialog.set_logo] an about dialog Returns the program name displayed in the about dialog. the program name an about dialog Returns the system information that is shown in the about dialog. the system information an about dialog Returns the translator credits string which is displayed in the credits page. The translator credits string an about dialog Returns the version string. The version string an about dialog Returns the website URL. The website URL an about dialog Returns the label used for the website link. The label used for the website link an about dialog Returns whether the license text in the about dialog is automatically wrapped. `TRUE` if the license text is wrapped an about dialog Sets the names of the artists to be displayed in the "Credits" page. an about dialog the authors of the artwork of the application Sets the names of the authors which are displayed in the "Credits" page of the about dialog. an about dialog the authors of the application Sets the comments string to display in the about dialog. This should be a short string of one or two lines. an about dialog a comments string Sets the copyright string to display in the about dialog. This should be a short string of one or two lines. an about dialog the copyright string Sets the names of the documenters which are displayed in the "Credits" page. an about dialog the authors of the documentation of the application Sets the license information to be displayed in the about dialog. If `license` is `NULL`, the license page is hidden. an about dialog the license information Sets the license of the application showing the about dialog from a list of known licenses. This function overrides the license set using [method@Gtk.AboutDialog.set_license]. an about dialog the type of license Sets the logo in the about dialog. an about dialog a `GdkPaintable` Sets the icon name to be displayed as logo in the about dialog. an about dialog an icon name Sets the name to display in the about dialog. If `name` is not set, the string returned by `g_get_application_name()` is used. an about dialog the program name Sets the system information to be displayed in the about dialog. If `system_information` is `NULL`, the system information page is hidden. See [property@Gtk.AboutDialog:system-information]. an about dialog system information Sets the translator credits string which is displayed in the credits page. The intended use for this string is to display the translator of the language which is currently used in the user interface. Using `gettext()`, a simple way to achieve that is to mark the string for translation: ```c GtkWidget *about = gtk_about_dialog_new (); gtk_about_dialog_set_translator_credits (GTK_ABOUT_DIALOG (about), _("translator-credits")); ``` It is a good idea to use the customary `msgid` “translator-credits” for this purpose, since translators will already know the purpose of that `msgid`, and since `GtkAboutDialog` will detect if “translator-credits” is untranslated and omit translator credits. an about dialog the translator credits Sets the version string to display in the about dialog. an about dialog the version string Sets the URL to use for the website link. an about dialog a URL string starting with `http://` Sets the label to be used for the website link. an about dialog the label used for the website link Sets whether the license text in the about dialog should be automatically wrapped. an about dialog whether to wrap the license The people who contributed artwork to the program. Each string may contain email addresses and URLs, which will be displayed as links. The authors of the program. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. Comments about the program. This string is displayed in a label in the main dialog, thus it should be a short explanation of the main purpose of the program, not a detailed list of features. Copyright information for the program. The people documenting the program. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. The license of the program, as free-form text. This string is displayed in a text view in a secondary dialog, therefore it is fine to use a long multi-paragraph text. Note that the text is only wrapped in the text view if the "wrap-license" property is set to `TRUE`; otherwise the text itself must contain the intended linebreaks. When setting this property to a non-`NULL` value, the [property@Gtk.AboutDialog:license-type] property is set to [enum@Gtk.License.custom] as a side effect. The text may contain links in this format `<http://www.some.place/>` and email references in the form `<mail-to@some.body>`, and these will be converted into clickable links. The license of the program. The `GtkAboutDialog` will automatically fill out a standard disclaimer and link the user to the appropriate online resource for the license text. If [enum@Gtk.License.unknown] is used, the link used will be the same specified in the [property@Gtk.AboutDialog:website] property. If [enum@Gtk.License.custom] is used, the current contents of the [property@Gtk.AboutDialog:license] property are used. For any other [enum@Gtk.License] value, the contents of the [property@Gtk.AboutDialog:license] property are also set by this property as a side effect. A logo for the about box. If it is `NULL`, the default window icon set with [func@Gtk.Window.set_default_icon_name] will be used. A named icon to use as the logo for the about box. This property overrides the [property@Gtk.AboutDialog:logo] property. The name of the program. If this is not set, it defaults to the value returned by [func@GLib.get_application_name]. Information about the system on which the program is running. This information is displayed in a separate page, therefore it is fine to use a long multi-paragraph text. Note that the text should contain the intended linebreaks. The text may contain links in this format `<http://www.some.place/>` and email references in the form `<mail-to@some.body>`, and these will be converted into clickable links. Credits to the translators. This string should be marked as translatable. The string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. The version of the program. The URL for the link to the website of the program. This should be a string starting with `http://` or `https://`. The label for the link to the website of the program. Whether to wrap the text in the license dialog. Emitted every time a URL is activated. Applications may connect to it to override the default behaviour, which is to call [method@Gtk.FileLauncher.launch]. `TRUE` if the link has been activated the URI that is activated An interface for describing UI elements for Assistive Technologies. Every accessible implementation has: - a “role”, represented by a value of the [enum@Gtk.AccessibleRole] enumeration - “attributes”, represented by a set of [enum@Gtk.AccessibleState], [enum@Gtk.AccessibleProperty] and [enum@Gtk.AccessibleRelation] values The role cannot be changed after instantiating a `GtkAccessible` implementation. The attributes are updated every time a UI element's state changes in a way that should be reflected by assistive technologies. For instance, if a `GtkWidget` visibility changes, the %GTK_ACCESSIBLE_STATE_HIDDEN state will also change to reflect the [property@Gtk.Widget:visible] property. Every accessible implementation is part of a tree of accessible objects. Normally, this tree corresponds to the widget tree, but can be customized by reimplementing the [vfunc@Gtk.Accessible.get_accessible_parent], [vfunc@Gtk.Accessible.get_first_accessible_child] and [vfunc@Gtk.Accessible.get_next_accessible_sibling] virtual functions. Note that you can not create a top-level accessible object as of now, which means that you must always have a parent accessible object. Also note that when an accessible object does not correspond to a widget, and it has children, whose implementation you don't control, it is necessary to ensure the correct shape of the a11y tree by calling [method@Gtk.Accessible.set_accessible_parent] and updating the sibling by [method@Gtk.Accessible.update_next_accessible_sibling]. Retrieves the accessible identifier for the accessible object. This functionality can be overridden by `GtkAccessible` implementations. It is left to the accessible implementation to define the scope and uniqueness of the identifier. the accessible identifier an accessible object Retrieves the accessible parent for an accessible object. This function returns `NULL` for top level widgets. the accessible parent an accessible object Retrieves the implementation for the given accessible object. the accessible implementation object an accessible object Queries the coordinates and dimensions of this accessible This functionality can be overridden by `GtkAccessible` implementations, e.g. to get the bounds from an ignored child widget. true if the bounds are valid, and false otherwise an accessible object the x coordinate of the top left corner of the accessible the y coordinate of the top left corner of the widget the width of the accessible object the height of the accessible object Retrieves the first accessible child of an accessible object. the first accessible child an accessible object Retrieves the next accessible sibling of an accessible object the next accessible sibling an accessible object Queries a platform state, such as focus. This functionality can be overridden by `GtkAccessible` implementations, e.g. to get platform state from an ignored child widget, as is the case for `GtkText` wrappers. the value of state for the accessible an accessible object platform state to query Requests the user's screen reader to announce the given message. This kind of notification is useful for messages that either have only a visual representation or that are not exposed visually at all, e.g. a notification about a successful operation. Also, by using this API, you can ensure that the message does not interrupts the user's current screen reader output. an accessible object the string to announce the priority of the announcement Retrieves the accessible identifier for the accessible object. This functionality can be overridden by `GtkAccessible` implementations. It is left to the accessible implementation to define the scope and uniqueness of the identifier. the accessible identifier an accessible object Retrieves the accessible parent for an accessible object. This function returns `NULL` for top level widgets. the accessible parent an accessible object Retrieves the accessible role of an accessible object. the accessible role an accessible object Retrieves the implementation for the given accessible object. the accessible implementation object an accessible object Queries the coordinates and dimensions of this accessible This functionality can be overridden by `GtkAccessible` implementations, e.g. to get the bounds from an ignored child widget. true if the bounds are valid, and false otherwise an accessible object the x coordinate of the top left corner of the accessible the y coordinate of the top left corner of the widget the width of the accessible object the height of the accessible object Retrieves the first accessible child of an accessible object. the first accessible child an accessible object Retrieves the next accessible sibling of an accessible object the next accessible sibling an accessible object Queries a platform state, such as focus. This functionality can be overridden by `GtkAccessible` implementations, e.g. to get platform state from an ignored child widget, as is the case for `GtkText` wrappers. the value of state for the accessible an accessible object platform state to query Resets the accessible property to its default value. an accessible object the accessible property Resets the accessible relation to its default value. an accessible object the accessible relation Resets the accessible state to its default value. an accessible object the accessible state Sets the parent and sibling of an accessible object. This function is meant to be used by accessible implementations that are not part of the widget hierarchy, and but act as a logical bridge between widgets. For instance, if a widget creates an object that holds metadata for each child, and you want that object to implement the `GtkAccessible` interface, you will use this function to ensure that the parent of each child widget is the metadata object, and the parent of each metadata object is the container widget. an accessible object the parent accessible object the sibling accessible object Updates the next accessible sibling. That might be useful when a new child of a custom accessible is created, and it needs to be linked to a previous child. an accessible object the new next accessible sibling to set Informs ATs that the platform state has changed. This function should be used by `GtkAccessible` implementations that have a platform state but are not widgets. Widgets handle platform states automatically. an accessible object the platform state to update Updates a list of accessible properties. See the [enum@Gtk.AccessibleProperty] documentation for the value types of accessible properties. This function should be called by `GtkWidget` types whenever an accessible property change must be communicated to assistive technologies. Example: ```c value = gtk_adjustment_get_value (adjustment); gtk_accessible_update_property (GTK_ACCESSIBLE (spin_button), GTK_ACCESSIBLE_PROPERTY_VALUE_NOW, value, -1); ``` an accessible object the first accessible property a list of property and value pairs, terminated by -1 Updates an array of accessible properties. This function should be called by `GtkWidget` types whenever an accessible property change must be communicated to assistive technologies. This function is meant to be used by language bindings. an accessible object the number of accessible properties to set an array of accessible properties an array of `GValues`, one for each property Updates a list of accessible relations. This function should be called by `GtkWidget` types whenever an accessible relation change must be communicated to assistive technologies. If the [enum@Gtk.AccessibleRelation] requires a list of references, you should pass each reference individually, followed by `NULL`, e.g. ```c gtk_accessible_update_relation (accessible, GTK_ACCESSIBLE_RELATION_CONTROLS, ref1, NULL, GTK_ACCESSIBLE_RELATION_LABELLED_BY, ref1, ref2, ref3, NULL, -1); ``` an accessible object the first accessible relation a list of relation and value pairs, terminated by -1 Updates an array of accessible relations. This function should be called by `GtkWidget` types whenever an accessible relation change must be communicated to assistive technologies. This function is meant to be used by language bindings. an accessible object the number of accessible relations to set an array of accessible relations an array of `GValues`, one for each relation Updates a list of accessible states. See the [enum@Gtk.AccessibleState] documentation for the value types of accessible states. This function should be called by `GtkWidget` types whenever an accessible state change must be communicated to assistive technologies. Example: ```c value = GTK_ACCESSIBLE_TRISTATE_MIXED; gtk_accessible_update_state (GTK_ACCESSIBLE (check_button), GTK_ACCESSIBLE_STATE_CHECKED, value, -1); ``` an accessible object the first accessible state a list of state and value pairs, terminated by -1 Updates an array of accessible states. This function should be called by `GtkWidget` types whenever an accessible state change must be communicated to assistive technologies. This function is meant to be used by language bindings. an accessible objedct the number of accessible states to set an array of accessible states an array of `GValues`, one for each state The accessible role of the given `GtkAccessible` implementation. The accessible role cannot be changed once set. The priority of an accessibility announcement. The announcement is low priority, and might be read only on the user's request. The announcement is of medium priority, and is usually spoken at the next opportunity, such as at the end of speaking the current sentence or when the user pauses typing. The announcement is of high priority, and is usually spoken immediately. Because an interruption might disorient users or cause them to not complete their current task, authors SHOULD NOT use high priority announcements unless the interruption is imperative. An example would be a notification about a critical battery power level. The possible values for the %GTK_ACCESSIBLE_PROPERTY_AUTOCOMPLETE accessible property. Automatic suggestions are not displayed. When a user is providing input, text suggesting one way to complete the provided input may be dynamically inserted after the caret. When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. If displayed, one value in the collection is automatically selected, and the text needed to complete the automatically selected value appears after the caret in the input. Represents a link (i.e. a uri). A widget that contains one or more links should implement the [iface@Gtk.AccessibleHypertext] interface and return `GtkAccessibleHyperlink] objects for each of the links. Creates an accessible object that represents a hyperlink. This is meant to be used with an implementation of the [iface@Gtk.AccessibleHypertext] interface. the parent the index of this link in the parent the uri the text range that the link occupies (or 0, 0) Sets a platform state on the accessible. the accessible the platform state to change the new value for the platform state An interface for accessible objects containing links. The `GtkAccessibleHypertext` interfaces is meant to be implemented by accessible objects that contain links. Those links don't necessarily have to be part of text, they can be associated with images and other things. Retrieve the n-th link in the accessible object. @index must be smaller than the number of links. the link the accessible object the index of the link Retrieve the number of links in the accessible object. the number of links the accessible object The interface vtable for accessible objects containing links. the number of links the accessible object the link the accessible object the index of the link The common interface for accessible objects. retrieve the platform-specific accessibility context for the accessible implementation the accessible implementation object an accessible object retrieve the accessible state the value of state for the accessible an accessible object platform state to query the accessible parent an accessible object the first accessible child an accessible object the next accessible sibling an accessible object true if the bounds are valid, and false otherwise an accessible object the x coordinate of the top left corner of the accessible the y coordinate of the top left corner of the widget the width of the accessible object the height of the accessible object the accessible identifier an accessible object The possible values for the %GTK_ACCESSIBLE_STATE_INVALID accessible state. Note that the %GTK_ACCESSIBLE_INVALID_FALSE and %GTK_ACCESSIBLE_INVALID_TRUE have the same values as %FALSE and %TRUE. There are no detected errors in the value The value entered by the user has failed validation A grammatical error was detected A spelling error was detected Wraps a list of references to [iface@Gtk.Accessible] objects. Allocates a new list of accessible objects. the newly created list of accessible objects array of accessible objects length of the @accessibles array Allocates a new `GtkAccessibleList`, doing a shallow copy of the passed list of accessible objects the list of accessible objects a list of accessible objects Gets the list of objects this boxed type holds. a shallow copy of the objects The various platform states which can be queried using [method@Gtk.Accessible.get_platform_state]. whether the accessible can be focused whether the accessible has focus whether the accessible is active The possible accessible properties of a [iface@Accessible]. Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made. Value type: [enum@AccessibleAutocomplete] Defines a string value that describes or annotates the current element. Value type: string Indicates the availability of interactive popup element, such as menu or popover, that can be triggered by an element. Contrary to “aria-haspopup”, it doesn't indicate the type of the element, as such it cannot be used to indicate the availability of more complex elements such as dialog. Value type: boolean Indicates keyboard shortcuts that an author has implemented to activate or give focus to an element. Value type: string. The format of the value is a space-separated list of shortcuts, with each shortcut consisting of one or more modifiers (`Control`, `Alt` or `Shift`), followed by a non-modifier key, all separated by `+`. The [WAI-ARIA](https://www.w3.org/TR/wai-aria/#aria-keyshortcuts) reference specifies how to build keyboard shortcuts strings, with specific values for each key which are the same regardless of the language, so these strings can't be built from localized key names. You can convert an accelerator into the matching key shortcuts label with [func@Gtk.accelerator_get_accessible_label]. Examples: `F2`, `Alt+F`, `Control+Shift+N` Defines a string value that labels the current element. Value type: string Defines the hierarchical level of an element within a structure. Value type: integer Indicates whether an element is modal when displayed. Value type: boolean Indicates whether a text box accepts multiple lines of input or only a single line. Value type: boolean Indicates that the user may select more than one item from the current selectable descendants. Value type: boolean Indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. Value type: [enum@Orientation] Defines a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value. A hint could be a sample value or a brief description of the expected format. Value type: string Indicates that the element is not editable, but is otherwise operable. Value type: boolean Indicates that user input is required on the element before a form may be submitted. Value type: boolean Defines a human-readable, author-localized description for the role of an element. Value type: string Indicates if items in a table or grid are sorted in ascending or descending order. Value type: [enum@AccessibleSort] Defines the maximum allowed value for a range widget. Value type: double Defines the minimum allowed value for a range widget. Value type: double Defines the current value for a range widget. Value type: double Defines the human readable text alternative of [enum@Gtk.AccessibleProperty.VALUE_NOW] for a range widget. Value type: string Defines a string value that provides a description of non-standard keyboard interactions of the current element. Value type: string Initializes @value with the appropriate type for the @property. This function is mostly meant for language bindings, in conjunction with gtk_accessible_update_property_value(). a `GtkAccessibleProperty` an uninitialized `GValue` An interface for accessible objects containing a numeric value. `GtkAccessibleRange` describes ranged controls for Assistive Technologies. Ranged controls have a single value within an allowed range that can optionally be changed by the user. This interface is expected to be implemented by controls using the following roles: - `GTK_ACCESSIBLE_ROLE_METER` - `GTK_ACCESSIBLE_ROLE_PROGRESS_BAR` - `GTK_ACCESSIBLE_ROLE_SCROLLBAR` - `GTK_ACCESSIBLE_ROLE_SLIDER` - `GTK_ACCESSIBLE_ROLE_SPIN_BUTTON` If that is not the case, a warning will be issued at run time. In addition to this interface, its implementers are expected to provide the correct values for the following properties: - `GTK_ACCESSIBLE_PROPERTY_VALUE_MAX` - `GTK_ACCESSIBLE_PROPERTY_VALUE_MIN` - `GTK_ACCESSIBLE_PROPERTY_VALUE_NOW` - `GTK_ACCESSIBLE_PROPERTY_VALUE_TEXT` Sets the current value of the accessible range. This operation should behave similarly as if the user performed the action. true if the operation was performed, false otherwise a `GtkAccessibleRange` the value to set true if the operation was performed, false otherwise a `GtkAccessibleRange` the value to set The possible accessible relations of a [iface@Accessible]. Accessible relations can be references to other widgets, integers or strings. Identifies the currently active element when focus is on a composite widget, combobox, textbox, group, or application. Value type: reference Defines the total number of columns in a table, grid, or treegrid. Value type: integer Defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid. Value type: integer Defines a human readable text alternative of %GTK_ACCESSIBLE_RELATION_COL_INDEX. Value type: string Defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. Value type: integer Identifies the element (or elements) whose contents or presence are controlled by the current element. Value type: reference Identifies the element (or elements) that describes the object. Value type: reference Identifies the element (or elements) that provide additional information related to the object. Value type: reference Identifies the element (or elements) that provide an error message for an object. Value type: reference Identifies the next element (or elements) in an alternate reading order of content which, at the user's discretion, allows assistive technology to override the general default of reading in document source order. Value type: reference Identifies the element (or elements) that labels the current element. Value type: reference Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between elements where the widget hierarchy cannot be used to represent the relationship. Value type: reference Defines an element's number or position in the current set of listitems or treeitems. Value type: integer Defines the total number of rows in a table, grid, or treegrid. Value type: integer Defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid. Value type: integer Defines a human readable text alternative of [enum@Gtk.AccessibleRelation.ROW_INDEX]. Value type: string Defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. Value type: integer Defines the number of items in the current set of listitems or treeitems. Value type: integer Identifies the element (or elements) that are labeled by the current element. Value type: reference This relation is managed by GTK and should not be set from application code. Identifies the element (or elements) that are described by the current element. Value type: reference This relation is managed by GTK and should not be set from application code. Identifies the element (or elements) that the current element is controlled by. Value type: reference This relation is managed by GTK and should not be set from application code. Identifies the element (or elements) for which the current element provides additional information. Value type: reference This relation is managed by GTK and should not be set from application code. Identifies the element (or elements) for which the current element provides an error message. Value type: reference This relation is managed by GTK and should not be set from application code. Identifies the previous element (or elements) in an alternate reading order of content which, at the user's discretion, allows assistive technology to override the general default of reading in document source order. Value type: reference This relation is managed by GTK and should not be set from application code. Initializes @value with the appropriate type for the @relation. This function is mostly meant for language bindings, in conjunction with gtk_accessible_update_relation_value(). a `GtkAccessibleRelation` an uninitialized `GValue` The accessible role for a [iface@Accessible] implementation. Abstract roles are only used as part of the ontology; application developers must not use abstract roles in their code. An element with important, and usually time-sensitive, information A type of dialog that contains an alert message Unused An input element that allows for user-triggered actions when clicked or pressed Unused Unused A checkable input element that has three possible values: `true`, `false`, or `mixed` A header in a columned list. An input that controls another element, such as a list or a grid, that can dynamically pop up to help the user set the value of the input Abstract role. Abstract role. A dialog is a window that is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response. Content that assistive technology users may want to browse in a reading mode. Unused Unused A nameless container that has no semantic meaning of its own. This is the role that GTK uses by default for widgets. A grid of items. An item in a grid or tree grid. An element that groups multiple related widgets. GTK uses this role for various containers, like [class@Gtk.HeaderBar] or [class@Gtk.Notebook]. Unused An image. Abstract role. A visible name or caption for a user interface component. Abstract role. Unused A clickable link. A list of items. Unused. An item in a list. Unused Unused Unused Unused An element that represents a value within a known range. A menu. A menubar. An item in a menu. A check item in a menu. A radio item in a menu. Unused An element that is not represented to accessibility technologies. This role is synonymous to @GTK_ACCESSIBLE_ROLE_PRESENTATION. Unused Unused An element that is not represented to accessibility technologies. This role is synonymous to @GTK_ACCESSIBLE_ROLE_NONE. An element that displays the progress status for tasks that take a long time. A checkable input in a group of radio roles, only one of which can be checked at a time. Unused Abstract role. Unused A row in a columned list. Unused Unused A graphical object that controls the scrolling of content within a viewing area, regardless of whether the content is fully displayed within the viewing area. Unused A type of textbox intended for specifying search criteria. Abstract role. Abstract role. Abstract role. A divider that separates and distinguishes sections of content or groups of menuitems. A user input where the user selects a value from within a given range. A form of range that expects the user to select from among discrete choices. Unused Abstract role. A type of checkbox that represents on/off values, as opposed to checked/unchecked values. An item in a list of tab used for switching pages. Unused A list of tabs for switching pages. A page in a notebook or stack. A type of input that allows free-form text as its value. Unused Unused Unused Unused Unused A treeview-like, columned list. Unused Abstract role for interactive components of a graphical user interface Abstract role for windows. A type of push button which stays pressed until depressed by a second activation. A toplevel element of a graphical user interface. This is the role that GTK uses by default for windows. A paragraph of content. A section of content that is quoted from another source. A section of a page that consists of a composition that forms an independent part of a document, page, or site. A comment contains content expressing reaction to other content. A virtual terminal. The possible values for the %GTK_ACCESSIBLE_PROPERTY_SORT accessible property. There is no defined sort applied to the column. Items are sorted in ascending order by this column. Items are sorted in descending order by this column. A sort algorithm other than ascending or descending has been applied. The possible accessible states of a [iface@Accessible]. A “busy” state. This state has boolean values A “checked” state; indicates the current state of a [class@CheckButton]. Value type: [enum@AccessibleTristate] A “disabled” state; corresponds to the [property@Widget:sensitive] property. It indicates a UI element that is perceivable, but not editable or operable. Value type: boolean An “expanded” state; corresponds to the [property@Expander:expanded] property. Value type: boolean or undefined A “hidden” state; corresponds to the [property@Widget:visible] property. You can use this state explicitly on UI elements that should not be exposed to an assistive technology. Value type: boolean See also: %GTK_ACCESSIBLE_STATE_DISABLED An “invalid” state; set when a widget is showing an error. Value type: [enum@AccessibleInvalidState] A “pressed” state; indicates the current state of a [class@ToggleButton]. Value type: [enum@AccessibleTristate] enumeration A “selected” state; set when a widget is selected. Value type: boolean or undefined Indicates that a widget with the GTK_ACCESSIBLE_ROLE_LINK has been visited. Value type: boolean. Initializes @value with the appropriate type for the @state. This function is mostly meant for language bindings, in conjunction with gtk_accessible_update_relation_state(). a `GtkAccessibleState` an uninitialized `GValue` An interface for accessible objects containing formatted text. The `GtkAccessibleText` interfaces is meant to be implemented by accessible objects that have text formatted with attributes, or non-trivial text contents. You should use the [enum@Gtk.AccessibleProperty.LABEL] or the [enum@Gtk.AccessibleProperty.DESCRIPTION] properties for accessible objects containing simple, unformatted text. Retrieves the text attributes inside the accessible object. Each attribute is composed by: - a range - a name - a value It is left to the implementation to determine the serialization format of the value to a string. GTK provides support for various text attribute names and values, but implementations of this interface are free to add their own attributes. If this function returns true, `n_ranges` will be set to a value greater than or equal to one, @ranges will be set to a newly allocated array of [struct#Gtk.AccessibleTextRange]. true if the accessible object has at least an attribute, and false otherwise the accessible object the offset, in characters the number of attributes the ranges of the attributes inside the accessible object the names of the attributes inside the accessible object the values of the attributes inside the accessible object Retrieves the position of the caret inside the accessible object. the position of the caret, in characters the accessible object Retrieve the current contents of the accessible object within the given range. If @end is `G_MAXUINT`, the end of the range is the full content of the accessible object. the requested slice of the contents of the accessible object, as UTF-8. Note that the slice does not have to be NUL-terminated the accessible object the beginning of the range, in characters the end of the range, in characters Retrieve the current contents of the accessible object starting from the given offset, and using the given granularity. The @start and @end values contain the boundaries of the text. the requested slice of the contents of the accessible object, as UTF-8. Note that the slice does not have to be NUL-terminated the accessible object the offset, in characters the granularity of the query the start of the range, in characters the end of the range, in characters Retrieves the default text attributes inside the accessible object. Each attribute is composed by: - a name - a value It is left to the implementation to determine the serialization format of the value to a string. GTK provides support for various text attribute names and values, but implementations of this interface are free to add their own attributes. the accessible object the names of the default attributes inside the accessible object the values of the default attributes inside the accessible object Obtains the extents of a range of text, in widget coordinates. true if the extents were filled in, false otherwise the accessible object the start offset, in characters the end offset, in characters, @extents (out caller-allocates): return location for the extents Gets the text offset at a given point. true if the offset was set, false otherwise the accessible object a point in widget coordinates of @self return location for the text offset at @point Retrieves the selection ranges in the accessible object. If this function returns true, `n_ranges` will be set to a value greater than or equal to one, and @ranges will be set to a newly allocated array of [struct#Gtk.AccessibleTextRange]. true if there is at least a selection inside the accessible object, and false otherwise the accessible object the number of selection ranges the selection ranges Sets the caret position. true if the caret position was updated the accessible object the text offset in characters Sets the caret position. true if the selection was updated the accessible object the selection to set the range to set the selection to Updates the position of the caret. Implementations of the `GtkAccessibleText` interface should call this function every time the caret has moved, in order to notify assistive technologies. the accessible object Notifies assistive technologies of a change in contents. Implementations of the `GtkAccessibleText` interface should call this function every time their contents change as the result of an operation, like an insertion or a removal. Note: If the change is a deletion, this function must be called *before* removing the contents, if it is an insertion, it must be called *after* inserting the new contents. the accessible object the type of change in the contents the starting offset of the change, in characters the end offset of the change, in characters Updates the boundary of the selection. Implementations of the `GtkAccessibleText` interface should call this function every time the selection has moved, in order to notify assistive technologies. the accessible object The type of contents change operation. contents change as the result of an insert operation contents change as the result of a remove operation The granularity for queries about the text contents of a [iface@Gtk.AccessibleText] implementation. Use the boundary between characters (including non-printing characters) Use the boundary between words, starting from the beginning of the current word and ending at the beginning of the next word Use the boundary between sentences, starting from the beginning of the current sentence and ending at the beginning of the next sentence Use the boundary between lines, starting from the beginning of the current line and ending at the beginning of the next line Use the boundary between paragraphs, starting from the beginning of the current paragraph and ending at the beginning of the next paragraph The interface vtable for accessible objects containing text. the requested slice of the contents of the accessible object, as UTF-8. Note that the slice does not have to be NUL-terminated the accessible object the beginning of the range, in characters the end of the range, in characters the requested slice of the contents of the accessible object, as UTF-8. Note that the slice does not have to be NUL-terminated the accessible object the offset, in characters the granularity of the query the start of the range, in characters the end of the range, in characters the position of the caret, in characters the accessible object true if there is at least a selection inside the accessible object, and false otherwise the accessible object the number of selection ranges the selection ranges true if the accessible object has at least an attribute, and false otherwise the accessible object the offset, in characters the number of attributes the ranges of the attributes inside the accessible object the names of the attributes inside the accessible object the values of the attributes inside the accessible object the accessible object the names of the default attributes inside the accessible object the values of the default attributes inside the accessible object true if the extents were filled in, false otherwise the accessible object the start offset, in characters the end offset, in characters, @extents (out caller-allocates): return location for the extents true if the offset was set, false otherwise the accessible object a point in widget coordinates of @self return location for the text offset at @point true if the caret position was updated the accessible object the text offset in characters true if the selection was updated the accessible object the selection to set the range to set the selection to A range inside the text of an accessible object. the start of the range, in characters the length of the range, in characters The possible values for the %GTK_ACCESSIBLE_STATE_PRESSED accessible state. Note that the %GTK_ACCESSIBLE_TRISTATE_FALSE and %GTK_ACCESSIBLE_TRISTATE_TRUE have the same values as %FALSE and %TRUE. The state is `false` The state is `true` The state is `mixed` Presents contextual actions. <picture> <source srcset="action-bar-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkActionBar" src="action-bar.png"> </picture> `GtkActionBar` is expected to be displayed below the content and expand horizontally to fill the area. It allows placing children at the start or the end. In addition, it contains an internal centered box which is centered with respect to the full width of the box, even if the children at either side take up different amounts of space. # GtkActionBar as GtkBuildable The `GtkActionBar` implementation of the `GtkBuildable` interface supports adding children at the start or end sides by specifying “start” or “end” as the “type” attribute of a `<child>` element, or setting the center widget by specifying “center” value. # CSS nodes ``` actionbar ╰── revealer ╰── box ├── box.start │ ╰── [start children] ├── [center widget] ╰── box.end ╰── [end children] ``` A `GtkActionBar`'s CSS node is called `actionbar`. It contains a `revealer` subnode, which contains a `box` subnode, which contains two `box` subnodes at the start and end of the action bar, with `start` and `end` style classes respectively, as well as a center node that represents the center child. Each of the boxes contains children packed for that side. Creates a new action bar widget. a new `GtkActionBar` Retrieves the center bar widget of the bar. the center widget an action bsar Gets whether the contents of the action bar are revealed. the current value of the [property@Gtk.ActionBar:revealed] property an action bar Adds a child to the action bar, packed with reference to the end of the action bar. an action bar the widget to be added Adds a child to the action, packed with reference to the start of the action bar. an action bar the widget to be added Removes a child from the action bar. an action bar the widget to be removed Sets the center widget for the action bar. an action bar a widget to use for the center Reveals or conceals the content of the action bar. Note: this does not show or hide the action bar in the [property@Gtk.Widget:visible] sense, so revealing has no effect if the action bar is hidden. an action bar the new value for the property Controls whether the action bar shows its contents. Provides a way to associate widgets with actions. It primarily consists of two properties: [property@Gtk.Actionable:action-name] and [property@Gtk.Actionable:action-target]. There are also some convenience APIs for setting these properties. The action will be looked up in action groups that are found among the widgets ancestors. Most commonly, these will be the actions with the “win.” or “app.” prefix that are associated with the `GtkApplicationWindow` or `GtkApplication`, but other action groups that are added with [method@Gtk.Widget.insert_action_group] will be consulted as well. Gets the action name for @actionable. the action name a `GtkActionable` widget Gets the current target value of @actionable. the current target value a `GtkActionable` widget Specifies the name of the action with which this widget should be associated. If @action_name is %NULL then the widget will be unassociated from any previous action. Usually this function is used when the widget is located (or will be located) within the hierarchy of a `GtkApplicationWindow`. Names are of the form “win.save” or “app.quit” for actions on the containing [class@ApplicationWindow] or its associated [class@Application], respectively. This is the same form used for actions in the [class@Gio.Menu] associated with the window. a `GtkActionable` widget an action name Sets the target value of an actionable widget. If @target_value is %NULL then the target value is unset. The target value has two purposes. First, it is used as the parameter to activation of the action associated with the `GtkActionable` widget. Second, it is used to determine if the widget should be rendered as “active” — the widget is active if the state is equal to the given target. Consider the example of associating a set of buttons with a [iface@Gio.Action] with string state in a typical “radio button” situation. Each button will be associated with the same action, but with a different target value for that action. Clicking on a particular button will activate the action with the target of that button, which will typically cause the action’s state to change to that value. Since the action’s state is now equal to the target value of the button, the button will now be rendered as active (and the other buttons, with different targets, rendered inactive). a `GtkActionable` widget a [struct@GLib.Variant] to set as the target value Gets the action name for @actionable. the action name a `GtkActionable` widget Gets the current target value of @actionable. the current target value a `GtkActionable` widget Specifies the name of the action with which this widget should be associated. If @action_name is %NULL then the widget will be unassociated from any previous action. Usually this function is used when the widget is located (or will be located) within the hierarchy of a `GtkApplicationWindow`. Names are of the form “win.save” or “app.quit” for actions on the containing [class@ApplicationWindow] or its associated [class@Application], respectively. This is the same form used for actions in the [class@Gio.Menu] associated with the window. a `GtkActionable` widget an action name Sets the target of an actionable widget. This is a convenience function that calls [ctor@GLib.Variant.new] for @format_string and uses the result to call [method@Gtk.Actionable.set_action_target_value]. If you are setting a string-valued target and want to set the action name at the same time, you can use [method@Gtk.Actionable.set_detailed_action_name]. a `GtkActionable` widget a [struct@GLib.Variant] format string arguments appropriate for @format_string Sets the target value of an actionable widget. If @target_value is %NULL then the target value is unset. The target value has two purposes. First, it is used as the parameter to activation of the action associated with the `GtkActionable` widget. Second, it is used to determine if the widget should be rendered as “active” — the widget is active if the state is equal to the given target. Consider the example of associating a set of buttons with a [iface@Gio.Action] with string state in a typical “radio button” situation. Each button will be associated with the same action, but with a different target value for that action. Clicking on a particular button will activate the action with the target of that button, which will typically cause the action’s state to change to that value. Since the action’s state is now equal to the target value of the button, the button will now be rendered as active (and the other buttons, with different targets, rendered inactive). a `GtkActionable` widget a [struct@GLib.Variant] to set as the target value Sets the action-name and associated string target value of an actionable widget. @detailed_action_name is a string in the format accepted by [func@Gio.Action.parse_detailed_name]. a `GtkActionable` widget the detailed action name The name of the action with which this widget should be associated. The target value of the actionable widget's action. The interface vtable for `GtkActionable`. virtual function for [method@Actionable.get_action_name] the action name a `GtkActionable` widget virtual function for [method@Actionable.set_action_name] a `GtkActionable` widget an action name virtual function for [method@Actionable.get_action_target_value] the current target value a `GtkActionable` widget virtual function for [method@Actionable.set_action_target_value] a `GtkActionable` widget a [struct@GLib.Variant] to set as the target value Activates a widget. Widgets are activated by calling [method@Gtk.Widget.activate]. Gets the activate action. This is an action that calls gtk_widget_activate() on the given widget upon activation. The activate action A model for a numeric value. The `GtkAdjustment` has an associated lower and upper bound. It also contains step and page increments, and a page size. Adjustments are used within several GTK widgets, including [class@Gtk.SpinButton], [class@Gtk.Viewport], [class@Gtk.Scrollbar] and [class@Gtk.Scale]. The `GtkAdjustment` object does not update the value itself. Instead it is left up to the owner of the `GtkAdjustment` to control the value. Creates a new `GtkAdjustment`. a new `GtkAdjustment` the initial value the minimum value the maximum value the step increment the page increment the page size Updates the value of the adjustment to ensure that the given range is contained in the current page. The current page goes from `value` to `value` + `page-size`. If the range is larger than the page size, then only the start of it will be in the current page. A [signal@Gtk.Adjustment::value-changed] signal will be emitted if the value is changed. an adjustment the lower value the upper value Sets all properties of the adjustment at once. Use this function to avoid multiple emissions of the [signal@Gtk.Adjustment::changed] signal. See [method@Gtk.Adjustment.set_lower] for an alternative way of compressing multiple emissions of [signal@Gtk.Adjustment::changed] into one. an adjustment the new value the new minimum value the new maximum value the new step increment the new page increment the new page size Retrieves the minimum value of the adjustment. the minimum value an adjustment Gets the smaller of step increment and page increment. the minimum increment an adjustment Retrieves the page increment of the adjustment. the page increment an adjustment Retrieves the page size of the adjustment. the page size an adjustment Retrieves the step increment of the adjustment. the step increment an adjustment Retrieves the maximum value of the adjustment. the maximum value an adjustment Gets the current value of the adjustment. the current value an adjustment Sets the minimum value of the adjustment. When setting multiple adjustment properties via their individual setters, multiple [signal@Gtk.Adjustment::changed] signals will be emitted. However, since the emission of the [signal@Gtk.Adjustment::changed] signal is tied to the emission of the ::notify signals of the changed properties, it’s possible to compress the [signal@Gtk.Adjustment::changed] signals into one by calling g_object_freeze_notify() and g_object_thaw_notify() around the calls to the individual setters. Alternatively, using a single g_object_set() for all the properties to change, or using [method@Gtk.Adjustment.configure] has the same effect. an adjustment the new minimum value Sets the page increment of the adjustment. See [method@Gtk.Adjustment.set_lower] about how to compress multiple emissions of the [signal@Gtk.Adjustment::changed] signal when setting multiple adjustment properties. an adjustment the new page increment Sets the page size of the adjustment. See [method@Gtk.Adjustment.set_lower] about how to compress multiple emissions of the [signal@Gtk.Adjustment::changed] signal when setting multiple adjustment properties. an adjustment the new page size Sets the step increment of the adjustment. See [method@Gtk.Adjustment.set_lower] about how to compress multiple emissions of the [signal@Gtk.Adjustment::changed] signal when setting multiple adjustment properties. an adjustment the new step increment Sets the maximum value of the adjustment. Note that values will be restricted by `upper - page-size` if the page-size property is nonzero. See [method@Gtk.Adjustment.set_lower] about how to compress multiple emissions of the [signal@Gtk.Adjustment::changed] signal when setting multiple adjustment properties. an adjustment the new maximum value Sets the `GtkAdjustment` value. The value is clamped to lie between [property@Gtk.Adjustment:lower] and [property@Gtk.Adjustment:upper]. Note that for adjustments which are used in a `GtkScrollbar`, the effective range of allowed values goes from [property@Gtk.Adjustment:lower] to [property@Gtk.Adjustment:upper] - [property@Gtk.Adjustment:page-size]. an adjustment the new value The minimum value of the adjustment. The page increment of the adjustment. The page size of the adjustment. Note that the page-size is irrelevant and should be set to zero if the adjustment is used for a simple scalar value, e.g. in a `GtkSpinButton`. The step increment of the adjustment. The maximum value of the adjustment. Note that values will be restricted by `upper - page-size` if the page-size property is nonzero. The value of the adjustment. Emitted when one or more of the `GtkAdjustment` properties have been changed. Note that the [property@Gtk.Adjustment:value] property is covered by the [signal@Gtk.Adjustment::value-changed] signal. Emitted when the value has been changed. Collects the arguments that are needed to present a message to the user. The message is shown with the [method@Gtk.AlertDialog.choose] function. If you don't need to wait for a button to be clicked, you can use [method@Gtk.AlertDialog.show]. Creates a new `GtkAlertDialog` object. The message will be set to the formatted string resulting from the arguments. the new `GtkAlertDialog` `printf()`-style format string arguments for @format Shows the alert to the user. It is ok to pass `NULL` for the callback if the alert does not have more than one button. A simpler API for this case is [method@Gtk.AlertDialog.show]. an alert dialog the parent window a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.AlertDialog.choose] call. the index of the button that was clicked, or -1 if the dialog was cancelled and [property@Gtk.AlertDialog:cancel-button] is not set an alert dialog the result Returns the button labels for the alert. the button labels an alert dialog Returns the index of the cancel button. the index of the cancel button, or -1 an alert dialog Returns the index of the default button. the index of the default button, or -1 an alert dialog Returns the detail text that will be shown in the alert. the detail text an alert dialog Returns the message that will be shown in the alert. the message an alert dialog Returns whether the alert blocks interaction with the parent window while it is presented. true if the alert is modal an alert dialog Sets the button labels for the alert. an alert dialog the new button labels Sets the index of the cancel button. See [property@Gtk.AlertDialog:cancel-button] for details of how this value is used. an alert dialog the new cancel button Sets the index of the default button. See [property@Gtk.AlertDialog:default-button] for details of how this value is used. an alert dialog the new default button Sets the detail text that will be shown in the alert. an alert dialog the new detail text Sets the message that will be shown in the alert. an alert dialog the new message Sets whether the alert blocks interaction with the parent window while it is presented. an alert dialog the new value Shows the alert to the user. This function is a simpler version of [method@Gtk.AlertDialog.choose] intended for dialogs with a single button. If you want to cancel the dialog or if the alert has more than one button, you should use that function instead and provide it with a [class@Gio.Cancellable] and callback respectively. an alert dialog the parent window Labels for buttons to show in the alert. The labels should be translated and may contain a `_` character to indicate the mnemonic character. If this property is not set, then a 'Close' button is automatically created. Determines what happens when the <kbd>Escape</kbd> key is pressed while the alert is shown. If this property holds the index of a button in [property@Gtk.AlertDialog:buttons], then pressing Escape is treated as if that button was pressed. If it is -1 or not a valid index for the `buttons` array, then an error is returned. If `buttons` is `NULL`, then the automatically created 'Close' button is treated as both cancel and default button, so 0 is returned. Determines what happens when the <kbd>Return</kbd> key is pressed while the alert is shown. If this property holds the index of a button in [property@Gtk.AlertDialog:buttons], then pressing Return is treated as if that button was pressed. If it is -1 or not a valid index for the `buttons` array, then nothing happens. If `buttons` is `NULL`, then the automatically created 'Close' button is treated as both cancel and default button, so 0 is returned. The detail text for the alert. The message for the alert. Whether the alert is modal. Controls how a widget deals with extra space in a single dimension. Alignment only matters if the widget receives a “too large” allocation, for example if you packed the widget with the [property@Gtk.Widget:hexpand] property inside a [class@Box], then the widget might get extra space. If you have for example a 16x16 icon inside a 32x32 space, the icon could be scaled and stretched, it could be centered, or it could be positioned to one side of the space. Note that in horizontal context `GTK_ALIGN_START` and `GTK_ALIGN_END` are interpreted relative to text direction. Baseline support is optional for containers and widgets, and is only available for vertical alignment. `GTK_ALIGN_BASELINE_CENTER` and `GTK_ALIGN_BASELINE_FILL` are treated similar to `GTK_ALIGN_CENTER` and `GTK_ALIGN_FILL`, except that it positions the widget to line up the baselines, where that is supported. stretch to fill all space if possible, center if no meaningful way to stretch snap to left or top side, leaving space on right or bottom snap to right or bottom side, leaving space on left or top center natural width of widget inside the allocation a different name for `GTK_ALIGN_BASELINE`. align the widget according to the baseline. Use `GTK_ALIGN_BASELINE_FILL` instead stretch to fill all space, but align the baseline. Combines two shortcut triggers. The `GtkAlternativeTrigger` triggers when either of the two trigger. This can be cascaded to combine more than two triggers. Creates a `GtkShortcutTrigger` that will trigger whenever either of the two given triggers gets triggered. Note that nesting is allowed, so if you want more than two alternative, create a new alternative trigger for each option. a new `GtkShortcutTrigger` The first trigger that may trigger The second trigger that may trigger Gets the first of the two alternative triggers that may trigger @self. [method@Gtk.AlternativeTrigger.get_second] will return the other one. the first alternative trigger an alternative `GtkShortcutTrigger` Gets the second of the two alternative triggers that may trigger @self. [method@Gtk.AlternativeTrigger.get_first] will return the other one. the second alternative trigger an alternative `GtkShortcutTrigger` The first `GtkShortcutTrigger` to check. The second `GtkShortcutTrigger` to check. Matches an item when at least one of its filters matches. To add filters to a `GtkAnyFilter`, use [method@Gtk.MultiFilter.append]. Creates a new empty "any" filter. Use [method@Gtk.MultiFilter.append] to add filters to it. This filter matches an item if any of the filters added to it matches the item. In particular, this means that if no filter has been added to it, the filter matches no item. a new `GtkAnyFilter` `GtkAppChooser` is an interface for widgets which allow the user to choose an application. The main objects that implement this interface are [class@Gtk.AppChooserWidget], [class@Gtk.AppChooserDialog] and [class@Gtk.AppChooserButton]. Applications are represented by GIO `GAppInfo` objects here. GIO has a concept of recommended and fallback applications for a given content type. Recommended applications are those that claim to handle the content type itself, while fallback also includes applications that handle a more generic content type. GIO also knows the default and last-used application for a given content type. The `GtkAppChooserWidget` provides detailed control over whether the shown list of applications should include default, recommended or fallback applications. To obtain the application that has been selected in a `GtkAppChooser`, use [method@Gtk.AppChooser.get_app_info]. The application selection widgets should be implemented according to the design of each platform and/or application requiring them. Returns the currently selected application. This widget will be removed in GTK 5 a `GAppInfo` for the currently selected application a `GtkAppChooser` Returns the content type for which the `GtkAppChooser` shows applications. This widget will be removed in GTK 5 the content type of @self. Free with g_free() a `GtkAppChooser` Reloads the list of applications. This widget will be removed in GTK 5 a `GtkAppChooser` The content type of the `GtkAppChooser` object. See `GContentType` for more information about content types. The `GtkAppChooserButton` lets the user select an application. <picture> <source srcset="appchooserbutton-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkAppChooserButton" src="appchooserbutton.png"> </picture> Initially, a `GtkAppChooserButton` selects the first application in its list, which will either be the most-recently used application or, if [property@Gtk.AppChooserButton:show-default-item] is %TRUE, the default application. The list of applications shown in a `GtkAppChooserButton` includes the recommended applications for the given content type. When [property@Gtk.AppChooserButton:show-default-item] is set, the default application is also included. To let the user chooser other applications, you can set the [property@Gtk.AppChooserButton:show-dialog-item] property, which allows to open a full [class@Gtk.AppChooserDialog]. It is possible to add custom items to the list, using [method@Gtk.AppChooserButton.append_custom_item]. These items cause the [signal@Gtk.AppChooserButton::custom-item-activated] signal to be emitted when they are selected. To track changes in the selected application, use the [signal@Gtk.AppChooserButton::changed] signal. ## CSS nodes `GtkAppChooserButton` has a single CSS node with the name “appchooserbutton”. The application selection widgets should be implemented according to the design of each platform and/or application requiring them. Creates a new `GtkAppChooserButton` for applications that can handle content of the given type. This widget will be removed in GTK 5 a newly created `GtkAppChooserButton` the content type to show applications for Appends a custom item to the list of applications that is shown in the popup. The item name must be unique per-widget. Clients can use the provided name as a detail for the [signal@Gtk.AppChooserButton::custom-item-activated] signal, to add a callback for the activation of a particular custom item in the list. See also [method@Gtk.AppChooserButton.append_separator]. This widget will be removed in GTK 5 a `GtkAppChooserButton` the name of the custom item the label for the custom item the icon for the custom item Appends a separator to the list of applications that is shown in the popup. This widget will be removed in GTK 5 a `GtkAppChooserButton` Returns the text to display at the top of the dialog. This widget will be removed in GTK 5 the text to display at the top of the dialog, or %NULL, in which case a default text is displayed a `GtkAppChooserButton` Gets whether the dialog is modal. This widget will be removed in GTK 5 %TRUE if the dialog is modal a `GtkAppChooserButton` Returns whether the dropdown menu should show the default application at the top. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserButton:show-default-item] a `GtkAppChooserButton` Returns whether the dropdown menu shows an item for a `GtkAppChooserDialog`. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserButton:show-dialog-item] a `GtkAppChooserButton` Selects a custom item. See [method@Gtk.AppChooserButton.append_custom_item]. Use [method@Gtk.AppChooser.refresh] to bring the selection to its initial state. This widget will be removed in GTK 5 a `GtkAppChooserButton` the name of the custom item Sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text. This widget will be removed in GTK 5 a `GtkAppChooserButton` a string containing Pango markup Sets whether the dialog should be modal. This widget will be removed in GTK 5 a `GtkAppChooserButton` %TRUE to make the dialog modal Sets whether the dropdown menu of this button should show the default application for the given content type at top. This widget will be removed in GTK 5 a `GtkAppChooserButton` the new value for [property@Gtk.AppChooserButton:show-default-item] Sets whether the dropdown menu of this button should show an entry to trigger a `GtkAppChooserDialog`. This widget will be removed in GTK 5 a `GtkAppChooserButton` the new value for [property@Gtk.AppChooserButton:show-dialog-item] The text to show at the top of the dialog that can be opened from the button. The string may contain Pango markup. Whether the app chooser dialog should be modal. Determines whether the dropdown menu shows the default application on top for the provided content type. Determines whether the dropdown menu shows an item to open a `GtkAppChooserDialog`. Emitted to when the button is activated. The `::activate` signal on `GtkAppChooserButton` is an action signal and emitting it causes the button to pop up its dialog. Emitted when the active application changes. Emitted when a custom item is activated. Use [method@Gtk.AppChooserButton.append_custom_item], to add custom items. the name of the activated item `GtkAppChooserDialog` shows a `GtkAppChooserWidget` inside a `GtkDialog`. <picture> <source srcset="appchooserdialog-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkAppChooserDialog" src="appchooserdialog.png"> </picture> Note that `GtkAppChooserDialog` does not have any interesting methods of its own. Instead, you should get the embedded `GtkAppChooserWidget` using [method@Gtk.AppChooserDialog.get_widget] and call its methods if the generic [iface@Gtk.AppChooser] interface is not sufficient for your needs. To set the heading that is shown above the `GtkAppChooserWidget`, use [method@Gtk.AppChooserDialog.set_heading]. ## CSS nodes `GtkAppChooserDialog` has a single CSS node with the name `window` and style class `.appchooser`. The application selection widgets should be implemented according to the design of each platform and/or application requiring them. Creates a new `GtkAppChooserDialog` for the provided `GFile`. The dialog will show applications that can open the file. This widget will be removed in GTK 5 a newly created `GtkAppChooserDialog` a `GtkWindow` flags for this dialog a `GFile` Creates a new `GtkAppChooserDialog` for the provided content type. The dialog will show applications that can open the content type. This widget will be removed in GTK 5 a newly created `GtkAppChooserDialog` a `GtkWindow` flags for this dialog a content type string Returns the text to display at the top of the dialog. This widget will be removed in GTK 5 the text to display at the top of the dialog, or %NULL, in which case a default text is displayed a `GtkAppChooserDialog` Returns the `GtkAppChooserWidget` of this dialog. This widget will be removed in GTK 5 the `GtkAppChooserWidget` of @self a `GtkAppChooserDialog` Sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text. This widget will be removed in GTK 5 a `GtkAppChooserDialog` a string containing Pango markup The GFile used by the `GtkAppChooserDialog`. The dialog's `GtkAppChooserWidget` content type will be guessed from the file, if present. The text to show at the top of the dialog. The string may contain Pango markup. `GtkAppChooserWidget` is a widget for selecting applications. It is the main building block for [class@Gtk.AppChooserDialog]. Most applications only need to use the latter; but you can use this widget as part of a larger widget if you have special needs. `GtkAppChooserWidget` offers detailed control over what applications are shown, using the [property@Gtk.AppChooserWidget:show-default], [property@Gtk.AppChooserWidget:show-recommended], [property@Gtk.AppChooserWidget:show-fallback], [property@Gtk.AppChooserWidget:show-other] and [property@Gtk.AppChooserWidget:show-all] properties. See the [iface@Gtk.AppChooser] documentation for more information about these groups of applications. To keep track of the selected application, use the [signal@Gtk.AppChooserWidget::application-selected] and [signal@Gtk.AppChooserWidget::application-activated] signals. ## CSS nodes `GtkAppChooserWidget` has a single CSS node with name appchooser. The application selection widgets should be implemented according to the design of each platform and/or application requiring them. Creates a new `GtkAppChooserWidget` for applications that can handle content of the given type. This widget will be removed in GTK 5 a newly created `GtkAppChooserWidget` the content type to show applications for Returns the text that is shown if there are not applications that can handle the content type. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserWidget:default-text] a `GtkAppChooserWidget` Gets whether the app chooser should show all applications in a flat list. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserWidget:show-all] a `GtkAppChooserWidget` Gets whether the app chooser should show the default handler for the content type in a separate section. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserWidget:show-default] a `GtkAppChooserWidget` Gets whether the app chooser should show related applications for the content type in a separate section. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserWidget:show-fallback] a `GtkAppChooserWidget` Gets whether the app chooser should show applications which are unrelated to the content type. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserWidget:show-other] a `GtkAppChooserWidget` Gets whether the app chooser should show recommended applications for the content type in a separate section. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserWidget:show-recommended] a `GtkAppChooserWidget` Sets the text that is shown if there are not applications that can handle the content type. This widget will be removed in GTK 5 a `GtkAppChooserWidget` the new value for [property@Gtk.AppChooserWidget:default-text] Sets whether the app chooser should show all applications in a flat list. This widget will be removed in GTK 5 a `GtkAppChooserWidget` the new value for [property@Gtk.AppChooserWidget:show-all] Sets whether the app chooser should show the default handler for the content type in a separate section. This widget will be removed in GTK 5 a `GtkAppChooserWidget` the new value for [property@Gtk.AppChooserWidget:show-default] Sets whether the app chooser should show related applications for the content type in a separate section. This widget will be removed in GTK 5 a `GtkAppChooserWidget` the new value for [property@Gtk.AppChooserWidget:show-fallback] Sets whether the app chooser should show applications which are unrelated to the content type. This widget will be removed in GTK 5 a `GtkAppChooserWidget` the new value for [property@Gtk.AppChooserWidget:show-other] Sets whether the app chooser should show recommended applications for the content type in a separate section. This widget will be removed in GTK 5 a `GtkAppChooserWidget` the new value for [property@Gtk.AppChooserWidget:show-recommended] The text that appears in the widget when there are no applications for the given content type. If %TRUE, the app chooser presents all applications in a single list, without subsections for default, recommended or related applications. Determines whether the app chooser should show the default handler for the content type in a separate section. If %FALSE, the default handler is listed among the recommended applications. Determines whether the app chooser should show a section for fallback applications. If %FALSE, the fallback applications are listed among the other applications. Determines whether the app chooser should show a section for other applications. Determines whether the app chooser should show a section for recommended applications. If %FALSE, the recommended applications are listed among the other applications. Emitted when an application item is activated from the widget's list. This usually happens when the user double clicks an item, or an item is selected and the user presses one of the keys Space, Shift+Space, Return or Enter. the activated `GAppInfo` Emitted when an application item is selected from the widget's list. the selected `GAppInfo` A high-level API for writing applications. `GtkApplication` supports many aspects of writing a GTK application in a convenient fashion, without enforcing a one-size-fits-all model. Currently, it handles GTK initialization, application uniqueness, session management, provides some basic scriptability and desktop shell integration by exporting actions and menus and manages a list of toplevel windows whose life-cycle is automatically tied to the life-cycle of your application. While `GtkApplication` works fine with plain [class@Gtk.Window]s, it is recommended to use it together with [class@Gtk.ApplicationWindow]. ## Initialization A typical `GtkApplication` will create a window in its [signal@GIO.Application::activate], [signal@GIO.Application::open] or [signal@GIO.Application::command-line] handlers. Note that all of these signals may be emitted multiple times, so handlers must be careful to take existing windows into account. A typical ::activate handler should look like this: ``` static void activate (GApplication *gapp) { GtkApplication *app = GTK_APPLICATION (gapp); GtkWindow *window; window = gtk_application_get_active_window (app); if (!window) window = create_window (app); gtk_window_present (window); } ``` ## Automatic resources `GtkApplication` will automatically load menus from the `GtkBuilder` resource located at "gtk/menus.ui", relative to the application's resource base path (see [method@Gio.Application.set_resource_base_path]). The menu with the ID "menubar" is taken as the application's menubar. Additional menus (most interesting submenus) can be named and accessed via [method@Gtk.Application.get_menu_by_id] which allows for dynamic population of a part of the menu structure. Note that automatic resource loading uses the resource base path that is set at construction time and will not work if the resource base path is changed at a later time. It is also possible to provide the menubar manually using [method@Gtk.Application.set_menubar]. `GtkApplication` will also automatically setup an icon search path for the default icon theme by appending "icons" to the resource base path. This allows your application to easily store its icons as resources. See [method@Gtk.IconTheme.add_resource_path] for more information. If there is a resource located at `gtk/help-overlay.ui` which defines a [class@Gtk.ShortcutsWindow] with ID `help_overlay` then `GtkApplication` associates an instance of this shortcuts window with each [class@Gtk.ApplicationWindow] and sets up the keyboard accelerator <kbd>Control</kbd>+<kbd>?</kbd> to open it. To create a menu item that displays the shortcuts window, associate the item with the action `win.show-help-overlay`. `GtkApplication` will also automatically set the application id as the default window icon. Use [func@Gtk.Window.set_default_icon_name] or [property@Gtk.Window:icon-name] to override that behavior. # Inhibiting An application can block various ways to end the session with the [method@Gtk.Application.inhibit] function. Typical use cases for this kind of inhibiting are long-running, uninterruptible operations, such as burning a CD or performing a disk backup. The session manager may not honor the inhibitor, but it can be expected to inform the user about the negative consequences of ending the session while inhibitors are present. ## A simple application [A simple example](https://gitlab.gnome.org/GNOME/gtk/tree/main/examples/bp/bloatpad.c) is available in the GTK source code repository ## See Also - [Using GtkApplication](https://developer.gnome.org/documentation/tutorials/application.html) - [Getting Started with GTK: Basics](getting_started.html#basics) Creates a new application instance. When using `GtkApplication`, it is not necessary to call [func@Gtk.init] manually. It is called as soon as the application gets registered as the primary instance. Concretely, [func@Gtk.init] is called in the default handler for the `GApplication::startup` signal. Therefore, `GtkApplication` subclasses should always chain up in their [vfunc@GIO.Application.startup] handler before using any GTK API. Note that commandline arguments are not passed to [func@Gtk.init]. If `application_id` is not `NULL`, then it must be valid. See [func@Gio.Application.id_is_valid]. If no application ID is given then some features (most notably application uniqueness) will be disabled. a new `GtkApplication` instance The application ID the application flags Signal emitted when a `GtkWindow` is added to application through gtk_application_add_window(). Signal emitted when a `GtkWindow` is removed from application, either as a side-effect of being destroyed or explicitly through gtk_application_remove_window(). Adds a window to the application. This call can only happen after the application has started; typically, you should add new application windows in response to the emission of the [signal@GIO.Application::activate] signal. This call is equivalent to setting the [property@Gtk.Window:application] property of the window to @application. Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it with [method@Gtk.Application.remove_window]. GTK will keep the application running as long as it has any windows. an application a window Gets the accelerators that are currently associated with the given action. accelerators for @detailed_action_name an application a detailed action name, specifying an action and target to obtain accelerators for Returns the list of actions (possibly empty) that the accelerator maps to. Each item in the list is a detailed action name in the usual form. This might be useful to discover if an accel already exists in order to prevent installation of a conflicting accelerator (from an accelerator editor or a plugin system, for example). Note that having more than one action per accelerator may not be a bad thing and might make sense in cases where the actions never appear in the same context. In case there are no actions for a given accelerator, an empty array is returned. `NULL` is never returned. It is a programmer error to pass an invalid accelerator string. If you are unsure, check it with [func@Gtk.accelerator_parse] first. actions for @accel a application an accelerator that can be parsed by [func@Gtk.accelerator_parse] Gets the “active” window for the application. The active window is the one that was most recently focused (within the application). This window may not have the focus at the moment if another application has it — this is just the most recently-focused window within this application. the active window an application Gets a menu from automatically loaded resources. See [the section on Automatic resources](class.Application.html#automatic-resources) for more information. Gets the menu with the given ID from the automatically loaded resources an application the ID of the menu to look up Returns the menu model for the menu bar of the application. the menubar for windows of the application an application Returns the window with the given ID. The ID of a `GtkApplicationWindow` can be retrieved with [method@Gtk.ApplicationWindow.get_id]. the window for the given ID an application` an identifier number Gets a list of the window associated with the application. The list is sorted by most recently focused window, such that the first element is the currently focused window. (Useful for choosing a parent for a transient window.) The list that is returned should not be modified in any way. It will only remain valid until the next focus change or window creation or deletion. the list of windows an application Informs the session manager that certain types of actions should be inhibited. This is not guaranteed to work on all platforms and for all types of actions. Applications should invoke this method when they begin an operation that should not be interrupted, such as creating a CD or DVD. The types of actions that may be blocked are specified by the @flags parameter. When the application completes the operation it should call [method@Gtk.Application.uninhibit] to remove the inhibitor. Note that an application can have multiple inhibitors, and all of them must be individually removed. Inhibitors are also cleared when the application exits. Applications should not expect that they will always be able to block the action. In most cases, users will be given the option to force the action to take place. The @reason message should be short and to the point. If a window is given, the session manager may point the user to this window to find out more about why the action is inhibited. The cookie that is returned by this function should be used as an argument to [method@Gtk.Application.uninhibit] in order to remove the request. A non-zero cookie that is used to uniquely identify this, or 0 if the platform does not support inhibiting or the request failed for some reason the application a window what types of actions should be inhibited a short, human-readable string that explains why these operations are inhibited Lists the detailed action names which have associated accelerators. See [method@Gtk.Application.set_accels_for_action]. the detailed action names an application Remove a window from the application. If the window belongs to the application then this call is equivalent to setting the [property@Gtk.Window:application] property of the window to `NULL`. The application may stop running as a result of a call to this function, if the window was the last window of the application. an application a window Sets zero or more keyboard accelerators that will trigger the given action. The first item in @accels will be the primary accelerator, which may be displayed in the UI. To remove all accelerators for an action, use an empty, zero-terminated array for @accels. For the @detailed_action_name, see [func@Gio.Action.parse_detailed_name] and [Gio.Action.print_detailed_name]. an application a detailed action name, specifying an action and target to associate accelerators with a list of accelerators in the format understood by [func@Gtk.accelerator_parse] Sets or unsets the menubar for windows of the application. This is a menubar in the traditional sense. This can only be done in the primary instance of the application, after it has been registered. [vfunc@GIO.Application.startup] is a good place to call this. Depending on the desktop environment, this may appear at the top of each window, or at the top of the screen. In some environments, if both the application menu and the menubar are set, the application menu will be presented as if it were the first item of the menubar. Other environments treat the two as completely separate — for example, the application menu may be rendered by the desktop shell while the menubar (if set) remains in each individual window. Use the base `GActionMap` interface to add actions, to respond to the user selecting these menu items. an application a menu model Removes an inhibitor that has been previously established. See [method@Gtk.Application.inhibit]. Inhibitors are also cleared when the application exits. the application a cookie that was returned by [method@Gtk.Application.inhibit] The currently focused window of the application. The menu model to be used for the application's menu bar. Set this property to true to register with the session manager. This will make GTK track the session state (such as the [property@Gtk.Application:screensaver-active] property). This property is ignored. GTK always registers with the session manager This property is true if GTK believes that the screensaver is currently active. Tracking the screensaver state is currently only supported on Linux. Emitted when the session manager is about to end the session. Applications can connect to this signal and call [method@Gtk.Application.inhibit] with [flags@Gtk.ApplicationInhibitFlags.logout] to delay the end of the session until state has been saved. Emitted when a window is added to an application. See [method@Gtk.Application.add_window]. the newly-added window Emitted when a window is removed from an application. This can happen as a side-effect of the window being destroyed or explicitly through [method@Gtk.Application.remove_window]. the window that is being removed The parent class. Signal emitted when a `GtkWindow` is added to application through gtk_application_add_window(). Signal emitted when a `GtkWindow` is removed from application, either as a side-effect of being destroyed or explicitly through gtk_application_remove_window(). Types of user actions that may be blocked by `GtkApplication`. See [method@Gtk.Application.inhibit]. Inhibit ending the user session by logging out or by shutting down the computer Inhibit user switching Inhibit suspending the session or computer Inhibit the session being marked as idle (and possibly locked) A `GtkWindow` subclass that integrates with `GtkApplication`. Notably, `GtkApplicationWindow` can handle an application menubar. This class implements the [iface@Gio.ActionGroup] and [iface@Gio.ActionMap] interfaces, to let you add window-specific actions that will be exported by the associated [class@Gtk.Application], together with its application-wide actions. Window-specific actions are prefixed with the “win.” prefix and application-wide actions are prefixed with the “app.” prefix. Actions must be addressed with the prefixed name when referring to them from a menu model. Note that widgets that are placed inside a `GtkApplicationWindow` can also activate these actions, if they implement the [iface@Gtk.Actionable] interface. The settings [property@Gtk.Settings:gtk-shell-shows-app-menu] and [property@Gtk.Settings:gtk-shell-shows-menubar] tell GTK whether the desktop environment is showing the application menu and menubar models outside the application as part of the desktop shell. For instance, on OS X, both menus will be displayed remotely; on Windows neither will be. If the desktop environment does not display the menubar, it can be shown in the `GtkApplicationWindow` by setting the [property@Gtk.ApplicationWindow:show-menubar] property to true. If the desktop environment does not display the application menu, then it will automatically be included in the menubar or in the window’s client-side decorations. See [class@Gtk.PopoverMenu] for information about the XML language used by `GtkBuilder` for menu models. See also: [method@Gtk.Application.set_menubar]. ## A GtkApplicationWindow with a menubar The code sample below shows how to set up a `GtkApplicationWindow` with a menu bar defined on the [class@Gtk.Application]: ```c GtkApplication *app = gtk_application_new ("org.gtk.test", 0); GtkBuilder *builder = gtk_builder_new_from_string ( "<interface>" " <menu id='menubar'>" " <submenu>" " <attribute name='label' translatable='yes'>_Edit</attribute>" " <item>" " <attribute name='label' translatable='yes'>_Copy</attribute>" " <attribute name='action'>win.copy</attribute>" " </item>" " <item>" " <attribute name='label' translatable='yes'>_Paste</attribute>" " <attribute name='action'>win.paste</attribute>" " </item>" " </submenu>" " </menu>" "</interface>", -1); GMenuModel *menubar = G_MENU_MODEL (gtk_builder_get_object (builder, "menubar")); gtk_application_set_menubar (GTK_APPLICATION (app), menubar); g_object_unref (builder); // ... GtkWidget *window = gtk_application_window_new (app); ``` Creates a new `GtkApplicationWindow`. a newly created `GtkApplicationWindow` an application Gets the `GtkShortcutsWindow` that is associated with @window. See [method@Gtk.ApplicationWindow.set_help_overlay]. `GtkShortcutsWindow` will be removed in GTK 5 the help overlay associated with the window an application window Returns the unique ID of the window. If the window has not yet been added to a `GtkApplication`, returns `0`. the unique ID for the window, or `0` if the window has not yet been added to an application an application window Returns whether the window will display a menubar for the app menu and menubar as needed. True if the window will display a menubar when needed an application window Associates a shortcuts window with the application window. Additionally, sets up an action with the name `win.show-help-overlay` to present it. The window takes responsibility for destroying the help overlay. `GtkShortcutsWindow` will be removed in GTK 5 an application window a shortcuts window Sets whether the window will display a menubar for the app menu and menubar as needed. an application window whether to show a menubar when needed If this property is true, the window will display a menubar unless it is shown by the desktop shell. See [method@Gtk.Application.set_menubar]. If false, the window will not display a menubar, regardless of whether the desktop shell is showing it or not. The parent class. Indicates the direction in which an arrow should point. Represents an upward pointing arrow. Represents a downward pointing arrow. Represents a left pointing arrow. Represents a right pointing arrow. No arrow. Preserves the aspect ratio of its child. The frame can respect the aspect ratio of the child widget, or use its own aspect ratio. # CSS nodes `GtkAspectFrame` uses a CSS node with name `aspectframe`. # Accessibility Until GTK 4.10, `GtkAspectFrame` used the [enum@Gtk.AccessibleRole.group] role. Starting from GTK 4.12, `GtkAspectFrame` uses the [enum@Gtk.AccessibleRole.generic] role. Create a new `GtkAspectFrame`. the new `GtkAspectFrame`. Horizontal alignment of the child within the parent. Ranges from 0.0 (left aligned) to 1.0 (right aligned) Vertical alignment of the child within the parent. Ranges from 0.0 (top aligned) to 1.0 (bottom aligned) The desired aspect ratio. If %TRUE, @ratio is ignored, and the aspect ratio is taken from the requistion of the child. Gets the child widget of @self. the child widget of @self a `GtkAspectFrame` Returns whether the child's size request should override the set aspect ratio of the `GtkAspectFrame`. whether to obey the child's size request a `GtkAspectFrame` Returns the desired aspect ratio of the child. the desired aspect ratio a `GtkAspectFrame` Returns the horizontal alignment of the child within the allocation of the `GtkAspectFrame`. the horizontal alignment a `GtkAspectFrame` Returns the vertical alignment of the child within the allocation of the `GtkAspectFrame`. the vertical alignment a `GtkAspectFrame` Sets the child widget of @self. a `GtkAspectFrame` the child widget Sets whether the aspect ratio of the child's size request should override the set aspect ratio of the `GtkAspectFrame`. a `GtkAspectFrame` If %TRUE, @ratio is ignored, and the aspect ratio is taken from the requisition of the child. Sets the desired aspect ratio of the child. a `GtkAspectFrame` aspect ratio of the child Sets the horizontal alignment of the child within the allocation of the `GtkAspectFrame`. a `GtkAspectFrame` horizontal alignment, from 0.0 (left aligned) to 1.0 (right aligned) Sets the vertical alignment of the child within the allocation of the `GtkAspectFrame`. a `GtkAspectFrame` horizontal alignment, from 0.0 (top aligned) to 1.0 (bottom aligned) The child widget. Whether the `GtkAspectFrame` should use the aspect ratio of its child. The aspect ratio to be used by the `GtkAspectFrame`. This property is only used if [property@Gtk.AspectFrame:obey-child] is set to %FALSE. The horizontal alignment of the child. The vertical alignment of the child. `GtkAssistant` is used to represent a complex as a series of steps. <picture> <source srcset="assistant-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkAssistant" src="assistant.png"> </picture> Each step consists of one or more pages. `GtkAssistant` guides the user through the pages, and controls the page flow to collect the data needed for the operation. `GtkAssistant` handles which buttons to show and to make sensitive based on page sequence knowledge and the [enum@Gtk.AssistantPageType] of each page in addition to state information like the *completed* and *committed* page statuses. If you have a case that doesn’t quite fit in `GtkAssistant`s way of handling buttons, you can use the %GTK_ASSISTANT_PAGE_CUSTOM page type and handle buttons yourself. `GtkAssistant` maintains a `GtkAssistantPage` object for each added child, which holds additional per-child properties. You obtain the `GtkAssistantPage` for a child with [method@Gtk.Assistant.get_page]. # GtkAssistant as GtkBuildable The `GtkAssistant` implementation of the `GtkBuildable` interface exposes the @action_area as internal children with the name “action_area”. To add pages to an assistant in `GtkBuilder`, simply add it as a child to the `GtkAssistant` object. If you need to set per-object properties, create a `GtkAssistantPage` object explicitly, and set the child widget as a property on it. # CSS nodes `GtkAssistant` has a single CSS node with the name window and style class .assistant. This widget will be removed in GTK 5 Creates a new `GtkAssistant`. This widget will be removed in GTK 5 a newly created `GtkAssistant` Adds a widget to the action area of a `GtkAssistant`. This widget will be removed in GTK 5 a `GtkAssistant` a `GtkWidget` Appends a page to the @assistant. This widget will be removed in GTK 5 the index (starting at 0) of the inserted page a `GtkAssistant` a `GtkWidget` Erases the visited page history. GTK will then hide the back button on the current page, and removes the cancel button from subsequent pages. Use this when the information provided up to the current page is hereafter deemed permanent and cannot be modified or undone. For example, showing a progress page to track a long-running, unreversible operation after the user has clicked apply on a confirmation page. This widget will be removed in GTK 5 a `GtkAssistant` Returns the page number of the current page. This widget will be removed in GTK 5 The index (starting from 0) of the current page in the @assistant, or -1 if the @assistant has no pages, or no current page a `GtkAssistant` Returns the number of pages in the @assistant This widget will be removed in GTK 5 the number of pages in the @assistant a `GtkAssistant` Returns the child widget contained in page number @page_num. This widget will be removed in GTK 5 the child widget, or %NULL if @page_num is out of bounds a `GtkAssistant` the index of a page in the @assistant, or -1 to get the last page Returns the `GtkAssistantPage` object for @child. This widget will be removed in GTK 5 the `GtkAssistantPage` for @child a `GtkAssistant` a child of @assistant Gets whether @page is complete. This widget will be removed in GTK 5 %TRUE if @page is complete. a `GtkAssistant` a page of @assistant Gets the title for @page. This widget will be removed in GTK 5 the title for @page a `GtkAssistant` a page of @assistant Gets the page type of @page. This widget will be removed in GTK 5 the page type of @page a `GtkAssistant` a page of @assistant Gets a list model of the assistant pages. This widget will be removed in GTK 5 A list model of the pages. a `GtkAssistant` Inserts a page in the @assistant at a given position. This widget will be removed in GTK 5 the index (starting from 0) of the inserted page a `GtkAssistant` a `GtkWidget` the index (starting at 0) at which to insert the page, or -1 to append the page to the @assistant Navigate to the next page. It is a programming error to call this function when there is no next page. This function is for use when creating pages of the %GTK_ASSISTANT_PAGE_CUSTOM type. This widget will be removed in GTK 5 a `GtkAssistant` Prepends a page to the @assistant. This widget will be removed in GTK 5 the index (starting at 0) of the inserted page a `GtkAssistant` a `GtkWidget` Navigate to the previous visited page. It is a programming error to call this function when no previous page is available. This function is for use when creating pages of the %GTK_ASSISTANT_PAGE_CUSTOM type. This widget will be removed in GTK 5 a `GtkAssistant` Removes a widget from the action area of a `GtkAssistant`. This widget will be removed in GTK 5 a `GtkAssistant` a `GtkWidget` Removes the @page_num’s page from @assistant. This widget will be removed in GTK 5 a `GtkAssistant` the index of a page in the @assistant, or -1 to remove the last page Switches the page to @page_num. Note that this will only be necessary in custom buttons, as the @assistant flow can be set with gtk_assistant_set_forward_page_func(). This widget will be removed in GTK 5 a `GtkAssistant` index of the page to switch to, starting from 0. If negative, the last page will be used. If greater than the number of pages in the @assistant, nothing will be done. Sets the page forwarding function to be @page_func. This function will be used to determine what will be the next page when the user presses the forward button. Setting @page_func to %NULL will make the assistant to use the default forward function, which just goes to the next visible page. This widget will be removed in GTK 5 a `GtkAssistant` the `GtkAssistantPageFunc`, or %NULL to use the default one user data for @page_func destroy notifier for @data Sets whether @page contents are complete. This will make @assistant update the buttons state to be able to continue the task. This widget will be removed in GTK 5 a `GtkAssistant` a page of @assistant the completeness status of the page Sets a title for @page. The title is displayed in the header area of the assistant when @page is the current page. This widget will be removed in GTK 5 a `GtkAssistant` a page of @assistant the new title for @page Sets the page type for @page. The page type determines the page behavior in the @assistant. This widget will be removed in GTK 5 a `GtkAssistant` a page of @assistant the new type for @page Forces @assistant to recompute the buttons state. GTK automatically takes care of this in most situations, e.g. when the user goes to a different page, or when the visibility or completeness of a page changes. One situation where it can be necessary to call this function is when changing a value on the current page affects the future page flow of the assistant. This widget will be removed in GTK 5 a `GtkAssistant` `GListModel` containing the pages. %TRUE if the assistant uses a `GtkHeaderBar` for action buttons instead of the action-area. For technical reasons, this property is declared as an integer property, but you should only set it to %TRUE or %FALSE. This widget will be removed in GTK 5 Emitted when the apply button is clicked. The default behavior of the `GtkAssistant` is to switch to the page after the current page, unless the current page is the last one. A handler for the ::apply signal should carry out the actions for which the wizard has collected data. If the action takes a long time to complete, you might consider putting a page of type %GTK_ASSISTANT_PAGE_PROGRESS after the confirmation page and handle this operation within the [signal@Gtk.Assistant::prepare] signal of the progress page. This widget will be removed in GTK 5 Emitted when then the cancel button is clicked. This widget will be removed in GTK 5 Emitted either when the close button of a summary page is clicked, or when the apply button in the last page in the flow (of type %GTK_ASSISTANT_PAGE_CONFIRM) is clicked. This widget will be removed in GTK 5 The action signal for the Escape binding. This widget will be removed in GTK 5 Emitted when a new page is set as the assistant's current page, before making the new page visible. A handler for this signal can do any preparations which are necessary before showing @page. This widget will be removed in GTK 5 the current page `GtkAssistantPage` is an auxiliary object used by `GtkAssistant`. This object will be removed in GTK 5 Returns the child to which @page belongs. This widget will be removed in GTK 5 the child to which @page belongs a `GtkAssistantPage` The child widget. This object will be removed in GTK 5 Whether all required fields are filled in. GTK uses this information to control the sensitivity of the navigation buttons. This object will be removed in GTK 5 The type of the assistant page. This object will be removed in GTK 5 The title of the page. This object will be removed in GTK 5 Type of callback used to calculate the next page in a `GtkAssistant`. It’s called both for computing the next page when the user presses the “forward” button and for handling the behavior of the “last” button. See [method@Gtk.Assistant.set_forward_page_func]. The next page number The page number used to calculate the next page. user data. Determines the role of a page inside a `GtkAssistant`. The role is used to handle buttons sensitivity and visibility. Note that an assistant needs to end its page flow with a page of type %GTK_ASSISTANT_PAGE_CONFIRM, %GTK_ASSISTANT_PAGE_SUMMARY or %GTK_ASSISTANT_PAGE_PROGRESS to be correct. The Cancel button will only be shown if the page isn’t “committed”. See gtk_assistant_commit() for details. `GtkAssistant` will be removed in GTK 5 The page has regular contents. Both the Back and forward buttons will be shown. The page contains an introduction to the assistant task. Only the Forward button will be shown if there is a next page. The page lets the user confirm or deny the changes. The Back and Apply buttons will be shown. The page informs the user of the changes done. Only the Close button will be shown. Used for tasks that take a long time to complete, blocks the assistant until the page is marked as complete. Only the back button will be shown. Used for when other page types are not appropriate. No buttons will be shown, and the application must add its own buttons through gtk_assistant_add_action_widget(). Like [func@get_binary_age], but from the headers used at application compile time, rather than from the library linked against at application run time. This macro should be used to emit a warning about and unexpected @type value in a `GtkBuildable` add_child implementation. the `GtkBuildable` on which the warning occurred the unexpected type value Baseline position in a row of widgets. Whenever a container has some form of natural row it may align children in that row along a common typographical baseline. If the amount of vertical space in the row is taller than the total requested height of the baseline-aligned children then it can use a `GtkBaselinePosition` to select where to put the baseline inside the extra available space. Align the baseline at the top Center the baseline Align the baseline at the bottom A layout manager for widgets with a single child. `GtkBinLayout` will stack each child of a widget on top of each other, using the [property@Gtk.Widget:hexpand], [property@Gtk.Widget:vexpand], [property@Gtk.Widget:halign], and [property@Gtk.Widget:valign] properties of each child to determine where they should be positioned. Creates a new `GtkBinLayout` instance. the newly created `GtkBinLayout` A set of unsigned integers. Another name for this data structure is “bitmap”. The current implementation is based on [roaring bitmaps](https://roaringbitmap.org/). A bitset allows adding a set of integers and provides support for set operations like unions, intersections and checks for equality or if a value is contained in the set. `GtkBitset` also contains various functions to query metadata about the bitset, such as the minimum or maximum values or its size. The fastest way to iterate values in a bitset is [struct@Gtk.BitsetIter]. The main use case for `GtkBitset` is implementing complex selections for [iface@Gtk.SelectionModel]. Creates a new empty bitset. A new empty bitset Creates a bitset with the given range set. A new bitset first value to add number of consecutive values to add Adds @value to @self if it wasn't part of it before. %TRUE if @value was not part of @self and @self was changed a `GtkBitset` value to add Adds all values from @start (inclusive) to @start + @n_items (exclusive) in @self. a `GtkBitset` first value to add number of consecutive values to add Adds the closed range [@first, @last], so @first, @last and all values in between. @first must be smaller than @last. a `GtkBitset` first value to add last value to add Interprets the values as a 2-dimensional boolean grid with the given @stride and inside that grid, adds a rectangle with the given @width and @height. a `GtkBitset` first value to add width of the rectangle height of the rectangle row stride of the grid Checks if the given @value has been added to @self %TRUE if @self contains @value a `GtkBitset` the value to check Creates a copy of @self. A new bitset that contains the same values as @self a `GtkBitset` Sets @self to be the symmetric difference of @self and @other. The symmetric difference is set @self to contain all values that were either contained in @self or in @other, but not in both. This operation is also called an XOR. It is allowed for @self and @other to be the same bitset. The bitset will be emptied in that case. a `GtkBitset` the `GtkBitset` to compute the difference from Returns %TRUE if @self and @other contain the same values. %TRUE if @self and @other contain the same values a `GtkBitset` another `GtkBitset` Returns the largest value in @self. If @self is empty, 0 is returned. The largest value in @self a `GtkBitset` Returns the smallest value in @self. If @self is empty, `G_MAXUINT` is returned. The smallest value in @self a `GtkBitset` Returns the value of the @nth item in self. If @nth is >= the size of @self, 0 is returned. the value of the @nth item in @self a `GtkBitset` index of the item to get Gets the number of values that were added to the set. For example, if the set is empty, 0 is returned. Note that this function returns a `guint64`, because when all values are set, the return value is `G_MAXUINT + 1`. Unless you are sure this cannot happen (it can't with `GListModel`), be sure to use a 64bit type. The number of values in the set. a `GtkBitset` Gets the number of values that are part of the set from @first to @last (inclusive). Note that this function returns a `guint64`, because when all values are set, the return value is `G_MAXUINT + 1`. Unless you are sure this cannot happen (it can't with `GListModel`), be sure to use a 64bit type. The number of values in the set from @first to @last. a `GtkBitset` the first element to include the last element to include Sets @self to be the intersection of @self and @other. In other words, remove all values from @self that are not part of @other. It is allowed for @self and @other to be the same bitset. Nothing will happen in that case. a `GtkBitset` the `GtkBitset` to intersect with Check if no value is contained in bitset. %TRUE if @self is empty a `GtkBitset` Acquires a reference on the given `GtkBitset`. the `GtkBitset` with an additional reference a `GtkBitset` Removes @value from @self if it was part of it before. %TRUE if @value was part of @self and @self was changed a `GtkBitset` value to remove Removes all values from the bitset so that it is empty again. a `GtkBitset` Removes all values from @start (inclusive) to @start + @n_items (exclusive) in @self. a `GtkBitset` first value to remove number of consecutive values to remove Removes the closed range [@first, @last], so @first, @last and all values in between. @first must be smaller than @last. a `GtkBitset` first value to remove last value to remove Interprets the values as a 2-dimensional boolean grid with the given @stride and inside that grid, removes a rectangle with the given @width and @height. a `GtkBitset` first value to remove width of the rectangle height of the rectangle row stride of the grid Shifts all values in @self to the left by @amount. Values smaller than @amount are discarded. a `GtkBitset` amount to shift all values to the left Shifts all values in @self to the right by @amount. Values that end up too large to be held in a #guint are discarded. a `GtkBitset` amount to shift all values to the right This is a support function for `GListModel` handling, by mirroring the `GlistModel::items-changed` signal. First, it "cuts" the values from @position to @removed from the bitset. That is, it removes all those values and shifts all larger values to the left by @removed places. Then, it "pastes" new room into the bitset by shifting all values larger than @position by @added spaces to the right. This frees up space that can then be filled. a `GtkBitset` position at which to slice number of values to remove number of values to add Sets @self to be the subtraction of @other from @self. In other words, remove all values from @self that are part of @other. It is allowed for @self and @other to be the same bitset. The bitset will be emptied in that case. a `GtkBitset` the `GtkBitset` to subtract Sets @self to be the union of @self and @other. That is, add all values from @other into @self that weren't part of it. It is allowed for @self and @other to be the same bitset. Nothing will happen in that case. a `GtkBitset` the `GtkBitset` to union with Releases a reference on the given `GtkBitset`. If the reference was the last, the resources associated to the @self are freed. a `GtkBitset` Iterates over the elements of a [struct@Gtk.Bitset]. `GtkBitSetIter is an opaque, stack-allocated struct. Before a `GtkBitsetIter` can be used, it needs to be initialized with [func@Gtk.BitsetIter.init_first], [func@Gtk.BitsetIter.init_last] or [func@Gtk.BitsetIter.init_at]. Gets the current value that @iter points to. If @iter is not valid and [method@Gtk.BitsetIter.is_valid] returns %FALSE, this function returns 0. The current value pointer to by @iter a `GtkBitsetIter` Checks if @iter points to a valid value. %TRUE if @iter points to a valid value a `GtkBitsetIter` Moves @iter to the next value in the set. If it was already pointing to the last value in the set, %FALSE is returned and @iter is invalidated. %TRUE if a next value existed a pointer to a valid `GtkBitsetIter` Set to the next value Moves @iter to the previous value in the set. If it was already pointing to the first value in the set, %FALSE is returned and @iter is invalidated. %TRUE if a previous value existed a pointer to a valid `GtkBitsetIter` Set to the previous value Initializes @iter to point to @target. If @target is not found, finds the next value after it. If no value >= @target exists in @set, this function returns %FALSE. %TRUE if a value was found. a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` target value to start iterating at Set to the found value in @set Initializes an iterator for @set and points it to the first value in @set. If @set is empty, %FALSE is returned and @value is set to %G_MAXUINT. %TRUE if @set isn't empty. a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` Set to the first value in @set Initializes an iterator for @set and points it to the last value in @set. If @set is empty, %FALSE is returned. %TRUE if @set isn't empty. a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` Set to the last value in @set A list model that wraps `GBookmarkFile`. It presents a `GListModel` and fills it asynchronously with the `GFileInfo`s returned from that function. The `GFileInfo`s in the list have some attributes in the recent namespace added: `recent::private` (boolean) and `recent:applications` (stringv). Creates a new `GtkBookmarkList` with the given @attributes. a new `GtkBookmarkList` The bookmark file to load The attributes to query Gets the attributes queried on the children. The queried attributes a `GtkBookmarkList` Returns the filename of the bookmark file that this list is loading. the filename of the .xbel file a `GtkBookmarkList` Gets the IO priority to use while loading file. The IO priority. a `GtkBookmarkList` Returns %TRUE if the files are currently being loaded. Files will be added to @self from time to time while loading is going on. The order in which are added is undefined and may change in between runs. %TRUE if @self is loading a `GtkBookmarkList` Sets the @attributes to be enumerated and starts the enumeration. If @attributes is %NULL, no attributes will be queried, but a list of `GFileInfo`s will still be created. a `GtkBookmarkList` the attributes to enumerate Sets the IO priority to use while loading files. The default IO priority is %G_PRIORITY_DEFAULT. a `GtkBookmarkList` IO priority to use The attributes to query. The bookmark file to load. Priority used when loading. The type of items. See [method@Gio.ListModel.get_item_type]. %TRUE if files are being loaded. The number of items. See [method@Gio.ListModel.get_n_items]. Evaluates a boolean expression to determine whether to include items. Creates a new bool filter. a new `GtkBoolFilter` the expression to evaluate Gets the expression that the filter evaluates for each item. the expression a bool filter Returns whether the filter inverts the expression. true if the filter inverts a bool filter Sets the expression that the filter uses to check if items should be filtered. The expression must have a value type of `G_TYPE_BOOLEAN`. a bool filter the expression Sets whether the filter should invert the expression. a bool filter true to invert The boolean expression to evaluate on each item. If the expression result should be inverted. Specifies a border around a rectangular area. Each side can have a different width. The width of the left border The width of the right border The width of the top border The width of the bottom border Allocates a new `GtkBorder` struct and initializes its elements to zero. a newly allocated `GtkBorder` struct. Free with [method@Gtk.Border.free] Copies a `GtkBorder`. a copy of @border_. a `GtkBorder` struct Frees a `GtkBorder`. a `GtkBorder` struct Describes how the border of a UI element should be rendered. No visible border Same as %GTK_BORDER_STYLE_NONE A single line segment Looks as if the content is sunken into the canvas Looks as if the content is coming out of the canvas A series of round dots A series of square-ended dashes Two parallel lines with some space between them Looks as if it were carved in the canvas Looks as if it were coming out of the canvas Arranges child widgets into a single row or column. <picture> <source srcset="box-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkBox" src="box.png"> </picture> Whether it is a row or column depends on the value of its [property@Gtk.Orientable:orientation] property. Within the other dimension, all children are allocated the same size. The [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties can be used on the children to influence their allocation. Use repeated calls to [method@Gtk.Box.append] to pack widgets into a `GtkBox` from start to end. Use [method@Gtk.Box.remove] to remove widgets from the `GtkBox`. [method@Gtk.Box.insert_child_after] can be used to add a child at a particular position. Use [method@Gtk.Box.set_homogeneous] to specify whether or not all children of the `GtkBox` are forced to get the same amount of space. Use [method@Gtk.Box.set_spacing] to determine how much space will be minimally placed between all children in the `GtkBox`. Note that spacing is added *between* the children. Use [method@Gtk.Box.reorder_child_after] to move a child to a different place in the box. # CSS nodes `GtkBox` uses a single CSS node with name box. # Accessibility Until GTK 4.10, `GtkBox` used the [enum@Gtk.AccessibleRole.group] role. Starting from GTK 4.12, `GtkBox` uses the [enum@Gtk.AccessibleRole.generic] role. Creates a new box. a new `GtkBox`. the box’s orientation the number of pixels to place between children Adds a child at the end. a box the widget to append Gets the value set by [method@Gtk.Box.set_baseline_child]. the baseline child a box Gets the value set by [method@Gtk.Box.set_baseline_position]. the baseline position a box Returns whether the box is homogeneous. In a homogeneous box all children are the same size. true if the box is homogeneous a box Gets the value set by [method@Gtk.Box.set_spacing]. spacing between children a box Inserts a child at a specific position. The child is added after @sibling in the list of @box children. If @sibling is `NULL`, the @child is placed at the beginning. a box the widget to insert the sibling after which to insert @child Adds a child at the beginning. a box the widget to prepend Removes a child widget from the box. The child must have been added before with [method@Gtk.Box.append], [method@Gtk.Box.prepend], or [method@Gtk.Box.insert_child_after]. a box the child to remove Moves a child to a different position. The child is moved to the position after @sibling in the list of @box children. If @sibling is `NULL`, the child is placed at the beginning. a box the widget to move, must be a child of @box the sibling to move @child after Sets the baseline child of a box. This affects only vertical boxes. a box a child position, or -1 Sets the baseline position of a box. This affects only horizontal boxes with at least one baseline aligned child. If there is more vertical space available than requested, and the baseline is not allocated by the parent then @position is used to allocate the baseline with respect to the extra space available. a box the baseline position Sets whether or not all children are given equal space in the box. a box true to create equal allotments, false for variable allotments Sets the number of pixels to place between children. a box the number of pixels to put between children The position of the child that determines the baseline. This is only relevant if the box is in vertical orientation. How to position baseline-aligned widgets if extra space is available. Whether the children should all be the same size. The amount of space between children. The parent class. Arranges children in a single row or column. Whether it is a row or column depends on the value of its [property@Gtk.Orientable:orientation] property. Within the other dimension all children all allocated the same size. The `GtkBoxLayout` will respect the [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties of each child widget. If you want all children to be assigned the same size, you can use the [property@Gtk.BoxLayout:homogeneous] property. If you want to specify the amount of space placed between each child, you can use the [property@Gtk.BoxLayout:spacing] property. Creates a new `GtkBoxLayout`. a new box layout the orientation for the new layout Gets the value set by gtk_box_layout_set_baseline_child(). the index of the child that determines the baseline in vertical layout, or -1 a `GtkBoxLayout` Gets the value set by gtk_box_layout_set_baseline_position(). the baseline position a `GtkBoxLayout` Returns whether the layout is set to be homogeneous. %TRUE if the layout is homogeneous a `GtkBoxLayout` Returns the space that @box_layout puts between children. the spacing of the layout a `GtkBoxLayout` Sets the index of the child that determines the baseline in vertical layout. a `GtkBoxLayout` the child position, or -1 Sets the baseline position of a box layout. The baseline position affects only horizontal boxes with at least one baseline aligned child. If there is more vertical space available than requested, and the baseline is not allocated by the parent then the given @position is used to allocate the baseline within the extra space available. a `GtkBoxLayout` a `GtkBaselinePosition` Sets whether the box layout will allocate the same size to all children. a `GtkBoxLayout` %TRUE to set the box layout as homogeneous Sets how much spacing to put between children. a `GtkBoxLayout` the spacing to apply between children The child that determines the baseline of the box in vertical layout. If the child does baseline positioning, then its baseline is lined up with the baseline of the box. If it doesn't, then the bottom edge of the child is used. The position of the allocated baseline within the extra space allocated to each child. This property is only relevant for horizontal layouts containing at least one child with a baseline alignment. Whether the box layout should distribute the available space equally among the children. The space to put between the children. Allows objects to extend and customize deserialization from ui files. The `GtkBuildable` interface includes methods for setting names and properties of objects, parsing custom tags and constructing child objects. It is implemented by all widgets and many of the non-widget objects that are provided by GTK. The main user of this interface is [class@Gtk.Builder]. There should be very little need for applications to call any of these functions directly. An object only needs to implement this interface if it needs to extend the `GtkBuilder` XML format or run any extra routines at deserialization time. Adds a child to @buildable. @type is an optional string describing how the child should be added. a `GtkBuildable` a `GtkBuilder` child to add kind of child or %NULL Constructs a child of a buildable that has been specified as “constructor” in the UI definition. This can be used to reference a widget created in a `<ui>` tag which is outside of the normal GtkBuilder UI definition hierarchy. A reference to the constructed object is returned and becomes owned by the caller. Similar to gtk_buildable_parser_finished() but is called once for each custom tag handled by the @buildable. a `GtkBuildable` a `GtkBuilder` child object or %NULL for non-child tags the name of the tag user data created in custom_tag_start Called at the end of each custom element handled by the buildable. A `GtkBuildable` `GtkBuilder` used to construct this object child object or %NULL for non-child tags name of tag user data that will be passed in to parser functions Called for each unknown element under `<child>`. %TRUE if an object has a custom implementation, %FALSE if it doesn't. a `GtkBuildable` a `GtkBuilder` used to construct this object child object or %NULL for non-child tags name of tag a `GtkBuildableParser` to fill in return location for user data that will be passed in to parser functions The getter corresponding to @set_id. Implement this if you implement @set_id. Retrieves the internal child called @childname of the @buildable object. the internal child of the buildable object a `GtkBuildable` a `GtkBuilder` name of child Called when a builder finishes the parsing of a UI definition. It is normally not necessary to implement this, unless you need to perform special cleanup actions. `GtkWindow` sets the `GtkWidget:visible` property here. Sets a property of a buildable object. It is normally not necessary to implement this, g_object_set_property() is used by default. `GtkWindow` implements this to delay showing itself (i.e. setting the [property@Gtk.Widget:visible] property) until the whole interface is created. Stores the id attribute given in the `GtkBuilder` UI definition. `GtkWidget` stores the name as object data. Implement this method if your object has some notion of “ID” and it makes sense to map the XML id attribute to it. Gets the ID of the @buildable object. `GtkBuilder` sets the name based on the ID attribute of the `<object>` tag used to construct the @buildable. the ID of the buildable object a `GtkBuildable` Contains methods to let `GtkBuilder` construct an object from a `GtkBuilder` UI definition. the parent class Stores the id attribute given in the `GtkBuilder` UI definition. `GtkWidget` stores the name as object data. Implement this method if your object has some notion of “ID” and it makes sense to map the XML id attribute to it. The getter corresponding to @set_id. Implement this if you implement @set_id. Adds a child. The @type parameter can be used to differentiate the kind of child. `GtkWidget` implements this to add event controllers to the widget, `GtkNotebook` uses the @type to distinguish between page labels (of type "page-label") and normal children. a `GtkBuildable` a `GtkBuilder` child to add kind of child or %NULL Sets a property of a buildable object. It is normally not necessary to implement this, g_object_set_property() is used by default. `GtkWindow` implements this to delay showing itself (i.e. setting the [property@Gtk.Widget:visible] property) until the whole interface is created. Constructs a child of a buildable that has been specified as “constructor” in the UI definition. This can be used to reference a widget created in a `<ui>` tag which is outside of the normal GtkBuilder UI definition hierarchy. A reference to the constructed object is returned and becomes owned by the caller. Implement this if the buildable needs to parse content below `<child>`. To handle an element, the implementation must fill in the @parser and @user_data and return %TRUE. `GtkWidget` implements this to parse accessible attributes specified in `<accessibility>` elements. Note that @user_data must be freed in @custom_tag_end or @custom_finished. %TRUE if an object has a custom implementation, %FALSE if it doesn't. a `GtkBuildable` a `GtkBuilder` used to construct this object child object or %NULL for non-child tags name of tag a `GtkBuildableParser` to fill in return location for user data that will be passed in to parser functions Called for the end tag of each custom element that is handled by the buildable (see @custom_tag_start). A `GtkBuildable` `GtkBuilder` used to construct this object child object or %NULL for non-child tags name of tag user data that will be passed in to parser functions Called for each custom tag handled by the buildable when the builder finishes parsing (see @custom_tag_start) a `GtkBuildable` a `GtkBuilder` child object or %NULL for non-child tags the name of the tag user data created in custom_tag_start Called when a builder finishes the parsing of a UI definition. It is normally not necessary to implement this, unless you need to perform special cleanup actions. `GtkWindow` sets the `GtkWidget:visible` property here. Returns an internal child of a buildable. `GtkDialog` implements this to give access to its @vbox, making it possible to add children to the vbox in a UI definition. Implement this if the buildable has internal children that may need to be accessed from a UI definition. the internal child of the buildable object a `GtkBuildable` a `GtkBuilder` name of child Provides context for parsing GtkBuilder UI files. `GtkBuildableParseContext` is an opaque struct. Retrieves the name of the currently open element. If called from the start_element or end_element handlers this will give the element_name as passed to those functions. For the parent elements, see gtk_buildable_parse_context_get_element_stack(). the name of the currently open element a `GtkBuildablParseContext` Retrieves the element stack from the internal state of the parser. The returned `GPtrArray` is an array of strings where the last item is the currently open tag (as would be returned by gtk_buildable_parse_context_get_element()) and the previous item is its immediate parent. This function is intended to be used in the start_element and end_element handlers where gtk_buildable_parse_context_get_element() would merely return the name of the element that is being processed. the element stack, which must not be modified a `GtkBuildableParseContext` Retrieves the current line number and the number of the character on that line. Intended for use in error messages; there are no strict semantics for what constitutes the "current" line number other than "the best number we could come up with for error messages." a `GtkBuildableParseContext` return location for a line number return location for a char-on-line number Completes the process of a temporary sub-parser redirection. This function exists to collect the user_data allocated by a matching call to gtk_buildable_parse_context_push(). It must be called in the end_element handler corresponding to the start_element handler during which gtk_buildable_parse_context_push() was called. You must not call this function from the error callback -- the @user_data is provided directly to the callback in that case. This function is not intended to be directly called by users interested in invoking subparsers. Instead, it is intended to be used by the subparsers themselves to implement a higher-level interface. the user data passed to gtk_buildable_parse_context_push() a `GtkBuildableParseContext` Temporarily redirects markup data to a sub-parser. This function may only be called from the start_element handler of a `GtkBuildableParser`. It must be matched with a corresponding call to gtk_buildable_parse_context_pop() in the matching end_element handler (except in the case that the parser aborts due to an error). All tags, text and other data between the matching tags is redirected to the subparser given by @parser. @user_data is used as the user_data for that parser. @user_data is also passed to the error callback in the event that an error occurs. This includes errors that occur in subparsers of the subparser. The end tag matching the start tag for which this call was made is handled by the previous parser (which is given its own user_data) which is why gtk_buildable_parse_context_pop() is provided to allow "one last access" to the @user_data provided to this function. In the case of error, the @user_data provided here is passed directly to the error callback of the subparser and gtk_buildable_parse_context_pop() should not be called. In either case, if @user_data was allocated then it ought to be freed from both of these locations. This function is not intended to be directly called by users interested in invoking subparsers. Instead, it is intended to be used by the subparsers themselves to implement a higher-level interface. For an example of how to use this, see g_markup_parse_context_push() which has the same kind of API. a `GtkBuildableParseContext` a `GtkBuildableParser` user data to pass to `GtkBuildableParser` functions A sub-parser for `GtkBuildable` implementations. function called for open elements function called for close elements function called for character data function called on error Reads XML descriptions of a user interface and instantiates the described objects. To create a `GtkBuilder` from a user interface description, call [ctor@Gtk.Builder.new_from_file], [ctor@Gtk.Builder.new_from_resource] or [ctor@Gtk.Builder.new_from_string]. In the (unusual) case that you want to add user interface descriptions from multiple sources to the same `GtkBuilder` you can call [ctor@Gtk.Builder.new] to get an empty builder and populate it by (multiple) calls to [method@Gtk.Builder.add_from_file], [method@Gtk.Builder.add_from_resource] or [method@Gtk.Builder.add_from_string]. A `GtkBuilder` holds a reference to all objects that it has constructed and drops these references when it is finalized. This finalization can cause the destruction of non-widget objects or widgets which are not contained in a toplevel window. For toplevel windows constructed by a builder, it is the responsibility of the user to call [method@Gtk.Window.destroy] to get rid of them and all the widgets they contain. The functions [method@Gtk.Builder.get_object] and [method@Gtk.Builder.get_objects] can be used to access the widgets in the interface by the names assigned to them inside the UI description. Toplevel windows returned by these functions will stay around until the user explicitly destroys them with [method@Gtk.Window.destroy]. Other widgets will either be part of a larger hierarchy constructed by the builder (in which case you should not have to worry about their lifecycle), or without a parent, in which case they have to be added to some container to make use of them. Non-widget objects need to be reffed with g_object_ref() to keep them beyond the lifespan of the builder. ## GtkBuilder UI Definitions `GtkBuilder` parses textual descriptions of user interfaces which are specified in XML format. We refer to these descriptions as “GtkBuilder UI definitions” or just “UI definitions” if the context is clear. ### Structure of UI definitions UI definition files are always encoded in UTF-8. The toplevel element is `<interface>`. It optionally takes a “domain” attribute, which will make the builder look for translated strings using `dgettext()` in the domain specified. This can also be done by calling [method@Gtk.Builder.set_translation_domain] on the builder. For example: ```xml <?xml version="1.0" encoding="UTF-8"?> <interface domain="your-app"> ... </interface> ``` ### Requirements The target toolkit version(s) are described by `<requires>` elements, the “lib” attribute specifies the widget library in question (currently the only supported value is “gtk”) and the “version” attribute specifies the target version in the form “`<major>`.`<minor>`”. `GtkBuilder` will error out if the version requirements are not met. For example: ```xml <?xml version="1.0" encoding="UTF-8"?> <interface domain="your-app"> <requires lib="gtk" version="4.0" /> </interface> ``` ### Objects Objects are defined as children of the `<interface>` element. Objects are described by `<object>` elements, which can contain `<property>` elements to set properties, `<signal>` elements which connect signals to handlers, and `<child>` elements, which describe child objects. Typically, the specific kind of object represented by an `<object>` element is specified by the “class” attribute. If the type has not been loaded yet, GTK tries to find the `get_type()` function from the class name by applying heuristics. This works in most cases, but if necessary, it is possible to specify the name of the `get_type()` function explicitly with the "type-func" attribute. If your UI definition is referencing internal types, you should make sure to call `g_type_ensure()` for each object type before parsing the UI definition. Objects may be given a name with the “id” attribute, which allows the application to retrieve them from the builder with [method@Gtk.Builder.get_object]. An id is also necessary to use the object as property value in other parts of the UI definition. GTK reserves ids starting and ending with `___` (three consecutive underscores) for its own purposes. ### Properties Setting properties of objects is pretty straightforward with the `<property>` element: the “name” attribute specifies the name of the property, and the content of the element specifies the value: ```xml <object class="GtkButton"> <property name="label">Hello, world</property> </object> ``` If the “translatable” attribute is set to a true value, GTK uses `gettext()` (or `dgettext()` if the builder has a translation domain set) to find a translation for the value. This happens before the value is parsed, so it can be used for properties of any type, but it is probably most useful for string properties. It is also possible to specify a context to disambiguate short strings, and comments which may help the translators: ```xml <object class="GtkButton"> <property name="label" translatable="yes" context="button" comments="A classic">Hello, world</property> </object> ``` The xgettext tool that is part of gettext can extract these strings, but note that it only looks for translatable="yes". `GtkBuilder` can parse textual representations for the most common property types: - characters - strings - integers - floating-point numbers - booleans (strings like “TRUE”, “t”, “yes”, “y”, “1” are interpreted as true values, strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted as false values) - string lists (separated by newlines) - enumeration types (can be specified by their full C identifier their short name used when registering the enumeration type, or their integer value) - flag types (can be specified by their C identifier or short name, optionally combined with “|” for bitwise OR, or a single integer value e.g., “GTK_INPUT_HINT_EMOJI|GTK_INPUT_HINT_LOWERCASE”, or “emoji|lowercase” or 520). - colors (in the format understood by [method@Gdk.RGBA.parse]) - transforms (in the format understood by [func@Gsk.Transform.parse]) - Pango attribute lists (in the format understood by [method@Pango.AttrList.to_string]) - Pango tab arrays (in the format understood by [method@Pango.TabArray.to_string]) - Pango font descriptions (in the format understood by [func@Pango.FontDescription.from_string]) - `GVariant` (in the format understood by [func@GLib.Variant.parse]) - textures (can be specified as an object id, a resource path or a filename of an image file to load relative to the Builder file or the CWD if [method@Gtk.Builder.add_from_string] was used) - GFile (like textures, can be specified as an object id, a URI or a filename of a file to load relative to the Builder file or the CWD if [method@Gtk.Builder.add_from_string] was used) Objects can be referred to by their name and by default refer to objects declared in the local XML fragment and objects exposed via [method@Gtk.Builder.expose_object]. In general, `GtkBuilder` allows forward references to objects declared in the local XML; an object doesn’t have to be constructed before it can be referred to. The exception to this rule is that an object has to be constructed before it can be used as the value of a construct-only property. ### Child objects Many widgets have properties for child widgets, such as [property@Gtk.Expander:child]. In this case, the preferred way to specify the child widget in a ui file is to simply set the property: ```xml <object class="GtkExpander"> <property name="child"> <object class="GtkLabel"> ... </object> </property> </object> ``` Generic containers that can contain an arbitrary number of children, such as [class@Gtk.Box] instead use the `<child>` element. A `<child>` element contains an `<object>` element which describes the child object. Most often, child objects are widgets inside a container, but they can also be, e.g., actions in an action group, or columns in a tree model. Any object type that implements the [iface@Gtk.Buildable] interface can specify how children may be added to it. Since many objects and widgets that are included with GTK already implement the `GtkBuildable` interface, typically child objects can be added using the `<child>` element without having to be concerned about the underlying implementation. See the [`GtkWidget` documentation](class.Widget.html#gtkwidget-as-gtkbuildable) for many examples of using `GtkBuilder` with widgets, including setting child objects using the `<child>` element. A noteworthy special case to the general rule that only objects implementing `GtkBuildable` may specify how to handle the `<child>` element is that `GtkBuilder` provides special support for adding objects to a [class@Gio.ListStore] by using the `<child>` element. For instance: ```xml <object class="GListStore"> <property name="item-type">MyObject</property> <child> <object class="MyObject" /> </child> ... </object> ``` ### Property bindings It is also possible to bind a property value to another object's property value using the attributes "bind-source" to specify the source object of the binding, and optionally, "bind-property" and "bind-flags" to specify the source property and source binding flags respectively. Internally, `GtkBuilder` implements this using [class@GObject.Binding] objects. For instance, in the example below the “label” property of the `bottom_label` widget is bound to the “label” property of the `top_button` widget: ```xml <object class="GtkBox"> <property name="orientation">vertical</property> <child> <object class="GtkButton" id="top_button"> <property name="label">Hello, world</property> </object> </child> <child> <object class="GtkLabel" id="bottom_label"> <property name="label" bind-source="top_button" bind-property="label" bind-flags="sync-create" /> </object> </child> </object> ``` For more information, see the documentation of the [method@GObject.Object.bind_property] method. Please note that another way to set up bindings between objects in .ui files is to use the `GtkExpression` methodology. See the [`GtkExpression` documentation](class.Expression.html#gtkexpression-in-ui-files) for more information. ### Internal children Sometimes it is necessary to refer to widgets which have implicitly been constructed by GTK as part of a composite widget, to set properties on them or to add further children (e.g. the content area of a `GtkDialog`). This can be achieved by setting the “internal-child” property of the `<child>` element to a true value. Note that `GtkBuilder` still requires an `<object>` element for the internal child, even if it has already been constructed. ### Specialized children A number of widgets have different places where a child can be added (e.g. tabs vs. page content in notebooks). This can be reflected in a UI definition by specifying the “type” attribute on a `<child>` The possible values for the “type” attribute are described in the sections describing the widget-specific portions of UI definitions. ### Signal handlers and function pointers Signal handlers are set up with the `<signal>` element. The “name” attribute specifies the name of the signal, and the “handler” attribute specifies the function to connect to the signal. ```xml <object class="GtkButton" id="hello_button"> <signal name="clicked" handler="hello_button__clicked" /> </object> ``` The remaining attributes, “after”, “swapped” and “object”, have the same meaning as the corresponding parameters of the [func@GObject.signal_connect_object] or [func@GObject.signal_connect_data] functions: - “after” matches the `G_CONNECT_AFTER` flag, and will ensure that the handler is called after the default class closure for the signal - “swapped” matches the `G_CONNECT_SWAPPED` flag, and will swap the instance and closure arguments when invoking the signal handler - “object” will bind the signal handler to the lifetime of the object referenced by the attribute By default "swapped" will be set to "yes" if not specified otherwise, in the case where "object" is set, for convenience. A “last_modification_time” attribute is also allowed, but it does not have a meaning to the builder. When compiling applications for Windows, you must declare signal callbacks with the `G_MODULE_EXPORT` decorator, or they will not be put in the symbol table: ```c G_MODULE_EXPORT void hello_button__clicked (GtkButton *button, gpointer data) { // ... } ``` On Linux and Unix, this is not necessary; applications should instead be compiled with the `-Wl,--export-dynamic` argument inside their compiler flags, and linked against `gmodule-export-2.0`. ## Example UI Definition ```xml <interface> <object class="GtkDialog" id="dialog1"> <child internal-child="content_area"> <object class="GtkBox"> <child internal-child="action_area"> <object class="GtkBox"> <child> <object class="GtkButton" id="ok_button"> <property name="label" translatable="yes">_Ok</property> <property name="use-underline">True</property> <signal name="clicked" handler="ok_button_clicked"/> </object> </child> </object> </child> </object> </child> </object> </interface> ``` ## Using GtkBuildable for extending UI definitions Objects can implement the [iface@Gtk.Buildable] interface to add custom elements and attributes to the XML. Typically, any extension will be documented in each type that implements the interface. ## Menus In addition to objects with properties that are created with `<object>` and `<property>` elements, `GtkBuilder` also allows to parse XML menu definitions as used by [class@Gio.Menu] when exporting menu models over D-Bus, and as described in the [class@Gtk.PopoverMenu] documentation. Menus can be defined as toplevel elements, or as property values for properties of type `GMenuModel`. ## Templates When describing a [class@Gtk.Widget], you can use the `<template>` tag to describe a UI bound to a specific widget type. GTK will automatically load the UI definition when instantiating the type, and bind children and signal handlers to instance fields and function symbols. For more information, see the [`GtkWidget` documentation](class.Widget.html#building-composite-widgets-from-template-xml) for details. Creates a new empty builder object. This function is only useful if you intend to make multiple calls to [method@Gtk.Builder.add_from_file], [method@Gtk.Builder.add_from_resource] or [method@Gtk.Builder.add_from_string] in order to merge multiple UI descriptions into a single builder. a new (empty) `GtkBuilder` object Parses the UI definition in the file @filename. If there is an error opening the file or parsing the description then the program will be aborted. You should only ever attempt to parse user interface descriptions that are shipped as part of your program. a `GtkBuilder` containing the described interface filename of user interface description file Parses the UI definition at @resource_path. If there is an error locating the resource or parsing the description, then the program will be aborted. a `GtkBuilder` containing the described interface a `GResource` resource path Parses the UI definition in @string. If @string is %NULL-terminated, then @length should be -1. If @length is not -1, then it is the length of @string. If there is an error parsing @string then the program will be aborted. You should not attempt to parse user interface description from untrusted sources. a `GtkBuilder` containing the interface described by @string a user interface (XML) description the length of @string, or -1 Parses a file containing a UI definition and merges it with the current contents of @builder. This function is useful if you need to call [method@Gtk.Builder.set_current_object]) to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want [ctor@Gtk.Builder.new_from_file] instead. If an error occurs, 0 will be returned and @error will be assigned a `GError` from the `GTK_BUILDER_ERROR`, `G_MARKUP_ERROR` or `G_FILE_ERROR` domains. It’s not really reasonable to attempt to handle failures of this call. You should not use this function with untrusted files (ie: files that are not part of your application). Broken `GtkBuilder` files can easily crash your program, and it’s possible that memory was leaked leading up to the reported failure. The only reasonable thing to do when an error is detected is to call `g_error()`. %TRUE on success, %FALSE if an error occurred a `GtkBuilder` the name of the file to parse Parses a resource file containing a UI definition and merges it with the current contents of @builder. This function is useful if you need to call [method@Gtk.Builder.set_current_object] to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want [ctor@Gtk.Builder.new_from_resource] instead. If an error occurs, 0 will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_RESOURCE_ERROR domain. It’s not really reasonable to attempt to handle failures of this call. The only reasonable thing to do when an error is detected is to call g_error(). %TRUE on success, %FALSE if an error occurred a `GtkBuilder` the path of the resource file to parse Parses a string containing a UI definition and merges it with the current contents of @builder. This function is useful if you need to call [method@Gtk.Builder.set_current_object] to add user data to callbacks before loading `GtkBuilder` UI. Otherwise, you probably want [ctor@Gtk.Builder.new_from_string] instead. Upon errors %FALSE will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_VARIANT_PARSE_ERROR domain. It’s not really reasonable to attempt to handle failures of this call. The only reasonable thing to do when an error is detected is to call g_error(). %TRUE on success, %FALSE if an error occurred a `GtkBuilder` the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) Parses a file containing a UI definition building only the requested objects and merges them with the current contents of @builder. Upon errors, 0 will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_FILE_ERROR domain. If you are adding an object that depends on an object that is not its child (for instance a `GtkTreeView` that depends on its `GtkTreeModel`), you have to explicitly list all of them in @object_ids. %TRUE on success, %FALSE if an error occurred a `GtkBuilder` the name of the file to parse nul-terminated array of objects to build Parses a resource file containing a UI definition, building only the requested objects and merges them with the current contents of @builder. Upon errors, 0 will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_RESOURCE_ERROR domain. If you are adding an object that depends on an object that is not its child (for instance a `GtkTreeView` that depends on its `GtkTreeModel`), you have to explicitly list all of them in @object_ids. %TRUE on success, %FALSE if an error occurred a `GtkBuilder` the path of the resource file to parse nul-terminated array of objects to build Parses a string containing a UI definition, building only the requested objects and merges them with the current contents of @builder. Upon errors %FALSE will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR or %G_MARKUP_ERROR domain. If you are adding an object that depends on an object that is not its child (for instance a `GtkTreeView` that depends on its `GtkTreeModel`), you have to explicitly list all of them in @object_ids. %TRUE on success, %FALSE if an error occurred a `GtkBuilder` the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) nul-terminated array of objects to build Creates a closure to invoke the function called @function_name. This is using the create_closure() implementation of @builder's [iface@Gtk.BuilderScope]. If no closure could be created, %NULL will be returned and @error will be set. A new closure for invoking @function_name a `GtkBuilder` name of the function to look up closure creation flags Object to create the closure with Add @object to the @builder object pool so it can be referenced just like any other object built by builder. Only a single object may be added using @name. However, it is not an error to expose the same object under multiple names. `gtk_builder_get_object()` may be used to determine if an object has already been added with @name. a `GtkBuilder` the name of the object exposed to the builder the object to expose Main private entry point for building composite components from template XML. Most likely you do not need to call this function in applications as templates are handled by `GtkWidget`. A positive value on success, 0 if an error occurred a `GtkBuilder` the object that is being extended the type that the template is for the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) Gets the current object set via gtk_builder_set_current_object(). the current object a `GtkBuilder` Gets the object named @name. Note that this function does not increment the reference count of the returned object. the object named @name a `GtkBuilder` name of object to get Gets all objects that have been constructed by @builder. Note that this function does not increment the reference counts of the returned objects. a newly-allocated `GSList` containing all the objects constructed by the `GtkBuilder instance`. It should be freed by g_slist_free() a `GtkBuilder` Gets the scope in use that was set via gtk_builder_set_scope(). the current scope a `GtkBuilder` Gets the translation domain of @builder. the translation domain a `GtkBuilder` Looks up a type by name. This is using the virtual function that `GtkBuilder` has for that purpose. This is mainly used when implementing the `GtkBuildable` interface on a type. the `GType` found for @type_name or %G_TYPE_INVALID if no type was found a `GtkBuilder` type name to lookup Sets the current object for the @builder. The current object can be thought of as the `this` object that the builder is working for and will often be used as the default object when an object is optional. [method@Gtk.Widget.init_template] for example will set the current object to the widget the template is inited for. For functions like [ctor@Gtk.Builder.new_from_resource], the current object will be %NULL. a `GtkBuilder` the new current object Sets the scope the builder should operate in. If @scope is %NULL, a new [class@Gtk.BuilderCScope] will be created. a `GtkBuilder` the scope to use Sets the translation domain of @builder. a `GtkBuilder` the translation domain Demarshals a value from a string. This function calls g_value_init() on the @value argument, so it need not be initialised beforehand. Can handle char, uchar, boolean, int, uint, long, ulong, enum, flags, float, double, string, `GdkRGBA` and `GtkAdjustment` type values. Upon errors %FALSE will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR domain. %TRUE on success a `GtkBuilder` the `GParamSpec` for the property the string representation of the value the `GValue` to store the result in Demarshals a value from a string. Unlike [method@Gtk.Builder.value_from_string], this function takes a `GType` instead of `GParamSpec`. Calls g_value_init() on the @value argument, so it need not be initialised beforehand. Upon errors %FALSE will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR domain. %TRUE on success a `GtkBuilder` the `GType` of the value the string representation of the value the `GValue` to store the result in The object the builder is evaluating for. The scope the builder is operating in The translation domain used when translating property values that have been marked as translatable. If the translation domain is %NULL, `GtkBuilder` uses gettext(), otherwise g_dgettext(). A `GtkBuilderScope` implementation for the C language. `GtkBuilderCScope` instances use symbols explicitly added to @builder with prior calls to [method@Gtk.BuilderCScope.add_callback_symbol]. If developers want to do that, they are encouraged to create their own scopes for that purpose. In the case that symbols are not explicitly added; GTK will uses `GModule`’s introspective features (by opening the module %NULL) to look at the application’s symbol table. From here it tries to match the signal function names given in the interface description with symbols in the application. Note that unless [method@Gtk.BuilderCScope.add_callback_symbol] is called for all signal callbacks which are referenced by the loaded XML, this functionality will require that `GModule` be supported on the platform. Creates a new `GtkBuilderCScope` object to use with future `GtkBuilder` instances. Calling this function is only necessary if you want to add custom callbacks via [method@Gtk.BuilderCScope.add_callback_symbol]. a new `GtkBuilderCScope` Adds the @callback_symbol to the scope of @builder under the given @callback_name. Using this function overrides the behavior of [method@Gtk.Builder.create_closure] for any callback symbols that are added. Using this method allows for better encapsulation as it does not require that callback symbols be declared in the global namespace. a `GtkBuilderCScope` The name of the callback, as expected in the XML The callback pointer A convenience function to add many callbacks. This is equivalent to calling [method@Gtk.BuilderCScope.add_callback_symbol] for each symbol. a `GtkBuilderCScope` The name of the callback, as expected in the XML The callback pointer A list of callback name and callback symbol pairs terminated with %NULL Fetches a symbol previously added with gtk_builder_cscope_add_callback_symbol(). The callback symbol in @builder for @callback_name a `GtkBuilderCScope` The name of the callback The list of flags that can be passed to gtk_builder_create_closure(). New values may be added in the future for new features, so external implementations of [iface@Gtk.BuilderScope] should test the flags for unknown values and raise a %GTK_BUILDER_ERROR_INVALID_ATTRIBUTE error when they encounter one. The closure should be created swapped. See g_cclosure_new_swap() for details. Error codes that identify various errors that can occur while using `GtkBuilder`. A type-func attribute didn’t name a function that returns a `GType`. The input contained a tag that `GtkBuilder` can’t handle. An attribute that is required by `GtkBuilder` was missing. `GtkBuilder` found an attribute that it doesn’t understand. `GtkBuilder` found a tag that it doesn’t understand. A required property value was missing. `GtkBuilder` couldn’t parse some attribute value. The input file requires a newer version of GTK. An object id occurred twice. A specified object type is of the same type or derived from the type of the composite class being extended with builder XML. The wrong type was specified in a composite class’s template XML The specified property is unknown for the object class. The specified signal is unknown for the object class. An object id is unknown. A function could not be found. This often happens when symbols are set to be kept private. Compiling code with -rdynamic or using the `gmodule-export-2.0` pkgconfig module can fix this problem. Registers an error quark for [class@Gtk.Builder] errors. the error quark Creates widgets by instantiating `GtkBuilder` UI templates. The templates must extend the class that the parent widget expects. For example, a factory provided to [property@Gtk.ListView:factory] must have a template that extends [class@Gtk.ListItem]. Templates typically use [class@Gtk.Expression] to obtain data from the items in the model. Example: ```xml <interface> <template class="GtkListItem"> <property name="child"> <object class="GtkLabel"> <property name="xalign">0</property> <binding name="label"> <lookup name="name" type="SettingsKey"> <lookup name="item">GtkListItem</lookup> </lookup> </binding> </object> </property> </template> </interface> ``` A common approach is to embed such templates as CDATA marked sections into a surrounding UI file. Note that if you use this approach, extracting translatable strings with xgettext will not work for strings inside the marked section. Creates a new `GtkBuilderListItemFactory` that instantiates widgets using @bytes as the data to pass to `GtkBuilder`. a new `GtkBuilderListItemFactory` A scope to use when instantiating the `GBytes` containing the UI definition to instantiate Creates a new `GtkBuilderListItemFactory` that instantiates widgets using data read from the given @resource_path to pass to `GtkBuilder`. a new `GtkBuilderListItemFactory` A scope to use when instantiating valid path to a resource that contains the UI definition Gets the data used as the `GtkBuilder` UI template for constructing listitems. The `GtkBuilder` data a `GtkBuilderListItemFactory` If the data references a resource, gets the path of that resource. The path to the resource a `GtkBuilderListItemFactory` Gets the scope used when constructing listitems. The scope used when constructing listitems a `GtkBuilderListItemFactory` `GBytes` containing the UI definition. Path of the resource containing the UI definition. `GtkBuilderScope` to use when instantiating listitems Provides language binding support to `GtkBuilder`. The goal of `GtkBuilderScope` is to look up programming-language-specific values for strings that are given in a `GtkBuilder` UI file. The primary intended audience is bindings that want to provide deeper integration of `GtkBuilder` into the language. A `GtkBuilderScope` instance may be used with multiple `GtkBuilder` objects, even at once. By default, GTK will use its own implementation of `GtkBuilderScope` for the C language which can be created via [ctor@Gtk.BuilderCScope.new]. If you implement `GtkBuilderScope` for a language binding, you may want to (partially) derive from or fall back to a [class@Gtk.BuilderCScope], as that class implements support for automatic lookups from C symbols. Create a closure with the given arguments. See gtk_builder_create_closure() for more details on those. The C implementation will try to use dlsym() to locate the function name and then g_cclosure_new() to create a closure for the symbol. The default implementation just fails and returns %NULL. Try to lookup a `GType` via the given function name, specified explicitly in a GtkBuilder file, like via the "type-func" attribute in the `<object>` tag. This function is very rarely used. The C implementation will use dlsym() and call the resulting function as a `GTypeFunc`. The default implementation will fail and just return %G_TYPE_INVALID. Try to lookup a `GType` via the its name. See gtk_builder_get_type_from_name() for more details. The C implementation will use g_type_from_name() and if that fails try to guess the correct function name for registering the type and then use dlsym() to load it. The default implementation just tries g_type_from_name() and otherwise fails. The virtual function table to implement for `GtkBuilderScope` implementations. Default implementations for each function do exist, but they usually just fail, so it is suggested that implementations implement all of them. Try to lookup a `GType` via the its name. See gtk_builder_get_type_from_name() for more details. The C implementation will use g_type_from_name() and if that fails try to guess the correct function name for registering the type and then use dlsym() to load it. The default implementation just tries g_type_from_name() and otherwise fails. Try to lookup a `GType` via the given function name, specified explicitly in a GtkBuilder file, like via the "type-func" attribute in the `<object>` tag. This function is very rarely used. The C implementation will use dlsym() and call the resulting function as a `GTypeFunc`. The default implementation will fail and just return %G_TYPE_INVALID. Create a closure with the given arguments. See gtk_builder_create_closure() for more details on those. The C implementation will try to use dlsym() to locate the function name and then g_cclosure_new() to create a closure for the symbol. The default implementation just fails and returns %NULL. Calls a callback function when the button is clicked. <picture> <source srcset="button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkButton" src="button.png"> </picture> The `GtkButton` widget can hold any valid child widget. That is, it can hold almost any other standard `GtkWidget`. The most commonly used child is the `GtkLabel`. # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.Button::activate] # CSS nodes `GtkButton` has a single CSS node with name button. The node will get the style classes .image-button or .text-button, if the content is just an image or label, respectively. It may also receive the .flat style class. When activating a button via the keyboard, the button will temporarily gain the .keyboard-activating style class. Other style classes that are commonly used with `GtkButton` include .suggested-action and .destructive-action. In special cases, buttons can be made round by adding the .circular style class. Button-like widgets like [class@Gtk.ToggleButton], [class@Gtk.MenuButton], [class@Gtk.VolumeButton], [class@Gtk.LockButton], [class@Gtk.ColorButton] or [class@Gtk.FontButton] use style classes such as .toggle, .popup, .scale, .lock, .color on the button node to differentiate themselves from a plain `GtkButton`. # Accessibility `GtkButton` uses the [enum@Gtk.AccessibleRole.button] role. Creates a new `GtkButton` widget. To add a child widget to the button, use [method@Gtk.Button.set_child]. The newly created `GtkButton` widget. Creates a new button containing an icon from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately. a new `GtkButton` displaying the themed icon an icon name Creates a `GtkButton` widget with a `GtkLabel` child. The newly created `GtkButton` widget The text you want the `GtkLabel` to hold Creates a new `GtkButton` containing a label. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing <kbd>Alt</kbd> and that key activates the button. a new `GtkButton` The text of the button, with an underscore in front of the mnemonic character Signal that causes the button to animate press then release. Applications should never connect to this signal, but use the @clicked signal. Signal emitted when the button has been activated (pressed and released). Retrieves whether the button can be smaller than the natural size of its contents. true if the button can shrink, and false otherwise a button Gets the child widget of @button. the child widget of @button a `GtkButton` Returns whether the button has a frame. %TRUE if the button has a frame a `GtkButton` Returns the icon name of the button. If the icon name has not been set with [method@Gtk.Button.set_icon_name] the return value will be %NULL. This will be the case if you create an empty button with [ctor@Gtk.Button.new] to use as a container. The icon name set via [method@Gtk.Button.set_icon_name] A `GtkButton` Fetches the text from the label of the button. If the label text has not been set with [method@Gtk.Button.set_label] the return value will be %NULL. This will be the case if you create an empty button with [ctor@Gtk.Button.new] to use as a container. The text of the label widget. This string is owned by the widget and must not be modified or freed. a `GtkButton` gets whether underlines are interpreted as mnemonics. See [method@Gtk.Button.set_use_underline]. %TRUE if an embedded underline in the button label indicates the mnemonic accelerator keys. a `GtkButton` Sets whether the button size can be smaller than the natural size of its contents. For text buttons, setting @can_shrink to true will ellipsize the label. For icons and custom children, this function has no effect. a button whether the button can shrink Sets the child widget of @button. Note that by using this API, you take full responsibility for setting up the proper accessibility label and description information for @button. Most likely, you'll either set the accessibility label or description for @button explicitly, or you'll set a labelled-by or described-by relations from @child to @button. a `GtkButton` the child widget Sets the style of the button. Buttons can have a flat appearance or have a frame drawn around them. a `GtkButton` whether the button should have a visible frame Adds a `GtkImage` with the given icon name as a child. If @button already contains a child widget, that child widget will be removed and replaced with the image. A `GtkButton` An icon name Sets the text of the label of the button to @label. This will also clear any previously set labels. a `GtkButton` a string Sets whether to use underlines as mnemonics. If true, an underline in the text of the button label indicates the next character should be used for the mnemonic accelerator key. a `GtkButton` %TRUE if underlines in the text indicate mnemonics Whether the size of the button can be made smaller than the natural size of its contents. For text buttons, setting this property will allow ellipsizing the label. If the contents of a button are an icon or a custom widget, setting this property has no effect. The child widget. Whether the button has a frame. The name of the icon used to automatically populate the button. Text of the label inside the button, if the button contains a label widget. If set, an underline in the text indicates that the following character is to be used as mnemonic. Emitted to animate press then release. This is an action signal. Applications should never connect to this signal, but use the [signal@Gtk.Button::clicked] signal. The default bindings for this signal are all forms of the <kbd>␣</kbd> and <kbd>Enter</kbd> keys. Emitted when the button has been activated (pressed and released). The parent class. Signal emitted when the button has been activated (pressed and released). Signal that causes the button to animate press then release. Applications should never connect to this signal, but use the @clicked signal. Prebuilt sets of buttons for `GtkDialog`. If none of these choices are appropriate, simply use %GTK_BUTTONS_NONE and call [method@Gtk.Dialog.add_buttons]. > Please note that %GTK_BUTTONS_OK, %GTK_BUTTONS_YES_NO > and %GTK_BUTTONS_OK_CANCEL are discouraged by the > [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/). no buttons at all an OK button a Close button a Cancel button Yes and No buttons OK and Cancel buttons A variant of `GtkClosureExpression` using a C closure. Creates a `GtkExpression` that calls `callback_func` when it is evaluated. This function is a variant of [ctor@Gtk.ClosureExpression.new] that creates a `GClosure` by calling g_cclosure_new() with the given `callback_func`, `user_data` and `user_destroy`. a new `GtkExpression` the type of the value that this expression evaluates to marshaller used for creating a closure the number of params needed for evaluating @closure expressions for each parameter callback used for creating a closure user data used for creating a closure destroy notify for @user_data This macro should be used to emit a standard warning about unexpected properties in set_cell_property() and get_cell_property() implementations. There is no replacement the `GObject` on which set_cell_property() or get_cell_property() was called the numeric id of the property the `GParamSpec` of the property Returns true if the version of the GTK header files is the same as or newer than the passed-in version. major version (e.g. 1 for version 1.2.5) minor version (e.g. 2 for version 1.2.5) micro version (e.g. 5 for version 1.2.5) Displays a Gregorian calendar, one month at a time. <picture> <source srcset="calendar-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkCalendar" src="calendar.png"> </picture> A `GtkCalendar` can be created with [ctor@Gtk.Calendar.new]. The selected date can be retrieved from a `GtkCalendar` using [method@Gtk.Calendar.get_date]. It can be altered with [method@Gtk.Calendar.set_date]. To place a visual marker on a particular day, use [method@Gtk.Calendar.mark_day] and to remove the marker, [method@Gtk.Calendar.unmark_day]. Alternative, all marks can be cleared with [method@Gtk.Calendar.clear_marks]. Users should be aware that, although the Gregorian calendar is the legal calendar in most countries, it was adopted progressively between 1582 and 1929. Display before these dates is likely to be historically incorrect. # Shortcuts and Gestures `GtkCalendar` supports the following gestures: - Scrolling up or down will switch to the previous or next month. - Date strings can be dropped for setting the current day. # CSS nodes ``` calendar.view ├── header │ ├── button │ ├── stack.month │ ├── button │ ├── button │ ├── label.year │ ╰── button ╰── grid ╰── label[.day-name][.week-number][.day-number][.other-month][.today] ``` `GtkCalendar` has a main node with name calendar. It contains a subnode called header containing the widgets for switching between years and months. The grid subnode contains all day labels, including week numbers on the left (marked with the .week-number css class) and day names on top (marked with the .day-name css class). Day labels that belong to the previous or next month get the .other-month style class. The label of the current day get the .today style class. Marked day labels get the :selected state assigned. Creates a new calendar, with the current date being selected. a newly `GtkCalendar` widget Remove all visual markers. a `GtkCalendar` Returns a `GDateTime` representing the shown year, month and the selected day. The returned date is in the local time zone. the `GDateTime` representing the selected date a `GtkCalendar` Gets the day of the selected date. the day of the selected date. a `GtkCalendar` Returns if the @day of the @calendar is already marked. whether the day is marked. a `GtkCalendar` the day number between 1 and 31. Gets the month of the selected date. The month of the selected date (as a number between 0 and 11). a `GtkCalendar` Returns whether @self is currently showing the names of the week days. This is the value of the [property@Gtk.Calendar:show-day-names] property. Whether the calendar shows day names. a `GtkCalendar` Returns whether @self is currently showing the heading. This is the value of the [property@Gtk.Calendar:show-heading] property. Whether the calendar is showing a heading. a `GtkCalendar` Returns whether @self is showing week numbers right now. This is the value of the [property@Gtk.Calendar:show-week-numbers] property. Whether the calendar is showing week numbers. a `GtkCalendar` Gets the year of the selected date. the year of the selected date. a `GtkCalendar` Places a visual marker on a particular day of the current month. a `GtkCalendar` the day number to mark between 1 and 31. Switches to @date's year and month and select its day. Use [method@Calendar.set_date] instead. a `GtkCalendar`. a `GDateTime` representing the day to select Switches to @date's year and month and selects its day. a `GtkCalendar`. a `GDateTime` representing the day to select Sets the day for the selected date. The new date must be valid. For example, setting the day to 31 when the month is February will fail. a `GtkCalendar` The desired day for the selected date (as a number between 1 and 31). Sets the month for the selected date. The new date must be valid. For example, setting the month to 1 (February) when the day is 31 will fail. a `GtkCalendar` The desired month for the selected date (as a number between 0 and 11). Sets whether the calendar shows day names. a `GtkCalendar` Whether to show day names above the day numbers Sets whether the calendar should show a heading. The heading contains the current year and month as well as buttons for changing both. a `GtkCalendar` Whether to show the heading in the calendar Sets whether week numbers are shown in the calendar. a `GtkCalendar` whether to show week numbers alongside the days Sets the year for the selected date. The new date must be valid. For example, setting the year to 2023 when the date is February 29 will fail. a `GtkCalendar` The desired year for the selected date (within [struct@GLib.DateTime] limits, i.e. from 0001 to 9999). Removes the visual marker from a particular day. a `GtkCalendar`. the day number to unmark between 1 and 31. The selected date. This property gets initially set to the current date. The selected day (as a number between 1 and 31). This property will be removed in GTK 5. Use [property@Calendar:date] instead. The selected month (as a number between 0 and 11). This property gets initially set to the current month. This property will be removed in GTK 5. Use [property@Calendar:date] instead. Determines whether day names are displayed. Determines whether a heading is displayed. Determines whether week numbers are displayed. The selected year. This property gets initially set to the current year. This property will be removed in GTK 5. Use [property@Calendar:date] instead. Emitted when the user selects a day. Emitted when the user switches to the next month. Emitted when user switches to the next year. Emitted when the user switches to the previous month. Emitted when user switches to the previous year. Invokes a callback. Create a custom action that calls the given @callback when activated. A new shortcut action the callback to call when the action is activated the data to be passed to @callback the function to be called when the callback action is finalized The type of the callback functions used for iterating over the cell renderers and their allocated areas inside a `GtkCellArea`, see gtk_cell_area_foreach_alloc(). There is no replacement %TRUE to stop iterating over cells. the cell renderer to operate on the area allocated to @renderer inside the rectangle provided to gtk_cell_area_foreach_alloc(). the background area for @renderer inside the background area provided to gtk_cell_area_foreach_alloc(). user-supplied data An abstract class for laying out `GtkCellRenderer`s The `GtkCellArea` is an abstract class for [iface@Gtk.CellLayout] widgets (also referred to as "layouting widgets") to interface with an arbitrary number of [class@Gtk.CellRenderer]s and interact with the user for a given [iface@Gtk.TreeModel] row. The cell area handles events, focus navigation, drawing and size requests and allocations for a given row of data. Usually users dont have to interact with the `GtkCellArea` directly unless they are implementing a cell-layouting widget themselves. ## Requesting area sizes As outlined in [GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management), GTK uses a height-for-width geometry management system to compute the sizes of widgets and user interfaces. `GtkCellArea` uses the same semantics to calculate the size of an area for an arbitrary number of `GtkTreeModel` rows. When requesting the size of a cell area one needs to calculate the size for a handful of rows, and this will be done differently by different layouting widgets. For instance a [class@Gtk.TreeViewColumn] always lines up the areas from top to bottom while a [class@Gtk.IconView] on the other hand might enforce that all areas received the same width and wrap the areas around, requesting height for more cell areas when allocated less width. It’s also important for areas to maintain some cell alignments with areas rendered for adjacent rows (cells can appear “columnized” inside an area even when the size of cells are different in each row). For this reason the `GtkCellArea` uses a [class@Gtk.CellAreaContext] object to store the alignments and sizes along the way (as well as the overall largest minimum and natural size for all the rows which have been calculated with the said context). The [class@Gtk.CellAreaContext] is an opaque object specific to the `GtkCellArea` which created it (see [method@Gtk.CellArea.create_context]). The owning cell-layouting widget can create as many contexts as it wishes to calculate sizes of rows which should receive the same size in at least one orientation (horizontally or vertically), However, it’s important that the same [class@Gtk.CellAreaContext] which was used to request the sizes for a given `GtkTreeModel` row be used when rendering or processing events for that row. In order to request the width of all the rows at the root level of a `GtkTreeModel` one would do the following: ```c GtkTreeIter iter; int minimum_width; int natural_width; valid = gtk_tree_model_get_iter_first (model, &iter); while (valid) { gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE); gtk_cell_area_get_preferred_width (area, context, widget, NULL, NULL); valid = gtk_tree_model_iter_next (model, &iter); } gtk_cell_area_context_get_preferred_width (context, &minimum_width, &natural_width); ``` Note that in this example it’s not important to observe the returned minimum and natural width of the area for each row unless the cell-layouting object is actually interested in the widths of individual rows. The overall width is however stored in the accompanying `GtkCellAreaContext` object and can be consulted at any time. This can be useful since `GtkCellLayout` widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The `GtkCellLayout` widget in that case would calculate the required width of the rows in an idle or timeout source (see [func@GLib.timeout_add]) and when the widget is requested its actual width in [vfunc@Gtk.Widget.measure] it can simply consult the width accumulated so far in the `GtkCellAreaContext` object. A simple example where rows are rendered from top to bottom and take up the full width of the layouting widget would look like: ```c static void foo_get_preferred_width (GtkWidget *widget, int *minimum_size, int *natural_size) { Foo *self = FOO (widget); FooPrivate *priv = foo_get_instance_private (self); foo_ensure_at_least_one_handfull_of_rows_have_been_requested (self); gtk_cell_area_context_get_preferred_width (priv->context, minimum_size, natural_size); } ``` In the above example the `Foo` widget has to make sure that some row sizes have been calculated (the amount of rows that `Foo` judged was appropriate to request space for in a single timeout iteration) before simply returning the amount of space required by the area via the `GtkCellAreaContext`. Requesting the height for width (or width for height) of an area is a similar task except in this case the `GtkCellAreaContext` does not store the data (actually, it does not know how much space the layouting widget plans to allocate it for every row. It’s up to the layouting widget to render each row of data with the appropriate height and width which was requested by the `GtkCellArea`). In order to request the height for width of all the rows at the root level of a `GtkTreeModel` one would do the following: ```c GtkTreeIter iter; int minimum_height; int natural_height; int full_minimum_height = 0; int full_natural_height = 0; valid = gtk_tree_model_get_iter_first (model, &iter); while (valid) { gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE); gtk_cell_area_get_preferred_height_for_width (area, context, widget, width, &minimum_height, &natural_height); if (width_is_for_allocation) cache_row_height (&iter, minimum_height, natural_height); full_minimum_height += minimum_height; full_natural_height += natural_height; valid = gtk_tree_model_iter_next (model, &iter); } ``` Note that in the above example we would need to cache the heights returned for each row so that we would know what sizes to render the areas for each row. However we would only want to really cache the heights if the request is intended for the layouting widgets real allocation. In some cases the layouting widget is requested the height for an arbitrary for_width, this is a special case for layouting widgets who need to request size for tens of thousands of rows. For this case it’s only important that the layouting widget calculate one reasonably sized chunk of rows and return that height synchronously. The reasoning here is that any layouting widget is at least capable of synchronously calculating enough height to fill the screen height (or scrolled window height) in response to a single call to [vfunc@Gtk.Widget.measure]. Returning a perfect height for width that is larger than the screen area is inconsequential since after the layouting receives an allocation from a scrolled window it simply continues to drive the scrollbar values while more and more height is required for the row heights that are calculated in the background. ## Rendering Areas Once area sizes have been acquired at least for the rows in the visible area of the layouting widget they can be rendered at [vfunc@Gtk.Widget.snapshot] time. A crude example of how to render all the rows at the root level runs as follows: ```c GtkAllocation allocation; GdkRectangle cell_area = { 0, }; GtkTreeIter iter; int minimum_width; int natural_width; gtk_widget_get_allocation (widget, &allocation); cell_area.width = allocation.width; valid = gtk_tree_model_get_iter_first (model, &iter); while (valid) { cell_area.height = get_cached_height_for_row (&iter); gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE); gtk_cell_area_render (area, context, widget, cr, &cell_area, &cell_area, state_flags, FALSE); cell_area.y += cell_area.height; valid = gtk_tree_model_iter_next (model, &iter); } ``` Note that the cached height in this example really depends on how the layouting widget works. The layouting widget might decide to give every row its minimum or natural height or, if the model content is expected to fit inside the layouting widget without scrolling, it would make sense to calculate the allocation for each row at the time the widget is allocated using [func@Gtk.distribute_natural_allocation]. ## Handling Events and Driving Keyboard Focus Passing events to the area is as simple as handling events on any normal widget and then passing them to the [method@Gtk.CellArea.event] API as they come in. Usually `GtkCellArea` is only interested in button events, however some customized derived areas can be implemented who are interested in handling other events. Handling an event can trigger the [signal@Gtk.CellArea::focus-changed] signal to fire; as well as [signal@Gtk.CellArea::add-editable] in the case that an editable cell was clicked and needs to start editing. You can call [method@Gtk.CellArea.stop_editing] at any time to cancel any cell editing that is currently in progress. The `GtkCellArea` drives keyboard focus from cell to cell in a way similar to `GtkWidget`. For layouting widgets that support giving focus to cells it’s important to remember to pass `GTK_CELL_RENDERER_FOCUSED` to the area functions for the row that has focus and to tell the area to paint the focus at render time. Layouting widgets that accept focus on cells should implement the [vfunc@Gtk.Widget.focus] virtual method. The layouting widget is always responsible for knowing where `GtkTreeModel` rows are rendered inside the widget, so at [vfunc@Gtk.Widget.focus] time the layouting widget should use the `GtkCellArea` methods to navigate focus inside the area and then observe the [enum@Gtk.DirectionType] to pass the focus to adjacent rows and areas. A basic example of how the [vfunc@Gtk.Widget.focus] virtual method should be implemented: ``` static gboolean foo_focus (GtkWidget *widget, GtkDirectionType direction) { Foo *self = FOO (widget); FooPrivate *priv = foo_get_instance_private (self); int focus_row = priv->focus_row; gboolean have_focus = FALSE; if (!gtk_widget_has_focus (widget)) gtk_widget_grab_focus (widget); valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, priv->focus_row); while (valid) { gtk_cell_area_apply_attributes (priv->area, priv->model, &iter, FALSE, FALSE); if (gtk_cell_area_focus (priv->area, direction)) { priv->focus_row = focus_row; have_focus = TRUE; break; } else { if (direction == GTK_DIR_RIGHT || direction == GTK_DIR_LEFT) break; else if (direction == GTK_DIR_UP || direction == GTK_DIR_TAB_BACKWARD) { if (focus_row == 0) break; else { focus_row--; valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, focus_row); } } else { if (focus_row == last_row) break; else { focus_row++; valid = gtk_tree_model_iter_next (priv->model, &iter); } } } } return have_focus; } ``` Note that the layouting widget is responsible for matching the `GtkDirectionType` values to the way it lays out its cells. ## Cell Properties The `GtkCellArea` introduces cell properties for `GtkCellRenderer`s. This provides some general interfaces for defining the relationship cell areas have with their cells. For instance in a [class@Gtk.CellAreaBox] a cell might “expand” and receive extra space when the area is allocated more than its full natural request, or a cell might be configured to “align” with adjacent rows which were requested and rendered with the same `GtkCellAreaContext`. Use [method@Gtk.CellAreaClass.install_cell_property] to install cell properties for a cell area class and [method@Gtk.CellAreaClass.find_cell_property] or [method@Gtk.CellAreaClass.list_cell_properties] to get information about existing cell properties. To set the value of a cell property, use [method@Gtk.CellArea.cell_set_property], [method@Gtk.CellArea.cell_set] or [method@Gtk.CellArea.cell_set_valist]. To obtain the value of a cell property, use [method@Gtk.CellArea.cell_get_property] [method@Gtk.CellArea.cell_get] or [method@Gtk.CellArea.cell_get_valist]. List views use widgets for displaying their contents Activates @area, usually by activating the currently focused cell, however some subclasses which embed widgets in the area can also activate a widget if it currently has the focus. Whether @area was successfully activated. a `GtkCellArea` the `GtkCellArea`Context in context with the current row data the `GtkWidget` that @area is rendering on the size and location of @area relative to @widget’s allocation the `GtkCellRenderer`State flags for @area for this row of data. if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated. Adds @renderer to @area with the default child cell properties. a `GtkCellArea` the `GtkCellRenderer` to add to @area Applies any connected attributes to the renderers in @area by pulling the values from @tree_model. a `GtkCellArea` the `GtkTreeModel` to pull values from the `GtkTreeIter` in @tree_model to apply values for whether @iter has children whether @iter is expanded in the view and children are visible This is sometimes needed for cases where rows need to share alignments in one orientation but may be separately grouped in the opposing orientation. For instance, `GtkIconView` creates all icons (rows) to have the same width and the cells theirin to have the same horizontal alignments. However each row of icons may have a separate collective height. `GtkIconView` uses this to request the heights of each row based on a context which was already used to request all the row widths that are to be displayed. a newly created `GtkCellArea`Context copy of @context. a `GtkCellArea` the `GtkCellArea`Context to copy Creates a `GtkCellArea`Context to be used with @area for all purposes. `GtkCellArea`Context stores geometry information for rows for which it was operated on, it is important to use the same context for the same row of data at all times (i.e. one should render and handle events with the same `GtkCellArea`Context which was used to request the size of those rows of data). a newly created `GtkCellArea`Context which can be used with @area. a `GtkCellArea` Delegates event handling to a `GtkCellArea`. %TRUE if the event was handled by @area. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the `GdkEvent` to handle the @widget relative coordinates for @area the `GtkCellRenderer`State for @area in this row. This should be called by the @area’s owning layout widget when focus is to be passed to @area, or moved within @area for a given @direction and row data. Implementing `GtkCellArea` classes should implement this method to receive and navigate focus in its own way particular to how it lays out cells. %TRUE if focus remains inside @area as a result of this call. a `GtkCellArea` the `GtkDirectionType` Calls @callback for every `GtkCellRenderer` in @area. a `GtkCellArea` the `GtkCellCallback` to call user provided data pointer Calls @callback for every `GtkCellRenderer` in @area with the allocated rectangle inside @cell_area. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the @widget relative coordinates and size for @area the @widget relative coordinates of the background area the `GtkCellAllocCallback` to call user provided data pointer This should be implemented to report the values of child cell properties for a given child `GtkCellRenderer`. Retrieves a cell area’s initial minimum and natural height. @area will store some geometrical information in @context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the @minimum_height and @natural_height of this call but rather to consult gtk_cell_area_context_get_preferred_height() after a series of requests. a `GtkCellArea` the `GtkCellArea`Context to perform this request with the `GtkWidget` where @area will be rendering location to store the minimum height location to store the natural height Retrieves a cell area’s minimum and natural height if it would be given the specified @width. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_width(). It’s important to perform a series of gtk_cell_area_get_preferred_width() requests with @context first and then call gtk_cell_area_get_preferred_height_for_width() on each cell area individually to get the height for width of each fully requested row. If at some point, the width of a single row changes, it should be requested with gtk_cell_area_get_preferred_width() again and then the full width of the requested rows checked again with gtk_cell_area_context_get_preferred_width(). a `GtkCellArea` the `GtkCellArea`Context which has already been requested for widths. the `GtkWidget` where @area will be rendering the width for which to check the height of this area location to store the minimum height location to store the natural height Retrieves a cell area’s initial minimum and natural width. @area will store some geometrical information in @context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the @minimum_width and @natural_width of this call but rather to consult gtk_cell_area_context_get_preferred_width() after a series of requests. a `GtkCellArea` the `GtkCellArea`Context to perform this request with the `GtkWidget` where @area will be rendering location to store the minimum width location to store the natural width Retrieves a cell area’s minimum and natural width if it would be given the specified @height. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_height(). It’s important to perform a series of gtk_cell_area_get_preferred_height() requests with @context first and then call gtk_cell_area_get_preferred_width_for_height() on each cell area individually to get the height for width of each fully requested row. If at some point, the height of a single row changes, it should be requested with gtk_cell_area_get_preferred_height() again and then the full height of the requested rows checked again with gtk_cell_area_context_get_preferred_height(). a `GtkCellArea` the `GtkCellArea`Context which has already been requested for widths. the `GtkWidget` where @area will be rendering the height for which to check the width of this area location to store the minimum width location to store the natural width Gets whether the area prefers a height-for-width layout or a width-for-height layout. The `GtkSizeRequestMode` preferred by @area. a `GtkCellArea` Returns whether the area can do anything when activated, after applying new attributes to @area. whether @area can do anything when activated. a `GtkCellArea` Removes @renderer from @area. a `GtkCellArea` the `GtkCellRenderer` to remove from @area This should be implemented to handle changes in child cell properties for a given `GtkCellRenderer` that were previously installed on the `GtkCellAreaClass` with gtk_cell_area_class_install_cell_property(). Snapshots @area’s cells according to @area’s layout onto at the given coordinates. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the `GtkSnapshot` to draw to the @widget relative coordinates for @area’s background the @widget relative coordinates for @area the `GtkCellRenderer`State for @area in this row. whether @area should paint focus on focused cells for focused rows or not. Activates @area, usually by activating the currently focused cell, however some subclasses which embed widgets in the area can also activate a widget if it currently has the focus. Whether @area was successfully activated. a `GtkCellArea` the `GtkCellArea`Context in context with the current row data the `GtkWidget` that @area is rendering on the size and location of @area relative to @widget’s allocation the `GtkCellRenderer`State flags for @area for this row of data. if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated. This is used by `GtkCellArea` subclasses when handling events to activate cells, the base `GtkCellArea` class activates cells for keyboard events for free in its own GtkCellArea->activate() implementation. whether cell activation was successful a `GtkCellArea` the `GtkWidget` that @area is rendering onto the `GtkCellRenderer` in @area to activate the `GdkEvent` for which cell activation should occur the `GdkRectangle` in @widget relative coordinates of @renderer for the current row. the `GtkCellRenderer`State for @renderer Adds @renderer to @area with the default child cell properties. a `GtkCellArea` the `GtkCellRenderer` to add to @area Adds @sibling to @renderer’s focusable area, focus will be drawn around @renderer and all of its siblings if @renderer can focus for a given row. Events handled by focus siblings can also activate the given focusable @renderer. a `GtkCellArea` the `GtkCellRenderer` expected to have focus the `GtkCellRenderer` to add to @renderer’s focus area Adds @renderer to @area, setting cell properties at the same time. See gtk_cell_area_add() and gtk_cell_area_cell_set() for more details. a `GtkCellArea` a `GtkCellRenderer` to be placed inside @area the name of the first cell property to set a %NULL-terminated list of property names and values, starting with @first_prop_name Applies any connected attributes to the renderers in @area by pulling the values from @tree_model. a `GtkCellArea` the `GtkTreeModel` to pull values from the `GtkTreeIter` in @tree_model to apply values for whether @iter has children whether @iter is expanded in the view and children are visible Connects an @attribute to apply values from @column for the `GtkTreeModel` in use. a `GtkCellArea` the `GtkCellRenderer` to connect an attribute for the attribute name the `GtkTreeModel` column to fetch attribute values from Disconnects @attribute for the @renderer in @area so that attribute will no longer be updated with values from the model. a `GtkCellArea` the `GtkCellRenderer` to disconnect an attribute for the attribute name Returns the model column that an attribute has been mapped to, or -1 if the attribute is not mapped. the model column, or -1 a `GtkCellArea` a `GtkCellRenderer` an attribute on the renderer Gets the values of one or more cell properties for @renderer in @area. a `GtkCellArea` a `GtkCellRenderer` which is inside @area the name of the first cell property to get return location for the first cell property, followed optionally by more name/return location pairs, followed by %NULL Gets the value of a cell property for @renderer in @area. a `GtkCellArea` a `GtkCellRenderer` inside @area the name of the property to get a location to return the value Gets the values of one or more cell properties for @renderer in @area. a `GtkCellArea` a `GtkCellRenderer` inside @area the name of the first property to get return location for the first property, followed optionally by more name/return location pairs, followed by %NULL Sets one or more cell properties for @cell in @area. a `GtkCellArea` a `GtkCellRenderer` which is a cell inside @area the name of the first cell property to set a %NULL-terminated list of property names and values, starting with @first_prop_name Sets a cell property for @renderer in @area. a `GtkCellArea` a `GtkCellRenderer` inside @area the name of the cell property to set the value to set the cell property to Sets one or more cell properties for @renderer in @area. a `GtkCellArea` a `GtkCellRenderer` which inside @area the name of the first cell property to set a %NULL-terminated list of property names and values, starting with @first_prop_name This is sometimes needed for cases where rows need to share alignments in one orientation but may be separately grouped in the opposing orientation. For instance, `GtkIconView` creates all icons (rows) to have the same width and the cells theirin to have the same horizontal alignments. However each row of icons may have a separate collective height. `GtkIconView` uses this to request the heights of each row based on a context which was already used to request all the row widths that are to be displayed. a newly created `GtkCellArea`Context copy of @context. a `GtkCellArea` the `GtkCellArea`Context to copy Creates a `GtkCellArea`Context to be used with @area for all purposes. `GtkCellArea`Context stores geometry information for rows for which it was operated on, it is important to use the same context for the same row of data at all times (i.e. one should render and handle events with the same `GtkCellArea`Context which was used to request the size of those rows of data). a newly created `GtkCellArea`Context which can be used with @area. a `GtkCellArea` Delegates event handling to a `GtkCellArea`. %TRUE if the event was handled by @area. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the `GdkEvent` to handle the @widget relative coordinates for @area the `GtkCellRenderer`State for @area in this row. This should be called by the @area’s owning layout widget when focus is to be passed to @area, or moved within @area for a given @direction and row data. Implementing `GtkCellArea` classes should implement this method to receive and navigate focus in its own way particular to how it lays out cells. %TRUE if focus remains inside @area as a result of this call. a `GtkCellArea` the `GtkDirectionType` Calls @callback for every `GtkCellRenderer` in @area. a `GtkCellArea` the `GtkCellCallback` to call user provided data pointer Calls @callback for every `GtkCellRenderer` in @area with the allocated rectangle inside @cell_area. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the @widget relative coordinates and size for @area the @widget relative coordinates of the background area the `GtkCellAllocCallback` to call user provided data pointer Derives the allocation of @renderer inside @area if @area were to be rendered in @cell_area. a `GtkCellArea` the `GtkCellArea`Context used to hold sizes for @area. the `GtkWidget` that @area is rendering on the `GtkCellRenderer` to get the allocation for the whole allocated area for @area in @widget for this row where to store the allocation for @renderer Gets the `GtkCellRenderer` at @x and @y coordinates inside @area and optionally returns the full cell allocation for it inside @cell_area. the `GtkCellRenderer` at @x and @y. a `GtkCellArea` the `GtkCellArea`Context used to hold sizes for @area. the `GtkWidget` that @area is rendering on the whole allocated area for @area in @widget for this row the x position the y position where to store the inner allocated area of the returned cell renderer Gets the current `GtkTreePath` string for the currently applied `GtkTreeIter`, this is implicitly updated when gtk_cell_area_apply_attributes() is called and can be used to interact with renderers from `GtkCellArea` subclasses. The current `GtkTreePath` string for the current attributes applied to @area. This string belongs to the area and should not be freed. a `GtkCellArea` Gets the `GtkCellEditable` widget currently used to edit the currently edited cell. The currently active `GtkCellEditable` widget a `GtkCellArea` Gets the `GtkCellRenderer` in @area that is currently being edited. The currently edited `GtkCellRenderer` a `GtkCellArea` Retrieves the currently focused cell for @area the currently focused cell in @area. a `GtkCellArea` Gets the `GtkCellRenderer` which is expected to be focusable for which @renderer is, or may be a sibling. This is handy for `GtkCellArea` subclasses when handling events, after determining the renderer at the event location it can then chose to activate the focus cell for which the event cell may have been a sibling. the `GtkCellRenderer` for which @renderer is a sibling a `GtkCellArea` the `GtkCellRenderer` Gets the focus sibling cell renderers for @renderer. A `GList` of `GtkCellRenderer`s. The returned list is internal and should not be freed. a `GtkCellArea` the `GtkCellRenderer` expected to have focus Retrieves a cell area’s initial minimum and natural height. @area will store some geometrical information in @context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the @minimum_height and @natural_height of this call but rather to consult gtk_cell_area_context_get_preferred_height() after a series of requests. a `GtkCellArea` the `GtkCellArea`Context to perform this request with the `GtkWidget` where @area will be rendering location to store the minimum height location to store the natural height Retrieves a cell area’s minimum and natural height if it would be given the specified @width. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_width(). It’s important to perform a series of gtk_cell_area_get_preferred_width() requests with @context first and then call gtk_cell_area_get_preferred_height_for_width() on each cell area individually to get the height for width of each fully requested row. If at some point, the width of a single row changes, it should be requested with gtk_cell_area_get_preferred_width() again and then the full width of the requested rows checked again with gtk_cell_area_context_get_preferred_width(). a `GtkCellArea` the `GtkCellArea`Context which has already been requested for widths. the `GtkWidget` where @area will be rendering the width for which to check the height of this area location to store the minimum height location to store the natural height Retrieves a cell area’s initial minimum and natural width. @area will store some geometrical information in @context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the @minimum_width and @natural_width of this call but rather to consult gtk_cell_area_context_get_preferred_width() after a series of requests. a `GtkCellArea` the `GtkCellArea`Context to perform this request with the `GtkWidget` where @area will be rendering location to store the minimum width location to store the natural width Retrieves a cell area’s minimum and natural width if it would be given the specified @height. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_height(). It’s important to perform a series of gtk_cell_area_get_preferred_height() requests with @context first and then call gtk_cell_area_get_preferred_width_for_height() on each cell area individually to get the height for width of each fully requested row. If at some point, the height of a single row changes, it should be requested with gtk_cell_area_get_preferred_height() again and then the full height of the requested rows checked again with gtk_cell_area_context_get_preferred_height(). a `GtkCellArea` the `GtkCellArea`Context which has already been requested for widths. the `GtkWidget` where @area will be rendering the height for which to check the width of this area location to store the minimum width location to store the natural width Gets whether the area prefers a height-for-width layout or a width-for-height layout. The `GtkSizeRequestMode` preferred by @area. a `GtkCellArea` Checks if @area contains @renderer. %TRUE if @renderer is in the @area. a `GtkCellArea` the `GtkCellRenderer` to check This is a convenience function for `GtkCellArea` implementations to get the inner area where a given `GtkCellRenderer` will be rendered. It removes any padding previously added by gtk_cell_area_request_renderer(). a `GtkCellArea` the `GtkWidget` that @area is rendering onto the @widget relative coordinates where one of @area’s cells is to be placed the return location for the inner cell area Returns whether the area can do anything when activated, after applying new attributes to @area. whether @area can do anything when activated. a `GtkCellArea` Returns whether @sibling is one of @renderer’s focus siblings (see gtk_cell_area_add_focus_sibling()). %TRUE if @sibling is a focus sibling of @renderer a `GtkCellArea` the `GtkCellRenderer` expected to have focus the `GtkCellRenderer` to check against @renderer’s sibling list Removes @renderer from @area. a `GtkCellArea` the `GtkCellRenderer` to remove from @area Removes @sibling from @renderer’s focus sibling list (see gtk_cell_area_add_focus_sibling()). a `GtkCellArea` the `GtkCellRenderer` expected to have focus the `GtkCellRenderer` to remove from @renderer’s focus area This is a convenience function for `GtkCellArea` implementations to request size for cell renderers. It’s important to use this function to request size and then use gtk_cell_area_inner_cell_area() at render and event time since this function will add padding around the cell for focus painting. a `GtkCellArea` the `GtkCellRenderer` to request size for the `GtkOrientation` in which to request size the `GtkWidget` that @area is rendering onto the allocation contextual size to request for, or -1 if the base request for the orientation is to be returned. location to store the minimum size location to store the natural size Explicitly sets the currently focused cell to @renderer. This is generally called by implementations of `GtkCellAreaClass.focus()` or `GtkCellAreaClass.event()`, however it can also be used to implement functions such as gtk_tree_view_set_cursor_on_cell(). a `GtkCellArea` the `GtkCellRenderer` to give focus to Snapshots @area’s cells according to @area’s layout onto at the given coordinates. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the `GtkSnapshot` to draw to the @widget relative coordinates for @area’s background the @widget relative coordinates for @area the `GtkCellRenderer`State for @area in this row. whether @area should paint focus on focused cells for focused rows or not. Explicitly stops the editing of the currently edited cell. If @canceled is %TRUE, the currently edited cell renderer will emit the ::editing-canceled signal, otherwise the the ::editing-done signal will be emitted on the current edit widget. See gtk_cell_area_get_edited_cell() and gtk_cell_area_get_edit_widget(). a `GtkCellArea` whether editing was canceled. The widget currently editing the edited cell This property is read-only and only changes as a result of a call gtk_cell_area_activate_cell(). The cell in the area that is currently edited This property is read-only and only changes as a result of a call gtk_cell_area_activate_cell(). The cell in the area that currently has focus Indicates that editing has started on @renderer and that @editable should be added to the owning cell-layouting widget at @cell_area. the `GtkCellRenderer` that started the edited the `GtkCellEditable` widget to add the `GtkWidget` relative `GdkRectangle` coordinates where @editable should be added the `GtkTreePath` string this edit was initiated for This signal is emitted whenever applying attributes to @area from @model the `GtkTreeModel` to apply the attributes from the `GtkTreeIter` indicating which row to apply the attributes of whether the view shows children for this row whether the view is currently showing the children of this row Indicates that focus changed on this @area. This signal is emitted either as a result of focus handling or event handling. It's possible that the signal is emitted even if the currently focused renderer did not change, this is because focus may change to the same renderer in the same cell area for a different row of data. the `GtkCellRenderer` that has focus the current `GtkTreePath` string set for @area Indicates that editing finished on @renderer and that @editable should be removed from the owning cell-layouting widget. the `GtkCellRenderer` that finished editeding the `GtkCellEditable` widget to remove A cell area that renders GtkCellRenderers into a row or a column The `GtkCellAreaBox` renders cell renderers into a row or a column depending on its `GtkOrientation`. GtkCellAreaBox uses a notion of packing. Packing refers to adding cell renderers with reference to a particular position in a `GtkCellAreaBox`. There are two reference positions: the start and the end of the box. When the `GtkCellAreaBox` is oriented in the %GTK_ORIENTATION_VERTICAL orientation, the start is defined as the top of the box and the end is defined as the bottom. In the %GTK_ORIENTATION_HORIZONTAL orientation start is defined as the left side and the end is defined as the right side. Alignments of `GtkCellRenderer`s rendered in adjacent rows can be configured by configuring the `GtkCellAreaBox` align child cell property with gtk_cell_area_cell_set_property() or by specifying the "align" argument to gtk_cell_area_box_pack_start() and gtk_cell_area_box_pack_end(). List views use widgets for displaying their contents Creates a new `GtkCellAreaBox`. a newly created `GtkCellAreaBox` Gets the spacing added between cell renderers. the space added between cell renderers in @box. a `GtkCellAreaBox` Adds @renderer to @box, packed with reference to the end of @box. The @renderer is packed after (away from end of) any other `GtkCellRenderer` packed with reference to the end of @box. a `GtkCellAreaBox` the `GtkCellRenderer` to add whether @renderer should receive extra space when the area receives more than its natural size whether @renderer should be aligned in adjacent rows whether @renderer should have the same size in all rows Adds @renderer to @box, packed with reference to the start of @box. The @renderer is packed after any other `GtkCellRenderer` packed with reference to the start of @box. a `GtkCellAreaBox` the `GtkCellRenderer` to add whether @renderer should receive extra space when the area receives more than its natural size whether @renderer should be aligned in adjacent rows whether @renderer should have the same size in all rows Sets the spacing to add between cell renderers in @box. a `GtkCellAreaBox` the space to add between `GtkCellRenderer`s The amount of space to reserve between cells. adds a `GtkCellRenderer` to the area. a `GtkCellArea` the `GtkCellRenderer` to add to @area removes a `GtkCellRenderer` from the area. a `GtkCellArea` the `GtkCellRenderer` to remove from @area calls the `GtkCellCallback` function on every `GtkCellRenderer` in the area with the provided user data until the callback returns %TRUE. a `GtkCellArea` the `GtkCellCallback` to call user provided data pointer Calls the `GtkCellAllocCallback` function on every `GtkCellRenderer` in the area with the allocated area for the cell and the provided user data until the callback returns %TRUE. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the @widget relative coordinates and size for @area the @widget relative coordinates of the background area the `GtkCellAllocCallback` to call user provided data pointer Handle an event in the area, this is generally used to activate a cell at the event location for button events but can also be used to generically pass events to `GtkWidget`s drawn onto the area. %TRUE if the event was handled by @area. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the `GdkEvent` to handle the @widget relative coordinates for @area the `GtkCellRenderer`State for @area in this row. Actually snapshot the area’s cells to the specified rectangle, @background_area should be correctly distributed to the cells corresponding background areas. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the `GtkSnapshot` to draw to the @widget relative coordinates for @area’s background the @widget relative coordinates for @area the `GtkCellRenderer`State for @area in this row. whether @area should paint focus on focused cells for focused rows or not. Apply the cell attributes to the cells. This is implemented as a signal and generally `GtkCellArea` subclasses don't need to implement it since it is handled by the base class. a `GtkCellArea` the `GtkTreeModel` to pull values from the `GtkTreeIter` in @tree_model to apply values for whether @iter has children whether @iter is expanded in the view and children are visible Creates and returns a class specific `GtkCellAreaContext` to store cell alignment and allocation details for a said `GtkCellArea` class. a newly created `GtkCellArea`Context which can be used with @area. a `GtkCellArea` Creates a new `GtkCellAreaContext` in the same state as the passed @context with any cell alignment data and allocations intact. a newly created `GtkCellArea`Context copy of @context. a `GtkCellArea` the `GtkCellArea`Context to copy This allows an area to tell its layouting widget whether it prefers to be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. The `GtkSizeRequestMode` preferred by @area. a `GtkCellArea` Calculates the minimum and natural width of the areas cells with the current attributes applied while considering the particular layouting details of the said `GtkCellArea`. While requests are performed over a series of rows, alignments and overall minimum and natural sizes should be stored in the corresponding `GtkCellAreaContext`. a `GtkCellArea` the `GtkCellArea`Context to perform this request with the `GtkWidget` where @area will be rendering location to store the minimum width location to store the natural width Calculates the minimum and natural height for the area if the passed @context would be allocated the given width. When implementing this virtual method it is safe to assume that @context has already stored the aligned cell widths for every `GtkTreeModel` row that @context will be allocated for since this information was stored at `GtkCellAreaClass.get_preferred_width()` time. This virtual method should also store any necessary alignments of cell heights for the case that the context is allocated a height. a `GtkCellArea` the `GtkCellArea`Context which has already been requested for widths. the `GtkWidget` where @area will be rendering the width for which to check the height of this area location to store the minimum height location to store the natural height Calculates the minimum and natural height of the areas cells with the current attributes applied. Essentially this is the same as `GtkCellAreaClass.get_preferred_width()` only for areas that are being requested as %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT. a `GtkCellArea` the `GtkCellArea`Context to perform this request with the `GtkWidget` where @area will be rendering location to store the minimum height location to store the natural height Calculates the minimum and natural width for the area if the passed @context would be allocated the given height. The same as `GtkCellAreaClass.get_preferred_height_for_width()` only for handling requests in the %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. a `GtkCellArea` the `GtkCellArea`Context which has already been requested for widths. the `GtkWidget` where @area will be rendering the height for which to check the width of this area location to store the minimum width location to store the natural width This should be implemented to handle changes in child cell properties for a given `GtkCellRenderer` that were previously installed on the `GtkCellAreaClass` with gtk_cell_area_class_install_cell_property(). This should be implemented to report the values of child cell properties for a given child `GtkCellRenderer`. This virtual method should be implemented to navigate focus from cell to cell inside the `GtkCellArea`. The `GtkCellArea` should move focus from cell to cell inside the area and return %FALSE if focus logically leaves the area with the following exceptions: When the area contains no activatable cells, the entire area receives focus. Focus should not be given to cells that are actually “focus siblings” of other sibling cells (see gtk_cell_area_get_focus_from_sibling()). Focus is set by calling gtk_cell_area_set_focus_cell(). %TRUE if focus remains inside @area as a result of this call. a `GtkCellArea` the `GtkDirectionType` Returns whether the `GtkCellArea` can respond to `GtkCellAreaClass.activate()`, usually this does not need to be implemented since the base class takes care of this however it can be enhanced if the `GtkCellArea` subclass can handle activation in other ways than activating its `GtkCellRenderers`. whether @area can do anything when activated. a `GtkCellArea` This is called when the layouting widget rendering the `GtkCellArea` activates the focus cell (see gtk_cell_area_get_focus_cell()). Whether @area was successfully activated. a `GtkCellArea` the `GtkCellArea`Context in context with the current row data the `GtkWidget` that @area is rendering on the size and location of @area relative to @widget’s allocation the `GtkCellRenderer`State flags for @area for this row of data. if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated. Finds a cell property of a cell area class by name. the `GParamSpec` of the child property a `GtkCellAreaClass` the name of the child property to find Installs a cell property on a cell area class. a `GtkCellAreaClass` the id for the property the `GParamSpec` for the property Returns all cell properties of a cell area class. a newly allocated %NULL-terminated array of `GParamSpec`*. The array must be freed with g_free(). a `GtkCellAreaClass` location to return the number of cell properties found Stores geometrical information for a series of rows in a GtkCellArea The `GtkCellAreaContext` object is created by a given `GtkCellArea` implementation via its `GtkCellAreaClass.create_context()` virtual method and is used to store cell sizes and alignments for a series of `GtkTreeModel` rows that are requested and rendered in the same context. `GtkCellLayout` widgets can create any number of contexts in which to request and render groups of data rows. However, it’s important that the same context which was used to request sizes for a given `GtkTreeModel` row also be used for the same row when calling other `GtkCellArea` APIs such as gtk_cell_area_render() and gtk_cell_area_event(). This object will be removed in GTK 5 Allocates a width and/or a height for all rows which are to be rendered with @context. Usually allocation is performed only horizontally or sometimes vertically since a group of rows are usually rendered side by side vertically or horizontally and share either the same width or the same height. Sometimes they are allocated in both horizontal and vertical orientations producing a homogeneous effect of the rows. This is generally the case for `GtkTreeView` when `GtkTreeView:fixed-height-mode` is enabled. This object will be removed in GTK 5 a `GtkCellAreaContext` the allocated width for all `GtkTreeModel` rows rendered with @context, or -1 the allocated height for all `GtkTreeModel` rows rendered with @context, or -1 Gets the accumulative preferred height for @width for all rows which have been requested for the same said @width with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a `GtkCellArea`, the returned values are -1. This object will be removed in GTK 5 a `GtkCellAreaContext` a proposed width for allocation location to store the minimum height location to store the natural height Gets the accumulative preferred width for @height for all rows which have been requested for the same said @height with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a `GtkCellArea`, the returned values are -1. This object will be removed in GTK 5 a `GtkCellAreaContext` a proposed height for allocation location to store the minimum width location to store the natural width Resets any previously cached request and allocation data. When underlying `GtkTreeModel` data changes its important to reset the context if the content size is allowed to shrink. If the content size is only allowed to grow (this is usually an option for views rendering large data stores as a measure of optimization), then only the row that changed or was inserted needs to be (re)requested with gtk_cell_area_get_preferred_width(). When the new overall size of the context requires that the allocated size changes (or whenever this allocation changes at all), the variable row sizes need to be re-requested for every row. For instance, if the rows are displayed all with the same width from top to bottom then a change in the allocated width necessitates a recalculation of all the displayed row heights using gtk_cell_area_get_preferred_height_for_width(). This object will be removed in GTK 5 a `GtkCellAreaContext` Allocates a width and/or a height for all rows which are to be rendered with @context. Usually allocation is performed only horizontally or sometimes vertically since a group of rows are usually rendered side by side vertically or horizontally and share either the same width or the same height. Sometimes they are allocated in both horizontal and vertical orientations producing a homogeneous effect of the rows. This is generally the case for `GtkTreeView` when `GtkTreeView:fixed-height-mode` is enabled. This object will be removed in GTK 5 a `GtkCellAreaContext` the allocated width for all `GtkTreeModel` rows rendered with @context, or -1 the allocated height for all `GtkTreeModel` rows rendered with @context, or -1 Fetches the current allocation size for @context. If the context was not allocated in width or height, or if the context was recently reset with gtk_cell_area_context_reset(), the returned value will be -1. This object will be removed in GTK 5 a `GtkCellAreaContext` location to store the allocated width location to store the allocated height Fetches the `GtkCellArea` this @context was created by. This is generally unneeded by layouting widgets; however, it is important for the context implementation itself to fetch information about the area it is being used for. For instance at `GtkCellAreaContextClass.allocate()` time it’s important to know details about any cell spacing that the `GtkCellArea` is configured with in order to compute a proper allocation. This object will be removed in GTK 5 the `GtkCellArea` this context was created by. a `GtkCellAreaContext` Gets the accumulative preferred height for all rows which have been requested with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a `GtkCellArea`, the returned values are 0. This object will be removed in GTK 5 a `GtkCellAreaContext` location to store the minimum height location to store the natural height Gets the accumulative preferred height for @width for all rows which have been requested for the same said @width with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a `GtkCellArea`, the returned values are -1. This object will be removed in GTK 5 a `GtkCellAreaContext` a proposed width for allocation location to store the minimum height location to store the natural height Gets the accumulative preferred width for all rows which have been requested with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a `GtkCellArea`, the returned values are 0. This object will be removed in GTK 5 a `GtkCellAreaContext` location to store the minimum width location to store the natural width Gets the accumulative preferred width for @height for all rows which have been requested for the same said @height with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a `GtkCellArea`, the returned values are -1. This object will be removed in GTK 5 a `GtkCellAreaContext` a proposed height for allocation location to store the minimum width location to store the natural width Causes the minimum and/or natural height to grow if the new proposed sizes exceed the current minimum and natural height. This is used by `GtkCellAreaContext` implementations during the request process over a series of `GtkTreeModel` rows to progressively push the requested height over a series of gtk_cell_area_get_preferred_height() requests. This object will be removed in GTK 5 a `GtkCellAreaContext` the proposed new minimum height for @context the proposed new natural height for @context Causes the minimum and/or natural width to grow if the new proposed sizes exceed the current minimum and natural width. This is used by `GtkCellAreaContext` implementations during the request process over a series of `GtkTreeModel` rows to progressively push the requested width over a series of gtk_cell_area_get_preferred_width() requests. This object will be removed in GTK 5 a `GtkCellAreaContext` the proposed new minimum width for @context the proposed new natural width for @context Resets any previously cached request and allocation data. When underlying `GtkTreeModel` data changes its important to reset the context if the content size is allowed to shrink. If the content size is only allowed to grow (this is usually an option for views rendering large data stores as a measure of optimization), then only the row that changed or was inserted needs to be (re)requested with gtk_cell_area_get_preferred_width(). When the new overall size of the context requires that the allocated size changes (or whenever this allocation changes at all), the variable row sizes need to be re-requested for every row. For instance, if the rows are displayed all with the same width from top to bottom then a change in the allocated width necessitates a recalculation of all the displayed row heights using gtk_cell_area_get_preferred_height_for_width(). This object will be removed in GTK 5 a `GtkCellAreaContext` The `GtkCellArea` this context was created by This object will be removed in GTK 5 The minimum height for the `GtkCellArea` in this context for all `GtkTreeModel` rows that this context was requested for using gtk_cell_area_get_preferred_height(). This object will be removed in GTK 5 The minimum width for the `GtkCellArea` in this context for all `GtkTreeModel` rows that this context was requested for using gtk_cell_area_get_preferred_width(). This object will be removed in GTK 5 The natural height for the `GtkCellArea` in this context for all `GtkTreeModel` rows that this context was requested for using gtk_cell_area_get_preferred_height(). This object will be removed in GTK 5 The natural width for the `GtkCellArea` in this context for all `GtkTreeModel` rows that this context was requested for using gtk_cell_area_get_preferred_width(). This object will be removed in GTK 5 This tells the context that an allocation width or height (or both) have been decided for a group of rows. The context should store any allocations for internally aligned cells at this point so that they dont need to be recalculated at gtk_cell_area_render() time. a `GtkCellAreaContext` the allocated width for all `GtkTreeModel` rows rendered with @context, or -1 the allocated height for all `GtkTreeModel` rows rendered with @context, or -1 Clear any previously stored information about requested and allocated sizes for the context. a `GtkCellAreaContext` Returns the aligned height for the given width that context must store while collecting sizes for it’s rows. a `GtkCellAreaContext` a proposed width for allocation location to store the minimum height location to store the natural height Returns the aligned width for the given height that context must store while collecting sizes for it’s rows. a `GtkCellAreaContext` a proposed height for allocation location to store the minimum width location to store the natural width The type of the callback functions used for iterating over the cell renderers of a `GtkCellArea`, see gtk_cell_area_foreach(). There is no replacement %TRUE to stop iterating over cells. the cell renderer to operate on user-supplied data Interface for widgets that can be used for editing cells The `GtkCellEditable` interface must be implemented for widgets to be usable to edit the contents of a `GtkTreeView` cell. It provides a way to specify how temporary widgets should be configured for editing, get the new value, etc. List views use widgets for displaying their contents. See [iface@Gtk.Editable] for editable text widgets Emits the `GtkCellEditable::editing-done` signal. A `GtkCellEditable` Emits the `GtkCellEditable::remove-widget` signal. A `GtkCellEditable` Begins editing on a @cell_editable. The `GtkCellRenderer` for the cell creates and returns a `GtkCellEditable` from gtk_cell_renderer_start_editing(), configured for the `GtkCellRenderer` type. gtk_cell_editable_start_editing() can then set up @cell_editable suitably for editing a cell, e.g. making the Esc key emit `GtkCellEditable::editing-done`. Note that the @cell_editable is created on-demand for the current edit; its lifetime is temporary and does not persist across other edits and/or cells. A `GtkCellEditable` The `GdkEvent` that began the editing process, or %NULL if editing was initiated programmatically Emits the `GtkCellEditable::editing-done` signal. A `GtkCellEditable` Emits the `GtkCellEditable::remove-widget` signal. A `GtkCellEditable` Begins editing on a @cell_editable. The `GtkCellRenderer` for the cell creates and returns a `GtkCellEditable` from gtk_cell_renderer_start_editing(), configured for the `GtkCellRenderer` type. gtk_cell_editable_start_editing() can then set up @cell_editable suitably for editing a cell, e.g. making the Esc key emit `GtkCellEditable::editing-done`. Note that the @cell_editable is created on-demand for the current edit; its lifetime is temporary and does not persist across other edits and/or cells. A `GtkCellEditable` The `GdkEvent` that began the editing process, or %NULL if editing was initiated programmatically Indicates whether editing on the cell has been canceled. This signal is a sign for the cell renderer to update its value from the @cell_editable. Implementations of `GtkCellEditable` are responsible for emitting this signal when they are done editing, e.g. `GtkEntry` emits this signal when the user presses Enter. Typical things to do in a handler for ::editing-done are to capture the edited value, disconnect the @cell_editable from signals on the `GtkCellRenderer`, etc. gtk_cell_editable_editing_done() is a convenience method for emitting `GtkCellEditable::editing-done`. This signal is meant to indicate that the cell is finished editing, and the @cell_editable widget is being removed and may subsequently be destroyed. Implementations of `GtkCellEditable` are responsible for emitting this signal when they are done editing. It must be emitted after the `GtkCellEditable::editing-done` signal, to give the cell renderer a chance to update the cell's value before the widget is removed. gtk_cell_editable_remove_widget() is a convenience method for emitting `GtkCellEditable::remove-widget`. Signal is a sign for the cell renderer to update its value from the cell_editable. A `GtkCellEditable` Signal is meant to indicate that the cell is finished editing, and the widget may now be destroyed. A `GtkCellEditable` Begins editing on a cell_editable. A `GtkCellEditable` The `GdkEvent` that began the editing process, or %NULL if editing was initiated programmatically An interface for packing cells `GtkCellLayout` is an interface to be implemented by all objects which want to provide a `GtkTreeViewColumn` like API for packing cells, setting attributes and data funcs. One of the notable features provided by implementations of `GtkCellLayout` are attributes. Attributes let you set the properties in flexible ways. They can just be set to constant values like regular properties. But they can also be mapped to a column of the underlying tree model with gtk_cell_layout_set_attributes(), which means that the value of the attribute can change from cell to cell as they are rendered by the cell renderer. Finally, it is possible to specify a function with gtk_cell_layout_set_cell_data_func() that is called to determine the value of the attribute for each cell that is rendered. ## GtkCellLayouts as GtkBuildable Implementations of GtkCellLayout which also implement the GtkBuildable interface (`GtkCellView`, `GtkIconView`, `GtkComboBox`, `GtkEntryCompletion`, `GtkTreeViewColumn`) accept `GtkCellRenderer` objects as `<child>` elements in UI definitions. They support a custom `<attributes>` element for their children, which can contain multiple `<attribute>` elements. Each `<attribute>` element has a name attribute which specifies a property of the cell renderer; the content of the element is the attribute value. This is an example of a UI definition fragment specifying attributes: ```xml <object class="GtkCellView"> <child> <object class="GtkCellRendererText"/> <attributes> <attribute name="text">0</attribute> </attributes> </child> </object> ``` Furthermore for implementations of `GtkCellLayout` that use a `GtkCellArea` to lay out cells (all `GtkCellLayout`s in GTK use a `GtkCellArea`) [cell properties](class.CellArea.html#cell-properties) can also be defined in the format by specifying the custom `<cell-packing>` attribute which can contain multiple `<property>` elements. Here is a UI definition fragment specifying cell properties: ```xml <object class="GtkTreeViewColumn"> <child> <object class="GtkCellRendererText"/> <cell-packing> <property name="align">True</property> <property name="expand">False</property> </cell-packing> </child> </object> ``` ## Subclassing GtkCellLayout implementations When subclassing a widget that implements `GtkCellLayout` like `GtkIconView` or `GtkComboBox`, there are some considerations related to the fact that these widgets internally use a `GtkCellArea`. The cell area is exposed as a construct-only property by these widgets. This means that it is possible to e.g. do ```c GtkWIdget *combo = g_object_new (GTK_TYPE_COMBO_BOX, "cell-area", my_cell_area, NULL); ``` to use a custom cell area with a combo box. But construct properties are only initialized after instance `init()` functions have run, which means that using functions which rely on the existence of the cell area in your subclass `init()` function will cause the default cell area to be instantiated. In this case, a provided construct property value will be ignored (with a warning, to alert you to the problem). ```c static void my_combo_box_init (MyComboBox *b) { GtkCellRenderer *cell; cell = gtk_cell_renderer_pixbuf_new (); // The following call causes the default cell area for combo boxes, // a GtkCellAreaBox, to be instantiated gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (b), cell, FALSE); ... } GtkWidget * my_combo_box_new (GtkCellArea *area) { // This call is going to cause a warning about area being ignored return g_object_new (MY_TYPE_COMBO_BOX, "cell-area", area, NULL); } ``` If supporting alternative cell areas with your derived widget is not important, then this does not have to concern you. If you want to support alternative cell areas, you can do so by moving the problematic calls out of `init()` and into a `constructor()` for your class. List views use widgets to display their contents. See [class@Gtk.LayoutManager] for layout manager delegate objects Adds an attribute mapping to the list in @cell_layout. The @column is the column of the model to get a value from, and the @attribute is the property on @cell to be set from that value. So for example if column 2 of the model contains strings, you could have the “text” attribute of a `GtkCellRendererText` get its values from column 2. In this context "attribute" and "property" are used interchangeably. a `GtkCellLayout` a `GtkCellRenderer` a property on the renderer the column position on the model to get the attribute from Unsets all the mappings on all renderers on @cell_layout and removes all renderers from @cell_layout. a `GtkCellLayout` Clears all existing attributes previously set with gtk_cell_layout_set_attributes(). a `GtkCellLayout` a `GtkCellRenderer` to clear the attribute mapping on Returns the underlying `GtkCellArea` which might be @cell_layout if called on a `GtkCellArea` or might be %NULL if no `GtkCellArea` is used by @cell_layout. the cell area used by @cell_layout a `GtkCellLayout` Returns the cell renderers which have been added to @cell_layout. a list of cell renderers. The list, but not the renderers has been newly allocated and should be freed with g_list_free() when no longer needed. a `GtkCellLayout` Adds the @cell to the end of @cell_layout. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Note that reusing the same cell renderer is not supported. a `GtkCellLayout` a `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @cell_layout Packs the @cell into the beginning of @cell_layout. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Note that reusing the same cell renderer is not supported. a `GtkCellLayout` a `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @cell_layout Re-inserts @cell at @position. Note that @cell has already to be packed into @cell_layout for this to function properly. a `GtkCellLayout` a `GtkCellRenderer` to reorder new position to insert @cell at Sets the `GtkCellLayout`DataFunc to use for @cell_layout. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of @cell_layout’s cell renderer(s) as appropriate. @func may be %NULL to remove a previously set function. a `GtkCellLayout` a `GtkCellRenderer` the `GtkCellLayout`DataFunc to use user data for @func destroy notify for @func_data Adds an attribute mapping to the list in @cell_layout. The @column is the column of the model to get a value from, and the @attribute is the property on @cell to be set from that value. So for example if column 2 of the model contains strings, you could have the “text” attribute of a `GtkCellRendererText` get its values from column 2. In this context "attribute" and "property" are used interchangeably. a `GtkCellLayout` a `GtkCellRenderer` a property on the renderer the column position on the model to get the attribute from Unsets all the mappings on all renderers on @cell_layout and removes all renderers from @cell_layout. a `GtkCellLayout` Clears all existing attributes previously set with gtk_cell_layout_set_attributes(). a `GtkCellLayout` a `GtkCellRenderer` to clear the attribute mapping on Returns the underlying `GtkCellArea` which might be @cell_layout if called on a `GtkCellArea` or might be %NULL if no `GtkCellArea` is used by @cell_layout. the cell area used by @cell_layout a `GtkCellLayout` Returns the cell renderers which have been added to @cell_layout. a list of cell renderers. The list, but not the renderers has been newly allocated and should be freed with g_list_free() when no longer needed. a `GtkCellLayout` Adds the @cell to the end of @cell_layout. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Note that reusing the same cell renderer is not supported. a `GtkCellLayout` a `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @cell_layout Packs the @cell into the beginning of @cell_layout. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Note that reusing the same cell renderer is not supported. a `GtkCellLayout` a `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @cell_layout Re-inserts @cell at @position. Note that @cell has already to be packed into @cell_layout for this to function properly. a `GtkCellLayout` a `GtkCellRenderer` to reorder new position to insert @cell at Sets the attributes in the parameter list as the attributes of @cell_layout. See [method@Gtk.CellLayout.add_attribute] for more details. The attributes should be in attribute/column order, as in gtk_cell_layout_add_attribute(). All existing attributes are removed, and replaced with the new attributes. a `GtkCellLayout` a `GtkCellRenderer` a %NULL-terminated list of attributes Sets the `GtkCellLayout`DataFunc to use for @cell_layout. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of @cell_layout’s cell renderer(s) as appropriate. @func may be %NULL to remove a previously set function. a `GtkCellLayout` a `GtkCellRenderer` the `GtkCellLayout`DataFunc to use user data for @func destroy notify for @func_data A function which should set the value of @cell_layout’s cell renderer(s) as appropriate. There is no replacement a `GtkCellLayout` the cell renderer whose value is to be set the model a `GtkTreeIter` indicating the row to set the value for user data passed to gtk_cell_layout_set_cell_data_func() Packs the cell into the beginning of cell_layout. a `GtkCellLayout` a `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @cell_layout Adds the cell to the end of cell_layout. a `GtkCellLayout` a `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @cell_layout Unsets all the mappings on all renderers on cell_layout and removes all renderers from cell_layout. a `GtkCellLayout` Adds an attribute mapping to the list in cell_layout. a `GtkCellLayout` a `GtkCellRenderer` a property on the renderer the column position on the model to get the attribute from Sets the `GtkCellLayout`DataFunc to use for cell_layout. a `GtkCellLayout` a `GtkCellRenderer` the `GtkCellLayout`DataFunc to use user data for @func destroy notify for @func_data Clears all existing attributes previously set with gtk_cell_layout_set_attributes(). a `GtkCellLayout` a `GtkCellRenderer` to clear the attribute mapping on Re-inserts cell at position. a `GtkCellLayout` a `GtkCellRenderer` to reorder new position to insert @cell at Get the cell renderers which have been added to cell_layout. a list of cell renderers. The list, but not the renderers has been newly allocated and should be freed with g_list_free() when no longer needed. a `GtkCellLayout` Get the underlying `GtkCellArea` which might be cell_layout if called on a `GtkCellArea` or might be NULL if no `GtkCellArea` is used by cell_layout. the cell area used by @cell_layout a `GtkCellLayout` An object for rendering a single cell The `GtkCellRenderer` is a base class of a set of objects used for rendering a cell to a `cairo_t`. These objects are used primarily by the `GtkTreeView` widget, though they aren’t tied to them in any specific way. It is worth noting that `GtkCellRenderer` is not a `GtkWidget` and cannot be treated as such. The primary use of a `GtkCellRenderer` is for drawing a certain graphical elements on a `cairo_t`. Typically, one cell renderer is used to draw many cells on the screen. To this extent, it isn’t expected that a CellRenderer keep any permanent state around. Instead, any state is set just prior to use using `GObject`s property system. Then, the cell is measured using gtk_cell_renderer_get_preferred_size(). Finally, the cell is rendered in the correct location using gtk_cell_renderer_snapshot(). There are a number of rules that must be followed when writing a new `GtkCellRenderer`. First and foremost, it’s important that a certain set of properties will always yield a cell renderer of the same size, barring a style change. The `GtkCellRenderer` also has a number of generic properties that are expected to be honored by all children. Beyond merely rendering a cell, cell renderers can optionally provide active user interface elements. A cell renderer can be “activatable” like `GtkCellRenderer`Toggle, which toggles when it gets activated by a mouse click, or it can be “editable” like `GtkCellRenderer`Text, which allows the user to edit the text using a widget implementing the `GtkCellEditable` interface, e.g. `GtkEntry`. To make a cell renderer activatable or editable, you have to implement the `GtkCellRenderer`Class.activate or `GtkCellRenderer`Class.start_editing virtual functions, respectively. Many properties of `GtkCellRenderer` and its subclasses have a corresponding “set” property, e.g. “cell-background-set” corresponds to “cell-background”. These “set” properties reflect whether a property has been set or not. You should not set them independently. List views use widgets for displaying their contents Passes an activate event to the cell renderer for possible processing. Some cell renderers may use events; for example, `GtkCellRendererToggle` toggles when it gets a mouse click. %TRUE if the event was consumed/handled a `GtkCellRenderer` a `GdkEvent` widget that received the event widget-dependent string representation of the event location; e.g. for `GtkTreeView`, a string representation of `GtkTreePath` background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Signal gets emitted when the user cancels the process of editing a cell. Signal gets emitted when a cell starts to be edited. Gets the aligned area used by @cell inside @cell_area. Used for finding the appropriate edit and focus rectangle. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to render flags cell area which would be passed to gtk_cell_renderer_render() the return location for the space inside @cell_area that would actually be used to render. Retrieves a renderer’s natural size when rendered to @widget. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location to store the minimum size location to store the natural size Retrieves a cell renderers’s minimum and natural height if it were rendered to @widget with the specified @width. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to the size which is available for allocation location for storing the minimum size location for storing the preferred size Retrieves a renderer’s natural size when rendered to @widget. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location to store the minimum size location to store the natural size Retrieves a cell renderers’s minimum and natural width if it were rendered to @widget with the specified @height. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to the size which is available for allocation location for storing the minimum size location for storing the preferred size Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. The `GtkSizeRequestMode` preferred by this renderer. a `GtkCellRenderer` instance Invokes the virtual render function of the `GtkCellRenderer`. The three passed-in rectangles are areas in @cr. Most renderers will draw within @cell_area; the xalign, yalign, xpad, and ypad fields of the `GtkCellRenderer` should be honored with respect to @cell_area. @background_area includes the blank space around the cell, and also the area containing the tree expander; so the @background_area rectangles for all cells tile to cover the entire @window. a `GtkCellRenderer` a `GtkSnapshot` to draw to the widget owning @window entire cell area (including tree expanders and maybe padding on the sides) area normally rendered by a cell renderer flags that affect rendering Starts editing the contents of this @cell, through a new `GtkCellEditable` widget created by the `GtkCellRenderer`Class.start_editing virtual function. A new `GtkCellEditable` for editing this @cell, or %NULL if editing is not possible a `GtkCellRenderer` a `GdkEvent` widget that received the event widget-dependent string representation of the event location; e.g. for `GtkTreeView`, a string representation of `GtkTreePath` background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Passes an activate event to the cell renderer for possible processing. Some cell renderers may use events; for example, `GtkCellRendererToggle` toggles when it gets a mouse click. %TRUE if the event was consumed/handled a `GtkCellRenderer` a `GdkEvent` widget that received the event widget-dependent string representation of the event location; e.g. for `GtkTreeView`, a string representation of `GtkTreePath` background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Gets the aligned area used by @cell inside @cell_area. Used for finding the appropriate edit and focus rectangle. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to render flags cell area which would be passed to gtk_cell_renderer_render() the return location for the space inside @cell_area that would actually be used to render. Fills in @xalign and @yalign with the appropriate values of @cell. A `GtkCellRenderer` location to fill in with the x alignment of the cell location to fill in with the y alignment of the cell Fills in @width and @height with the appropriate size of @cell. A `GtkCellRenderer` location to fill in with the fixed width of the cell location to fill in with the fixed height of the cell Checks whether the given `GtkCellRenderer` is expanded. %TRUE if the cell renderer is expanded a `GtkCellRenderer` Checks whether the given `GtkCellRenderer` is an expander. %TRUE if @cell is an expander, and %FALSE otherwise a `GtkCellRenderer` Fills in @xpad and @ypad with the appropriate values of @cell. A `GtkCellRenderer` location to fill in with the x padding of the cell location to fill in with the y padding of the cell Retrieves a renderer’s natural size when rendered to @widget. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location to store the minimum size location to store the natural size Retrieves a cell renderers’s minimum and natural height if it were rendered to @widget with the specified @width. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to the size which is available for allocation location for storing the minimum size location for storing the preferred size Retrieves the minimum and natural size of a cell taking into account the widget’s preference for height-for-width management. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location for storing the minimum size location for storing the natural size Retrieves a renderer’s natural size when rendered to @widget. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location to store the minimum size location to store the natural size Retrieves a cell renderers’s minimum and natural width if it were rendered to @widget with the specified @height. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to the size which is available for allocation location for storing the minimum size location for storing the preferred size Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. The `GtkSizeRequestMode` preferred by this renderer. a `GtkCellRenderer` instance Returns the cell renderer’s sensitivity. %TRUE if the cell renderer is sensitive A `GtkCellRenderer` Translates the cell renderer state to `GtkStateFlags`, based on the cell renderer and widget sensitivity, and the given `GtkCellRenderer`State. the widget state flags applying to @cell a `GtkCellRenderer` a `GtkWidget` cell renderer state Returns the cell renderer’s visibility. %TRUE if the cell renderer is visible A `GtkCellRenderer` Checks whether the cell renderer can do something when activated. %TRUE if the cell renderer can do anything when activated A `GtkCellRenderer` Sets the renderer’s alignment within its available space. A `GtkCellRenderer` the x alignment of the cell renderer the y alignment of the cell renderer Sets the renderer size to be explicit, independent of the properties set. A `GtkCellRenderer` the width of the cell renderer, or -1 the height of the cell renderer, or -1 Sets whether the given `GtkCellRenderer` is expanded. a `GtkCellRenderer` whether @cell should be expanded Sets whether the given `GtkCellRenderer` is an expander. a `GtkCellRenderer` whether @cell is an expander Sets the renderer’s padding. A `GtkCellRenderer` the x padding of the cell renderer the y padding of the cell renderer Sets the cell renderer’s sensitivity. A `GtkCellRenderer` the sensitivity of the cell Sets the cell renderer’s visibility. A `GtkCellRenderer` the visibility of the cell Invokes the virtual render function of the `GtkCellRenderer`. The three passed-in rectangles are areas in @cr. Most renderers will draw within @cell_area; the xalign, yalign, xpad, and ypad fields of the `GtkCellRenderer` should be honored with respect to @cell_area. @background_area includes the blank space around the cell, and also the area containing the tree expander; so the @background_area rectangles for all cells tile to cover the entire @window. a `GtkCellRenderer` a `GtkSnapshot` to draw to the widget owning @window entire cell area (including tree expanders and maybe padding on the sides) area normally rendered by a cell renderer flags that affect rendering Starts editing the contents of this @cell, through a new `GtkCellEditable` widget created by the `GtkCellRenderer`Class.start_editing virtual function. A new `GtkCellEditable` for editing this @cell, or %NULL if editing is not possible a `GtkCellRenderer` a `GdkEvent` widget that received the event widget-dependent string representation of the event location; e.g. for `GtkTreeView`, a string representation of `GtkTreePath` background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Informs the cell renderer that the editing is stopped. If @canceled is %TRUE, the cell renderer will emit the `GtkCellRenderer`::editing-canceled signal. This function should be called by cell renderer implementations in response to the `GtkCellEditable::editing-done` signal of `GtkCellEditable`. A `GtkCellRenderer` %TRUE if the editing has been canceled Cell background as a `GdkRGBA` This signal gets emitted when the user cancels the process of editing a cell. For example, an editable cell renderer could be written to cancel editing when the user presses Escape. See also: gtk_cell_renderer_stop_editing(). This signal gets emitted when a cell starts to be edited. The intended use of this signal is to do special setup on @editable, e.g. adding a `GtkEntryCompletion` or setting up additional columns in a `GtkComboBox`. See gtk_cell_editable_start_editing() for information on the lifecycle of the @editable and a way to do setup that doesn’t depend on the @renderer. Note that GTK doesn't guarantee that cell renderers will continue to use the same kind of widget for editing in future releases, therefore you should check the type of @editable before doing any specific setup, as in the following example: ```c static void text_editing_started (GtkCellRenderer *cell, GtkCellEditable *editable, const char *path, gpointer data) { if (GTK_IS_ENTRY (editable)) { GtkEntry *entry = GTK_ENTRY (editable); // ... create a GtkEntryCompletion gtk_entry_set_completion (entry, completion); } } ``` the `GtkCellEditable` the path identifying the edited cell Renders a keyboard accelerator in a cell `GtkCellRendererAccel` displays a keyboard accelerator (i.e. a key combination like `Control + a`). If the cell renderer is editable, the accelerator can be changed by simply typing the new combination. Applications editing keyboard accelerators should provide their own implementation according to platform design guidelines Creates a new `GtkCellRendererAccel`. the new cell renderer The keyval of the accelerator. Determines if the edited accelerators are GTK accelerators. If they are, consumed modifiers are suppressed, only accelerators accepted by GTK are allowed, and the accelerators are rendered in the same way as they are in menus. The modifier mask of the accelerator. The hardware keycode of the accelerator. Note that the hardware keycode is only relevant if the key does not have a keyval. Normally, the keyboard configuration should assign keyvals to all keys. Gets emitted when the user has removed the accelerator. the path identifying the row of the edited cell Gets emitted when the user has selected a new accelerator. the path identifying the row of the edited cell the new accelerator keyval the new accelerator modifier mask the keycode of the new accelerator The available modes for [property@Gtk.CellRendererAccel:accel-mode]. There is no replacement GTK accelerators mode Other accelerator mode Called to gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. The `GtkSizeRequestMode` preferred by this renderer. a `GtkCellRenderer` instance Called to get a renderer’s natural width. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location to store the minimum size location to store the natural size Called to get a renderer’s natural height for width. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to the size which is available for allocation location for storing the minimum size location for storing the preferred size Called to get a renderer’s natural height. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location to store the minimum size location to store the natural size Called to get a renderer’s natural width for height. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to the size which is available for allocation location for storing the minimum size location for storing the preferred size Called to get the aligned area used by @cell inside @cell_area. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to render flags cell area which would be passed to gtk_cell_renderer_render() the return location for the space inside @cell_area that would actually be used to render. Called to snapshot the content of the `GtkCellRenderer`. a `GtkCellRenderer` a `GtkSnapshot` to draw to the widget owning @window entire cell area (including tree expanders and maybe padding on the sides) area normally rendered by a cell renderer flags that affect rendering Called to activate the content of the `GtkCellRenderer`. %TRUE if the event was consumed/handled a `GtkCellRenderer` a `GdkEvent` widget that received the event widget-dependent string representation of the event location; e.g. for `GtkTreeView`, a string representation of `GtkTreePath` background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Called to initiate editing the content of the `GtkCellRenderer`. A new `GtkCellEditable` for editing this @cell, or %NULL if editing is not possible a `GtkCellRenderer` a `GdkEvent` widget that received the event widget-dependent string representation of the event location; e.g. for `GtkTreeView`, a string representation of `GtkTreePath` background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Signal gets emitted when the user cancels the process of editing a cell. Signal gets emitted when a cell starts to be edited. Renders a combobox in a cell `GtkCellRendererCombo` renders text in a cell like `GtkCellRendererText` from which it is derived. But while `GtkCellRendererText` offers a simple entry to edit the text, `GtkCellRendererCombo` offers a `GtkComboBox` widget to edit the text. The values to display in the combo box are taken from the tree model specified in the `GtkCellRendererCombo`:model property. The combo cell renderer takes care of adding a text cell renderer to the combo box and sets it to display the column specified by its `GtkCellRendererCombo`:text-column property. Further properties of the combo box can be set in a handler for the `GtkCellRenderer::editing-started` signal. List views use widgets to display their contents. You should use [class@Gtk.DropDown] instead Creates a new `GtkCellRendererCombo`. Adjust how text is drawn using object properties. Object properties can be set globally (with g_object_set()). Also, with `GtkTreeViewColumn`, you can bind a property to a value in a `GtkTreeModel`. For example, you can bind the “text” property on the cell renderer to a string value in the model, thus rendering a different string in each row of the `GtkTreeView`. the new cell renderer If %TRUE, the cell renderer will include an entry and allow to enter values other than the ones in the popup list. Holds a tree model containing the possible values for the combo box. Use the text_column property to specify the column holding the values. Specifies the model column which holds the possible values for the combo box. Note that this refers to the model specified in the model property, not the model backing the tree view to which this cell renderer is attached. `GtkCellRendererCombo` automatically adds a text cell renderer for this column to its combo box. This signal is emitted each time after the user selected an item in the combo box, either by using the mouse or the arrow keys. Contrary to GtkComboBox, GtkCellRendererCombo::changed is not emitted for changes made to a selected item in the entry. The argument @new_iter corresponds to the newly selected item in the combo box and it is relative to the GtkTreeModel set via the model property on GtkCellRendererCombo. Note that as soon as you change the model displayed in the tree view, the tree view will immediately cease the editing operating. This means that you most probably want to refrain from changing the model until the combo cell renderer emits the edited or editing_canceled signal. a string of the path identifying the edited cell (relative to the tree view model) the new iter selected in the combo box (relative to the combo box model) Identifies how the user can interact with a particular cell. There is no replacement. The cell is just for display and cannot be interacted with. Note that this doesn’t mean that eg. the row being drawn can’t be selected -- just that a particular element of it cannot be individually modified. The cell can be clicked. The cell can be edited or otherwise modified. Renders a pixbuf in a cell A `GtkCellRendererPixbuf` can be used to render an image in a cell. It allows to render either a given `GdkPixbuf` (set via the `GtkCellRendererPixbuf:pixbuf` property) or a named icon (set via the `GtkCellRendererPixbuf:icon-name` property). To support the tree view, `GtkCellRendererPixbuf` also supports rendering two alternative pixbufs, when the `GtkCellRenderer:is-expander` property is %TRUE. If the `GtkCellRenderer:is-expanded property` is %TRUE and the `GtkCellRendererPixbuf:pixbuf-expander-open` property is set to a pixbuf, it renders that pixbuf, if the `GtkCellRenderer:is-expanded` property is %FALSE and the `GtkCellRendererPixbuf:pixbuf-expander-closed` property is set to a pixbuf, it renders that one. List views use widgets to display their contents. You should use [class@Gtk.Image] for icons, and [class@Gtk.Picture] for images Creates a new `GtkCellRendererPixbuf`. Adjust rendering parameters using object properties. Object properties can be set globally (with g_object_set()). Also, with `GtkTreeViewColumn`, you can bind a property to a value in a `GtkTreeModel`. For example, you can bind the “pixbuf” property on the cell renderer to a pixbuf value in the model, thus rendering a different image in each row of the `GtkTreeView`. the new cell renderer The GIcon representing the icon to display. If the icon theme is changed, the image will be updated automatically. The name of the themed icon to display. This property only has an effect if not overridden by the "pixbuf" property. The `GtkIconSize` value that specifies the size of the rendered icon. Renders numbers as progress bars `GtkCellRendererProgress` renders a numeric value as a progress par in a cell. Additionally, it can display a text on top of the progress bar. List views use widgets to display their contents. You should use [class@Gtk.ProgressBar] instead Creates a new `GtkCellRendererProgress`. the new cell renderer Whether progess is inverted. Setting this to a non-negative value causes the cell renderer to enter "activity mode", where a block bounces back and forth to indicate that some progress is made, without specifying exactly how much. Each increment of the property causes the block to move by a little bit. To indicate that the activity has not started yet, set the property to zero. To indicate completion, set the property to %G_MAXINT. The "text" property determines the label which will be drawn over the progress bar. Setting this property to %NULL causes the default label to be displayed. Setting this property to an empty string causes no label to be displayed. The "text-xalign" property controls the horizontal alignment of the text in the progress bar. Valid values range from 0 (left) to 1 (right). Reserved for RTL layouts. The "text-yalign" property controls the vertical alignment of the text in the progress bar. Valid values range from 0 (top) to 1 (bottom). The "value" property determines the percentage to which the progress bar will be "filled in". Renders a spin button in a cell `GtkCellRendererSpin` renders text in a cell like `GtkCellRendererText` from which it is derived. But while `GtkCellRendererText` offers a simple entry to edit the text, `GtkCellRendererSpin` offers a `GtkSpinButton` widget. Of course, that means that the text has to be parseable as a floating point number. The range of the spinbutton is taken from the adjustment property of the cell renderer, which can be set explicitly or mapped to a column in the tree model, like all properties of cell renders. `GtkCellRendererSpin` also has properties for the `GtkCellRendererSpin:climb-rate` and the number of `GtkCellRendererSpin:digits` to display. Other `GtkSpinButton` properties can be set in a handler for the `GtkCellRenderer::editing-started` signal. List views use widgets to display their contents. You should use [class@Gtk.SpinButton] instead Creates a new `GtkCellRendererSpin`. a new `GtkCellRendererSpin` The adjustment that holds the value of the spinbutton. This must be non-%NULL for the cell renderer to be editable. The acceleration rate when you hold down a button. The number of decimal places to display. Renders a spinning animation in a cell `GtkCellRendererSpinner` renders a spinning animation in a cell, very similar to `GtkSpinner`. It can often be used as an alternative to a `GtkCellRendererProgress` for displaying indefinite activity, instead of actual progress. To start the animation in a cell, set the `GtkCellRendererSpinner:active` property to %TRUE and increment the `GtkCellRendererSpinner:pulse` property at regular intervals. The usual way to set the cell renderer properties for each cell is to bind them to columns in your tree model using e.g. gtk_tree_view_column_add_attribute(). List views use widgets to display their contents. You should use [class@Gtk.Spinner] instead Returns a new cell renderer which will show a spinner to indicate activity. a new `GtkCellRenderer` Whether the spinner is active (ie. shown) in the cell Pulse of the spinner. Increment this value to draw the next frame of the spinner animation. Usually, you would update this value in a timeout. By default, the `GtkSpinner` widget draws one full cycle of the animation, consisting of 12 frames, in 750 milliseconds. The `GtkIconSize` value that specifies the size of the rendered spinner. Tells how a cell is to be rendered. There is no replacement. The cell is currently selected, and probably has a selection colored background to render to. The mouse is hovering over the cell. The cell is drawn in an insensitive manner The cell is in a sorted row The cell is in the focus row. The cell is in a row that can be expanded The cell is in a row that is expanded Renders text in a cell A `GtkCellRendererText` renders a given text in its cell, using the font, color and style information provided by its properties. The text will be ellipsized if it is too long and the `GtkCellRendererText:ellipsize` property allows it. If the `GtkCellRenderer:mode` is %GTK_CELL_RENDERER_MODE_EDITABLE, the `GtkCellRendererText` allows to edit its text using an entry. List views use widgets to display their contents. You should use [class@Gtk.Inscription] or [class@Gtk.Label] instead Creates a new `GtkCellRendererText`. Adjust how text is drawn using object properties. Object properties can be set globally (with g_object_set()). Also, with `GtkTreeViewColumn`, you can bind a property to a value in a `GtkTreeModel`. For example, you can bind the “text” property on the cell renderer to a string value in the model, thus rendering a different string in each row of the `GtkTreeView`. the new cell renderer Sets the height of a renderer to explicitly be determined by the “font” and “y_pad” property set on it. Further changes in these properties do not affect the height, so they must be accompanied by a subsequent call to this function. Using this function is inflexible, and should really only be used if calculating the size of a cell is too slow (ie, a massive number of cells displayed). If @number_of_rows is -1, then the fixed height is unset, and the height is determined by the properties again. A `GtkCellRendererText` Number of rows of text each cell renderer is allocated, or -1 Specifies how to align the lines of text with respect to each other. Note that this property describes how to align the lines of text in case there are several of them. The "xalign" property of `GtkCellRenderer`, on the other hand, sets the horizontal alignment of the whole text. Background color as a `GdkRGBA` Specifies the preferred place to ellipsize the string, if the cell renderer does not have enough room to display the entire string. Setting it to %PANGO_ELLIPSIZE_NONE turns off ellipsizing. See the wrap-width property for another way of making the text fit into a given width. Foreground color as a `GdkRGBA` The desired maximum width of the cell, in characters. If this property is set to -1, the width will be calculated automatically. For cell renderers that ellipsize or wrap text; this property controls the maximum reported width of the cell. The cell should not receive any greater allocation unless it is set to expand in its `GtkCellLayout` and all of the cell's siblings have received their natural width. The text that will be displayed in the `GtkCellRenderer` if `GtkCellRendererText:editable` is %TRUE and the cell is empty. The desired width of the cell, in characters. If this property is set to -1, the width will be calculated automatically, otherwise the cell will request either 3 characters or the property value, whichever is greater. Specifies how to break the string into multiple lines, if the cell renderer does not have enough room to display the entire string. This property has no effect unless the wrap-width property is set. Specifies the minimum width at which the text is wrapped. The wrap-mode property can be used to influence at what character positions the line breaks can be placed. Setting wrap-width to -1 turns wrapping off. This signal is emitted after @renderer has been edited. It is the responsibility of the application to update the model and store @new_text at the position indicated by @path. the path identifying the edited cell the new text Renders a toggle button in a cell `GtkCellRendererToggle` renders a toggle button in a cell. The button is drawn as a radio or a checkbutton, depending on the `GtkCellRendererToggle:radio` property. When activated, it emits the `GtkCellRendererToggle::toggled` signal. List views use widgets to display their contents. You should use [class@Gtk.ToggleButton] instead Creates a new `GtkCellRendererToggle`. Adjust rendering parameters using object properties. Object properties can be set globally (with g_object_set()). Also, with `GtkTreeViewColumn`, you can bind a property to a value in a `GtkTreeModel`. For example, you can bind the “active” property on the cell renderer to a boolean value in the model, thus causing the check button to reflect the state of the model. the new cell renderer Returns whether the cell renderer is activatable. See gtk_cell_renderer_toggle_set_activatable(). %TRUE if the cell renderer is activatable. a `GtkCellRendererToggle` Returns whether the cell renderer is active. See gtk_cell_renderer_toggle_set_active(). %TRUE if the cell renderer is active. a `GtkCellRendererToggle` Returns whether we’re rendering radio toggles rather than checkboxes. %TRUE if we’re rendering radio toggles rather than checkboxes a `GtkCellRendererToggle` Makes the cell renderer activatable. a `GtkCellRendererToggle`. the value to set. Activates or deactivates a cell renderer. a `GtkCellRendererToggle`. the value to set. If @radio is %TRUE, the cell renderer renders a radio toggle (i.e. a toggle in a group of mutually-exclusive toggles). If %FALSE, it renders a check toggle (a standalone boolean option). This can be set globally for the cell renderer, or changed just before rendering each cell in the model (for `GtkTreeView`, you set up a per-row setting using `GtkTreeViewColumn` to associate model columns with cell renderer properties). a `GtkCellRendererToggle` %TRUE to make the toggle look like a radio button The ::toggled signal is emitted when the cell is toggled. It is the responsibility of the application to update the model with the correct value to store at @path. Often this is simply the opposite of the value currently stored at @path. string representation of `GtkTreePath` describing the event location A widget displaying a single row of a GtkTreeModel A `GtkCellView` displays a single row of a `GtkTreeModel` using a `GtkCellArea` and `GtkCellAreaContext`. A `GtkCellAreaContext` can be provided to the `GtkCellView` at construction time in order to keep the cellview in context of a group of cell views, this ensures that the renderers displayed will be properly aligned with each other (like the aligned cells in the menus of `GtkComboBox`). `GtkCellView` is `GtkOrientable` in order to decide in which orientation the underlying `GtkCellAreaContext` should be allocated. Taking the `GtkComboBox` menu as an example, cellviews should be oriented horizontally if the menus are listed top-to-bottom and thus all share the same width but may have separate individual heights (left-to-right menus should be allocated vertically since they all share the same height but may have variable widths). ## CSS nodes GtkCellView has a single CSS node with name cellview. List views use widgets to display their contents. You can use [class@Gtk.Box] instead Creates a new `GtkCellView` widget. A newly created `GtkCellView` widget. Creates a new `GtkCellView` widget with a specific `GtkCellArea` to layout cells and a specific `GtkCellAreaContext`. Specifying the same context for a handful of cells lets the underlying area synchronize the geometry for those cells, in this way alignments with cellviews for other rows are possible. A newly created `GtkCellView` widget. the `GtkCellArea` to layout cells the `GtkCellAreaContext` in which to calculate cell geometry Creates a new `GtkCellView` widget, adds a `GtkCellRendererText` to it, and makes it show @markup. The text can be marked up with the [Pango text markup language](https://docs.gtk.org/Pango/pango_markup.html). A newly created `GtkCellView` widget. the text to display in the cell view Creates a new `GtkCellView` widget, adds a `GtkCellRendererText` to it, and makes it show @text. A newly created `GtkCellView` widget. the text to display in the cell view Creates a new `GtkCellView` widget, adds a `GtkCellRendererPixbuf` to it, and makes it show @texture. A newly created `GtkCellView` widget. the image to display in the cell view Returns a `GtkTreePath` referring to the currently displayed row. If no row is currently displayed, %NULL is returned. the currently displayed row a `GtkCellView` Gets whether @cell_view is configured to draw all of its cells in a sensitive state. whether @cell_view draws all of its cells in a sensitive state a `GtkCellView` Gets whether @cell_view is configured to request space to fit the entire `GtkTreeModel`. whether @cell_view requests space to fit the entire `GtkTreeModel`. a `GtkCellView` Returns the model for @cell_view. If no model is used %NULL is returned. a `GtkTreeModel` used a `GtkCellView` Sets the row of the model that is currently displayed by the `GtkCellView`. If the path is unset, then the contents of the cellview “stick” at their last value; this is not normally a desired result, but may be a needed intermediate state if say, the model for the `GtkCellView` becomes temporarily empty. a `GtkCellView` a `GtkTreePath` or %NULL to unset. Sets whether @cell_view should draw all of its cells in a sensitive state, this is used by `GtkComboBox` menus to ensure that rows with insensitive cells that contain children appear sensitive in the parent menu item. a `GtkCellView` whether to draw all cells in a sensitive state. Sets whether @cell_view should request space to fit the entire `GtkTreeModel`. This is used by `GtkComboBox` to ensure that the cell view displayed on the combo box’s button always gets enough space and does not resize when selection changes. a `GtkCellView` whether @cell_view should request space for the whole model. Sets the model for @cell_view. If @cell_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. a `GtkCellView` a `GtkTreeModel` The `GtkCellArea` rendering cells If no area is specified when creating the cell view with gtk_cell_view_new_with_context() a horizontally oriented `GtkCellArea`Box will be used. since 3.0 The `GtkCellAreaContext` used to compute the geometry of the cell view. A group of cell views can be assigned the same context in order to ensure the sizes and cell alignments match across all the views with the same context. `GtkComboBox` menus uses this to assign the same context to all cell views in the menu items for a single menu (each submenu creates its own context since the size of each submenu does not depend on parent or sibling menus). since 3.0 Whether all cells should be draw as sensitive for this view regardless of the actual cell properties (used to make menus with submenus appear sensitive when the items in submenus might be insensitive). since 3.0 Whether the view should request enough space to always fit the size of every row in the model (used by the combo box to ensure the combo box size doesn't change when different items are selected). since 3.0 The model for cell view since 2.10 Arranges three children in a row, keeping the middle child centered as well as possible. <picture> <source srcset="centerbox-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkCenterBox" src="centerbox.png"> </picture> To add children to `GtkCenterBox`, use [method@Gtk.CenterBox.set_start_widget], [method@Gtk.CenterBox.set_center_widget] and [method@Gtk.CenterBox.set_end_widget]. The sizing and positioning of children can be influenced with the align and expand properties of the children. # GtkCenterBox as GtkBuildable The `GtkCenterBox` implementation of the `GtkBuildable` interface supports placing children in the 3 positions by specifying “start”, “center” or “end” as the “type” attribute of a `<child>` element. # CSS nodes `GtkCenterBox` uses a single CSS node with the name “box”, The first child of the `GtkCenterBox` will be allocated depending on the text direction, i.e. in left-to-right layouts it will be allocated on the left and in right-to-left layouts on the right. In vertical orientation, the nodes of the children are arranged from top to bottom. # Accessibility Until GTK 4.10, `GtkCenterBox` used the [enum@Gtk.AccessibleRole.group] role. Starting from GTK 4.12, `GtkCenterBox` uses the [enum@Gtk.AccessibleRole.generic] role. Creates a new `GtkCenterBox`. the new `GtkCenterBox` Gets the baseline position of the center box. See [method@Gtk.CenterBox.set_baseline_position]. the baseline position a center box Gets the center widget. the center widget a center box Gets the end widget. the end widget a center box Gets whether the center widget shrinks after other children. whether to shrink the center widget after others a center box Gets the start widget. the start widget a center box Sets the baseline position of a center box. This affects only horizontal boxes with at least one baseline aligned child. If there is more vertical space available than requested, and the baseline is not allocated by the parent then @position is used to allocate the baseline with respect to the extra space available. a center box the baseline position Sets the center widget. To remove the existing center widget, pass `NULL`. a center box the new center widget Sets the end widget. To remove the existing end widget, pass `NULL`. a center box the new end widget Sets whether to shrink the center widget after other children. By default, when there's no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. If @shrink_center_last is false, start and end widgets keep natural width and the center widget starts shrinking instead. a cener box whether to shrink the center widget after others Sets the start widget. To remove the existing start widget, pass `NULL`. a center box the new start widget The position of the baseline aligned widget if extra space is available. The widget that is placed at the center position. The widget that is placed at the end position. In vertical orientation, the end position is at the bottom. In horizontal orientation, the end position is at the trailing edge with respect to the text direction. Whether to shrink the center widget after other children. By default, when there's no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. If false, start and end widgets keep natural width and the center widget starts shrinking instead. The widget that is placed at the start position. In vertical orientation, the start position is at the top. In horizontal orientation, the start position is at the leading edge with respect to the text direction. Manages up to three children. The start widget is allocated at the start of the layout (left in left-to-right locales and right in right-to-left ones), and the end widget at the end. The center widget is centered regarding the full width of the layout's. Creates a new `GtkCenterLayout`. the newly created `GtkCenterLayout` Returns the baseline position of the layout. The current baseline position of @self. a `GtkCenterLayout` Returns the center widget of the layout. the current center widget of @self a `GtkCenterLayout` Returns the end widget of the layout. the current end widget of @self a `GtkCenterLayout` Gets the current orienration of the layout manager. The current orientation of @self a `GtkCenterLayout` Gets whether @self shrinks the center widget after other children. whether to shrink the center widget after others a `GtkCenterLayout` Returns the start widget of the layout. The current start widget of @self a `GtkCenterLayout` Sets the new baseline position of @self a `GtkCenterLayout` the new baseline position Sets the new center widget of @self. To remove the existing center widget, pass %NULL. a `GtkCenterLayout` the new center widget Sets the new end widget of @self. To remove the existing center widget, pass %NULL. a `GtkCenterLayout` the new end widget Sets the orientation of @self. a `GtkCenterLayout` the new orientation Sets whether to shrink the center widget after other children. By default, when there's no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. If set to `FALSE`, start and end widgets keep natural width and the center widget starts shrinking instead. a `GtkCenterLayout` whether to shrink the center widget after others Sets the new start widget of @self. To remove the existing start widget, pass %NULL. a `GtkCenterLayout` the new start widget Whether to shrink the center widget after other children. By default, when there's no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. If set to `FALSE`, start and end widgets keep natural width and the center widget starts shrinking instead. Places a label next to an indicator. <picture> <source srcset="check-button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Example GtkCheckButtons" src="check-button.png"> </picture> A `GtkCheckButton` is created by calling either [ctor@Gtk.CheckButton.new] or [ctor@Gtk.CheckButton.new_with_label]. The state of a `GtkCheckButton` can be set specifically using [method@Gtk.CheckButton.set_active], and retrieved using [method@Gtk.CheckButton.get_active]. # Inconsistent state In addition to "on" and "off", check buttons can be an "in between" state that is neither on nor off. This can be used e.g. when the user has selected a range of elements (such as some text or spreadsheet cells) that are affected by a check button, and the current values in that range are inconsistent. To set a `GtkCheckButton` to inconsistent state, use [method@Gtk.CheckButton.set_inconsistent]. # Grouping Check buttons can be grouped together, to form mutually exclusive groups - only one of the buttons can be toggled at a time, and toggling another one will switch the currently toggled one off. Grouped check buttons use a different indicator, and are commonly referred to as *radio buttons*. <picture> <source srcset="radio-button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Example GtkRadioButtons" src="radio-button.png"> </picture> To add a `GtkCheckButton` to a group, use [method@Gtk.CheckButton.set_group]. When the code must keep track of the state of a group of radio buttons, it is recommended to keep track of such state through a stateful `GAction` with a target for each button. Using the `toggled` signals to keep track of the group changes and state is discouraged. # Shortcuts and Gestures `GtkCheckButton` supports the following keyboard shortcuts: - <kbd>␣</kbd> or <kbd>Enter</kbd> activates the button. # CSS nodes ``` checkbutton[.text-button][.grouped] ├── check ╰── [label] ``` A `GtkCheckButton` has a main node with name checkbutton. If the [property@Gtk.CheckButton:label] or [property@Gtk.CheckButton:child] properties are set, it contains a child widget. The indicator node is named check when no group is set, and radio if the checkbutton is grouped together with other checkbuttons. # Accessibility `GtkCheckButton` uses the [enum@Gtk.AccessibleRole.checkbox] role. Creates a new `GtkCheckButton`. a new `GtkCheckButton` Creates a new `GtkCheckButton` with the given text. a new `GtkCheckButton` the text for the check button. Creates a new `GtkCheckButton` with the given text and a mnemonic. a new `GtkCheckButton` The text of the button, with an underscore in front of the mnemonic character Returns whether the check button is active. whether the check button is active a `GtkCheckButton` Gets the child widget of @button or `NULL` if [property@CheckButton:label] is set. the child widget of @button a `GtkCheckButton` Returns whether the check button is in an inconsistent state. %TRUE if @check_button is currently in an inconsistent state a `GtkCheckButton` Returns the label of the check button or `NULL` if [property@CheckButton:child] is set. The label @self shows next to the indicator. If no label is shown, %NULL will be returned. a `GtkCheckButton` Returns whether underlines in the label indicate mnemonics. The value of the [property@Gtk.CheckButton:use-underline] property. See [method@Gtk.CheckButton.set_use_underline] for details on how to set a new value. a `GtkCheckButton` Changes the check buttons active state. a `GtkCheckButton` the new value to set Sets the child widget of @button. Note that by using this API, you take full responsibility for setting up the proper accessibility label and description information for @button. Most likely, you'll either set the accessibility label or description for @button explicitly, or you'll set a labelled-by or described-by relations from @child to @button. a `GtkCheckButton` the child widget Adds @self to the group of @group. In a group of multiple check buttons, only one button can be active at a time. The behavior of a checkbutton in a group is also commonly known as a *radio button*. Setting the group of a check button also changes the css name of the indicator widget's CSS node to 'radio'. Setting up groups in a cycle leads to undefined behavior. Note that the same effect can be achieved via the [iface@Gtk.Actionable] API, by using the same action with parameter type and state type 's' for all buttons in the group, and giving each button its own target value. a `GtkCheckButton` another `GtkCheckButton` to form a group with Sets the `GtkCheckButton` to inconsistent state. You should turn off the inconsistent state again if the user checks the check button. This has to be done manually. a `GtkCheckButton` %TRUE if state is inconsistent Sets the text of @self. If [property@Gtk.CheckButton:use-underline] is %TRUE, an underscore in @label is interpreted as mnemonic indicator, see [method@Gtk.CheckButton.set_use_underline] for details on this behavior. a `GtkCheckButton` The text shown next to the indicator, or %NULL to show no text Sets whether underlines in the label indicate mnemonics. If @setting is %TRUE, an underscore character in @self's label indicates a mnemonic accelerator key. This behavior is similar to [property@Gtk.Label:use-underline]. a `GtkCheckButton` the new value to set If the check button is active. Setting `active` to %TRUE will add the `:checked:` state to both the check button and the indicator CSS node. The child widget. The check button whose group this widget belongs to. If the check button is in an “in between” state. The inconsistent state only affects visual appearance, not the semantics of the button. Text of the label inside the check button, if it contains a label widget. If set, an underline in the text indicates that the following character is to be used as mnemonic. Emitted to when the check button is activated. The `::activate` signal on `GtkCheckButton` is an action signal and emitting it causes the button to animate press then release. Applications should never connect to this signal, but use the [signal@Gtk.CheckButton::toggled] signal. The default bindings for this signal are all forms of the <kbd>␣</kbd> and <kbd>Enter</kbd> keys. Emitted when the buttons's [property@Gtk.CheckButton:active] property changes. An expression using a custom `GClosure` to compute the value from its parameters. Creates a `GtkExpression` that calls `closure` when it is evaluated. `closure` is called with the `this` object and the results of evaluating the `params` expressions. a new `GtkExpression` the type of the value that this expression evaluates to closure to call when evaluating this expression. If closure is floating, it is adopted the number of params needed for evaluating `closure` expressions for each parameter Describes how a [class@Gtk.StringSorter] turns strings into sort keys to compare them. Note that the result of sorting will in general depend on the current locale unless the mode is @GTK_COLLATION_NONE. Don't do any collation Use [func@GLib.utf8_collate_key] Use [func@GLib.utf8_collate_key_for_filename] The `GtkColorButton` allows to open a color chooser dialog to change the color. <picture> <source srcset="color-button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkColorButton" src="color-button.png"> </picture> It is suitable widget for selecting a color in a preference dialog. # CSS nodes ``` colorbutton ╰── button.color ╰── [content] ``` `GtkColorButton` has a single CSS node with name colorbutton which contains a button node. To differentiate it from a plain `GtkButton`, it gets the .color style class. Use [class@Gtk.ColorDialogButton] instead Creates a new color button. This returns a widget in the form of a small button containing a swatch representing the current selected color. When the button is clicked, a color chooser dialog will open, allowing the user to select a color. The swatch will be updated to reflect the new color when the user finishes. Use [class@Gtk.ColorDialogButton] instead a new color button Creates a new color button showing the given color. a new color button A `GdkRGBA` to set the current color with Gets whether the dialog is modal. Use [class@Gtk.ColorDialogButton] instead %TRUE if the dialog is modal a `GtkColorButton` Gets the title of the color chooser dialog. Use [class@Gtk.ColorDialogButton] instead An internal string, do not free the return value a `GtkColorButton` Sets whether the dialog should be modal. Use [class@Gtk.ColorDialogButton] instead a `GtkColorButton` %TRUE to make the dialog modal Sets the title for the color chooser dialog. Use [class@Gtk.ColorDialogButton] instead a `GtkColorButton` String containing new window title Whether the color chooser dialog should be modal. Whether the color chooser should open in editor mode. This property should be used in cases where the palette in the editor would be redundant, such as when the color button is already part of a palette. The title of the color chooser dialog Emitted to when the color button is activated. The `::activate` signal on `GtkMenuButton` is an action signal and emitting it causes the button to pop up its dialog. Emitted when the user selects a color. When handling this signal, use [method@Gtk.ColorChooser.get_rgba] to find out which color was just selected. Note that this signal is only emitted when the user changes the color. If you need to react to programmatic color changes as well, use the notify::rgba signal. `GtkColorChooser` is an interface that is implemented by widgets for choosing colors. Depending on the situation, colors may be allowed to have alpha (translucency). In GTK, the main widgets that implement this interface are [class@Gtk.ColorChooserWidget], [class@Gtk.ColorChooserDialog] and [class@Gtk.ColorButton]. Use [class@Gtk.ColorDialog] and [class@Gtk.ColorDialogButton] instead of widgets implementing `GtkColorChooser` Adds a palette to the color chooser. If @orientation is horizontal, the colors are grouped in rows, with @colors_per_line colors in each row. If @horizontal is %FALSE, the colors are grouped in columns instead. The default color palette of [class@Gtk.ColorChooserWidget] has 45 colors, organized in columns of 5 colors (this includes some grays). The layout of the color chooser widget works best when the palettes have 9-10 columns. Calling this function for the first time has the side effect of removing the default color palette from the color chooser. If @colors is %NULL, removes all previously added palettes. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` %GTK_ORIENTATION_HORIZONTAL if the palette should be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns the number of colors to show in each row/column the total number of elements in @colors the colors of the palette Gets the currently-selected color. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` a `GdkRGBA` to fill in with the current color Sets the color. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` the new color Adds a palette to the color chooser. If @orientation is horizontal, the colors are grouped in rows, with @colors_per_line colors in each row. If @horizontal is %FALSE, the colors are grouped in columns instead. The default color palette of [class@Gtk.ColorChooserWidget] has 45 colors, organized in columns of 5 colors (this includes some grays). The layout of the color chooser widget works best when the palettes have 9-10 columns. Calling this function for the first time has the side effect of removing the default color palette from the color chooser. If @colors is %NULL, removes all previously added palettes. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` %GTK_ORIENTATION_HORIZONTAL if the palette should be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns the number of colors to show in each row/column the total number of elements in @colors the colors of the palette Gets the currently-selected color. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` a `GdkRGBA` to fill in with the current color Returns whether the color chooser shows the alpha channel. Use [class@Gtk.ColorDialog] instead %TRUE if the color chooser uses the alpha channel, %FALSE if not a `GtkColorChooser` Sets the color. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` the new color Sets whether or not the color chooser should use the alpha channel. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` %TRUE if color chooser should use alpha channel, %FALSE if not The currently selected color, as a `GdkRGBA` struct. The property can be set to change the current selection programmatically. Use [class@Gtk.ColorDialog] and [class@Gtk.ColorDialogButton] instead of widgets implementing `GtkColorChooser` Whether colors may have alpha (translucency). When ::use-alpha is %FALSE, the `GdkRGBA` struct obtained via the [property@Gtk.ColorChooser:rgba] property will be forced to have alpha == 1. Implementations are expected to show alpha by rendering the color over a non-uniform background (like a checkerboard pattern). Use [class@Gtk.ColorDialog] and [class@Gtk.ColorDialogButton] instead of widgets implementing `GtkColorChooser` Emitted when a color is activated from the color chooser. This usually happens when the user clicks a color swatch, or a color is selected and the user presses one of the keys Space, Shift+Space, Return or Enter. Use [class@Gtk.ColorDialog] and [class@Gtk.ColorDialogButton] instead of widgets implementing `GtkColorChooser` the color A dialog for choosing a color. <picture> <source srcset="colorchooser-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkColorChooserDialog" src="colorchooser.png"> </picture> `GtkColorChooserDialog` implements the [iface@Gtk.ColorChooser] interface and does not provide much API of its own. To create a `GtkColorChooserDialog`, use [ctor@Gtk.ColorChooserDialog.new]. To change the initially selected color, use [method@Gtk.ColorChooser.set_rgba]. To get the selected color use [method@Gtk.ColorChooser.get_rgba]. `GtkColorChooserDialog` has been deprecated in favor of [class@Gtk.ColorDialog]. ## CSS nodes `GtkColorChooserDialog` has a single CSS node with the name `window` and style class `.colorchooser`. Use [class@Gtk.ColorDialog] instead Creates a new `GtkColorChooserDialog`. Use [class@Gtk.ColorDialog] instead a new `GtkColorChooserDialog` Title of the dialog Transient parent of the dialog Whether the color chooser dialog is showing the single-color editor. It can be set to switch the color chooser into single-color editing mode. a `GtkColorChooser` a `GdkRGBA` to fill in with the current color a `GtkColorChooser` the new color a `GtkColorChooser` %GTK_ORIENTATION_HORIZONTAL if the palette should be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns the number of colors to show in each row/column the total number of elements in @colors the colors of the palette The `GtkColorChooserWidget` widget lets the user select a color. By default, the chooser presents a predefined palette of colors, plus a small number of settable custom colors. It is also possible to select a different color with the single-color editor. To enter the single-color editing mode, use the context menu of any color of the palette, or use the '+' button to add a new custom color. The chooser automatically remembers the last selection, as well as custom colors. To create a `GtkColorChooserWidget`, use [ctor@Gtk.ColorChooserWidget.new]. To change the initially selected color, use [method@Gtk.ColorChooser.set_rgba]. To get the selected color use [method@Gtk.ColorChooser.get_rgba]. The `GtkColorChooserWidget` is used in the [class@Gtk.ColorChooserDialog] to provide a dialog for selecting colors. # Actions `GtkColorChooserWidget` defines a set of built-in actions: - `color.customize` activates the color editor for the given color. - `color.select` emits the [signal@Gtk.ColorChooser::color-activated] signal for the given color. # CSS names `GtkColorChooserWidget` has a single CSS node with name colorchooser. Direct use of `GtkColorChooserWidget` is deprecated. Creates a new `GtkColorChooserWidget`. a new `GtkColorChooserWidget` %TRUE when the color chooser is showing the single-color editor. It can be set to switch the color chooser into single-color editing mode. Asynchronous API to present a color chooser dialog. `GtkColorDialog` collects the arguments that are needed to present the dialog to the user, such as a title for the dialog and whether it should be modal. The dialog is shown with the [method@Gtk.ColorDialog.choose_rgba] function. See [class@Gtk.ColorDialogButton] for a convenient control that uses `GtkColorDialog` and presents the results. Creates a new `GtkColorDialog` object. the new `GtkColorDialog` Presents a color chooser dialog to the user. a color dialog the parent window the color to select initially a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.ColorDialog.choose_rgba] call Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. the selected color a color dialog the result Returns whether the color chooser dialog blocks interaction with the parent window while it is presented. true if the color chooser dialog is modal a color dialog Returns the title that will be shown on the color chooser dialog. the title a color dialog Returns whether colors may have alpha. true if colors may have alpha a color dailog Sets whether the color chooser dialog blocks interaction with the parent window while it is presented. a color dialog the new value Sets the title that will be shown on the color chooser dialog. a color dialog the new title Sets whether colors may have alpha. a color dialog the new value Whether the color chooser dialog is modal. A title that may be shown on the color chooser dialog. Whether colors may have alpha (translucency). When with-alpha is false, the color that is selected will be forced to have alpha == 1. Opens a color chooser dialog to select a color. <picture> <source srcset="color-button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkColorDialogButton" src="color-button.png"> </picture> It is suitable widget for selecting a color in a preference dialog. # CSS nodes ``` colorbutton ╰── button.color ╰── [content] ``` `GtkColorDialogButton` has a single CSS node with name colorbutton which contains a button node. To differentiate it from a plain `GtkButton`, it gets the .color style class. Creates a new `GtkColorDialogButton` with the given `GtkColorDialog`. You can pass `NULL` to this function and set a `GtkColorDialog` later. The button will be insensitive until that happens. the new `GtkColorDialogButton` the `GtkColorDialog` to use Returns the `GtkColorDialog` of @self. the `GtkColorDialog` a `GtkColorDialogButton` Returns the color of the button. This function is what should be used to obtain the color that was chosen by the user. To get informed about changes, listen to "notify::rgba". the color a `GtkColorDialogButton` Sets a `GtkColorDialog` object to use for creating the color chooser dialog that is presented when the user clicks the button. a `GtkColorDialogButton` the new `GtkColorDialog` Sets the color of the button. a `GtkColorDialogButton` the new color The `GtkColorDialog` that contains parameters for the color chooser dialog. The selected color. This property can be set to give the button its initial color, and it will be updated to reflect the users choice in the color chooser dialog. Listen to `notify::rgba` to get informed about changes to the buttons color. Emitted when the color dialog button is activated. The `::activate` signal on `GtkColorDialogButton` is an action signal and emitting it causes the button to pop up its dialog. Presents a large dynamic list of items using multiple columns with headers. `GtkColumnView` uses the factories of its columns to generate a cell widget for each column, for each visible item and displays them together as the row for this item. The [property@Gtk.ColumnView:show-row-separators] and [property@Gtk.ColumnView:show-column-separators] properties offer a simple way to display separators between the rows or columns. `GtkColumnView` allows the user to select items according to the selection characteristics of the model. For models that allow multiple selected items, it is possible to turn on *rubberband selection*, using [property@Gtk.ColumnView:enable-rubberband]. The column view supports sorting that can be customized by the user by clicking on column headers. To set this up, the `GtkSorter` returned by [method@Gtk.ColumnView.get_sorter] must be attached to a sort model for the data that the view is showing, and the columns must have sorters attached to them by calling [method@Gtk.ColumnViewColumn.set_sorter]. The initial sort order can be set with [method@Gtk.ColumnView.sort_by_column]. The column view also supports interactive resizing and reordering of columns, via Drag-and-Drop of the column headers. This can be enabled or disabled with the [property@Gtk.ColumnView:reorderable] and [property@Gtk.ColumnViewColumn:resizable] properties. To learn more about the list widget framework, see the [overview](section-list-widget.html). # CSS nodes ``` columnview[.column-separators][.rich-list][.navigation-sidebar][.data-table] ├── header │ ├── <column header> ┊ ┊ │ ╰── <column header> │ ├── listview │ ┊ ╰── [rubberband] ``` `GtkColumnView` uses a single CSS node named columnview. It may carry the .column-separators style class, when [property@Gtk.ColumnView:show-column-separators] property is set. Header widgets appear below a node with name header. The rows are contained in a `GtkListView` widget, so there is a listview node with the same structure as for a standalone `GtkListView` widget. If [property@Gtk.ColumnView:show-row-separators] is set, it will be passed on to the list view, causing its CSS node to carry the .separators style class. For rubberband selection, a node with name rubberband is used. The main columnview node may also carry style classes to select the style of [list presentation](section-list-widget.html#list-styles): .rich-list, .navigation-sidebar or .data-table. # Accessibility `GtkColumnView` uses the [enum@Gtk.AccessibleRole.tree_grid] role, header title widgets are using the [enum@Gtk.AccessibleRole.column_header] role. The row widgets are using the [enum@Gtk.AccessibleRole.row] role, and individual cells are using the [enum@Gtk.AccessibleRole.grid_cell] role Creates a new `GtkColumnView`. You most likely want to call [method@Gtk.ColumnView.append_column] to add columns next. a new `GtkColumnView` the list model to use Appends the @column to the end of the columns in @self. a columnview a column that hasn't been added to a `GtkColumnView` yet Gets the list of columns in this column view. This list is constant over the lifetime of @self and can be used to monitor changes to the columns of @self by connecting to the [signal@Gio.ListModel::items-changed] signal. The list managing the columns a columnview Returns whether rows can be selected by dragging with the mouse. true if rubberband selection is enabled a columnview Gets the factory that's currently used to populate section headers. The factory in use a columnview Gets the model that's currently used to read the items displayed. The model in use a columnview Returns whether columns are reorderable. true if columns are reorderable a columnview Gets the factory set via [method@Gtk.ColumnView.set_row_factory]. The factory a columnview Returns whether the list should show separators between columns. true if the list shows column separators a columnview Returns whether the list should show separators between rows. true if the list shows separators a columnview Returns whether rows will be activated on single click and selected on hover. true if rows are activated on single click a columnview Returns a special sorter that reflects the users sorting choices in the column view. To allow users to customizable sorting by clicking on column headers, this sorter needs to be set on the sort model underneath the model that is displayed by the view. See [method@Gtk.ColumnViewColumn.set_sorter] for setting up per-column sorting. Here is an example: ```c gtk_column_view_column_set_sorter (column, sorter); gtk_column_view_append_column (view, column); sorter = g_object_ref (gtk_column_view_get_sorter (view))); model = gtk_sort_list_model_new (store, sorter); selection = gtk_no_selection_new (model); gtk_column_view_set_model (view, selection); ``` the `GtkSorter` of @self a columnview Gets the behavior set for the <kbd>Tab</kbd> key. The behavior of the <kbd>Tab</kbd> key a columnview Inserts a column at the given position in the columns of @self. If @column is already a column of @self, it will be repositioned. a columnview the position to insert @column at the column to insert Removes the @column from the list of columns of @self. a columnview a column that's part of @self Scroll to the row at the given position - or cell if a column is given - and performs the actions specified in @flags. This function works no matter if the columnview is shown or focused. If it isn't, then the changes will take effect once that happens. The columnview position of the item. Must be less than the number of items in the view. The column to scroll to or `NULL` to not scroll columns actions to perform details of how to perform the scroll operation or %NULL to scroll into view Sets whether selections can be changed by dragging with the mouse. a columnview whether to enable rubberband selection Sets the factory to use for populating the [class@Gtk.ListHeader] objects used in section headers. If this factory is set to `NULL`, the list will not show section headers. a columnview the factory to use Sets the model to use. This must be a [iface@Gtk.SelectionModel]. a columnview the model to use Sets whether columns should be reorderable by dragging. a columnview whether columns should be reorderable Sets the factory used for configuring rows. The factory must be for configuring [class@Gtk.ColumnViewRow] objects. If this factory is not set - which is the default - then the defaults will be used. This factory is not used to set the widgets displayed in the individual cells. For that see [method@GtkColumnViewColumn.set_factory] and [class@GtkColumnViewCell]. a columnview The row factory Sets whether the list should show separators between columns. a columnview whether to show column separators Sets whether the list should show separators between rows. a columnview whether to show row separators Sets whether rows should be activated on single click and selected on hover. a columnview whether to activate items on single click Sets the <kbd>Tab</kbd> key behavior. This influences how the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys move the focus in the columnview. a columnview The desired tab behavior Sets the sorting of the view. This function should be used to set up the initial sorting. At runtime, users can change the sorting of a column view by clicking on the list headers. This call only has an effect if the sorter returned by [method@Gtk.ColumnView.get_sorter] is set on a sort model, and [method@Gtk.ColumnViewColumn.set_sorter] has been called on @column to associate a sorter with the column. If @column is unset, the view will be unsorted. a columnview the column to sort by the direction to sort in The list of columns. Allow rubberband selection. Factory for creating header widgets. The factory must be for configuring [class@Gtk.ListHeader] objects. Model for the items displayed. Whether columns are reorderable. The factory used for configuring rows. The factory must be for configuring [class@Gtk.ColumnViewRow] objects. Show separators between columns. Show separators between rows. Activate rows on single click and select them on hover. Sorter with the sorting choices of the user. Behavior of the <kbd>Tab</kbd> key Emitted when a row has been activated by the user, usually via activating the GtkListBase|list.activate-item action. This allows for a convenient way to handle activation in a columnview. See [method@Gtk.ListItem.set_activatable] for details on how to use this signal. position of item to activate Represents items in a cell in [class@Gtk.ColumnView]. The `GtkColumnViewCell`s are managed by the [class@Gtk.ColumnView] widget (with its factory) and cannot be created by applications, but they need to be populated by application code. This is done by calling [method@Gtk.ColumnViewCell.set_child]. `GtkColumnViewCell`s exist in 2 stages: 1. The unbound stage where the listitem is not currently connected to an item in the list. In that case, the [property@Gtk.ColumnViewCell:item] property is set to %NULL. 2. The bound stage where the listitem references an item from the list. The [property@Gtk.ColumnViewCell:item] property is not %NULL. Gets the child previously set via gtk_column_view_cell_set_child() or %NULL if none was set. The child a `GtkColumnViewCell` Checks if a list item has been set to be focusable via gtk_column_view_cell_set_focusable(). %TRUE if the item is focusable a `GtkColumnViewCell` Gets the model item that associated with @self. If @self is unbound, this function returns %NULL. The item displayed a `GtkColumnViewCell` Gets the position in the model that @self currently displays. If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. The position of this item a `GtkColumnViewCell` Checks if the item is displayed as selected. The selected state is maintained by the list widget and its model and cannot be set otherwise. %TRUE if the item is selected. a `GtkColumnViewCell` Sets the child to be used for this listitem. This function is typically called by applications when setting up a listitem so that the widget can be reused when binding it multiple times. a `GtkColumnViewCell` The list item's child or %NULL to unset Sets @self to be focusable. If an item is focusable, it can be focused using the keyboard. This works similar to [method@Gtk.Widget.set_focusable]. Note that if items are not focusable, the keyboard cannot be used to activate them and selecting only works if one of the listitem's children is focusable. By default, list items are focusable. a `GtkColumnViewCell` if the item should be focusable Widget used for display. If the item can be focused with the keyboard. Displayed item. Position of the item. If the item is currently selected. Represents the columns in a `GtkColumnView`. The main ingredient for a `GtkColumnViewColumn` is the `GtkListItemFactory` that tells the columnview how to create cells for this column from items in the model. Columns have a title, and can optionally have a header menu set with [method@Gtk.ColumnViewColumn.set_header_menu]. A sorter can be associated with a column using [method@Gtk.ColumnViewColumn.set_sorter], to let users influence sorting by clicking on the column header. Creates a new `GtkColumnViewColumn` that uses the given @factory for mapping items to widgets. You most likely want to call [method@Gtk.ColumnView.append_column] next. The function takes ownership of the argument, so you can write code like: ```c column = gtk_column_view_column_new (_("Name"), gtk_builder_list_item_factory_new_from_resource ("/name.ui")); ``` a new `GtkColumnViewColumn` using the given @factory Title to use for this column The factory to populate items with Gets the column view that's currently displaying this column. If @self has not been added to a column view yet, `NULL` is returned. The column view displaying @self. a column Returns whether this column should expand. true if this column expands a column Gets the factory that's currently used to populate list items for this column. The factory in use a column Gets the fixed width of the column. the fixed with of the column a column Gets the menu model that is used to create the context menu for the column header. the `GMenuModel` a column Returns the ID set with [method@Gtk.ColumnViewColumn.set_id]. The column's ID a column Returns whether this column is resizable. true if this column is resizable a column Returns the sorter that is associated with the column. the `GtkSorter` of @self a column Returns the title set with [method@Gtk.ColumnViewColumn.set_title]. The column's title a column Returns whether this column is visible. true if this column is visible a column Sets the column to take available extra space. The extra space is shared equally amongst all columns that have are set to expand. a column whether this column should expand to fill available space Sets the `GtkListItemFactory` to use for populating list items for this column. a column the factory to use Sets the fixed width of the column. If @fixed_width is -1, the fixed width of the column is unset. Setting a fixed width overrides the automatically calculated width. Interactive resizing also sets the “fixed-width” property. a column the new fixed width, or -1 Sets the menu model that is used to create the context menu for the column header. a column a `GMenuModel` Sets the id of this column. GTK makes no use of this, but applications can use it when storing column view configuration. It is up to callers to ensure uniqueness of IDs. a column ID to use for this column Sets whether this column should be resizable by dragging. a column whether this column should be resizable Associates a sorter with the column. If @sorter is unset, the column will not let users change the sorting by clicking on its header. This sorter can be made active by clicking on the column header, or by calling [method@Gtk.ColumnView.sort_by_column]. See [method@Gtk.ColumnView.get_sorter] for the necessary steps for setting up customizable sorting for [class@Gtk.ColumnView]. a column the `GtkSorter` to associate with @column Sets the title of this column. The title is displayed in the header of a `GtkColumnView` for this column and is therefore user-facing text that should be translated. a column Title to use for this column Sets whether this column should be visible in views. a column whether this column should be visible The `GtkColumnView` this column is a part of. Column gets share of extra width allocated to the view. Factory for populating list items. The factory must be for configuring [class@Gtk.ColumnViewCell] objects. If not -1, this is the width that the column is allocated, regardless of the size of its content. Menu model used to create the context menu for the column header. An ID for the column. GTK is not currently using the ID for anything, but it can be used by applications when saving column view configurations. It is up to applications to ensure uniqueness of IDs. Whether this column is resizable. Sorter for sorting items according to this column. Title displayed in the header. Whether this column is visible. Configures how rows are displayed in a [class@Gtk.ColumnView]. It is not used to set the widgets displayed in the individual cells. For that see [method@GtkColumnViewColumn.set_factory] and [class@GtkColumnViewCell]. Gets the accessible description of @self. the accessible description a `GtkColumnViewRow` Gets the accessible label of @self. the accessible label a `GtkColumnViewRow` Checks if the row has been set to be activatable via gtk_column_view_row_set_activatable(). %TRUE if the row is activatable a `GtkColumnViewRow` Checks if a row item has been set to be focusable via gtk_column_view_row_set_focusable(). %TRUE if the row is focusable a `GtkColumnViewRow` Gets the model item that associated with @self. If @self is unbound, this function returns %NULL. The item displayed a `GtkColumnViewRow` Gets the position in the model that @self currently displays. If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. The position of this row a `GtkColumnViewRow` Checks if the row has been set to be selectable via gtk_column_view_row_set_selectable(). Do not confuse this function with [method@Gtk.ColumnViewRow.get_selected]. %TRUE if the row is selectable a `GtkColumnViewRow` Checks if the item is selected that this row corresponds to. The selected state is maintained by the list widget and its model and cannot be set otherwise. %TRUE if the item is selected. a `GtkColumnViewRow` Sets the accessible description for the row, which may be used by e.g. screen readers. a `GtkColumnViewRow` the description Sets the accessible label for the row, which may be used by e.g. screen readers. a `GtkColumnViewRow` the label Sets @self to be activatable. If a row is activatable, double-clicking on the row, using the Return key or calling gtk_widget_activate() will activate the row. Activating instructs the containing columnview to emit the [signal@Gtk.ColumnView::activate] signal. By default, row are activatable. a `GtkColumnViewRow` if the row should be activatable Sets @self to be focusable. If a row is focusable, it can be focused using the keyboard. This works similar to [method@Gtk.Widget.set_focusable]. Note that if row are not focusable, the contents of cells can still be focused if they are focusable. By default, rows are focusable. a `GtkColumnViewRow` if the row should be focusable Sets @self to be selectable. If a row is selectable, clicking on the row or using the keyboard will try to select or unselect the row. Whether this succeeds is up to the model to determine, as it is managing the selected state. Note that this means that making a row non-selectable has no influence on the selected state at all. A non-selectable row may still be selected. By default, rows are selectable. a `GtkColumnViewRow` if the row should be selectable The accessible description to set on the row. The accessible label to set on the row. If the row can be activated by the user. If the row can be focused with the keyboard. The item for this row. Position of the row. If the row can be selected by the user. If the item in the row is currently selected. Sorts [class@Gtk.ColumnView] columns. The sorter returned by [method@Gtk.ColumnView.get_sorter] is a `GtkColumnViewSorter`. In column views, sorting can be configured by associating sorters with columns, and users can invert sort order by clicking on column headers. The API of `GtkColumnViewSorter` is designed to allow saving and restoring this configuration. If you are only interested in the primary sort column (i.e. the column where a sort indicator is shown in the header), then you can just look at [property@Gtk.ColumnViewSorter:primary-sort-column] and [property@Gtk.ColumnViewSorter:primary-sort-order]. If you want to store the full sort configuration, including secondary sort columns that are used for tie breaking, then you can use [method@Gtk.ColumnViewSorter.get_nth_sort_column]. To get notified about changes, use [signal@Gtk.Sorter::changed]. To restore a saved sort configuration on a `GtkColumnView`, use code like: ``` sorter = gtk_column_view_get_sorter (view); for (i = gtk_column_view_sorter_get_n_sort_columns (sorter) - 1; i >= 0; i--) { column = gtk_column_view_sorter_get_nth_sort_column (sorter, i, &order); gtk_column_view_sort_by_column (view, column, order); } ``` Returns the number of columns by which the sorter sorts. If the sorter of the primary sort column does not determine a total order, then the secondary sorters are consulted to break the ties. Use the [signal@Gtk.Sorter::changed] signal to get notified when the number of sort columns changes. the number of sort columns a columnviewsorter Gets the @position'th sort column and its associated sort order. Use the [signal@Gtk.Sorter::changed] signal to get notified when sort columns change. the sort column at the @position a columnviewsorter the position of the sort column to retrieve (0 for the primary sort column) return location for the sort order Returns the primary sort column. The primary sort column is the one that displays the triangle in a column view header. the primary sort column a columnviewsorter Returns the primary sort order. The primary sort order determines whether the triangle displayed in the column view header of the primary sort column points upwards or downwards. If there is no primary sort column, then this function returns `GTK_SORT_ASCENDING`. the primary sort order a columnviewsorter The primary sort column. The primary sort column is the one that displays the triangle in a column view header. The primary sort order. The primary sort order determines whether the triangle displayed in the column view header of the primary sort column points upwards or downwards. A `GtkComboBox` is a widget that allows the user to choose from a list of valid choices. <picture> <source srcset="combo-box-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkComboBox" src="combo-box.png"> </picture> The `GtkComboBox` displays the selected choice; when activated, the `GtkComboBox` displays a popup which allows the user to make a new choice. The `GtkComboBox` uses the model-view pattern; the list of valid choices is specified in the form of a tree model, and the display of the choices can be adapted to the data in the model by using cell renderers, as you would in a tree view. This is possible since `GtkComboBox` implements the [iface@Gtk.CellLayout] interface. The tree model holding the valid choices is not restricted to a flat list, it can be a real tree, and the popup will reflect the tree structure. To allow the user to enter values not in the model, the [property@Gtk.ComboBox:has-entry] property allows the `GtkComboBox` to contain a [class@Gtk.Entry]. This entry can be accessed by calling [method@Gtk.ComboBox.get_child] on the combo box. For a simple list of textual choices, the model-view API of `GtkComboBox` can be a bit overwhelming. In this case, [class@Gtk.ComboBoxText] offers a simple alternative. Both `GtkComboBox` and `GtkComboBoxText` can contain an entry. ## CSS nodes ``` combobox ├── box.linked │ ╰── button.combo │ ╰── box │ ├── cellview │ ╰── arrow ╰── window.popup ``` A normal combobox contains a box with the .linked class, a button with the .combo class and inside those buttons, there are a cellview and an arrow. ``` combobox ├── box.linked │ ├── entry.combo │ ╰── button.combo │ ╰── box │ ╰── arrow ╰── window.popup ``` A `GtkComboBox` with an entry has a single CSS node with name combobox. It contains a box with the .linked class. That box contains an entry and a button, both with the .combo class added. The button also contains another node with name arrow. ## Accessibility `GtkComboBox` uses the [enum@Gtk.AccessibleRole.combo_box] role. Use [class@Gtk.DropDown] instead Creates a new empty `GtkComboBox`. Use [class@Gtk.DropDown] A new `GtkComboBox` Creates a new empty `GtkComboBox` with an entry. In order to use a combo box with entry, you need to tell it which column of the model contains the text for the entry by calling [method@Gtk.ComboBox.set_entry_text_column]. Use [class@Gtk.DropDown] A new `GtkComboBox` Creates a new `GtkComboBox` with a model. Use [class@Gtk.DropDown] A new `GtkComboBox` a `GtkTreeModel` Creates a new empty `GtkComboBox` with an entry and a model. See also [ctor@Gtk.ComboBox.new_with_entry]. Use [class@Gtk.DropDown] A new `GtkComboBox` A `GtkTreeModel` Signal is emitted when the active item is changed. Signal which allows you to change how the text displayed in a combo box’s entry is displayed. Returns the index of the currently active item. If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this function returns `gtk_tree_path_get_indices (path)[0]`, where `path` is the [struct@Gtk.TreePath] of the active item. Use [class@Gtk.DropDown] An integer which is the index of the currently active item, or -1 if there’s no active item A `GtkComboBox` Returns the ID of the active row of @combo_box. This value is taken from the active row and the column specified by the [property@Gtk.ComboBox:id-column] property of @combo_box (see [method@Gtk.ComboBox.set_id_column]). The returned value is an interned string which means that you can compare the pointer by value to other interned strings and that you must not free it. If the [property@Gtk.ComboBox:id-column] property of @combo_box is not set, or if no row is active, or if the active row has a %NULL ID value, then %NULL is returned. Use [class@Gtk.DropDown] the ID of the active row a `GtkComboBox` Sets @iter to point to the currently active item. If no item is active, @iter is left unchanged. Use [class@Gtk.DropDown] %TRUE if @iter was set, %FALSE otherwise A `GtkComboBox` A `GtkTreeIter` Returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model. Use [class@Gtk.DropDown] %GTK_SENSITIVITY_ON if the dropdown button is sensitive when the model is empty, %GTK_SENSITIVITY_OFF if the button is always insensitive or %GTK_SENSITIVITY_AUTO if it is only sensitive as long as the model has one item to be selected. a `GtkComboBox` Gets the child widget of @combo_box. Use [class@Gtk.DropDown] the child widget of @combo_box a `GtkComboBox` Returns the column which @combo_box is using to get the strings from to display in the internal entry. Use [class@Gtk.DropDown] A column in the data source model of @combo_box. A `GtkComboBox` Returns whether the combo box has an entry. Use [class@Gtk.DropDown] whether there is an entry in @combo_box. a `GtkComboBox` Returns the column which @combo_box is using to get string IDs for values from. Use [class@Gtk.DropDown] A column in the data source model of @combo_box. A `GtkComboBox` Returns the `GtkTreeModel` of @combo_box. Use [class@Gtk.DropDown] A `GtkTreeModel` which was passed during construction. A `GtkComboBox` Gets whether the popup uses a fixed width. Use [class@Gtk.DropDown] %TRUE if the popup uses a fixed width a `GtkComboBox` Returns the current row separator function. Use [class@Gtk.DropDown] the current row separator function. a `GtkComboBox` Hides the menu or dropdown list of @combo_box. This function is mostly intended for use by accessibility technologies; applications should have little use for it. Use [class@Gtk.DropDown] a `GtkComboBox` Pops up the menu or dropdown list of @combo_box. This function is mostly intended for use by accessibility technologies; applications should have little use for it. Before calling this, @combo_box must be mapped, or nothing will happen. Use [class@Gtk.DropDown] a `GtkComboBox` Pops up the menu of @combo_box. Note that currently this does not do anything with the device, as it was previously only used for list-mode combo boxes, and those were removed in GTK 4. However, it is retained in case similar functionality is added back later. Use [class@Gtk.DropDown] a `GtkComboBox` a `GdkDevice` Sets the active item of @combo_box to be the item at @index. Use [class@Gtk.DropDown] a `GtkComboBox` An index in the model passed during construction, or -1 to have no active item Changes the active row of @combo_box to the one that has an ID equal to @active_id. If @active_id is %NULL, the active row is unset. Rows having a %NULL ID string cannot be made active by this function. If the [property@Gtk.ComboBox:id-column] property of @combo_box is unset or if no row has the given ID then the function does nothing and returns %FALSE. Use [class@Gtk.DropDown] %TRUE if a row with a matching ID was found. If a %NULL @active_id was given to unset the active row, the function always returns %TRUE. a `GtkComboBox` the ID of the row to select Sets the current active item to be the one referenced by @iter. If @iter is %NULL, the active item is unset. Use [class@Gtk.DropDown] A `GtkComboBox` The `GtkTreeIter` Sets whether the dropdown button of the combo box should update its sensitivity depending on the model contents. Use [class@Gtk.DropDown] a `GtkComboBox` specify the sensitivity of the dropdown button Sets the child widget of @combo_box. Use [class@Gtk.DropDown] a `GtkComboBox` the child widget Sets the model column which @combo_box should use to get strings from to be @text_column. For this column no separate [class@Gtk.CellRenderer] is needed. The column @text_column in the model of @combo_box must be of type %G_TYPE_STRING. This is only relevant if @combo_box has been created with [property@Gtk.ComboBox:has-entry] as %TRUE. Use [class@Gtk.DropDown] A `GtkComboBox` A column in @model to get the strings from for the internal entry Sets the model column which @combo_box should use to get string IDs for values from. The column @id_column in the model of @combo_box must be of type %G_TYPE_STRING. Use [class@Gtk.DropDown] A `GtkComboBox` A column in @model to get string IDs for values from Sets the model used by @combo_box to be @model. Will unset a previously set model (if applicable). If model is %NULL, then it will unset the model. Note that this function does not clear the cell renderers, you have to call [method@Gtk.CellLayout.clear] yourself if you need to set up different cell renderers for the new model. Use [class@Gtk.DropDown] A `GtkComboBox` A `GtkTreeModel` Specifies whether the popup’s width should be a fixed width. If @fixed is %TRUE, the popup's width is set to match the allocated width of the combo box. Use [class@Gtk.DropDown] a `GtkComboBox` whether to use a fixed popup width Sets the row separator function, which is used to determine whether a row should be drawn as a separator. If the row separator function is %NULL, no separators are drawn. This is the default value. Use [class@Gtk.DropDown] a `GtkComboBox` a `GtkTreeViewRowSeparatorFunc` user data to pass to @func destroy notifier for @data The item which is currently active. If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this property has the value `gtk_tree_path_get_indices (path)[0]`, where `path` is the [struct@Gtk.TreePath] of the active item. The value of the ID column of the active row. Whether the dropdown button is sensitive when the model is empty. The child widget. The model column to associate with strings from the entry. This is property only relevant if the combo was created with [property@Gtk.ComboBox:has-entry] is %TRUE. Whether the combo box has an entry. The `has-frame` property controls whether a frame is drawn around the entry. The model column that provides string IDs for the values in the model, if != -1. The model from which the combo box takes its values. Whether the popup's width should be a fixed width matching the allocated width of the combo box. Whether the combo boxes dropdown is popped up. Note that this property is mainly useful, because it allows you to connect to notify::popup-shown. Emitted to when the combo box is activated. The `::activate` signal on `GtkComboBox` is an action signal and emitting it causes the combo box to pop up its dropdown. Emitted when the active item is changed. The can be due to the user selecting a different item from the list, or due to a call to [method@Gtk.ComboBox.set_active_iter]. It will also be emitted while typing into the entry of a combo box with an entry. Emitted to allow changing how the text in a combo box's entry is displayed. See [property@Gtk.ComboBox:has-entry]. Connect a signal handler which returns an allocated string representing @path. That string will then be used to set the text in the combo box's entry. The default signal handler uses the text from the [property@Gtk.ComboBox:entry-text-column] model column. Here's an example signal handler which fetches data from the model and displays it in the entry. ```c static char * format_entry_text_callback (GtkComboBox *combo, const char *path, gpointer user_data) { GtkTreeIter iter; GtkTreeModel model; double value; model = gtk_combo_box_get_model (combo); gtk_tree_model_get_iter_from_string (model, &iter, path); gtk_tree_model_get (model, &iter, THE_DOUBLE_VALUE_COLUMN, &value, -1); return g_strdup_printf ("%g", value); } ``` a newly allocated string representing @path for the current `GtkComboBox` model. the [struct@Gtk.TreePath] string from the combo box's current model to format text for Emitted to move the active selection. This is an [keybinding signal](class.SignalAction.html). a `GtkScrollType` Emitted to popdown the combo box list. This is an [keybinding signal](class.SignalAction.html). The default bindings for this signal are Alt+Up and Escape. whether the combo box was popped down Emitted to popup the combo box list. This is an [keybinding signal](class.SignalAction.html). The default binding for this signal is Alt+Down. The parent class. Signal is emitted when the active item is changed. Signal which allows you to change how the text displayed in a combo box’s entry is displayed. A `GtkComboBoxText` is a simple variant of `GtkComboBox` for text-only use cases. <picture> <source srcset="combo-box-text-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkComboBoxText" src="combo-box-text.png"> </picture> `GtkComboBoxText` hides the model-view complexity of `GtkComboBox`. To create a `GtkComboBoxText`, use [ctor@Gtk.ComboBoxText.new] or [ctor@Gtk.ComboBoxText.new_with_entry]. You can add items to a `GtkComboBoxText` with [method@Gtk.ComboBoxText.append_text], [method@Gtk.ComboBoxText.insert_text] or [method@Gtk.ComboBoxText.prepend_text] and remove options with [method@Gtk.ComboBoxText.remove]. If the `GtkComboBoxText` contains an entry (via the [property@Gtk.ComboBox:has-entry] property), its contents can be retrieved using [method@Gtk.ComboBoxText.get_active_text]. You should not call [method@Gtk.ComboBox.set_model] or attempt to pack more cells into this combo box via its [iface@Gtk.CellLayout] interface. ## GtkComboBoxText as GtkBuildable The `GtkComboBoxText` implementation of the `GtkBuildable` interface supports adding items directly using the `<items>` element and specifying `<item>` elements for each item. Each `<item>` element can specify the “id” corresponding to the appended text and also supports the regular translation attributes “translatable”, “context” and “comments”. Here is a UI definition fragment specifying `GtkComboBoxText` items: ```xml <object class="GtkComboBoxText"> <items> <item translatable="yes" id="factory">Factory</item> <item translatable="yes" id="home">Home</item> <item translatable="yes" id="subway">Subway</item> </items> </object> ``` ## CSS nodes ``` combobox ╰── box.linked ├── entry.combo ├── button.combo ╰── window.popup ``` `GtkComboBoxText` has a single CSS node with name combobox. It adds the style class .combo to the main CSS nodes of its entry and button children, and the .linked class to the node of its internal box. Use [class@Gtk.DropDown] with a [class@Gtk.StringList] instead Creates a new `GtkComboBoxText`. Use [class@Gtk.DropDown] A new `GtkComboBoxText` Creates a new `GtkComboBoxText` with an entry. Use [class@Gtk.DropDown] a new `GtkComboBoxText` Appends @text to the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. This is the same as calling [method@Gtk.ComboBoxText.insert] with a position of -1. Use [class@Gtk.DropDown] A `GtkComboBoxText` a string ID for this value A string Appends @text to the list of strings stored in @combo_box. This is the same as calling [method@Gtk.ComboBoxText.insert_text] with a position of -1. Use [class@Gtk.DropDown] A `GtkComboBoxText` A string Returns the currently active string in @combo_box. If no row is currently selected, %NULL is returned. If @combo_box contains an entry, this function will return its contents (which will not necessarily be an item from the list). Use [class@Gtk.DropDown] a newly allocated string containing the currently active text. Must be freed with g_free(). A `GtkComboBoxText` Inserts @text at @position in the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. See [property@Gtk.ComboBox:id-column]. If @position is negative then @text is appended. Use [class@Gtk.DropDown] A `GtkComboBoxText` An index to insert @text a string ID for this value A string to display Inserts @text at @position in the list of strings stored in @combo_box. If @position is negative then @text is appended. This is the same as calling [method@Gtk.ComboBoxText.insert] with a %NULL ID string. Use [class@Gtk.DropDown] A `GtkComboBoxText` An index to insert @text A string Prepends @text to the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. This is the same as calling [method@Gtk.ComboBoxText.insert] with a position of 0. Use [class@Gtk.DropDown] A `GtkComboBox` a string ID for this value a string Prepends @text to the list of strings stored in @combo_box. This is the same as calling [method@Gtk.ComboBoxText.insert_text] with a position of 0. Use [class@Gtk.DropDown] A `GtkComboBox` A string Removes the string at @position from @combo_box. Use [class@Gtk.DropDown] A `GtkComboBox` Index of the item to remove Removes all the text entries from the combo box. Use [class@Gtk.DropDown] A `GtkComboBoxText` A constant value in a `GtkExpression`. Creates a `GtkExpression` that evaluates to the object given by the arguments. a new `GtkExpression` The type of the object arguments to create the object from Creates an expression that always evaluates to the given `value`. a new `GtkExpression` a `GValue` Gets the value that a constant expression evaluates to. the value a constant `GtkExpression` Describes a constraint between attributes of two widgets, expressed as a linear equation. The typical equation for a constraint is: ``` target.target_attr = source.source_attr × multiplier + constant ``` Each `GtkConstraint` is part of a system that will be solved by a [class@Gtk.ConstraintLayout] in order to allocate and position each child widget or guide. The source and target, as well as their attributes, of a `GtkConstraint` instance are immutable after creation. Creates a new constraint representing a relation between a layout attribute on a source and a layout attribute on a target. the newly created constraint the target of the constraint the attribute of `target` to be set the relation equivalence between `target_attribute` and `source_attribute` the source of the constraint the attribute of `source` to be read a multiplication factor to be applied to `source_attribute` a constant factor to be added to `source_attribute` the strength of the constraint Creates a new constraint representing a relation between a layout attribute on a target and a constant value. the newly created constraint a the target of the constraint the attribute of `target` to be set the relation equivalence between `target_attribute` and `constant` a constant factor to be set on `target_attribute` the strength of the constraint Retrieves the constant factor added to the source attributes' value. a constant factor a `GtkConstraint` Retrieves the multiplication factor applied to the source attribute's value. a multiplication factor a `GtkConstraint` The order relation between the terms of the constraint. a relation type a `GtkConstraint` Retrieves the [iface@Gtk.ConstraintTarget] used as the source for the constraint. If the source is set to `NULL` at creation, the constraint will use the widget using the [class@Gtk.ConstraintLayout] as the source. the source of the constraint a `GtkConstraint` Retrieves the attribute of the source to be read by the constraint. the source's attribute a `GtkConstraint` Retrieves the strength of the constraint. the strength value a `GtkConstraint` Retrieves the [iface@Gtk.ConstraintTarget] used as the target for the constraint. If the targe is set to `NULL` at creation, the constraint will use the widget using the [class@Gtk.ConstraintLayout] as the target. a `GtkConstraintTarget` a `GtkConstraint` Retrieves the attribute of the target to be set by the constraint. the target's attribute a `GtkConstraint` Checks whether the constraint is attached to a [class@Gtk.ConstraintLayout], and it is contributing to the layout. `TRUE` if the constraint is attached a `GtkConstraint` Checks whether the constraint describes a relation between an attribute on the [property@Gtk.Constraint:target] and a constant value. `TRUE` if the constraint is a constant relation a `GtkConstraint` Checks whether the constraint is a required relation for solving the constraint layout. %TRUE if the constraint is required a `GtkConstraint` The constant value to be added to the [property@Gtk.Constraint:source-attribute]. The multiplication factor to be applied to the [property@Gtk.Constraint:source-attribute]. The order relation between the terms of the constraint. The source of the constraint. The constraint will set the [property@Gtk.Constraint:target-attribute] property of the target using the [property@Gtk.Constraint:source-attribute] property of the source. The attribute of the [property@Gtk.Constraint:source] read by the constraint. The strength of the constraint. The strength can be expressed either using one of the symbolic values of the [enum@Gtk.ConstraintStrength] enumeration, or any positive integer value. The target of the constraint. The constraint will set the [property@Gtk.Constraint:target-attribute] property of the target using the [property@Gtk.Constraint:source-attribute] property of the source widget. The attribute of the [property@Gtk.Constraint:target] set by the constraint. The widget attributes that can be used when creating a [class@Constraint]. No attribute, used for constant relations The left edge of a widget, regardless of text direction The right edge of a widget, regardless of text direction The top edge of a widget The bottom edge of a widget The leading edge of a widget, depending on text direction; equivalent to %GTK_CONSTRAINT_ATTRIBUTE_LEFT for LTR languages, and %GTK_CONSTRAINT_ATTRIBUTE_RIGHT for RTL ones The trailing edge of a widget, depending on text direction; equivalent to %GTK_CONSTRAINT_ATTRIBUTE_RIGHT for LTR languages, and %GTK_CONSTRAINT_ATTRIBUTE_LEFT for RTL ones The width of a widget The height of a widget The center of a widget, on the horizontal axis The center of a widget, on the vertical axis The baseline of a widget An invisible layout element in a `GtkConstraintLayout`. The `GtkConstraintLayout` treats guides like widgets. They can be used as the source or target of a `GtkConstraint`. Guides have a minimum, maximum and natural size. Depending on the constraints that are applied, they can act like a guideline that widgets can be aligned to, or like *flexible space*. Unlike a `GtkWidget`, a `GtkConstraintGuide` will not be drawn. Creates a new `GtkConstraintGuide` object. a new `GtkConstraintGuide` object. Gets the maximum size of @guide. a `GtkConstraintGuide` object return location for the maximum width return location for the maximum height Gets the minimum size of @guide. a `GtkConstraintGuide` object return location for the minimum width return location for the minimum height Retrieves the name set using gtk_constraint_guide_set_name(). the name of the guide a `GtkConstraintGuide` Gets the natural size of @guide. a `GtkConstraintGuide` object return location for the natural width return location for the natural height Retrieves the strength set using gtk_constraint_guide_set_strength(). the strength of the constraint on the natural size a `GtkConstraintGuide` Sets the maximum size of @guide. If @guide is attached to a `GtkConstraintLayout`, the constraints will be updated to reflect the new size. a `GtkConstraintGuide` object the new maximum width, or -1 to not change it the new maximum height, or -1 to not change it Sets the minimum size of @guide. If @guide is attached to a `GtkConstraintLayout`, the constraints will be updated to reflect the new size. a `GtkConstraintGuide` object the new minimum width, or -1 to not change it the new minimum height, or -1 to not change it Sets a name for the given `GtkConstraintGuide`. The name is useful for debugging purposes. a `GtkConstraintGuide` a name for the @guide Sets the natural size of @guide. If @guide is attached to a `GtkConstraintLayout`, the constraints will be updated to reflect the new size. a `GtkConstraintGuide` object the new natural width, or -1 to not change it the new natural height, or -1 to not change it Sets the strength of the constraint on the natural size of the given `GtkConstraintGuide`. a `GtkConstraintGuide` the strength of the constraint The maximum height of the guide. The maximum width of the guide. The minimum height of the guide. The minimum width of the guide. A name that identifies the `GtkConstraintGuide`, for debugging. The preferred, or natural, height of the guide. The preferred, or natural, width of the guide. The `GtkConstraintStrength` to be used for the constraint on the natural size of the guide. Uses constraints to describe relations between widgets. `GtkConstraintLayout` is a layout manager that uses relations between widget attributes, expressed via [class@Gtk.Constraint] instances, to measure and allocate widgets. ### How do constraints work Constraints are objects defining the relationship between attributes of a widget; you can read the description of the [class@Gtk.Constraint] class to have a more in depth definition. By taking multiple constraints and applying them to the children of a widget using `GtkConstraintLayout`, it's possible to describe complex layout policies; each constraint applied to a child or to the parent widgets contributes to the full description of the layout, in terms of parameters for resolving the value of each attribute. It is important to note that a layout is defined by the totality of constraints; removing a child, or a constraint, from an existing layout without changing the remaining constraints may result in an unstable or unsolvable layout. Constraints have an implicit "reading order"; you should start describing each edge of each child, as well as their relationship with the parent container, from the top left (or top right, in RTL languages), horizontally first, and then vertically. A constraint-based layout with too few constraints can become "unstable", that is: have more than one solution. The behavior of an unstable layout is undefined. A constraint-based layout with conflicting constraints may be unsolvable, and lead to an unstable layout. You can use the [property@Gtk.Constraint:strength] property of [class@Gtk.Constraint] to "nudge" the layout towards a solution. ### GtkConstraintLayout as GtkBuildable `GtkConstraintLayout` implements the [iface@Gtk.Buildable] interface and has a custom "constraints" element which allows describing constraints in a [class@Gtk.Builder] UI file. An example of a UI definition fragment specifying a constraint: ```xml <object class="GtkConstraintLayout"> <constraints> <constraint target="button" target-attribute="start" relation="eq" source="super" source-attribute="start" constant="12" strength="required" /> <constraint target="button" target-attribute="width" relation="ge" constant="250" strength="strong" /> </constraints> </object> ``` The definition above will add two constraints to the GtkConstraintLayout: - a required constraint between the leading edge of "button" and the leading edge of the widget using the constraint layout, plus 12 pixels - a strong, constant constraint making the width of "button" greater than, or equal to 250 pixels The "target" and "target-attribute" attributes are required. The "source" and "source-attribute" attributes of the "constraint" element are optional; if they are not specified, the constraint is assumed to be a constant. The "relation" attribute is optional; if not specified, the constraint is assumed to be an equality. The "strength" attribute is optional; if not specified, the constraint is assumed to be required. The "source" and "target" attributes can be set to "super" to indicate that the constraint target is the widget using the GtkConstraintLayout. There can be "constant" and "multiplier" attributes. Additionally, the "constraints" element can also contain a description of the `GtkConstraintGuides` used by the layout: ```xml <constraints> <guide min-width="100" max-width="500" name="hspace"/> <guide min-height="64" nat-height="128" name="vspace" strength="strong"/> </constraints> ``` The "guide" element has the following optional attributes: - "min-width", "nat-width", and "max-width", describe the minimum, natural, and maximum width of the guide, respectively - "min-height", "nat-height", and "max-height", describe the minimum, natural, and maximum height of the guide, respectively - "strength" describes the strength of the constraint on the natural size of the guide; if not specified, the constraint is assumed to have a medium strength - "name" describes a name for the guide, useful when debugging ### Using the Visual Format Language Complex constraints can be described using a compact syntax called VFL, or *Visual Format Language*. The Visual Format Language describes all the constraints on a row or column, typically starting from the leading edge towards the trailing one. Each element of the layout is composed by "views", which identify a [iface@Gtk.ConstraintTarget]. For instance: ``` [button]-[textField] ``` Describes a constraint that binds the trailing edge of "button" to the leading edge of "textField", leaving a default space between the two. Using VFL is also possible to specify predicates that describe constraints on attributes like width and height: ``` // Width must be greater than, or equal to 50 [button(>=50)] // Width of button1 must be equal to width of button2 [button1(==button2)] ``` The default orientation for a VFL description is horizontal, unless otherwise specified: ``` // horizontal orientation, default attribute: width H:[button(>=150)] // vertical orientation, default attribute: height V:[button1(==button2)] ``` It's also possible to specify multiple predicates, as well as their strength: ``` // minimum width of button must be 150 // natural width of button can be 250 [button(>=150@required, ==250@medium)] ``` Finally, it's also possible to use simple arithmetic operators: ``` // width of button1 must be equal to width of button2 // divided by 2 plus 12 [button1(button2 / 2 + 12)] ``` Creates a new `GtkConstraintLayout` layout manager. the newly created `GtkConstraintLayout` Adds a constraint to the layout manager. The [property@Gtk.Constraint:source] and [property@Gtk.Constraint:target] properties of `constraint` can be: - set to `NULL` to indicate that the constraint refers to the widget using `layout` - set to the [class@Gtk.Widget] using `layout` - set to a child of the [class@Gtk.Widget] using `layout` - set to a [class@Gtk.ConstraintGuide] that is part of `layout` The @layout acquires the ownership of @constraint after calling this function. a `GtkConstraintLayout` a [class@Gtk.Constraint] Creates a list of constraints from a VFL description. This function is a convenience wrapper around [method@Gtk.ConstraintLayout.add_constraints_from_descriptionv], using variadic arguments to populate the view/target map. the list of [class@Gtk.Constraint]s that were added to the layout a `GtkConstraintLayout` an array of Visual Format Language lines defining a set of constraints the number of lines default horizontal spacing value, or -1 for the fallback value default vertical spacing value, or -1 for the fallback value return location for a `GError` the name of a view in the VFL description, followed by the [iface@Gtk.ConstraintTarget] to which it maps a `NULL`-terminated list of view names and [iface@Gtk.ConstraintTarget]s Creates a list of constraints from a VFL description. The Visual Format Language, VFL, is based on Apple's AutoLayout [VFL](https://developer.apple.com/library/content/documentation/UserExperience/Conceptual/AutolayoutPG/VisualFormatLanguage.html). The `views` dictionary is used to match [iface@Gtk.ConstraintTarget] instances to the symbolic view name inside the VFL. The VFL grammar is: ``` <visualFormatString> = (<orientation>)? (<superview><connection>)? <view>(<connection><view>)* (<connection><superview>)? <orientation> = 'H' | 'V' <superview> = '|' <connection> = '' | '-' <predicateList> '-' | '-' <predicateList> = <simplePredicate> | <predicateListWithParens> <simplePredicate> = <metricName> | <positiveNumber> <predicateListWithParens> = '(' <predicate> (',' <predicate>)* ')' <predicate> = (<relation>)? <objectOfPredicate> (<operatorList>)? ('@' <priority>)? <relation> = '==' | '<=' | '>=' <objectOfPredicate> = <constant> | <viewName> | ('.' <attributeName>)? <priority> = <positiveNumber> | 'required' | 'strong' | 'medium' | 'weak' <constant> = <number> <operatorList> = (<multiplyOperator>)? (<addOperator>)? <multiplyOperator> = [ '*' | '/' ] <positiveNumber> <addOperator> = [ '+' | '-' ] <positiveNumber> <viewName> = [A-Za-z_]([A-Za-z0-9_]*) // A C identifier <metricName> = [A-Za-z_]([A-Za-z0-9_]*) // A C identifier <attributeName> = 'top' | 'bottom' | 'left' | 'right' | 'width' | 'height' | 'start' | 'end' | 'centerX' | 'centerY' | 'baseline' <positiveNumber> // A positive real number parseable by g_ascii_strtod() <number> // A real number parseable by g_ascii_strtod() ``` **Note**: The VFL grammar used by GTK is slightly different than the one defined by Apple, as it can use symbolic values for the constraint's strength instead of numeric values; additionally, GTK allows adding simple arithmetic operations inside predicates. Examples of VFL descriptions are: ``` // Default spacing [button]-[textField] // Width constraint [button(>=50)] // Connection to super view |-50-[purpleBox]-50-| // Vertical layout V:[topField]-10-[bottomField] // Flush views [maroonView][blueView] // Priority [button(100@strong)] // Equal widths [button1(==button2)] // Multiple predicates [flexibleButton(>=70,<=100)] // A complete line of layout |-[find]-[findNext]-[findField(>=20)]-| // Operators [button1(button2 / 3 + 50)] // Named attributes [button1(==button2.height)] ``` the list of [class@Gtk.Constraint] instances that were added to the layout a `GtkConstraintLayout` an array of Visual Format Language lines defining a set of constraints the number of lines default horizontal spacing value, or -1 for the fallback value default vertical spacing value, or -1 for the fallback value a dictionary of `[ name, target ]` pairs; the `name` keys map to the view names in the VFL lines, while the `target` values map to children of the widget using a `GtkConstraintLayout`, or guides Adds a guide to `layout`. A guide can be used as the source or target of constraints, like a widget, but it is not visible. The `layout` acquires the ownership of `guide` after calling this function. a `GtkConstraintLayout` a [class@Gtk.ConstraintGuide] object Returns a `GListModel` to track the constraints that are part of the layout. Calling this function will enable extra internal bookkeeping to track constraints and emit signals on the returned listmodel. It may slow down operations a lot. Applications should try hard to avoid calling this function because of the slowdowns. a `GListModel` tracking the layout's constraints a `GtkConstraintLayout` Returns a `GListModel` to track the guides that are part of the layout. Calling this function will enable extra internal bookkeeping to track guides and emit signals on the returned listmodel. It may slow down operations a lot. Applications should try hard to avoid calling this function because of the slowdowns. a `GListModel` tracking the layout's guides a `GtkConstraintLayout` Removes all constraints from the layout manager. a `GtkConstraintLayout` Removes `constraint` from the layout manager, so that it no longer influences the layout. a `GtkConstraintLayout` a [class@Gtk.Constraint] Removes `guide` from the layout manager, so that it no longer influences the layout. a `GtkConstraintLayout` a [class@Gtk.ConstraintGuide] object `GtkLayoutChild` subclass for children in a `GtkConstraintLayout`. The relation between two terms of a constraint. Less than, or equal Equal Greater than, or equal The strength of a constraint, expressed as a symbolic constant. The strength of a [class@Constraint] can be expressed with any positive integer; the values of this enumeration can be used for readability. The constraint is required towards solving the layout A strong constraint A medium constraint A weak constraint Makes it possible to use an object as source or target in a [class@Gtk.Constraint]. Besides `GtkWidget`, it is also implemented by `GtkConstraintGuide`. Domain for VFL parsing errors. Invalid or unknown symbol Invalid or unknown attribute Invalid or unknown view Invalid or unknown metric Invalid or unknown priority Invalid or unknown relation Registers an error quark for VFL error parsing. the error quark Controls how a content should be made to fit inside an allocation. Make the content fill the entire allocation, without taking its aspect ratio in consideration. The resulting content will appear as stretched if its aspect ratio is different from the allocation aspect ratio. Scale the content to fit the allocation, while taking its aspect ratio in consideration. The resulting content will appear as letterboxed if its aspect ratio is different from the allocation aspect ratio. Cover the entire allocation, while taking the content aspect ratio in consideration. The resulting content will appear as clipped if its aspect ratio is different from the allocation aspect ratio. The content is scaled down to fit the allocation, if needed, otherwise its original size is used. Specifies which corner a child widget should be placed in when packed into a `GtkScrolledWindow.` This is effectively the opposite of where the scroll bars are placed. Place the scrollbars on the right and bottom of the widget (default behaviour). Place the scrollbars on the top and right of the widget. Place the scrollbars on the left and bottom of the widget. Place the scrollbars on the top and left of the widget. Points at a location inside a CSS stream. Errors that can occur while parsing CSS. These errors are unexpected and will cause parts of the given CSS to be ignored. Unknown failure. The given text does not form valid syntax Failed to import a resource The given name has not been defined The given value is not correct Warnings that can occur while parsing CSS. Unlike `GtkCssParserError`s, warnings do not cause the parser to skip any input, but they indicate issues that should be fixed. The given construct is deprecated and will be removed in a future version A syntax construct was used that should be avoided A feature is not implemented A style provider for CSS. It is able to parse CSS-like input in order to style widgets. An application can make GTK parse a specific CSS style sheet by calling [method@Gtk.CssProvider.load_from_file] or [method@Gtk.CssProvider.load_from_resource] and adding the provider with [method@Gtk.StyleContext.add_provider] or [func@Gtk.StyleContext.add_provider_for_display]. In addition, certain files will be read when GTK is initialized. First, the file `$XDG_CONFIG_HOME/gtk-4.0/gtk.css` is loaded if it exists. Then, GTK loads the first existing file among `XDG_DATA_HOME/themes/THEME/gtk-VERSION/gtk-VARIANT.css`, `$HOME/.themes/THEME/gtk-VERSION/gtk-VARIANT.css`, `$XDG_DATA_DIRS/themes/THEME/gtk-VERSION/gtk-VARIANT.css` and `DATADIR/share/themes/THEME/gtk-VERSION/gtk-VARIANT.css`, where `THEME` is the name of the current theme (see the [property@Gtk.Settings:gtk-theme-name] setting), `VARIANT` is the variant to load (see the [property@Gtk.Settings:gtk-application-prefer-dark-theme] setting), `DATADIR` is the prefix configured when GTK was compiled (unless overridden by the `GTK_DATA_PREFIX` environment variable), and `VERSION` is the GTK version number. If no file is found for the current version, GTK tries older versions all the way back to 4.0. To track errors while loading CSS, connect to the [signal@Gtk.CssProvider::parsing-error] signal. Returns a newly created `GtkCssProvider`. A new `GtkCssProvider` Loads @data into @css_provider. This clears any previously loaded information. a `GtkCssProvider` `GBytes` containing the data to load Loads @data into @css_provider. This clears any previously loaded information. Use [method@Gtk.CssProvider.load_from_string] or [method@Gtk.CssProvider.load_from_bytes] instead a `GtkCssProvider` CSS data to be parsed the length of @data in bytes, or -1 for NUL terminated strings Loads the data contained in @file into @css_provider. This clears any previously loaded information. a `GtkCssProvider` `GFile` pointing to a file to load Loads the data contained in @path into @css_provider. This clears any previously loaded information. a `GtkCssProvider` the path of a filename to load, in the GLib filename encoding Loads the data contained in the resource at @resource_path into the @css_provider. This clears any previously loaded information. a `GtkCssProvider` a `GResource` resource path Loads @string into @css_provider. This clears any previously loaded information. a `GtkCssProvider` the CSS to load Loads a theme from the usual theme paths. The actual process of finding the theme might change between releases, but it is guaranteed that this function uses the same mechanism to load the theme that GTK uses for loading its own theme. Using any of the other theme loaders, combine with media queries. a `GtkCssProvider` A theme name variant to load, for example, "dark", or %NULL for the default Converts the @provider into a string representation in CSS format. Using [method@Gtk.CssProvider.load_from_string] with the return value from this function on a new provider created with [ctor@Gtk.CssProvider.new] will basically create a duplicate of this @provider. a new string representing the @provider. the provider to write to a string Define the color scheme used for rendering the user interface. The UI can be set to either [enum@Gtk.InterfaceColorScheme.LIGHT], or [enum@Gtk.InterfaceColorScheme.DARK] mode. Other values will be interpreted the same as [enum@Gtk.InterfaceColorScheme.LIGHT]. This setting is be available for media queries in CSS: ```css @media (prefers-color-scheme: dark) { // some dark mode styling } ``` Changing this setting will reload the style sheet. Define the contrast mode to use for the user interface. When set to [enum@Gtk.InterfaceContrast.MORE] or [enum@Gtk.InterfaceContrast.LESS], the UI is rendered in high or low contrast. When set to [enum@Gtk.InterfaceContrast.NO_PREFERENCE] (the default), the user interface will be rendered in default mode. This setting is be available for media queries in CSS: ```css @media (prefers-contrast: more) { // some style with high contrast } ``` Changing this setting will reload the style sheet. Define the type of reduced motion to use for the user interface. When set to [enum@Gtk.ReducedMotion.REDUCE] the UI is rendered in with reduced motion animations. When set to [enum@Gtk.ReducedMotion.NO_PREFERENCE] (the default), the user interface will be rendered in default mode. This setting is be available for media queries in CSS: ```css @media (prefers-reduced-motion: reduce) { // some style with reduced motion } ``` Changing this setting will reload the style sheet. Signals that a parsing error occurred. The expected error values are in the [error@Gtk.CssParserError] and [enum@Gtk.CssParserWarning] enumerations. The @path, @line and @position describe the actual location of the error as accurately as possible. Parsing errors are never fatal, so the parsing will resume after the error. Errors may however cause parts of the given data or even all of it to not be parsed at all. So it is a useful idea to check that the parsing succeeds by connecting to this signal. Errors in the [enum@Gtk.CssParserWarning] enumeration should not be treated as fatal errors. Note that this signal may be emitted at any time as the css provider may opt to defer parsing parts or all of the input to a later time than when a loading function was called. section the error happened in The parsing error Defines a part of a CSS document. Because sections are nested into one another, you can use [method@CssSection.get_parent] to get the containing region. Creates a new `GtkCssSection` referring to the section in the given `file` from the `start` location to the `end` location. a new `GtkCssSection` The file this section refers to The start location The end location Creates a new `GtkCssSection` referring to the section in the given `file` or the given `bytes` from the `start` location to the `end` location. a new `GtkCssSection` The file this section refers to The bytes this sections refers to The start location The end location Gets the bytes that @section was parsed from. the `GBytes` from which the `section` was parsed the section Returns the location in the CSS document where this section ends. The end location of this section the section Gets the file that @section was parsed from. If no such file exists, for example because the CSS was loaded via [method@Gtk.CssProvider.load_from_data], then `NULL` is returned. the `GFile` from which the `section` was parsed the section Gets the parent section for the given `section`. The parent section is the section that contains this `section`. A special case are sections of type `GTK_CSS_SECTION_DOCUMENT`. Their parent will either be `NULL` if they are the original CSS document that was loaded by [method@Gtk.CssProvider.load_from_file] or a section of type `GTK_CSS_SECTION_IMPORT` if it was loaded with an `@import` rule from a different file. the parent section the section Returns the location in the CSS document where this section starts. The start location of this section the section Prints the `section` into `string` in a human-readable form. This is a form like `gtk.css:32:1-23` to denote line 32, characters 1 to 23 in the file `gtk.css`. a section a `GString` to print to Increments the reference count on `section`. the CSS section itself. a `GtkCssSection` Prints the section into a human-readable text form using [method@Gtk.CssSection.print]. A new string. a `GtkCssSection` Decrements the reference count on `section`, freeing the structure if the reference count reaches 0. a `GtkCssSection` A CSS style change. A function to be used by `GtkCustomLayout` to allocate a widget. the widget to allocate the new width of the widget the new height of the widget the new baseline of the widget, or -1 Determines whether to include items with a callback. Creates a new filter using the given function to filter items. If @match_func is `NULL`, the filter matches all items. If the filter func changes its filtering behavior, [method@Gtk.Filter.changed] needs to be called. a new `GtkCustomFilter` function to filter items user data to pass to @match_func destroy notify for @user_data Sets the function used for filtering items. If @match_func is `NULL`, the filter matches all items. If the filter func changes its filtering behavior, [method@Gtk.Filter.changed] needs to be called. If a previous function was set, its @user_destroy will be called. a custom filter function to filter items user data to pass to @match_func destroy notify for @user_data User function that is called to determine if the @item should be matched. If the filter matches the item, this function must return true. If the item should be filtered out, false must be returned. true to keep the item around the item to be matched user data Uses closures for size negotiation. A `GtkCustomLayout` uses closures matching to the old `GtkWidget` virtual functions for size negotiation, as a convenience API to ease the porting towards the corresponding `GtkLayoutManager` virtual functions. Creates a new legacy layout manager. Legacy layout managers map to the old `GtkWidget` size negotiation virtual functions, and are meant to be used during the transition from layout containers to layout manager delegates. the newly created `GtkCustomLayout` a function to retrieve the `GtkSizeRequestMode` of the widget using the layout; the default request mode is %GTK_SIZE_REQUEST_CONSTANT_SIZE a function to measure the widget using the layout manager a function to allocate the children of the widget using the layout manager A function to be used by `GtkCustomLayout` to measure a widget. the widget to be measured the direction to be measured the size to be measured for the measured minimum size of the widget the measured natural size of the widget the measured minimum baseline of the widget the measured natural baseline of the widget Queries a widget for its preferred size request mode. the size request mode the widget to be queried Sorts items via a callback function. Creates a new `GtkSorter` that works by calling @sort_func to compare items. If @sort_func is %NULL, all items are considered equal. a new `GtkCustomSorter` the `GCompareDataFunc` to use for sorting user data to pass to @sort_func destroy notify for @user_data Sets (or unsets) the function used for sorting items. If @sort_func is %NULL, all items are considered equal. If the sort func changes its sorting behavior, gtk_sorter_changed() needs to be called. If a previous function was set, its @user_destroy will be called now. a `GtkCustomSorter` function to sort items user data to pass to @match_func destroy notify for @user_data Whether the `type` debug flag is set. type to check Flags to use with gtk_set_debug_flags(). Settings these flags causes GTK to print out different types of debugging information. Some of these flags are only available when GTK has been configured with `-Ddebug=true`. Information about GtkTextView Information about GtkTreeView Information about keyboard shortcuts Information about modules and extensions Information about size allocation Information about icon themes Information about printing Trace GtkBuilder operation Information about size requests Disable the style property cache Open the GTK inspector Show touch UI elements for pointer events. Information about actions and menu models Information from layout managers Include debug render nodes in the generated snapshots Information from the constraints solver Log unused GtkBuilder objects Information about accessibility state changes Information about icon fallback. Inverts the default text-direction. Information about deprecated CSS features. Information about deprecated GtkBuilder features. Information about session saving. Passed to various keybinding signals for deleting text. Delete characters. Delete only the portion of the word to the left/right of cursor if we’re in the middle of a word. Delete words. Delete display-lines. Display-lines refers to the visible lines, with respect to the current line breaks. As opposed to paragraphs, which are defined by line breaks in the input. Delete only the portion of the display-line to the left/right of cursor. Delete to the end of the paragraph. Like C-k in Emacs (or its reverse). Delete entire line. Like C-k in pico. Delete only whitespace. Like M-\ in Emacs. Dialogs are a convenient way to prompt the user for a small amount of input. <picture> <source srcset="dialog-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkDialog" src="dialog.png"> </picture> Typical uses are to display a message, ask a question, or anything else that does not require extensive effort on the user’s part. The main area of a `GtkDialog` is called the "content area", and is yours to populate with widgets such a `GtkLabel` or `GtkEntry`, to present your information, questions, or tasks to the user. In addition, dialogs allow you to add "action widgets". Most commonly, action widgets are buttons. Depending on the platform, action widgets may be presented in the header bar at the top of the window, or at the bottom of the window. To add action widgets, create your `GtkDialog` using [ctor@Gtk.Dialog.new_with_buttons], or use [method@Gtk.Dialog.add_button], [method@Gtk.Dialog.add_buttons], or [method@Gtk.Dialog.add_action_widget]. `GtkDialogs` uses some heuristics to decide whether to add a close button to the window decorations. If any of the action buttons use the response ID %GTK_RESPONSE_CLOSE or %GTK_RESPONSE_CANCEL, the close button is omitted. Clicking a button that was added as an action widget will emit the [signal@Gtk.Dialog::response] signal with a response ID that you specified. GTK will never assign a meaning to positive response IDs; these are entirely user-defined. But for convenience, you can use the response IDs in the [enum@Gtk.ResponseType] enumeration (these all have values less than zero). If a dialog receives a delete event, the [signal@Gtk.Dialog::response] signal will be emitted with the %GTK_RESPONSE_DELETE_EVENT response ID. Dialogs are created with a call to [ctor@Gtk.Dialog.new] or [ctor@Gtk.Dialog.new_with_buttons]. The latter is recommended; it allows you to set the dialog title, some convenient flags, and add buttons. A “modal” dialog (that is, one which freezes the rest of the application from user input), can be created by calling [method@Gtk.Window.set_modal] on the dialog. When using [ctor@Gtk.Dialog.new_with_buttons], you can also pass the %GTK_DIALOG_MODAL flag to make a dialog modal. For the simple dialog in the following example, a [class@Gtk.MessageDialog] would save some effort. But you’d need to create the dialog contents manually if you had more than a simple message in the dialog. An example for simple `GtkDialog` usage: ```c // Function to open a dialog box with a message void quick_message (GtkWindow *parent, char *message) { GtkWidget *dialog, *label, *content_area; GtkDialogFlags flags; // Create the widgets flags = GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_dialog_new_with_buttons ("Message", parent, flags, _("_OK"), GTK_RESPONSE_NONE, NULL); content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog)); label = gtk_label_new (message); // Ensure that the dialog box is destroyed when the user responds g_signal_connect_swapped (dialog, "response", G_CALLBACK (gtk_window_destroy), dialog); // Add the label, and show everything we’ve added gtk_box_append (GTK_BOX (content_area), label); gtk_widget_show (dialog); } ``` # GtkDialog as GtkBuildable The `GtkDialog` implementation of the `GtkBuildable` interface exposes the @content_area as an internal child with the name “content_area”. `GtkDialog` supports a custom `<action-widgets>` element, which can contain multiple `<action-widget>` elements. The “response” attribute specifies a numeric response, and the content of the element is the id of widget (which should be a child of the dialogs @action_area). To mark a response as default, set the “default” attribute of the `<action-widget>` element to true. `GtkDialog` supports adding action widgets by specifying “action” as the “type” attribute of a `<child>` element. The widget will be added either to the action area or the headerbar of the dialog, depending on the “use-header-bar” property. The response id has to be associated with the action widget using the `<action-widgets>` element. An example of a `GtkDialog` UI definition fragment: ```xml <object class="GtkDialog" id="dialog1"> <child type="action"> <object class="GtkButton" id="button_cancel"/> </child> <child type="action"> <object class="GtkButton" id="button_ok"> </object> </child> <action-widgets> <action-widget response="cancel">button_cancel</action-widget> <action-widget response="ok" default="true">button_ok</action-widget> </action-widgets> </object> ``` # Accessibility `GtkDialog` uses the %GTK_ACCESSIBLE_ROLE_DIALOG role. Use [class@Gtk.Window] instead Creates a new dialog box. Widgets should not be packed into the `GtkWindow` directly, but into the @content_area and @action_area, as described above. Use [class@Gtk.Window] instead the new dialog as a `GtkWidget` Creates a new `GtkDialog` with the given title and transient parent. The @flags argument can be used to make the dialog modal, have it destroyed along with its transient parent, or make it use a headerbar. Button text/response ID pairs should be listed in pairs, with a %NULL pointer ending the list. Button text can be arbitrary text. A response ID can be any positive number, or one of the values in the [enum@Gtk.ResponseType] enumeration. If the user clicks one of these buttons, `GtkDialog` will emit the [signal@Gtk.Dialog::response] signal with the corresponding response ID. If a `GtkDialog` receives a delete event, it will emit ::response with a response ID of %GTK_RESPONSE_DELETE_EVENT. However, destroying a dialog does not emit the ::response signal; so be careful relying on ::response when using the %GTK_DIALOG_DESTROY_WITH_PARENT flag. Here’s a simple example: ```c GtkWindow *main_app_window; // Window the dialog should show up on GtkWidget *dialog; GtkDialogFlags flags = GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_dialog_new_with_buttons ("My dialog", main_app_window, flags, _("_OK"), GTK_RESPONSE_ACCEPT, _("_Cancel"), GTK_RESPONSE_REJECT, NULL); ``` Use [class@Gtk.Window] instead a new `GtkDialog` Title of the dialog Transient parent of the dialog from `GtkDialogFlags` text to go in first button response ID for first button, then additional buttons, ending with %NULL Signal emitted when the user uses a keybinding to close the dialog. Emits the ::response signal with the given response ID. Used to indicate that the user has responded to the dialog in some way. Use [class@Gtk.Window] instead a `GtkDialog` response ID Adds an activatable widget to the action area of a `GtkDialog`. GTK connects a signal handler that will emit the [signal@Gtk.Dialog::response] signal on the dialog when the widget is activated. The widget is appended to the end of the dialog’s action area. If you want to add a non-activatable widget, simply pack it into the @action_area field of the `GtkDialog` struct. Use [class@Gtk.Window] instead a `GtkDialog` an activatable widget response ID for @child Adds a button with the given text. GTK arranges things so that clicking the button will emit the [signal@Gtk.Dialog::response] signal with the given @response_id. The button is appended to the end of the dialog’s action area. The button widget is returned, but usually you don’t need it. Use [class@Gtk.Window] instead the `GtkButton` widget that was added a `GtkDialog` text of button response ID for the button Adds multiple buttons. This is the same as calling [method@Gtk.Dialog.add_button] repeatedly. The variable argument list should be %NULL-terminated as with [ctor@Gtk.Dialog.new_with_buttons]. Each button must have both text and response ID. Use [class@Gtk.Window] instead a `GtkDialog` button text response ID for first button, then more text-response_id pairs Returns the content area of @dialog. Use [class@Gtk.Window] instead the content area `GtkBox`. a `GtkDialog` Returns the header bar of @dialog. Note that the headerbar is only used by the dialog if the [property@Gtk.Dialog:use-header-bar] property is %TRUE. Use [class@Gtk.Window] instead the header bar a `GtkDialog` Gets the response id of a widget in the action area of a dialog. Use [class@Gtk.Window] instead the response id of @widget, or %GTK_RESPONSE_NONE if @widget doesn’t have a response id set. a `GtkDialog` a widget in the action area of @dialog Gets the widget button that uses the given response ID in the action area of a dialog. Use [class@Gtk.Window] instead the @widget button that uses the given @response_id a `GtkDialog` the response ID used by the @dialog widget Emits the ::response signal with the given response ID. Used to indicate that the user has responded to the dialog in some way. Use [class@Gtk.Window] instead a `GtkDialog` response ID Sets the default widget for the dialog based on the response ID. Pressing “Enter” normally activates the default widget. Use [class@Gtk.Window] instead a `GtkDialog` a response ID A convenient way to sensitize/desensitize dialog buttons. Calls `gtk_widget_set_sensitive (widget, @setting)` for each widget in the dialog’s action area with the given @response_id. Use [class@Gtk.Window] instead a `GtkDialog` a response ID %TRUE for sensitive %TRUE if the dialog uses a headerbar for action buttons instead of the action-area. For technical reasons, this property is declared as an integer property, but you should only set it to %TRUE or %FALSE. ## Creating a dialog with headerbar Builtin `GtkDialog` subclasses such as [class@Gtk.ColorChooserDialog] set this property according to platform conventions (using the [property@Gtk.Settings:gtk-dialogs-use-header] setting). Here is how you can achieve the same: ```c g_object_get (settings, "gtk-dialogs-use-header", &header, NULL); dialog = g_object_new (GTK_TYPE_DIALOG, header, TRUE, NULL); ``` Use [class@Gtk.Window] instead Emitted when the user uses a keybinding to close the dialog. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is the Escape key. Use [class@Gtk.Window] instead Emitted when an action widget is clicked. The signal is also emitted when the dialog receives a delete event, and when [method@Gtk.Dialog.response] is called. On a delete event, the response ID is %GTK_RESPONSE_DELETE_EVENT. Otherwise, it depends on which action widget was clicked. Use [class@Gtk.Window] instead the response ID The parent class. Signal emitted when an action widget is activated. a `GtkDialog` response ID Signal emitted when the user uses a keybinding to close the dialog. Error codes in the `GTK_DIALOG_ERROR` domain that can be returned by async dialog functions. Generic error condition for when an operation fails and no more specific code is applicable The async function call was cancelled via its `GCancellable` The operation was cancelled by the user (via a Cancel or Close button) Registers an error quark for an operation that requires a dialog if necessary. the error quark Flags used to influence dialog construction. There is no replacement. Make the constructed dialog modal Destroy the dialog when its parent is destroyed Create dialog with actions in header bar instead of action area Focus movement types. Move forward. Move backward. Move up. Move down. Move left. Move right. A list model that wraps [method@Gio.File.enumerate_children_async]. It presents a `GListModel` and fills it asynchronously with the `GFileInfo`s returned from that function. Enumeration will start automatically when the [property@Gtk.DirectoryList:file] property is set. While the `GtkDirectoryList` is being filled, the [property@Gtk.DirectoryList:loading] property will be set to %TRUE. You can listen to that property if you want to show information like a `GtkSpinner` or a "Loading..." text. If loading fails at any point, the [property@Gtk.DirectoryList:error] property will be set to give more indication about the failure. The `GFileInfo`s returned from a `GtkDirectoryList` have the "standard::file" attribute set to the `GFile` they refer to. This way you can get at the file that is referred to in the same way you would via g_file_enumerator_get_child(). This means you do not need access to the `GtkDirectoryList`, but can access the `GFile` directly from the `GFileInfo` when operating with a `GtkListView` or similar. Creates a new `GtkDirectoryList`. The `GtkDirectoryList` is querying the given @file with the given @attributes. a new `GtkDirectoryList` The attributes to query with The file to query Gets the attributes queried on the children. The queried attributes a `GtkDirectoryList` Gets the loading error, if any. If an error occurs during the loading process, the loading process will finish and this property allows querying the error that happened. This error will persist until a file is loaded again. An error being set does not mean that no files were loaded, and all successfully queried files will remain in the list. The loading error or %NULL if loading finished successfully a `GtkDirectoryList` Gets the file whose children are currently enumerated. The file whose children are enumerated a `GtkDirectoryList` Gets the IO priority set via gtk_directory_list_set_io_priority(). The IO priority. a `GtkDirectoryList` Returns whether the directory list is monitoring the directory for changes. %TRUE if the directory is monitored a `GtkDirectoryList` Returns %TRUE if the children enumeration is currently in progress. Files will be added to @self from time to time while loading is going on. The order in which are added is undefined and may change in between runs. %TRUE if @self is loading a `GtkDirectoryList` Sets the @attributes to be enumerated and starts the enumeration. If @attributes is %NULL, the list of file infos will still be created, it will just not contain any extra attributes. a `GtkDirectoryList` the attributes to enumerate Sets the @file to be enumerated and starts the enumeration. If @file is %NULL, the result will be an empty list. a `GtkDirectoryList` the `GFile` to be enumerated Sets the IO priority to use while loading directories. Setting the priority while @self is loading will reprioritize the ongoing load as soon as possible. The default IO priority is %G_PRIORITY_DEFAULT, which is higher than the GTK redraw priority. If you are loading a lot of directories in parallel, lowering it to something like %G_PRIORITY_DEFAULT_IDLE may increase responsiveness. a `GtkDirectoryList` IO priority to use Sets whether the directory list will monitor the directory for changes. If monitoring is enabled, the ::items-changed signal will be emitted when the directory contents change. When monitoring is turned on after the initial creation of the directory list, the directory is reloaded to avoid missing files that appeared between the initial loading and when monitoring was turned on. a `GtkDirectoryList` %TRUE to monitor the directory for changes The attributes to query. Error encountered while loading files. File to query. Priority used when loading. The type of items. See [method@Gio.ListModel.get_item_type]. %TRUE if files are being loaded. %TRUE if the directory is monitored for changed. The number of items. See [method@Gio.ListModel.get_n_items]. A `GtkRoot` implementation for drag icons. A drag icon moves with the pointer during a Drag-and-Drop operation and is destroyed when the drag ends. To set up a drag icon and associate it with an ongoing drag operation, use [ctor@Gtk.DragIcon.get_for_drag] to get the icon for a drag. You can then use it like any other widget and use [method@Gtk.DragIcon.set_child] to set whatever widget should be used for the drag icon. Keep in mind that drag icons do not allow user input. Gets the `GtkDragIcon` in use with @drag. If no drag icon exists yet, a new one will be created and shown. the `GtkDragIcon` a `GdkDrag` Creates a widget that can be used as a drag icon for the given @value. Supported types include strings, `GdkRGBA` and `GtkTextBuffer`. If GTK does not know how to create a widget for a given value, it will return %NULL. This method is used to set the default drag icon on drag-and-drop operations started by `GtkDragSource`, so you don't need to set a drag icon using this function there. A new `GtkWidget` for displaying @value as a drag icon. a `GValue` Creates a `GtkDragIcon` that shows @paintable, and associates it with the drag operation. The hotspot position on the paintable is aligned with the hotspot of the cursor. a `GdkDrag` a `GdkPaintable` to display X coordinate of the hotspot Y coordinate of the hotspot Gets the widget currently used as drag icon. The drag icon a `GtkDragIcon` Sets the widget to display as the drag icon. a `GtkDragIcon` a `GtkWidget` The widget to display as drag icon. An event controller to initiate Drag-And-Drop operations. `GtkDragSource` can be set up with the necessary ingredients for a DND operation ahead of time. This includes the source for the data that is being transferred, in the form of a [class@Gdk.ContentProvider], the desired action, and the icon to use during the drag operation. After setting it up, the drag source must be added to a widget as an event controller, using [method@Gtk.Widget.add_controller]. ```c static void my_widget_init (MyWidget *self) { GtkDragSource *drag_source = gtk_drag_source_new (); g_signal_connect (drag_source, "prepare", G_CALLBACK (on_drag_prepare), self); g_signal_connect (drag_source, "drag-begin", G_CALLBACK (on_drag_begin), self); gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (drag_source)); } ``` Setting up the content provider and icon ahead of time only makes sense when the data does not change. More commonly, you will want to set them up just in time. To do so, `GtkDragSource` has [signal@Gtk.DragSource::prepare] and [signal@Gtk.DragSource::drag-begin] signals. The ::prepare signal is emitted before a drag is started, and can be used to set the content provider and actions that the drag should be started with. ```c static GdkContentProvider * on_drag_prepare (GtkDragSource *source, double x, double y, MyWidget *self) { // This widget supports two types of content: GFile objects // and GdkPixbuf objects; GTK will handle the serialization // of these types automatically GFile *file = my_widget_get_file (self); GdkPixbuf *pixbuf = my_widget_get_pixbuf (self); return gdk_content_provider_new_union ((GdkContentProvider *[2]) { gdk_content_provider_new_typed (G_TYPE_FILE, file), gdk_content_provider_new_typed (GDK_TYPE_PIXBUF, pixbuf), }, 2); } ``` The ::drag-begin signal is emitted after the `GdkDrag` object has been created, and can be used to set up the drag icon. ```c static void on_drag_begin (GtkDragSource *source, GdkDrag *drag, MyWidget *self) { // Set the widget as the drag icon GdkPaintable *paintable = gtk_widget_paintable_new (GTK_WIDGET (self)); gtk_drag_source_set_icon (source, paintable, 0, 0); g_object_unref (paintable); } ``` During the DND operation, `GtkDragSource` emits signals that can be used to obtain updates about the status of the operation, but it is not normally necessary to connect to any signals, except for one case: when the supported actions include %GDK_ACTION_MOVE, you need to listen for the [signal@Gtk.DragSource::drag-end] signal and delete the data after it has been transferred. Creates a new `GtkDragSource` object. the new `GtkDragSource` Cancels a currently ongoing drag operation. a `GtkDragSource` Gets the actions that are currently set on the `GtkDragSource`. the actions set on @source a `GtkDragSource` Gets the current content provider of a `GtkDragSource`. the `GdkContentProvider` of @source a `GtkDragSource` Returns the underlying `GdkDrag` object for an ongoing drag. the `GdkDrag` of the current drag operation a `GtkDragSource` Sets the actions on the `GtkDragSource`. During a DND operation, the actions are offered to potential drop targets. If @actions include %GDK_ACTION_MOVE, you need to listen to the [signal@Gtk.DragSource::drag-end] signal and handle @delete_data being %TRUE. This function can be called before a drag is started, or in a handler for the [signal@Gtk.DragSource::prepare] signal. a `GtkDragSource` the actions to offer Sets a content provider on a `GtkDragSource`. When the data is requested in the cause of a DND operation, it will be obtained from the content provider. This function can be called before a drag is started, or in a handler for the [signal@Gtk.DragSource::prepare] signal. You may consider setting the content provider back to %NULL in a [signal@Gtk.DragSource::drag-end] signal handler. a `GtkDragSource` a `GdkContentProvider` Sets a paintable to use as icon during DND operations. The hotspot coordinates determine the point on the icon that gets aligned with the hotspot of the cursor. If @paintable is %NULL, a default icon is used. This function can be called before a drag is started, or in a [signal@Gtk.DragSource::prepare] or [signal@Gtk.DragSource::drag-begin] signal handler. a `GtkDragSource` the `GdkPaintable` to use as icon the hotspot X coordinate on the icon the hotspot Y coordinate on the icon The actions that are supported by drag operations from the source. Note that you must handle the [signal@Gtk.DragSource::drag-end] signal if the actions include %GDK_ACTION_MOVE. The data that is offered by drag operations from this source. Emitted on the drag source when a drag is started. It can be used to e.g. set a custom drag icon with [method@Gtk.DragSource.set_icon]. the `GdkDrag` object Emitted on the drag source when a drag has failed. The signal handler may handle a failed drag operation based on the type of error. It should return %TRUE if the failure has been handled and the default "drag operation failed" animation should not be shown. %TRUE if the failed drag operation has been already handled the `GdkDrag` object information on why the drag failed Emitted on the drag source when a drag is finished. A typical reason to connect to this signal is to undo things done in [signal@Gtk.DragSource::prepare] or [signal@Gtk.DragSource::drag-begin] handlers. the `GdkDrag` object %TRUE if the drag was performing %GDK_ACTION_MOVE, and the data should be deleted Emitted when a drag is about to be initiated. It returns the `GdkContentProvider` to use for the drag that is about to start. The default handler for this signal returns the value of the [property@Gtk.DragSource:content] property, so if you set up that property ahead of time, you don't need to connect to this signal. a `GdkContentProvider` the X coordinate of the drag starting point the Y coordinate of the drag starting point Allows drawing with cairo. <picture> <source srcset="drawingarea-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkDrawingArea" src="drawingarea.png"> </picture> It’s essentially a blank widget; you can draw on it. After creating a drawing area, the application may want to connect to: - The [signal@Gtk.Widget::realize] signal to take any necessary actions when the widget is instantiated on a particular display. (Create GDK resources in response to this signal.) - The [signal@Gtk.DrawingArea::resize] signal to take any necessary actions when the widget changes size. - Call [method@Gtk.DrawingArea.set_draw_func] to handle redrawing the contents of the widget. The following code portion demonstrates using a drawing area to display a circle in the normal widget foreground color. ## Simple GtkDrawingArea usage ```c static void draw_function (GtkDrawingArea *area, cairo_t *cr, int width, int height, gpointer data) { GdkRGBA color; cairo_arc (cr, width / 2.0, height / 2.0, MIN (width, height) / 2.0, 0, 2 * G_PI); gtk_widget_get_color (GTK_WIDGET (area), &color); gdk_cairo_set_source_rgba (cr, &color); cairo_fill (cr); } int main (int argc, char **argv) { gtk_init (); GtkWidget *area = gtk_drawing_area_new (); gtk_drawing_area_set_content_width (GTK_DRAWING_AREA (area), 100); gtk_drawing_area_set_content_height (GTK_DRAWING_AREA (area), 100); gtk_drawing_area_set_draw_func (GTK_DRAWING_AREA (area), draw_function, NULL, NULL); return 0; } ``` The draw function is normally called when a drawing area first comes onscreen, or when it’s covered by another window and then uncovered. You can also force a redraw by adding to the “damage region” of the drawing area’s window using [method@Gtk.Widget.queue_draw]. This will cause the drawing area to call the draw function again. The available routines for drawing are documented in the [Cairo documentation](https://www.cairographics.org/manual/); GDK offers additional API to integrate with Cairo, like [func@Gdk.cairo_set_source_rgba] or [func@Gdk.cairo_set_source_pixbuf]. To receive mouse events on a drawing area, you will need to use event controllers. To receive keyboard events, you will need to set the “can-focus” property on the drawing area, and you should probably draw some user-visible indication that the drawing area is focused. If you need more complex control over your widget, you should consider creating your own `GtkWidget` subclass. Creates a new drawing area. a new `GtkDrawingArea` Retrieves the content height of the `GtkDrawingArea`. The height requested for content of the drawing area a `GtkDrawingArea` Retrieves the content width of the `GtkDrawingArea`. The width requested for content of the drawing area a `GtkDrawingArea` Sets the desired height of the contents of the drawing area. Note that because widgets may be allocated larger sizes than they requested, it is possible that the actual height passed to your draw function is larger than the height set here. You can use [method@Gtk.Widget.set_valign] to avoid that. If the height is set to 0 (the default), the drawing area may disappear. a `GtkDrawingArea` the height of contents Sets the desired width of the contents of the drawing area. Note that because widgets may be allocated larger sizes than they requested, it is possible that the actual width passed to your draw function is larger than the width set here. You can use [method@Gtk.Widget.set_halign] to avoid that. If the width is set to 0 (the default), the drawing area may disappear. a `GtkDrawingArea` the width of contents Setting a draw function is the main thing you want to do when using a drawing area. The draw function is called whenever GTK needs to draw the contents of the drawing area to the screen. The draw function will be called during the drawing stage of GTK. In the drawing stage it is not allowed to change properties of any GTK widgets or call any functions that would cause any properties to be changed. You should restrict yourself exclusively to drawing your contents in the draw function. If what you are drawing does change, call [method@Gtk.Widget.queue_draw] on the drawing area. This will cause a redraw and will call @draw_func again. a `GtkDrawingArea` callback that lets you draw the drawing area's contents user data passed to @draw_func destroy notifier for @user_data The content height. The content width. Emitted once when the widget is realized, and then each time the widget is changed while realized. This is useful in order to keep state up to date with the widget size, like for instance a backing surface. the width of the viewport the height of the viewport Whenever @drawing_area needs to redraw, this function will be called. This function should exclusively redraw the contents of the drawing area and must not call any widget functions that cause changes. the `GtkDrawingArea` to redraw the context to draw to the actual width of the contents. This value will be at least as wide as GtkDrawingArea:width. the actual height of the contents. This value will be at least as wide as GtkDrawingArea:height. user data An event controller tracking the pointer during Drag-and-Drop operations. It is modeled after [class@Gtk.EventControllerMotion] so if you have used that, this should feel really familiar. This controller is not able to accept drops, use [class@Gtk.DropTarget] for that purpose. Creates a new event controller that will handle pointer motion events during drag and drop. a new `GtkDropControllerMotion` Returns if a Drag-and-Drop operation is within the widget @self or one of its children. %TRUE if a dragging pointer is within @self or one of its children. a `GtkDropControllerMotion` Returns the `GdkDrop` of a current Drag-and-Drop operation over the widget of @self. The `GdkDrop` currently happening within @self a `GtkDropControllerMotion` Returns if a Drag-and-Drop operation is within the widget @self, not one of its children. %TRUE if a dragging pointer is within @self but not one of its children a `GtkDropControllerMotion` Whether the pointer of a Drag-and-Drop operation is in the controller's widget or a descendant. See also [property@Gtk.DropControllerMotion:is-pointer]. When handling crossing events, this property is updated before [signal@Gtk.DropControllerMotion::enter], but after [signal@Gtk.DropControllerMotion::leave] is emitted. The ongoing drop operation over the controller's widget or its descendant. If no drop operation is going on, this property returns %NULL. The event controller should not modify the @drop, but it might want to query its properties. When handling crossing events, this property is updated before [signal@Gtk.DropControllerMotion::enter], but after [signal@Gtk.DropControllerMotion::leave] is emitted. Whether the pointer is in the controllers widget itself, as opposed to in a descendent widget. See also [property@Gtk.DropControllerMotion:contains-pointer]. When handling crossing events, this property is updated before [signal@Gtk.DropControllerMotion::enter], but after [signal@Gtk.DropControllerMotion::leave] is emitted. Signals that the pointer has entered the widget. coordinates of pointer location coordinates of pointer location Signals that the pointer has left the widget. Emitted when the pointer moves inside the widget. the x coordinate the y coordinate Allows the user to choose an item from a list of options. <picture> <source srcset="drop-down-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkDropDown" src="drop-down.png"> </picture> The `GtkDropDown` displays the [selected][property@Gtk.DropDown:selected] choice. The options are given to `GtkDropDown` in the form of `GListModel` and how the individual options are represented is determined by a [class@Gtk.ListItemFactory]. The default factory displays simple strings, and adds a checkmark to the selected item in the popup. To set your own factory, use [method@Gtk.DropDown.set_factory]. It is possible to use a separate factory for the items in the popup, with [method@Gtk.DropDown.set_list_factory]. `GtkDropDown` knows how to obtain strings from the items in a [class@Gtk.StringList]; for other models, you have to provide an expression to find the strings via [method@Gtk.DropDown.set_expression]. `GtkDropDown` can optionally allow search in the popup, which is useful if the list of options is long. To enable the search entry, use [method@Gtk.DropDown.set_enable_search]. Here is a UI definition example for `GtkDropDown` with a simple model: ```xml <object class="GtkDropDown"> <property name="model"> <object class="GtkStringList"> <items> <item translatable="yes">Factory</item> <item translatable="yes">Home</item> <item translatable="yes">Subway</item> </items> </object> </property> </object> ``` If a `GtkDropDown` is created in this manner, or with [ctor@Gtk.DropDown.new_from_strings], for instance, the object returned from [method@Gtk.DropDown.get_selected_item] will be a [class@Gtk.StringObject]. To learn more about the list widget framework, see the [overview](section-list-widget.html). ## CSS nodes `GtkDropDown` has a single CSS node with name dropdown, with the button and popover nodes as children. ## Accessibility `GtkDropDown` uses the [enum@Gtk.AccessibleRole.combo_box] role. Creates a new `GtkDropDown`. You may want to call [method@Gtk.DropDown.set_factory] to set up a way to map its items to widgets. a new `GtkDropDown` the model to use the expression to use Creates a new `GtkDropDown` that is populated with the strings. a new `GtkDropDown` The strings to put in the dropdown Returns whether search is enabled. %TRUE if the popup includes a search entry a `GtkDropDown` Gets the expression set that is used to obtain strings from items. See [method@Gtk.DropDown.set_expression]. a `GtkExpression` a `GtkDropDown` Gets the factory that's currently used to populate list items. The factory returned by this function is always used for the item in the button. It is also used for items in the popup if [property@Gtk.DropDown:list-factory] is not set. The factory in use a `GtkDropDown` Gets the factory that's currently used to create header widgets for the popup. The factory in use a `GtkDropDown` Gets the factory that's currently used to populate list items in the popup. The factory in use a `GtkDropDown` Gets the model that provides the displayed items. The model in use a `GtkDropDown` Returns the match mode that the search filter is using. the match mode of the search filter a `GtkDropDown` Gets the position of the selected item. the position of the selected item, or %GTK_INVALID_LIST_POSITION if no item is selected a `GtkDropDown` Gets the selected item. If no item is selected, %NULL is returned. The selected item a `GtkDropDown` Returns whether to show an arrow within the widget. %TRUE if an arrow will be shown. a `GtkDropDown` Sets whether a search entry will be shown in the popup that allows to search for items in the list. Note that [property@Gtk.DropDown:expression] must be set for search to work. a `GtkDropDown` whether to enable search Sets the expression that gets evaluated to obtain strings from items. This is used for search in the popup. The expression must have a value type of %G_TYPE_STRING. a `GtkDropDown` a `GtkExpression` Sets the `GtkListItemFactory` to use for populating list items. a `GtkDropDown` the factory to use Sets the `GtkListItemFactory` to use for creating header widgets for the popup. a `GtkDropDown` the factory to use Sets the `GtkListItemFactory` to use for populating list items in the popup. a `GtkDropDown` the factory to use Sets the `GListModel` to use. a `GtkDropDown` the model to use Sets the match mode for the search filter. a `GtkDropDown` the new match mode Selects the item at the given position. a `GtkDropDown` the position of the item to select, or %GTK_INVALID_LIST_POSITION Sets whether an arrow will be displayed within the widget. a `GtkDropDown` whether to show an arrow within the widget Whether to show a search entry in the popup. Note that search requires [property@Gtk.DropDown:expression] to be set. An expression to evaluate to obtain strings to match against the search term. See [property@Gtk.DropDown:enable-search] for how to enable search. If [property@Gtk.DropDown:factory] is not set, the expression is also used to bind strings to labels produced by a default factory. Factory for populating list items. The factory for creating header widgets for the popup. The factory for populating list items in the popup. If this is not set, [property@Gtk.DropDown:factory] is used. Model for the displayed items. The match mode for the search filter. The position of the selected item. If no item is selected, the property has the value %GTK_INVALID_LIST_POSITION. The selected item. Whether to show an arrow within the GtkDropDown widget. Emitted to when the drop down is activated. The `::activate` signal on `GtkDropDown` is an action signal and emitting it causes the drop down to pop up its dropdown. An event controller to receive Drag-and-Drop operations. The most basic way to use a `GtkDropTarget` to receive drops on a widget is to create it via [ctor@Gtk.DropTarget.new], passing in the `GType` of the data you want to receive and connect to the [signal@Gtk.DropTarget::drop] signal to receive the data: ```c static gboolean on_drop (GtkDropTarget *target, const GValue *value, double x, double y, gpointer data) { MyWidget *self = data; // Call the appropriate setter depending on the type of data // that we received if (G_VALUE_HOLDS (value, G_TYPE_FILE)) my_widget_set_file (self, g_value_get_object (value)); else if (G_VALUE_HOLDS (value, GDK_TYPE_PIXBUF)) my_widget_set_pixbuf (self, g_value_get_object (value)); else return FALSE; return TRUE; } static void my_widget_init (MyWidget *self) { GtkDropTarget *target = gtk_drop_target_new (G_TYPE_INVALID, GDK_ACTION_COPY); // This widget accepts two types of drop types: GFile objects // and GdkPixbuf objects gtk_drop_target_set_gtypes (target, (GType [2]) { G_TYPE_FILE, GDK_TYPE_PIXBUF, }, 2); g_signal_connect (target, "drop", G_CALLBACK (on_drop), self); gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (target)); } ``` `GtkDropTarget` supports more options, such as: * rejecting potential drops via the [signal@Gtk.DropTarget::accept] signal and the [method@Gtk.DropTarget.reject] function to let other drop targets handle the drop * tracking an ongoing drag operation before the drop via the [signal@Gtk.DropTarget::enter], [signal@Gtk.DropTarget::motion] and [signal@Gtk.DropTarget::leave] signals * configuring how to receive data by setting the [property@Gtk.DropTarget:preload] property and listening for its availability via the [property@Gtk.DropTarget:value] property However, `GtkDropTarget` is ultimately modeled in a synchronous way and only supports data transferred via `GType`. If you want full control over an ongoing drop, the [class@Gtk.DropTargetAsync] object gives you this ability. While a pointer is dragged over the drop target's widget and the drop has not been rejected, that widget will receive the %GTK_STATE_FLAG_DROP_ACTIVE state, which can be used to style the widget. If you are not interested in receiving the drop, but just want to update UI state during a Drag-and-Drop operation (e.g. switching tabs), you can use [class@Gtk.DropControllerMotion]. Creates a new `GtkDropTarget` object. If the drop target should support more than 1 type, pass %G_TYPE_INVALID for @type and then call [method@Gtk.DropTarget.set_gtypes]. the new `GtkDropTarget` The supported type or %G_TYPE_INVALID the supported actions Gets the actions that this drop target supports. the actions that this drop target supports a `GtkDropTarget` Gets the currently handled drop operation. If no drop operation is going on, %NULL is returned. The current drop a `GtkDropTarget` Gets the currently handled drop operation. If no drop operation is going on, %NULL is returned. Use [method@Gtk.DropTarget.get_current_drop] instead The current drop a `GtkDropTarget` Gets the data formats that this drop target accepts. If the result is %NULL, all formats are expected to be supported. the supported data formats a `GtkDropTarget` Gets the list of supported `GType`s that can be dropped on the target. If no types have been set, `NULL` will be returned. the `G_TYPE_INVALID`-terminated array of types included in formats a `GtkDropTarget` the number of `GType`s contained in the return value Gets whether data should be preloaded on hover. %TRUE if drop data should be preloaded a `GtkDropTarget` Gets the current drop data, as a `GValue`. The current drop data a `GtkDropTarget` Rejects the ongoing drop operation. If no drop operation is ongoing, i.e when [property@Gtk.DropTarget:current-drop] is %NULL, this function does nothing. This function should be used when delaying the decision on whether to accept a drag or not until after reading the data. a `GtkDropTarget` Sets the actions that this drop target supports. a `GtkDropTarget` the supported actions Sets the supported `GType`s for this drop target. a `GtkDropTarget` all supported `GType`s that can be dropped on the target number of @types Sets whether data should be preloaded on hover. a `GtkDropTarget` %TRUE to preload drop data The `GdkDragActions` that this drop target supports. The `GdkDrop` that is currently being performed. The `GdkDrop` that is currently being performed. Use [property@Gtk.DropTarget:current-drop] instead The `GdkContentFormats` that determine the supported data formats. Whether the drop data should be preloaded when the pointer is only hovering over the widget but has not been released. Setting this property allows finer grained reaction to an ongoing drop at the cost of loading more data. The default value for this property is %FALSE to avoid downloading huge amounts of data by accident. For example, if somebody drags a full document of gigabytes of text from a text editor across a widget with a preloading drop target, this data will be downloaded, even if the data is ultimately dropped elsewhere. For a lot of data formats, the amount of data is very small (like %GDK_TYPE_RGBA), so enabling this property does not hurt at all. And for local-only Drag-and-Drop operations, no data transfer is done, so enabling it there is free. The value for this drop operation. This is %NULL if the data has not been loaded yet or no drop operation is going on. Data may be available before the [signal@Gtk.DropTarget::drop] signal gets emitted - for example when the [property@Gtk.DropTarget:preload] property is set. You can use the ::notify signal to be notified of available data. Emitted on the drop site when a drop operation is about to begin. If the drop is not accepted, %FALSE will be returned and the drop target will ignore the drop. If %TRUE is returned, the drop is accepted for now but may be rejected later via a call to [method@Gtk.DropTarget.reject] or ultimately by returning %FALSE from a [signal@Gtk.DropTarget::drop] handler. The default handler for this signal decides whether to accept the drop based on the formats provided by the @drop. If the decision whether the drop will be accepted or rejected depends on the data, this function should return %TRUE, the [property@Gtk.DropTarget:preload] property should be set and the value should be inspected via the ::notify:value signal, calling [method@Gtk.DropTarget.reject] if required. %TRUE if @drop is accepted the `GdkDrop` Emitted on the drop site when the user drops the data onto the widget. The signal handler must determine whether the pointer position is in a drop zone or not. If it is not in a drop zone, it returns %FALSE and no further processing is necessary. Otherwise, the handler returns %TRUE. In this case, this handler will accept the drop. The handler is responsible for using the given @value and performing the drop operation. whether the drop was accepted at the given pointer position the `GValue` being dropped the x coordinate of the current pointer position the y coordinate of the current pointer position Emitted on the drop site when the pointer enters the widget. It can be used to set up custom highlighting. Preferred action for this drag operation or `GDK_ACTION_NONE` if dropping is not supported at the current @x,@y location. the x coordinate of the current pointer position the y coordinate of the current pointer position Emitted on the drop site when the pointer leaves the widget. Its main purpose it to undo things done in [signal@Gtk.DropTarget::enter]. Emitted while the pointer is moving over the drop target. Preferred action for this drag operation or `GDK_ACTION_NONE` if dropping is not supported at the current @x,@y location. the x coordinate of the current pointer position the y coordinate of the current pointer position An event controller to receive Drag-and-Drop operations, asynchronously. It is the more complete but also more complex method of handling drop operations compared to [class@Gtk.DropTarget], and you should only use it if `GtkDropTarget` doesn't provide all the features you need. To use a `GtkDropTargetAsync` to receive drops on a widget, you create a `GtkDropTargetAsync` object, configure which data formats and actions you support, connect to its signals, and then attach it to the widget with [method@Gtk.Widget.add_controller]. During a drag operation, the first signal that a `GtkDropTargetAsync` emits is [signal@Gtk.DropTargetAsync::accept], which is meant to determine whether the target is a possible drop site for the ongoing drop. The default handler for the ::accept signal accepts the drop if it finds a compatible data format and an action that is supported on both sides. If it is, and the widget becomes a target, you will receive a [signal@Gtk.DropTargetAsync::drag-enter] signal, followed by [signal@Gtk.DropTargetAsync::drag-motion] signals as the pointer moves, optionally a [signal@Gtk.DropTargetAsync::drop] signal when a drop happens, and finally a [signal@Gtk.DropTargetAsync::drag-leave] signal when the pointer moves off the widget. The ::drag-enter and ::drag-motion handler return a `GdkDragAction` to update the status of the ongoing operation. The ::drop handler should decide if it ultimately accepts the drop and if it does, it should initiate the data transfer and finish the operation by calling [method@Gdk.Drop.finish]. Between the ::drag-enter and ::drag-leave signals the widget is a current drop target, and will receive the %GTK_STATE_FLAG_DROP_ACTIVE state, which can be used by themes to style the widget as a drop target. Creates a new `GtkDropTargetAsync` object. the new `GtkDropTargetAsync` the supported data formats the supported actions Gets the actions that this drop target supports. the actions that this drop target supports a `GtkDropTargetAsync` Gets the data formats that this drop target accepts. If the result is %NULL, all formats are expected to be supported. the supported data formats a `GtkDropTargetAsync` Sets the @drop as not accepted on this drag site. This function should be used when delaying the decision on whether to accept a drag or not until after reading the data. a `GtkDropTargetAsync` the `GdkDrop` of an ongoing drag operation Sets the actions that this drop target supports. a `GtkDropTargetAsync` the supported actions Sets the data formats that this drop target will accept. a `GtkDropTargetAsync` the supported data formats or %NULL for any format The `GdkDragActions` that this drop target supports. The `GdkContentFormats` that determines the supported data formats. Emitted on the drop site when a drop operation is about to begin. If the drop is not accepted, %FALSE will be returned and the drop target will ignore the drop. If %TRUE is returned, the drop is accepted for now but may be rejected later via a call to [method@Gtk.DropTargetAsync.reject_drop] or ultimately by returning %FALSE from a [signal@Gtk.DropTargetAsync::drop] handler. The default handler for this signal decides whether to accept the drop based on the formats provided by the @drop. If the decision whether the drop will be accepted or rejected needs further processing, such as inspecting the data, this function should return %TRUE and proceed as is @drop was accepted and if it decides to reject the drop later, it should call [method@Gtk.DropTargetAsync.reject_drop]. %TRUE if @drop is accepted the `GdkDrop` Emitted on the drop site when the pointer enters the widget. It can be used to set up custom highlighting. Preferred action for this drag operation. the `GdkDrop` the x coordinate of the current pointer position the y coordinate of the current pointer position Emitted on the drop site when the pointer leaves the widget. Its main purpose it to undo things done in `GtkDropTargetAsync`::drag-enter. the `GdkDrop` Emitted while the pointer is moving over the drop target. Preferred action for this drag operation. the `GdkDrop` the x coordinate of the current pointer position the y coordinate of the current pointer position Emitted on the drop site when the user drops the data onto the widget. The signal handler must determine whether the pointer position is in a drop zone or not. If it is not in a drop zone, it returns %FALSE and no further processing is necessary. Otherwise, the handler returns %TRUE. In this case, this handler will accept the drop. The handler must ensure that [method@Gdk.Drop.finish] is called to let the source know that the drop is done. The call to [method@Gdk.Drop.finish] must only be done when all data has been received. To receive the data, use one of the read functions provided by [class@Gdk.Drop] such as [method@Gdk.Drop.read_async] or [method@Gdk.Drop.read_value_async]. whether the drop is accepted at the given pointer position the `GdkDrop` the x coordinate of the current pointer position the y coordinate of the current pointer position Interface for single-line text editing widgets. Typical examples of editable widgets are [class@Gtk.Entry] and [class@Gtk.SpinButton]. It contains functions for generically manipulating an editable widget, a large number of action signals used for key bindings, and several signals that an application can connect to modify the behavior of a widget. As an example of the latter usage, by connecting the following handler to [signal@Gtk.Editable::insert-text], an application can convert all entry into a widget into uppercase. ## Forcing entry to uppercase. ```c #include <ctype.h> void insert_text_handler (GtkEditable *editable, const char *text, int length, int *position, gpointer data) { char *result = g_utf8_strup (text, length); g_signal_handlers_block_by_func (editable, (gpointer) insert_text_handler, data); gtk_editable_insert_text (editable, result, length, position); g_signal_handlers_unblock_by_func (editable, (gpointer) insert_text_handler, data); g_signal_stop_emission_by_name (editable, "insert_text"); g_free (result); } ``` ## Implementing GtkEditable The most likely scenario for implementing `GtkEditable` on your own widget is that you will embed a `GtkText` inside a complex widget, and want to delegate the editable functionality to that text widget. `GtkEditable` provides some utility functions to make this easy. In your class_init function, call [func@Gtk.Editable.install_properties], passing the first available property ID: ```c static void my_class_init (MyClass *class) { ... g_object_class_install_properties (object_class, NUM_PROPERTIES, props); gtk_editable_install_properties (object_clas, NUM_PROPERTIES); ... } ``` In your interface_init function for the `GtkEditable` interface, provide an implementation for the get_delegate vfunc that returns your text widget: ```c GtkEditable * get_editable_delegate (GtkEditable *editable) { return GTK_EDITABLE (MY_WIDGET (editable)->text_widget); } static void my_editable_init (GtkEditableInterface *iface) { iface->get_delegate = get_editable_delegate; } ``` You don't need to provide any other vfuncs. The default implementations work by forwarding to the delegate that the GtkEditableInterface.get_delegate() vfunc returns. In your instance_init function, create your text widget, and then call [method@Gtk.Editable.init_delegate]: ```c static void my_widget_init (MyWidget *self) { ... self->text_widget = gtk_text_new (); gtk_editable_init_delegate (GTK_EDITABLE (self)); ... } ``` In your dispose function, call [method@Gtk.Editable.finish_delegate] before destroying your text widget: ```c static void my_widget_dispose (GObject *object) { ... gtk_editable_finish_delegate (GTK_EDITABLE (self)); g_clear_pointer (&self->text_widget, gtk_widget_unparent); ... } ``` Finally, use [func@Gtk.Editable.delegate_set_property] in your `set_property` function (and similar for `get_property`), to set the editable properties: ```c ... if (gtk_editable_delegate_set_property (object, prop_id, value, pspec)) return; switch (prop_id) ... ``` It is important to note that if you create a `GtkEditable` that uses a delegate, the low level [signal@Gtk.Editable::insert-text] and [signal@Gtk.Editable::delete-text] signals will be propagated from the "wrapper" editable to the delegate, but they will not be propagated from the delegate to the "wrapper" editable, as they would cause an infinite recursion. If you wish to connect to the [signal@Gtk.Editable::insert-text] and [signal@Gtk.Editable::delete-text] signals, you will need to connect to them on the delegate obtained via [method@Gtk.Editable.get_delegate]. Gets a property of the `GtkEditable` delegate for @object. This is helper function that should be called in the `get_property` function of your `GtkEditable` implementation, before handling your own properties. %TRUE if the property was found a `GObject` a property ID value to set the `GParamSpec` for the property Sets a property on the `GtkEditable` delegate for @object. This is a helper function that should be called in the `set_property` function of your `GtkEditable` implementation, before handling your own properties. %TRUE if the property was found a `GObject` a property ID value to set the `GParamSpec` for the property Overrides the `GtkEditable` properties for @class. This is a helper function that should be called in class_init, after installing your own properties. Note that your class must have "text", "cursor-position", "selection-bound", "editable", "width-chars", "max-width-chars", "xalign" and "enable-undo" properties for this function to work. To handle the properties in your set_property and get_property functions, you can either use [func@Gtk.Editable.delegate_set_property] and [func@Gtk.Editable.delegate_get_property] (if you are using a delegate), or remember the @first_prop offset and add it to the values in the [enum@Gtk.EditableProperties] enumeration to get the property IDs for these properties. the number of properties that were installed a `GObjectClass` property ID to use for the first property Deletes a sequence of characters. The characters that are deleted are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters deleted are those from @start_pos to the end of the text. Note that the positions are specified in characters, not bytes. a `GtkEditable` start position end position Deletes a sequence of characters. The characters that are deleted are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters deleted are those from @start_pos to the end of the text. Note that the positions are specified in characters, not bytes. a `GtkEditable` start position end position Inserts @length bytes of @text into the contents of the widget, at position @position. Note that the position is in characters, not in bytes. The function updates @position to point after the newly inserted text. a `GtkEditable` the text to insert the length of the text in bytes, or -1 location of the position text will be inserted at Gets the `GtkEditable` that @editable is delegating its implementation to. Typically, the delegate is a [class@Gtk.Text] widget. the delegate `GtkEditable` a `GtkEditable` Retrieves the selection bound of the editable. @start_pos will be filled with the start of the selection and @end_pos with end. If no text was selected both will be identical and %FALSE will be returned. Note that positions are specified in characters, not bytes. %TRUE if there is a non-empty selection, %FALSE otherwise a `GtkEditable` location to store the starting position location to store the end position Retrieves the contents of @editable. The returned string is owned by GTK and must not be modified or freed. a pointer to the contents of the editable a `GtkEditable` Inserts @length bytes of @text into the contents of the widget, at position @position. Note that the position is in characters, not in bytes. The function updates @position to point after the newly inserted text. a `GtkEditable` the text to insert the length of the text in bytes, or -1 location of the position text will be inserted at Selects a region of text. The characters that are selected are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters selected are those characters from @start_pos to the end of the text. Note that positions are specified in characters, not bytes. a `GtkEditable` start of region end of region Retrieves the accessible platform state from the editable delegate. This is an helper function to retrieve the accessible state for `GtkEditable` interface implementations using a delegate pattern. You should call this function in your editable widget implementation of the [vfunc@Gtk.Accessible.get_platform_state] virtual function, for instance: ```c static void accessible_interface_init (GtkAccessibleInterface *iface) { iface->get_platform_state = your_editable_get_accessible_platform_state; } static gboolean your_editable_get_accessible_platform_state (GtkAccessible *accessible, GtkAccessiblePlatformState state) { return gtk_editable_delegate_get_accessible_platform_state (GTK_EDITABLE (accessible), state); } ``` Note that the widget which is the delegate *must* be a direct child of this widget, otherwise your implementation of [vfunc@Gtk.Accessible.get_platform_state] might not even be called, as the platform change will originate from the parent of the delegate, and, as a result, will not work properly. So, if you can't ensure the direct child condition, you should give the delegate the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role, or you can change your tree to allow this function to work. the accessible platform state of the delegate a `GtkEditable` implementation what kind of accessible state to retrieve Deletes the currently selected text of the editable. This call doesn’t do anything if there is no selected text. a `GtkEditable` Deletes a sequence of characters. The characters that are deleted are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters deleted are those from @start_pos to the end of the text. Note that the positions are specified in characters, not bytes. a `GtkEditable` start position end position Undoes the setup done by [method@Gtk.Editable.init_delegate]. This is a helper function that should be called from dispose, before removing the delegate object. a `GtkEditable` Gets the alignment of the editable. the alignment a `GtkEditable` Retrieves a sequence of characters. The characters that are retrieved are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters retrieved are those characters from @start_pos to the end of the text. Note that positions are specified in characters, not bytes. a pointer to the contents of the widget as a string. This string is allocated by the `GtkEditable` implementation and should be freed by the caller. a `GtkEditable` start of text end of text Gets the `GtkEditable` that @editable is delegating its implementation to. Typically, the delegate is a [class@Gtk.Text] widget. the delegate `GtkEditable` a `GtkEditable` Retrieves whether @editable is editable. %TRUE if @editable is editable. a `GtkEditable` Gets if undo/redo actions are enabled for @editable %TRUE if undo is enabled a `GtkEditable` Retrieves the desired maximum width of @editable, in characters. the maximum width of the entry, in characters a `GtkEditable` Retrieves the current position of the cursor relative to the start of the content of the editable. Note that this position is in characters, not in bytes. the cursor position a `GtkEditable` Retrieves the selection bound of the editable. @start_pos will be filled with the start of the selection and @end_pos with end. If no text was selected both will be identical and %FALSE will be returned. Note that positions are specified in characters, not bytes. %TRUE if there is a non-empty selection, %FALSE otherwise a `GtkEditable` location to store the starting position location to store the end position Retrieves the contents of @editable. The returned string is owned by GTK and must not be modified or freed. a pointer to the contents of the editable a `GtkEditable` Gets the number of characters of space reserved for the contents of the editable. number of chars to request space for, or negative if unset a `GtkEditable` Sets up a delegate for `GtkEditable`. This is assuming that the get_delegate vfunc in the `GtkEditable` interface has been set up for the @editable's type. This is a helper function that should be called in instance init, after creating the delegate object. a `GtkEditable` Inserts @length bytes of @text into the contents of the widget, at position @position. Note that the position is in characters, not in bytes. The function updates @position to point after the newly inserted text. a `GtkEditable` the text to insert the length of the text in bytes, or -1 location of the position text will be inserted at Selects a region of text. The characters that are selected are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters selected are those characters from @start_pos to the end of the text. Note that positions are specified in characters, not bytes. a `GtkEditable` start of region end of region Sets the alignment for the contents of the editable. This controls the horizontal positioning of the contents when the displayed text is shorter than the width of the editable. a `GtkEditable` The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts Determines if the user can edit the text in the editable widget. a `GtkEditable` %TRUE if the user is allowed to edit the text in the widget If enabled, changes to @editable will be saved for undo/redo actions. This results in an additional copy of text changes and are not stored in secure memory. As such, undo is forcefully disabled when [property@Gtk.Text:visibility] is set to %FALSE. a `GtkEditable` if undo/redo should be enabled Sets the desired maximum width in characters of @editable. a `GtkEditable` the new desired maximum width, in characters Sets the cursor position in the editable to the given value. The cursor is displayed before the character with the given (base 0) index in the contents of the editable. The value must be less than or equal to the number of characters in the editable. A value of -1 indicates that the position should be set after the last character of the editable. Note that @position is in characters, not in bytes. a `GtkEditable` the position of the cursor Sets the text in the editable to the given value. This is replacing the current contents. a `GtkEditable` the text to set Changes the size request of the editable to be about the right size for @n_chars characters. Note that it changes the size request, the size can still be affected by how you pack the widget into containers. If @n_chars is -1, the size reverts to the default size. a `GtkEditable` width in chars The current position of the insertion cursor in chars. Whether the entry contents can be edited. If undo/redo should be enabled for the editable. The desired maximum width of the entry, in characters. The position of the opposite end of the selection from the cursor in chars. The contents of the entry. Number of characters to leave space for in the entry. The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts. Emitted at the end of a single user-visible operation on the contents. E.g., a paste operation that replaces the contents of the selection will cause only one signal emission (even though it is implemented by first deleting the selection, then inserting the new content, and may cause multiple ::notify::text signals to be emitted). Emitted when text is deleted from the widget by the user. The default handler for this signal will normally be responsible for deleting the text, so by connecting to this signal and then stopping the signal with g_signal_stop_emission(), it is possible to modify the range of deleted text, or prevent it from being deleted entirely. The @start_pos and @end_pos parameters are interpreted as for [method@Gtk.Editable.delete_text]. the starting position the end position Emitted when text is inserted into the widget by the user. The default handler for this signal will normally be responsible for inserting the text, so by connecting to this signal and then stopping the signal with g_signal_stop_emission(), it is possible to modify the inserted text, or prevent it from being inserted entirely. the new text to insert the length of the new text, in bytes, or -1 if new_text is nul-terminated the position, in characters, at which to insert the new text. this is an in-out parameter. After the signal emission is finished, it should point after the newly inserted text. a `GtkEditable` the text to insert the length of the text in bytes, or -1 location of the position text will be inserted at a `GtkEditable` start position end position a pointer to the contents of the editable a `GtkEditable` a `GtkEditable` the text to insert the length of the text in bytes, or -1 location of the position text will be inserted at a `GtkEditable` start position end position %TRUE if there is a non-empty selection, %FALSE otherwise a `GtkEditable` location to store the starting position location to store the end position a `GtkEditable` start of region end of region the delegate `GtkEditable` a `GtkEditable` Allows users to edit the displayed text by switching to an “edit mode”. <picture> <source srcset="editable-label-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkEditableLabel" src="editable-label.png"> </picture> `GtkEditableLabel` does not have API of its own, but it implements the [iface@Gtk.Editable] interface. The default bindings for activating the edit mode is to click or press the Enter key. The default bindings for leaving the edit mode are the Enter key (to save the results) or the Escape key (to cancel the editing). # Shortcuts and Gestures `GtkEditableLabel` supports the following keyboard shortcuts: - <kbd>Enter</kbd> starts editing. - <kbd>Escape</kbd> stops editing. # Actions `GtkEditableLabel` defines a set of built-in actions: - `editing.starts` switches the widget into editing mode. - `editing.stop` switches the widget out of editing mode. # CSS nodes ``` editablelabel[.editing] ╰── stack ├── label ╰── text ``` `GtkEditableLabel` has a main node with the name editablelabel. When the entry is in editing mode, it gets the .editing style class. For all the subnodes added to the text node in various situations, see [class@Gtk.Text]. Creates a new `GtkEditableLabel` widget. the new `GtkEditableLabel` the text for the label Returns whether the label is currently in “editing mode”. %TRUE if @self is currently in editing mode a `GtkEditableLabel` Switches the label into “editing mode”. a `GtkEditableLabel` Switches the label out of “editing mode”. If @commit is %TRUE, the resulting text is kept as the [property@Gtk.Editable:text] property value, otherwise the resulting text is discarded and the label will keep its previous [property@Gtk.Editable:text] property value. a `GtkEditableLabel` whether to set the edited text on the label This property is %TRUE while the widget is in edit mode. The identifiers for [iface@Gtk.Editable] properties. See [func@Gtk.Editable.install_properties] for details on how to implement the `GtkEditable` interface. the property id for [property@Gtk.Editable:text] the property id for [property@Gtk.Editable:cursor-position] the property id for [property@Gtk.Editable:selection-bound] the property id for [property@Gtk.Editable:editable] the property id for [property@Gtk.Editable:width-chars] the property id for [property@Gtk.Editable:max-width-chars] the property id for [property@Gtk.Editable:xalign] the property id for [property@Gtk.Editable:enable-undo] the number of properties Used by text widgets to let users insert Emoji characters. <picture> <source srcset="emojichooser-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkEmojiChooser" src="emojichooser.png"> </picture> `GtkEmojiChooser` emits the [signal@Gtk.EmojiChooser::emoji-picked] signal when an Emoji is selected. # Shortcuts and Gestures `GtkEmojiChooser` supports the following keyboard shortcuts: - <kbd>Ctrl</kbd>+<kbd>N</kbd> scrolls th the next section. - <kbd>Ctrl</kbd>+<kbd>P</kbd> scrolls th the previous section. # Actions `GtkEmojiChooser` defines a set of built-in actions: - `scroll.section` scrolls to the next or previous section. # CSS nodes ``` popover ├── box.emoji-searchbar │ ╰── entry.search ╰── box.emoji-toolbar ├── button.image-button.emoji-section ├── ... ╰── button.image-button.emoji-section ``` Every `GtkEmojiChooser` consists of a main node called popover. The contents of the popover are largely implementation defined and supposed to inherit general styles. The top searchbar used to search emoji and gets the .emoji-searchbar style class itself. The bottom toolbar used to switch between different emoji categories consists of buttons with the .emoji-section style class and gets the .emoji-toolbar style class itself. Creates a new `GtkEmojiChooser`. a new `GtkEmojiChooser` Emitted when the user selects an Emoji. the Unicode sequence for the picked Emoji, in UTF-8 A single-line text entry widget. <picture> <source srcset="entry-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkEntry" src="entry.png"> </picture> A fairly large set of key bindings are supported by default. If the entered text is longer than the allocation of the widget, the widget will scroll so that the cursor position is visible. When using an entry for passwords and other sensitive information, it can be put into “password mode” using [method@Gtk.Entry.set_visibility]. In this mode, entered text is displayed using a “invisible” character. By default, GTK picks the best invisible character that is available in the current font, but it can be changed with [method@Gtk.Entry.set_invisible_char]. `GtkEntry` has the ability to display progress or activity information behind the text. To make an entry display such information, use [method@Gtk.Entry.set_progress_fraction] or [method@Gtk.Entry.set_progress_pulse_step]. Additionally, `GtkEntry` can show icons at either side of the entry. These icons can be activatable by clicking, can be set up as drag source and can have tooltips. To add an icon, use [method@Gtk.Entry.set_icon_from_gicon] or one of the various other functions that set an icon from an icon name or a paintable. To trigger an action when the user clicks an icon, connect to the [signal@Gtk.Entry::icon-press] signal. To allow DND operations from an icon, use [method@Gtk.Entry.set_icon_drag_source]. To set a tooltip on an icon, use [method@Gtk.Entry.set_icon_tooltip_text] or the corresponding function for markup. Note that functionality or information that is only available by clicking on an icon in an entry may not be accessible at all to users which are not able to use a mouse or other pointing device. It is therefore recommended that any such functionality should also be available by other means, e.g. via the context menu of the entry. # CSS nodes ``` entry[.flat][.warning][.error] ├── text[.readonly] ├── image.left ├── image.right ╰── [progress[.pulse]] ``` `GtkEntry` has a main node with the name entry. Depending on the properties of the entry, the style classes .read-only and .flat may appear. The style classes .warning and .error may also be used with entries. When the entry shows icons, it adds subnodes with the name image and the style class .left or .right, depending on where the icon appears. When the entry shows progress, it adds a subnode with the name progress. The node has the style class .pulse when the shown progress is pulsing. For all the subnodes added to the text node in various situations, see [class@Gtk.Text]. # GtkEntry as GtkBuildable The `GtkEntry` implementation of the `GtkBuildable` interface supports a custom `<attributes>` element, which supports any number of `<attribute>` elements. The `<attribute>` element has attributes named “name“, “value“, “start“ and “end“ and allows you to specify `PangoAttribute` values for this label. An example of a UI definition fragment specifying Pango attributes: ```xml <object class="GtkEntry"> <attributes> <attribute name="weight" value="PANGO_WEIGHT_BOLD"/> <attribute name="background" value="red" start="5" end="10"/> </attributes> </object> ``` The start and end attributes specify the range of characters to which the Pango attribute applies. If start and end are not specified, the attribute is applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup embedded in the translatable content instead. # Accessibility `GtkEntry` uses the [enum@Gtk.AccessibleRole.text_box] role. Creates a new entry. a new `GtkEntry`. Creates a new entry with the specified text buffer. a new `GtkEntry` The buffer to use for the new `GtkEntry`. Class handler for the `GtkEntry::activate` signal. The default implementation activates the gtk.activate-default action. Retrieves the value set by gtk_entry_set_activates_default(). %TRUE if the entry will activate the default widget a `GtkEntry` Gets the value set by gtk_entry_set_alignment(). See also: [property@Gtk.Editable:xalign] the alignment a `GtkEntry` Gets the attribute list of the `GtkEntry`. See [method@Gtk.Entry.set_attributes]. the attribute list a `GtkEntry` Get the `GtkEntryBuffer` object which holds the text for this widget. A `GtkEntryBuffer` object. a `GtkEntry` Returns the auxiliary completion object currently in use by @entry. GtkEntryCompletion will be removed in GTK 5. The auxiliary completion object currently in use by @entry A `GtkEntry` Returns the index of the icon which is the source of the current DND operation, or -1. index of the icon which is the source of the current DND operation, or -1. a `GtkEntry` Gets the menu model set with gtk_entry_set_extra_menu(). the menu model a `GtkEntry` Gets the value set by gtk_entry_set_has_frame(). whether the entry has a beveled frame a `GtkEntry` Returns whether the icon is activatable. %TRUE if the icon is activatable. a `GtkEntry` Icon position Gets the area where entry’s icon at @icon_pos is drawn. This function is useful when drawing something to the entry in a draw callback. If the entry is not realized or has no icon at the given position, @icon_area is filled with zeros. Otherwise, @icon_area will be filled with the icon's allocation, relative to @entry's allocation. A `GtkEntry` Icon position Return location for the icon’s area Finds the icon at the given position and return its index. The position’s coordinates are relative to the @entry’s top left corner. If @x, @y doesn’t lie inside an icon, -1 is returned. This function is intended for use in a [signal@Gtk.Widget::query-tooltip] signal handler. the index of the icon at the given position, or -1 a `GtkEntry` the x coordinate of the position to find, relative to @entry the y coordinate of the position to find, relative to @entry Retrieves the `GIcon` used for the icon. %NULL will be returned if there is no icon or if the icon was set by some other method (e.g., by `GdkPaintable` or icon name). A `GIcon` A `GtkEntry` Icon position Retrieves the icon name used for the icon. %NULL is returned if there is no icon or if the icon was set by some other method (e.g., by `GdkPaintable` or gicon). An icon name A `GtkEntry` Icon position Retrieves the `GdkPaintable` used for the icon. If no `GdkPaintable` was used for the icon, %NULL is returned. A `GdkPaintable` if no icon is set for this position or the icon set is not a `GdkPaintable`. A `GtkEntry` Icon position Returns whether the icon appears sensitive or insensitive. %TRUE if the icon is sensitive. a `GtkEntry` Icon position Gets the type of representation being used by the icon to store image data. If the icon has no image data, the return value will be %GTK_IMAGE_EMPTY. image representation being used a `GtkEntry` Icon position Gets the contents of the tooltip on the icon at the specified position in @entry. the tooltip text a `GtkEntry` the icon position Gets the contents of the tooltip on the icon at the specified position in @entry. the tooltip text a `GtkEntry` the icon position Gets the input hints of this `GtkEntry`. the input hints a `GtkEntry` Gets the input purpose of the `GtkEntry`. the input purpose a `GtkEntry` Retrieves the character displayed in place of the actual text in “password mode”. the current invisible char, or 0, if the entry does not show invisible text at all. a `GtkEntry` Retrieves the maximum allowed length of the text in @entry. See [method@Gtk.Entry.set_max_length]. the maximum allowed number of characters in `GtkEntry`, or 0 if there is no maximum. a `GtkEntry` Gets the text that will be used in the context menu of the `GtkEntry` when the specified icon is activatable. Selecting this item in the menu results, from all aspects, the same than clicking on the specified icon. This greatly simplifies making accessible applications, because the icons aren't focusable when using keyboard navigation. This is why Gtk recommends to add the same action to the context menu. the text that will be used in the menu item, or NULL if no menu item is desired. a `GtkEntry` either @GTK_ENTRY_ICON_PRIMARY or @GTK_ENTRY_ICON_SECONDARY Gets whether the `GtkEntry` is in overwrite mode. whether the text is overwritten when typing. a `GtkEntry` Retrieves the text that will be displayed when @entry is empty and unfocused a pointer to the placeholder text as a string. This string points to internally allocated storage in the widget and must not be freed, modified or stored. If no placeholder text has been set, %NULL will be returned. a `GtkEntry` Returns the current fraction of the task that’s been completed. See [method@Gtk.Entry.set_progress_fraction]. a fraction from 0.0 to 1.0 a `GtkEntry` Retrieves the pulse step set with gtk_entry_set_progress_pulse_step(). a fraction from 0.0 to 1.0 a `GtkEntry` Gets the tabstops of the `GtkEntry`. See [method@Gtk.Entry.set_tabs]. the tabstops a `GtkEntry` Retrieves the current length of the text in @entry. This is equivalent to getting @entry's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.get_length] on it. the current number of characters in `GtkEntry`, or 0 if there are none. a `GtkEntry` Retrieves whether the text in @entry is visible. See [method@Gtk.Entry.set_visibility]. %TRUE if the text is currently visible a `GtkEntry` Causes @entry to have keyboard focus. It behaves like [method@Gtk.Widget.grab_focus], except that it doesn't select the contents of the entry. You only want to call this on some special entries which the user usually doesn't want to replace all text in, such as search-as-you-type entries. %TRUE if focus is now inside @self a `GtkEntry` Indicates that some progress is made, but you don’t know how much. Causes the entry’s progress indicator to enter “activity mode”, where a block bounces back and forth. Each call to gtk_entry_progress_pulse() causes the block to move by a little bit (the amount of movement per pulse is determined by [method@Gtk.Entry.set_progress_pulse_step]). a `GtkEntry` Reset the input method context of the entry if needed. This can be necessary in the case where modifying the buffer would confuse on-going input method behavior. a `GtkEntry` Sets whether pressing Enter in the @entry will activate the default widget for the window containing the entry. This usually means that the dialog containing the entry will be closed, since the default widget is usually one of the dialog buttons. a `GtkEntry` %TRUE to activate window’s default widget on Enter keypress Sets the alignment for the contents of the entry. This controls the horizontal positioning of the contents when the displayed text is shorter than the width of the entry. See also: [property@Gtk.Editable:xalign] a `GtkEntry` The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts Sets a `PangoAttrList`. The attributes in the list are applied to the entry text. Since the attributes will be applied to text that changes as the user types, it makes most sense to use attributes with unlimited extent. a `GtkEntry` a `PangoAttrList` Set the `GtkEntryBuffer` object which holds the text for this widget. a `GtkEntry` a `GtkEntryBuffer` Sets @completion to be the auxiliary completion object to use with @entry. All further configuration of the completion mechanism is done on @completion using the `GtkEntryCompletion` API. Completion is disabled if @completion is set to %NULL. GtkEntryCompletion will be removed in GTK 5. A `GtkEntry` The `GtkEntryCompletion` Sets a menu model to add when constructing the context menu for @entry. a `GtkEntry` a `GMenuModel` Sets whether the entry has a beveled frame around it. a `GtkEntry` new value Sets whether the icon is activatable. A `GtkEntry` Icon position %TRUE if the icon should be activatable Sets up the icon at the given position as drag source. This makes it so that GTK will start a drag operation when the user clicks and drags the icon. a `GtkEntry` icon position a `GdkContentProvider` a bitmask of the allowed drag actions Sets the icon shown in the entry at the specified position from the current icon theme. If the icon isn’t known, a “broken image” icon will be displayed instead. If @icon is %NULL, no icon will be shown in the specified position. A `GtkEntry` The position at which to set the icon The icon to set Sets the icon shown in the entry at the specified position from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If @icon_name is %NULL, no icon will be shown in the specified position. A `GtkEntry` The position at which to set the icon An icon name Sets the icon shown in the specified position using a `GdkPaintable`. If @paintable is %NULL, no icon will be shown in the specified position. a `GtkEntry` Icon position A `GdkPaintable` Sets the sensitivity for the specified icon. A `GtkEntry` Icon position Specifies whether the icon should appear sensitive or insensitive Sets @tooltip as the contents of the tooltip for the icon at the specified position. @tooltip is assumed to be marked up with Pango Markup. Use %NULL for @tooltip to remove an existing tooltip. See also [method@Gtk.Widget.set_tooltip_markup] and [method@Gtk.Entry.set_icon_tooltip_text]. a `GtkEntry` the icon position the contents of the tooltip for the icon Sets @tooltip as the contents of the tooltip for the icon at the specified position. Use %NULL for @tooltip to remove an existing tooltip. See also [method@Gtk.Widget.set_tooltip_text] and [method@Gtk.Entry.set_icon_tooltip_markup]. If you unset the widget tooltip via [method@Gtk.Widget.set_tooltip_text] or [method@Gtk.Widget.set_tooltip_markup], this sets [property@Gtk.Widget:has-tooltip] to %FALSE, which suppresses icon tooltips too. You can resolve this by then calling [method@Gtk.Widget.set_has_tooltip] to set [property@Gtk.Widget:has-tooltip] back to %TRUE, or setting at least one non-empty tooltip on any icon achieves the same result. a `GtkEntry` the icon position the contents of the tooltip for the icon Set additional hints which allow input methods to fine-tune their behavior. a `GtkEntry` the hints Sets the input purpose which can be used by input methods to adjust their behavior. a `GtkEntry` the purpose Sets the character to use in place of the actual text in “password mode”. See [method@Gtk.Entry.set_visibility] for how to enable “password mode”. By default, GTK picks the best invisible char available in the current font. If you set the invisible char to 0, then the user will get no feedback at all; there will be no text on the screen as they type. a `GtkEntry` a Unicode character Sets the maximum allowed length of the contents of the widget. If the current contents are longer than the given length, then they will be truncated to fit. The length is in characters. This is equivalent to getting @entry's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.set_max_length] on it. a `GtkEntry` the maximum length of the entry, or 0 for no maximum. (other than the maximum length of entries.) The value passed in will be clamped to the range 0-65536. Sets the text that will be used in the context menu of the `GtkEntry` when the specified icon is activatable. Selecting this item in the menu results, from all aspects, the same than clicking on the specified icon. This greatly simplifies making accessible applications, because the icons aren't focusable when using keyboard navigation. This is why Gtk recommends to add the same action to the context menu. a `GtkEntry` either @GTK_ENTRY_ICON_PRIMARY or @GTK_ENTRY_ICON_SECONDARY the text used for the menu item in the context menu, or NULL to not add a menu item. Sets whether the text is overwritten when typing in the `GtkEntry`. a `GtkEntry` new value Sets text to be displayed in @entry when it is empty. This can be used to give a visual hint of the expected contents of the `GtkEntry`. a `GtkEntry` a string to be displayed when @entry is empty and unfocused Causes the entry’s progress indicator to “fill in” the given fraction of the bar. The fraction should be between 0.0 and 1.0, inclusive. a `GtkEntry` fraction of the task that’s been completed Sets the fraction of total entry width to move the progress bouncing block for each pulse. Use [method@Gtk.Entry.progress_pulse] to pulse the progress. a `GtkEntry` fraction between 0.0 and 1.0 Sets a `PangoTabArray`. The tabstops in the array are applied to the entry text. a `GtkEntry` a `PangoTabArray` Sets whether the contents of the entry are visible or not. When visibility is set to %FALSE, characters are displayed as the invisible char, and will also appear that way when the text in the entry widget is copied elsewhere. By default, GTK picks the best invisible character available in the current font, but it can be changed with [method@Gtk.Entry.set_invisible_char]. Note that you probably want to set [property@Gtk.Entry:input-purpose] to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN to inform input methods about the purpose of this entry, in addition to setting visibility to %FALSE. a `GtkEntry` %TRUE if the contents of the entry are displayed as plaintext Unsets the invisible char, so that the default invisible char is used again. See [method@Gtk.Entry.set_invisible_char]. a `GtkEntry` Whether to activate the default widget when Enter is pressed. A list of Pango attributes to apply to the text of the entry. This is mainly useful to change the size or weight of the text. The `PangoAttribute`'s @start_index and @end_index must refer to the [class@Gtk.EntryBuffer] text, i.e. without the preedit string. The buffer object which actually stores the text. The auxiliary completion object to use with the entry. GtkEntryCompletion will be removed in GTK 5. Whether to suggest Emoji replacements for :-delimited names like `:heart:`. A menu model whose contents will be appended to the context menu. Whether the entry should draw a frame. Which IM (input method) module should be used for this entry. See [class@Gtk.IMContext]. Setting this to a non-%NULL value overrides the system-wide IM module setting. See the GtkSettings [property@Gtk.Settings:gtk-im-module] property. Additional hints that allow input methods to fine-tune their behavior. Also see [property@Gtk.Entry:input-purpose] The purpose of this text field. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN is independent from setting [property@Gtk.Entry:visibility]. The character to use when masking entry contents (“password mode”). Whether the invisible char has been set for the `GtkEntry`. Maximum number of characters for this entry. Text for an item in the context menu to activate the primary icon action. When the primary icon is activatable and this property has been set, a new entry in the context menu of this GtkEntry will appear with this text. Selecting that menu entry will result in the primary icon being activated, exactly in the same way as it would be activated from a mouse click. This simplifies adding accessibility support to applications using activatable icons. The activatable icons aren't focusable when navigating the interface with the keyboard This is why Gtk recommends to also add those actions in the context menu. This set of methods greatly simplifies this, by adding a menu item that, when enabled, calls the same callback than clicking on the icon. Text for an item in the context menu to activate the secondary icon action. When the primary icon is activatable and this property has been set, a new entry in the context menu of this GtkEntry will appear with this text. Selecting that menu entry will result in the primary icon being activated, exactly in the same way as it would be activated from a mouse click. This simplifies adding accessibility support to applications using activatable icons. The activatable icons aren't focusable when navigating the interface with the keyboard This is why Gtk recommends to also add those actions in the context menu. This set of methods greatly simplifies this, by adding a menu item that, when enabled, calls the same callback than clicking on the icon. If text is overwritten when typing in the `GtkEntry`. The text that will be displayed in the `GtkEntry` when it is empty and unfocused. Whether the primary icon is activatable. GTK emits the [signal@Gtk.Entry::icon-press] and [signal@Gtk.Entry::icon-release] signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes. The `GIcon` to use for the primary icon for the entry. The icon name to use for the primary icon for the entry. A `GdkPaintable` to use as the primary icon for the entry. Whether the primary icon is sensitive. An insensitive icon appears grayed out. GTK does not emit the [signal@Gtk.Entry::icon-press] and [signal@Gtk.Entry::icon-release] signals and does not allow DND from insensitive icons. An icon should be set insensitive if the action that would trigger when clicked is currently not available. The representation which is used for the primary icon of the entry. The contents of the tooltip on the primary icon, with markup. Also see [method@Gtk.Entry.set_icon_tooltip_markup]. The contents of the tooltip on the primary icon. Also see [method@Gtk.Entry.set_icon_tooltip_text]. The current fraction of the task that's been completed. The fraction of total entry width to move the progress bouncing block for each pulse. See [method@Gtk.Entry.progress_pulse]. Number of pixels of the entry scrolled off the screen to the left. Whether the secondary icon is activatable. GTK emits the [signal@Gtk.Entry::icon-press] and [signal@Gtk.Entry::icon-release] signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes. The `GIcon` to use for the secondary icon for the entry. The icon name to use for the secondary icon for the entry. A `GdkPaintable` to use as the secondary icon for the entry. Whether the secondary icon is sensitive. An insensitive icon appears grayed out. GTK does not emit the [signal@Gtk.Entry::icon-press[ and [signal@Gtk.Entry::icon-release] signals and does not allow DND from insensitive icons. An icon should be set insensitive if the action that would trigger when clicked is currently not available. The representation which is used for the secondary icon of the entry. The contents of the tooltip on the secondary icon, with markup. Also see [method@Gtk.Entry.set_icon_tooltip_markup]. The contents of the tooltip on the secondary icon. Also see [method@Gtk.Entry.set_icon_tooltip_text]. Whether the entry will show an Emoji icon in the secondary icon position to open the Emoji chooser. A list of tabstops to apply to the text of the entry. The length of the text in the `GtkEntry`. When %TRUE, pasted multi-line text is truncated to the first line. Whether the entry should show the “invisible char” instead of the actual text (“password mode”). Emitted when the entry is activated. The keybindings for this signal are all forms of the Enter key. Emitted when an activatable icon is clicked. The position of the clicked icon Emitted on the button release from a mouse click over an activatable icon. The position of the clicked icon Holds the text that is displayed in a single-line text entry widget. A single `GtkEntryBuffer` object can be shared by multiple widgets which will then share the same text content, but not the cursor position, visibility attributes, icon etc. `GtkEntryBuffer` may be derived from. Such a derived class might allow text to be stored in an alternate location, such as non-pageable memory, useful in the case of important passwords. Or a derived class could integrate with an application’s concept of undo/redo. Create a new `GtkEntryBuffer` object. Optionally, specify initial text to set in the buffer. A new `GtkEntryBuffer` object. initial buffer text number of characters in @initial_chars, or -1 Deletes a sequence of characters from the buffer. @n_chars characters are deleted starting at @position. If @n_chars is negative, then all characters until the end of the text are deleted. If @position or @n_chars are out of bounds, then they are coerced to sane values. Note that the positions are specified in characters, not bytes. The number of characters deleted. a `GtkEntryBuffer` position at which to delete text number of characters to delete Retrieves the length in characters of the buffer. The number of characters in the buffer. a `GtkEntryBuffer` Inserts @n_chars characters of @chars into the contents of the buffer, at position @position. If @n_chars is negative, then characters from chars will be inserted until a null-terminator is found. If @position or @n_chars are out of bounds, or the maximum buffer text length is exceeded, then they are coerced to sane values. Note that the position and length are in characters, not in bytes. The number of characters actually inserted. a `GtkEntryBuffer` the position at which to insert text. the text to insert into the buffer. the length of the text in characters, or -1 Deletes a sequence of characters from the buffer. @n_chars characters are deleted starting at @position. If @n_chars is negative, then all characters until the end of the text are deleted. If @position or @n_chars are out of bounds, then they are coerced to sane values. Note that the positions are specified in characters, not bytes. The number of characters deleted. a `GtkEntryBuffer` position at which to delete text number of characters to delete Used when subclassing `GtkEntryBuffer`. a `GtkEntryBuffer` position at which text was deleted number of characters deleted Used when subclassing `GtkEntryBuffer`. a `GtkEntryBuffer` position at which text was inserted text that was inserted number of characters inserted Retrieves the length in bytes of the buffer. See [method@Gtk.EntryBuffer.get_length]. The byte length of the buffer. a `GtkEntryBuffer` Retrieves the length in characters of the buffer. The number of characters in the buffer. a `GtkEntryBuffer` Retrieves the maximum allowed length of the text in @buffer. the maximum allowed number of characters in `GtkEntryBuffer`, or 0 if there is no maximum. a `GtkEntryBuffer` Retrieves the contents of the buffer. The memory pointer returned by this call will not change unless this object emits a signal, or is finalized. a pointer to the contents of the widget as a string. This string points to internally allocated storage in the buffer and must not be freed, modified or stored. a `GtkEntryBuffer` Inserts @n_chars characters of @chars into the contents of the buffer, at position @position. If @n_chars is negative, then characters from chars will be inserted until a null-terminator is found. If @position or @n_chars are out of bounds, or the maximum buffer text length is exceeded, then they are coerced to sane values. Note that the position and length are in characters, not in bytes. The number of characters actually inserted. a `GtkEntryBuffer` the position at which to insert text. the text to insert into the buffer. the length of the text in characters, or -1 Sets the maximum allowed length of the contents of the buffer. If the current contents are longer than the given length, then they will be truncated to fit. a `GtkEntryBuffer` the maximum length of the entry buffer, or 0 for no maximum. (other than the maximum length of entries.) The value passed in will be clamped to the range 0-65536. Sets the text in the buffer. This is roughly equivalent to calling [method@Gtk.EntryBuffer.delete_text] and [method@Gtk.EntryBuffer.insert_text]. Note that @n_chars is in characters, not in bytes. a `GtkEntryBuffer` the new text the number of characters in @text, or -1 The length (in characters) of the text in buffer. The maximum length (in characters) of the text in the buffer. The contents of the buffer. The text is altered in the default handler for this signal. If you want access to the text after the text has been modified, use %G_CONNECT_AFTER. the position the text was deleted at. The number of characters that were deleted. This signal is emitted after text is inserted into the buffer. the position the text was inserted at. The text that was inserted. The number of characters that were inserted. The number of characters in the buffer. a `GtkEntryBuffer` The number of characters actually inserted. a `GtkEntryBuffer` the position at which to insert text. the text to insert into the buffer. the length of the text in characters, or -1 The number of characters deleted. a `GtkEntryBuffer` position at which to delete text number of characters to delete Class structure for `GtkEntry`. All virtual functions have a default implementation. Derived classes may set the virtual function pointers for the signal handlers to %NULL, but must keep @get_text_area_size and @get_frame_size non-%NULL; either use the default implementation, or provide a custom one. The parent class. Class handler for the `GtkEntry::activate` signal. The default implementation activates the gtk.activate-default action. `GtkEntryCompletion` is an auxiliary object to provide completion functionality for `GtkEntry`. It implements the [iface@Gtk.CellLayout] interface, to allow the user to add extra cells to the `GtkTreeView` with completion matches. “Completion functionality” means that when the user modifies the text in the entry, `GtkEntryCompletion` checks which rows in the model match the current content of the entry, and displays a list of matches. By default, the matching is done by comparing the entry text case-insensitively against the text column of the model (see [method@Gtk.EntryCompletion.set_text_column]), but this can be overridden with a custom match function (see [method@Gtk.EntryCompletion.set_match_func]). When the user selects a completion, the content of the entry is updated. By default, the content of the entry is replaced by the text column of the model, but this can be overridden by connecting to the [signal@Gtk.EntryCompletion::match-selected] signal and updating the entry in the signal handler. Note that you should return %TRUE from the signal handler to suppress the default behaviour. To add completion functionality to an entry, use [method@Gtk.Entry.set_completion]. `GtkEntryCompletion` uses a [class@Gtk.TreeModelFilter] model to represent the subset of the entire model that is currently matching. While the `GtkEntryCompletion` signals [signal@Gtk.EntryCompletion::match-selected] and [signal@Gtk.EntryCompletion::cursor-on-match] take the original model and an iter pointing to that model as arguments, other callbacks and signals (such as `GtkCellLayoutDataFunc` or [signal@Gtk.CellArea::apply-attributes)] will generally take the filter model as argument. As long as you are only calling [method@Gtk.TreeModel.get], this will make no difference to you. If for some reason, you need the original model, use [method@Gtk.TreeModelFilter.get_model]. Don’t forget to use [method@Gtk.TreeModelFilter.convert_iter_to_child_iter] to obtain a matching iter. Creates a new `GtkEntryCompletion` object. GtkEntryCompletion will be removed in GTK 5. A newly created `GtkEntryCompletion` object Creates a new `GtkEntryCompletion` object using the specified @area. The `GtkCellArea` is used to layout cells in the underlying `GtkTreeViewColumn` for the drop-down menu. GtkEntryCompletion will be removed in GTK 5. A newly created `GtkEntryCompletion` object the `GtkCellArea` used to layout cells Requests a completion operation, or in other words a refiltering of the current list with completions, using the current key. The completion list view will be updated accordingly. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` Computes the common prefix that is shared by all rows in @completion that start with @key. If no row matches @key, %NULL will be returned. Note that a text column must have been set for this function to work, see [method@Gtk.EntryCompletion.set_text_column] for details. GtkEntryCompletion will be removed in GTK 5. The common prefix all rows starting with @key the entry completion The text to complete for Get the original text entered by the user that triggered the completion or %NULL if there’s no completion ongoing. GtkEntryCompletion will be removed in GTK 5. the prefix for the current completion a `GtkEntryCompletion` Gets the entry @completion has been attached to. GtkEntryCompletion will be removed in GTK 5. The entry @completion has been attached to a `GtkEntryCompletion` Returns whether the common prefix of the possible completions should be automatically inserted in the entry. GtkEntryCompletion will be removed in GTK 5. %TRUE if inline completion is turned on a `GtkEntryCompletion` Returns %TRUE if inline-selection mode is turned on. GtkEntryCompletion will be removed in GTK 5. %TRUE if inline-selection mode is on a `GtkEntryCompletion` Returns the minimum key length as set for @completion. GtkEntryCompletion will be removed in GTK 5. The currently used minimum key length a `GtkEntryCompletion` Returns the model the `GtkEntryCompletion` is using as data source. Returns %NULL if the model is unset. GtkEntryCompletion will be removed in GTK 5. A `GtkTreeModel` a `GtkEntryCompletion` Returns whether the completions should be presented in a popup window. GtkEntryCompletion will be removed in GTK 5. %TRUE if popup completion is turned on a `GtkEntryCompletion` Returns whether the completion popup window will be resized to the width of the entry. GtkEntryCompletion will be removed in GTK 5. %TRUE if the popup window will be resized to the width of the entry a `GtkEntryCompletion` Returns whether the completion popup window will appear even if there is only a single match. GtkEntryCompletion will be removed in GTK 5. %TRUE if the popup window will appear regardless of the number of matches a `GtkEntryCompletion` Returns the column in the model of @completion to get strings from. GtkEntryCompletion will be removed in GTK 5. the column containing the strings a `GtkEntryCompletion` Requests a prefix insertion. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` Sets whether the common prefix of the possible completions should be automatically inserted in the entry. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` %TRUE to do inline completion Sets whether it is possible to cycle through the possible completions inside the entry. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` %TRUE to do inline selection Sets the match function for @completion to be @func. The match function is used to determine if a row should or should not be in the completion list. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` the `GtkEntryCompletion`MatchFunc to use user data for @func destroy notify for @func_data. Requires the length of the search key for @completion to be at least @length. This is useful for long lists, where completing using a small key takes a lot of time and will come up with meaningless results anyway (ie, a too large dataset). GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` the minimum length of the key in order to start completing Sets the model for a `GtkEntryCompletion`. If @completion already has a model set, it will remove it before setting the new model. If model is %NULL, then it will unset the model. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` the `GtkTreeModel` Sets whether the completions should be presented in a popup window. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` %TRUE to do popup completion Sets whether the completion popup window will be resized to be the same width as the entry. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` %TRUE to make the width of the popup the same as the entry Sets whether the completion popup window will appear even if there is only a single match. You may want to set this to %FALSE if you are using [property@Gtk.EntryCompletion:inline-completion]. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` %TRUE if the popup should appear even for a single match Convenience function for setting up the most used case of this code: a completion list with just strings. This function will set up @completion to have a list displaying all (and just) strings in the completion list, and to get those strings from @column in the model of @completion. This functions creates and adds a `GtkCellRendererText` for the selected column. If you need to set the text column, but don't want the cell renderer, use g_object_set() to set the [property@Gtk.EntryCompletion:text-column] property directly. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` the column in the model of @completion to get strings from The `GtkCellArea` used to layout cell renderers in the treeview column. If no area is specified when creating the entry completion with [ctor@Gtk.EntryCompletion.new_with_area], a horizontally oriented [class@Gtk.CellAreaBox] will be used. Determines whether the common prefix of the possible completions should be inserted automatically in the entry. Note that this requires text-column to be set, even if you are using a custom match function. Determines whether the possible completions on the popup will appear in the entry as you navigate through them. The minimum key length as set for completion. The model used as data source. Determines whether the possible completions should be shown in a popup window. Determines whether the completions popup window will be resized to the width of the entry. Determines whether the completions popup window will shown for a single possible completion. You probably want to set this to %FALSE if you are using [property@Gtk.EntryCompletion:inline-completion]. The column of the model containing the strings. Note that the strings must be UTF-8. Emitted when a match from the cursor is on a match of the list. The default behaviour is to replace the contents of the entry with the contents of the text column in the row pointed to by @iter. Note that @model is the model that was passed to [method@Gtk.EntryCompletion.set_model]. %TRUE if the signal has been handled the `GtkTreeModel` containing the matches a `GtkTreeIter` positioned at the selected match Emitted when the inline autocompletion is triggered. The default behaviour is to make the entry display the whole prefix and select the newly inserted part. Applications may connect to this signal in order to insert only a smaller part of the @prefix into the entry - e.g. the entry used in the `GtkFileChooser` inserts only the part of the prefix up to the next '/'. %TRUE if the signal has been handled the common prefix of all possible completions Emitted when a match from the list is selected. The default behaviour is to replace the contents of the entry with the contents of the text column in the row pointed to by @iter. Note that @model is the model that was passed to [method@Gtk.EntryCompletion.set_model]. %TRUE if the signal has been handled the `GtkTreeModel` containing the matches a `GtkTreeIter` positioned at the selected match Emitted when the filter model has zero number of rows in completion_complete method. In other words when `GtkEntryCompletion` is out of suggestions. A function which decides whether the row indicated by @iter matches a given @key, and should be displayed as a possible completion for @key. Note that @key is normalized and case-folded (see g_utf8_normalize() and g_utf8_casefold()). If this is not appropriate, match functions have access to the unmodified key via `gtk_editable_get_text (GTK_EDITABLE (gtk_entry_completion_get_entry ()))`. There is no replacement %TRUE if @iter should be displayed as a possible completion for @key the `GtkEntryCompletion` the string to match, normalized and case-folded a `GtkTreeIter` indicating the row to match user data given to gtk_entry_completion_set_match_func() Specifies the side of the entry at which an icon is placed. At the beginning of the entry (depending on the text direction). At the end of the entry (depending on the text direction). The base class for event controllers. These are ancillary objects associated to widgets, which react to `GdkEvents`, and possibly trigger actions as a consequence. Event controllers are added to a widget with [method@Gtk.Widget.add_controller]. It is rarely necessary to explicitly remove a controller with [method@Gtk.Widget.remove_controller]. See the chapter on [input handling](input-handling.html) for an overview of the basic concepts, such as the capture and bubble phases of event propagation. Returns the event that is currently being handled by the controller. At other times, %NULL is returned. the event that is currently handled by @controller a `GtkEventController` Returns the device of the event that is currently being handled by the controller. At other times, %NULL is returned. device of the event is currently handled by @controller a `GtkEventController` Returns the modifier state of the event that is currently being handled by the controller. At other times, 0 is returned. modifier state of the event is currently handled by @controller a `GtkEventController` Returns the timestamp of the event that is currently being handled by the controller. At other times, 0 is returned. timestamp of the event is currently handled by @controller a `GtkEventController` Gets the name of @controller. The controller name a `GtkEventController` Gets the propagation limit of the event controller. the propagation limit a `GtkEventController` Gets the propagation phase at which @controller handles events. the propagation phase a `GtkEventController` Returns the `GtkWidget` this controller relates to. a `GtkWidget` a `GtkEventController` Resets the @controller to a clean state. a `GtkEventController` Sets a name on the controller that can be used for debugging. a `GtkEventController` a name for @controller Sets the event propagation limit on the event controller. If the limit is set to %GTK_LIMIT_SAME_NATIVE, the controller won't handle events that are targeted at widgets on a different surface, such as popovers. a `GtkEventController` the propagation limit Sets the propagation phase at which a controller handles events. If @phase is %GTK_PHASE_NONE, no automatic event handling will be performed, but other additional gesture maintenance will. a `GtkEventController` a propagation phase Sets a name on the controller that can be used for debugging. a `GtkEventController` a name for @controller, must be a static string The name for this controller, typically used for debugging purposes. The limit for which events this controller will handle. The propagation phase at which this controller will handle events. The widget receiving the `GdkEvents` that the controller will handle. Tracks keyboard focus. The event controller offers [signal@Gtk.EventControllerFocus::enter] and [signal@Gtk.EventControllerFocus::leave] signals, as well as [property@Gtk.EventControllerFocus:is-focus] and [property@Gtk.EventControllerFocus:contains-focus] properties which are updated to reflect focus changes inside the widget hierarchy that is rooted at the controllers widget. Creates a new event controller that will handle focus events. a new `GtkEventControllerFocus` Returns %TRUE if focus is within @self or one of its children. %TRUE if focus is within @self or one of its children a `GtkEventControllerFocus` Returns %TRUE if focus is within @self, but not one of its children. %TRUE if focus is within @self, but not one of its children a `GtkEventControllerFocus` %TRUE if focus is contained in the controllers widget. See [property@Gtk.EventControllerFocus:is-focus] for whether the focus is in the widget itself or inside a descendent. When handling focus events, this property is updated before [signal@Gtk.EventControllerFocus::enter] or [signal@Gtk.EventControllerFocus::leave] are emitted. %TRUE if focus is in the controllers widget itself, as opposed to in a descendent widget. See also [property@Gtk.EventControllerFocus:contains-focus]. When handling focus events, this property is updated before [signal@Gtk.EventControllerFocus::enter] or [signal@Gtk.EventControllerFocus::leave] are emitted. Emitted whenever the focus enters into the widget or one of its descendents. Note that this means you may not get an ::enter signal even though the widget becomes the focus location, in certain cases (such as when the focus moves from a descendent of the widget to the widget itself). If you are interested in these cases, you can monitor the [property@Gtk.EventControllerFocus:is-focus] property for changes. Emitted whenever the focus leaves the widget hierarchy that is rooted at the widget that the controller is attached to. Note that this means you may not get a ::leave signal even though the focus moves away from the widget, in certain cases (such as when the focus moves from the widget to a descendent). If you are interested in these cases, you can monitor the [property@Gtk.EventControllerFocus:is-focus] property for changes. Provides access to key events. Creates a new event controller that will handle key events. a new `GtkEventControllerKey` Forwards the current event of this @controller to a @widget. This function can only be used in handlers for the [signal@Gtk.EventControllerKey::key-pressed], [signal@Gtk.EventControllerKey::key-released] or [signal@Gtk.EventControllerKey::modifiers] signals. whether the @widget handled the event a `GtkEventControllerKey` a `GtkWidget` Gets the key group of the current event of this @controller. See [method@Gdk.KeyEvent.get_layout]. the key group a `GtkEventControllerKey` Gets the input method context of the key @controller. the `GtkIMContext` a `GtkEventControllerKey` Sets the input method context of the key @controller. a `GtkEventControllerKey` a `GtkIMContext` Emitted whenever the input method context filters away a keypress and prevents the @controller receiving it. See [method@Gtk.EventControllerKey.set_im_context] and [method@Gtk.IMContext.filter_keypress]. Emitted whenever a key is pressed. %TRUE if the key press was handled, %FALSE otherwise. the pressed key. the raw code of the pressed key. the bitmask, representing the state of modifier keys and pointer buttons. Emitted whenever a key is released. the released key. the raw code of the released key. the bitmask, representing the state of modifier keys and pointer buttons. Emitted whenever the state of modifier keys and pointer buttons change. whether to ignore modifiers the bitmask, representing the new state of modifier keys and pointer buttons. Provides raw access to the event stream. It should only be used as a last resort if none of the other event controllers or gestures do the job. Creates a new legacy event controller. the newly created event controller. Emitted for each GDK event delivered to @controller. %TRUE to stop other handlers from being invoked for the event and the emission of this signal. %FALSE to propagate the event further. the `GdkEvent` which triggered this signal Tracks the pointer position. The event controller offers [signal@Gtk.EventControllerMotion::enter] and [signal@Gtk.EventControllerMotion::leave] signals, as well as [property@Gtk.EventControllerMotion:is-pointer] and [property@Gtk.EventControllerMotion:contains-pointer] properties which are updated to reflect changes in the pointer position as it moves over the widget. Creates a new event controller that will handle motion events. a new `GtkEventControllerMotion` Returns if a pointer is within @self or one of its children. %TRUE if a pointer is within @self or one of its children a `GtkEventControllerMotion` Returns if a pointer is within @self, but not one of its children. %TRUE if a pointer is within @self but not one of its children a `GtkEventControllerMotion` Whether the pointer is in the controllers widget or a descendant. See also [property@Gtk.EventControllerMotion:is-pointer]. When handling crossing events, this property is updated before [signal@Gtk.EventControllerMotion::enter], but after [signal@Gtk.EventControllerMotion::leave] is emitted. Whether the pointer is in the controllers widget itself, as opposed to in a descendent widget. See also [property@Gtk.EventControllerMotion:contains-pointer]. When handling crossing events, this property is updated before [signal@Gtk.EventControllerMotion::enter], but after [signal@Gtk.EventControllerMotion::leave] is emitted. Signals that the pointer has entered the widget. coordinates of pointer location coordinates of pointer location Signals that the pointer has left the widget. Emitted when the pointer moves inside the widget. the x coordinate the y coordinate Handles scroll events. It is capable of handling both discrete and continuous scroll events from mice or touchpads, abstracting them both with the [signal@Gtk.EventControllerScroll::scroll] signal. Deltas in the discrete case are multiples of 1. In the case of continuous scroll events, `GtkEventControllerScroll` encloses all [signal@Gtk.EventControllerScroll::scroll] emissions between two [signal@Gtk.EventControllerScroll::scroll-begin] and [signal@Gtk.EventControllerScroll::scroll-end] signals. The behavior of the event controller can be modified by the flags given at creation time, or modified at a later point through [method@Gtk.EventControllerScroll.set_flags] (e.g. because the scrolling conditions of the widget changed). The controller can be set up to emit motion for either/both vertical and horizontal scroll events through %GTK_EVENT_CONTROLLER_SCROLL_VERTICAL, %GTK_EVENT_CONTROLLER_SCROLL_HORIZONTAL and %GTK_EVENT_CONTROLLER_SCROLL_BOTH_AXES. If any axis is disabled, the respective [signal@Gtk.EventControllerScroll::scroll] delta will be 0. Vertical scroll events will be translated to horizontal motion for the devices incapable of horizontal scrolling. The event controller can also be forced to emit discrete events on all devices through %GTK_EVENT_CONTROLLER_SCROLL_DISCRETE. This can be used to implement discrete actions triggered through scroll events (e.g. switching across combobox options). The %GTK_EVENT_CONTROLLER_SCROLL_KINETIC flag toggles the emission of the [signal@Gtk.EventControllerScroll::decelerate] signal, emitted at the end of scrolling with two X/Y velocity arguments that are consistent with the motion that was received. Creates a new event controller that will handle scroll events. a new `GtkEventControllerScroll` flags affecting the controller behavior Gets the flags conditioning the scroll controller behavior. the controller flags. a `GtkEventControllerScroll` Gets the scroll unit of the last [signal@Gtk.EventControllerScroll::scroll] signal received. Always returns %GDK_SCROLL_UNIT_WHEEL if the %GTK_EVENT_CONTROLLER_SCROLL_DISCRETE flag is set. the scroll unit. a `GtkEventControllerScroll`. Sets the flags conditioning scroll controller behavior. a `GtkEventControllerScroll` flags affecting the controller behavior The flags affecting event controller behavior. Emitted after scroll is finished if the %GTK_EVENT_CONTROLLER_SCROLL_KINETIC flag is set. @vel_x and @vel_y express the initial velocity that was imprinted by the scroll events. @vel_x and @vel_y are expressed in pixels/ms. X velocity Y velocity Signals that the widget should scroll by the amount specified by @dx and @dy. For the representation unit of the deltas, see [method@Gtk.EventControllerScroll.get_unit]. %TRUE if the scroll event was handled, %FALSE otherwise. X delta Y delta Signals that a new scrolling operation has begun. It will only be emitted on devices capable of it. Signals that a scrolling operation has finished. It will only be emitted on devices capable of it. Describes the behavior of a `GtkEventControllerScroll`. Don't emit scroll. Emit scroll with vertical deltas. Emit scroll with horizontal deltas. Only emit deltas that are multiples of 1. Emit ::decelerate after continuous scroll finishes. A #GtkEventControllerScrollFlags value to prefer physical direction over logical direction (i.e. oblivious to natural scroll). Emit scroll on both axes. Describes the state of a [struct@Gdk.EventSequence] in a [class@Gesture]. The sequence is handled, but not grabbed. The sequence is handled and grabbed. The sequence is denied. Matches an item when each of its filters matches. To add filters to a `GtkEveryFilter`, use [method@Gtk.MultiFilter.append]. Creates a new empty "every" filter. Use [method@Gtk.MultiFilter.append] to add filters to it. This filter matches an item if each of the filters added to it matches the item. In particular, this means that if no filter has been added to it, the filter matches every item. a new `GtkEveryFilter` Allows the user to reveal or conceal a child widget. <picture> <source srcset="expander-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkExpander" src="expander.png"> </picture> This is similar to the triangles used in a `GtkTreeView`. Normally you use an expander as you would use a frame; you create the child widget and use [method@Gtk.Expander.set_child] to add it to the expander. When the expander is toggled, it will take care of showing and hiding the child automatically. # Special Usage There are situations in which you may prefer to show and hide the expanded widget yourself, such as when you want to actually create the widget at expansion time. In this case, create a `GtkExpander` but do not add a child to it. The expander widget has an [property@Gtk.Expander:expanded] property which can be used to monitor its expansion state. You should watch this property with a signal connection as follows: ```c static void expander_callback (GObject *object, GParamSpec *param_spec, gpointer user_data) { GtkExpander *expander; expander = GTK_EXPANDER (object); if (gtk_expander_get_expanded (expander)) { // Show or create widgets } else { // Hide or destroy widgets } } static void create_expander (void) { GtkWidget *expander = gtk_expander_new_with_mnemonic ("_More Options"); g_signal_connect (expander, "notify::expanded", G_CALLBACK (expander_callback), NULL); // ... } ``` # GtkExpander as GtkBuildable An example of a UI definition fragment with GtkExpander: ```xml <object class="GtkExpander"> <property name="label-widget"> <object class="GtkLabel" id="expander-label"/> </property> <property name="child"> <object class="GtkEntry" id="expander-content"/> </property> </object> ``` # CSS nodes ``` expander-widget ╰── box ├── title │ ├── expander │ ╰── <label widget> ╰── <child> ``` `GtkExpander` has a main node `expander-widget`, and subnode `box` containing the title and child widget. The box subnode `title` contains node `expander`, i.e. the expand/collapse arrow; then the label widget if any. The arrow of an expander that is showing its child gets the `:checked` pseudoclass set on it. # Accessibility `GtkExpander` uses the [enum@Gtk.AccessibleRole.button] role. Creates a new expander using @label as the text of the label. a new `GtkExpander` widget. the text of the label Creates a new expander using @label as the text of the label. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button. a new `GtkExpander` widget. the text of the label with an underscore in front of the mnemonic character Gets the child widget of @expander. the child widget of @expander a `GtkExpander` Queries a `GtkExpander` and returns its current state. Returns %TRUE if the child widget is revealed. the current state of the expander a `GtkExpander` Fetches the text from a label widget. This is including any embedded underlines indicating mnemonics and Pango markup, as set by [method@Gtk.Expander.set_label]. If the label text has not been set the return value will be %NULL. This will be the case if you create an empty button with gtk_button_new() to use as a container. The text of the label widget. This string is owned by the widget and must not be modified or freed. a `GtkExpander` Retrieves the label widget for the frame. the label widget a `GtkExpander` Returns whether the expander will resize the toplevel widget containing the expander upon resizing and collapsing. the “resize toplevel” setting. a `GtkExpander` Returns whether the label’s text is interpreted as Pango markup. %TRUE if the label’s text will be parsed for markup a `GtkExpander` Returns whether an underline in the text indicates a mnemonic. %TRUE if an embedded underline in the expander label indicates the mnemonic accelerator keys a `GtkExpander` Sets the child widget of @expander. a `GtkExpander` the child widget Sets the state of the expander. Set to %TRUE, if you want the child widget to be revealed, and %FALSE if you want the child widget to be hidden. a `GtkExpander` whether the child widget is revealed Sets the text of the label of the expander to @label. This will also clear any previously set labels. a `GtkExpander` a string Set the label widget for the expander. This is the widget that will appear embedded alongside the expander arrow. a `GtkExpander` the new label widget Sets whether the expander will resize the toplevel widget containing the expander upon resizing and collapsing. a `GtkExpander` whether to resize the toplevel Sets whether the text of the label contains Pango markup. a `GtkExpander` %TRUE if the label’s text should be parsed for markup If true, an underline in the text indicates a mnemonic. a `GtkExpander` %TRUE if underlines in the text indicate mnemonics The child widget. Whether the expander has been opened to reveal the child. The text of the expanders label. A widget to display instead of the usual expander label. When this property is %TRUE, the expander will resize the toplevel widget containing the expander upon expanding and collapsing. Whether the text in the label is Pango markup. Whether an underline in the text indicates a mnemonic. Activates the `GtkExpander`. Provides a way to describe references to values. An important aspect of expressions is that the value can be obtained from a source that is several steps away. For example, an expression may describe ‘the value of property A of `object1`, which is itself the value of a property of `object2`’. And `object1` may not even exist yet at the time that the expression is created. This is contrast to `GObject` property bindings, which can only create direct connections between the properties of two objects that must both exist for the duration of the binding. An expression needs to be "evaluated" to obtain the value that it currently refers to. An evaluation always happens in the context of a current object called `this` (it mirrors the behavior of object-oriented languages), which may or may not influence the result of the evaluation. Use [method@Gtk.Expression.evaluate] for evaluating an expression. Various methods for defining expressions exist, from simple constants via [ctor@Gtk.ConstantExpression.new] to looking up properties in a `GObject` (even recursively) via [ctor@Gtk.PropertyExpression.new] or providing custom functions to transform and combine expressions via [ctor@Gtk.ClosureExpression.new]. Here is an example of a complex expression: ```c color_expr = gtk_property_expression_new (GTK_TYPE_LIST_ITEM, NULL, "item"); expression = gtk_property_expression_new (GTK_TYPE_COLOR, color_expr, "name"); ``` when evaluated with `this` being a `GtkListItem`, it will obtain the "item" property from the `GtkListItem`, and then obtain the "name" property from the resulting object (which is assumed to be of type `GTK_TYPE_COLOR`). A more concise way to describe this would be ``` this->item->name ``` The most likely place where you will encounter expressions is in the context of list models and list widgets using them. For example, `GtkDropDown` is evaluating a `GtkExpression` to obtain strings from the items in its model that it can then use to match against the contents of its search entry. `GtkStringFilter` is using a `GtkExpression` for similar reasons. By default, expressions are not paying attention to changes and evaluation is just a snapshot of the current state at a given time. To get informed about changes, an expression needs to be "watched" via a [struct@Gtk.ExpressionWatch], which will cause a callback to be called whenever the value of the expression may have changed; [method@Gtk.Expression.watch] starts watching an expression, and [method@Gtk.ExpressionWatch.unwatch] stops. Watches can be created for automatically updating the property of an object, similar to GObject's `GBinding` mechanism, by using [method@Gtk.Expression.bind]. ## GtkExpression in GObject properties In order to use a `GtkExpression` as a `GObject` property, you must use the [func@Gtk.param_spec_expression] when creating a `GParamSpec` to install in the `GObject` class being defined; for instance: ```c obj_props[PROP_EXPRESSION] = gtk_param_spec_expression ("expression", "Expression", "The expression used by the widget", G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY); ``` When implementing the `GObjectClass.set_property` and `GObjectClass.get_property` virtual functions, you must use [func@Gtk.value_get_expression], to retrieve the stored `GtkExpression` from the `GValue` container, and [func@Gtk.value_set_expression], to store the `GtkExpression` into the `GValue`; for instance: ```c // in set_property()... case PROP_EXPRESSION: foo_widget_set_expression (foo, gtk_value_get_expression (value)); break; // in get_property()... case PROP_EXPRESSION: gtk_value_set_expression (value, foo->expression); break; ``` ## GtkExpression in .ui files `GtkBuilder` has support for creating expressions. The syntax here can be used where a `GtkExpression` object is needed like in a `<property>` tag for an expression property, or in a `<binding name="property">` tag to bind a property to an expression. To create a property expression, use the `<lookup>` element. It can have a `type` attribute to specify the object type, and a `name` attribute to specify the property to look up. The content of `<lookup>` can either be a string that specifies the name of the object to use, an element specifying an expression to provide an object, or empty to use the `this` object. Example: ```xml <lookup name='search'>string_filter</lookup> ``` Since the `<lookup>` element creates an expression and its element content can itself be an expression, this means that `<lookup>` tags can also be nested. This is a common idiom when dealing with `GtkListItem`s. See [class@Gtk.BuilderListItemFactory] for an example of this technique. To create a constant expression, use the `<constant>` element. If the type attribute is specified, the element content is interpreted as a value of that type, and the initial attribute can be specified to get the initial value for that type. Otherwise, it is assumed to be an object. For instance: ```xml <constant>string_filter</constant> <constant type='gchararray'>Hello, world</constant> <constant type='gchararray' initial='true' /> <!-- NULL --> ``` String (`type='gchararray'`) constants can be marked for translation with the `translatable=` attribute, and will then be looked up in the [property@Gtk.Builder:translation-domain] when the expression is constructed. ```xml <constant type='gchararray' translatable='yes'>I'm translatable!</constant> ``` As with other translatable strings in [type@Gtk.Builder], constants can also have a context and/or translation comment: ```xml <constant type='gchararray' translatable='yes' context='example' comments='A sample string'>I'm translatable!</constant> ``` To create a closure expression, use the `<closure>` element. The `function` attribute specifies what function to use for the closure, and the `type` attribute specifies its return type. The content of the element contains the expressions for the parameters. For instance: ```xml <closure type='gchararray' function='combine_args_somehow'> <constant type='gchararray'>File size:</constant> <lookup type='GFile' name='size'>myfile</lookup> </closure> ``` If an expression can fail, a `<try>` element can be used to provide fallbacks. The expressions are tried from top to bottom until one of them succeeds. If none of the expressions succeed, the expression fails as normal: ```xml <try> <lookup type='GtkWindow' name='title'> <lookup type='GtkLabel' name='root'></lookup> </lookup> <constant type='gchararray'>Hello World</constant> </try> ``` To create a property binding, use the `<binding>` element in place of where a `<property>` tag would ordinarily be used. The `name` and `object` attributes are supported. The `name` attribute is required, and pertains to the applicable property name. The `object` attribute is optional. If provided, it will use the specified object as the `this` object when the expression is evaluated. Here is an example in which the `label` property of a `GtkLabel` is bound to the `string` property of another arbitrary object: ```xml <object class='GtkLabel'> <binding name='label'> <lookup name='string'>some_other_object</lookup> </binding> </object> ``` Bind `target`'s property named `property` to `self`. The value that `self` evaluates to is set via `g_object_set()` on `target`. This is repeated whenever `self` changes to ensure that the object's property stays synchronized with `self`. If `self`'s evaluation fails, `target`'s `property` is not updated. Use a [class@Gtk.TryExpression] to provide a fallback for this case. Note that this function takes ownership of `self`. If you want to keep it around, you should [method@Gtk.Expression.ref] it beforehand. a `GtkExpressionWatch` a `GtkExpression` the target object to bind to name of the property on `target` to bind to the this argument for the evaluation of `self` Evaluates the given expression and on success stores the result in @value. The `GType` of `value` will be the type given by [method@Gtk.Expression.get_value_type]. It is possible that expressions cannot be evaluated - for example when the expression references objects that have been destroyed or set to `NULL`. In that case `value` will remain empty and `FALSE` will be returned. `TRUE` if the expression could be evaluated a `GtkExpression` the this argument for the evaluation an empty `GValue` Gets the `GType` that this expression evaluates to. This type is constant and will not change over the lifetime of this expression. The type returned from [method@Gtk.Expression.evaluate] a `GtkExpression` Checks if the expression is static. A static expression will never change its result when [method@Gtk.Expression.evaluate] is called on it with the same arguments. That means a call to [method@Gtk.Expression.watch] is not necessary because it will never trigger a notify. `TRUE` if the expression is static a `GtkExpression` Acquires a reference on the given `GtkExpression`. the `GtkExpression` with an additional reference a `GtkExpression` Releases a reference on the given `GtkExpression`. If the reference was the last, the resources associated to the `self` are freed. a `GtkExpression` Watch the given `expression` for changes. The @notify function will be called whenever the evaluation of `self` may have changed. GTK cannot guarantee that the evaluation did indeed change when the @notify gets invoked, but it guarantees the opposite: When it did in fact change, the @notify will be invoked. The newly installed watch. Note that the only reference held to the watch will be released when the watch is unwatched which can happen automatically, and not just via [method@Gtk.ExpressionWatch.unwatch]. You should call [method@Gtk.ExpressionWatch.ref] if you want to keep the watch around. a `GtkExpression` the `this` argument to watch callback to invoke when the expression changes user data to pass to the `notify` callback destroy notify for `user_data` Callback called by gtk_expression_watch() when the expression value changes. data passed to gtk_expression_watch() An opaque structure representing a watched `GtkExpression`. The contents of `GtkExpressionWatch` should only be accessed through the provided API. Evaluates the watched expression and on success stores the result in `value`. This is equivalent to calling [method@Gtk.Expression.evaluate] with the expression and this pointer originally used to create `watch`. `TRUE` if the expression could be evaluated and `value` was set a `GtkExpressionWatch` an empty `GValue` to be set Acquires a reference on the given `GtkExpressionWatch`. the `GtkExpressionWatch` with an additional reference a `GtkExpressionWatch` Releases a reference on the given `GtkExpressionWatch`. If the reference was the last, the resources associated to `self` are freed. a `GtkExpressionWatch` Stops watching an expression. See [method@Gtk.Expression.watch] for how the watch was established. watch to release `GtkFileChooser` is an interface that can be implemented by file selection widgets. In GTK, the main objects that implement this interface are [class@Gtk.FileChooserWidget] and [class@Gtk.FileChooserDialog]. You do not need to write an object that implements the `GtkFileChooser` interface unless you are trying to adapt an existing file selector to expose a standard programming interface. `GtkFileChooser` allows for shortcuts to various places in the filesystem. In the default implementation these are displayed in the left pane. It may be a bit confusing at first that these shortcuts come from various sources and in various flavours, so lets explain the terminology here: - Bookmarks: are created by the user, by dragging folders from the right pane to the left pane, or by using the “Add”. Bookmarks can be renamed and deleted by the user. - Shortcuts: can be provided by the application. For example, a Paint program may want to add a shortcut for a Clipart folder. Shortcuts cannot be modified by the user. - Volumes: are provided by the underlying filesystem abstraction. They are the “roots” of the filesystem. # File Names and Encodings When the user is finished selecting files in a `GtkFileChooser`, your program can get the selected filenames as `GFile`s. # Adding options You can add extra widgets to a file chooser to provide options that are not present in the default design, by using [method@Gtk.FileChooser.add_choice]. Each choice has an identifier and a user visible label; additionally, each choice can have multiple options. If a choice has no option, it will be rendered as a check button with the given label; if a choice has options, it will be rendered as a combo box. Use [class@Gtk.FileDialog] instead Adds a 'choice' to the file chooser. This is typically implemented as a combobox or, for boolean choices, as a checkbutton. You can select a value using [method@Gtk.FileChooser.set_choice] before the dialog is shown, and you can obtain the user-selected value in the [signal@Gtk.Dialog::response] signal handler using [method@Gtk.FileChooser.get_choice]. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` id for the added choice user-visible label for the added choice ids for the options of the choice, or %NULL for a boolean choice user-visible labels for the options, must be the same length as @options Adds @filter to the list of filters that the user can select between. When a filter is selected, only files that are passed by that filter are displayed. Note that the @chooser takes ownership of the filter if it is floating, so you have to ref and sink it if you want to keep a reference. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` a `GtkFileFilter` Adds a folder to be displayed with the shortcut folders in a file chooser. Use [class@Gtk.FileDialog] instead %TRUE if the folder could be added successfully, %FALSE otherwise. a `GtkFileChooser` a `GFile` for the folder to add Gets the type of operation that the file chooser is performing. Use [class@Gtk.FileDialog] instead the action that the file selector is performing a `GtkFileChooser` Gets the currently selected option in the 'choice' with the given ID. Use [class@Gtk.FileDialog] instead the ID of the currently selected option a `GtkFileChooser` the ID of the choice to get Gets whether file chooser will offer to create new folders. Use [class@Gtk.FileDialog] instead %TRUE if the Create Folder button should be displayed. a `GtkFileChooser` Gets the current folder of @chooser as `GFile`. Use [class@Gtk.FileDialog] instead the `GFile` for the current folder. a `GtkFileChooser` Gets the current name in the file selector, as entered by the user. This is meant to be used in save dialogs, to get the currently typed filename when the file itself does not exist yet. Use [class@Gtk.FileDialog] instead The raw text from the file chooser’s “Name” entry. Free with g_free(). Note that this string is not a full pathname or URI; it is whatever the contents of the entry are. Note also that this string is in UTF-8 encoding, which is not necessarily the system’s encoding for filenames. a `GtkFileChooser` Gets the `GFile` for the currently selected file in the file selector. If multiple files are selected, one of the files will be returned at random. If the file chooser is in folder mode, this function returns the selected folder. Use [class@Gtk.FileDialog] instead a selected `GFile`. You own the returned file; use g_object_unref() to release it. a `GtkFileChooser` Lists all the selected files and subfolders in the current folder of @chooser as `GFile`. Use [class@Gtk.FileDialog] instead a list model containing a `GFile` for each selected file and subfolder in the current folder. Free the returned list with g_object_unref(). a `GtkFileChooser` Gets the current filter. Use [class@Gtk.FileDialog] instead the current filter a `GtkFileChooser` Gets the current set of user-selectable filters, as a list model. See [method@Gtk.FileChooser.add_filter] and [method@Gtk.FileChooser.remove_filter] for changing individual filters. You should not modify the returned list model. Future changes to @chooser may or may not affect the returned model. Use [class@Gtk.FileDialog] instead a `GListModel` containing the current set of user-selectable filters. a `GtkFileChooser` Gets whether multiple files can be selected in the file chooser. Use [class@Gtk.FileDialog] instead %TRUE if multiple files can be selected. a `GtkFileChooser` Queries the list of shortcut folders in the file chooser. You should not modify the returned list model. Future changes to @chooser may or may not affect the returned model. Use [class@Gtk.FileDialog] instead A list model of `GFile`s a `GtkFileChooser` Removes a 'choice' that has been added with gtk_file_chooser_add_choice(). Use [class@Gtk.FileDialog] instead a `GtkFileChooser` the ID of the choice to remove Removes @filter from the list of filters that the user can select between. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` a `GtkFileFilter` Removes a folder from the shortcut folders in a file chooser. Use [class@Gtk.FileDialog] instead %TRUE if the folder could be removed successfully, %FALSE otherwise. a `GtkFileChooser` a `GFile` for the folder to remove Sets the type of operation that the chooser is performing. The user interface is adapted to suit the selected action. For example, an option to create a new folder might be shown if the action is %GTK_FILE_CHOOSER_ACTION_SAVE but not if the action is %GTK_FILE_CHOOSER_ACTION_OPEN. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` the action that the file selector is performing Selects an option in a 'choice' that has been added with gtk_file_chooser_add_choice(). For a boolean choice, the possible options are "true" and "false". Use [class@Gtk.FileDialog] instead a `GtkFileChooser` the ID of the choice to set the ID of the option to select Sets whether file chooser will offer to create new folders. This is only relevant if the action is not set to be %GTK_FILE_CHOOSER_ACTION_OPEN. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` %TRUE if the Create Folder button should be displayed Sets the current folder for @chooser from a `GFile`. Use [class@Gtk.FileDialog] instead %TRUE if the folder could be changed successfully, %FALSE otherwise. a `GtkFileChooser` the `GFile` for the new folder Sets the current name in the file selector, as if entered by the user. Note that the name passed in here is a UTF-8 string rather than a filename. This function is meant for such uses as a suggested name in a “Save As...” dialog. You can pass “Untitled.doc” or a similarly suitable suggestion for the @name. If you want to preselect a particular existing file, you should use [method@Gtk.FileChooser.set_file] instead. Please see the documentation for those functions for an example of using [method@Gtk.FileChooser.set_current_name] as well. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` the filename to use, as a UTF-8 string Sets @file as the current filename for the file chooser. This includes changing to the file’s parent folder and actually selecting the file in list. If the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file’s base name will also appear in the dialog’s file name entry. If the file name isn’t in the current folder of @chooser, then the current folder of @chooser will be changed to the folder containing @file. Note that the file must exist, or nothing will be done except for the directory change. If you are implementing a save dialog, you should use this function if you already have a file name to which the user may save; for example, when the user opens an existing file and then does “Save As…”. If you don’t have a file name already — for example, if the user just created a new file and is saving it for the first time, do not call this function. Instead, use something similar to this: ```c static void prepare_file_chooser (GtkFileChooser *chooser, GFile *existing_file) { gboolean document_is_new = (existing_file == NULL); if (document_is_new) { GFile *default_file_for_saving = g_file_new_for_path ("./out.txt"); // the user just created a new document gtk_file_chooser_set_current_folder (chooser, default_file_for_saving, NULL); gtk_file_chooser_set_current_name (chooser, "Untitled document"); g_object_unref (default_file_for_saving); } else { // the user edited an existing document gtk_file_chooser_set_file (chooser, existing_file, NULL); } } ``` Use [class@Gtk.FileDialog] instead Not useful a `GtkFileChooser` the `GFile` to set as current Sets the current filter. Only the files that pass the filter will be displayed. If the user-selectable list of filters is non-empty, then the filter should be one of the filters in that list. Setting the current filter when the list of filters is empty is useful if you want to restrict the displayed set of files without letting the user change it. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` a `GtkFileFilter` Sets whether multiple files can be selected in the file chooser. This is only relevant if the action is set to be %GTK_FILE_CHOOSER_ACTION_OPEN or %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` %TRUE if multiple files can be selected. The type of operation that the file chooser is performing. Use [class@Gtk.FileDialog] instead Whether a file chooser not in %GTK_FILE_CHOOSER_ACTION_OPEN mode will offer the user to create new folders. Use [class@Gtk.FileDialog] instead The current filter for selecting files that are displayed. Use [class@Gtk.FileDialog] instead A `GListModel` containing the filters that have been added with gtk_file_chooser_add_filter(). The returned object should not be modified. It may or may not be updated for later changes. Use [class@Gtk.FileDialog] instead Whether to allow multiple files to be selected. Use [class@Gtk.FileDialog] instead A `GListModel` containing the shortcut folders that have been added with gtk_file_chooser_add_shortcut_folder(). The returned object should not be modified. It may or may not be updated for later changes. Use [class@Gtk.FileDialog] instead Describes whether a `GtkFileChooser` is being used to open existing files or to save to a possibly new file. Indicates open mode. The file chooser will only let the user pick an existing file. Indicates save mode. The file chooser will let the user pick an existing file, or type in a new filename. Indicates an Open mode for selecting folders. The file chooser will let the user pick an existing folder. `GtkFileChooserDialog` is a dialog suitable for use with “File Open” or “File Save” commands. ![An example GtkFileChooserDialog](filechooser.png) This widget works by putting a [class@Gtk.FileChooserWidget] inside a [class@Gtk.Dialog]. It exposes the [iface@Gtk.FileChooser] interface, so you can use all of the [iface@Gtk.FileChooser] functions on the file chooser dialog as well as those for [class@Gtk.Dialog]. Note that `GtkFileChooserDialog` does not have any methods of its own. Instead, you should use the functions that work on a [iface@Gtk.FileChooser]. If you want to integrate well with the platform you should use the [class@Gtk.FileChooserNative] API, which will use a platform-specific dialog if available and fall back to `GtkFileChooserDialog` otherwise. ## Typical usage In the simplest of cases, you can the following code to use `GtkFileChooserDialog` to select a file for opening: ```c static void on_open_response (GtkDialog *dialog, int response) { if (response == GTK_RESPONSE_ACCEPT) { GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog); g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser); open_file (file); } gtk_window_destroy (GTK_WINDOW (dialog)); } // ... GtkWidget *dialog; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN; dialog = gtk_file_chooser_dialog_new ("Open File", parent_window, action, _("_Cancel"), GTK_RESPONSE_CANCEL, _("_Open"), GTK_RESPONSE_ACCEPT, NULL); gtk_window_present (GTK_WINDOW (dialog)); g_signal_connect (dialog, "response", G_CALLBACK (on_open_response), NULL); ``` To use a dialog for saving, you can use this: ```c static void on_save_response (GtkDialog *dialog, int response) { if (response == GTK_RESPONSE_ACCEPT) { GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog); g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser); save_to_file (file); } gtk_window_destroy (GTK_WINDOW (dialog)); } // ... GtkWidget *dialog; GtkFileChooser *chooser; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE; dialog = gtk_file_chooser_dialog_new ("Save File", parent_window, action, _("_Cancel"), GTK_RESPONSE_CANCEL, _("_Save"), GTK_RESPONSE_ACCEPT, NULL); chooser = GTK_FILE_CHOOSER (dialog); if (user_edited_a_new_document) gtk_file_chooser_set_current_name (chooser, _("Untitled document")); else gtk_file_chooser_set_file (chooser, existing_filename); gtk_window_present (GTK_WINDOW (dialog)); g_signal_connect (dialog, "response", G_CALLBACK (on_save_response), NULL); ``` ## Setting up a file chooser dialog There are various cases in which you may need to use a `GtkFileChooserDialog`: - To select a file for opening, use %GTK_FILE_CHOOSER_ACTION_OPEN. - To save a file for the first time, use %GTK_FILE_CHOOSER_ACTION_SAVE, and suggest a name such as “Untitled” with [method@Gtk.FileChooser.set_current_name]. - To save a file under a different name, use %GTK_FILE_CHOOSER_ACTION_SAVE, and set the existing file with [method@Gtk.FileChooser.set_file]. - To choose a folder instead of a file, use %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. In general, you should only cause the file chooser to show a specific folder when it is appropriate to use [method@Gtk.FileChooser.set_file], i.e. when you are doing a “Save As” command and you already have a file saved somewhere. ## Response Codes `GtkFileChooserDialog` inherits from [class@Gtk.Dialog], so buttons that go in its action area have response codes such as %GTK_RESPONSE_ACCEPT and %GTK_RESPONSE_CANCEL. For example, you could call [ctor@Gtk.FileChooserDialog.new] as follows: ```c GtkWidget *dialog; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN; dialog = gtk_file_chooser_dialog_new ("Open File", parent_window, action, _("_Cancel"), GTK_RESPONSE_CANCEL, _("_Open"), GTK_RESPONSE_ACCEPT, NULL); ``` This will create buttons for “Cancel” and “Open” that use predefined response identifiers from [enum@Gtk.ResponseType]. For most dialog boxes you can use your own custom response codes rather than the ones in [enum@Gtk.ResponseType], but `GtkFileChooserDialog` assumes that its “accept”-type action, e.g. an “Open” or “Save” button, will have one of the following response codes: - %GTK_RESPONSE_ACCEPT - %GTK_RESPONSE_OK - %GTK_RESPONSE_YES - %GTK_RESPONSE_APPLY This is because `GtkFileChooserDialog` must intercept responses and switch to folders if appropriate, rather than letting the dialog terminate — the implementation uses these known response codes to know which responses can be blocked if appropriate. To summarize, make sure you use a predefined response code when you use `GtkFileChooserDialog` to ensure proper operation. ## CSS nodes `GtkFileChooserDialog` has a single CSS node with the name `window` and style class `.filechooser`. Use [class@Gtk.FileDialog] instead Creates a new `GtkFileChooserDialog`. This function is analogous to [ctor@Gtk.Dialog.new_with_buttons]. Use [class@Gtk.FileDialog] instead a new `GtkFileChooserDialog` Title of the dialog Transient parent of the dialog Open or save mode for the dialog text to go in the first button response ID for the first button, then additional (button, id) pairs, ending with %NULL These identify the various errors that can occur while calling `GtkFileChooser` functions. There is no replacement Indicates that a file does not exist. Indicates a malformed filename. Indicates a duplicate path (e.g. when adding a bookmark). Indicates an incomplete hostname (e.g. "http://foo" without a slash after that). Registers an error quark for `GtkFileChooser` errors. The error quark used for `GtkFileChooser` errors. `GtkFileChooserNative` is an abstraction of a dialog suitable for use with “File Open” or “File Save as” commands. By default, this just uses a `GtkFileChooserDialog` to implement the actual dialog. However, on some platforms, such as Windows and macOS, the native platform file chooser is used instead. When the application is running in a sandboxed environment without direct filesystem access (such as Flatpak), `GtkFileChooserNative` may call the proper APIs (portals) to let the user choose a file and make it available to the application. While the API of `GtkFileChooserNative` closely mirrors `GtkFileChooserDialog`, the main difference is that there is no access to any `GtkWindow` or `GtkWidget` for the dialog. This is required, as there may not be one in the case of a platform native dialog. Showing, hiding and running the dialog is handled by the [class@Gtk.NativeDialog] functions. Note that unlike `GtkFileChooserDialog`, `GtkFileChooserNative` objects are not toplevel widgets, and GTK does not keep them alive. It is your responsibility to keep a reference until you are done with the object. ## Typical usage In the simplest of cases, you can the following code to use `GtkFileChooserNative` to select a file for opening: ```c static void on_response (GtkNativeDialog *native, int response) { if (response == GTK_RESPONSE_ACCEPT) { GtkFileChooser *chooser = GTK_FILE_CHOOSER (native); GFile *file = gtk_file_chooser_get_file (chooser); open_file (file); g_object_unref (file); } g_object_unref (native); } // ... GtkFileChooserNative *native; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN; native = gtk_file_chooser_native_new ("Open File", parent_window, action, "_Open", "_Cancel"); g_signal_connect (native, "response", G_CALLBACK (on_response), NULL); gtk_native_dialog_show (GTK_NATIVE_DIALOG (native)); ``` To use a `GtkFileChooserNative` for saving, you can use this: ```c static void on_response (GtkNativeDialog *native, int response) { if (response == GTK_RESPONSE_ACCEPT) { GtkFileChooser *chooser = GTK_FILE_CHOOSER (native); GFile *file = gtk_file_chooser_get_file (chooser); save_to_file (file); g_object_unref (file); } g_object_unref (native); } // ... GtkFileChooserNative *native; GtkFileChooser *chooser; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE; native = gtk_file_chooser_native_new ("Save File", parent_window, action, "_Save", "_Cancel"); chooser = GTK_FILE_CHOOSER (native); if (user_edited_a_new_document) gtk_file_chooser_set_current_name (chooser, _("Untitled document")); else gtk_file_chooser_set_file (chooser, existing_file, NULL); g_signal_connect (native, "response", G_CALLBACK (on_response), NULL); gtk_native_dialog_show (GTK_NATIVE_DIALOG (native)); ``` For more information on how to best set up a file dialog, see the [class@Gtk.FileChooserDialog] documentation. ## Response Codes `GtkFileChooserNative` inherits from [class@Gtk.NativeDialog], which means it will return %GTK_RESPONSE_ACCEPT if the user accepted, and %GTK_RESPONSE_CANCEL if he pressed cancel. It can also return %GTK_RESPONSE_DELETE_EVENT if the window was unexpectedly closed. ## Differences from `GtkFileChooserDialog` There are a few things in the [iface@Gtk.FileChooser] interface that are not possible to use with `GtkFileChooserNative`, as such use would prohibit the use of a native dialog. No operations that change the dialog work while the dialog is visible. Set all the properties that are required before showing the dialog. ## Win32 details On windows the `IFileDialog` implementation (added in Windows Vista) is used. It supports many of the features that `GtkFileChooser` has, but there are some things it does not handle: * Any [class@Gtk.FileFilter] added using a mimetype If any of these features are used the regular `GtkFileChooserDialog` will be used in place of the native one. ## Portal details When the `org.freedesktop.portal.FileChooser` portal is available on the session bus, it is used to bring up an out-of-process file chooser. Depending on the kind of session the application is running in, this may or may not be a GTK file chooser. ## macOS details On macOS the `NSSavePanel` and `NSOpenPanel` classes are used to provide native file chooser dialogs. Some features provided by `GtkFileChooser` are not supported: * Shortcut folders. Use [class@Gtk.FileDialog] instead Creates a new `GtkFileChooserNative`. Use [class@Gtk.FileDialog] instead a new `GtkFileChooserNative` Title of the native Transient parent of the native Open or save mode for the dialog text to go in the accept button, or %NULL for the default text to go in the cancel button, or %NULL for the default Retrieves the custom label text for the accept button. Use [class@Gtk.FileDialog] instead The custom label a `GtkFileChooserNative` Retrieves the custom label text for the cancel button. Use [class@Gtk.FileDialog] instead The custom label a `GtkFileChooserNative` Sets the custom label text for the accept button. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key should activate the button. Use [class@Gtk.FileDialog] instead a `GtkFileChooserNative` custom label Sets the custom label text for the cancel button. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key should activate the button. Use [class@Gtk.FileDialog] instead a `GtkFileChooserNative` custom label The text used for the label on the accept button in the dialog, or %NULL to use the default text. The text used for the label on the cancel button in the dialog, or %NULL to use the default text. `GtkFileChooserWidget` is a widget for choosing files. It exposes the [iface@Gtk.FileChooser] interface, and you should use the methods of this interface to interact with the widget. # Shortcuts and Gestures `GtkFileChooserWidget` supports the following keyboard shortcuts: - <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. The following signals have default keybindings: - [signal@Gtk.FileChooserWidget::desktop-folder] - [signal@Gtk.FileChooserWidget::down-folder] - [signal@Gtk.FileChooserWidget::home-folder] - [signal@Gtk.FileChooserWidget::location-popup] - [signal@Gtk.FileChooserWidget::location-popup-on-paste] - [signal@Gtk.FileChooserWidget::location-toggle-popup] - [signal@Gtk.FileChooserWidget::places-shortcut] - [signal@Gtk.FileChooserWidget::quick-bookmark] - [signal@Gtk.FileChooserWidget::recent-shortcut] - [signal@Gtk.FileChooserWidget::search-shortcut] - [signal@Gtk.FileChooserWidget::show-hidden] - [signal@Gtk.FileChooserWidget::up-folder] # CSS nodes `GtkFileChooserWidget` has a single CSS node with name filechooser. Direct use of `GtkFileChooserWidget` is deprecated Creates a new `GtkFileChooserWidget`. This is a file chooser widget that can be embedded in custom windows, and it is the same widget that is used by `GtkFileChooserDialog`. Direct use of `GtkFileChooserWidget` is deprecated a new `GtkFileChooserWidget` Open or save mode for the widget Whether search mode is enabled. Whether to show the time. The subtitle of the file chooser widget. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser show the user's Desktop folder in the file list. The default binding for this signal is <kbd>Alt</kbd>-<kbd>D</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser go to a child of the current folder in the file hierarchy. The subfolder that will be used is displayed in the path bar widget of the file chooser. For example, if the path bar is showing "/foo/bar/baz", with bar currently displayed, then this will cause the file chooser to switch to the "baz" subfolder. The default binding for this signal is <kbd>Alt</kbd>-<kbd>Down</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser show the user's home folder in the file list. The default binding for this signal is <kbd>Alt</kbd>-<kbd>Home</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser show a "Location" prompt which the user can use to manually type the name of the file he wishes to select. The default bindings for this signal are <kbd>Control</kbd>-<kbd>L</kbd> with a @path string of "" (the empty string). It is also bound to <kbd>/</kbd> with a @path string of "`/`" (a slash): this lets you type `/` and immediately type a path name. On Unix systems, this is bound to <kbd>~</kbd> (tilde) with a @path string of "~" itself for access to home directories. a string that gets put in the text entry for the file name Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser show a "Location" prompt when the user pastes into a `GtkFileChooserWidget`. The default binding for this signal is <kbd>Control</kbd>-<kbd>V</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to toggle the visibility of a "Location" prompt which the user can use to manually type the name of the file he wishes to select. The default binding for this signal is <kbd>Control</kbd>-<kbd>L</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to move the focus to the places sidebar. The default binding for this signal is <kbd>Alt</kbd>-<kbd>P</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser switch to the bookmark specified in the @bookmark_index parameter. For example, if you have three bookmarks, you can pass 0, 1, 2 to this signal to switch to each of them, respectively. The default binding for this signal is <kbd>Alt</kbd>-<kbd>1</kbd>, <kbd>Alt</kbd>-<kbd>2</kbd>, etc. until <kbd>Alt</kbd>-<kbd>0</kbd>. Note that in the default binding, that <kbd>Alt</kbd>-<kbd>1</kbd> is actually defined to switch to the bookmark at index 0, and so on successively. the number of the bookmark to switch to Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser show the Recent location. The default binding for this signal is <kbd>Alt</kbd>-<kbd>R</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser show the search entry. The default binding for this signal is <kbd>Alt</kbd>-<kbd>S</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser display hidden files. The default binding for this signal is <kbd>Control</kbd>-<kbd>H</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser go to the parent of the current folder in the file hierarchy. The default binding for this signal is <kbd>Alt</kbd>-<kbd>Up</kbd>. Asynchronous API to present a file chooser dialog. `GtkFileDialog` collects the arguments that are needed to present the dialog to the user, such as a title for the dialog and whether it should be modal. The dialog is shown with [method@Gtk.FileDialog.open], [method@Gtk.FileDialog.save], etc. Creates a new `GtkFileDialog` object. the new `GtkFileDialog` Retrieves the text used by the dialog on its accept button. the label shown on the file chooser's accept button a file dialog Gets the filter that will be selected by default in the file chooser dialog. the default filter a file dialog Gets the filters that will be offered to the user in the file chooser dialog. the filters, as a list model of [class@Gtk.FileFilter] a file dialog Gets the file that will be initially selected in the file chooser dialog. the file a file dialog Gets the folder that will be set as the initial folder in the file chooser dialog. the folder a file dialog Gets the filename that will be initially selected. the name a file dialog Returns whether the file chooser dialog blocks interaction with the parent window while it is presented. true if the file chooser dialog is modal a file dialog Returns the title that will be shown on the file chooser dialog. the title a file dialog Presents a file chooser dialog to the user. The file chooser dialog will be set up to select a single file. The @callback will be called when the dialog is closed. a file dialog the parent window a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileDialog.open] call. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. the file that was selected a file dialog the result Presents a file chooser dialog to the user. The file chooser dialog will be set up to select multiple files. The file chooser dialog will initially be opened in the directory [property@Gtk.FileDialog:initial-folder]. The @callback will be called when the dialog is closed. a file dialog the parent window a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileDialog.open] call. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. the files that were selected, as a list model of [iface@Gio.File] a file dialog the result Presents a file chooser dialog to the user. The file chooser dialog will be set up to select multiple files. The file chooser dialog will initially be opened in the directory [property@Gtk.FileDialog:initial-folder]. In contrast to [method@Gtk.FileDialog.open], this function lets the user select the text encoding for the files, if possible. The @callback will be called when the dialog is closed. a file dialog the parent window a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileDialog.open] call. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. the files that were selected, as a list model of [iface@Gio.File] a file dialog the result return location for the text encoding to use Initiates a file selection operation by presenting a file chooser dialog to the user. In contrast to [method@Gtk.FileDialog.open], this function lets the user select the text encoding for the file, if possible. The @callback will be called when the dialog is closed. a `GtkFileDialog` the parent `GtkWindow` a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileDialog.open_text_file] call and returns the resulting file and text encoding. If the user has explicitly selected a text encoding to use for the file, then @encoding will be set to a codeset name that is suitable for passing to iconv_open(). Otherwise, it will be `NULL`. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. the file that was selected a `GtkFileDialog` a `GAsyncResult` return location for the text encoding to use Presents a file chooser dialog to the user. The file chooser dialog will be save mode. The @callback will be called when the dialog is closed. a file dialog the parent window a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileDialog.save] call. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. the file that was selected a file dialog the result Initiates a file save operation by presenting a file chooser dialog to the user. In contrast to [method@Gtk.FileDialog.save], this function lets the user select the text encoding and line endings for the text file, if possible. The @callback will be called when the dialog is closed. a `GtkFileDialog` the parent `GtkWindow` a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileDialog.save_text_file] call and returns the resulting file, text encoding and line endings. If the user has explicitly selected a text encoding to use for the file, then @encoding will be set to a codeset name that is suitable for passing to iconv_open(). Otherwise, it will be `NULL`. The @line_ending will be set to one of "\n", "\r\n", "\r" or "", where the latter means to preserve existing line endings. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. the file that was selected. a `GtkFileDialog` a `GAsyncResult` return location for the text encoding to use return location for the line endings to use Presents a file chooser dialog to the user. The file chooser dialog will be set up to select a single folder. If you pass @initial_folder, the file chooser dialog will initially be opened in the parent directory of that folder, otherwise, it will be in the directory [property@Gtk.FileDialog:initial-folder]. The @callback will be called when the dialog is closed. a file dialog the parent window a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileDialog.select_folder] call. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. the folder that was selected a file dialog the result Presents a file chooser dialog to the user. The file chooser dialog will be set up to allow selecting multiple folders. The file chooser dialog will initially be opened in the directory [property@Gtk.FileDialog:initial-folder]. The @callback will be called when the dialog is closed. a file dialog the parent window a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileDialog.select_multiple_folders] call. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. the folders that were selected, as a list model of [iface@Gio.File] a file dialog the result Sets the label shown on the file chooser's accept button. Leaving the accept label unset or setting it as `NULL` will fall back to a default label, depending on what API is used to launch the file dialog. a file dialog the new accept label Sets the filter that will be selected by default in the file chooser dialog. If set to `NULL`, the first item in [property@Gtk.FileDialog:filters] will be used as the default filter. If that list is empty, the dialog will be unfiltered. a file dialog the file filter Sets the filters that will be offered to the user in the file chooser dialog. a file dialog a list model of [class@Gtk.FileFilter] Sets the file that will be initially selected in the file chooser dialog. This function is a shortcut for calling both [method@Gtk.FileDialog.set_initial_folder] and [method@Gtk.FileDialog.set_initial_name] with the directory and name of @file, respectively. a file dialog a file Sets the folder that will be set as the initial folder in the file chooser dialog. a file dialog a file Sets the filename that will be initially selected. For save dialogs, @name will usually be pre-entered into the name field. If a file with this name already exists in the directory set via [property@Gtk.FileDialog:initial-folder], the dialog will preselect it. a file dialog a string Sets whether the file chooser dialog blocks interaction with the parent window while it is presented. a file dialog the new value Sets the title that will be shown on the file chooser dialog. a file dialog the new title Label for the file chooser's accept button. The default filter. This filter is initially active in the file chooser dialog. If the default filter is `NULL`, the first filter of [property@Gtk.FileDialog:filters] is used as the default filter. If that property contains no filter, the dialog will be unfiltered. If [property@Gtk.FileDialog:filters] is not `NULL`, the default filter should be part of the list. If it is not, the dialog may choose to not make it available. The list of filters. See [property@Gtk.FileDialog:default-filter] about how these two properties interact. The initial file. This file is initially selected in the file chooser dialog This is a utility property that sets both [property@Gtk.FileDialog:initial-folder] and [property@Gtk.FileDialog:initial-name]. The initial folder. This is the directory that is initially opened in the file chooser dialog. The initial name. This is the name of the file that is initially selected in the file chooser dialog. Whether the file chooser dialog is modal. A title that may be shown on the file chooser dialog. Filters files by name or mime type. `GtkFileFilter` can be used to restrict the files being shown in a file chooser. Files can be filtered based on their name (with [method@Gtk.FileFilter.add_pattern] or [method@Gtk.FileFilter.add_suffix]) or on their mime type (with [method@Gtk.FileFilter.add_mime_type]). Filtering by mime types handles aliasing and subclassing of mime types; e.g. a filter for text/plain also matches a file with mime type application/rtf, since application/rtf is a subclass of text/plain. Note that `GtkFileFilter` allows wildcards for the subtype of a mime type, so you can e.g. filter for image/\*. Normally, file filters are used by adding them to a file chooser (see [method@Gtk.FileDialog.set_filters]), but it is also possible to manually use a file filter on any [class@Gtk.FilterListModel] containing `GFileInfo` objects. # GtkFileFilter as GtkBuildable The `GtkFileFilter` implementation of the `GtkBuildable` interface supports adding rules using the `<mime-types>` and `<patterns>` and `<suffixes>` elements and listing the rules within. Specifying a `<mime-type>` or `<pattern>` or `<suffix>` has the same effect as as calling [method@Gtk.FileFilter.add_mime_type] or [method@Gtk.FileFilter.add_pattern] or [method@Gtk.FileFilter.add_suffix]. An example of a UI definition fragment specifying `GtkFileFilter` rules: ```xml <object class="GtkFileFilter"> <property name="name" translatable="yes">Text and Images</property> <mime-types> <mime-type>text/plain</mime-type> <mime-type>image/ *</mime-type> </mime-types> <patterns> <pattern>*.txt</pattern> </patterns> <suffixes> <suffix>png</suffix> </suffixes> </object> ``` Creates a new `GtkFileFilter` with no rules added to it. Such a filter doesn’t accept any files, so is not particularly useful until you add rules with [method@Gtk.FileFilter.add_mime_type], [method@Gtk.FileFilter.add_pattern], [method@Gtk.FileFilter.add_suffix] or [method@Gtk.FileFilter.add_pixbuf_formats]. To create a filter that accepts any file, use: ```c GtkFileFilter *filter = gtk_file_filter_new (); gtk_file_filter_add_pattern (filter, "*"); ``` a new `GtkFileFilter` Deserialize a file filter from a `GVariant`. The variant must be in the format produced by [method@Gtk.FileFilter.to_gvariant]. a new `GtkFileFilter` object an `a{sv}` `GVariant` Adds a rule allowing a given mime type. A file filter name of a MIME type Adds a rule allowing a given array of mime types. It can for example be used with [Gly.Loader.get_mime_types](https://gnome.pages.gitlab.gnome.org/glycin/libglycin/type_func.Loader.get_mime_types.html). This is equivalent to calling [method@Gtk.FileFilter.add_mime_type] for all the supported mime types. a file filter a %NULL-terminated array of mime types Adds a rule allowing a shell style glob pattern. Note that it depends on the platform whether pattern matching ignores case or not. On Windows, it does, on other platforms, it doesn't. a file filter a shell style glob pattern Adds a rule allowing image files in the formats supported by `GdkPixbuf`. This is equivalent to calling [method@Gtk.FileFilter.add_mime_type] for all the supported mime types. Use the api of your image loading framework (e.g. glycin) to enumerate supported formats a file filter Adds a suffix match rule to a filter. This is similar to adding a match for the pattern "*.@suffix" An exaple to filter files with the suffix ".sub": ```c gtk_file_filter_add_suffix (filter, "sub"); ``` Filters with multiple dots are allowed. In contrast to pattern matches, suffix matches are *always* case-insensitive. a file filter filename suffix to match Gets the attributes that need to be filled in for the `GFileInfo` passed to this filter. This function will not typically be used by applications; it is intended for use in file chooser implementation. the attributes a file filter Gets the human-readable name for the filter. See [method@Gtk.FileFilter.set_name]. the human-readable name of the filter a file filter Sets a human-readable name of the filter. This is the string that will be displayed in the user interface if there is a selectable list of filters. a file filter the human-readable name for the filter Serialize a file filter to an `a{sv}` variant. a new, floating, `GVariant` a file filter The MIME types that this filter matches. The human-readable name of the filter. This is the string that will be displayed in the user interface if there is a selectable list of filters. The patterns that this filter matches. The suffixes that this filter matches. Asynchronous API to open a file with an application. `GtkFileLauncher` collects the arguments that are needed to open the file. Depending on system configuration, user preferences and available APIs, this may or may not show an app chooser dialog or launch the default application right away. The operation is started with the [method@Gtk.FileLauncher.launch] function. To launch uris that don't represent files, use [class@Gtk.UriLauncher]. Creates a new `GtkFileLauncher` object. the new `GtkFileLauncher` the file to open Returns whether to ask the user which app to use. true if always asking the user a file launcher Gets the file that will be opened. the file a file launcher Returns whether to make the file writable for the handler. true if the file will be made writable a file launcher Launches an application to open the file. This may present an app chooser dialog to the user. a file launcher the parent window a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileLauncher.launch] call and returns the result. true if an application was launched a file launcher the result Launches a file manager to show the file in its parent directory. This is only supported for native files. It will fail if @file is e.g. a http:// uri. a file launcher the parent window a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileLauncher.open_containing_folder] call and returns the result. true if an application was launched a file launcher the result Sets whether to always ask the user which app to use. If false, the file might be opened with a default app or the previous choice. a file launcher whether to always ask Sets the file that will be opened. a file launcher the file Sets whether to make the file writable for the handler. a file launcher whether to make the file writable Whether to ask the user to choose an app for opening the file. If `FALSE`, the file might be opened with a default app or the previous choice. The file to launch. Whether to make the file writable for the handler. Describes the filtering to be performed by a [class@Gtk.FilterListModel]. The model will use the filter to determine if it should include items or not by calling [method@Gtk.Filter.match] for each item and only keeping the ones that the function returns true for. Filters may change what items they match through their lifetime. In that case, they will emit the [signal@Gtk.Filter::changed] signal to notify that previous filter results are no longer valid and that items should be checked again via [method@Gtk.Filter.match]. GTK provides various pre-made filter implementations for common filtering operations. These filters often include properties that can be linked to various widgets to easily allow searches. However, in particular for large lists or complex search methods, it is also possible to subclass `GtkFilter` and provide one's own filter. Gets the known strictness of a filter. If the strictness is not known, [enum@Gtk.FilterMatch.some] is returned. This value may change after emission of the [signal@Gtk.Filter::changed] signal. This function is meant purely for optimization purposes. Filters can choose to omit implementing it, but `GtkFilterListModel` uses it. the strictness of @self a filter Checks if the given @item is matched by the filter or not. true if the filter matches the item a filter The item to check Notifies all users of the filter that it has changed. This emits the [signal@Gtk.Filter::changed] signal. Users of the filter should then check items again via [method@Gtk.Filter.match]. Depending on the @change parameter, not all items need to be changed, but only some. Refer to the [enum@Gtk.FilterChange] documentation for details. This function is intended for implementers of `GtkFilter` subclasses and should not be called from other functions. a filter how the filter changed Gets the known strictness of a filter. If the strictness is not known, [enum@Gtk.FilterMatch.some] is returned. This value may change after emission of the [signal@Gtk.Filter::changed] signal. This function is meant purely for optimization purposes. Filters can choose to omit implementing it, but `GtkFilterListModel` uses it. the strictness of @self a filter Checks if the given @item is matched by the filter or not. true if the filter matches the item a filter The item to check Emitted whenever the filter changed. Users of the filter should then check items again via [method@Gtk.Filter.match]. `GtkFilterListModel` handles this signal automatically. Depending on the @change parameter, not all items need to be checked, but only some. Refer to the [enum@Gtk.FilterChange] documentation for details. how the filter changed Describes changes in a filter in more detail and allows objects using the filter to optimize refiltering items. If you are writing an implementation and are not sure which value to pass, `GTK_FILTER_CHANGE_DIFFERENT` is always a correct choice. New values may be added in the future. The filter change cannot be described with any of the other enumeration values The filter is less strict than it was before: All items that it used to return true still return true, others now may, too. The filter is more strict than it was before: All items that it used to return false still return false, others now may, too. Similar to [enum@Gtk.FilterChange.DIFFERENT], but signs that item watches should be recreated. This is used by [class@Gtk.FilterListModel] to keep the list up-to-date when items change. Similar to [enum@Gtk.FilterChange.LESS_STRICT], but signs that item watches should be recreated. This is used by [class@Gtk.FilterListModel] to keep the list up-to-date when items change. Similar to [enum@Gtk.FilterChange.MORE_STRICT], but signs that item watches should be recreated. This is used by [class@Gtk.FilterListModel] to keep the list up-to-date when items change. true if the filter matches the item a filter The item to check the strictness of @self a filter A list model that filters the elements of another model. It hides some elements from the underlying model according to criteria given by a `GtkFilter`. The model can be set up to do incremental filtering, so that filtering long lists doesn't block the UI. See [method@Gtk.FilterListModel.set_incremental] for details. `GtkFilterListModel` passes through sections from the underlying model. Creates a new `GtkFilterListModel` that will filter @model using the given @filter. a new `GtkFilterListModel` the model to sort filter Gets the `GtkFilter` currently set on @self. The filter currently in use a `GtkFilterListModel` Returns whether incremental filtering is enabled. See [method@Gtk.FilterListModel.set_incremental]. %TRUE if incremental filtering is enabled a `GtkFilterListModel` Gets the model currently filtered or %NULL if none. The model that gets filtered a `GtkFilterListModel` Returns the number of items that have not been filtered yet. You can use this value to check if @self is busy filtering by comparing the return value to 0 or you can compute the percentage of the filter remaining by dividing the return value by the total number of items in the underlying model: ```c pending = gtk_filter_list_model_get_pending (self); model = gtk_filter_list_model_get_model (self); percentage = pending / (double) g_list_model_get_n_items (model); ``` If no filter operation is ongoing - in particular when [property@Gtk.FilterListModel:incremental] is %FALSE - this function returns 0. The number of items not yet filtered a `GtkFilterListModel` Returns whether watching items is enabled. See [method@Gtk.FilterListModel.set_watch_items]. %TRUE if watching items is enabled a `GtkFilterListModel` Sets the filter used to filter items. a `GtkFilterListModel` filter to use Sets the filter model to do an incremental sort. When incremental filtering is enabled, the `GtkFilterListModel` will not run filters immediately, but will instead queue an idle handler that incrementally filters the items and adds them to the list. This of course means that items are not instantly added to the list, but only appear incrementally. When your filter blocks the UI while filtering, you might consider turning this on. Depending on your model and filters, this may become interesting around 10,000 to 100,000 items. By default, incremental filtering is disabled. See [method@Gtk.FilterListModel.get_pending] for progress information about an ongoing incremental filtering operation. a `GtkFilterListModel` %TRUE to enable incremental filtering Sets the model to be filtered. Note that GTK makes no effort to ensure that @model conforms to the item type of @self. It assumes that the caller knows what they are doing and have set up an appropriate filter to ensure that item types match. a `GtkFilterListModel` The model to be filtered Sets the filter model to monitor properties of its items. This allows implementations of [class@Gtk.Filter] that support expression watching to react to property changes. This property has no effect if the current filter doesn't support watching items. By default, watching items is disabled. a `GtkFilterListModel` %TRUE to watch items for property changes The filter for this model. If the model should filter items incrementally. The type of items. See [method@Gio.ListModel.get_item_type]. The model being filtered. The number of items. See [method@Gio.ListModel.get_n_items]. Number of items not yet filtered. Monitor the list items for changes. It may impact performance. Describes the known strictness of a filter. Note that for filters where the strictness is not known, `GTK_FILTER_MATCH_SOME` is always an acceptable value, even if a filter does match all or no items. The filter matches some items, [method@Gtk.Filter.match] may return true or false The filter does not match any item, [method@Gtk.Filter.match] will always return false The filter matches all items, [method@Gtk.Filter.match] will alays return true Places its child widgets at fixed positions and with fixed sizes. `GtkFixed` performs no automatic layout management. For most applications, you should not use this container! It keeps you from having to learn about the other GTK containers, but it results in broken applications. With `GtkFixed`, the following things will result in truncated text, overlapping widgets, and other display bugs: - Themes, which may change widget sizes. - Fonts other than the one you used to write the app will of course change the size of widgets containing text; keep in mind that users may use a larger font because of difficulty reading the default, or they may be using a different OS that provides different fonts. - Translation of text into other languages changes its size. Also, display of non-English text will use a different font in many cases. In addition, `GtkFixed` does not pay attention to text direction and thus may produce unwanted results if your app is run under right-to-left languages such as Hebrew or Arabic. That is: normally GTK will order containers appropriately for the text direction, e.g. to put labels to the right of the thing they label when using an RTL language, but it can’t do that with `GtkFixed`. So if you need to reorder widgets depending on the text direction, you would need to manually detect it and adjust child positions accordingly. Finally, fixed positioning makes it kind of annoying to add/remove UI elements, since you have to reposition all the other elements. This is a long-term maintenance problem for your application. If you know none of these things are an issue for your application, and prefer the simplicity of `GtkFixed`, by all means use the widget. But you should be aware of the tradeoffs. Creates a new `GtkFixed`. a new `GtkFixed`. Retrieves the translation transformation of the given child `GtkWidget` in the `GtkFixed`. See also: [method@Gtk.Fixed.get_child_transform]. a `GtkFixed` a child of @fixed the horizontal position of the @widget the vertical position of the @widget Retrieves the transformation for @widget set using gtk_fixed_set_child_transform(). a `GskTransform` a `GtkFixed` a `GtkWidget`, child of @fixed Sets a translation transformation to the given @x and @y coordinates to the child @widget of the `GtkFixed`. a `GtkFixed` the child widget the horizontal position to move the widget to the vertical position to move the widget to Adds a widget to a `GtkFixed` at the given position. a `GtkFixed` the widget to add the horizontal position to place the widget at the vertical position to place the widget at Removes a child from @fixed. a `GtkFixed` the child widget to remove Sets the transformation for @widget. This is a convenience function that retrieves the [class@Gtk.FixedLayoutChild] instance associated to @widget and calls [method@Gtk.FixedLayoutChild.set_transform]. a `GtkFixed` a `GtkWidget`, child of @fixed the transformation assigned to @widget to reset @widget's transform Places child widgets at fixed positions. Most applications should never use this layout manager; fixed positioning and sizing requires constant recalculations on where children need to be positioned and sized. Other layout managers perform this kind of work internally so that application developers don't need to do it. Specifically, widgets positioned in a fixed layout manager will need to take into account: - Themes, which may change widget sizes. - Fonts other than the one you used to write the app will of course change the size of widgets containing text; keep in mind that users may use a larger font because of difficulty reading the default, or they may be using a different OS that provides different fonts. - Translation of text into other languages changes its size. Also, display of non-English text will use a different font in many cases. In addition, `GtkFixedLayout` does not pay attention to text direction and thus may produce unwanted results if your app is run under right-to-left languages such as Hebrew or Arabic. That is: normally GTK will order containers appropriately depending on the text direction, e.g. to put labels to the right of the thing they label when using an RTL language; `GtkFixedLayout` won't be able to do that for you. Finally, fixed positioning makes it kind of annoying to add/remove UI elements, since you have to reposition all the other elements. This is a long-term maintenance problem for your application. Creates a new `GtkFixedLayout`. the newly created `GtkFixedLayout` `GtkLayoutChild` subclass for children in a `GtkFixedLayout`. Retrieves the transformation of the child. a `GskTransform` a `GtkFixedLayoutChild` Sets the transformation of the child of a `GtkFixedLayout`. a `GtkFixedLayoutChild` a `GskTransform` The transform of the child. A list model that concatenates other list models. `GtkFlattenListModel` takes a list model containing list models, and flattens it into a single model. Each list model becomes a section in the single model. Creates a new `GtkFlattenListModel` that flattens @list. a new `GtkFlattenListModel` the model to be flattened Gets the model set via gtk_flatten_list_model_set_model(). The model flattened by @self a `GtkFlattenListModel` Returns the model containing the item at the given position. the model containing the item at @position a `GtkFlattenListModel` a position Sets a new model to be flattened. a `GtkFlattenListModel` the new model The type of items. See [method@Gio.ListModel.get_item_type]. The model being flattened. The number of items. See [method@Gio.ListModel.get_n_items]. Puts child widgets in a reflowing grid. <picture> <source srcset="flow-box-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkFlowBox" src="flow-box.png"> </picture> For instance, with the horizontal orientation, the widgets will be arranged from left to right, starting a new row under the previous row when necessary. Reducing the width in this case will require more rows, so a larger height will be requested. Likewise, with the vertical orientation, the widgets will be arranged from top to bottom, starting a new column to the right when necessary. Reducing the height will require more columns, so a larger width will be requested. The size request of a `GtkFlowBox` alone may not be what you expect; if you need to be able to shrink it along both axes and dynamically reflow its children, you may have to wrap it in a `GtkScrolledWindow` to enable that. The children of a `GtkFlowBox` can be dynamically sorted and filtered. Although a `GtkFlowBox` must have only `GtkFlowBoxChild` children, you can add any kind of widget to it via [method@Gtk.FlowBox.insert], and a `GtkFlowBoxChild` widget will automatically be inserted between the box and the widget. Also see [class@Gtk.ListBox]. # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.FlowBox::move-cursor] - [signal@Gtk.FlowBox::select-all] - [signal@Gtk.FlowBox::toggle-cursor-child] - [signal@Gtk.FlowBox::unselect-all] # CSS nodes ``` flowbox ├── flowboxchild │ ╰── <child> ├── flowboxchild │ ╰── <child> ┊ ╰── [rubberband] ``` `GtkFlowBox` uses a single CSS node with name flowbox. `GtkFlowBoxChild` uses a single CSS node with name flowboxchild. For rubberband selection, a subnode with name rubberband is used. # Accessibility `GtkFlowBox` uses the [enum@Gtk.AccessibleRole.grid] role, and `GtkFlowBoxChild` uses the [enum@Gtk.AccessibleRole.grid_cell] role. Creates a `GtkFlowBox`. a new `GtkFlowBox` Adds @child to the end of @self. If a sort function is set, the widget will actually be inserted at the calculated position. See also: [method@Gtk.FlowBox.insert]. a `GtkFlowBox the `GtkWidget` to add Binds @model to @box. If @box was already bound to a model, that previous binding is destroyed. The contents of @box are cleared and then filled with widgets that represent items from @model. @box is updated whenever @model changes. If @model is %NULL, @box is left empty. It is undefined to add or remove widgets directly (for example, with [method@Gtk.FlowBox.insert]) while @box is bound to a model. Note that using a model is incompatible with the filtering and sorting functionality in `GtkFlowBox`. When using a model, filtering and sorting should be implemented by the model. a `GtkFlowBox` the `GListModel` to be bound to @box a function that creates widgets for items user data passed to @create_widget_func function for freeing @user_data Returns whether children activate on single clicks. %TRUE if children are activated on single click, %FALSE otherwise a `GtkFlowBox` Gets the nth child in the @box. the child widget, which will always be a `GtkFlowBoxChild` or %NULL in case no child widget with the given index exists. a `GtkFlowBox` the position of the child Gets the child in the (@x, @y) position. Both @x and @y are assumed to be relative to the origin of @box. the child widget, which will always be a `GtkFlowBoxChild` or %NULL in case no child widget exists for the given x and y coordinates. a `GtkFlowBox` the x coordinate of the child the y coordinate of the child Gets the horizontal spacing. the horizontal spacing a `GtkFlowBox` Returns whether the box is homogeneous. %TRUE if the box is homogeneous. a `GtkFlowBox` Gets the maximum number of children per line. the maximum number of children per line a `GtkFlowBox` Gets the minimum number of children per line. the minimum number of children per line a `GtkFlowBox` Gets the vertical spacing. the vertical spacing a `GtkFlowBox` Creates a list of all selected children. A `GList` containing the `GtkWidget` for each selected child. Free with g_list_free() when done. a `GtkFlowBox` Gets the selection mode of @box. the `GtkSelectionMode` a `GtkFlowBox` Inserts the @widget into @box at @position. If a sort function is set, the widget will actually be inserted at the calculated position. If @position is -1, or larger than the total number of children in the @box, then the @widget will be appended to the end. a `GtkFlowBox` the `GtkWidget` to add the position to insert @child in Updates the filtering for all children. Call this function when the result of the filter function on the @box is changed due to an external factor. For instance, this would be used if the filter function just looked for a specific search term, and the entry with the string has changed. a `GtkFlowBox` Updates the sorting for all children. Call this when the result of the sort function on @box is changed due to an external factor. a `GtkFlowBox` Adds @child to the start of @self. If a sort function is set, the widget will actually be inserted at the calculated position. See also: [method@Gtk.FlowBox.insert]. a `GtkFlowBox the `GtkWidget` to add Removes a child from @box. a `GtkFlowBox` the child widget to remove Removes all children from @box. This function does nothing if @box is backed by a model. a `GtkFlowBox` Select all children of @box, if the selection mode allows it. a `GtkFlowBox` Selects a single child of @box, if the selection mode allows it. a `GtkFlowBox` a child of @box Calls a function for each selected child. Note that the selection cannot be modified from within this function. a `GtkFlowBox` the function to call for each selected child user data to pass to the function If @single is %TRUE, children will be activated when you click on them, otherwise you need to double-click. a `GtkFlowBox` %TRUE to emit child-activated on a single click Sets the horizontal space to add between children. a `GtkFlowBox` the spacing to use By setting a filter function on the @box one can decide dynamically which of the children to show. For instance, to implement a search function that only shows the children matching the search terms. The @filter_func will be called for each child after the call, and it will continue to be called each time a child changes (via [method@Gtk.FlowBoxChild.changed]) or when [method@Gtk.FlowBox.invalidate_filter] is called. Note that using a filter function is incompatible with using a model (see [method@Gtk.FlowBox.bind_model]). a `GtkFlowBox` callback that lets you filter which children to show user data passed to @filter_func destroy notifier for @user_data Hooks up an adjustment to focus handling in @box. The adjustment is also used for autoscrolling during rubberband selection. See [method@Gtk.ScrolledWindow.get_hadjustment] for a typical way of obtaining the adjustment, and [method@Gtk.FlowBox.set_vadjustment] for setting the vertical adjustment. The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the box. a `GtkFlowBox` an adjustment which should be adjusted when the focus is moved among the descendents of @container Sets whether or not all children of @box are given equal space in the box. a `GtkFlowBox` %TRUE to create equal allotments, %FALSE for variable allotments Sets the maximum number of children to request and allocate space for in @box’s orientation. Setting the maximum number of children per line limits the overall natural size request to be no more than @n_children children long in the given orientation. a `GtkFlowBox` the maximum number of children per line Sets the minimum number of children to line up in @box’s orientation before flowing. a `GtkFlowBox` the minimum number of children per line Sets the vertical space to add between children. a `GtkFlowBox` the spacing to use Sets how selection works in @box. a `GtkFlowBox` the new selection mode By setting a sort function on the @box, one can dynamically reorder the children of the box, based on the contents of the children. The @sort_func will be called for each child after the call, and will continue to be called each time a child changes (via [method@Gtk.FlowBoxChild.changed]) and when [method@Gtk.FlowBox.invalidate_sort] is called. Note that using a sort function is incompatible with using a model (see [method@Gtk.FlowBox.bind_model]). a `GtkFlowBox` the sort function user data passed to @sort_func destroy notifier for @user_data Hooks up an adjustment to focus handling in @box. The adjustment is also used for autoscrolling during rubberband selection. See [method@Gtk.ScrolledWindow.get_vadjustment] for a typical way of obtaining the adjustment, and [method@Gtk.FlowBox.set_hadjustment] for setting the horizontal adjustment. The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the box. a `GtkFlowBox` an adjustment which should be adjusted when the focus is moved among the descendents of @container Unselect all children of @box, if the selection mode allows it. a `GtkFlowBox` Unselects a single child of @box, if the selection mode allows it. a `GtkFlowBox` a child of @box Whether to accept unpaired release events. Determines whether children can be activated with a single click, or require a double-click. The amount of horizontal space between two children. Determines whether all children should be allocated the same size. The maximum amount of children to request space for consecutively in the given orientation. The minimum number of children to allocate consecutively in the given orientation. Setting the minimum children per line ensures that a reasonably small height will be requested for the overall minimum width of the box. The amount of vertical space between two children. The selection mode used by the flow box. Emitted when the user activates the @box. This is a [keybinding signal](class.SignalAction.html). Emitted when a child has been activated by the user. the child that is activated Emitted when the user initiates a cursor movement. This is a [keybinding signal](class.SignalAction.html). Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifier does not. There are too many key combinations to list them all here. - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move by individual children - <kbd>Home</kbd>, <kbd>End</kbd> move to the ends of the box - <kbd>PgUp</kbd>, <kbd>PgDn</kbd> move vertically by pages %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the granularity of the move, as a `GtkMovementStep` the number of @step units to move whether to extend the selection whether to modify the selection Emitted to select all children of the box, if the selection mode permits it. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal is <kbd>Ctrl</kbd>-<kbd>a</kbd>. Emitted when the set of selected children changes. Use [method@Gtk.FlowBox.selected_foreach] or [method@Gtk.FlowBox.get_selected_children] to obtain the selected children. Emitted to toggle the selection of the child that has the focus. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Ctrl</kbd>-<kbd>Space</kbd>. Emitted to unselect all children of the box, if the selection mode permits it. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal is <kbd>Ctrl</kbd>-<kbd>Shift</kbd>-<kbd>a</kbd>. The kind of widget that can be added to a `GtkFlowBox`. [class@Gtk.FlowBox] will automatically wrap its children in a `GtkFlowBoxChild` when necessary. Creates a new `GtkFlowBoxChild`. This should only be used as a child of a `GtkFlowBox`. a new `GtkFlowBoxChild` Marks @child as changed, causing any state that depends on this to be updated. This affects sorting and filtering. Note that calls to this method must be in sync with the data used for the sorting and filtering functions. For instance, if the list is mirroring some external data set, and *two* children changed in the external data set when you call gtk_flow_box_child_changed() on the first child, the sort function must only read the new data for the first of the two changed children, otherwise the resorting of the children will be wrong. This generally means that if you don’t fully control the data model, you have to duplicate the data that affects the sorting and filtering functions into the widgets themselves. Another alternative is to call [method@Gtk.FlowBox.invalidate_sort] on any model change, but that is more expensive. a `GtkFlowBoxChild` Gets the child widget of @self. the child widget of @self a `GtkFlowBoxChild` Gets the current index of the @child in its `GtkFlowBox` container. the index of the @child, or -1 if the @child is not in a flow box a `GtkFlowBoxChild` Returns whether the @child is currently selected in its `GtkFlowBox` container. %TRUE if @child is selected a `GtkFlowBoxChild` Sets the child widget of @self. a `GtkFlowBoxChild` the child widget The child widget. Emitted when the user activates a child widget in a `GtkFlowBox`. This can happen either by clicking or double-clicking, or via a keybinding. This is a [keybinding signal](class.SignalAction.html), but it can be used by applications for their own purposes. The default bindings are <kbd>Space</kbd> and <kbd>Enter</kbd>. Called for flow boxes that are bound to a `GListModel`. This function is called for each item that gets added to the model. a `GtkWidget` that represents @item the item from the model for which to create a widget for user data from gtk_flow_box_bind_model() A function that will be called whenever a child changes or is added. It lets you control if the child should be visible or not. %TRUE if the row should be visible, %FALSE otherwise a `GtkFlowBoxChild` that may be filtered user data A function used by gtk_flow_box_selected_foreach(). It will be called on every selected child of the @box. a `GtkFlowBox` a `GtkFlowBoxChild` user data A function to compare two children to determine which should come first. < 0 if @child1 should be before @child2, 0 if they are equal, and > 0 otherwise the first child the second child user data The `GtkFontButton` allows to open a font chooser dialog to change the font. <picture> <source srcset="font-button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkFontButton" src="font-button.png"> </picture> It is suitable widget for selecting a font in a preference dialog. # CSS nodes ``` fontbutton ╰── button.font ╰── [content] ``` `GtkFontButton` has a single CSS node with name fontbutton which contains a button node with the .font style class. Use [class@Gtk.FontDialogButton] instead Creates a new font picker widget. Use [class@Gtk.FontDialogButton] instead a new font picker widget. Creates a new font picker widget showing the given font. Use [class@Gtk.FontDialogButton] instead a new font picker widget. Name of font to display in font chooser dialog Gets whether the dialog is modal. Use [class@Gtk.FontDialogButton] instead %TRUE if the dialog is modal a `GtkFontButton` Retrieves the title of the font chooser dialog. Use [class@Gtk.FontDialogButton] instead an internal copy of the title string which must not be freed. a `GtkFontButton` Returns whether the selected font is used in the label. Use [class@Gtk.FontDialogButton] instead whether the selected font is used in the label. a `GtkFontButton` Returns whether the selected size is used in the label. Use [class@Gtk.FontDialogButton] instead whether the selected size is used in the label. a `GtkFontButton` Sets whether the dialog should be modal. Use [class@Gtk.FontDialogButton] instead a `GtkFontButton` %TRUE to make the dialog modal Sets the title for the font chooser dialog. Use [class@Gtk.FontDialogButton] instead a `GtkFontButton` a string containing the font chooser dialog title If @use_font is %TRUE, the font name will be written using the selected font. Use [class@Gtk.FontDialogButton] instead a `GtkFontButton` If %TRUE, font name will be written using font chosen. If @use_size is %TRUE, the font name will be written using the selected size. Use [class@Gtk.FontDialogButton] instead a `GtkFontButton` If %TRUE, font name will be written using the selected size. Whether the font chooser dialog should be modal. The title of the font chooser dialog. Whether the buttons label will be drawn in the selected font. Whether the buttons label will use the selected font size. Emitted to when the font button is activated. The `::activate` signal on `GtkFontButton` is an action signal and emitting it causes the button to present its dialog. Emitted when the user selects a font. When handling this signal, use [method@Gtk.FontChooser.get_font] to find out which font was just selected. Note that this signal is only emitted when the user changes the font. If you need to react to programmatic font changes as well, use the notify::font signal. `GtkFontChooser` is an interface that can be implemented by widgets for choosing fonts. In GTK, the main objects that implement this interface are [class@Gtk.FontChooserWidget], [class@Gtk.FontChooserDialog] and [class@Gtk.FontButton]. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead Gets the `PangoFontFace` representing the selected font group details (i.e. family, slant, weight, width, etc). If the selected font is not installed, returns %NULL. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A `PangoFontFace` representing the selected font group details a `GtkFontChooser` Gets the `PangoFontFamily` representing the selected font family. Font families are a collection of font faces. If the selected font is not installed, returns %NULL. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A `PangoFontFamily` representing the selected font family a `GtkFontChooser` Gets the custom font map of this font chooser widget, or %NULL if it does not have one. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `PangoFontMap` a `GtkFontChooser` The selected font size. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A n integer representing the selected font size, or -1 if no font size is selected. a `GtkFontChooser` Adds a filter function that decides which fonts to display in the font chooser. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a `GtkFontFilterFunc` data to pass to @filter function to call to free @data when it is no longer needed Sets a custom font map to use for this font chooser widget. A custom font map can be used to present application-specific fonts instead of or in addition to the normal system fonts. ```c FcConfig *config; PangoFontMap *fontmap; config = FcInitLoadConfigAndFonts (); FcConfigAppFontAddFile (config, my_app_font_file); fontmap = pango_cairo_font_map_new_for_font_type (CAIRO_FONT_TYPE_FT); pango_fc_font_map_set_config (PANGO_FC_FONT_MAP (fontmap), config); gtk_font_chooser_set_font_map (font_chooser, fontmap); ``` Note that other GTK widgets will only be able to use the application-specific font if it is present in the font map they use: ```c context = gtk_widget_get_pango_context (label); pango_context_set_font_map (context, fontmap); ``` Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a `PangoFontMap` Gets the currently-selected font name. Note that this can be a different string than what you set with [method@Gtk.FontChooser.set_font], as the font chooser widget may normalize font names and thus return a string with a different structure. For example, “Helvetica Italic Bold 12” could be normalized to “Helvetica Bold Italic 12”. Use [method@Pango.FontDescription.equal] if you want to compare two font descriptions. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A string with the name of the current font a `GtkFontChooser` Gets the currently-selected font. Note that this can be a different string than what you set with [method@Gtk.FontChooser.set_font], as the font chooser widget may normalize font names and thus return a string with a different structure. For example, “Helvetica Italic Bold 12” could be normalized to “Helvetica Bold Italic 12”. Use [method@Pango.FontDescription.equal] if you want to compare two font descriptions. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A `PangoFontDescription` for the current font a `GtkFontChooser` Gets the `PangoFontFace` representing the selected font group details (i.e. family, slant, weight, width, etc). If the selected font is not installed, returns %NULL. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A `PangoFontFace` representing the selected font group details a `GtkFontChooser` Gets the `PangoFontFamily` representing the selected font family. Font families are a collection of font faces. If the selected font is not installed, returns %NULL. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A `PangoFontFamily` representing the selected font family a `GtkFontChooser` Gets the currently-selected font features. The format of the returned string is compatible with the [CSS font-feature-settings property](https://www.w3.org/TR/css-fonts-4/#font-rend-desc). It can be passed to [func@Pango.AttrFontFeatures.new]. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead the currently selected font features a `GtkFontChooser` Gets the custom font map of this font chooser widget, or %NULL if it does not have one. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `PangoFontMap` a `GtkFontChooser` The selected font size. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A n integer representing the selected font size, or -1 if no font size is selected. a `GtkFontChooser` Gets the language that is used for font features. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead the currently selected language a `GtkFontChooser` Returns the current level of granularity for selecting fonts. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead the current granularity level a `GtkFontChooser` Gets the text displayed in the preview area. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead the text displayed in the preview area a `GtkFontChooser` Returns whether the preview entry is shown or not. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead %TRUE if the preview entry is shown or %FALSE if it is hidden. a `GtkFontChooser` Adds a filter function that decides which fonts to display in the font chooser. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a `GtkFontFilterFunc` data to pass to @filter function to call to free @data when it is no longer needed Sets the currently-selected font. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a font name like “Helvetica 12” or “Times Bold 18” Sets the currently-selected font from @font_desc. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a `PangoFontDescription` Sets a custom font map to use for this font chooser widget. A custom font map can be used to present application-specific fonts instead of or in addition to the normal system fonts. ```c FcConfig *config; PangoFontMap *fontmap; config = FcInitLoadConfigAndFonts (); FcConfigAppFontAddFile (config, my_app_font_file); fontmap = pango_cairo_font_map_new_for_font_type (CAIRO_FONT_TYPE_FT); pango_fc_font_map_set_config (PANGO_FC_FONT_MAP (fontmap), config); gtk_font_chooser_set_font_map (font_chooser, fontmap); ``` Note that other GTK widgets will only be able to use the application-specific font if it is present in the font map they use: ```c context = gtk_widget_get_pango_context (label); pango_context_set_font_map (context, fontmap); ``` Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a `PangoFontMap` Sets the language to use for font features. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a language Sets the desired level of granularity for selecting fonts. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` the desired level of granularity Sets the text displayed in the preview area. The @text is used to show how the selected font looks. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` the text to display in the preview area Shows or hides the editable preview entry. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` whether to show the editable preview entry or not The font description as a string, e.g. "Sans Italic 12". Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead The font description as a `PangoFontDescription`. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead The selected font features. The format of the string is compatible with CSS and with Pango attributes. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead The language for which the font features were selected. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead The level of granularity to offer for selecting fonts. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead The string with which to preview the font. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead Whether to show an entry to change the preview text. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead Emitted when a font is activated. This usually happens when the user double clicks an item, or an item is selected and the user presses one of the keys Space, Shift+Space, Return or Enter. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead the font name The `GtkFontChooserDialog` widget is a dialog for selecting a font. <picture> <source srcset="fontchooser-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkFontChooserDialog" src="fontchooser.png"> </picture> `GtkFontChooserDialog` implements the [iface@Gtk.FontChooser] interface and does not provide much API of its own. To create a `GtkFontChooserDialog`, use [ctor@Gtk.FontChooserDialog.new]. # GtkFontChooserDialog as GtkBuildable The `GtkFontChooserDialog` implementation of the `GtkBuildable` interface exposes the buttons with the names “select_button” and “cancel_button”. ## CSS nodes `GtkFontChooserDialog` has a single CSS node with the name `window` and style class `.fontchooser`. Use [class@Gtk.FontDialog] instead Creates a new `GtkFontChooserDialog`. Use [class@Gtk.FontDialog] instead a new `GtkFontChooserDialog` Title of the dialog Transient parent of the dialog A `PangoFontFamily` representing the selected font family a `GtkFontChooser` A `PangoFontFace` representing the selected font group details a `GtkFontChooser` A n integer representing the selected font size, or -1 if no font size is selected. a `GtkFontChooser` a `GtkFontChooser` a `GtkFontFilterFunc` data to pass to @filter function to call to free @data when it is no longer needed a `GtkFontChooser` a `PangoFontMap` a `PangoFontMap` a `GtkFontChooser` Specifies the granularity of font selection that is desired in a `GtkFontChooser`. This enumeration may be extended in the future; applications should ignore unknown values. There is no replacement. Allow selecting a font family Allow selecting a specific font face Allow selecting a specific font size Allow changing OpenType font variation axes Allow selecting specific OpenType font features The `GtkFontChooserWidget` widget lets the user select a font. It is used in the `GtkFontChooserDialog` widget to provide a dialog for selecting fonts. To set the font which is initially selected, use [method@Gtk.FontChooser.set_font] or [method@Gtk.FontChooser.set_font_desc]. To get the selected font use [method@Gtk.FontChooser.get_font] or [method@Gtk.FontChooser.get_font_desc]. To change the text which is shown in the preview area, use [method@Gtk.FontChooser.set_preview_text]. # CSS nodes `GtkFontChooserWidget` has a single CSS node with name fontchooser. Direct use of `GtkFontChooserWidget` is deprecated. Creates a new `GtkFontChooserWidget`. Direct use of `GtkFontChooserWidget` is deprecated. a new `GtkFontChooserWidget` A toggle action that can be used to switch to the tweak page of the font chooser widget, which lets the user tweak the OpenType features and variation axes of the selected font. The action will be enabled or disabled depending on whether the selected font has any features or axes. Asynchronous API to present a font chooser dialog. `GtkFontDialog` collects the arguments that are needed to present the dialog to the user, such as a title for the dialog and whether it should be modal. The dialog is shown with the [method@Gtk.FontDialog.choose_font] function or its variants. See [class@Gtk.FontDialogButton] for a convenient control that uses `GtkFontDialog` and presents the results. Creates a new `GtkFontDialog` object. the new `GtkFontDialog` Presents a font chooser dialog to the user. The font chooser dialog will be set up for selecting a font face. A font face represents a font family and style, but no specific font size. a font dialog the parent window the initial value a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FontDialog.choose_face] call. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. the selected [class@Pango.FontFace] a font dialog the result Presents a font chooser dialog to the user. The font chooser dialog will be set up for selecting a font family. a font dialog the parent window the initial value a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FontDialog.choose_family] call. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. the selected [class@Pango.FontFamily] a font dialog the result Presents a font chooser dialog to the user. The font chooser dialog will be set up for selecting a font. If you want to let the user select font features as well, use [method@Gtk.FontDialog.choose_font_and_features] instead. a font dialog the parent window the font to select initially a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Presents a font chooser dialog to the user. The font chooser dialog will be set up for selecting a font and specify features for the selected font. Font features affect how the font is rendered, for example enabling glyph variants or ligatures. a font dialog the parent window the font to select initially a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FontDialog.choose_font_and_features] call. The selected font and features are returned in @font_desc and @font_features. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. true if a font was selected a font dialog the result return location for font description return location for font features return location for the language Finishes the [method@Gtk.FontDialog.choose_font] call. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. a [struct@Pango.FontDescription] describing the selected font a font dialog the result Returns the filter that decides which fonts to display in the font chooser dialog. the filter a font dialog Returns the fontmap from which fonts are selected, or `NULL` for the default fontmap. the fontmap a font dialog Returns the language for which font features are applied. the language for font features a font dialog Returns whether the font chooser dialog blocks interaction with the parent window while it is presented. true if the font chooser dialog is modal a font dialog Returns the title that will be shown on the font chooser dialog. the title a font dialog Adds a filter that decides which fonts to display in the font chooser dialog. The filter must be able to handle both `PangoFontFamily` and `PangoFontFace` objects. a font dialog the filter Sets the fontmap from which fonts are selected. If @fontmap is `NULL`, the default fontmap is used. a font dialog the fontmap Sets the language for which font features are applied. a font dialog the language for font features Sets whether the font chooser dialog blocks interaction with the parent window while it is presented. a font dialog the new value Sets the title that will be shown on the font chooser dialog. a font dialog the new title A filter to restrict what fonts are shown in the font chooser dialog. A custom font map to select fonts from. A custom font map can be used to present application-specific fonts instead of or in addition to the normal system fonts. The language for which the font features are selected. Whether the font chooser dialog is modal. A title that may be shown on the font chooser dialog that is presented by [method@Gtk.FontDialog.choose_font]. Opens a font chooser dialog to select a font. <picture> <source srcset="font-button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkFontDialogButton" src="font-button.png"> </picture> It is suitable widget for selecting a font in a preference dialog. # CSS nodes ``` fontbutton ╰── button.font ╰── [content] ``` `GtkFontDialogButton` has a single CSS node with name fontbutton which contains a button node with the .font style class. Creates a new `GtkFontDialogButton` with the given `GtkFontDialog`. You can pass `NULL` to this function and set a `GtkFontDialog` later. The button will be insensitive until that happens. the new `GtkFontDialogButton` the `GtkFontDialog` to use Returns the `GtkFontDialog` of @self. the `GtkFontDialog` a `GtkFontDialogButton` Returns the font of the button. This function is what should be used to obtain the font that was chosen by the user. To get informed about changes, listen to "notify::font-desc". the font a `GtkFontDialogButton` Returns the font features of the button. This function is what should be used to obtain the font features that were chosen by the user. To get informed about changes, listen to "notify::font-features". Note that the button will only let users choose font features if [property@Gtk.FontDialogButton:level] is set to `GTK_FONT_LEVEL_FEATURES`. the font features a `GtkFontDialogButton` Returns the language that is used for font features. the language a `GtkFontDialogButton` Returns the level of detail at which this dialog lets the user select fonts. the level of detail a `GtkFontDialogButton Returns whether the selected font is used in the label. whether the selected font is used in the label a `GtkFontDialogButton` Returns whether the selected font size is used in the label. whether the selected font size is used in the label a `GtkFontDialogButton` Sets a `GtkFontDialog` object to use for creating the font chooser dialog that is presented when the user clicks the button. a `GtkFontDialogButton` the new `GtkFontDialog` Sets the font of the button. a `GtkFontDialogButton` the new font Sets the font features of the button. a `GtkFontDialogButton` the font features Sets the language to use for font features. a `GtkFontDialogButton` the new language Sets the level of detail at which this dialog lets the user select fonts. a `GtkFontDialogButton` the level of detail If @use_font is `TRUE`, the font name will be written using the selected font. a `GtkFontDialogButton` If `TRUE`, font name will be written using the chosen font If @use_size is `TRUE`, the font name will be written using the selected font size. a `GtkFontDialogButton` If `TRUE`, font name will be written using the chosen font size The `GtkFontDialog` that contains parameters for the font chooser dialog. The selected font. This property can be set to give the button its initial font, and it will be updated to reflect the users choice in the font chooser dialog. Listen to `notify::font-desc` to get informed about changes to the buttons font. The selected font features. This property will be updated to reflect the users choice in the font chooser dialog. Listen to `notify::font-features` to get informed about changes to the buttons font features. The selected language for font features. This property will be updated to reflect the users choice in the font chooser dialog. Listen to `notify::language` to get informed about changes to the buttons language. The level of detail for the font chooser dialog. Whether the buttons label will be drawn in the selected font. Whether the buttons label will use the selected font size. Emitted when the font dialog button is activated. The `::activate` signal on `GtkFontDialogButton` is an action signal and emitting it causes the button to pop up its dialog. The type of function that is used for deciding what fonts get shown in a `GtkFontChooser`. See [method@Gtk.FontChooser.set_filter_func]. There is no replacement %TRUE if the font should be displayed a `PangoFontFamily` a `PangoFontFace` belonging to @family user data passed to gtk_font_chooser_set_filter_func() The level of granularity for the font selection. Depending on this value, the `PangoFontDescription` that is returned by [method@Gtk.FontDialogButton.get_font_desc] will have more or less fields set. Select a font family Select a font face (i.e. a family and a style) Select a font (i.e. a face with a size, and possibly font variations) Select a font and font features Values for the [property@Gtk.Settings:gtk-font-rendering] setting that influence how GTK renders fonts. Set up font rendering automatically, taking factors like screen resolution and scale into account Follow low-level font-related settings when configuring font rendering Surrounds its child with a decorative frame and an optional label. <picture> <source srcset="frame-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkFrame" src="frame.png"> </picture> If present, the label is drawn inside the top edge of the frame. The horizontal position of the label can be controlled with [method@Gtk.Frame.set_label_align]. `GtkFrame` clips its child. You can use this to add rounded corners to widgets, but be aware that it also cuts off shadows. # GtkFrame as GtkBuildable An example of a UI definition fragment with GtkFrame: ```xml <object class="GtkFrame"> <property name="label-widget"> <object class="GtkLabel" id="frame_label"/> </property> <property name="child"> <object class="GtkEntry" id="frame_content"/> </property> </object> ``` # CSS nodes ``` frame ├── <label widget> ╰── <child> ``` `GtkFrame` has a main CSS node with name “frame”, which is used to draw the visible border. You can set the appearance of the border using CSS properties like “border-style” on this node. # Accessibility `GtkFrame` uses the [enum@Gtk.AccessibleRole.group] role. Creates a new `GtkFrame`, with optional label @label. If @label is %NULL, the label is omitted. a new `GtkFrame` widget the text to use as the label of the frame Gets the child widget of @frame. the child widget of @frame a `GtkFrame` Returns the frame labels text. If the frame's label widget is not a `GtkLabel`, %NULL is returned. the text in the label, or %NULL if there was no label widget or the label widget was not a `GtkLabel`. This string is owned by GTK and must not be modified or freed. a `GtkFrame` Retrieves the X alignment of the frame’s label. the frames X alignment a `GtkFrame` Retrieves the label widget for the frame. the label widget a `GtkFrame` Sets the child widget of @frame. a `GtkFrame` the child widget Creates a new `GtkLabel` with the @label and sets it as the frame's label widget. a `GtkFrame` the text to use as the label of the frame Sets the X alignment of the frame widget’s label. The default value for a newly created frame is 0.0. a `GtkFrame` The position of the label along the top edge of the widget. A value of 0.0 represents left alignment; 1.0 represents right alignment. Sets the label widget for the frame. This is the widget that will appear embedded in the top edge of the frame as a title. a `GtkFrame` the new label widget The child widget. Text of the frame's label. Widget to display in place of the usual frame label. The horizontal alignment of the label. The parent class. Allows drawing with OpenGL. <picture> <source srcset="glarea-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkGLArea" src="glarea.png"> </picture> `GtkGLArea` sets up its own [class@Gdk.GLContext], and creates a custom GL framebuffer that the widget will do GL rendering onto. It also ensures that this framebuffer is the default GL rendering target when rendering. The completed rendering is integrated into the larger GTK scene graph as a texture. In order to draw, you have to connect to the [signal@Gtk.GLArea::render] signal, or subclass `GtkGLArea` and override the GtkGLAreaClass.render virtual function. The `GtkGLArea` widget ensures that the `GdkGLContext` is associated with the widget's drawing area, and it is kept updated when the size and position of the drawing area changes. ## Drawing with GtkGLArea The simplest way to draw using OpenGL commands in a `GtkGLArea` is to create a widget instance and connect to the [signal@Gtk.GLArea::render] signal: The `render()` function will be called when the `GtkGLArea` is ready for you to draw its content: The initial contents of the framebuffer are transparent. ```c static gboolean render (GtkGLArea *area, GdkGLContext *context) { // inside this function it's safe to use GL; the given // GdkGLContext has been made current to the drawable // surface used by the `GtkGLArea` and the viewport has // already been set to be the size of the allocation // we can start by clearing the buffer glClearColor (0, 0, 0, 0); glClear (GL_COLOR_BUFFER_BIT); // record the active framebuffer ID, so we can return to it // with `glBindFramebuffer (GL_FRAMEBUFFER, screen_fb)` should // we, for instance, intend on utilizing the results of an // intermediate render texture pass GLuint screen_fb = 0; glGetIntegerv (GL_FRAMEBUFFER_BINDING, &screen_fb); // draw your object // draw_an_object (); // we completed our drawing; the draw commands will be // flushed at the end of the signal emission chain, and // the buffers will be drawn on the window return TRUE; } void setup_glarea (void) { // create a GtkGLArea instance GtkWidget *gl_area = gtk_gl_area_new (); // connect to the "render" signal g_signal_connect (gl_area, "render", G_CALLBACK (render), NULL); } ``` If you need to initialize OpenGL state, e.g. buffer objects or shaders, you should use the [signal@Gtk.Widget::realize] signal; you can use the [signal@Gtk.Widget::unrealize] signal to clean up. Since the `GdkGLContext` creation and initialization may fail, you will need to check for errors, using [method@Gtk.GLArea.get_error]. An example of how to safely initialize the GL state is: ```c static void on_realize (GtkGLArea *area) { // We need to make the context current if we want to // call GL API gtk_gl_area_make_current (area); // If there were errors during the initialization or // when trying to make the context current, this // function will return a GError for you to catch if (gtk_gl_area_get_error (area) != NULL) return; // You can also use gtk_gl_area_set_error() in order // to show eventual initialization errors on the // GtkGLArea widget itself GError *internal_error = NULL; init_buffer_objects (&error); if (error != NULL) { gtk_gl_area_set_error (area, error); g_error_free (error); return; } init_shaders (&error); if (error != NULL) { gtk_gl_area_set_error (area, error); g_error_free (error); return; } } ``` If you need to change the options for creating the `GdkGLContext` you should use the [signal@Gtk.GLArea::create-context] signal. Creates a new `GtkGLArea` widget. a new `GtkGLArea` class closure for the `GtkGLArea::create-context` signal class closure for the `GtkGLArea::render` signal class closeure for the `GtkGLArea::resize` signal Binds buffers to the framebuffer. Ensures that the @area framebuffer object is made the current draw and read target, and that all the required buffers for the @area are created and bound to the framebuffer. This function is automatically called before emitting the [signal@Gtk.GLArea::render] signal, and doesn't normally need to be called by application code. a `GtkGLArea` Gets the allowed APIs. See [method@Gtk.GLArea.set_allowed_apis]. the allowed APIs a `GtkGLArea` Gets the API that is currently in use. If the GL area has not been realized yet, 0 is returned. the currently used API a `GtkGLArea` Returns whether the area is in auto render mode or not. %TRUE if the @area is auto rendering, %FALSE otherwise a `GtkGLArea` Retrieves the `GdkGLContext` used by @area. the `GdkGLContext` a `GtkGLArea` Gets the current error set on the @area. the `GError` a `GtkGLArea` Returns whether the area has a depth buffer. %TRUE if the @area has a depth buffer, %FALSE otherwise a `GtkGLArea` Returns whether the area has a stencil buffer. %TRUE if the @area has a stencil buffer, %FALSE otherwise a `GtkGLArea` Retrieves the required version of OpenGL. See [method@Gtk.GLArea.set_required_version]. a `GtkGLArea` return location for the required major version return location for the required minor version Returns whether the `GtkGLArea` should use OpenGL ES. See [method@Gtk.GLArea.set_use_es]. Use [method@Gtk.GLArea.get_api] %TRUE if the `GtkGLArea` should create an OpenGL ES context and %FALSE otherwise a `GtkGLArea` Ensures that the `GdkGLContext` used by @area is associated with the `GtkGLArea`. This function is automatically called before emitting the [signal@Gtk.GLArea::render] signal, and doesn't normally need to be called by application code. a `GtkGLArea` Marks the currently rendered data (if any) as invalid, and queues a redraw of the widget. This ensures that the [signal@Gtk.GLArea::render] signal is emitted during the draw. This is only needed when [method@Gtk.GLArea.set_auto_render] has been called with a %FALSE value. The default behaviour is to emit [signal@Gtk.GLArea::render] on each draw. a `GtkGLArea` Sets the allowed APIs to create a context with. You should check [property@Gtk.GLArea:api] before drawing with either API. By default, all APIs are allowed. a `GtkGLArea` the allowed APIs Sets whether the `GtkGLArea` is in auto render mode. If @auto_render is %TRUE the [signal@Gtk.GLArea::render] signal will be emitted every time the widget draws. This is the default and is useful if drawing the widget is faster. If @auto_render is %FALSE the data from previous rendering is kept around and will be used for drawing the widget the next time, unless the window is resized. In order to force a rendering [method@Gtk.GLArea.queue_render] must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw. a `GtkGLArea` a boolean Sets an error on the area which will be shown instead of the GL rendering. This is useful in the [signal@Gtk.GLArea::create-context] signal if GL context creation fails. a `GtkGLArea` a new `GError`, or %NULL to unset the error Sets whether the `GtkGLArea` should use a depth buffer. If @has_depth_buffer is %TRUE the widget will allocate and enable a depth buffer for the target framebuffer. Otherwise there will be none. a `GtkGLArea` %TRUE to add a depth buffer Sets whether the `GtkGLArea` should use a stencil buffer. If @has_stencil_buffer is %TRUE the widget will allocate and enable a stencil buffer for the target framebuffer. Otherwise there will be none. a `GtkGLArea` %TRUE to add a stencil buffer Sets the required version of OpenGL to be used when creating the context for the widget. This function must be called before the area has been realized. a `GtkGLArea` the major version the minor version Sets whether the @area should create an OpenGL or an OpenGL ES context. You should check the capabilities of the `GdkGLContext` before drawing with either API. Use [method@Gtk.GLArea.set_allowed_apis] a `GtkGLArea` whether to use OpenGL or OpenGL ES The allowed APIs. The API currently in use. If set to %TRUE the ::render signal will be emitted every time the widget draws. This is the default and is useful if drawing the widget is faster. If set to %FALSE the data from previous rendering is kept around and will be used for drawing the widget the next time, unless the window is resized. In order to force a rendering [method@Gtk.GLArea.queue_render] must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw. The `GdkGLContext` used by the `GtkGLArea` widget. The `GtkGLArea` widget is responsible for creating the `GdkGLContext` instance. If you need to render with other kinds of buffers (stencil, depth, etc), use render buffers. If set to %TRUE the widget will allocate and enable a depth buffer for the target framebuffer. Setting this property will enable GL's depth testing as a side effect. If you don't need depth testing, you should call `glDisable(GL_DEPTH_TEST)` in your `GtkGLArea::render` handler. If set to %TRUE the widget will allocate and enable a stencil buffer for the target framebuffer. If set to %TRUE the widget will try to create a `GdkGLContext` using OpenGL ES instead of OpenGL. Use [property@Gtk.GLArea:allowed-apis] Emitted when the widget is being realized. This allows you to override how the GL context is created. This is useful when you want to reuse an existing GL context, or if you want to try creating different kinds of GL options. If context creation fails then the signal handler can use [method@Gtk.GLArea.set_error] to register a more detailed error of how the construction failed. a newly created `GdkGLContext`; the `GtkGLArea` widget will take ownership of the returned value. Emitted every time the contents of the `GtkGLArea` should be redrawn. The @context is bound to the @area prior to emitting this function, and the buffers are painted to the window once the emission terminates. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the `GdkGLContext` used by @area Emitted once when the widget is realized, and then each time the widget is changed while realized. This is useful in order to keep GL state up to date with the widget size, like for instance camera properties which may depend on the width/height ratio. The GL context for the area is guaranteed to be current when this signal is emitted. The default handler sets up the GL viewport. the width of the viewport the height of the viewport The `GtkGLAreaClass` structure contains only private data. class closure for the `GtkGLArea::render` signal class closeure for the `GtkGLArea::resize` signal class closure for the `GtkGLArea::create-context` signal The base class for gesture recognition. Although `GtkGesture` is quite generalized to serve as a base for multi-touch gestures, it is suitable to implement single-touch and pointer-based gestures (using the special %NULL `GdkEventSequence` value for these). The number of touches that a `GtkGesture` need to be recognized is controlled by the [property@Gtk.Gesture:n-points] property, if a gesture is keeping track of less or more than that number of sequences, it won't check whether the gesture is recognized. As soon as the gesture has the expected number of touches, it will check regularly if it is recognized, the criteria to consider a gesture as "recognized" is left to `GtkGesture` subclasses. A recognized gesture will then emit the following signals: - [signal@Gtk.Gesture::begin] when the gesture is recognized. - [signal@Gtk.Gesture::update], whenever an input event is processed. - [signal@Gtk.Gesture::end] when the gesture is no longer recognized. ## Event propagation In order to receive events, a gesture needs to set a propagation phase through [method@Gtk.EventController.set_propagation_phase]. In the capture phase, events are propagated from the toplevel down to the target widget, and gestures that are attached to containers above the widget get a chance to interact with the event before it reaches the target. In the bubble phase, events are propagated up from the target widget to the toplevel, and gestures that are attached to containers above the widget get a chance to interact with events that have not been handled yet. ## States of a sequence Whenever input interaction happens, a single event may trigger a cascade of `GtkGesture`s, both across the parents of the widget receiving the event and in parallel within an individual widget. It is a responsibility of the widgets using those gestures to set the state of touch sequences accordingly in order to enable cooperation of gestures around the `GdkEventSequence`s triggering those. Within a widget, gestures can be grouped through [method@Gtk.Gesture.group]. Grouped gestures synchronize the state of sequences, so calling [method@Gtk.Gesture.set_state] on one will effectively propagate the state throughout the group. By default, all sequences start out in the %GTK_EVENT_SEQUENCE_NONE state, sequences in this state trigger the gesture event handler, but event propagation will continue unstopped by gestures. If a sequence enters into the %GTK_EVENT_SEQUENCE_DENIED state, the gesture group will effectively ignore the sequence, letting events go unstopped through the gesture, but the "slot" will still remain occupied while the touch is active. If a sequence enters in the %GTK_EVENT_SEQUENCE_CLAIMED state, the gesture group will grab all interaction on the sequence, by: - Setting the same sequence to %GTK_EVENT_SEQUENCE_DENIED on every other gesture group within the widget, and every gesture on parent widgets in the propagation chain. - Emitting [signal@Gtk.Gesture::cancel] on every gesture in widgets underneath in the propagation chain. - Stopping event propagation after the gesture group handles the event. Note: if a sequence is set early to %GTK_EVENT_SEQUENCE_CLAIMED on %GDK_TOUCH_BEGIN/%GDK_BUTTON_PRESS (so those events are captured before reaching the event widget, this implies %GTK_PHASE_CAPTURE), one similar event will be emulated if the sequence changes to %GTK_EVENT_SEQUENCE_DENIED. This way event coherence is preserved before event propagation is unstopped again. Sequence states can't be changed freely. See [method@Gtk.Gesture.set_state] to know about the possible lifetimes of a `GdkEventSequence`. ## Touchpad gestures On the platforms that support it, `GtkGesture` will handle transparently touchpad gesture events. The only precautions users of `GtkGesture` should do to enable this support are: - If the gesture has %GTK_PHASE_NONE, ensuring events of type %GDK_TOUCHPAD_SWIPE and %GDK_TOUCHPAD_PINCH are handled by the `GtkGesture` If there are touch sequences being currently handled by @gesture, returns %TRUE and fills in @rect with the bounding box containing all active touches. Otherwise, %FALSE will be returned. Note: This function will yield unexpected results on touchpad gestures. Since there is no correlation between physical and pixel distances, these will look as if constrained in an infinitely small area, @rect width and height will thus be 0 regardless of the number of touchpoints. %TRUE if there are active touches, %FALSE otherwise a `GtkGesture` bounding box containing all active touches. If there are touch sequences being currently handled by @gesture, returns %TRUE and fills in @x and @y with the center of the bounding box containing all active touches. Otherwise, %FALSE will be returned. %FALSE if no active touches are present, %TRUE otherwise a `GtkGesture` X coordinate for the bounding box center Y coordinate for the bounding box center Returns the logical `GdkDevice` that is currently operating on @gesture. This returns %NULL if the gesture is not being interacted. a `GdkDevice` a `GtkGesture` Returns all gestures in the group of @gesture The list of `GtkGesture`s, free with g_list_free() a `GtkGesture` Returns the last event that was processed for @sequence. Note that the returned pointer is only valid as long as the @sequence is still interpreted by the @gesture. If in doubt, you should make a copy of the event. The last event from @sequence a `GtkGesture` a `GdkEventSequence` Returns the `GdkEventSequence` that was last updated on @gesture. The last updated sequence a `GtkGesture` If @sequence is currently being interpreted by @gesture, returns %TRUE and fills in @x and @y with the last coordinates stored for that event sequence. The coordinates are always relative to the widget allocation. %TRUE if @sequence is currently interpreted a `GtkGesture` a `GdkEventSequence`, or %NULL for pointer events return location for X axis of the sequence coordinates return location for Y axis of the sequence coordinates Returns the @sequence state, as seen by @gesture. The sequence state in @gesture a `GtkGesture` a `GdkEventSequence` Returns the list of `GdkEventSequences` currently being interpreted by @gesture. A list of `GdkEventSequence`, the list elements are owned by GTK and must not be freed or modified, the list itself must be deleted through g_list_free() a `GtkGesture` Adds @gesture to the same group than @group_gesture. Gestures are by default isolated in their own groups. Both gestures must have been added to the same widget before they can be grouped. When gestures are grouped, the state of `GdkEventSequences` is kept in sync for all of those, so calling [method@Gtk.Gesture.set_sequence_state], on one will transfer the same value to the others. Groups also perform an "implicit grabbing" of sequences, if a `GdkEventSequence` state is set to %GTK_EVENT_SEQUENCE_CLAIMED on one group, every other gesture group attached to the same `GtkWidget` will switch the state for that sequence to %GTK_EVENT_SEQUENCE_DENIED. `GtkGesture` to group @gesture with a `GtkGesture` Returns %TRUE if @gesture is currently handling events corresponding to @sequence. %TRUE if @gesture is handling @sequence, %FALSE otherwise a `GtkGesture` a `GdkEventSequence` Returns %TRUE if the gesture is currently active. A gesture is active while there are touch sequences interacting with it. %TRUE if gesture is active a `GtkGesture` Returns %TRUE if both gestures pertain to the same group. whether the gestures are grouped a `GtkGesture` another `GtkGesture` Returns %TRUE if the gesture is currently recognized. A gesture is recognized if there are as many interacting touch sequences as required by @gesture. %TRUE if gesture is recognized a `GtkGesture` Sets the state of @sequence in @gesture. Sequences start in state %GTK_EVENT_SEQUENCE_NONE, and whenever they change state, they can never go back to that state. Likewise, sequences in state %GTK_EVENT_SEQUENCE_DENIED cannot turn back to a not denied state. With these rules, the lifetime of an event sequence is constrained to the next four: * None * None → Denied * None → Claimed * None → Claimed → Denied Note: Due to event handling ordering, it may be unsafe to set the state on another gesture within a [signal@Gtk.Gesture::begin] signal handler, as the callback might be executed before the other gesture knows about the sequence. A safe way to perform this could be: ```c static void first_gesture_begin_cb (GtkGesture *first_gesture, GdkEventSequence *sequence, gpointer user_data) { gtk_gesture_set_sequence_state (first_gesture, sequence, GTK_EVENT_SEQUENCE_CLAIMED); gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED); } static void second_gesture_begin_cb (GtkGesture *second_gesture, GdkEventSequence *sequence, gpointer user_data) { if (gtk_gesture_get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_CLAIMED) gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED); } ``` If both gestures are in the same group, just set the state on the gesture emitting the event, the sequence will be already be initialized to the group's global state when the second gesture processes the event. Use [method@Gtk.Gesture.set_state] %TRUE if @sequence is handled by @gesture, and the state is changed successfully a `GtkGesture` a `GdkEventSequence` the sequence state Sets the state of all sequences that @gesture is currently interacting with. Sequences start in state %GTK_EVENT_SEQUENCE_NONE, and whenever they change state, they can never go back to that state. Likewise, sequences in state %GTK_EVENT_SEQUENCE_DENIED cannot turn back to a not denied state. With these rules, the lifetime of an event sequence is constrained to the next four: * None * None → Denied * None → Claimed * None → Claimed → Denied Note: Due to event handling ordering, it may be unsafe to set the state on another gesture within a [signal@Gtk.Gesture::begin] signal handler, as the callback might be executed before the other gesture knows about the sequence. A safe way to perform this could be: ```c static void first_gesture_begin_cb (GtkGesture *first_gesture, GdkEventSequence *sequence, gpointer user_data) { gtk_gesture_set_state (first_gesture, GTK_EVENT_SEQUENCE_CLAIMED); gtk_gesture_set_state (second_gesture, GTK_EVENT_SEQUENCE_DENIED); } static void second_gesture_begin_cb (GtkGesture *second_gesture, GdkEventSequence *sequence, gpointer user_data) { if (gtk_gesture_get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_CLAIMED) gtk_gesture_set_state (second_gesture, GTK_EVENT_SEQUENCE_DENIED); } ``` If both gestures are in the same group, just set the state on the gesture emitting the event, the sequence will be already be initialized to the group's global state when the second gesture processes the event. %TRUE if the state of at least one sequence was changed successfully a `GtkGesture` the sequence state Separates @gesture into an isolated group. a `GtkGesture` The number of touch points that trigger recognition on this gesture. Emitted when the gesture is recognized. This means the number of touch sequences matches [property@Gtk.Gesture:n-points]. Note: These conditions may also happen when an extra touch (eg. a third touch on a 2-touches gesture) is lifted, in that situation @sequence won't pertain to the current set of active touches, so don't rely on this being true. the `GdkEventSequence` that made the gesture to be recognized Emitted whenever a sequence is cancelled. This usually happens on active touches when [method@Gtk.EventController.reset] is called on @gesture (manually, due to grabs...), or the individual @sequence was claimed by parent widgets' controllers (see [method@Gtk.Gesture.set_sequence_state]). @gesture must forget everything about @sequence as in response to this signal. the `GdkEventSequence` that was cancelled Emitted when @gesture either stopped recognizing the event sequences as something to be handled, or the number of touch sequences became higher or lower than [property@Gtk.Gesture:n-points]. Note: @sequence might not pertain to the group of sequences that were previously triggering recognition on @gesture (ie. a just pressed touch sequence that exceeds [property@Gtk.Gesture:n-points]). This situation may be detected by checking through [method@Gtk.Gesture.handles_sequence]. the `GdkEventSequence` that made gesture recognition to finish Emitted whenever a sequence state changes. See [method@Gtk.Gesture.set_sequence_state] to know more about the expectable sequence lifetimes. the `GdkEventSequence` that was cancelled the new sequence state Emitted whenever an event is handled while the gesture is recognized. @sequence is guaranteed to pertain to the set of active touches. the `GdkEventSequence` that was updated Recognizes click gestures. It is able to recognize multiple clicks on a nearby zone, which can be listened for through the [signal@Gtk.GestureClick::pressed] signal. Whenever time or distance between clicks exceed the GTK defaults, [signal@Gtk.GestureClick::stopped] is emitted, and the click counter is reset. Returns a newly created `GtkGesture` that recognizes single and multiple presses. a newly created `GtkGestureClick` Emitted whenever a button or touch press happens. how many touch/button presses happened with this one The X coordinate, in widget allocation coordinates The Y coordinate, in widget allocation coordinates Emitted when a button or touch is released. @n_press will report the number of press that is paired to this event, note that [signal@Gtk.GestureClick::stopped] may have been emitted between the press and its release, @n_press will only start over at the next press. number of press that is paired with this release The X coordinate, in widget allocation coordinates The Y coordinate, in widget allocation coordinates Emitted whenever any time/distance threshold has been exceeded. Emitted whenever the gesture receives a release event that had no previous corresponding press. Due to implicit grabs, this can only happen on situations where input is grabbed elsewhere mid-press or the pressed widget voluntarily relinquishes its implicit grab. X coordinate of the event Y coordinate of the event Button being released Sequence being released Recognizes drag gestures. The drag operation itself can be tracked throughout the [signal@Gtk.GestureDrag::drag-begin], [signal@Gtk.GestureDrag::drag-update] and [signal@Gtk.GestureDrag::drag-end] signals, and the relevant coordinates can be extracted through [method@Gtk.GestureDrag.get_offset] and [method@Gtk.GestureDrag.get_start_point]. Returns a newly created `GtkGesture` that recognizes drags. a newly created `GtkGestureDrag` Gets the offset from the start point. If the @gesture is active, this function returns %TRUE and fills in @x and @y with the coordinates of the current point, as an offset to the starting drag point. %TRUE if the gesture is active a `GtkGesture` X offset for the current point Y offset for the current point Gets the point where the drag started. If the @gesture is active, this function returns %TRUE and fills in @x and @y with the drag start coordinates, in widget-relative coordinates. %TRUE if the gesture is active a `GtkGesture` X coordinate for the drag start point Y coordinate for the drag start point Emitted whenever dragging starts. X coordinate, relative to the widget allocation Y coordinate, relative to the widget allocation Emitted whenever the dragging is finished. X offset, relative to the start point Y offset, relative to the start point Emitted whenever the dragging point moves. X offset, relative to the start point Y offset, relative to the start point Recognizes long press gestures. This gesture is also known as “Press and Hold”. When the timeout is exceeded, the gesture is triggering the [signal@Gtk.GestureLongPress::pressed] signal. If the touchpoint is lifted before the timeout passes, or if it drifts too far of the initial press point, the [signal@Gtk.GestureLongPress::cancelled] signal will be emitted. How long the timeout is before the ::pressed signal gets emitted is determined by the [property@Gtk.Settings:gtk-long-press-time] setting. It can be modified by the [property@Gtk.GestureLongPress:delay-factor] property. Returns a newly created `GtkGesture` that recognizes long presses. a newly created `GtkGestureLongPress`. Returns the delay factor. the delay factor A `GtkGestureLongPress` Applies the given delay factor. The default long press time will be multiplied by this value. Valid values are in the range [0.5..2.0]. A `GtkGestureLongPress` The delay factor to apply Factor by which to modify the default timeout. Emitted whenever a press moved too far, or was released before [signal@Gtk.GestureLongPress::pressed] happened. Emitted whenever a press goes unmoved/unreleased longer than what the GTK defaults tell. the X coordinate where the press happened, relative to the widget allocation the Y coordinate where the press happened, relative to the widget allocation Recognizes pan gestures. These are drags that are locked to happen along one axis. The axis that a `GtkGesturePan` handles is defined at construct time, and can be changed through [method@Gtk.GesturePan.set_orientation]. When the gesture starts to be recognized, `GtkGesturePan` will attempt to determine as early as possible whether the sequence is moving in the expected direction, and denying the sequence if this does not happen. Once a panning gesture along the expected axis is recognized, the [signal@Gtk.GesturePan::pan] signal will be emitted as input events are received, containing the offset in the given axis. Returns a newly created `GtkGesture` that recognizes pan gestures. a newly created `GtkGesturePan` expected orientation Returns the orientation of the pan gestures that this @gesture expects. the expected orientation for pan gestures A `GtkGesturePan` Sets the orientation to be expected on pan gestures. A `GtkGesturePan` expected orientation The expected orientation of pan gestures. Emitted once a panning gesture along the expected axis is detected. current direction of the pan gesture Offset along the gesture orientation Recognizes 2-finger rotation gestures. Whenever the angle between both handled sequences changes, the [signal@Gtk.GestureRotate::angle-changed] signal is emitted. Returns a newly created `GtkGesture` that recognizes 2-touch rotation gestures. a newly created `GtkGestureRotate` Gets the angle delta in radians. If @gesture is active, this function returns the angle difference in radians since the gesture was first recognized. If @gesture is not active, 0 is returned. the angle delta in radians a `GtkGestureRotate` Emitted when the angle between both tracked points changes. Current angle in radians Difference with the starting angle, in radians A `GtkGesture` subclass optimized for singe-touch and mouse gestures. Under interaction, these gestures stick to the first interacting sequence, which is accessible through [method@Gtk.GestureSingle.get_current_sequence] while the gesture is being interacted with. By default gestures react to both %GDK_BUTTON_PRIMARY and touch events. [method@Gtk.GestureSingle.set_touch_only] can be used to change the touch behavior. Callers may also specify a different mouse button number to interact with through [method@Gtk.GestureSingle.set_button], or react to any mouse button by setting it to 0. While the gesture is active, the button being currently pressed can be known through [method@Gtk.GestureSingle.get_current_button]. Returns the button number @gesture listens for. If this is 0, the gesture reacts to any button press. The button number, or 0 for any button a `GtkGestureSingle` Returns the button number currently interacting with @gesture, or 0 if there is none. The current button number a `GtkGestureSingle` Returns the event sequence currently interacting with @gesture. This is only meaningful if [method@Gtk.Gesture.is_active] returns %TRUE. the current sequence a `GtkGestureSingle` Gets whether a gesture is exclusive. For more information, see [method@Gtk.GestureSingle.set_exclusive]. Whether the gesture is exclusive a `GtkGestureSingle` Returns %TRUE if the gesture is only triggered by touch events. %TRUE if the gesture only handles touch events a `GtkGestureSingle` Sets the button number @gesture listens to. If non-0, every button press from a different button number will be ignored. Touch events implicitly match with button 1. a `GtkGestureSingle` button number to listen to, or 0 for any button Sets whether @gesture is exclusive. An exclusive gesture will only handle pointer and "pointer emulated" touch events, so at any given time, there is only one sequence able to interact with those. a `GtkGestureSingle` %TRUE to make @gesture exclusive Sets whether to handle only touch events. If @touch_only is %TRUE, @gesture will only handle events of type %GDK_TOUCH_BEGIN, %GDK_TOUCH_UPDATE or %GDK_TOUCH_END. If %FALSE, mouse events will be handled too. a `GtkGestureSingle` whether @gesture handles only touch events Mouse button number to listen to, or 0 to listen for any button. Whether the gesture is exclusive. Exclusive gestures only listen to pointer and pointer emulated events. Whether the gesture handles only touch events. Recognizes tablet stylus input. The provided signals just relay the basic information of the stylus events. Creates a new `GtkGestureStylus`. a newly created stylus gesture Returns the current values for the requested @axes. This function must be called from the handler of one of the [signal@Gtk.GestureStylus::down], [signal@Gtk.GestureStylus::motion], [signal@Gtk.GestureStylus::up] or [signal@Gtk.GestureStylus::proximity] signals. %TRUE if there is a current value for the axes a `GtkGestureStylus` array of requested axes, terminated with %GDK_AXIS_IGNORE return location for the axis values Returns the current value for the requested @axis. This function must be called from the handler of one of the [signal@Gtk.GestureStylus::down], [signal@Gtk.GestureStylus::motion], [signal@Gtk.GestureStylus::up] or [signal@Gtk.GestureStylus::proximity] signals. %TRUE if there is a current value for the axis a `GtkGestureStylus` requested device axis return location for the axis value Returns the accumulated backlog of tracking information. By default, GTK will limit rate of input events. On stylus input where accuracy of strokes is paramount, this function returns the accumulated coordinate/timing state before the emission of the current [Gtk.GestureStylus::motion] signal. This function may only be called within a [signal@Gtk.GestureStylus::motion] signal handler, the state given in this signal and obtainable through [method@Gtk.GestureStylus.get_axis] express the latest (most up-to-date) state in motion history. The @backlog is provided in chronological order. %TRUE if there is a backlog to unfold in the current state. a `GtkGestureStylus` coordinates and times for the backlog events return location for the number of elements Returns the `GdkDeviceTool` currently driving input through this gesture. This function must be called from the handler of one of the [signal@Gtk.GestureStylus::down], [signal@Gtk.GestureStylus::motion], [signal@Gtk.GestureStylus::up] or [signal@Gtk.GestureStylus::proximity] signals. The current stylus tool a `GtkGestureStylus` Checks whether the gesture is for styluses only. Stylus-only gestures will signal events exclusively from stylus input devices. %TRUE if the gesture is only for stylus events the gesture Sets the state of stylus-only If true, the gesture will exclusively handle events from stylus input devices, otherwise it'll handle events from any pointing device. the gesture whether the gesture is used exclusively for stylus events If this gesture should exclusively react to stylus input devices. Emitted when the stylus touches the device. the X coordinate of the stylus event the Y coordinate of the stylus event Emitted when the stylus moves while touching the device. the X coordinate of the stylus event the Y coordinate of the stylus event Emitted when the stylus is in proximity of the device. the X coordinate of the stylus event the Y coordinate of the stylus event Emitted when the stylus no longer touches the device. the X coordinate of the stylus event the Y coordinate of the stylus event Recognizes swipe gestures. After a press/move/.../move/release sequence happens, the [signal@Gtk.GestureSwipe::swipe] signal will be emitted, providing the velocity and directionality of the sequence at the time it was lifted. If the velocity is desired in intermediate points, [method@Gtk.GestureSwipe.get_velocity] can be called in a [signal@Gtk.Gesture::update] handler. All velocities are reported in pixels/sec units. Returns a newly created `GtkGesture` that recognizes swipes. a newly created `GtkGestureSwipe` Gets the current velocity. If the gesture is recognized, this function returns %TRUE and fills in @velocity_x and @velocity_y with the recorded velocity, as per the last events processed. whether velocity could be calculated a `GtkGestureSwipe` return value for the velocity in the X axis, in pixels/sec return value for the velocity in the Y axis, in pixels/sec Emitted when the recognized gesture is finished. Velocity and direction are a product of previously recorded events. velocity in the X axis, in pixels/sec velocity in the Y axis, in pixels/sec Recognizes 2-finger pinch/zoom gestures. Whenever the distance between both tracked sequences changes, the [signal@Gtk.GestureZoom::scale-changed] signal is emitted to report the scale factor. Returns a newly created `GtkGesture` that recognizes pinch/zoom gestures. a newly created `GtkGestureZoom` Gets the scale delta. If @gesture is active, this function returns the zooming difference since the gesture was recognized (hence the starting point is considered 1:1). If @gesture is not active, 1 is returned. the scale delta a `GtkGestureZoom` Emitted whenever the distance between both tracked sequences changes. Scale delta, taking the initial state as 1:1 Bypasses gsk rendering by passing the content of its child directly to the compositor. Graphics offload is an optimization to reduce overhead and battery use that is most useful for video content. It only works on some platforms and in certain situations. GTK will automatically fall back to normal rendering if it doesn't. Graphics offload is most efficient if there are no controls drawn on top of the video content. You should consider using graphics offload for your main widget if it shows frequently changing content (such as a video, or a VM display) and you provide the content in the form of dmabuf textures (see [class@Gdk.DmabufTextureBuilder]), in particular if it may be fullscreen. Numerous factors can prohibit graphics offload: - Unsupported platforms. Currently, graphics offload only works on Linux with Wayland. - Clipping, such as rounded corners that cause the video content to not be rectangular - Unsupported dmabuf formats (see [method@Gdk.Display.get_dmabuf_formats]) - Translucent video content (content with an alpha channel, even if it isn't used) - Transforms that are more complex than translations and scales - Filters such as opacity, grayscale or similar To investigate problems related graphics offload, GTK offers debug flags to print out information about graphics offload and dmabuf use: GDK_DEBUG=offload GDK_DEBUG=dmabuf The GTK inspector provides a visual debugging tool for graphics offload. Creates a new GtkGraphicsOffload widget. the new widget the child widget Returns whether the widget draws a black background. See [method@Gtk.GraphicsOffload.set_black_background]. `TRUE` if black background is drawn a `GtkGraphicsOffload` Gets the child of @self. the child widget a `GtkGraphicsOffload` Returns whether offload is enabled for @self. whether offload is enabled a `GtkGraphicsOffload` Sets whether this GtkGraphicsOffload widget will draw a black background. A main use case for this is **_letterboxing_** where black bars are visible next to the content if the aspect ratio of the content does not match the dimensions of the monitor. Using this property for letterboxing instead of CSS allows compositors to show content with maximum efficiency, using direct scanout to avoid extra copies in the compositor. On Wayland, this is implemented using the [single-pixel buffer](https://wayland.app/protocols/single-pixel-buffer-v1) protocol. a `GtkGraphicsOffload` whether to draw a black background behind the content Sets the child of @self. a `GtkGraphicsOffload` the child widget Sets whether this GtkGraphicsOffload widget will attempt to offload the content of its child widget. a `GtkGraphicsOffload` whether to enable offload Whether to draw a black background. The child widget. Whether graphics offload is enabled. Represents the state of graphics offloading. Graphics offloading is enabled. Graphics offloading is disabled. Arranges its child widgets in rows and columns. <picture> <source srcset="grid-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkGrid" src="grid.png"> </picture> It supports arbitrary positions and horizontal/vertical spans. Children are added using [method@Gtk.Grid.attach]. They can span multiple rows or columns. It is also possible to add a child next to an existing child, using [method@Gtk.Grid.attach_next_to]. To remove a child from the grid, use [method@Gtk.Grid.remove]. The behaviour of `GtkGrid` when several children occupy the same grid cell is undefined. # GtkGrid as GtkBuildable Every child in a `GtkGrid` has access to a custom [iface@Gtk.Buildable] element, called `<layout>`. It can by used to specify a position in the grid and optionally spans. All properties that can be used in the `<layout>` element are implemented by [class@Gtk.GridLayoutChild]. It is implemented by `GtkWidget` using [class@Gtk.LayoutManager]. To showcase it, here is a simple example: ```xml <object class="GtkGrid" id="my_grid"> <child> <object class="GtkButton" id="button1"> <property name="label">Button 1</property> <layout> <property name="column">0</property> <property name="row">0</property> </layout> </object> </child> <child> <object class="GtkButton" id="button2"> <property name="label">Button 2</property> <layout> <property name="column">1</property> <property name="row">0</property> </layout> </object> </child> <child> <object class="GtkButton" id="button3"> <property name="label">Button 3</property> <layout> <property name="column">2</property> <property name="row">0</property> <property name="row-span">2</property> </layout> </object> </child> <child> <object class="GtkButton" id="button4"> <property name="label">Button 4</property> <layout> <property name="column">0</property> <property name="row">1</property> <property name="column-span">2</property> </layout> </object> </child> </object> ``` It organizes the first two buttons side-by-side in one cell each. The third button is in the last column but spans across two rows. This is defined by the `row-span` property. The last button is located in the second row and spans across two columns, which is defined by the `column-span` property. # CSS nodes `GtkGrid` uses a single CSS node with name `grid`. # Accessibility Until GTK 4.10, `GtkGrid` used the [enum@Gtk.AccessibleRole.group] role. Starting from GTK 4.12, `GtkGrid` uses the [enum@Gtk.AccessibleRole.generic] role. Creates a new grid widget. the new `GtkGrid` Adds a widget to the grid. The position of @child is determined by @column and @row. The number of “cells” that @child will occupy is determined by @width and @height. a `GtkGrid` the widget to add the column number to attach the left side of @child to the row number to attach the top side of @child to the number of columns that @child will span the number of rows that @child will span Adds a widget to the grid. The widget is placed next to @sibling, on the side determined by @side. When @sibling is %NULL, the widget is placed in row (for left or right placement) or column 0 (for top or bottom placement), at the end indicated by @side. Attaching widgets labeled `[1]`, `[2]`, `[3]` with `@sibling == %NULL` and `@side == %GTK_POS_LEFT` yields a layout of `[3][2][1]`. a `GtkGrid` the widget to add the child of @grid that @child will be placed next to, or %NULL to place @child at the beginning or end the side of @sibling that @child is positioned next to the number of columns that @child will span the number of rows that @child will span Returns which row defines the global baseline of @grid. the row index defining the global baseline a `GtkGrid` Gets the child of @grid whose area covers the grid cell at @column, @row. the child at the given position a `GtkGrid` the left edge of the cell the top edge of the cell Returns whether all columns of @grid have the same width. whether all columns of @grid have the same width. a `GtkGrid` Returns the amount of space between the columns of @grid. the column spacing of @grid a `GtkGrid` Returns the baseline position of @row. See [method@Gtk.Grid.set_row_baseline_position]. the baseline position of @row a `GtkGrid` a row index Returns whether all rows of @grid have the same height. whether all rows of @grid have the same height. a `GtkGrid` Returns the amount of space between the rows of @grid. the row spacing of @grid a `GtkGrid` Inserts a column at the specified position. Children which are attached at or to the right of this position are moved one column to the right. Children which span across this position are grown to span the new column. a `GtkGrid` the position to insert the column at Inserts a row or column at the specified position. The new row or column is placed next to @sibling, on the side determined by @side. If @side is %GTK_POS_TOP or %GTK_POS_BOTTOM, a row is inserted. If @side is %GTK_POS_LEFT of %GTK_POS_RIGHT, a column is inserted. a `GtkGrid` the child of @grid that the new row or column will be placed next to the side of @sibling that @child is positioned next to Inserts a row at the specified position. Children which are attached at or below this position are moved one row down. Children which span across this position are grown to span the new row. a `GtkGrid` the position to insert the row at Queries the attach points and spans of @child inside the given `GtkGrid`. a `GtkGrid` a `GtkWidget` child of @grid the column used to attach the left side of @child the row used to attach the top side of @child the number of columns @child spans the number of rows @child spans Removes a child from @grid. The child must have been added with [method@Gtk.Grid.attach] or [method@Gtk.Grid.attach_next_to]. a `GtkGrid` the child widget to remove Removes a column from the grid. Children that are placed in this column are removed, spanning children that overlap this column have their width reduced by one, and children after the column are moved to the left. a `GtkGrid` the position of the column to remove Removes a row from the grid. Children that are placed in this row are removed, spanning children that overlap this row have their height reduced by one, and children below the row are moved up. a `GtkGrid` the position of the row to remove Sets which row defines the global baseline for the entire grid. Each row in the grid can have its own local baseline, but only one of those is global, meaning it will be the baseline in the parent of the @grid. a `GtkGrid` the row index Sets whether all columns of @grid will have the same width. a `GtkGrid` %TRUE to make columns homogeneous Sets the amount of space between columns of @grid. a `GtkGrid` the amount of space to insert between columns Sets how the baseline should be positioned on @row of the grid, in case that row is assigned more space than is requested. The default baseline position is %GTK_BASELINE_POSITION_CENTER. a `GtkGrid` a row index a `GtkBaselinePosition` Sets whether all rows of @grid will have the same height. a `GtkGrid` %TRUE to make rows homogeneous Sets the amount of space between rows of @grid. a `GtkGrid` the amount of space to insert between rows The row to align to the baseline when valign is using baseline alignment. If %TRUE, the columns are all the same width. The amount of space between two consecutive columns. If %TRUE, the rows are all the same height. The amount of space between two consecutive rows. The parent class. Arranges child widgets in rows and columns. Children have an "attach point" defined by the horizontal and vertical index of the cell they occupy; children can span multiple rows or columns. The layout properties for setting the attach points and spans are set using the [class@Gtk.GridLayoutChild] associated to each child widget. The behaviour of `GtkGridLayout` when several children occupy the same grid cell is undefined. `GtkGridLayout` can be used like a `GtkBoxLayout` if all children are attached to the same row or column; however, if you only ever need a single row or column, you should consider using `GtkBoxLayout`. Creates a new `GtkGridLayout`. the newly created `GtkGridLayout` Retrieves the row set with gtk_grid_layout_set_baseline_row(). the global baseline row a `GtkGridLayout` Checks whether all columns of @grid should have the same width. %TRUE if the columns are homogeneous, and %FALSE otherwise a `GtkGridLayout` Retrieves the spacing set with gtk_grid_layout_set_column_spacing(). the spacing between consecutive columns a `GtkGridLayout` Returns the baseline position of @row. If no value has been set with [method@Gtk.GridLayout.set_row_baseline_position], the default value of %GTK_BASELINE_POSITION_CENTER is returned. the baseline position of @row a `GtkGridLayout` a row index Checks whether all rows of @grid should have the same height. %TRUE if the rows are homogeneous, and %FALSE otherwise a `GtkGridLayout` Retrieves the spacing set with gtk_grid_layout_set_row_spacing(). the spacing between consecutive rows a `GtkGridLayout` Sets which row defines the global baseline for the entire grid. Each row in the grid can have its own local baseline, but only one of those is global, meaning it will be the baseline in the parent of the @grid. a `GtkGridLayout` the row index Sets whether all columns of @grid should have the same width. a `GtkGridLayout` %TRUE to make columns homogeneous Sets the amount of space to insert between consecutive columns. a `GtkGridLayout` the amount of space between columns, in pixels Sets how the baseline should be positioned on @row of the grid, in case that row is assigned more space than is requested. a `GtkGridLayout` a row index a `GtkBaselinePosition` Sets whether all rows of @grid should have the same height. a `GtkGridLayout` %TRUE to make rows homogeneous Sets the amount of space to insert between consecutive rows. a `GtkGridLayout` the amount of space between rows, in pixels The row to align to the baseline, when `GtkWidget:valign` is set to %GTK_ALIGN_BASELINE. Whether all the columns in the grid have the same width. The amount of space between to consecutive columns. Whether all the rows in the grid have the same height. The amount of space between to consecutive rows. `GtkLayoutChild` subclass for children in a `GtkGridLayout`. Retrieves the column number to which @child attaches its left side. the column number a `GtkGridLayoutChild` Retrieves the number of columns that @child spans to. the number of columns a `GtkGridLayoutChild` Retrieves the row number to which @child attaches its top side. the row number a `GtkGridLayoutChild` Retrieves the number of rows that @child spans to. the number of row a `GtkGridLayoutChild` Sets the column number to attach the left side of @child. a `GtkGridLayoutChild` the attach point for @child Sets the number of columns @child spans to. a `GtkGridLayoutChild` the span of @child Sets the row to place @child in. a `GtkGridLayoutChild` the row for @child Sets the number of rows @child spans to. a `GtkGridLayoutChild` the span of @child The column to place the child in. The number of columns the child spans to. The row to place the child in. The number of rows the child spans to. Presents a large dynamic grid of items. `GtkGridView` uses its factory to generate one child widget for each visible item and shows them in a grid. The orientation of the grid view determines if the grid reflows vertically or horizontally. `GtkGridView` allows the user to select items according to the selection characteristics of the model. For models that allow multiple selected items, it is possible to turn on _rubberband selection_, using [property@Gtk.GridView:enable-rubberband]. To learn more about the list widget framework, see the [overview](section-list-widget.html). # Actions `GtkGridView` defines a set of built-in actions: - `list.activate-item` activates the item at given position by emitting the the [signal@Gtk.GridView::activate] signal. # CSS nodes ``` gridview ├── child[.activatable] │ ├── child[.activatable] │ ┊ ╰── [rubberband] ``` `GtkGridView` uses a single CSS node with name `gridview`. Each child uses a single CSS node with name `child`. If the [property@Gtk.ListItem:activatable] property is set, the corresponding row will have the `.activatable` style class. For rubberband selection, a subnode with name `rubberband` is used. # Accessibility `GtkGridView` uses the [enum@Gtk.AccessibleRole.grid] role, and the items use the [enum@Gtk.AccessibleRole.grid_cell] role. Creates a new `GtkGridView` that uses the given @factory for mapping items to widgets. The function takes ownership of the arguments, so you can write code like ```c grid_view = gtk_grid_view_new (create_model (), gtk_builder_list_item_factory_new_from_resource ("/resource.ui")); ``` a new `GtkGridView` using the given @model and @factory the model to use The factory to populate items with Returns whether rows can be selected by dragging with the mouse. %TRUE if rubberband selection is enabled a `GtkGridView` Gets the factory that's currently used to populate list items. The factory in use a `GtkGridView` Gets the maximum number of columns that the grid will use. The maximum number of columns a `GtkGridView` Gets the minimum number of columns that the grid will use. The minimum number of columns a `GtkGridView` Gets the model that's currently used to read the items displayed. The model in use a `GtkGridView` Returns whether items will be activated on single click and selected on hover. %TRUE if items are activated on single click a `GtkGridView` Gets the behavior set for the <kbd>Tab</kbd> key. The behavior of the <kbd>Tab</kbd> key a `GtkGridView` Scrolls to the item at the given position and performs the actions specified in @flags. This function works no matter if the gridview is shown or focused. If it isn't, then the changes will take effect once that happens. The gridview to scroll in position of the item. Must be less than the number of items in the view. actions to perform details of how to perform the scroll operation or %NULL to scroll into view Sets whether selections can be changed by dragging with the mouse. a `GtkGridView` %TRUE to enable rubberband selection Sets the `GtkListItemFactory` to use for populating list items. a `GtkGridView` the factory to use Sets the maximum number of columns to use. This number must be at least 1. If @max_columns is smaller than the minimum set via [method@Gtk.GridView.set_min_columns], that value is used instead. a `GtkGridView` The maximum number of columns Sets the minimum number of columns to use. This number must be at least 1. If @min_columns is smaller than the minimum set via [method@Gtk.GridView.set_max_columns], that value is ignored. a `GtkGridView` The minimum number of columns Sets the model to use. This must be a [iface@Gtk.SelectionModel]. a `GtkGridView` the model to use Sets whether items should be activated on single click and selected on hover. a `GtkGridView` %TRUE to activate items on single click Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. a `GtkGridView` The desired tab behavior Allow rubberband selection. Factory for populating list items. The factory must be for configuring [class@Gtk.ListItem] objects. Maximum number of columns per row. If this number is smaller than [property@Gtk.GridView:min-columns], that value is used instead. Minimum number of columns per row. Model for the items displayed. Activate rows on single click and select them on hover. Behavior of the <kbd>Tab</kbd> key Emitted when a cell has been activated by the user, usually via activating the GtkGridView|list.activate-item action. This allows for a convenient way to handle activation in a gridview. See [property@Gtk.ListItem:activatable] for details on how to use this signal. position of item to activate Creates a custom titlebar for a window. <picture> <source srcset="headerbar-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkHeaderBar" src="headerbar.png"> </picture> `GtkHeaderBar` is similar to a horizontal `GtkCenterBox`. It allows children to be placed at the start or the end. In addition, it allows the window title to be displayed. The title will be centered with respect to the width of the box, even if the children at either side take up different amounts of space. `GtkHeaderBar` can add typical window frame controls, such as minimize, maximize and close buttons, or the window icon. For these reasons, `GtkHeaderBar` is the natural choice for use as the custom titlebar widget of a `GtkWindow` (see [method@Gtk.Window.set_titlebar]), as it gives features typical of titlebars while allowing the addition of child widgets. ## GtkHeaderBar as GtkBuildable The `GtkHeaderBar` implementation of the `GtkBuildable` interface supports adding children at the start or end sides by specifying “start” or “end” as the “type” attribute of a `<child>` element, or setting the title widget by specifying “title” value. By default the `GtkHeaderBar` uses a `GtkLabel` displaying the title of the window it is contained in as the title widget, equivalent to the following UI definition: ```xml <object class="GtkHeaderBar"> <property name="title-widget"> <object class="GtkLabel"> <property name="label" translatable="yes">Label</property> <property name="single-line-mode">True</property> <property name="ellipsize">end</property> <property name="width-chars">5</property> <style> <class name="title"/> </style> </object> </property> </object> ``` # CSS nodes ``` headerbar ╰── windowhandle ╰── box ├── box.start │ ├── windowcontrols.start │ ╰── [other children] ├── [Title Widget] ╰── box.end ├── [other children] ╰── windowcontrols.end ``` A `GtkHeaderBar`'s CSS node is called `headerbar`. It contains a `windowhandle` subnode, which contains a `box` subnode, which contains two `box` subnodes at the start and end of the header bar, as well as a center node that represents the title. Each of the boxes contains a `windowcontrols` subnode, see [class@Gtk.WindowControls] for details, as well as other children. # Accessibility `GtkHeaderBar` uses the [enum@Gtk.AccessibleRole.group] role. Creates a new `GtkHeaderBar` widget. a new `GtkHeaderBar` Gets the decoration layout of the header bar. the decoration layout a header bar Returns whether this header bar shows the standard window title buttons. true if title buttons are shown a header bar Retrieves the title widget of the header bar. See [method@Gtk.HeaderBar.set_title_widget]. the title widget a header bar Returns whether this header bar shows platform native window controls. true if native window controls are shown a header bar Adds a child to the header bar, packed with reference to the end. A header bar the widget to be added to @bar Adds a child to the header bar, packed with reference to the start. A header bar the widget to be added to @bar Removes a child from the header bar. The child must have been added with [method@Gtk.HeaderBar.pack_start], [method@Gtk.HeaderBar.pack_end] or [method@Gtk.HeaderBar.set_title_widget]. a header bar the child to remove Sets the decoration layout for this header bar. This property overrides the [property@Gtk.Settings:gtk-decoration-layout] setting. There can be valid reasons for overriding the setting, such as a header bar design that does not allow for buttons to take room on the right, or only offers room for a single close button. Split header bars are another example for overriding the setting. The format of the string is button names, separated by commas. A colon separates the buttons that should appear on the left from those on the right. Recognized button names are minimize, maximize, close and icon (the window icon). For example, “icon:minimize,maximize,close” specifies an icon on the left, and minimize, maximize and close buttons on the right. a header bar a decoration layout Sets whether this header bar shows the standard window title buttons. a header bar true to show standard title buttons Sets the title for the header bar. When set to `NULL`, the headerbar will display the title of the window it is contained in. The title should help a user identify the current view. To achieve the same style as the builtin title, use the “title” style class. You should set the title widget to `NULL`, for the window title label to be visible again. a header bar a widget to use for a title Sets whether this header bar shows native window controls. This option shows the "stoplight" buttons on macOS. For Linux, this option has no effect. See also [Using GTK on Apple macOS](osx.html?native-window-controls). a header bar true to show native window controls The decoration layout for buttons. If this property is not set, the [property@Gtk.Settings:gtk-decoration-layout] setting is used. Whether to show title buttons like close, minimize, maximize. Which buttons are actually shown and where is determined by the [property@Gtk.HeaderBar:decoration-layout] property, and by the state of the window (e.g. a close button will not be shown if the window can't be closed). The title widget to display. Whether to show platform native close/minimize/maximize buttons. For macOS, the [property@Gtk.HeaderBar:decoration-layout] property can be used to enable/disable controls. On Linux, this option has no effect. See also [Using GTK on Apple macOS](osx.html?native-window-controls). The interface for GTK input methods. `GtkIMContext` is used by GTK text input widgets like `GtkText` to map from key events to Unicode character strings. An input method may consume multiple key events in sequence before finally outputting the composed result. This is called *preediting*, and an input method may provide feedback about this process by displaying the intermediate composition states as preedit text. To do so, the `GtkIMContext` will emit [signal@Gtk.IMContext::preedit-start], [signal@Gtk.IMContext::preedit-changed] and [signal@Gtk.IMContext::preedit-end] signals. For instance, the built-in GTK input method [class@Gtk.IMContextSimple] implements the input of arbitrary Unicode code points by holding down the <kbd>Control</kbd> and <kbd>Shift</kbd> keys and then typing <kbd>u</kbd> followed by the hexadecimal digits of the code point. When releasing the <kbd>Control</kbd> and <kbd>Shift</kbd> keys, preediting ends and the character is inserted as text. For example, Ctrl+Shift+u 2 0 A C results in the € sign. Additional input methods can be made available for use by GTK widgets as loadable modules. An input method module is a small shared library which provides a `GIOExtension` for the extension point named "gtk-im-module". To connect a widget to the users preferred input method, you should use [class@Gtk.IMMulticontext]. Default handler of the [signal@Gtk.IMContext::commit] signal. Asks the widget that the input context is attached to delete characters around the cursor position by emitting the `::delete_surrounding` signal. Note that @offset and @n_chars are in characters not in bytes which differs from the usage other places in `GtkIMContext`. In order to use this function, you should first call [method@Gtk.IMContext.get_surrounding] to get the current context, and call this function immediately afterwards to make sure that you know what you are deleting. You should also account for the fact that even if the signal was handled, the input context might not have deleted all the characters that were requested to be deleted. This function is used by an input method that wants to make substitutions in the existing text in response to new input. It is not useful for applications. %TRUE if the signal was handled. a `GtkIMContext` offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. Allow an input method to internally handle key press and release events. If this function returns %TRUE, then no further processing should be done for this key event. %TRUE if the input method handled the key event. a `GtkIMContext` the key event Notify the input method that the widget to which this input context corresponds has gained focus. The input method may, for example, change the displayed feedback to reflect this change. a `GtkIMContext` Notify the input method that the widget to which this input context corresponds has lost focus. The input method may, for example, change the displayed feedback or reset the contexts state to reflect this change. a `GtkIMContext` Retrieve the current preedit string for the input context, and a list of attributes to apply to the string. This string should be displayed inserted at the insertion point. a `GtkIMContext` location to store the retrieved string. The string retrieved must be freed with g_free(). location to store the retrieved attribute list. When you are done with this list, you must unreference it with [method@Pango.AttrList.unref]. location to store position of cursor (in characters) within the preedit string. Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai where only some sequences of characters are allowed. This function is implemented by emitting the [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method; in response to this signal, a widget should provide as much context as is available, up to an entire paragraph, by calling [method@Gtk.IMContext.set_surrounding]. Note that there is no obligation for a widget to respond to the `::retrieve-surrounding` signal, so input methods must be prepared to function without context. Use [method@Gtk.IMContext.get_surrounding_with_selection] instead. `TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. a `GtkIMContext` location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai where only some sequences of characters are allowed. This function is implemented by emitting the [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method; in response to this signal, a widget should provide as much context as is available, up to an entire paragraph, by calling [method@Gtk.IMContext.set_surrounding_with_selection]. Note that there is no obligation for a widget to respond to the `::retrieve-surrounding` signal, so input methods must be prepared to function without context. `TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. a `GtkIMContext` location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. location to store byte index of the selection bound within @text Default handler of the [signal@Gtk.IMContext::invalid-composition] signal. Since: 4.22 Default handler of the [signal@Gtk.IMContext::preedit-changed] signal. Default handler of the [signal@Gtk.IMContext::preedit-end] signal. Default handler of the [signal@Gtk.IMContext::preedit-start] signal. Notify the input method that a change such as a change in cursor position has been made. This will typically cause the input method to clear the preedit state. a `GtkIMContext` Default handler of the [signal@Gtk.IMContext::retrieve-surrounding] signal. Set the client widget for the input context. This is the `GtkWidget` holding the input focus. This widget is used in order to correctly position status windows, and may also be used for purposes internal to the input method. a `GtkIMContext` the client widget. This may be %NULL to indicate that the previous client widget no longer exists. Notify the input method that a change in cursor position has been made. The location is relative to the client widget. a `GtkIMContext` new location Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the [signal@Gtk.IMContext::retrieve-surrounding] signal, and will likely have no effect if called at other times. Use [method@Gtk.IMContext.set_surrounding_with_selection] instead a `GtkIMContext` text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the [signal@Gtk.IMContext::retrieve_surrounding] signal, and will likely have no effect if called at other times. a `GtkIMContext` text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text the byte index of the selection bound within @text Sets whether the IM context should use the preedit string to display feedback. If @use_preedit is %FALSE (default is %TRUE), then the IM context may use some other method to display feedback, such as displaying it in a child of the root window. a `GtkIMContext` whether the IM context should use the preedit string. Requests the platform to show an on-screen keyboard for user input. This method will return %TRUE if this request was actually performed to the platform, other environmental factors may result in an on-screen keyboard effectively not showing up. %TRUE if an on-screen keyboard could be requested to the platform. a `GtkIMContext` a [class@Gdk.Event] Asks the widget that the input context is attached to delete characters around the cursor position by emitting the `::delete_surrounding` signal. Note that @offset and @n_chars are in characters not in bytes which differs from the usage other places in `GtkIMContext`. In order to use this function, you should first call [method@Gtk.IMContext.get_surrounding] to get the current context, and call this function immediately afterwards to make sure that you know what you are deleting. You should also account for the fact that even if the signal was handled, the input context might not have deleted all the characters that were requested to be deleted. This function is used by an input method that wants to make substitutions in the existing text in response to new input. It is not useful for applications. %TRUE if the signal was handled. a `GtkIMContext` offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. Allow an input method to forward key press and release events to another input method without necessarily having a `GdkEvent` available. %TRUE if the input method handled the key event. a `GtkIMContext` whether to forward a key press or release event the surface the event is for the device that the event is for the timestamp for the event the keycode for the event modifier state for the event the active keyboard group for the event Allow an input method to internally handle key press and release events. If this function returns %TRUE, then no further processing should be done for this key event. %TRUE if the input method handled the key event. a `GtkIMContext` the key event Notify the input method that the widget to which this input context corresponds has gained focus. The input method may, for example, change the displayed feedback to reflect this change. a `GtkIMContext` Notify the input method that the widget to which this input context corresponds has lost focus. The input method may, for example, change the displayed feedback or reset the contexts state to reflect this change. a `GtkIMContext` Retrieve the current preedit string for the input context, and a list of attributes to apply to the string. This string should be displayed inserted at the insertion point. a `GtkIMContext` location to store the retrieved string. The string retrieved must be freed with g_free(). location to store the retrieved attribute list. When you are done with this list, you must unreference it with [method@Pango.AttrList.unref]. location to store position of cursor (in characters) within the preedit string. Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai where only some sequences of characters are allowed. This function is implemented by emitting the [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method; in response to this signal, a widget should provide as much context as is available, up to an entire paragraph, by calling [method@Gtk.IMContext.set_surrounding]. Note that there is no obligation for a widget to respond to the `::retrieve-surrounding` signal, so input methods must be prepared to function without context. Use [method@Gtk.IMContext.get_surrounding_with_selection] instead. `TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. a `GtkIMContext` location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai where only some sequences of characters are allowed. This function is implemented by emitting the [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method; in response to this signal, a widget should provide as much context as is available, up to an entire paragraph, by calling [method@Gtk.IMContext.set_surrounding_with_selection]. Note that there is no obligation for a widget to respond to the `::retrieve-surrounding` signal, so input methods must be prepared to function without context. `TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. a `GtkIMContext` location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. location to store byte index of the selection bound within @text Notify the input method that a change such as a change in cursor position has been made. This will typically cause the input method to clear the preedit state. a `GtkIMContext` Set the client widget for the input context. This is the `GtkWidget` holding the input focus. This widget is used in order to correctly position status windows, and may also be used for purposes internal to the input method. a `GtkIMContext` the client widget. This may be %NULL to indicate that the previous client widget no longer exists. Notify the input method that a change in cursor position has been made. The location is relative to the client widget. a `GtkIMContext` new location Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the [signal@Gtk.IMContext::retrieve-surrounding] signal, and will likely have no effect if called at other times. Use [method@Gtk.IMContext.set_surrounding_with_selection] instead a `GtkIMContext` text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the [signal@Gtk.IMContext::retrieve_surrounding] signal, and will likely have no effect if called at other times. a `GtkIMContext` text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text the byte index of the selection bound within @text Sets whether the IM context should use the preedit string to display feedback. If @use_preedit is %FALSE (default is %TRUE), then the IM context may use some other method to display feedback, such as displaying it in a child of the root window. a `GtkIMContext` whether the IM context should use the preedit string. Additional hints that allow input methods to fine-tune their behaviour. The purpose of the text field that the `GtkIMContext is connected to. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. The ::commit signal is emitted when a complete input sequence has been entered by the user. If the commit comes after a preediting sequence, the ::commit signal is emitted after ::preedit-end. This can be a single character immediately after a key press or the final result of preediting. the completed character(s) entered by the user The ::delete-surrounding signal is emitted when the input method needs to delete all or part of the context surrounding the cursor. %TRUE if the signal was handled. the character offset from the cursor position of the text to be deleted. A negative value indicates a position before the cursor. the number of characters to be deleted Emitted when the filtered keys do not compose to a single valid character. true if the IM context avoid beeping on invalid composition the completed character(s) entered by the user The ::preedit-changed signal is emitted whenever the preedit sequence currently being entered has changed. It is also emitted at the end of a preedit sequence, in which case [method@Gtk.IMContext.get_preedit_string] returns the empty string. The ::preedit-end signal is emitted when a preediting sequence has been completed or canceled. The ::preedit-start signal is emitted when a new preediting sequence starts. The ::retrieve-surrounding signal is emitted when the input method requires the context surrounding the cursor. The callback should set the input method surrounding context by calling the [method@Gtk.IMContext.set_surrounding] method. %TRUE if the signal was handled. Default handler of the [signal@Gtk.IMContext::preedit-start] signal. Default handler of the [signal@Gtk.IMContext::preedit-end] signal. Default handler of the [signal@Gtk.IMContext::preedit-changed] signal. Default handler of the [signal@Gtk.IMContext::commit] signal. Default handler of the [signal@Gtk.IMContext::retrieve-surrounding] signal. Default handler of the [signal@Gtk.IMContext::delete-surrounding] signal. %TRUE if the signal was handled. a `GtkIMContext` offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. Called via [method@Gtk.IMContext.set_client_widget] when the input window where the entered text will appear changes. Override this to keep track of the current input window, for instance for the purpose of positioning a status display of your input method. a `GtkIMContext` the client widget. This may be %NULL to indicate that the previous client widget no longer exists. Called via [method@Gtk.IMContext.get_preedit_string] to retrieve the text currently being preedited for display at the cursor position. Any input method which composes complex characters or any other compositions from multiple sequential key presses should override this method to provide feedback. a `GtkIMContext` location to store the retrieved string. The string retrieved must be freed with g_free(). location to store the retrieved attribute list. When you are done with this list, you must unreference it with [method@Pango.AttrList.unref]. location to store position of cursor (in characters) within the preedit string. Called via [method@Gtk.IMContext.filter_keypress] on every key press or release event. Every non-trivial input method needs to override this in order to implement the mapping from key events to text. A return value of %TRUE indicates to the caller that the event was consumed by the input method. In that case, the [signal@Gtk.IMContext::commit] signal should be emitted upon completion of a key sequence to pass the resulting text back to the input widget. Alternatively, %FALSE may be returned to indicate that the event wasn’t handled by the input method. If a builtin mapping exists for the key, it is used to produce a character. %TRUE if the input method handled the key event. a `GtkIMContext` the key event Called via [method@Gtk.IMContext.focus_in] when the input widget has gained focus. May be overridden to keep track of the current focus. a `GtkIMContext` Called via [method@Gtk.IMContext.focus_out] when the input widget has lost focus. May be overridden to keep track of the current focus. a `GtkIMContext` Called via [method@Gtk.IMContext.reset] to signal a change such as a change in cursor position. An input method that implements preediting should override this method to clear the preedit state on reset. a `GtkIMContext` Called via [method@Gtk.IMContext.set_cursor_location] to inform the input method of the current cursor location relative to the client window. May be overridden to implement the display of popup windows at the cursor position. a `GtkIMContext` new location Called via [method@Gtk.IMContext.set_use_preedit] to control the use of the preedit string. Override this to display feedback by some other means if turned off. a `GtkIMContext` whether the IM context should use the preedit string. Called via [method@Gtk.IMContext.set_surrounding] in response to [signal@Gtk.IMContext::retrieve-surrounding] signal to update the input method’s idea of the context around the cursor. It is not necessary to override this method even with input methods which implement context-dependent behavior. The base implementation is sufficient for [method@Gtk.IMContext.get_surrounding] to work. a `GtkIMContext` text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. Called via [method@Gtk.IMContext.get_surrounding] to update the context around the cursor location. It is not necessary to override this method even with input methods which implement context-dependent behavior. The base implementation emits [signal@Gtk.IMContext::retrieve-surrounding] and records the context received by the subsequent invocation of [vfunc@Gtk.IMContext.get_surrounding]. `TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. a `GtkIMContext` location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. Called via [method@Gtk.IMContext.set_surrounding_with_selection] in response to the [signal@Gtk.IMContext::retrieve-surrounding] signal to update the input method’s idea of the context around the cursor. It is not necessary to override this method even with input methods which implement context-dependent behavior. The base implementation is sufficient for [method@Gtk.IMContext.get_surrounding] to work. a `GtkIMContext` text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text the byte index of the selection bound within @text Called via [method@Gtk.IMContext.get_surrounding_with_selection] to update the context around the cursor location. It is not necessary to override this method even with input methods which implement context-dependent behavior. The base implementation emits [signal@Gtk.IMContext::retrieve-surrounding] and records the context received by the subsequent invocation of [vfunc@Gtk.IMContext.get_surrounding]. `TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. a `GtkIMContext` location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. location to store byte index of the selection bound within @text Default handler of the [signal@Gtk.IMContext::invalid-composition] signal. Since: 4.22 Supports compose sequences, dead keys and numeric Unicode input. ## Compose sequences `GtkIMContextSimple` reads compose sequences from the first of the following files that is found: ~/.config/gtk-4.0/Compose, ~/.XCompose, /usr/share/X11/locale/$locale/Compose (for locales that have a nontrivial Compose file). A subset of the file syntax described in the Compose(5) manual page is supported. Additionally, `include "%L"` loads GTK’s built-in table of compose sequences rather than the locale-specific one from X11. If none of these files is found, `GtkIMContextSimple` uses a built-in table of compose sequences that is derived from the X11 Compose files. Note that compose sequences typically start with the Compose_key, which is often not available as a dedicated key on keyboards. Keyboard layouts may map this keysym to other keys, such as the right Control key. ## Unicode characters `GtkIMContextSimple` also supports numeric entry of Unicode characters by typing <kbd>Ctrl</kbd>-<kbd>Shift</kbd>-<kbd>u</kbd>, followed by a hexadecimal Unicode codepoint. For example, Ctrl-Shift-u 1 2 3 Enter yields U+0123 LATIN SMALL LETTER G WITH CEDILLA, i.e. ģ. ## Dead keys `GtkIMContextSimple` supports dead keys. For example, typing dead_acute a yields U+00E! LATIN SMALL LETTER_A WITH ACUTE, i.e. á. Note that this depends on the keyboard layout including dead keys. Creates a new `GtkIMContextSimple`. a new `GtkIMContextSimple` Adds an additional table from the X11 compose file. A `GtkIMContextSimple` The path of compose file Adds an additional table to search to the input context. Each row of the table consists of @max_seq_len key symbols followed by two #guint16 interpreted as the high and low words of a #gunicode value. Tables are searched starting from the last added. The table must be sorted in dictionary order on the numeric value of the key symbol fields. (Values beyond the length of the sequence should be zero.) Use gtk_im_context_simple_add_compose_file() A `GtkIMContextSimple` the table Maximum length of a sequence in the table number of sequences in the table Supports switching between multiple input methods. Text widgets such as `GtkText` or `GtkTextView` use a `GtkIMMultiContext` to implement their `im-module` property for switching between different input methods. Creates a new `GtkIMMulticontext`. a new `GtkIMMulticontext`. Gets the id of the currently active delegate of the @context. the id of the currently active delegate a `GtkIMMulticontext` Sets the context id for @context. This causes the currently active delegate of @context to be replaced by the delegate corresponding to the new context id. Setting this to a non-%NULL value overrides the system-wide IM module setting. See the [property@Gtk.Settings:gtk-im-module] property. a `GtkIMMulticontext` the id to use The default name of the extension point. Constant to return from a signal handler for the ::input signal in case of conversion failure. See [signal@Gtk.SpinButton::input]. Like [func@get_interface_age], but from the headers used at application compile time, rather than from the library linked against at application run time. The value used to refer to a guaranteed invalid position in a `GListModel`. This value may be returned from some functions, others may accept it as input. Its interpretation may differ for different functions. Refer to each function's documentation for if this value is allowed and what it does. Used to specify options for gtk_icon_theme_lookup_icon(). Perform a regular lookup. Try to always load regular icons, even when symbolic icon names are given Try to always load symbolic icons, even when regular icon names are given Starts loading the texture in the background so it is ready when later needed. Contains information found when looking up an icon in `GtkIconTheme` or loading it from a file. `GtkIconPaintable` implements `GdkPaintable` and `GtkSymbolicPaintable`. Creates a `GtkIconPaintable` for a file with a given size and scale. The icon can then be rendered by using it as a `GdkPaintable`. a `GtkIconPaintable` containing for the icon. Unref with g_object_unref() a `GFile` desired icon size, in application pixels the desired scale Gets the `GFile` that was used to load the icon. Returns %NULL if the icon was not loaded from a file. the `GFile` for the icon a `GtkIconPaintable` Get the icon name being used for this icon. When an icon looked up in the icon theme was not available, the icon theme may use fallback icons - either those specified to gtk_icon_theme_lookup_icon() or the always-available "image-missing". The icon chosen is returned by this function. If the icon was created without an icon theme, this function returns %NULL. the themed icon-name for the icon, or %NULL if its not a themed icon. a `GtkIconPaintable` Checks if the icon is symbolic or not. This currently uses only the file name and not the file contents for determining this. This behaviour may change in the future. true if the icon is symbolic, false otherwise an icon paintable The file representing the icon, if any. The icon name that was chosen during lookup. Whether the icon is symbolic or not. Built-in icon sizes. Icon sizes default to being inherited. Where they cannot be inherited, text size is the default. All widgets which use `GtkIconSize` set the normal-icons or large-icons style classes correspondingly, and let themes determine the actual size to be used with the `-gtk-icon-size` CSS property. Keep the size of the parent element Size similar to text size Large size, for example in an icon view Loads themed icons. The main reason for using a name rather than simply providing a filename is to allow different icons to be used depending on what “icon theme” is selected by the user. The operation of icon themes on Linux and Unix follows the [Icon Theme Specification](http://www.freedesktop.org/Standards/icon-theme-spec) There is a fallback icon theme, named `hicolor`, where applications should install their icons, but additional icon themes can be installed as operating system vendors and users choose. In many cases, named themes are used indirectly, via [class@Gtk.Image] rather than directly, but looking up icons directly is also simple. The `GtkIconTheme` object acts as a database of all the icons in the current theme. You can create new `GtkIconTheme` objects, but it’s much more efficient to use the standard icon theme of the `GtkWidget` so that the icon information is shared with other people looking up icons. ```c GtkIconTheme *icon_theme; GtkIconPaintable *icon; GdkPaintable *paintable; icon_theme = gtk_icon_theme_get_for_display (gtk_widget_get_display (my_widget)); icon = gtk_icon_theme_lookup_icon (icon_theme, "my-icon-name", // icon name 48, // icon size 1, // scale 0, // flags); paintable = GDK_PAINTABLE (icon); // Use the paintable g_object_unref (icon); ``` Creates a new icon theme object. Icon theme objects are used to lookup up an icon by name in a particular icon theme. Usually, you’ll want to use [func@Gtk.IconTheme.get_for_display] rather than creating a new icon theme object for scratch. the newly created `GtkIconTheme` object. Gets the icon theme object associated with @display. If this function has not previously been called for the given display, a new icon theme object will be created and associated with the display. Icon theme objects are fairly expensive to create, so using this function is usually a better choice than calling [ctor@Gtk.IconTheme.new] and setting the display yourself; by using this function a single icon theme object will be shared between users. A unique `GtkIconTheme` associated with the given display. This icon theme is associated with the display and can be used as long as the display is open. Do not ref or unref it. a `GdkDisplay` Adds a resource path that will be looked at when looking for icons, similar to search paths. See [method@Gtk.IconTheme.set_resource_path]. This function should be used to make application-specific icons available as part of the icon theme. a `GtkIconTheme` a resource path Appends a directory to the search path. See [method@Gtk.IconTheme.set_search_path]. a `GtkIconTheme` directory name to append to the icon path Returns the display that the `GtkIconTheme` object was created for. the display of @icon_theme a `GtkIconTheme` Lists the names of icons in the current icon theme. a string array holding the names of all the icons in the theme. You must free the array using g_strfreev(). a `GtkIconTheme` Returns an array of integers describing the sizes at which the icon is available without scaling. A size of -1 means that the icon is available in a scalable format. The array is zero-terminated. A newly allocated array describing the sizes at which the icon is available. The array should be freed with g_free() when it is no longer needed. a `GtkIconTheme` the name of an icon Gets the current resource path. See [method@Gtk.IconTheme.set_resource_path]. A list of resource paths a `GtkIconTheme` Gets the current search path. See [method@Gtk.IconTheme.set_search_path]. a list of icon theme path directories a `GtkIconTheme` Gets the current icon theme name. the current icon theme name, a `GtkIconTheme` Checks whether an icon theme includes an icon for a particular `GIcon`. %TRUE if @self includes an icon for @gicon a `GtkIconTheme` a `GIcon` Checks whether an icon theme includes an icon for a particular name. %TRUE if @self includes an icon for @icon_name. a `GtkIconTheme` the name of an icon Looks up a icon for a desired size and window scale. The icon can then be rendered by using it as a `GdkPaintable`, or you can get information such as the filename and size. a `GtkIconPaintable` containing information about the icon. Unref with g_object_unref() a `GtkIconTheme` the `GIcon` to look up desired icon size, in application pixels the desired scale text direction the icon will be displayed in flags modifying the behavior of the icon lookup Looks up a named icon for a desired size and window scale, returning a `GtkIconPaintable`. The icon can then be rendered by using it as a `GdkPaintable`, or you can get information such as the filename and size. If the available @icon_name is not available and @fallbacks are provided, they will be tried in order. If no matching icon is found, then a paintable that renders the "missing icon" icon is returned. If you need to do something else for missing icons you need to use [method@Gtk.IconTheme.has_icon]. Note that you probably want to listen for icon theme changes and update the icon. This is usually done by overriding the GtkWidgetClass.css-changed() function. a `GtkIconPaintable` object containing the icon. a `GtkIconTheme` the name of the icon to lookup fallback names desired icon size, in application pixels the window scale this will be displayed on text direction the icon will be displayed in flags modifying the behavior of the icon lookup Sets the resource paths that will be looked at when looking for icons, similar to search paths. The resources are considered as part of the hicolor icon theme and must be located in subdirectories that are defined in the hicolor icon theme, such as `@path/16x16/actions/run.png` or `@path/scalable/actions/run.svg`. Icons that are directly placed in the resource path instead of a subdirectory are also considered as ultimate fallback, but they are treated like unthemed icons. a `GtkIconTheme` NULL-terminated array of resource paths that are searched for icons Sets the search path for the icon theme object. When looking for an icon theme, GTK will search for a subdirectory of one or more of the directories in @path with the same name as the icon theme containing an index.theme file. (Themes from multiple of the path elements are combined to allow themes to be extended by adding icons in the user’s home directory.) In addition if an icon found isn’t found either in the current icon theme or the default icon theme, and an image file with the right name is found directly in one of the elements of @path, then that image will be used for the icon name. (This is legacy feature, and new icons should be put into the fallback icon theme, which is called hicolor, rather than directly on the icon path.) a `GtkIconTheme` NULL-terminated array of directories that are searched for icon themes Sets the name of the icon theme that the `GtkIconTheme` object uses overriding system configuration. This function cannot be called on the icon theme objects returned from [func@Gtk.IconTheme.get_for_display]. a `GtkIconTheme` name of icon theme to use instead of configured theme, or %NULL to unset a previously set custom theme The display that this icon theme object is attached to. The icon names that are supported by the icon theme. Resource paths that will be looked at when looking for icons, similar to search paths. The resources are considered as part of the hicolor icon theme and must be located in subdirectories that are defined in the hicolor icon theme, such as `@path/16x16/actions/run.png`. Icons that are directly placed in the resource path instead of a subdirectory are also considered as ultimate fallback. The search path for this icon theme. When looking for icons, GTK will search for a subdirectory of one or more of the directories in the search path with the same name as the icon theme containing an index.theme file. (Themes from multiple of the path elements are combined to allow themes to be extended by adding icons in the user’s home directory.) The name of the icon theme that is being used. Unless set to a different value, this will be the value of the `GtkSettings:gtk-icon-theme-name` property of the `GtkSettings` object associated to the display of the icontheme object. Emitted when the icon theme changes. This can happen because current icon theme is switched or because GTK detects that a change has occurred in the contents of the current icon theme. Error codes for `GtkIconTheme` operations. The icon specified does not exist in the theme An unspecified error occurred. Registers an error quark for [class@Gtk.IconTheme] errors. the error quark `GtkIconView` is a widget which displays data in a grid of icons. <picture> <source srcset="icon-view-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkIconView" src="icon-view.png"> </picture> `GtkIconView` provides an alternative view on a `GtkTreeModel`. It displays the model as a grid of icons with labels. Like [class@Gtk.TreeView], it allows to select one or multiple items (depending on the selection mode, see [method@Gtk.IconView.set_selection_mode]). In addition to selection with the arrow keys, `GtkIconView` supports rubberband selection, which is controlled by dragging the pointer. Note that if the tree model is backed by an actual tree store (as opposed to a flat list where the mapping to icons is obvious), `GtkIconView` will only display the first level of the tree and ignore the tree’s branches. ## CSS nodes ``` iconview.view ╰── [rubberband] ``` `GtkIconView` has a single CSS node with name iconview and style class .view. For rubberband selection, a subnode with name rubberband is used. Use [class@Gtk.GridView] instead Creates a new `GtkIconView` widget Use [class@Gtk.GridView] instead A newly created `GtkIconView` widget Creates a new `GtkIconView` widget using the specified @area to layout cells inside the icons. Use [class@Gtk.GridView] instead A newly created `GtkIconView` widget the `GtkCellArea` to use to layout cells Creates a new `GtkIconView` widget with the model @model. Use [class@Gtk.GridView] instead A newly created `GtkIconView` widget. The model. Creates a `GdkPaintable` representation of the item at @path. This image is used for a drag icon. Use [class@Gtk.GridView] instead a newly-allocated `GdkPaintable` of the drag icon. a `GtkIconView` a `GtkTreePath` in @icon_view Turns @icon_view into a drop destination for automatic DND. Calling this method sets `GtkIconView`:reorderable to %FALSE. Use [class@Gtk.GridView] instead a `GtkIconView` the formats that the drag will support the bitmask of possible actions for a drag to this widget Turns @icon_view into a drag source for automatic DND. Calling this method sets `GtkIconView`:reorderable to %FALSE. Use [class@Gtk.GridView] instead a `GtkIconView` Mask of allowed buttons to start drag the formats that the drag will support the bitmask of possible actions for a drag from this widget Gets the setting set by gtk_icon_view_set_activate_on_single_click(). Use [class@Gtk.GridView] instead %TRUE if item-activated will be emitted on a single click a `GtkIconView` Fills the bounding rectangle in widget coordinates for the cell specified by @path and @cell. If @cell is %NULL the main cell area is used. This function is only valid if @icon_view is realized. Use [class@Gtk.GridView] instead %FALSE if there is no such item, %TRUE otherwise a `GtkIconView` a `GtkTreePath` a `GtkCellRenderer` rectangle to fill with cell rect Returns the value of the ::column-spacing property. Use [class@Gtk.GridView] instead the space between columns a `GtkIconView` Returns the value of the ::columns property. Use [class@Gtk.GridView] instead the number of columns, or -1 a `GtkIconView` Fills in @path and @cell with the current cursor path and cell. If the cursor isn’t currently set, then *@path will be %NULL. If no cell currently has focus, then *@cell will be %NULL. The returned `GtkTreePath` must be freed with gtk_tree_path_free(). Use [class@Gtk.GridView] instead %TRUE if the cursor is set. A `GtkIconView` Return location for the current cursor path Return location the current focus cell Determines the destination item for a given position. Use [class@Gtk.GridView] instead whether there is an item at the given position. a `GtkIconView` the position to determine the destination item for the position to determine the destination item for Return location for the path of the item Return location for the drop position Gets information about the item that is highlighted for feedback. Use [class@Gtk.GridView] instead a `GtkIconView` Return location for the path of the highlighted item Return location for the drop position Gets the path and cell for the icon at the given position. Use [class@Gtk.GridView] instead %TRUE if an item exists at the specified position A `GtkIconView`. The x position to be identified The y position to be identified Return location for the path Return location for the renderer responsible for the cell at (@x, @y) Gets the column in which the item @path is currently displayed. Column numbers start at 0. Use [class@Gtk.GridView] instead The column in which the item is displayed a `GtkIconView` the `GtkTreePath` of the item Returns the value of the ::item-orientation property which determines whether the labels are drawn beside the icons instead of below. Use [class@Gtk.GridView] instead the relative position of texts and icons a `GtkIconView` Returns the value of the ::item-padding property. Use [class@Gtk.GridView] instead the padding around items a `GtkIconView` Gets the row in which the item @path is currently displayed. Row numbers start at 0. Use [class@Gtk.GridView] instead The row in which the item is displayed a `GtkIconView` the `GtkTreePath` of the item Returns the value of the ::item-width property. Use [class@Gtk.GridView] instead the width of a single item, or -1 a `GtkIconView` Returns the value of the ::margin property. Use [class@Gtk.GridView] instead the space at the borders a `GtkIconView` Returns the column with markup text for @icon_view. Use [class@Gtk.GridView] instead the markup column, or -1 if it’s unset. A `GtkIconView`. Returns the model the `GtkIconView` is based on. Returns %NULL if the model is unset. Use [class@Gtk.GridView] instead The currently used `GtkTreeModel` a `GtkIconView` Gets the path for the icon at the given position. Use [class@Gtk.GridView] instead The `GtkTreePath` corresponding to the icon or %NULL if no icon exists at that position. A `GtkIconView`. The x position to be identified The y position to be identified Returns the column with pixbufs for @icon_view. Use [class@Gtk.GridView] instead the pixbuf column, or -1 if it’s unset. A `GtkIconView`. Retrieves whether the user can reorder the list via drag-and-drop. See gtk_icon_view_set_reorderable(). Use [class@Gtk.GridView] instead %TRUE if the list can be reordered. a `GtkIconView` Returns the value of the ::row-spacing property. Use [class@Gtk.GridView] instead the space between rows a `GtkIconView` Creates a list of paths of all selected items. Additionally, if you are planning on modifying the model after calling this function, you may want to convert the returned list into a list of `GtkTreeRowReferences`. To do this, you can use gtk_tree_row_reference_new(). To free the return value, use `g_list_free_full`: ```c GtkWidget *icon_view = gtk_icon_view_new (); // Use icon_view GList *list = gtk_icon_view_get_selected_items (GTK_ICON_VIEW (icon_view)); // use list g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); ``` Use [class@Gtk.GridView] instead A `GList` containing a `GtkTreePath` for each selected row. A `GtkIconView`. Gets the selection mode of the @icon_view. Use [class@Gtk.GridView] instead the current selection mode A `GtkIconView`. Returns the value of the ::spacing property. Use [class@Gtk.GridView] instead the space between cells a `GtkIconView` Returns the column with text for @icon_view. Use [class@Gtk.GridView] instead the text column, or -1 if it’s unset. A `GtkIconView`. Returns the column of @icon_view’s model which is being used for displaying tooltips on @icon_view’s rows. Use [class@Gtk.GridView] instead the index of the tooltip column that is currently being used, or -1 if this is disabled. a `GtkIconView` This function is supposed to be used in a `GtkWidget::query-tooltip` signal handler for `GtkIconView`. The @x, @y and @keyboard_tip values which are received in the signal handler, should be passed to this function without modification. The return value indicates whether there is an icon view item at the given coordinates (%TRUE) or not (%FALSE) for mouse tooltips. For keyboard tooltips the item returned will be the cursor item. When %TRUE, then any of @model, @path and @iter which have been provided will be set to point to that row and the corresponding model. Use [class@Gtk.GridView] instead whether or not the given tooltip context points to an item an `GtkIconView` the x coordinate (relative to widget coordinates) the y coordinate (relative to widget coordinates) whether this is a keyboard tooltip or not a pointer to receive a `GtkTreeModel` a pointer to receive a `GtkTreePath` a pointer to receive a `GtkTreeIter` Sets @start_path and @end_path to be the first and last visible path. Note that there may be invisible paths in between. Both paths should be freed with gtk_tree_path_free() after use. Use [class@Gtk.GridView] instead %TRUE, if valid paths were placed in @start_path and @end_path A `GtkIconView` Return location for start of region Return location for end of region Activates the item determined by @path. Use [class@Gtk.GridView] instead A `GtkIconView` The `GtkTreePath` to be activated Returns %TRUE if the icon pointed to by @path is currently selected. If @path does not point to a valid location, %FALSE is returned. Use [class@Gtk.GridView] instead %TRUE if @path is selected. A `GtkIconView`. A `GtkTreePath` to check selection on. Moves the alignments of @icon_view to the position specified by @path. @row_align determines where the row is placed, and @col_align determines where @column is placed. Both are expected to be between 0.0 and 1.0. 0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 means center. If @use_align is %FALSE, then the alignment arguments are ignored, and the tree does the minimum amount of work to scroll the item onto the screen. This means that the item will be scrolled to the edge closest to its current position. If the item is currently visible on the screen, nothing is done. This function only works if the model is set, and @path is a valid row on the model. If the model changes before the @icon_view is realized, the centered path will be modified to reflect this change. Use [class@Gtk.GridView] instead A `GtkIconView` The path of the item to move to. whether to use alignment arguments, or %FALSE. The vertical alignment of the item specified by @path. The horizontal alignment of the item specified by @path. Selects all the icons. @icon_view must has its selection mode set to %GTK_SELECTION_MULTIPLE. Use [class@Gtk.GridView] instead A `GtkIconView`. Selects the row at @path. Use [class@Gtk.GridView] instead A `GtkIconView`. The `GtkTreePath` to be selected. Calls a function for each selected icon. Note that the model or selection cannot be modified from within this function. Use [class@Gtk.GridView] instead A `GtkIconView`. The function to call for each selected icon. User data to pass to the function. Causes the `GtkIconView`::item-activated signal to be emitted on a single click instead of a double click. Use [class@Gtk.GridView] instead a `GtkIconView` %TRUE to emit item-activated on a single click Sets the ::column-spacing property which specifies the space which is inserted between the columns of the icon view. Use [class@Gtk.GridView] instead a `GtkIconView` the column spacing Sets the ::columns property which determines in how many columns the icons are arranged. If @columns is -1, the number of columns will be chosen automatically to fill the available area. Use [class@Gtk.GridView] instead a `GtkIconView` the number of columns Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular item. If @cell is not %NULL, then focus is given to the cell specified by it. Additionally, if @start_editing is %TRUE, then editing should be started in the specified cell. This function is often followed by `gtk_widget_grab_focus (icon_view)` in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized. Use [class@Gtk.GridView] instead A `GtkIconView` A `GtkTreePath` One of the cell renderers of @icon_view %TRUE if the specified cell should start being edited. Sets the item that is highlighted for feedback. Use [class@Gtk.GridView] instead a `GtkIconView` The path of the item to highlight Specifies where to drop, relative to the item Sets the ::item-orientation property which determines whether the labels are drawn beside the icons instead of below. Use [class@Gtk.GridView] instead a `GtkIconView` the relative position of texts and icons Sets the `GtkIconView`:item-padding property which specifies the padding around each of the icon view’s items. Use [class@Gtk.GridView] instead a `GtkIconView` the item padding Sets the ::item-width property which specifies the width to use for each item. If it is set to -1, the icon view will automatically determine a suitable item size. Use [class@Gtk.GridView] instead a `GtkIconView` the width for each item Sets the ::margin property which specifies the space which is inserted at the top, bottom, left and right of the icon view. Use [class@Gtk.GridView] instead a `GtkIconView` the margin Sets the column with markup information for @icon_view to be @column. The markup column must be of type `G_TYPE_STRING`. If the markup column is set to something, it overrides the text column set by gtk_icon_view_set_text_column(). Use [class@Gtk.GridView] instead A `GtkIconView`. A column in the currently used model, or -1 to display no text Sets the model for a `GtkIconView`. If the @icon_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. Use [class@Gtk.GridView] instead A `GtkIconView`. The model. Sets the column with pixbufs for @icon_view to be @column. The pixbuf column must be of type `GDK_TYPE_PIXBUF` Use [class@Gtk.GridView] instead A `GtkIconView`. A column in the currently used model, or -1 to disable This function is a convenience function to allow you to reorder models that support the `GtkTreeDragSourceIface` and the `GtkTreeDragDestIface`. Both `GtkTreeStore` and `GtkListStore` support these. If @reorderable is %TRUE, then the user can reorder the model by dragging and dropping rows. The developer can listen to these changes by connecting to the model's row_inserted and row_deleted signals. The reordering is implemented by setting up the icon view as a drag source and destination. Therefore, drag and drop can not be used in a reorderable view for any other purpose. This function does not give you any degree of control over the order -- any reordering is allowed. If more control is needed, you should probably handle drag and drop manually. Use [class@Gtk.GridView] instead A `GtkIconView`. %TRUE, if the list of items can be reordered. Sets the ::row-spacing property which specifies the space which is inserted between the rows of the icon view. Use [class@Gtk.GridView] instead a `GtkIconView` the row spacing Sets the selection mode of the @icon_view. Use [class@Gtk.GridView] instead A `GtkIconView`. The selection mode Sets the ::spacing property which specifies the space which is inserted between the cells (i.e. the icon and the text) of an item. Use [class@Gtk.GridView] instead a `GtkIconView` the spacing Sets the column with text for @icon_view to be @column. The text column must be of type `G_TYPE_STRING`. Use [class@Gtk.GridView] instead A `GtkIconView`. A column in the currently used model, or -1 to display no text Sets the tip area of @tooltip to the area which @cell occupies in the item pointed to by @path. See also gtk_tooltip_set_tip_area(). See also gtk_icon_view_set_tooltip_column() for a simpler alternative. Use [class@Gtk.GridView] instead a `GtkIconView` a `GtkTooltip` a `GtkTreePath` a `GtkCellRenderer` If you only plan to have simple (text-only) tooltips on full items, you can use this function to have `GtkIconView` handle these automatically for you. @column should be set to the column in @icon_view’s model containing the tooltip texts, or -1 to disable this feature. When enabled, `GtkWidget:has-tooltip` will be set to %TRUE and @icon_view will connect a `GtkWidget::query-tooltip` signal handler. Note that the signal handler sets the text with gtk_tooltip_set_markup(), so &, <, etc have to be escaped in the text. Use [class@Gtk.GridView] instead a `GtkIconView` an integer, which is a valid column number for @icon_view’s model Sets the tip area of @tooltip to be the area covered by the item at @path. See also gtk_icon_view_set_tooltip_column() for a simpler alternative. See also gtk_tooltip_set_tip_area(). Use [class@Gtk.GridView] instead a `GtkIconView` a `GtkTooltip` a `GtkTreePath` Unselects all the icons. Use [class@Gtk.GridView] instead A `GtkIconView`. Unselects the row at @path. Use [class@Gtk.GridView] instead A `GtkIconView`. The `GtkTreePath` to be unselected. Undoes the effect of gtk_icon_view_enable_model_drag_dest(). Calling this method sets `GtkIconView`:reorderable to %FALSE. Use [class@Gtk.GridView] instead a `GtkIconView` Undoes the effect of gtk_icon_view_enable_model_drag_source(). Calling this method sets `GtkIconView`:reorderable to %FALSE. Use [class@Gtk.GridView] instead a `GtkIconView` The activate-on-single-click property specifies whether the "item-activated" signal will be emitted after a single click. The `GtkCellArea` used to layout cell renderers for this view. If no area is specified when creating the icon view with gtk_icon_view_new_with_area() a `GtkCellAreaBox` will be used. The column-spacing property specifies the space which is inserted between the columns of the icon view. The columns property contains the number of the columns in which the items should be displayed. If it is -1, the number of columns will be chosen automatically to fill the available area. The item-orientation property specifies how the cells (i.e. the icon and the text) of the item are positioned relative to each other. The item-padding property specifies the padding around each of the icon view's item. The item-width property specifies the width to use for each item. If it is set to -1, the icon view will automatically determine a suitable item size. The margin property specifies the space which is inserted at the edges of the icon view. The ::markup-column property contains the number of the model column containing markup information to be displayed. The markup column must be of type `G_TYPE_STRING`. If this property and the :text-column property are both set to column numbers, it overrides the text column. If both are set to -1, no texts are displayed. The model of the icon view. The ::pixbuf-column property contains the number of the model column containing the pixbufs which are displayed. The pixbuf column must be of type `GDK_TYPE_PIXBUF`. Setting this property to -1 turns off the display of pixbufs. The reorderable property specifies if the items can be reordered by DND. The row-spacing property specifies the space which is inserted between the rows of the icon view. The ::selection-mode property specifies the selection mode of icon view. If the mode is %GTK_SELECTION_MULTIPLE, rubberband selection is enabled, for the other modes, only keyboard selection is possible. The spacing property specifies the space which is inserted between the cells (i.e. the icon and the text) of an item. The ::text-column property contains the number of the model column containing the texts which are displayed. The text column must be of type `G_TYPE_STRING`. If this property and the :markup-column property are both set to -1, no texts are displayed. The column of the icon view model which is being used for displaying tooltips on it's rows. A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user activates the currently focused item. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control activation programmatically. The default bindings for this signal are Space, Return and Enter. whether the item was activated The ::item-activated signal is emitted when the method gtk_icon_view_item_activated() is called, when the user double clicks an item with the "activate-on-single-click" property set to %FALSE, or when the user single clicks an item when the "activate-on-single-click" property set to %TRUE. It is also emitted when a non-editable item is selected and one of the keys: Space, Return or Enter is pressed. the `GtkTreePath` for the activated item The ::move-cursor signal is a [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user initiates a cursor movement. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal include - Arrow keys which move by individual steps - Home/End keys which move to the first/last item - PageUp/PageDown which move by "pages" All of these will extend the selection when combined with the Shift modifier. whether the cursor was moved the granularity of the move, as a `GtkMovementStep` the number of @step units to move whether to extend the selection whether to modify the selection A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user selects all items. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control selection programmatically. The default binding for this signal is Ctrl-a. A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user selects the item that is currently focused. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control selection programmatically. There is no default binding for this signal. The ::selection-changed signal is emitted when the selection (i.e. the set of selected items) changes. A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user toggles whether the currently focused item is selected or not. The exact effect of this depend on the selection mode. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control selection programmatically. There is no default binding for this signal is Ctrl-Space. A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user unselects all items. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control selection programmatically. The default binding for this signal is Ctrl-Shift-a. An enum for determining where a dropped item goes. There is no replacement. no drop possible dropped item replaces the item dropped item is inserted to the left dropped item is inserted to the right dropped item is inserted above dropped item is inserted below A function used by gtk_icon_view_selected_foreach() to map all selected rows. It will be called on every selected row in the view. There is no replacement. a `GtkIconView` The `GtkTreePath` of a selected row user data Displays an image. <picture> <source srcset="image-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkImage" src="image.png"> </picture> Various kinds of object can be displayed as an image; most typically, you would load a `GdkTexture` from a file, using the convenience function [ctor@Gtk.Image.new_from_file], for instance: ```c GtkWidget *image = gtk_image_new_from_file ("myfile.png"); ``` If the file isn’t loaded successfully, the image will contain a “broken image” icon similar to that used in many web browsers. If you want to handle errors in loading the file yourself, for example by displaying an error message, then load the image with an image loading framework such as libglycin, then create the `GtkImage` with [ctor@Gtk.Image.new_from_paintable]. Sometimes an application will want to avoid depending on external data files, such as image files. See the documentation of `GResource` inside GIO, for details. In this case, [property@Gtk.Image:resource], [ctor@Gtk.Image.new_from_resource], and [method@Gtk.Image.set_from_resource] should be used. `GtkImage` displays its image as an icon, with a size that is determined by the application. See [class@Gtk.Picture] if you want to show an image at is actual size. ## CSS nodes `GtkImage` has a single CSS node with the name `image`. The style classes `.normal-icons` or `.large-icons` may appear, depending on the [property@Gtk.Image:icon-size] property. ## Accessibility `GtkImage` uses the [enum@Gtk.AccessibleRole.img] role. Creates a new empty `GtkImage` widget. a newly created `GtkImage` widget. Creates a new `GtkImage` displaying the file @filename. If the file isn’t found or can’t be loaded, the resulting `GtkImage` will display a “broken image” icon. This function never returns %NULL, it always returns a valid `GtkImage` widget. If you need to detect failures to load the file, use an image loading framework such as libglycin to load the file yourself, then create the `GtkImage` from the texture. The storage type (see [method@Gtk.Image.get_storage_type]) of the returned image is not defined, it will be whatever is appropriate for displaying the file. a new `GtkImage` a filename Creates a `GtkImage` displaying an icon from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately. a new `GtkImage` displaying the themed icon an icon Creates a `GtkImage` displaying an icon from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately. a new `GtkImage` displaying the themed icon an icon name Creates a new `GtkImage` displaying @paintable. The `GtkImage` does not assume a reference to the paintable; you still need to unref it if you own references. `GtkImage` will add its own reference rather than adopting yours. The `GtkImage` will track changes to the @paintable and update its size and contents in response to it. Note that paintables are still subject to the icon size that is set on the image. If you want to display a paintable at its intrinsic size, use [class@Gtk.Picture] instead. If @paintable is a [iface@Gtk.SymbolicPaintable], then it will be recolored with the symbolic palette from the theme. a new `GtkImage` a `GdkPaintable` Creates a new `GtkImage` displaying @pixbuf. The `GtkImage` does not assume a reference to the pixbuf; you still need to unref it if you own references. `GtkImage` will add its own reference rather than adopting yours. This is a helper for [ctor@Gtk.Image.new_from_paintable], and you can't get back the exact pixbuf once this is called, only a texture. Note that this function just creates an `GtkImage` from the pixbuf. The `GtkImage` created will not react to state changes. Should you want that, you should use [ctor@Gtk.Image.new_from_icon_name]. Use [ctor@Gtk.Image.new_from_paintable] and [ctor@Gdk.Texture.new_for_pixbuf] instead a new `GtkImage` a `GdkPixbuf` Creates a new `GtkImage` displaying the resource file @resource_path. If the file isn’t found or can’t be loaded, the resulting `GtkImage` will display a “broken image” icon. This function never returns %NULL, it always returns a valid `GtkImage` widget. If you need to detect failures to load the file, use an image loading framework such as libglycin to load the file yourself, then create the `GtkImage` from the texture. The storage type (see [method@Gtk.Image.get_storage_type]) of the returned image is not defined, it will be whatever is appropriate for displaying the file. a new `GtkImage` a resource path Resets the image to be empty. a `GtkImage` Gets the `GIcon` being displayed by the `GtkImage`. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_GICON (see [method@Gtk.Image.get_storage_type]). The caller of this function does not own a reference to the returned `GIcon`. a `GIcon` a `GtkImage` Gets the icon name and size being displayed by the `GtkImage`. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_ICON_NAME (see [method@Gtk.Image.get_storage_type]). The returned string is owned by the `GtkImage` and should not be freed. the icon name a `GtkImage` Gets the icon size used by the @image when rendering icons. the image size used by icons a `GtkImage` Gets the image `GdkPaintable` being displayed by the `GtkImage`. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_PAINTABLE (see [method@Gtk.Image.get_storage_type]). The caller of this function does not own a reference to the returned paintable. the displayed paintable a `GtkImage` Gets the pixel size used for named icons. the pixel size used for named icons. a `GtkImage` Gets the type of representation being used by the `GtkImage` to store image data. If the `GtkImage` has no image data, the return value will be %GTK_IMAGE_EMPTY. image representation being used a `GtkImage` Sets a `GtkImage` to show a file. See [ctor@Gtk.Image.new_from_file] for details. ::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a `GdkTexture`, and then use [method@Gtk.Image.set_from_paintable]. a `GtkImage` a filename Sets a `GtkImage` to show a `GIcon`. See [ctor@Gtk.Image.new_from_gicon] for details. a `GtkImage` an icon Sets a `GtkImage` to show a named icon. See [ctor@Gtk.Image.new_from_icon_name] for details. a `GtkImage` an icon name Sets a `GtkImage` to show a `GdkPaintable`. See [ctor@Gtk.Image.new_from_paintable] for details. a `GtkImage` a `GdkPaintable` Sets a `GtkImage` to show a `GdkPixbuf`. See [ctor@Gtk.Image.new_from_pixbuf] for details. Note: This is a helper for [method@Gtk.Image.set_from_paintable], and you can't get back the exact pixbuf once this is called, only a paintable. Use [method@Gtk.Image.set_from_paintable] instead a `GtkImage` a `GdkPixbuf` or `NULL` Sets a `GtkImage` to show a resource. See [ctor@Gtk.Image.new_from_resource] for details. a `GtkImage` a resource path Suggests an icon size to the theme for named icons. a `GtkImage` the new icon size Sets the pixel size to use for named icons. If the pixel size is set to a value != -1, it is used instead of the icon size set by [method@Gtk.Image.set_icon_size]. a `GtkImage` the new pixel size A path to the file to display. The `GIcon` displayed in the GtkImage. For themed icons, If the icon theme is changed, the image will be updated automatically. The name of the icon in the icon theme. If the icon theme is changed, the image will be updated automatically. The symbolic size to display icons at. The `GdkPaintable` to display. The size in pixels to display icons at. If set to a value != -1, this property overrides the [property@Gtk.Image:icon-size] property for images of type `GTK_IMAGE_ICON_NAME`. A path to a resource file to display. The representation being used for image data. Whether the icon displayed in the `GtkImage` will use standard icon names fallback. The value of this property is only relevant for images of type %GTK_IMAGE_ICON_NAME and %GTK_IMAGE_GICON. Describes the image data representation used by a [class@Gtk.Image]. If you want to get the image from the widget, you can only get the currently-stored representation; for instance, if the gtk_image_get_storage_type() returns %GTK_IMAGE_PAINTABLE, then you can call gtk_image_get_paintable(). For empty images, you can request any storage type (call any of the "get" functions), but they will all return %NULL values. there is no image displayed by the widget the widget contains a named icon the widget contains a `GIcon` the widget contains a `GdkPaintable` `GtkInfoBar` can be used to show messages to the user without a dialog. <picture> <source srcset="info-bar-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkInfoBar" src="info-bar.png"> </picture> It is often temporarily shown at the top or bottom of a document. In contrast to [class@Gtk.Dialog], which has an action area at the bottom, `GtkInfoBar` has an action area at the side. The API of `GtkInfoBar` is very similar to `GtkDialog`, allowing you to add buttons to the action area with [method@Gtk.InfoBar.add_button] or [ctor@Gtk.InfoBar.new_with_buttons]. The sensitivity of action widgets can be controlled with [method@Gtk.InfoBar.set_response_sensitive]. To add widgets to the main content area of a `GtkInfoBar`, use [method@Gtk.InfoBar.add_child]. Similar to [class@Gtk.MessageDialog], the contents of a `GtkInfoBar` can by classified as error message, warning, informational message, etc, by using [method@Gtk.InfoBar.set_message_type]. GTK may use the message type to determine how the message is displayed. A simple example for using a `GtkInfoBar`: ```c GtkWidget *message_label; GtkWidget *widget; GtkWidget *grid; GtkInfoBar *bar; // set up info bar widget = gtk_info_bar_new (); bar = GTK_INFO_BAR (widget); grid = gtk_grid_new (); message_label = gtk_label_new (""); gtk_info_bar_add_child (bar, message_label); gtk_info_bar_add_button (bar, _("_OK"), GTK_RESPONSE_OK); g_signal_connect (bar, "response", G_CALLBACK (gtk_widget_hide), NULL); gtk_grid_attach (GTK_GRID (grid), widget, 0, 2, 1, 1); // ... // show an error message gtk_label_set_text (GTK_LABEL (message_label), "An error occurred!"); gtk_info_bar_set_message_type (bar, GTK_MESSAGE_ERROR); gtk_widget_show (bar); ``` # GtkInfoBar as GtkBuildable `GtkInfoBar` supports a custom `<action-widgets>` element, which can contain multiple `<action-widget>` elements. The “response” attribute specifies a numeric response, and the content of the element is the id of widget (which should be a child of the dialogs @action_area). `GtkInfoBar` supports adding action widgets by specifying “action” as the “type” attribute of a `<child>` element. The widget will be added either to the action area. The response id has to be associated with the action widget using the `<action-widgets>` element. # CSS nodes `GtkInfoBar` has a single CSS node with name infobar. The node may get one of the style classes .info, .warning, .error or .question, depending on the message type. If the info bar shows a close button, that button will have the .close style class applied. There is no replacement in GTK for an "info bar" widget; you can use [class@Gtk.Revealer] with a [class@Gtk.Box] containing a [class@Gtk.Label] and an optional [class@Gtk.Button], according to your application's design. Creates a new `GtkInfoBar` object. a new `GtkInfoBar` object Creates a new `GtkInfoBar` with buttons. Button text/response ID pairs should be listed, with a %NULL pointer ending the list. A response ID can be any positive number, or one of the values in the `GtkResponseType` enumeration. If the user clicks one of these dialog buttons, GtkInfoBar will emit the [signal@Gtk.InfoBar::response] signal with the corresponding response ID. a new `GtkInfoBar` ext to go in first button response ID for first button, then additional buttons, ending with %NULL Add an activatable widget to the action area of a `GtkInfoBar`. This also connects a signal handler that will emit the [signal@Gtk.InfoBar::response] signal on the message area when the widget is activated. The widget is appended to the end of the message areas action area. a `GtkInfoBar` an activatable widget response ID for @child Adds a button with the given text. Clicking the button will emit the [signal@Gtk.InfoBar::response] signal with the given response_id. The button is appended to the end of the info bar's action area. The button widget is returned, but usually you don't need it. the `GtkButton` widget that was added a `GtkInfoBar` text of button response ID for the button Adds multiple buttons. This is the same as calling [method@Gtk.InfoBar.add_button] repeatedly. The variable argument list should be %NULL-terminated as with [ctor@Gtk.InfoBar.new_with_buttons]. Each button must have both text and response ID. a `GtkInfoBar` button text response ID for first button, then more text-response_id pairs, ending with %NULL Adds a widget to the content area of the info bar. a `GtkInfoBar` the child to be added Returns the message type of the message area. the message type of the message area. a `GtkInfoBar` Returns whether the info bar is currently revealed. the current value of the [property@Gtk.InfoBar:revealed] property a `GtkInfoBar` Returns whether the widget will display a standard close button. %TRUE if the widget displays standard close button a `GtkInfoBar` Removes a widget from the action area of @info_bar. The widget must have been put there by a call to [method@Gtk.InfoBar.add_action_widget] or [method@Gtk.InfoBar.add_button]. a `GtkInfoBar` an action widget to remove Removes a widget from the content area of the info bar. a `GtkInfoBar` a child that has been added to the content area Emits the “response” signal with the given @response_id. a `GtkInfoBar` a response ID Sets the last widget in the info bar’s action area with the given response_id as the default widget for the dialog. Pressing “Enter” normally activates the default widget. Note that this function currently requires @info_bar to be added to a widget hierarchy. a `GtkInfoBar` a response ID Sets the message type of the message area. GTK uses this type to determine how the message is displayed. a `GtkInfoBar` a `GtkMessageType` Sets the sensitivity of action widgets for @response_id. Calls `gtk_widget_set_sensitive (widget, setting)` for each widget in the info bars’s action area with the given @response_id. A convenient way to sensitize/desensitize buttons. a `GtkInfoBar` a response ID TRUE for sensitive Sets whether the `GtkInfoBar` is revealed. Changing this will make @info_bar reveal or conceal itself via a sliding transition. Note: this does not show or hide @info_bar in the [property@Gtk.Widget:visible] sense, so revealing has no effect if [property@Gtk.Widget:visible] is %FALSE. a `GtkInfoBar` The new value of the property If true, a standard close button is shown. When clicked it emits the response %GTK_RESPONSE_CLOSE. a `GtkInfoBar` %TRUE to include a close button The type of the message. The type may be used to determine the appearance of the info bar. Whether the info bar shows its contents. Whether to include a standard close button. Gets emitted when the user uses a keybinding to dismiss the info bar. The ::close signal is a [keybinding signal](class.SignalAction.html). The default binding for this signal is the Escape key. Emitted when an action widget is clicked. The signal is also emitted when the application programmer calls [method@Gtk.InfoBar.response]. The @response_id depends on which action widget was clicked. the response ID Describes hints that might be taken into account by input methods or applications. Note that input methods may already tailor their behaviour according to the [enum@InputPurpose] of the entry. Some common sense is expected when using these flags - mixing %GTK_INPUT_HINT_LOWERCASE with any of the uppercase hints makes no sense. This enumeration may be extended in the future; input methods should ignore unknown values. No special behaviour suggested Suggest checking for typos Suggest not checking for typos Suggest word completion Suggest to convert all text to lowercase Suggest to capitalize all text Suggest to capitalize the first character of each word Suggest to capitalize the first word of each sentence Suggest to not show an onscreen keyboard (e.g for a calculator that already has all the keys). The text is vertical Suggest offering Emoji support Suggest not offering Emoji support Request that the input method should not update personalized data (like typing history) Describes primary purpose of the input widget. This information is useful for on-screen keyboards and similar input methods to decide which keys should be presented to the user. Note that the purpose is not meant to impose a totally strict rule about allowed characters, and does not replace input validation. It is fine for an on-screen keyboard to let the user override the character set restriction that is expressed by the purpose. The application is expected to validate the entry contents, even if it specified a purpose. The difference between %GTK_INPUT_PURPOSE_DIGITS and %GTK_INPUT_PURPOSE_NUMBER is that the former accepts only digits while the latter also some punctuation (like commas or points, plus, minus) and “e” or “E” as in 3.14E+000. This enumeration may be extended in the future; input methods should interpret unknown values as “free form”. Allow any character Allow only alphabetic characters Allow only digits Edited field expects numbers Edited field expects phone number Edited field expects URL Edited field expects email address Edited field expects the name of a person Like %GTK_INPUT_PURPOSE_FREE_FORM, but characters are hidden Like %GTK_INPUT_PURPOSE_DIGITS, but characters are hidden Allow any character, in addition to control codes Shows text in a predefined area. You likely want to use `GtkLabel` instead as this widget is intended only for a small subset of use cases. The main scenario envisaged is inside lists such as `GtkColumnView`. While a `GtkLabel` sizes itself depending on the text that is displayed, `GtkInscription` is given a size and inscribes the given text into that space as well as it can. Users of this widget should take care to plan behaviour for the common case where the text doesn't fit exactly in the allocated space. ## CSS nodes `GtkInscription` has a single CSS node with the name label. Creates a new `GtkInscription` with the given text. a new `GtkInscription` The text to display. Gets the inscription's attribute list. the attribute list a `GtkInscription` Gets the `min-chars` of the inscription. See the [property@Gtk.Inscription:min-chars] property. the min-chars property a `GtkInscription` Gets the `min-lines` of the inscription. See the [property@Gtk.Inscription:min-lines] property. the min-lines property a `GtkInscription` Gets the `nat-chars` of the inscription. See the [property@Gtk.Inscription:nat-chars] property. the nat-chars property a `GtkInscription` Gets the `nat-lines` of the inscription. See the [property@Gtk.Inscription:nat-lines] property. the nat-lines property a `GtkInscription` Gets the text that is displayed. The displayed text a `GtkInscription` Gets the inscription's overflow method. the overflow method a `GtkInscription` Returns line wrap mode used by the inscription. See [method@Gtk.Inscription.set_wrap_mode]. the line wrap mode a `GtkInscription` Gets the `xalign` of the inscription. See the [property@Gtk.Inscription:xalign] property. the xalign property a `GtkInscription` Gets the `yalign` of the inscription. See the [property@Gtk.Inscription:yalign] property. the yalign property a `GtkInscription` Apply attributes to the inscription text. These attributes will not be evaluated for sizing the inscription. a `GtkInscription` a [struct@Pango.AttrList] Utility function to set the text and attributes to be displayed. See the [property@Gtk.Inscription:markup] property. a `GtkInscription` The markup to display Sets the `min-chars` of the inscription. See the [property@Gtk.Inscription:min-chars] property. a `GtkInscription` the minimum number of characters that should fit, approximately Sets the `min-lines` of the inscription. See the [property@Gtk.Inscription:min-lines] property. a `GtkInscription` the minimum number of lines that should fit, approximately Sets the `nat-chars` of the inscription. See the [property@Gtk.Inscription:nat-chars] property. a `GtkInscription` the number of characters that should ideally fit, approximately Sets the `nat-lines` of the inscription. See the [property@Gtk.Inscription:nat-lines] property. a `GtkInscription` the number of lines that should ideally fit Sets the text to be displayed. a `GtkInscription` The text to display Sets what to do when the text doesn't fit. a `GtkInscription` the overflow method to use Controls how line wrapping is done. a `GtkInscription` the line wrapping mode Sets the `xalign` of the inscription. See the [property@Gtk.Inscription:xalign] property. a `GtkInscription` the new xalign value, between 0 and 1 Sets the `yalign` of the inscription. See the [property@Gtk.Inscription:yalign] property. a `GtkInscription` the new yalign value, between 0 and 1 A list of style attributes to apply to the text of the inscription. Utility property that sets both the [property@Gtk.Inscription:text] and [property@Gtk.Inscription:attributes] properties, mainly intended for use in GtkBuilder ui files to ease translation support and bindings. This function uses [func@Pango.parse_markup] to parse the markup into text and attributes. The markup must be valid. If you cannot ensure that, consider using [func@Pango.parse_markup] and setting the two properties yourself. The number of characters that should fit into the inscription at minimum. This influences the requested width, not the width actually given to the widget, which might turn out to be larger. Note that this is an approximate character width, so some characters might be wider and some might be thinner, so do not expect the number of characters to exactly match. If you set this property to 0, the inscription will not request any width at all and its width will be determined entirely by its surroundings. The number of lines that should fit into the inscription at minimum. This influences the requested height, not the height actually given to the widget, which might turn out to be larger. Note that this is an approximate line height, so if the text uses things like fancy Unicode or attribute that influence the height, the text might not fit. If you set this property to 0, the inscription will not request any height at all and its height will be determined entirely by its surroundings. The number of characters that should ideally fit into the inscription. This influences the requested width, not the width actually given to the widget. The widget might turn out larger as well as smaller. If this property is set to a value smaller than [property@Gtk.Inscription:min-chars], that value will be used. In particular, for the default value of 0, this will always be the case. The number of lines that should ideally fit into the inscription. This influences the requested height, not the height actually given to the widget. The widget might turn out larger as well as smaller. If this property is set to a value smaller than [property@Gtk.Inscription:min-lines], that value will be used. In particular, for the default value of 0, this will always be the case. The displayed text. The overflow method to use for the text. Controls how the line wrapping is done. Note that unlike `GtkLabel`, the default here is %PANGO_WRAP_WORD_CHAR. The horizontal alignment of the text inside the allocated size. Compare this to [property@Gtk.Widget:halign], which determines how the inscription's size allocation is positioned in the available space. The vertical alignment of the text inside the allocated size. Compare this to [property@Gtk.Widget:valign], which determines how the inscription's size allocation is positioned in the available space. The different methods to handle text in #GtkInscription when it doesn't fit the available space. Clip the remaining text Omit characters at the start of the text Omit characters at the middle of the text Omit characters at the end of the text Values for the [property@Gtk.Settings:gtk-interface-color-scheme] and [property@Gtk.CssProvider:prefers-color-scheme] properties that indicates what color scheme is used. This information can be used inside CSS via media queries. More values may be added to this enumeration. Unknown values should be treated the same as `GTK_INTERFACE_COLOR_SCHEME_DEFAULT`. The system doesn't support color schemes The default color scheme is used A dark color scheme is used A light color scheme is used Values for the [property@Gtk.Settings:gtk-interface-contrast] and [property@Gtk.CssProvider:prefers-contrast] properties that indicates the preferred level of contrast. This information can be used inside CSS via media queries. More values may be added to this enumeration. Unknown values should be treated the same as `GTK_INTERFACE_CONTRAST_NO_PREFERENCE`. The system doesn't support contrast levels No particular preference for contrast More contrast is preferred Less contrast is preferred Used for justifying the text inside a [class@Label] widget. The text is placed at the left edge of the label. The text is placed at the right edge of the label. The text is placed in the center of the label. The text is placed is distributed across the label. Triggers when a specific keyval and modifiers are pressed. Creates a `GtkShortcutTrigger` that will trigger whenever the key with the given @keyval and @modifiers is pressed. A new `GtkShortcutTrigger` The keyval to trigger for the modifiers that need to be present Gets the keyval that must be pressed to succeed triggering @self. the keyval a keyval `GtkShortcutTrigger` Gets the modifiers that must be present to succeed triggering @self. the modifiers a keyval `GtkShortcutTrigger` The key value for the trigger. The key modifiers for the trigger. The name used for the stock full offset included by `GtkLevelBar`. The name used for the stock high offset included by `GtkLevelBar`. The name used for the stock low offset included by `GtkLevelBar`. Displays a small amount of text. Most labels are used to label another widget (such as an [class@Entry]). <picture> <source srcset="label-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkLabel" src="label.png"> </picture> ## Shortcuts and Gestures `GtkLabel` supports the following keyboard shortcuts, when the cursor is visible: - <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. - <kbd>Ctrl</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&sol;</kbd> selects all. - <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&bsol;</kbd> unselects all. Additionally, the following signals have default keybindings: - [signal@Gtk.Label::activate-current-link] - [signal@Gtk.Label::copy-clipboard] - [signal@Gtk.Label::move-cursor] ## Actions `GtkLabel` defines a set of built-in actions: - `clipboard.copy` copies the text to the clipboard. - `clipboard.cut` doesn't do anything, since text in labels can't be deleted. - `clipboard.paste` doesn't do anything, since text in labels can't be edited. - `link.open` opens the link, when activated on a link inside the label. - `link.copy` copies the link to the clipboard, when activated on a link inside the label. - `menu.popup` opens the context menu. - `selection.delete` doesn't do anything, since text in labels can't be deleted. - `selection.select-all` selects all of the text, if the label allows selection. ## CSS nodes ``` label ├── [selection] ├── [link] ┊ ╰── [link] ``` `GtkLabel` has a single CSS node with the name label. A wide variety of style classes may be applied to labels, such as .title, .subtitle, .dim-label, etc. In the `GtkShortcutsWindow`, labels are used with the .keycap style class. If the label has a selection, it gets a subnode with name selection. If the label has links, there is one subnode per link. These subnodes carry the link or visited state depending on whether they have been visited. In this case, label node also gets a .link style class. ## GtkLabel as GtkBuildable The GtkLabel implementation of the GtkBuildable interface supports a custom `<attributes>` element, which supports any number of `<attribute>` elements. The `<attribute>` element has attributes named “name“, “value“, “start“ and “end“ and allows you to specify [struct@Pango.Attribute] values for this label. An example of a UI definition fragment specifying Pango attributes: ```xml <object class="GtkLabel"> <attributes> <attribute name="weight" value="PANGO_WEIGHT_BOLD"/> <attribute name="background" value="red" start="5" end="10"/> </attributes> </object> ``` The start and end attributes specify the range of characters to which the Pango attribute applies. If start and end are not specified, the attribute is applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup embedded in the translatable content instead. ## Accessibility `GtkLabel` uses the [enum@Gtk.AccessibleRole.label] role. ## Mnemonics Labels may contain “mnemonics”. Mnemonics are underlined characters in the label, used for keyboard navigation. Mnemonics are created by providing a string with an underscore before the mnemonic character, such as `"_File"`, to the functions [ctor@Gtk.Label.new_with_mnemonic] or [method@Gtk.Label.set_text_with_mnemonic]. Mnemonics automatically activate any activatable widget the label is inside, such as a [class@Gtk.Button]; if the label is not inside the mnemonic’s target widget, you have to tell the label about the target using [method@Gtk.Label.set_mnemonic_widget]. Here’s a simple example where the label is inside a button: ```c // Pressing Alt+H will activate this button GtkWidget *button = gtk_button_new (); GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello"); gtk_button_set_child (GTK_BUTTON (button), label); ``` There’s a convenience function to create buttons with a mnemonic label already inside: ```c // Pressing Alt+H will activate this button GtkWidget *button = gtk_button_new_with_mnemonic ("_Hello"); ``` To create a mnemonic for a widget alongside the label, such as a [class@Gtk.Entry], you have to point the label at the entry with [method@Gtk.Label.set_mnemonic_widget]: ```c // Pressing Alt+H will focus the entry GtkWidget *entry = gtk_entry_new (); GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello"); gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry); ``` ## Markup (styled text) To make it easy to format text in a label (changing colors, fonts, etc.), label text can be provided in a simple markup format: Here’s how to create a label with a small font: ```c GtkWidget *label = gtk_label_new (NULL); gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>"); ``` (See the Pango manual for complete documentation] of available tags, [func@Pango.parse_markup]) The markup passed to [method@Gtk.Label.set_markup] must be valid XML; for example, literal `<`, `>` and `&` characters must be escaped as `&lt;`, `&gt;`, and `&amp;`. If you pass text obtained from the user, file, or a network to [method@Gtk.Label.set_markup], you’ll want to escape it with [func@GLib.markup_escape_text] or [func@GLib.markup_printf_escaped]. Markup strings are just a convenient way to set the [struct@Pango.AttrList] on a label; [method@Gtk.Label.set_attributes] may be a simpler way to set attributes in some cases. Be careful though; [struct@Pango.AttrList] tends to cause internationalization problems, unless you’re applying attributes to the entire string (i.e. unless you set the range of each attribute to [0, `G_MAXINT`)). The reason is that specifying the `start_index` and `end_index` for a [struct@Pango.Attribute] requires knowledge of the exact string being displayed, so translations will cause problems. ## Selectable labels Labels can be made selectable with [method@Gtk.Label.set_selectable]. Selectable labels allow the user to copy the label contents to the clipboard. Only labels that contain useful-to-copy information — such as error messages — should be made selectable. ## Text layout A label can contain any number of paragraphs, but will have performance problems if it contains more than a small number. Paragraphs are separated by newlines or other paragraph separators understood by Pango. Labels can automatically wrap text if you call [method@Gtk.Label.set_wrap]. [method@Gtk.Label.set_justify] sets how the lines in a label align with one another. If you want to set how the label as a whole aligns in its available space, see the [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties. The [property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] properties can be used to control the size allocation of ellipsized or wrapped labels. For ellipsizing labels, if either is specified (and less than the actual text size), it is used as the minimum width, and the actual text size is used as the natural width of the label. For wrapping labels, width-chars is used as the minimum width, if specified, and max-width-chars is used as the natural width. Even if max-width-chars specified, wrapping labels will be rewrapped to use all of the available width. ## Links GTK supports markup for clickable hyperlinks in addition to regular Pango markup. The markup for links is borrowed from HTML, using the `<a>` tag with “href“, “title“ and “class“ attributes. GTK renders links similar to the way they appear in web browsers, with colored, underlined text. The “title“ attribute is displayed as a tooltip on the link. The “class“ attribute is used as style class on the CSS node for the link. An example of inline links looks like this: ```c const char *text = "Go to the " "<a href=\"https://www.gtk.org\" title=\"&lt;i&gt;Our&lt;/i&gt; website\">" "GTK website</a> for more..."; GtkWidget *label = gtk_label_new (NULL); gtk_label_set_markup (GTK_LABEL (label), text); ``` It is possible to implement custom handling for links and their tooltips with the [signal@Gtk.Label::activate-link] signal and the [method@Gtk.Label.get_current_uri] function. Creates a new label with the given text inside it. You can pass `NULL` to get an empty label widget. the new label the text of the label Creates a new label with the given text inside it, and a mnemonic. If characters in @str are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use '__' (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. If [method@Gtk.Label.set_mnemonic_widget] is not called, then the first activatable ancestor of the label will be chosen as the mnemonic widget. For instance, if the label is inside a button or menu item, the button or menu item will automatically become the mnemonic widget and be activated by the mnemonic. the new label the text of the label, with an underscore in front of the mnemonic character Gets the label's attribute list. This is the [struct@Pango.AttrList] that was set on the label using [method@Gtk.Label.set_attributes], if any. This function does not reflect attributes that come from the label's markup (see [method@Gtk.Label.set_markup]). If you want to get the effective attributes for the label, use `pango_layout_get_attributes (gtk_label_get_layout (self))`. the attribute list a label Returns the URI for the active link in the label. The active link is the one under the mouse pointer or, in a selectable label, the link in which the text cursor is currently positioned. This function is intended for use in a [signal@Gtk.Label::activate-link] handler or for use in a [signal@Gtk.Widget::query-tooltip] handler. the active URI a label Returns the ellipsization mode of the label. See [method@Gtk.Label.set_ellipsize]. the ellipsization mode a label Gets the extra menu model of the label. See [method@Gtk.Label.set_extra_menu]. the menu model a label Returns the justification of the label. See [method@Gtk.Label.set_justify]. the justification value a label Fetches the text from a label. The returned text includes any embedded underlines indicating mnemonics and Pango markup. (See [method@Gtk.Label.get_text]). the text of the label widget a label Gets the Pango layout used to display the label. The layout is useful to e.g. convert text positions to pixel positions, in combination with [method@Gtk.Label.get_layout_offsets]. The returned layout is owned by the @label so need not be freed by the caller. The @label is free to recreate its layout at any time, so it should be considered read-only. the [class@Pango.Layout] for this label a label Obtains the coordinates where the label will draw its Pango layout. The coordinates are useful to convert mouse events into coordinates inside the [class@Pango.Layout], e.g. to take some action if some part of the label is clicked. Remember when using the [class@Pango.Layout] functions you need to convert to and from pixels using `PANGO_PIXELS()` or [const@Pango.SCALE]. a label location to store X offset of layout location to store Y offset of layout Gets the number of lines to which an ellipsized, wrapping label should be limited. See [method@Gtk.Label.set_lines]. the number of lines a label Retrieves the maximum width of the label in characters. See [method@Gtk.Label.set_width_chars]. the maximum width of the label, in characters a label Return the mnemonic accelerator. If the label has been set so that it has a mnemonic key this function returns the keyval used for the mnemonic accelerator. If there is no mnemonic set up it returns `GDK_KEY_VoidSymbol`. GDK keyval usable for accelerators, or `GDK_KEY_VoidSymbol` a label Retrieves the mnemonic target of this label. See [method@Gtk.Label.set_mnemonic_widget]. the target of the label’s mnemonic, or `NULL` if none has been set and the default algorithm will be used. a label Returns natural line wrap mode used by the label. See [method@Gtk.Label.set_natural_wrap_mode]. the natural line wrap mode a label Returns whether the label is selectable. true if the user can copy text from the label a label Gets the selected range of characters in the label. The returned @start and @end positions are in characters. true if selection is non-empty a label return location for start of selection return location for end of selection Returns whether the label is in single line mode. true if the label is in single line mode a label Gets the tab stops for the label. The returned array will be `NULL` if “standard” (8-space) tabs are used. copy of default tab array, or `NULL` if standard tabs are used a label Gets the text of the label. The returned text is as it appears on screen. This does not include any embedded underlines indicating mnemonics or Pango markup. (See [method@Gtk.Label.get_label]) the text in the label widget a label Returns whether the label’s text is interpreted as Pango markup. See [method@Gtk.Label.set_use_markup]. true if the label’s text will be parsed for markup a label Returns whether underlines in the label indicate mnemonics. See [method@Gtk.Label.set_use_underline]. true if underlines in the label indicate mnemonics a label Retrieves the desired width of the label in characters. See [method@Gtk.Label.set_width_chars]. the desired width of the label, in characters a label Returns whether lines in the label are automatically wrapped. See [method@Gtk.Label.set_wrap]. true if the lines of the label are automatically wrapped a label Returns line wrap mode used by the label. See [method@Gtk.Label.set_wrap_mode]. the line wrap mode a label Gets the `xalign` of the label. See the [property@Gtk.Label:xalign] property. the xalign value a label Gets the `yalign` of the label. See the [property@Gtk.Label:yalign] property. the yalign value a label Selects a range of characters in the label, if the label is selectable. See [method@Gtk.Label.set_selectable]. If the label is not selectable, this function has no effect. If @start_offset or @end_offset are -1, then the end of the label will be substituted. a label start offset, in characters end offset, in characters Apply attributes to the label text. The attributes set with this function will be applied and merged with any other attributes previously effected by way of the [property@Gtk.Label:use-underline] or [property@Gtk.Label:use-markup] properties While it is not recommended to mix markup strings with manually set attributes, if you must; know that the attributes will be applied to the label after the markup string is parsed. a label a list of style attributes Sets the mode used to ellipsize the text. The text will be ellipsized if there is not enough space to render the entire string. a label the ellipsization mode Sets a menu model to add to the context menu of the label. a label a menu model Sets the alignment of lines in the label relative to each other. This function has no effect on labels containing only a single line. [enum@Gtk.Justification.left] is the default value when the widget is first created with [ctor@Gtk.Label.new]. If you instead want to set the alignment of the label as a whole, use [method@Gtk.Widget.set_halign] instead. a label the new justification Sets the text of the label. The label is interpreted as including embedded underlines and/or Pango markup depending on the values of the [property@Gtk.Label:use-underline] and [property@Gtk.Label:use-markup] properties. a label the new text to set for the label Sets the number of lines to which an ellipsized, wrapping label should be limited. This has no effect if the label is not wrapping or ellipsized. Set this to -1 if you don’t want to limit the number of lines. a label the desired number of lines, or -1 Sets the labels text and attributes from markup. The string must be marked up with Pango markup (see [func@Pango.parse_markup]). If @str is external data, you may need to escape it with [func@GLib.markup_escape_text] or [func@GLib.markup_printf_escaped]: ```c GtkWidget *self = gtk_label_new (NULL); const char *str = "..."; const char *format = "<span style=\"italic\">\%s</span>"; char *markup; markup = g_markup_printf_escaped (format, str); gtk_label_set_markup (GTK_LABEL (self), markup); g_free (markup); ``` This function sets the [property@Gtk.Label:use-markup] property to true. Also see [method@Gtk.Label.set_text]. a label the markup string Sets the labels text, attributes and mnemonic from markup. Parses @str which is marked up with Pango markup (see [func@Pango.parse_markup]), setting the label’s text and attribute list based on the parse results. If characters in @str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. a label the markup string Sets the maximum width of the label in characters. a label the new maximum width, in characters. Associate the label with its mnemonic target. If the label has been set so that it has a mnemonic key (using i.e. [method@Gtk.Label.set_markup_with_mnemonic], [method@Gtk.Label.set_text_with_mnemonic], [ctor@Gtk.Label.new_with_mnemonic] or the [property@Gtk.Label:use_underline] property) the label can be associated with a widget that is the target of the mnemonic. When the label is inside a widget (like a [class@Gtk.Button] or a [class@Gtk.Notebook] tab) it is automatically associated with the correct widget, but sometimes (i.e. when the target is a [class@Gtk.Entry] next to the label) you need to set it explicitly using this function. The target widget will be accelerated by emitting the [signal@Gtk.Widget::mnemonic-activate] signal on it. The default handler for this signal will activate the widget if there are no mnemonic collisions and toggle focus between the colliding widgets otherwise. a label the target widget Selects the line wrapping for the natural size request. This only affects the natural size requested, for the actual wrapping used, see the [property@Gtk.Label:wrap-mode] property. a label the line wrapping mode Makes text in the label selectable. Selectable labels allow the user to select text from the label, for copy-and-paste. a label true to allow selecting text in the label Sets whether the label is in single line mode. a label true to enable single line mode Sets tab stops for the label. a label tab stops Sets the text for the label. It overwrites any text that was there before and clears any previously set mnemonic accelerators, and sets the [property@Gtk.Label:use-underline] and [property@Gtk.Label:use-markup] properties to false. Also see [method@Gtk.Label.set_markup]. a label the text to show in @self Sets the text for the label, with mnemonics. If characters in @str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. a label the text Sets whether the text of the label contains markup. See [method@Gtk.Label.set_markup]. a label true if the label’s text should be parsed for markup. Sets whether underlines in the text indicate mnemonics. a label true if underlines in the text indicate mnemonics Sets the desired width in characters of the label. a label the new desired width, in characters. Toggles line wrapping within the label. True makes it break lines if text exceeds the widget’s size. false lets the text get cut off by the edge of the widget if it exceeds the widget size. Note that setting line wrapping to true does not make the label wrap at its parent widget’s width, because GTK widgets conceptually can’t make their requisition depend on the parent widget’s size. For a label that wraps at a specific position, set the label’s width using [method@Gtk.Widget.set_size_request]. a label whether to wrap lines Controls how line wrapping is done. This only affects the label if line wrapping is on. (See [method@Gtk.Label.set_wrap]) The default is [enum@Pango.WrapMode.word], which means wrap on word boundaries. For sizing behavior, also consider the [property@Gtk.Label:natural-wrap-mode] property. a label the line wrapping mode Sets the `xalign` of the label. See the [property@Gtk.Label:xalign] property. a label the new xalign value, between 0 and 1 Sets the `yalign` of the label. See the [property@Gtk.Label:yalign] property. a label the new yalign value, between 0 and 1 A list of style attributes to apply to the text of the label. The preferred place to ellipsize the string, if the label does not have enough room to display the entire string. Note that setting this property to a value other than [enum.Pango.EllipsizeMode.none] has the side-effect that the label requests only enough space to display the ellipsis "...". In particular, this means that ellipsizing labels do not work well in notebook tabs, unless the [property@Gtk.NotebookPage:tab-expand] child property is set to true. Other ways to set a label's width are [method@Gtk.Widget.set_size_request] and [method@Gtk.Label.set_width_chars]. A menu model whose contents will be appended to the context menu. The alignment of the lines in the text of the label, relative to each other. This does *not* affect the alignment of the label within its allocation. See [property@Gtk.Label:xalign] for that. The contents of the label. If the string contains Pango markup (see [func@Pango.parse_markup]), you will have to set the [property@Gtk.Label:use-markup] property to true in order for the label to display the markup attributes. See also [method@Gtk.Label.set_markup] for a convenience function that sets both this property and the [property@Gtk.Label:use-markup] property at the same time. If the string contains underlines acting as mnemonics, you will have to set the [property@Gtk.Label:use-underline] property to true in order for the label to display them. The number of lines to which an ellipsized, wrapping label should display before it gets ellipsized. This both prevents the label from ellipsizing before this many lines are displayed, and limits the height request of the label to this many lines. ::: warning Setting this property has unintuitive and unfortunate consequences for the minimum _width_ of the label. Specifically, if the height of the label is such that it fits a smaller number of lines than the value of this property, the label can not be ellipsized at all, which means it must be wide enough to fit all the text fully. This property has no effect if the label is not wrapping or ellipsized. Set this property to -1 if you don't want to limit the number of lines. The desired maximum width of the label, in characters. If this property is set to -1, the width will be calculated automatically. See the section on [text layout](class.Label.html#text-layout) for details of how [property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] determine the width of ellipsized and wrapped labels. The mnemonic accelerator key for the label. The widget to be activated when the labels mnemonic key is pressed. Select the line wrapping for the natural size request. This only affects the natural size requested. For the actual wrapping used, see the [property@Gtk.Label:wrap-mode] property. The default is [enum@Gtk.NaturalWrapMode.inherit], which inherits the behavior of the [property@Gtk.Label:wrap-mode] property. Whether the label text can be selected with the mouse. Whether the label is in single line mode. In single line mode, the height of the label does not depend on the actual text, it is always set to ascent + descent of the font. This can be an advantage in situations where resizing the label because of text changes would be distracting, e.g. in a statusbar. Custom tabs for this label. True if the text of the label includes Pango markup. See [func@Pango.parse_markup]. True if the text of the label indicates a mnemonic with an `_` before the mnemonic character. The desired width of the label, in characters. If this property is set to -1, the width will be calculated automatically. See the section on [text layout](class.Label.html#text-layout) for details of how [property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] determine the width of ellipsized and wrapped labels. True if the label text will wrap if it gets too wide. Controls how the line wrapping is done. This only affects the formatting if line wrapping is on (see the [property@Gtk.Label:wrap] property). The default is [enum@Pango.WrapMode.word], which means wrap on word boundaries. For sizing behavior, also consider the [property@Gtk.Label:natural-wrap-mode] property. The horizontal alignment of the label text inside its size allocation. Compare this to [property@Gtk.Widget:halign], which determines how the labels size allocation is positioned in the space available for the label. The vertical alignment of the label text inside its size allocation. Compare this to [property@Gtk.Widget:valign], which determines how the labels size allocation is positioned in the space available for the label. Gets emitted when the user activates a link in the label. The `::activate-current-link` is a [keybinding signal](class.SignalAction.html). Applications may also emit the signal with g_signal_emit_by_name() if they need to control activation of URIs programmatically. The default bindings for this signal are all forms of the <kbd>Enter</kbd> key. Gets emitted to activate a URI. Applications may connect to it to override the default behaviour, which is to call [method@Gtk.FileLauncher.launch]. true if the link has been activated the URI that is activated Gets emitted to copy the selection to the clipboard. The `::copy-clipboard` signal is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Ctrl</kbd>+<kbd>c</kbd>. Gets emitted when the user initiates a cursor movement. The `::move-cursor` signal is a [keybinding signal](class.SignalAction.html). If the cursor is not visible in @entry, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with [func@GObject.signal_emit_by_name] if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the <kbd>Shift</kbd> modifier extends the selection, the variant without the <kbd>Shift</kbd> modifier does not. There are too many key combinations to list them all here. - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move by individual characters/lines - <kbd>Ctrl</kbd>+<kbd>←</kbd>, etc. move by words/paragraphs - <kbd>Home</kbd> and <kbd>End</kbd> move to the ends of the buffer the granularity of the move, as a `GtkMovementStep` the number of @step units to move true if the move should extend the selection The base class for objects that are meant to hold layout properties. If a `GtkLayoutManager` has per-child properties, like their packing type, or the horizontal and vertical span, or the icon name, then the layout manager should use a `GtkLayoutChild` implementation to store those properties. A `GtkLayoutChild` instance is only ever valid while a widget is part of a layout. Retrieves the `GtkWidget` associated to the given @layout_child. a `GtkWidget` a `GtkLayoutChild` Retrieves the `GtkLayoutManager` instance that created the given @layout_child. a `GtkLayoutManager` a `GtkLayoutChild` The widget that is associated to the `GtkLayoutChild` instance. The layout manager that created the `GtkLayoutChild` instance. Handles the preferred size and allocation for children of a widget. You typically subclass `GtkLayoutManager` if you want to implement a layout policy for the children of a widget, or if you want to determine the size of a widget depending on its contents. Each `GtkWidget` can only have a `GtkLayoutManager` instance associated to it at any given time; it is possible, though, to replace the layout manager instance using [method@Gtk.Widget.set_layout_manager]. ## Layout properties A layout manager can expose properties for controlling the layout of each child, by creating an object type derived from [class@Gtk.LayoutChild] and installing the properties on it as normal `GObject` properties. Each `GtkLayoutChild` instance storing the layout properties for a specific child is created through the [method@Gtk.LayoutManager.get_layout_child] method; a `GtkLayoutManager` controls the creation of its `GtkLayoutChild` instances by overriding the GtkLayoutManagerClass.create_layout_child() virtual function. The typical implementation should look like: ```c static GtkLayoutChild * create_layout_child (GtkLayoutManager *manager, GtkWidget *container, GtkWidget *child) { return g_object_new (your_layout_child_get_type (), "layout-manager", manager, "child-widget", child, NULL); } ``` The [property@Gtk.LayoutChild:layout-manager] and [property@Gtk.LayoutChild:child-widget] properties on the newly created `GtkLayoutChild` instance are mandatory. The `GtkLayoutManager` will cache the newly created `GtkLayoutChild` instance until the widget is removed from its parent, or the parent removes the layout manager. Each `GtkLayoutManager` instance creating a `GtkLayoutChild` should use [method@Gtk.LayoutManager.get_layout_child] every time it needs to query the layout properties; each `GtkLayoutChild` instance should call [method@Gtk.LayoutManager.layout_changed] every time a property is updated, in order to queue a new size measuring and allocation. Assigns the given @width, @height, and @baseline to a @widget, and computes the position and sizes of the children of the @widget using the layout management policy of @manager. a `GtkLayoutManager` the `GtkWidget` using @manager the new width of the @widget the new height of the @widget the baseline position of the @widget, or -1 Create a `GtkLayoutChild` instance for the given @for_child widget. a `GtkLayoutChild` the `GtkLayoutManager` the widget using the @manager the child of @widget a virtual function, used to return the preferred request mode for the layout manager; for instance, "width for height" or "height for width"; see `GtkSizeRequestMode` Measures the size of the @widget using @manager, for the given @orientation and size. See the [class@Gtk.Widget] documentation on layout management for more details. a `GtkLayoutManager` the `GtkWidget` using @manager the orientation to measure Size for the opposite of @orientation; for instance, if the @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height of the widget; if the @orientation is %GTK_ORIENTATION_VERTICAL, this is the width of the widget. This allows to measure the height for the given width, and the width for the given height. Use -1 if the size is not known the minimum size for the given size and orientation the natural, or preferred size for the given size and orientation the baseline position for the minimum size the baseline position for the natural size a virtual function, called when the widget using the layout manager is attached to a `GtkRoot` a virtual function, called when the widget using the layout manager is detached from a `GtkRoot` Assigns the given @width, @height, and @baseline to a @widget, and computes the position and sizes of the children of the @widget using the layout management policy of @manager. a `GtkLayoutManager` the `GtkWidget` using @manager the new width of the @widget the new height of the @widget the baseline position of the @widget, or -1 Retrieves a `GtkLayoutChild` instance for the `GtkLayoutManager`, creating one if necessary. The @child widget must be a child of the widget using @manager. The `GtkLayoutChild` instance is owned by the `GtkLayoutManager`, and is guaranteed to exist as long as @child is a child of the `GtkWidget` using the given `GtkLayoutManager`. a `GtkLayoutChild` a `GtkLayoutManager` a `GtkWidget` Retrieves the request mode of @manager. a `GtkSizeRequestMode` a `GtkLayoutManager` Retrieves the `GtkWidget` using the given `GtkLayoutManager`. a `GtkWidget` a `GtkLayoutManager` Queues a resize on the `GtkWidget` using @manager, if any. This function should be called by subclasses of `GtkLayoutManager` in response to changes to their layout management policies. a `GtkLayoutManager` Measures the size of the @widget using @manager, for the given @orientation and size. See the [class@Gtk.Widget] documentation on layout management for more details. a `GtkLayoutManager` the `GtkWidget` using @manager the orientation to measure Size for the opposite of @orientation; for instance, if the @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height of the widget; if the @orientation is %GTK_ORIENTATION_VERTICAL, this is the width of the widget. This allows to measure the height for the given width, and the width for the given height. Use -1 if the size is not known the minimum size for the given size and orientation the natural, or preferred size for the given size and orientation the baseline position for the minimum size the baseline position for the natural size The `GtkLayoutManagerClass` structure contains only private data, and should only be accessed through the provided API, or when subclassing `GtkLayoutManager`. a virtual function, used to return the preferred request mode for the layout manager; for instance, "width for height" or "height for width"; see `GtkSizeRequestMode` a virtual function, used to measure the minimum and preferred sizes of the widget using the layout manager for a given orientation a `GtkLayoutManager` the `GtkWidget` using @manager the orientation to measure Size for the opposite of @orientation; for instance, if the @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height of the widget; if the @orientation is %GTK_ORIENTATION_VERTICAL, this is the width of the widget. This allows to measure the height for the given width, and the width for the given height. Use -1 if the size is not known the minimum size for the given size and orientation the natural, or preferred size for the given size and orientation the baseline position for the minimum size the baseline position for the natural size a virtual function, used to allocate the size of the widget using the layout manager a `GtkLayoutManager` the `GtkWidget` using @manager the new width of the @widget the new height of the @widget the baseline position of the @widget, or -1 the type of `GtkLayoutChild` used by this layout manager a virtual function, used to create a `GtkLayoutChild` meta object for the layout properties a `GtkLayoutChild` the `GtkLayoutManager` the widget using the @manager the child of @widget a virtual function, called when the widget using the layout manager is attached to a `GtkRoot` a virtual function, called when the widget using the layout manager is detached from a `GtkRoot` Shows a level indicator. Typical use cases are displaying the strength of a password, or showing the charge level of a battery. <picture> <source srcset="levelbar-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkLevelBar" src="levelbar.png"> </picture> Use [method@Gtk.LevelBar.set_value] to set the current value, and [method@Gtk.LevelBar.add_offset_value] to set the value offsets at which the bar will be considered in a different state. GTK will add a few offsets by default on the level bar: %GTK_LEVEL_BAR_OFFSET_LOW, %GTK_LEVEL_BAR_OFFSET_HIGH and %GTK_LEVEL_BAR_OFFSET_FULL, with values 0.25, 0.75 and 1.0 respectively. Note that it is your responsibility to update preexisting offsets when changing the minimum or maximum value. GTK will simply clamp them to the new range. ## Adding a custom offset on the bar ```c static GtkWidget * create_level_bar (void) { GtkWidget *widget; GtkLevelBar *bar; widget = gtk_level_bar_new (); bar = GTK_LEVEL_BAR (widget); // This changes the value of the default low offset gtk_level_bar_add_offset_value (bar, GTK_LEVEL_BAR_OFFSET_LOW, 0.10); // This adds a new offset to the bar; the application will // be able to change its color CSS like this: // // levelbar block.my-offset { // background-color: magenta; // border-style: solid; // border-color: black; // border-width: 1px; // } gtk_level_bar_add_offset_value (bar, "my-offset", 0.60); return widget; } ``` The default interval of values is between zero and one, but it’s possible to modify the interval using [method@Gtk.LevelBar.set_min_value] and [method@Gtk.LevelBar.set_max_value]. The value will be always drawn in proportion to the admissible interval, i.e. a value of 15 with a specified interval between 10 and 20 is equivalent to a value of 0.5 with an interval between 0 and 1. When %GTK_LEVEL_BAR_MODE_DISCRETE is used, the bar level is rendered as a finite number of separated blocks instead of a single one. The number of blocks that will be rendered is equal to the number of units specified by the admissible interval. For instance, to build a bar rendered with five blocks, it’s sufficient to set the minimum value to 0 and the maximum value to 5 after changing the indicator mode to discrete. # GtkLevelBar as GtkBuildable The `GtkLevelBar` implementation of the `GtkBuildable` interface supports a custom `<offsets>` element, which can contain any number of `<offset>` elements, each of which must have "name" and "value" attributes. # CSS nodes ``` levelbar[.discrete] ╰── trough ├── block.filled.level-name ┊ ├── block.empty ┊ ``` `GtkLevelBar` has a main CSS node with name levelbar and one of the style classes .discrete or .continuous and a subnode with name trough. Below the trough node are a number of nodes with name block and style class .filled or .empty. In continuous mode, there is exactly one node of each, in discrete mode, the number of filled and unfilled nodes corresponds to blocks that are drawn. The block.filled nodes also get a style class .level-name corresponding to the level for the current value. In horizontal orientation, the nodes are always arranged from left to right, regardless of text direction. # Accessibility `GtkLevelBar` uses the [enum@Gtk.AccessibleRole.meter] role. Creates a new `GtkLevelBar`. a `GtkLevelBar`. Creates a new `GtkLevelBar` for the specified interval. a `GtkLevelBar` a positive value a positive value Adds a new offset marker on @self at the position specified by @value. When the bar value is in the interval topped by @value (or between @value and [property@Gtk.LevelBar:max-value] in case the offset is the last one on the bar) a style class named `level-`@name will be applied when rendering the level bar fill. If another offset marker named @name exists, its value will be replaced by @value. a `GtkLevelBar` the name of the new offset the value for the new offset Returns whether the levelbar is inverted. %TRUE if the level bar is inverted a `GtkLevelBar` Returns the `max-value` of the `GtkLevelBar`. a positive value a `GtkLevelBar` Returns the `min-value` of the `GtkLevelBar`. a positive value a `GtkLevelBar` Returns the `mode` of the `GtkLevelBar`. a `GtkLevelBarMode` a `GtkLevelBar` Fetches the value specified for the offset marker @name in @self. %TRUE if the specified offset is found a `GtkLevelBar` the name of an offset in the bar location where to store the value Returns the `value` of the `GtkLevelBar`. a value in the interval between [property@Gtk.LevelBar:min-value] and [property@Gtk.LevelBar:max-value] a `GtkLevelBar` Removes an offset marker from a `GtkLevelBar`. The marker must have been previously added with [method@Gtk.LevelBar.add_offset_value]. a `GtkLevelBar` the name of an offset in the bar Sets whether the `GtkLevelBar` is inverted. a `GtkLevelBar` %TRUE to invert the level bar Sets the `max-value` of the `GtkLevelBar`. You probably want to update preexisting level offsets after calling this function. a `GtkLevelBar` a positive value Sets the `min-value` of the `GtkLevelBar`. You probably want to update preexisting level offsets after calling this function. a `GtkLevelBar` a positive value Sets the `mode` of the `GtkLevelBar`. a `GtkLevelBar` a `GtkLevelBarMode` Sets the value of the `GtkLevelBar`. a `GtkLevelBar` a value in the interval between [property@Gtk.LevelBar:min-value] and [property@Gtk.LevelBar:max-value] Whether the `GtkLeveBar` is inverted. Level bars normally grow from top to bottom or left to right. Inverted level bars grow in the opposite direction. Determines the maximum value of the interval that can be displayed by the bar. Determines the minimum value of the interval that can be displayed by the bar. Determines the way `GtkLevelBar` interprets the value properties to draw the level fill area. Specifically, when the value is %GTK_LEVEL_BAR_MODE_CONTINUOUS, `GtkLevelBar` will draw a single block representing the current value in that area; when the value is %GTK_LEVEL_BAR_MODE_DISCRETE, the widget will draw a succession of separate blocks filling the draw area, with the number of blocks being equal to the units separating the integral roundings of [property@Gtk.LevelBar:min-value] and [property@Gtk.LevelBar:max-value]. Determines the currently filled value of the level bar. Emitted when an offset specified on the bar changes value. This typically is the result of a [method@Gtk.LevelBar.add_offset_value] call. The signal supports detailed connections; you can connect to the detailed signal "changed::x" in order to only receive callbacks when the value of offset "x" changes. the name of the offset that changed value Describes how [class@LevelBar] contents should be rendered. Note that this enumeration could be extended with additional modes in the future. the bar has a continuous mode the bar has a discrete mode The type of license for an application. This enumeration can be expanded at later date. No license specified A license text is going to be specified by the developer The GNU General Public License, version 2.0 or later The GNU General Public License, version 3.0 or later The GNU Lesser General Public License, version 2.1 or later The GNU Lesser General Public License, version 3.0 or later The BSD standard license The MIT/X11 standard license The Artistic License, version 2.0 The GNU General Public License, version 2.0 only The GNU General Public License, version 3.0 only The GNU Lesser General Public License, version 2.1 only The GNU Lesser General Public License, version 3.0 only The GNU Affero General Public License, version 3.0 or later The GNU Affero General Public License, version 3.0 only The 3-clause BSD licence The Apache License, version 2.0 The Mozilla Public License, version 2.0 Zero-Clause BSD license A button with a hyperlink. <picture> <source srcset="link-button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkLinkButton" src="link-button.png"> </picture> It is useful to show quick links to resources. A link button is created by calling either [ctor@Gtk.LinkButton.new] or [ctor@Gtk.LinkButton.new_with_label]. If using the former, the URI you pass to the constructor is used as a label for the widget. The URI bound to a `GtkLinkButton` can be set specifically using [method@Gtk.LinkButton.set_uri]. By default, `GtkLinkButton` calls [method@Gtk.FileLauncher.launch] when the button is clicked. This behaviour can be overridden by connecting to the [signal@Gtk.LinkButton::activate-link] signal and returning %TRUE from the signal handler. # Shortcuts and Gestures `GtkLinkButton` supports the following keyboard shortcuts: - <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. # Actions `GtkLinkButton` defines a set of built-in actions: - `clipboard.copy` copies the url to the clipboard. - `menu.popup` opens the context menu. # CSS nodes `GtkLinkButton` has a single CSS node with name button. To differentiate it from a plain `GtkButton`, it gets the .link style class. # Accessibility `GtkLinkButton` uses the [enum@Gtk.AccessibleRole.link] role. Creates a new `GtkLinkButton` with the URI as its text. a new link button widget. a valid URI Creates a new `GtkLinkButton` containing a label. a new link button widget. a valid URI the text of the button Retrieves the URI of the `GtkLinkButton`. a valid URI. The returned string is owned by the link button and should not be modified or freed. a `GtkLinkButton` Retrieves the “visited” state of the `GtkLinkButton`. The button becomes visited when it is clicked. If the URI is changed on the button, the “visited” state is unset again. The state may also be changed using [method@Gtk.LinkButton.set_visited]. %TRUE if the link has been visited, %FALSE otherwise a `GtkLinkButton` Sets @uri as the URI where the `GtkLinkButton` points. As a side-effect this unsets the “visited” state of the button. a `GtkLinkButton` a valid URI Sets the “visited” state of the `GtkLinkButton`. See [method@Gtk.LinkButton.get_visited] for more details. a `GtkLinkButton` the new “visited” state The URI bound to this button. The 'visited' state of this button. A visited link is drawn in a different color. Emitted each time the `GtkLinkButton` is clicked. The default handler will call [method@Gtk.FileLauncher.launch] with the URI stored inside the [property@Gtk.LinkButton:uri] property. To override the default behavior, you can connect to the ::activate-link signal and stop the propagation of the signal by returning %TRUE from your handler. %TRUE if the signal has been handled The abstract base class for GTK's list widgets. # Shortcuts and Gestures `GtkListBase` supports the following keyboard shortcuts: - <kbd>Ctrl</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&sol;</kbd> selects all items. - <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&bsol;</kbd> unselects all items. The focused item is controlled by the navigation keys below, combined with the <kbd>Ctrl</kbd> modifier to prevent moving the selection, and the <kbd>Shift</kbd> modifier to extend the current selection. - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move the focus on the next item in the designed direction. - <kbd>Home</kbd> and <kbd>End</kbd> focus the first or last item. - <kbd>PgUp</kbd> and <kbd>PgDn</kbd> move the focus one page up or down. List item widgets support the following keyboard shortcuts: - <kbd>Enter</kbd> activates the item. - <kbd>␣</kbd> selects the item, with the same <kbd>Ctrl</kbd> and <kbd>Shift</kbd> modifiers combinations as the navigation keys. # Actions `GtkListBase` defines a set of built-in actions: - `list.scroll-to-item` moves the visible area to the item at given position with the minimum amount of scrolling required. If the item is already visible, nothing happens. - `list.select-item` changes the selection. - `list.select-all` selects all items in the model, if the selection model supports it. - `list.unselect-all` unselects all items in the model, if the selection model supports it. List item widgets install the following actions: - `listitem.select` changes selection if the item is selectable. - `listitem.scroll-to` moves the visible area of the list to this item with the minimum amount of scrolling required. The orientation of the list. See GtkOrientable:orientation for details. Shows a vertical list. <picture> <source srcset="list-box-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkListBox" src="list-box.png"> </picture> A `GtkListBox` only contains `GtkListBoxRow` children. These rows can by dynamically sorted and filtered, and headers can be added dynamically depending on the row content. It also allows keyboard and mouse navigation and selection like a typical list. Using `GtkListBox` is often an alternative to `GtkTreeView`, especially when the list contents has a more complicated layout than what is allowed by a `GtkCellRenderer`, or when the contents is interactive (i.e. has a button in it). Although a `GtkListBox` must have only `GtkListBoxRow` children, you can add any kind of widget to it via [method@Gtk.ListBox.prepend], [method@Gtk.ListBox.append] and [method@Gtk.ListBox.insert] and a `GtkListBoxRow` widget will automatically be inserted between the list and the widget. `GtkListBoxRows` can be marked as activatable or selectable. If a row is activatable, [signal@Gtk.ListBox::row-activated] will be emitted for it when the user tries to activate it. If it is selectable, the row will be marked as selected when the user tries to select it. # GtkListBox as GtkBuildable The `GtkListBox` implementation of the `GtkBuildable` interface supports setting a child as the placeholder by specifying “placeholder” as the “type” attribute of a `<child>` element. See [method@Gtk.ListBox.set_placeholder] for info. # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.ListBox::move-cursor] - [signal@Gtk.ListBox::select-all] - [signal@Gtk.ListBox::toggle-cursor-row] - [signal@Gtk.ListBox::unselect-all] # CSS nodes ``` list[.separators][.rich-list][.navigation-sidebar][.boxed-list] ╰── row[.activatable] ``` `GtkListBox` uses a single CSS node named list. It may carry the .separators style class, when the [property@Gtk.ListBox:show-separators] property is set. Each `GtkListBoxRow` uses a single CSS node named row. The row nodes get the .activatable style class added when appropriate. It may also carry the .boxed-list style class. In this case, the list will be automatically surrounded by a frame and have separators. The main list node may also carry style classes to select the style of [list presentation](section-list-widget.html#list-styles): .rich-list, .navigation-sidebar or .data-table. # Accessibility `GtkListBox` uses the [enum@Gtk.AccessibleRole.list] role and `GtkListBoxRow` uses the [enum@Gtk.AccessibleRole.list_item] role. Creates a new `GtkListBox` container. a new `GtkListBox` Append a widget to the list. If a sort function is set, the widget will actually be inserted at the calculated position. a `GtkListBox` the `GtkWidget` to add Binds @model to @box. If @box was already bound to a model, that previous binding is destroyed. The contents of @box are cleared and then filled with widgets that represent items from @model. @box is updated whenever @model changes. If @model is %NULL, @box is left empty. It is undefined to add or remove widgets directly (for example, with [method@Gtk.ListBox.insert]) while @box is bound to a model. Note that using a model is incompatible with the filtering and sorting functionality in `GtkListBox`. When using a model, filtering and sorting should be implemented by the model. a `GtkListBox` the `GListModel` to be bound to @box a function that creates widgets for items or %NULL in case you also passed %NULL as @model user data passed to @create_widget_func function for freeing @user_data Add a drag highlight to a row. This is a helper function for implementing DnD onto a `GtkListBox`. The passed in @row will be highlighted by setting the %GTK_STATE_FLAG_DROP_ACTIVE state and any previously highlighted row will be unhighlighted. The row will also be unhighlighted when the widget gets a drag leave event. a `GtkListBox` a `GtkListBoxRow` If a row has previously been highlighted via gtk_list_box_drag_highlight_row(), it will have the highlight removed. a `GtkListBox` Returns whether rows activate on single clicks. %TRUE if rows are activated on single click, %FALSE otherwise a `GtkListBox` Gets the adjustment (if any) that the widget uses to for vertical scrolling. the adjustment a `GtkListBox` Gets the n-th child in the list (not counting headers). If @index_ is negative or larger than the number of items in the list, %NULL is returned. the child `GtkWidget` a `GtkListBox` the index of the row Gets the row at the @y position. the row a `GtkListBox` position Gets the selected row, or %NULL if no rows are selected. Note that the box may allow multiple selection, in which case you should use [method@Gtk.ListBox.selected_foreach] to find all selected rows. the selected row a `GtkListBox` Creates a list of all selected children. A `GList` containing the `GtkWidget` for each selected child. Free with g_list_free() when done. a `GtkListBox` Gets the selection mode of the listbox. a `GtkSelectionMode` a `GtkListBox` Returns whether the list box should show separators between rows. %TRUE if the list box shows separators a `GtkListBox` Returns the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. the tab behavior a `GtkListBox` Insert the @child into the @box at @position. If a sort function is set, the widget will actually be inserted at the calculated position. If @position is -1, or larger than the total number of items in the @box, then the @child will be appended to the end. a `GtkListBox` the `GtkWidget` to add the position to insert @child in Update the filtering for all rows. Call this when result of the filter function on the @box is changed due to an external factor. For instance, this would be used if the filter function just looked for a specific search string and the entry with the search string has changed. a `GtkListBox` Update the separators for all rows. Call this when result of the header function on the @box is changed due to an external factor. a `GtkListBox` Update the sorting for all rows. Call this when result of the sort function on the @box is changed due to an external factor. a `GtkListBox` Prepend a widget to the list. If a sort function is set, the widget will actually be inserted at the calculated position. a `GtkListBox` the `GtkWidget` to add Removes a child from @box. a `GtkListBox` the child to remove Removes all rows from @box. This function does nothing if @box is backed by a model. a `GtkListBox` Select all children of @box, if the selection mode allows it. a `GtkListBox` Make @row the currently selected row. a `GtkListBox` The row to select Calls a function for each selected child. Note that the selection cannot be modified from within this function. a `GtkListBox` the function to call for each selected child user data to pass to the function If @single is %TRUE, rows will be activated when you click on them, otherwise you need to double-click. a `GtkListBox` a boolean Sets the adjustment (if any) that the widget uses to for vertical scrolling. For instance, this is used to get the page size for PageUp/Down key handling. In the normal case when the @box is packed inside a `GtkScrolledWindow` the adjustment from that will be picked up automatically, so there is no need to manually do that. a `GtkListBox` the adjustment By setting a filter function on the @box one can decide dynamically which of the rows to show. For instance, to implement a search function on a list that filters the original list to only show the matching rows. The @filter_func will be called for each row after the call, and it will continue to be called each time a row changes (via [method@Gtk.ListBoxRow.changed]) or when [method@Gtk.ListBox.invalidate_filter] is called. Note that using a filter function is incompatible with using a model (see [method@Gtk.ListBox.bind_model]). a `GtkListBox` callback that lets you filter which rows to show user data passed to @filter_func destroy notifier for @user_data Sets a header function. By setting a header function on the @box one can dynamically add headers in front of rows, depending on the contents of the row and its position in the list. For instance, one could use it to add headers in front of the first item of a new kind, in a list sorted by the kind. The @update_header can look at the current header widget using [method@Gtk.ListBoxRow.get_header] and either update the state of the widget as needed, or set a new one using [method@Gtk.ListBoxRow.set_header]. If no header is needed, set the header to %NULL. Note that you may get many calls @update_header to this for a particular row when e.g. changing things that don’t affect the header. In this case it is important for performance to not blindly replace an existing header with an identical one. The @update_header function will be called for each row after the call, and it will continue to be called each time a row changes (via [method@Gtk.ListBoxRow.changed]) and when the row before changes (either by [method@Gtk.ListBoxRow.changed] on the previous row, or when the previous row becomes a different row). It is also called for all rows when [method@Gtk.ListBox.invalidate_headers] is called. a `GtkListBox` callback that lets you add row headers user data passed to @update_header destroy notifier for @user_data Sets the placeholder widget that is shown in the list when it doesn't display any visible children. a `GtkListBox` a `GtkWidget` Sets how selection works in the listbox. a `GtkListBox` The `GtkSelectionMode` Sets whether the list box should show separators between rows. a `GtkListBox` %TRUE to show separators Sets a sort function. By setting a sort function on the @box one can dynamically reorder the rows of the list, based on the contents of the rows. The @sort_func will be called for each row after the call, and will continue to be called each time a row changes (via [method@Gtk.ListBoxRow.changed]) and when [method@Gtk.ListBox.invalidate_sort] is called. Note that using a sort function is incompatible with using a model (see [method@Gtk.ListBox.bind_model]). a `GtkListBox` the sort function user data passed to @sort_func destroy notifier for @user_data Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. a `GtkListBox` the tab behavior Unselect all children of @box, if the selection mode allows it. a `GtkListBox` Unselects a single row of @box, if the selection mode allows it. a `GtkListBox` the row to unselect Whether to accept unpaired release events. Determines whether children can be activated with a single click, or require a double-click. The selection mode used by the list box. Whether to show separators between rows. Behavior of the <kbd>Tab</kbd> key Emitted when the cursor row is activated. Emitted when the user initiates a cursor movement. The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifier does not. There are too many key combinations to list them all here. - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move by individual children - <kbd>Home</kbd>, <kbd>End</kbd> move to the ends of the box - <kbd>PgUp</kbd>, <kbd>PgDn</kbd> move vertically by pages the granularity of the move, as a `GtkMovementStep` the number of @step units to move whether to extend the selection whether to modify the selection Emitted when a row has been activated by the user. the activated row Emitted when a new row is selected, or (with a %NULL @row) when the selection is cleared. When the @box is using %GTK_SELECTION_MULTIPLE, this signal will not give you the full picture of selection changes, and you should use the [signal@Gtk.ListBox::selected-rows-changed] signal instead. the selected row Emitted to select all children of the box, if the selection mode permits it. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Ctrl</kbd>-<kbd>a</kbd>. Emitted when the set of selected rows changes. Emitted when the cursor row is toggled. The default bindings for this signal is <kbd>Ctrl</kbd>+<kbd>␣</kbd>. Emitted to unselect all children of the box, if the selection mode permits it. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Ctrl</kbd>-<kbd>Shift</kbd>-<kbd>a</kbd>. Called for list boxes that are bound to a `GListModel` with gtk_list_box_bind_model() for each item that gets added to the model. If the widget returned is not a #GtkListBoxRow widget, then the widget will be inserted as the child of an intermediate #GtkListBoxRow. a `GtkWidget` that represents @item the item from the model for which to create a widget for user data Will be called whenever the row changes or is added and lets you control if the row should be visible or not. %TRUE if the row should be visible, %FALSE otherwise the row that may be filtered user data A function used by gtk_list_box_selected_foreach(). It will be called on every selected child of the @box. a `GtkListBox` a `GtkListBoxRow` user data The kind of widget that can be added to a `GtkListBox`. [class@Gtk.ListBox] will automatically wrap its children in a `GtkListboxRow` when necessary. Creates a new `GtkListBoxRow`. a new `GtkListBoxRow` Marks @row as changed, causing any state that depends on this to be updated. This affects sorting, filtering and headers. Note that calls to this method must be in sync with the data used for the row functions. For instance, if the list is mirroring some external data set, and *two* rows changed in the external data set then when you call gtk_list_box_row_changed() on the first row the sort function must only read the new data for the first of the two changed rows, otherwise the resorting of the rows will be wrong. This generally means that if you don’t fully control the data model you have to duplicate the data that affects the listbox row functions into the row widgets themselves. Another alternative is to call [method@Gtk.ListBox.invalidate_sort] on any model change, but that is more expensive. a `GtkListBoxRow` Gets whether the row is activatable. %TRUE if the row is activatable a `GtkListBoxRow` Gets the child widget of @row. the child widget of @row a `GtkListBoxRow` Returns the current header of the @row. This can be used in a [callback@Gtk.ListBoxUpdateHeaderFunc] to see if there is a header set already, and if so to update the state of it. the current header a `GtkListBoxRow` Gets the current index of the @row in its `GtkListBox` container. the index of the @row, or -1 if the @row is not in a listbox a `GtkListBoxRow` Gets whether the row can be selected. %TRUE if the row is selectable a `GtkListBoxRow` Returns whether the child is currently selected in its `GtkListBox` container. %TRUE if @row is selected a `GtkListBoxRow` Set whether the row is activatable. a `GtkListBoxRow` %TRUE to mark the row as activatable Sets the child widget of @self. a `GtkListBoxRow` the child widget Sets the current header of the @row. This is only allowed to be called from a [callback@Gtk.ListBoxUpdateHeaderFunc]. It will replace any existing header in the row, and be shown in front of the row in the listbox. a `GtkListBoxRow` the header Set whether the row can be selected. a `GtkListBoxRow` %TRUE to mark the row as selectable Determines whether the ::row-activated signal will be emitted for this row. The child widget. Determines whether this row can be selected. This is a keybinding signal, which will cause this row to be activated. If you want to be notified when the user activates a row (by key or not), use the [signal@Gtk.ListBox::row-activated] signal on the row’s parent `GtkListBox`. The parent class. Compare two rows to determine which should be first. < 0 if @row1 should be before @row2, 0 if they are equal and > 0 otherwise the first row the second row user data Whenever @row changes or which row is before @row changes this is called, which lets you update the header on @row. You may remove or set a new one via [method@Gtk.ListBoxRow.set_header] or just change the state of the current header widget. the row to update the row before @row, or %NULL if it is first user data Used by list widgets to represent the headers they display. `GtkListHeader` objects are managed just like [class@Gtk.ListItem] objects via their factory, but provide a different set of properties suitable for managing the header instead of individual items. Gets the child previously set via gtk_list_header_set_child() or %NULL if none was set. The child a `GtkListHeader` Gets the end position in the model of the section that @self is currently the header for. If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. The end position of the section a `GtkListHeader` Gets the model item at the start of the section. This is the item that occupies the list model at position [property@Gtk.ListHeader:start]. If @self is unbound, this function returns %NULL. The item displayed a `GtkListHeader` Gets the the number of items in the section. If @self is unbound, 0 is returned. The number of items in the section a `GtkListHeader` Gets the start position in the model of the section that @self is currently the header for. If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. The start position of the section a `GtkListHeader` Sets the child to be used for this listitem. This function is typically called by applications when setting up a header so that the widget can be reused when binding it multiple times. a `GtkListHeader` The list item's child or %NULL to unset Widget used for display. The first position no longer part of this section. The item at the start of the section. Number of items in this section. First position of items in this section. Used by list widgets to represent items in a [iface@Gio.ListModel]. `GtkListItem` objects are managed by the list widget (with its factory) and cannot be created by applications, but they need to be populated by application code. This is done by calling [method@Gtk.ListItem.set_child]. `GtkListItem` objects exist in 2 stages: 1. The unbound stage where the listitem is not currently connected to an item in the list. In that case, the [property@Gtk.ListItem:item] property is set to `NULL`. 2. The bound stage where the listitem references an item from the list. The [property@Gtk.ListItem:item] property is not `NULL`. Gets the accessible description of @self. the accessible description a listitem Gets the accessible label of @self. the accessible label a listitem Checks if a listitem has been set to be activatable via [method@Gtk.ListItem.set_activatable]. true if the item is activatable a listitem Gets the child previously set via [method@Gtk.ListItem.set_child] or `NULL` if none was set. The child a listitem Checks if a listitem has been set to be focusable via [method@Gtk.ListItem.set_focusable]. true if the item is focusable a lits item Gets the model item that associated with @self. If @self is unbound, this function returns `NULL`. The item displayed a listitem Gets the position in the model that @self currently displays. If @self is unbound, `GTK_INVALID_LIST_POSITION` is returned. The position of this item a listitem Checks if a listitem has been set to be selectable via [method@Gtk.ListItem.set_selectable]. Do not confuse this function with [method@Gtk.ListItem.get_selected]. true if the item is selectable a listitem Checks if the item is displayed as selected. The selected state is maintained by the list widget and its model and cannot be set otherwise. true if the item is selected. a listitem Sets the accessible description for the listitem. The accessible description may be used by e.g. screen readers. a listitem the description Sets the accessible label for the listitem. The accessible label may be used by e.g. screen readers. a listitem the label Sets @self to be activatable. If an item is activatable, double-clicking on the item, using the Return key or calling [method@Gtk.Widget.activate] will activate the item. Activating instructs the containing view to handle activation. `GtkListView` for example will be emitting the [signal@Gtk.ListView::activate] signal. By default, listitems are activatable. a listitem if the item should be activatable Sets the child to be used for this listitem. This function is typically called by applications when setting up a listitem so that the widget can be reused when binding it multiple times. a listitem The listitem's child or `NULL` to unset Sets @self to be focusable. If an item is focusable, it can be focused using the keyboard. This works similar to [method@Gtk.Widget.set_focusable]. Note that if items are not focusable, the keyboard cannot be used to activate them and selecting only works if one of the listitem's children is focusable. By default, listitems are focusable. a listitem if the item should be focusable Sets @self to be selectable. If an item is selectable, clicking on the item or using the keyboard will try to select or unselect the item. If this succeeds is up to the model to determine, as it is managing the selected state. Note that this means that making an item non-selectable has no influence on the selected state at all. A non-selectable item may still be selected. By default, listitems are selectable. When rebinding them to a new item, they will also be reset to be selectable by GTK. a listitem if the item should be selectable The accessible description to set on the listitem. The accessible label to set on the listitem. If the item can be activated by the user. Widget used for display. If the item can be focused with the keyboard. Displayed item. Position of the item. If the item can be selected by the user. If the item is currently selected. Creates widgets for the items taken from a `GListModel`. This is one of the core concepts of handling list widgets such as [class@Gtk.ListView] or [class@Gtk.GridView]. The `GtkListItemFactory` is tasked with creating widgets for items taken from the model when the views need them and updating them as the items displayed by the view change. A view is usually only able to display anything after both a factory and a model have been set on the view. So it is important that you do not skip this step when setting up your first view. Because views do not display the whole list at once but only a few items, they only need to maintain a few widgets at a time. They will instruct the `GtkListItemFactory` to create these widgets and bind them to the items that are currently displayed. As the list model changes or the user scrolls to the list, the items will change and the view will instruct the factory to bind the widgets to those new items. The actual widgets used for displaying those widgets is provided by you. When the factory needs widgets created, it will create a `GtkListItem` and hand it to your code to set up a widget for. This list item will provide various properties with information about what item to display and provide you with some opportunities to configure its behavior. See the [class@Gtk.ListItem] documentation for further details. Various implementations of `GtkListItemFactory` exist to allow you different ways to provide those widgets. The most common implementations are [class@Gtk.BuilderListItemFactory] which takes a `GtkBuilder` .ui file and then creates widgets and manages everything automatically from the information in that file and [class@Gtk.SignalListItemFactory] which allows you to connect to signals with your own code and retain full control over how the widgets are setup and managed. A `GtkListItemFactory` is supposed to be final - that means its behavior should not change and the first widget created from it should behave the same way as the last widget created from it. If you intend to do changes to the behavior, it is recommended that you create a new `GtkListItemFactory` which will allow the views to recreate its widgets. Once you have chosen your factory and created it, you need to set it on the view widget you want to use it with, such as via [method@Gtk.ListView.set_factory]. Reusing factories across different views is allowed, but very uncommon. List of actions to perform when scrolling to items in a list widget. Don't do anything extra Focus the target item Select the target item and unselect all other items. A list-like data structure that can be used with the [class@Gtk.TreeView]. The `GtkListStore` object is a list model for use with a `GtkTreeView` widget. It implements the `GtkTreeModel` interface, and consequentialy, can use all of the methods available there. It also implements the `GtkTreeSortable` interface so it can be sorted by the view. Finally, it also implements the tree [drag](iface.TreeDragSource.html) and [drop](iface.TreeDragDest.html) interfaces. The `GtkListStore` can accept most `GType`s as a column type, though it can’t accept all custom types. Internally, it will keep a copy of data passed in (such as a string or a boxed pointer). Columns that accept `GObject`s are handled a little differently. The `GtkListStore` will keep a reference to the object instead of copying the value. As a result, if the object is modified, it is up to the application writer to call [method@Gtk.TreeModel.row_changed] to emit the [signal@Gtk.TreeModel::row_changed] signal. This most commonly affects lists with [class@Gdk.Texture]s stored. An example for creating a simple list store: ```c enum { COLUMN_STRING, COLUMN_INT, COLUMN_BOOLEAN, N_COLUMNS }; { GtkListStore *list_store; GtkTreePath *path; GtkTreeIter iter; int i; list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT, G_TYPE_BOOLEAN); for (i = 0; i < 10; i++) { char *some_data; some_data = get_some_data (i); // Add a new row to the model gtk_list_store_append (list_store, &iter); gtk_list_store_set (list_store, &iter, COLUMN_STRING, some_data, COLUMN_INT, i, COLUMN_BOOLEAN, FALSE, -1); // As the store will keep a copy of the string internally, // we free some_data. g_free (some_data); } // Modify a particular row path = gtk_tree_path_new_from_string ("4"); gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store), &iter, path); gtk_tree_path_free (path); gtk_list_store_set (list_store, &iter, COLUMN_BOOLEAN, TRUE, -1); } ``` `GtkListStore` is deprecated since GTK 4.10, and should not be used in newly written code. You should use [class@Gio.ListStore] instead, and the various list models provided by GTK. ## Performance Considerations Internally, the `GtkListStore` was originally implemented with a linked list with a tail pointer. As a result, it was fast at data insertion and deletion, and not fast at random data access. The `GtkListStore` sets the `GTK_TREE_MODEL_ITERS_PERSIST` flag, which means that `GtkTreeIter`s can be cached while the row exists. Thus, if access to a particular row is needed often and your code is expected to run on older versions of GTK, it is worth keeping the iter around. ## Atomic Operations It is important to note that only the methods gtk_list_store_insert_with_values() and gtk_list_store_insert_with_valuesv() are atomic, in the sense that the row is being appended to the store and the values filled in in a single operation with regard to `GtkTreeModel` signaling. In contrast, using e.g. gtk_list_store_append() and then gtk_list_store_set() will first create a row, which triggers the `GtkTreeModel::row-inserted` signal on `GtkListStore`. The row, however, is still empty, and any signal handler connecting to `GtkTreeModel::row-inserted` on this particular store should be prepared for the situation that the row might be empty. This is especially important if you are wrapping the `GtkListStore` inside a `GtkTreeModel`Filter and are using a `GtkTreeModel`FilterVisibleFunc. Using any of the non-atomic operations to append rows to the `GtkListStore` will cause the `GtkTreeModel`FilterVisibleFunc to be visited with an empty row first; the function must be prepared for that. ## GtkListStore as GtkBuildable The GtkListStore implementation of the [iface@Gtk.Buildable] interface allows to specify the model columns with a `<columns>` element that may contain multiple `<column>` elements, each specifying one model column. The “type” attribute specifies the data type for the column. Additionally, it is possible to specify content for the list store in the UI definition, with the `<data>` element. It can contain multiple `<row>` elements, each specifying to content for one row of the list model. Inside a `<row>`, the `<col>` elements specify the content for individual cells. Note that it is probably more common to define your models in the code, and one might consider it a layering violation to specify the content of a list store in a UI definition, data, not presentation, and common wisdom is to separate the two, as far as possible. An example of a UI Definition fragment for a list store: ```xml <object class="GtkListStore"> <columns> <column type="gchararray"/> <column type="gchararray"/> <column type="gint"/> </columns> <data> <row> <col id="0">John</col> <col id="1">Doe</col> <col id="2">25</col> </row> <row> <col id="0">Johan</col> <col id="1">Dahlin</col> <col id="2">50</col> </row> </data> </object> ``` Use [class@Gio.ListStore] instead Creates a new list store. The list store will have @n_columns columns, with each column using the given type passed to this function. Note that only types derived from standard GObject fundamental types are supported. As an example: ```c gtk_list_store_new (3, G_TYPE_INT, G_TYPE_STRING, GDK_TYPE_TEXTURE); ``` will create a new `GtkListStore` with three columns, of type `int`, `gchararray` and `GdkTexture`, respectively. Use [class@Gio.ListStore] instead a new `GtkListStore` number of columns in the list store all `GType` types for the columns, from first to last Creates a new `GtkListStore`. This function is meant to be used by language bindings. Use [class@Gio.ListStore] instead a new `GtkListStore` number of columns in the list store an array of `GType` types for the columns, from first to last Appends a new row to @list_store. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the appended row Removes all rows from the list store. Use list models a `GtkListStore`. Creates a new row at @position. @iter will be changed to point to this new row. If @position is -1 or is larger than the number of rows on the list, then the new row will be appended to the list. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the new row position to insert the new row, or -1 for last Inserts a new row after @sibling. If @sibling is %NULL, then the row will be prepended to the beginning of the list. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the new row A valid `GtkTreeIter` Inserts a new row before @sibling. If @sibling is %NULL, then the row will be appended to the end of the list. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the new row A valid `GtkTreeIter` Creates a new row at @position. @iter will be changed to point to this new row. If @position is -1, or larger than the number of rows in the list, then the new row will be appended to the list. The row will be filled with the values given to this function. Calling `gtk_list_store_insert_with_values (list_store, iter, position...)` has the same effect as calling: ```c static void insert_value (GtkListStore *list_store, GtkTreeIter *iter, int position) { gtk_list_store_insert (list_store, iter, position); gtk_list_store_set (list_store, iter // ... ); } ``` with the difference that the former will only emit `GtkTreeModel`::row-inserted once, while the latter will emit `GtkTreeModel`::row-inserted, `GtkTreeModel`::row-changed and, if the list store is sorted, `GtkTreeModel`::rows-reordered for every inserted value. Since emitting the `GtkTreeModel::rows-reordered` signal repeatedly can affect the performance of the program, gtk_list_store_insert_with_values() should generally be preferred when inserting rows in a sorted list store. Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the new row position to insert the new row, or -1 to append after existing rows pairs of column number and value, terminated with -1 A variant of gtk_list_store_insert_with_values() which takes the columns and values as two arrays, instead of varargs. This function is mainly intended for language-bindings. Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the new row position to insert the new row, or -1 for last an array of column numbers an array of GValues the length of the @columns and @values arrays Checks if the given iter is a valid iter for this `GtkListStore`. This function is slow. Only use it for debugging and/or testing purposes. Use list models %TRUE if the iter is valid, %FALSE if the iter is invalid. a list store the iterator to check Moves @iter in @store to the position after @position. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the start of the list. Use list models A `GtkListStore`. A `GtkTreeIter` A `GtkTreeIter` Moves @iter in @store to the position before @position. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the end of the list. Use list models A `GtkListStore`. A `GtkTreeIter` A `GtkTreeIter` Prepends a new row to @list_store. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the prepend row Removes the given row from the list store. After being removed, @iter is set to be the next valid row, or invalidated if it pointed to the last row in @list_store. Use list models %TRUE if @iter is valid, %FALSE if not. A `GtkListStore` A valid `GtkTreeIter` Reorders @store to follow the order indicated by @new_order. Note that this function only works with unsorted stores. Use list models A `GtkListStore`. an array of integers mapping the new position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos`. It must have exactly as many items as the list store’s length. Sets the value of one or more cells in the row referenced by @iter. The variable argument list should contain integer column numbers, each column number followed by the value to be set. The list is terminated by a -1. For example, to set column 0 with type %G_TYPE_STRING to “Foo”, you would write `gtk_list_store_set (store, iter, 0, "Foo", -1)`. The value will be referenced by the store if it is a %G_TYPE_OBJECT, and it will be copied if it is a %G_TYPE_STRING or %G_TYPE_BOXED. Use list models a `GtkListStore` row iterator pairs of column number and value, terminated with -1 Sets the types of the columns of a list store. This function is meant primarily for objects that inherit from `GtkListStore`, and should only be used when constructing a new instance. This function cannot be called after a row has been added, or a method on the `GtkTreeModel` interface is called. Use list models A `GtkListStore` Number of columns for the list store An array length n of `GType`s See gtk_list_store_set(); this version takes a va_list for use by language bindings. Use list models A `GtkListStore` A valid `GtkTreeIter` for the row being modified va_list of column/value pairs Sets the data in the cell specified by @iter and @column. The type of @value must be convertible to the type of the column. Use list models A `GtkListStore` A valid `GtkTreeIter` for the row being modified column number to modify new value for the cell A variant of gtk_list_store_set_valist() which takes the columns and values as two arrays, instead of varargs. This function is mainly intended for language-bindings and in case the number of columns to change is not known until run-time. Use list models A `GtkListStore` A valid `GtkTreeIter` for the row being modified an array of column numbers an array of GValues the length of the @columns and @values arrays Swaps @a and @b in @store. Note that this function only works with unsorted stores. Use list models A `GtkListStore`. A `GtkTreeIter` Another `GtkTreeIter` Used to configure the focus behavior in the `GTK_DIR_TAB_FORWARD` and `GTK_DIR_TAB_BACKWARD` direction, like the <kbd>Tab</kbd> key in a [class@Gtk.ListView]. Cycle through all focusable items of the list Cycle through a single list element, then move focus out of the list. Moving focus between items needs to be done with the arrow keys. Cycle only through a single cell, then move focus out of the list. Moving focus between cells needs to be done with the arrow keys. This is only relevant for cell-based widgets like #GtkColumnView, otherwise it behaves like `GTK_LIST_TAB_ITEM`. Presents a large dynamic list of items. `GtkListView` uses its factory to generate one row widget for each visible item and shows them in a linear display, either vertically or horizontally. The [property@Gtk.ListView:show-separators] property offers a simple way to display separators between the rows. `GtkListView` allows the user to select items according to the selection characteristics of the model. For models that allow multiple selected items, it is possible to turn on _rubberband selection_, using [property@Gtk.ListView:enable-rubberband]. If you need multiple columns with headers, see [class@Gtk.ColumnView]. To learn more about the list widget framework, see the [overview](section-list-widget.html). An example of using `GtkListView`: ```c static void setup_listitem_cb (GtkListItemFactory *factory, GtkListItem *list_item) { GtkWidget *image; image = gtk_image_new (); gtk_image_set_icon_size (GTK_IMAGE (image), GTK_ICON_SIZE_LARGE); gtk_list_item_set_child (list_item, image); } static void bind_listitem_cb (GtkListItemFactory *factory, GtkListItem *list_item) { GtkWidget *image; GAppInfo *app_info; image = gtk_list_item_get_child (list_item); app_info = gtk_list_item_get_item (list_item); gtk_image_set_from_gicon (GTK_IMAGE (image), g_app_info_get_icon (app_info)); } static void activate_cb (GtkListView *list, guint position, gpointer unused) { GAppInfo *app_info; app_info = g_list_model_get_item (G_LIST_MODEL (gtk_list_view_get_model (list)), position); g_app_info_launch (app_info, NULL, NULL, NULL); g_object_unref (app_info); } ... model = create_application_list (); factory = gtk_signal_list_item_factory_new (); g_signal_connect (factory, "setup", G_CALLBACK (setup_listitem_cb), NULL); g_signal_connect (factory, "bind", G_CALLBACK (bind_listitem_cb), NULL); list = gtk_list_view_new (GTK_SELECTION_MODEL (gtk_single_selection_new (model)), factory); g_signal_connect (list, "activate", G_CALLBACK (activate_cb), NULL); gtk_scrolled_window_set_child (GTK_SCROLLED_WINDOW (sw), list); ``` # Actions `GtkListView` defines a set of built-in actions: - `list.activate-item` activates the item at given position by emitting the [signal@Gtk.ListView::activate] signal. # CSS nodes ``` listview[.separators][.rich-list][.navigation-sidebar][.data-table] ├── row[.activatable] │ ├── row[.activatable] │ ┊ ╰── [rubberband] ``` `GtkListView` uses a single CSS node named `listview`. It may carry the `.separators` style class, when [property@Gtk.ListView:show-separators] property is set. Each child widget uses a single CSS node named `row`. If the [property@Gtk.ListItem:activatable] property is set, the corresponding row will have the `.activatable` style class. For rubberband selection, a node with name `rubberband` is used. The main listview node may also carry style classes to select the style of [list presentation](section-list-widget.html#list-styles): .rich-list, .navigation-sidebar or .data-table. # Accessibility `GtkListView` uses the [enum@Gtk.AccessibleRole.list] role, and the list items use the [enum@Gtk.AccessibleRole.list_item] role. Creates a new `GtkListView` that uses the given @factory for mapping items to widgets. The function takes ownership of the arguments, so you can write code like ```c list_view = gtk_list_view_new (create_model (), gtk_builder_list_item_factory_new_from_resource ("/resource.ui")); ``` a new `GtkListView` using the given @model and @factory the model to use The factory to populate items with Returns whether rows can be selected by dragging with the mouse. true if rubberband selection is enabled a listview Gets the factory that's currently used to populate list items. The factory in use a listview Gets the factory that's currently used to populate section headers. The factory in use a listview Gets the model that's currently used to read the items displayed. The model in use a listview Returns whether the listview should show separators between rows. true if the listview shows separators a listview Returns whether rows will be activated on single click and selected on hover. true if rows are activated on single click a listview Gets the behavior set for the <kbd>Tab</kbd> key. The behavior of the <kbd>Tab</kbd> key a listview Scrolls to the item at the given position and performs the actions specified in @flags. This function works no matter if the listview is shown or focused. If it isn't, then the changes will take effect once that happens. a listview position of the item. Must be less than the number of items in the view. actions to perform details of how to perform the scroll operation or %NULL to scroll into view Sets whether selections can be changed by dragging with the mouse. a listview whether to enable rubberband selection Sets the `GtkListItemFactory` to use for populating list items. a listview the factory to use Sets the `GtkListItemFactory` to use for populating the [class@Gtk.ListHeader] objects used in section headers. If this factory is set to `NULL`, the list will not show section headers. a listview the factory to use Sets the model to use. This must be a [iface@Gtk.SelectionModel] to use. a listview the model to use Sets whether the listview should show separators between rows. a listview whether to show separators Sets whether rows should be activated on single click and selected on hover. a listview whether to activate items on single click Sets the <kbd>Tab</kbd> key behavior. This influences how the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys move the focus in the listview. a listview The desired tab behavior Allow rubberband selection. Factory for populating list items. The factory must be for configuring [class@Gtk.ListItem] objects. Factory for creating header widgets. The factory must be for configuring [class@Gtk.ListHeader] objects. Model for the items displayed. Show separators between rows. Activate rows on single click and select them on hover. Behavior of the <kbd>Tab</kbd> key Emitted when a row has been activated by the user. Activation usually happens via the list.activate-item action of the `GtkListView`. This allows for a convenient way to handle activation in a listview. See [method@Gtk.ListItem.set_activatable] for details on how to use this signal. position of item to activate `GtkLockButton` is a widget to obtain and revoke authorizations needed to operate the controls. <picture> <source srcset="lockbutton-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkLockButton" src="lockbutton.png"> </picture> It is typically used in preference dialogs or control panels. The required authorization is represented by a `GPermission` object. Concrete implementations of `GPermission` may use PolicyKit or some other authorization framework. To obtain a PolicyKit-based `GPermission`, use `polkit_permission_new()`. If the user is not currently allowed to perform the action, but can obtain the permission, the widget looks like this: <picture> <source srcset="lockbutton-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An locked GtkLockButton" src="lockbutton.png"> </picture> and the user can click the button to request the permission. Depending on the platform, this may pop up an authentication dialog or ask the user to authenticate in some other way. Once the user has obtained the permission, the widget changes to this: <picture> <source srcset="lockbutton-unlocked-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An unlocked GtkLockButton" src="lockbutton-unlocked.png"> </picture> and the permission can be dropped again by clicking the button. If the user is not able to obtain the permission at all, the widget looks like this: <picture> <source srcset="lockbutton-sorry-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An unobtainable GtkLockButton" src="lockbutton-sorry.png"> </picture> If the user has the permission and cannot drop it, the button is hidden. The text (and tooltips) that are shown in the various cases can be adjusted with the [property@Gtk.LockButton:text-lock], [property@Gtk.LockButton:text-unlock], [property@Gtk.LockButton:tooltip-lock], [property@Gtk.LockButton:tooltip-unlock] and [property@Gtk.LockButton:tooltip-not-authorized] properties. This widget will be removed in GTK 5 Creates a new lock button which reflects the @permission. This widget will be removed in GTK 5 a new `GtkLockButton` a `GPermission` Obtains the `GPermission` object that controls @button. This widget will be removed in GTK 5 the `GPermission` of @button a `GtkLockButton` Sets the `GPermission` object that controls @button. This widget will be removed in GTK 5 a `GtkLockButton` a `GPermission` object The `GPermission object controlling this button. This widget will be removed in GTK 5 The text to display when prompting the user to lock. This widget will be removed in GTK 5 The text to display when prompting the user to unlock. This widget will be removed in GTK 5 The tooltip to display when prompting the user to lock. This widget will be removed in GTK 5 The tooltip to display when the user cannot obtain authorization. This widget will be removed in GTK 5 The tooltip to display when prompting the user to unlock. This widget will be removed in GTK 5 Like [func@get_major_version], but from the headers used at application compile time, rather than from the library linked against at application run time. Evaluates to the maximum length of a compose sequence. This macro is longer used by GTK. The default extension point name for media file. Like [func@get_micro_version], but from the headers used at application compile time, rather than from the library linked against at application run time. Like [func@get_minor_version], but from the headers used at application compile time, rather than from the library linked against at application run time. A list model that maps the items in another model to different items. `GtkMapListModel` uses a [callback@Gtk.MapListModelMapFunc]. Example: Create a list of `GtkEventControllers` ```c static gpointer map_to_controllers (gpointer widget, gpointer data) { gpointer result = gtk_widget_observe_controllers (widget); g_object_unref (widget); return result; } widgets = gtk_widget_observe_children (widget); controllers = gtk_map_list_model_new (widgets, map_to_controllers, NULL, NULL); model = gtk_flatten_list_model_new (GTK_TYPE_EVENT_CONTROLLER, controllers); ``` `GtkMapListModel` will attempt to discard the mapped objects as soon as they are no longer needed and recreate them if necessary. `GtkMapListModel` passes through sections from the underlying model. Creates a new `GtkMapListModel` for the given arguments. a new `GtkMapListModel` The model to map map function user data passed to @map_func destroy notifier for @user_data Gets the model that is currently being mapped or %NULL if none. The model that gets mapped a `GtkMapListModel` Checks if a map function is currently set on @self. %TRUE if a map function is set a `GtkMapListModel` Sets the function used to map items. The function will be called whenever an item needs to be mapped and must return the item to use for the given input item. Note that `GtkMapListModel` may call this function multiple times on the same item, because it may delete items it doesn't need anymore. GTK makes no effort to ensure that @map_func conforms to the item type of @self. It assumes that the caller knows what they are doing and the map function returns items of the appropriate type. a `GtkMapListModel` map function user data passed to @map_func destroy notifier for @user_data Sets the model to be mapped. GTK makes no effort to ensure that @model conforms to the item type expected by the map function. It assumes that the caller knows what they are doing and have set up an appropriate map function. a `GtkMapListModel` The model to be mapped If a map is set for this model The type of items. See [method@Gio.ListModel.get_item_type]. The model being mapped. The number of items. See [method@Gio.ListModel.get_n_items]. User function that is called to map an @item of the original model to an item expected by the map model. The returned items must conform to the item type of the model they are used with. The item to map to The item to map user data Shows controls for video playback. <picture> <source srcset="media-controls-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkMediaControls" src="media-controls.png"> </picture> Usually, `GtkMediaControls` is used as part of [class@Gtk.Video]. Creates a new `GtkMediaControls` managing the @stream passed to it. a new `GtkMediaControls` a `GtkMediaStream` to manage Gets the media stream managed by @controls or %NULL if none. The media stream managed by @controls a `GtkMediaControls` Sets the stream that is controlled by @controls. a `GtkMediaControls` widget a `GtkMediaStream` The media-stream managed by this object or %NULL if none. Implements the `GtkMediaStream` interface for files. This provides a simple way to play back video files with GTK. GTK provides a GIO extension point for `GtkMediaFile` implementations to allow for external implementations using various media frameworks. GTK itself includes an implementation using GStreamer. Creates a new empty media file. a new `GtkMediaFile` Creates a new media file to play @file. a new `GtkMediaFile` playing @file The file to play Creates a new media file for the given filename. This is a utility function that converts the given @filename to a `GFile` and calls [ctor@Gtk.MediaFile.new_for_file]. a new `GtkMediaFile` playing @filename filename to open Creates a new media file to play @stream. If you want the resulting media to be seekable, the stream should implement the `GSeekable` interface. a new `GtkMediaFile` The stream to play Creates a new new media file for the given resource. This is a utility function that converts the given @resource to a `GFile` and calls [ctor@Gtk.MediaFile.new_for_file]. a new `GtkMediaFile` playing @resource_path resource path to open Resets the media file to be empty. a `GtkMediaFile` Returns the file that @self is currently playing from. When @self is not playing or not playing from a file, %NULL is returned. The currently playing file a `GtkMediaFile` Returns the stream that @self is currently playing from. When @self is not playing or not playing from a stream, %NULL is returned. The currently playing stream a `GtkMediaFile` Sets the `GtkMediaFile` to play the given file. If any file is still playing, stop playing it. a `GtkMediaFile` the file to play Sets the `GtkMediaFile` to play the given file. This is a utility function that converts the given @filename to a `GFile` and calls [method@Gtk.MediaFile.set_file]. a `GtkMediaFile` name of file to play Sets the `GtkMediaFile` to play the given stream. If anything is still playing, stop playing it. Full control about the @stream is assumed for the duration of playback. The stream will not be closed. a `GtkMediaFile` the stream to play from Sets the `GtkMediaFile` to play the given resource. This is a utility function that converts the given @resource_path to a `GFile` and calls [method@Gtk.MediaFile.set_file]. a `GtkMediaFile` path to resource to play The file being played back or %NULL if not playing a file. The stream being played back or %NULL if not playing a stream. This is %NULL when playing a file. The integration point for media playback inside GTK. GTK provides an implementation of the `GtkMediaStream` interface that is called [class@Gtk.MediaFile]. Apart from application-facing API for stream playback, `GtkMediaStream` has a number of APIs that are only useful for implementations and should not be used in applications: [method@Gtk.MediaStream.prepared], [method@Gtk.MediaStream.unprepared], [method@Gtk.MediaStream.update], [method@Gtk.MediaStream.ended], [method@Gtk.MediaStream.seek_success], [method@Gtk.MediaStream.seek_failed], [method@Gtk.MediaStream.gerror], [method@Gtk.MediaStream.error], [method@Gtk.MediaStream.error_valist]. Pauses playback of the stream. If the stream is not playing, do nothing. a `GtkMediaStream` Called by users to attach the media stream to a `GdkSurface` they manage. The stream can then access the resources of @surface for its rendering purposes. In particular, media streams might want to create a `GdkGLContext` or sync to the `GdkFrameClock`. Whoever calls this function is responsible for calling [method@Gtk.MediaStream.unrealize] before either the stream or @surface get destroyed. Multiple calls to this function may happen from different users of the video, even with the same @surface. Each of these calls must be followed by its own call to [method@Gtk.MediaStream.unrealize]. It is not required to call this function to make a media stream work. a `GtkMediaStream` a `GdkSurface` Start a seek operation on @self to @timestamp. If @timestamp is out of range, it will be clamped. Seek operations may not finish instantly. While a seek operation is in process, the [property@Gtk.MediaStream:seeking] property will be set. When calling gtk_media_stream_seek() during an ongoing seek operation, the new seek will override any pending seek. a `GtkMediaStream` timestamp to seek to. Undoes a previous call to gtk_media_stream_realize(). This causes the stream to release all resources it had allocated from @surface. a `GtkMediaStream` previously realized the `GdkSurface` the stream was realized with Pauses the media stream and marks it as ended. This is a hint only, calls to [method@Gtk.MediaStream.play] may still happen. The media stream must be prepared when this function is called. Use [method@Gtk.MediaStream.stream_ended] instead a `GtkMediaStream` Sets @self into an error state using a printf()-style format string. This is a utility function that calls [method@Gtk.MediaStream.gerror]. See that function for details. a `GtkMediaStream` error domain error code printf()-style format for error message parameters for message format Sets @self into an error state using a printf()-style format string. This is a utility function that calls [method@Gtk.MediaStream.gerror]. See that function for details. a `GtkMediaStream` error domain error code printf()-style format for error message `va_list` of parameters for the message format Sets @self into an error state. This will pause the stream (you can check for an error via [method@Gtk.MediaStream.get_error] in your GtkMediaStream.pause() implementation), abort pending seeks and mark the stream as prepared. if the stream is already in an error state, this call will be ignored and the existing error will be retained. To unset an error, the stream must be reset via a call to [method@Gtk.MediaStream.unprepared]. a `GtkMediaStream` the `GError` to set Gets the duration of the stream. If the duration is not known, 0 will be returned. the duration of the stream or 0 if not known. a `GtkMediaStream` Returns whether the streams playback is finished. %TRUE if playback is finished a `GtkMediaStream` If the stream is in an error state, returns the `GError` explaining that state. Any type of error can be reported here depending on the implementation of the media stream. A media stream in an error cannot be operated on, calls like [method@Gtk.MediaStream.play] or [method@Gtk.MediaStream.seek] will not have any effect. `GtkMediaStream` itself does not provide a way to unset an error, but implementations may provide options. For example, a [class@Gtk.MediaFile] will unset errors when a new source is set, e.g. with [method@Gtk.MediaFile.set_file]. %NULL if not in an error state or the `GError` of the stream a `GtkMediaStream` Returns whether the stream is set to loop. See [method@Gtk.MediaStream.set_loop] for details. %TRUE if the stream should loop a `GtkMediaStream` Returns whether the audio for the stream is muted. See [method@Gtk.MediaStream.set_muted] for details. %TRUE if the stream is muted a `GtkMediaStream` Return whether the stream is currently playing. %TRUE if the stream is playing a `GtkMediaStream` Returns the current presentation timestamp in microseconds. the timestamp in microseconds a `GtkMediaStream` Returns the volume of the audio for the stream. See [method@Gtk.MediaStream.set_volume] for details. volume of the stream from 0.0 to 1.0 a `GtkMediaStream` Returns whether the stream has audio. %TRUE if the stream has audio a `GtkMediaStream` Returns whether the stream has video. %TRUE if the stream has video a `GtkMediaStream` Returns whether the stream has finished initializing. At this point the existence of audio and video is known. %TRUE if the stream is prepared a `GtkMediaStream` Checks if a stream may be seekable. This is meant to be a hint. Streams may not allow seeking even if this function returns %TRUE. However, if this function returns %FALSE, streams are guaranteed to not be seekable and user interfaces may hide controls that allow seeking. It is allowed to call [method@Gtk.MediaStream.seek] on a non-seekable stream, though it will not do anything. %TRUE if the stream may support seeking a `GtkMediaStream` Checks if there is currently a seek operation going on. %TRUE if a seek operation is ongoing. a `GtkMediaStream` Pauses playback of the stream. If the stream is not playing, do nothing. a `GtkMediaStream` Starts playing the stream. If the stream is in error or already playing, do nothing. a `GtkMediaStream` Same as gtk_media_stream_stream_prepared(). Use [method@Gtk.MediaStream.stream_prepared] instead. a `GtkMediaStream` %TRUE if the stream should advertise audio support %TRUE if the stream should advertise video support %TRUE if the stream should advertise seekability The duration of the stream or 0 if unknown Called by users to attach the media stream to a `GdkSurface` they manage. The stream can then access the resources of @surface for its rendering purposes. In particular, media streams might want to create a `GdkGLContext` or sync to the `GdkFrameClock`. Whoever calls this function is responsible for calling [method@Gtk.MediaStream.unrealize] before either the stream or @surface get destroyed. Multiple calls to this function may happen from different users of the video, even with the same @surface. Each of these calls must be followed by its own call to [method@Gtk.MediaStream.unrealize]. It is not required to call this function to make a media stream work. a `GtkMediaStream` a `GdkSurface` Start a seek operation on @self to @timestamp. If @timestamp is out of range, it will be clamped. Seek operations may not finish instantly. While a seek operation is in process, the [property@Gtk.MediaStream:seeking] property will be set. When calling gtk_media_stream_seek() during an ongoing seek operation, the new seek will override any pending seek. a `GtkMediaStream` timestamp to seek to. Ends a seek operation started via GtkMediaStream.seek() as a failure. This will not cause an error on the stream and will assume that playback continues as if no seek had happened. See [method@Gtk.MediaStream.seek_success] for the other way of ending a seek. a `GtkMediaStream` Ends a seek operation started via GtkMediaStream.seek() successfully. This function will unset the GtkMediaStream:ended property if it was set. See [method@Gtk.MediaStream.seek_failed] for the other way of ending a seek. a `GtkMediaStream` Sets whether the stream should loop. In this case, it will attempt to restart playback from the beginning instead of stopping at the end. Not all streams may support looping, in particular non-seekable streams. Those streams will ignore the loop setting and just end. a `GtkMediaStream` %TRUE if the stream should loop Sets whether the audio stream should be muted. Muting a stream will cause no audio to be played, but it does not modify the volume. This means that muting and then unmuting the stream will restore the volume settings. If the stream has no audio, calling this function will still work but it will not have an audible effect. a `GtkMediaStream` %TRUE if the stream should be muted Starts or pauses playback of the stream. a `GtkMediaStream` whether to start or pause playback Sets the volume of the audio stream. This function call will work even if the stream is muted. The given @volume should range from 0.0 for silence to 1.0 for as loud as possible. Values outside of this range will be clamped to the nearest value. If the stream has no audio or is muted, calling this function will still work but it will not have an immediate audible effect. When the stream is unmuted, the new volume setting will take effect. a `GtkMediaStream` New volume of the stream from 0.0 to 1.0 Pauses the media stream and marks it as ended. This is a hint only, calls to [method@Gtk.MediaStream.play] may still happen. The media stream must be prepared when this function is called. a `GtkMediaStream` Called by `GtkMediaStream` implementations to advertise the stream being ready to play and providing details about the stream. Note that the arguments are hints. If the stream implementation cannot determine the correct values, it is better to err on the side of caution and return %TRUE. User interfaces will use those values to determine what controls to show. This function may not be called again until the stream has been reset via [method@Gtk.MediaStream.stream_unprepared]. a `GtkMediaStream` %TRUE if the stream should advertise audio support %TRUE if the stream should advertise video support %TRUE if the stream should advertise seekability The duration of the stream or 0 if unknown Resets a given media stream implementation. [method@Gtk.MediaStream.stream_prepared] can then be called again. This function will also reset any error state the stream was in. a `GtkMediaStream` Same as gtk_media_stream_stream_unprepared(). Use [method@Gtk.MediaStream.stream_unprepared] instead. a `GtkMediaStream` Undoes a previous call to gtk_media_stream_realize(). This causes the stream to release all resources it had allocated from @surface. a `GtkMediaStream` previously realized the `GdkSurface` the stream was realized with Media stream implementations should regularly call this function to update the timestamp reported by the stream. It is up to implementations to call this at the frequency they deem appropriate. The media stream must be prepared when this function is called. a `GtkMediaStream` the new timestamp The stream's duration in microseconds or 0 if unknown. Set when playback has finished. %NULL for a properly working stream or the `GError` that the stream is in. Whether the stream contains audio. Whether the stream contains video. Try to restart the media from the beginning once it ended. Whether the audio stream should be muted. Whether the stream is currently playing. Whether the stream has finished initializing and existence of audio and video is known. Set unless the stream is known to not support seeking. Set while a seek is in progress. The current presentation timestamp in microseconds. Volume of the audio stream. a `GtkMediaStream` a `GtkMediaStream` timestamp to seek to. a `GtkMediaStream` a `GdkSurface` a `GtkMediaStream` previously realized the `GdkSurface` the stream was realized with Displays a popup when clicked. <picture> <source srcset="menu-button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkMenuButton" src="menu-button.png"> </picture> This popup can be provided either as a `GtkPopover` or as an abstract `GMenuModel`. The `GtkMenuButton` widget can show either an icon (set with the [property@Gtk.MenuButton:icon-name] property) or a label (set with the [property@Gtk.MenuButton:label] property). If neither is explicitly set, a [class@Gtk.Image] is automatically created, using an arrow image oriented according to [property@Gtk.MenuButton:direction] or the generic “open-menu-symbolic” icon if the direction is not set. The positioning of the popup is determined by the [property@Gtk.MenuButton:direction] property of the menu button. For menus, the [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties of the menu are also taken into account. For example, when the direction is %GTK_ARROW_DOWN and the horizontal alignment is %GTK_ALIGN_START, the menu will be positioned below the button, with the starting edge (depending on the text direction) of the menu aligned with the starting edge of the button. If there is not enough space below the button, the menu is popped up above the button instead. If the alignment would move part of the menu offscreen, it is “pushed in”. | | start | center | end | | - | --- | --- | --- | | **down** | ![](down-start.png) | ![](down-center.png) | ![](down-end.png) | | **up** | ![](up-start.png) | ![](up-center.png) | ![](up-end.png) | | **left** | ![](left-start.png) | ![](left-center.png) | ![](left-end.png) | | **right** | ![](right-start.png) | ![](right-center.png) | ![](right-end.png) | # CSS nodes ``` menubutton ╰── button.toggle ╰── <content> ╰── [arrow] ``` `GtkMenuButton` has a single CSS node with name `menubutton` which contains a `button` node with a `.toggle` style class. If the button contains an icon, it will have the `.image-button` style class, if it contains text, it will have `.text-button` style class. If an arrow is visible in addition to an icon, text or a custom child, it will also have `.arrow-button` style class. Inside the toggle button content, there is an `arrow` node for the indicator, which will carry one of the `.none`, `.up`, `.down`, `.left` or `.right` style classes to indicate the direction that the menu will appear in. The CSS is expected to provide a suitable image for each of these cases using the `-gtk-icon-source` property. Optionally, the `menubutton` node can carry the `.circular` style class to request a round appearance. # Accessibility `GtkMenuButton` uses the [enum@Gtk.AccessibleRole.button] role. Creates a new `GtkMenuButton` widget with downwards-pointing arrow as the only child. You can replace the child widget with another `GtkWidget` should you wish to. The newly created `GtkMenuButton` Returns whether the menu button is active. TRUE if the button is active a `GtkMenuButton` Gets whether to show a dropdown arrow even when using an icon or a custom child. whether to show a dropdown arrow even when using an icon or a custom child. a `GtkMenuButton` Retrieves whether the button can be smaller than the natural size of its contents. true if the button can shrink, and false otherwise a button Gets the child widget of @menu_button. the child widget of @menu_button a `GtkMenuButton` Returns the direction the popup will be pointing at when popped up. a `GtkArrowType` value a `GtkMenuButton` Returns whether the button has a frame. %TRUE if the button has a frame a `GtkMenuButton` Gets the name of the icon shown in the button. the name of the icon shown in the button a `GtkMenuButton` Gets the label shown in the button the label shown in the button a `GtkMenuButton` Returns the `GMenuModel` used to generate the popup. a `GMenuModel` a `GtkMenuButton` Returns the `GtkPopover` that pops out of the button. If the button is not using a `GtkPopover`, this function returns %NULL. a `GtkPopover` or %NULL a `GtkMenuButton` Returns whether the menu button acts as a primary menu. %TRUE if the button is a primary menu a `GtkMenuButton` Returns whether an embedded underline in the text indicates a mnemonic. %TRUE whether an embedded underline in the text indicates the mnemonic accelerator keys. a `GtkMenuButton` Dismiss the menu. a `GtkMenuButton` Pop up the menu. a `GtkMenuButton` Sets whether the menu button is active. a `GtkMenuButton` whether the menu button is active Sets whether to show a dropdown arrow even when using an icon or a custom child. a `GtkMenuButton` whether to show a dropdown arrow even when using an icon or a custom child Sets whether the button size can be smaller than the natural size of its contents. For text buttons, setting @can_shrink to true will ellipsize the label. For icon buttons, this function has no effect. a menu button whether the button can shrink Sets the child widget of @menu_button. Setting a child resets [property@Gtk.MenuButton:label] and [property@Gtk.MenuButton:icon-name]. If [property@Gtk.MenuButton:always-show-arrow] is set to `TRUE` and [property@Gtk.MenuButton:direction] is not `GTK_ARROW_NONE`, a dropdown arrow will be shown next to the child. a `GtkMenuButton` the child widget Sets @func to be called when a popup is about to be shown. @func should use one of - [method@Gtk.MenuButton.set_popover] - [method@Gtk.MenuButton.set_menu_model] to set a popup for @menu_button. If @func is non-%NULL, @menu_button will always be sensitive. Using this function will not reset the menu widget attached to @menu_button. Instead, this can be done manually in @func. a `GtkMenuButton` function to call when a popup is about to be shown, but none has been provided via other means, or %NULL to reset to default behavior user data to pass to @func destroy notify for @user_data Sets the direction in which the popup will be popped up. If the button is automatically populated with an arrow icon, its direction will be changed to match. If the does not fit in the available space in the given direction, GTK will its best to keep it inside the screen and fully visible. If you pass %GTK_ARROW_NONE for a @direction, the popup will behave as if you passed %GTK_ARROW_DOWN (although you won’t see any arrows). a `GtkMenuButton` a `GtkArrowType` Sets the style of the button. a `GtkMenuButton` whether the button should have a visible frame Sets the name of an icon to show inside the menu button. Setting icon name resets [property@Gtk.MenuButton:label] and [property@Gtk.MenuButton:child]. If [property@Gtk.MenuButton:always-show-arrow] is set to `TRUE` and [property@Gtk.MenuButton:direction] is not `GTK_ARROW_NONE`, a dropdown arrow will be shown next to the icon. a `GtkMenuButton` the icon name Sets the label to show inside the menu button. Setting a label resets [property@Gtk.MenuButton:icon-name] and [property@Gtk.MenuButton:child]. If [property@Gtk.MenuButton:direction] is not `GTK_ARROW_NONE`, a dropdown arrow will be shown next to the label. a `GtkMenuButton` the label Sets the `GMenuModel` from which the popup will be constructed. If @menu_model is %NULL, the button is disabled. A [class@Gtk.Popover] will be created from the menu model with [ctor@Gtk.PopoverMenu.new_from_model]. Actions will be connected as documented for this function. If [property@Gtk.MenuButton:popover] is already set, it will be dissociated from the @menu_button, and the property is set to %NULL. a `GtkMenuButton` a `GMenuModel`, or %NULL to unset and disable the button Sets the `GtkPopover` that will be popped up when the @menu_button is clicked. If @popover is %NULL, the button is disabled. If [property@Gtk.MenuButton:menu-model] is set, the menu model is dissociated from the @menu_button, and the property is set to %NULL. a `GtkMenuButton` a `GtkPopover`, or %NULL to unset and disable the button Sets whether menu button acts as a primary menu. Primary menus can be opened with the <kbd>F10</kbd> key. a `GtkMenuButton` whether the menubutton should act as a primary menu If true, an underline in the text indicates a mnemonic. a `GtkMenuButton` %TRUE if underlines in the text indicate mnemonics Whether the menu button is active. Whether to show a dropdown arrow even when using an icon or a custom child. Whether the size of the button can be made smaller than the natural size of its contents. The child widget. The `GtkArrowType` representing the direction in which the menu or popover will be popped out. Whether the button has a frame. The name of the icon used to automatically populate the button. The label for the button. The `GMenuModel` from which the popup will be created. See [method@Gtk.MenuButton.set_menu_model] for the interaction with the [property@Gtk.MenuButton:popover] property. The `GtkPopover` that will be popped up when the button is clicked. Whether the menu button acts as a primary menu. Primary menus can be opened using the <kbd>F10</kbd> key If set an underscore in the text indicates a mnemonic. Emitted to when the menu button is activated. The `::activate` signal on `GtkMenuButton` is an action signal and emitting it causes the button to pop up its menu. User-provided callback function to create a popup for a `GtkMenuButton` on demand. This function is called when the popup of @menu_button is shown, but none has been provided via [method@Gtk.MenuButton.set_popover] or [method@Gtk.MenuButton.set_menu_model]. the `GtkMenuButton` User data passed to gtk_menu_button_set_create_popup_func() `GtkMessageDialog` presents a dialog with some message text. <picture> <source srcset="messagedialog-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkMessageDialog" src="messagedialog.png"> </picture> It’s simply a convenience widget; you could construct the equivalent of `GtkMessageDialog` from `GtkDialog` without too much effort, but `GtkMessageDialog` saves typing. The easiest way to do a modal message dialog is to use the %GTK_DIALOG_MODAL flag, which will call [method@Gtk.Window.set_modal] internally. The dialog will prevent interaction with the parent window until it's hidden or destroyed. You can use the [signal@Gtk.Dialog::response] signal to know when the user dismissed the dialog. An example for using a modal dialog: ```c GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT | GTK_DIALOG_MODAL; dialog = gtk_message_dialog_new (parent_window, flags, GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, "Error reading “%s”: %s", filename, g_strerror (errno)); // Destroy the dialog when the user responds to it // (e.g. clicks a button) g_signal_connect (dialog, "response", G_CALLBACK (gtk_window_destroy), NULL); ``` You might do a non-modal `GtkMessageDialog` simply by omitting the %GTK_DIALOG_MODAL flag: ```c GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_message_dialog_new (parent_window, flags, GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, "Error reading “%s”: %s", filename, g_strerror (errno)); // Destroy the dialog when the user responds to it // (e.g. clicks a button) g_signal_connect (dialog, "response", G_CALLBACK (gtk_window_destroy), NULL); ``` # GtkMessageDialog as GtkBuildable The `GtkMessageDialog` implementation of the `GtkBuildable` interface exposes the message area as an internal child with the name “message_area”. Use [class@Gtk.AlertDialog] instead Creates a new message dialog. This is a simple dialog with some text the user may want to see. When the user clicks a button a “response” signal is emitted with response IDs from [enum@Gtk.ResponseType]. See [class@Gtk.Dialog] for more details. Use [class@Gtk.AlertDialog] instead a new `GtkMessageDialog` transient parent flags type of message set of buttons to use printf()-style format string arguments for @message_format Creates a new message dialog. This is a simple dialog with some text that is marked up with Pango markup. When the user clicks a button a “response” signal is emitted with response IDs from [enum@Gtk.ResponseType]. See [class@Gtk.Dialog] for more details. Special XML characters in the printf() arguments passed to this function will automatically be escaped as necessary. (See g_markup_printf_escaped() for how this is implemented.) Usually this is what you want, but if you have an existing Pango markup string that you want to use literally as the label, then you need to use [method@Gtk.MessageDialog.set_markup] instead, since you can’t pass the markup string either as the format (it might contain “%” characters) or as a string argument. ```c GtkWidget *dialog; GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_message_dialog_new (parent_window, flags, GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, NULL); gtk_message_dialog_set_markup (GTK_MESSAGE_DIALOG (dialog), markup); ``` Use [class@Gtk.AlertDialog] instead a new `GtkMessageDialog` transient parent flags type of message set of buttons to use printf()-style format string arguments for @message_format Sets the secondary text of the message dialog. The @message_format is assumed to contain Pango markup. Due to an oversight, this function does not escape special XML characters like [ctor@Gtk.MessageDialog.new_with_markup] does. Thus, if the arguments may contain special XML characters, you should use g_markup_printf_escaped() to escape it. ```c char *msg; msg = g_markup_printf_escaped (message_format, ...); gtk_message_dialog_format_secondary_markup (message_dialog, "%s", msg); g_free (msg); ``` Use [class@Gtk.AlertDialog] instead a `GtkMessageDialog` printf()-style string with Pango markup arguments for @message_format Sets the secondary text of the message dialog. Use [class@Gtk.AlertDialog] instead a `GtkMessageDialog` printf()-style format string arguments for @message_format Returns the message area of the dialog. This is the box where the dialog’s primary and secondary labels are packed. You can add your own extra content to that box and it will appear below those labels. See [method@Gtk.Dialog.get_content_area] for the corresponding function in the parent [class@Gtk.Dialog]. Use [class@Gtk.AlertDialog] instead A `GtkBox` corresponding to the “message area” in the @message_dialog a `GtkMessageDialog` Sets the text of the message dialog. Use [class@Gtk.AlertDialog] instead a `GtkMessageDialog` string with Pango markup Set of buttons to display on the dialog. The `GtkBox` that corresponds to the message area of this dialog. See [method@Gtk.MessageDialog.get_message_area] for a detailed description of this area. The type of the message. The secondary text of the message dialog. %TRUE if the secondary text of the dialog includes Pango markup. See [func@Pango.parse_markup]. The primary text of the message dialog. If the dialog has a secondary text, this will appear as the title. %TRUE if the primary text of the dialog includes Pango markup. See [func@Pango.parse_markup]. The type of message being displayed in a [class@MessageDialog]. Informational message Non-fatal warning message Question requiring a choice Fatal error message None of the above Activates a widget with a mnemonic. This means that [method@Gtk.Widget.mnemonic_activate] is called. Gets the mnemonic action. This is an action that calls gtk_widget_mnemonic_activate() on the given widget upon activation. The mnemonic action Triggers when a specific mnemonic is pressed. Mnemonics require a *mnemonic modifier* (typically <kbd>Alt</kbd>) to be pressed together with the mnemonic key. Creates a `GtkShortcutTrigger` that will trigger whenever the key with the given @keyval is pressed and mnemonics have been activated. Mnemonics are activated by calling code when a key event with the right modifiers is detected. A new `GtkShortcutTrigger` The keyval to trigger for Gets the keyval that must be pressed to succeed triggering @self. the keyval a mnemonic `GtkShortcutTrigger` The key value for the trigger. Asks the user for passwords and other information required to mount a volume. `GtkMountOperation` is needed when mounting volumes: It is an implementation of `GMountOperation` that can be used with GIO functions for mounting volumes such as [method@Gio.File.mount_enclosing_volume], [method@Gio.File.mount_mountable], [method@Gio.Volume.mount], [method@Gio.Mount.unmount_with_operation] and others. When necessary, `GtkMountOperation` shows dialogs to let the user enter passwords, ask questions or show processes blocking unmount. Creates a new `GtkMountOperation`. a new `GtkMountOperation` transient parent of the window Gets the display on which windows of the `GtkMountOperation` will be shown. the display on which windows of @op are shown a `GtkMountOperation` Gets the transient parent used by the `GtkMountOperation`. the transient parent for windows shown by @op a `GtkMountOperation` Returns whether the `GtkMountOperation` is currently displaying a window. %TRUE if @op is currently displaying a window a `GtkMountOperation` Sets the display to show windows of the `GtkMountOperation` on. a `GtkMountOperation` a `GdkDisplay` Sets the transient parent for windows shown by the `GtkMountOperation`. a `GtkMountOperation` transient parent of the window The display where dialogs will be shown. Whether a dialog is currently shown. The parent window. The parent class. Passed as argument to various keybinding signals for moving the cursor position. Move forward or back by graphemes Move left or right by graphemes Move forward or back by words Move up or down lines (wrapped lines) Move to either end of a line Move up or down paragraphs (newline-ended lines) Move to either end of a paragraph Move by pages Move to ends of the buffer Move horizontally by pages Base class for filters that combine multiple filters. Adds a filter. a multi filter a filter to add Removes a filter. If @position is larger than the number of filters, nothing happens. a multi filter position of filter to remove The type of items. See [method@Gio.ListModel.get_item_type]. The number of items. See [method@Gio.ListModel.get_n_items]. A selection model that allows selecting multiple elements. Creates a new selection to handle @model. a new `GtkMultiSelection` the `GListModel` to manage Returns the underlying model of @self. the underlying model a `GtkMultiSelection` Sets the model that @self should wrap. If @model is %NULL, @self will be empty. a `GtkMultiSelection` A `GListModel` to wrap The type of items. See [method@Gio.ListModel.get_item_type]. The list managed by this selection. The number of items. See [method@Gio.ListModel.get_n_items]. Combines multiple sorters by trying them in turn. If the first sorter compares two items as equal, the second is tried next, and so on. Creates a new multi sorter. This sorter compares items by trying each of the sorters in turn, until one returns non-zero. In particular, if no sorter has been added to it, it will always compare items as equal. a new `GtkMultiSorter` Add @sorter to @self to use for sorting at the end. @self will consult all existing sorters before it will sort with the given @sorter. a `GtkMultiSorter` a sorter to add Removes the sorter at the given @position from the list of sorter used by @self. If @position is larger than the number of sorters, nothing happens. a `GtkMultiSorter` position of sorter to remove The type of items. See [method@Gio.ListModel.get_item_type]. The number of items. See [method@Gio.ListModel.get_n_items]. Activates a named action. See [method@Gtk.WidgetClass.install_action] and [method@Gtk.Widget.insert_action_group] for ways to associate named actions with widgets. Creates an action that when activated, activates the named action on the widget. It also passes the given arguments to it. See [method@Gtk.Widget.insert_action_group] for how to add actions to widgets. a new `GtkShortcutAction` the detailed name of the action Returns the name of the action that will be activated. the name of the action to activate a named action The name of the action to activate. An interface for widgets that have their own [class@Gdk.Surface]. The obvious example of a `GtkNative` is `GtkWindow`. Every widget that is not itself a `GtkNative` is contained in one, and you can get it with [method@Gtk.Widget.get_native]. To get the surface of a `GtkNative`, use [method@Gtk.Native.get_surface]. It is also possible to find the `GtkNative` to which a surface belongs, with [func@Gtk.Native.get_for_surface]. In addition to a [class@Gdk.Surface], a `GtkNative` also provides a [class@Gsk.Renderer] for rendering on that surface. To get the renderer, use [method@Gtk.Native.get_renderer]. Finds the `GtkNative` associated with the surface. the `GtkNative` that is associated with @surface a `GdkSurface` Returns the renderer that is used for this `GtkNative`. the renderer for @self a `GtkNative` Returns the surface of this `GtkNative`. the surface of @self a `GtkNative` Retrieves the surface transform of @self. This is the translation from @self's surface coordinates into @self's widget coordinates. a `GtkNative` return location for the x coordinate return location for the y coordinate Realizes a `GtkNative`. This should only be used by subclasses. a `GtkNative` Unrealizes a `GtkNative`. This should only be used by subclasses. a `GtkNative` Base class for platform dialogs that don't use `GtkDialog`. Native dialogs are used in order to integrate better with a platform, by looking the same as other native applications and supporting platform specific features. The [class@Gtk.Dialog] functions cannot be used on such objects, but we need a similar API in order to drive them. The `GtkNativeDialog` object is an API that allows you to do this. It allows you to set various common properties on the dialog, as well as show and hide it and get a [signal@Gtk.NativeDialog::response] signal when the user finished with the dialog. Note that unlike `GtkDialog`, `GtkNativeDialog` objects are not toplevel widgets, and GTK does not keep them alive. It is your responsibility to keep a reference until you are done with the object. Hides the dialog if it is visible, aborting any interaction. Once this is called the [signal@Gtk.NativeDialog::response] signal will *not* be emitted until after the next call to [method@Gtk.NativeDialog.show]. If the dialog is not visible this does nothing. a `GtkNativeDialog` class handler for the `GtkNativeDialog::response` signal Shows the dialog on the display. When the user accepts the state of the dialog the dialog will be automatically hidden and the [signal@Gtk.NativeDialog::response] signal will be emitted. Multiple calls while the dialog is visible will be ignored. a `GtkNativeDialog` Destroys a dialog. When a dialog is destroyed, it will break any references it holds to other objects. If it is visible it will be hidden and any underlying window system resources will be destroyed. Note that this does not release any reference to the object (as opposed to destroying a `GtkWindow`) because there is no reference from the windowing system to the `GtkNativeDialog`. a `GtkNativeDialog` Returns whether the dialog is modal. %TRUE if the dialog is set to be modal a `GtkNativeDialog` Gets the title of the `GtkNativeDialog`. the title of the dialog, or %NULL if none has been set explicitly. The returned string is owned by the widget and must not be modified or freed. a `GtkNativeDialog` Fetches the transient parent for this window. the transient parent for this window, or %NULL if no transient parent has been set. a `GtkNativeDialog` Determines whether the dialog is visible. %TRUE if the dialog is visible a `GtkNativeDialog` Hides the dialog if it is visible, aborting any interaction. Once this is called the [signal@Gtk.NativeDialog::response] signal will *not* be emitted until after the next call to [method@Gtk.NativeDialog.show]. If the dialog is not visible this does nothing. a `GtkNativeDialog` Sets a dialog modal or non-modal. Modal dialogs prevent interaction with other windows in the same application. To keep modal dialogs on top of main application windows, use [method@Gtk.NativeDialog.set_transient_for] to make the dialog transient for the parent; most window managers will then disallow lowering the dialog below the parent. a `GtkNativeDialog` whether the window is modal Sets the title of the `GtkNativeDialog.` a `GtkNativeDialog` title of the dialog Dialog windows should be set transient for the main application window they were spawned from. This allows window managers to e.g. keep the dialog on top of the main window, or center the dialog over the main window. Passing %NULL for @parent unsets the current transient window. a `GtkNativeDialog` parent window Shows the dialog on the display. When the user accepts the state of the dialog the dialog will be automatically hidden and the [signal@Gtk.NativeDialog::response] signal will be emitted. Multiple calls while the dialog is visible will be ignored. a `GtkNativeDialog` Whether the window should be modal with respect to its transient parent. The title of the dialog window The transient parent of the dialog, or %NULL for none. Whether the window is currently visible. Emitted when the user responds to the dialog. When this is called the dialog has been hidden. If you call [method@Gtk.NativeDialog.hide] before the user responds to the dialog this signal will not be emitted. the response ID Class structure for `GtkNativeDialog`. class handler for the `GtkNativeDialog::response` signal a `GtkNativeDialog` a `GtkNativeDialog` Options for selecting a different wrap mode for natural size requests. See for example the [property@Gtk.Label:natural-wrap-mode] property. Inherit the minimum size request. In particular, this should be used with %PANGO_WRAP_CHAR. Try not to wrap the text. This mode is the closest to GTK3's behavior but can lead to a wide label leaving lots of empty space below the text. Attempt to wrap at word boundaries. This is useful in particular when using %PANGO_WRAP_WORD_CHAR as the wrap mode. A `GtkShortcutTrigger` that never triggers. Gets the never trigger. This is a singleton for a trigger that never triggers. Use this trigger instead of %NULL because it implements all virtual functions. The never trigger A selection model that does not allow selecting anything. This model is meant to be used as a simple wrapper around a `GListModel` when a `GtkSelectionModel` is required. `GtkNoSelection` passes through sections from the underlying model. Creates a new selection to handle @model. a new `GtkNoSelection` the `GListModel` to manage Gets the model that @self is wrapping. The model being wrapped a `GtkNoSelection` Sets the model that @self should wrap. If @model is %NULL, this model will be empty. a `GtkNoSelection` A `GListModel` to wrap The type of items. See [method@Gio.ListModel.get_item_type]. The model being managed. The number of items. See [method@Gio.ListModel.get_n_items]. Switches between children using tabs. <picture> <source srcset="notebook-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkNotebook" src="notebook.png"> </picture> There are many configuration options for `GtkNotebook`. Among other things, you can choose on which edge the tabs appear (see [method@Gtk.Notebook.set_tab_pos]), whether, if there are too many tabs to fit the notebook should be made bigger or scrolling arrows added (see [method@Gtk.Notebook.set_scrollable]), and whether there will be a popup menu allowing the users to switch pages. (see [method@Gtk.Notebook.popup_enable]). # GtkNotebook as GtkBuildable The `GtkNotebook` implementation of the `GtkBuildable` interface supports placing children into tabs by specifying “tab” as the “type” attribute of a `<child>` element. Note that the content of the tab must be created before the tab can be filled. A tab child can be specified without specifying a `<child>` type attribute. To add a child widget in the notebooks action area, specify "action-start" or “action-end” as the “type” attribute of the `<child>` element. An example of a UI definition fragment with `GtkNotebook`: ```xml <object class="GtkNotebook"> <child> <object class="GtkLabel" id="notebook-content"> <property name="label">Content</property> </object> </child> <child type="tab"> <object class="GtkLabel" id="notebook-tab"> <property name="label">Tab</property> </object> </child> </object> ``` # Shortcuts and Gestures `GtkNotebook` supports the following keyboard shortcuts: - <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. - <kbd>Home</kbd> moves the focus to the first tab. - <kbd>End</kbd> moves the focus to the last tab. Additionally, the following signals have default keybindings: - [signal@Gtk.Notebook::change-current-page] - [signal@Gtk.Notebook::focus-tab] - [signal@Gtk.Notebook::move-focus-out] - [signal@Gtk.Notebook::reorder-tab] - [signal@Gtk.Notebook::select-page] Tabs support drag-and-drop between notebooks sharing the same `group-name`, or to new windows by handling the `::create-window` signal. # Actions `GtkNotebook` defines a set of built-in actions: - `menu.popup` opens the tabs context menu. # CSS nodes ``` notebook ├── header.top │ ├── [<action widget>] │ ├── tabs │ │ ├── [arrow] │ │ ├── tab │ │ │ ╰── <tab label> ┊ ┊ ┊ │ │ ├── tab[.reorderable-page] │ │ │ ╰── <tab label> │ │ ╰── [arrow] │ ╰── [<action widget>] │ ╰── stack ├── <child> ┊ ╰── <child> ``` `GtkNotebook` has a main CSS node with name `notebook`, a subnode with name `header` and below that a subnode with name `tabs` which contains one subnode per tab with name `tab`. If action widgets are present, their CSS nodes are placed next to the `tabs` node. If the notebook is scrollable, CSS nodes with name `arrow` are placed as first and last child of the `tabs` node. The main node gets the `.frame` style class when the notebook has a border (see [method@Gtk.Notebook.set_show_border]). The header node gets one of the style class `.top`, `.bottom`, `.left` or `.right`, depending on where the tabs are placed. For reorderable pages, the tab node gets the `.reorderable-page` class. A `tab` node gets the `.dnd` style class while it is moved with drag-and-drop. The nodes are always arranged from left-to-right, regardless of text direction. # Accessibility `GtkNotebook` uses the following roles: - [enum@Gtk.AccessibleRole.group] for the notebook widget - [enum@Gtk.AccessibleRole.tab_list] for the list of tabs - [enum@Gtk.AccessibleRole.tab] role for each tab - [enum@Gtk.AccessibleRole.tab_panel] for each page Creates a new `GtkNotebook` widget with no pages. the newly created `GtkNotebook` Appends a page to @notebook. the index (starting from 0) of the appended page in the notebook, or -1 if function fails a `GtkNotebook` the `GtkWidget` to use as the contents of the page the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” Appends a page to @notebook, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the appended page in the notebook, or -1 if function fails a `GtkNotebook` the `GtkWidget` to use as the contents of the page the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a `GtkLabel` or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label is not a `GtkLabel`, @menu_label must be specified if the page-switch menu is to be used. Removes the child from the notebook. This function is very similar to [method@Gtk.Notebook.remove_page], but additionally informs the notebook that the removal is happening as part of a tab DND operation, which should not be cancelled. a `GtkNotebook` a child Gets one of the action widgets. See [method@Gtk.Notebook.set_action_widget]. The action widget with the given @pack_type or %NULL when this action widget has not been set a `GtkNotebook` pack type of the action widget to receive Returns the page number of the current page. the index (starting from 0) of the current page in the notebook. If the notebook has no pages, then -1 will be returned. a `GtkNotebook` Gets the current group name for @notebook. the group name, or %NULL if none is set a `GtkNotebook` Retrieves the menu label widget of the page containing @child. the menu label, or %NULL if the notebook page does not have a menu label other than the default (the tab label). a `GtkNotebook` a widget contained in a page of @notebook Retrieves the text of the menu label for the page containing @child. the text of the tab label, or %NULL if the widget does not have a menu label other than the default menu label, or the menu label widget is not a `GtkLabel`. The string is owned by the widget and must not be freed. a `GtkNotebook` the child widget of a page of the notebook. Gets the number of pages in a notebook. the number of pages in the notebook a `GtkNotebook` Returns the child widget contained in page number @page_num. the child widget, or %NULL if @page_num is out of bounds a `GtkNotebook` the index of a page in the notebook, or -1 to get the last page Returns the `GtkNotebookPage` for @child. the `GtkNotebookPage` for @child a `GtkNotebook` a child of @notebook Returns a `GListModel` that contains the pages of the notebook. This can be used to keep an up-to-date view. The model also implements [iface@Gtk.SelectionModel] and can be used to track and modify the visible page. a `GListModel` for the notebook's children a `GtkNotebook` Returns whether the tab label area has arrows for scrolling. %TRUE if arrows for scrolling are present a `GtkNotebook` Returns whether a bevel will be drawn around the notebook pages. %TRUE if the bevel is drawn a `GtkNotebook` Returns whether the tabs of the notebook are shown. %TRUE if the tabs are shown a `GtkNotebook` Returns whether the tab contents can be detached from @notebook. %TRUE if the tab is detachable. a `GtkNotebook` a child `GtkWidget` Returns the tab label widget for the page @child. %NULL is returned if @child is not in @notebook or if no tab label has specifically been set for @child. the tab label a `GtkNotebook` the page Retrieves the text of the tab label for the page containing @child. the text of the tab label, or %NULL if the tab label widget is not a `GtkLabel`. The string is owned by the widget and must not be freed. a `GtkNotebook` a widget contained in a page of @notebook Gets the edge at which the tabs are drawn. the edge at which the tabs are drawn a `GtkNotebook` Gets whether the tab can be reordered via drag and drop or not. %TRUE if the tab is reorderable. a `GtkNotebook` a child `GtkWidget` Insert a page into @notebook at the given position. the index (starting from 0) of the inserted page in the notebook, or -1 if function fails a `GtkNotebook` the `GtkWidget` to use as the contents of the page the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages Insert a page into @notebook at the given position, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the inserted page in the notebook a `GtkNotebook` the `GtkWidget` to use as the contents of the page the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a `GtkLabel` or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label is not a `GtkLabel`, @menu_label must be specified if the page-switch menu is to be used. the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages. Switches to the next page. Nothing happens if the current page is the last page. a `GtkNotebook` Finds the index of the page which contains the given child widget. the index of the page containing @child, or -1 if @child is not in the notebook a `GtkNotebook` a `GtkWidget` Disables the popup menu. a `GtkNotebook` Enables the popup menu. If the user clicks with the right mouse button on the tab labels, a menu with all the pages will be popped up. a `GtkNotebook` Prepends a page to @notebook. the index (starting from 0) of the prepended page in the notebook, or -1 if function fails a `GtkNotebook` the `GtkWidget` to use as the contents of the page the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” Prepends a page to @notebook, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the prepended page in the notebook, or -1 if function fails a `GtkNotebook` the `GtkWidget` to use as the contents of the page the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a `GtkLabel` or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label is not a `GtkLabel`, @menu_label must be specified if the page-switch menu is to be used. Switches to the previous page. Nothing happens if the current page is the first page. a `GtkNotebook` Removes a page from the notebook given its index in the notebook. a `GtkNotebook` the index of a notebook page, starting from 0. If -1, the last page will be removed. Reorders the page containing @child, so that it appears in position @position. If @position is greater than or equal to the number of children in the list or negative, @child will be moved to the end of the list. a `GtkNotebook` the child to move the new position, or -1 to move to the end Sets @widget as one of the action widgets. Depending on the pack type the widget will be placed before or after the tabs. You can use a `GtkBox` if you need to pack more than one widget on the same side. a `GtkNotebook` a `GtkWidget` pack type of the action widget Switches to the page number @page_num. Note that due to historical reasons, GtkNotebook refuses to switch to a page unless the child widget is visible. Therefore, it is recommended to show child widgets before adding them to a notebook. a `GtkNotebook` index of the page to switch to, starting from 0. If negative, the last page will be used. If greater than the number of pages in the notebook, nothing will be done. Sets a group name for @notebook. Notebooks with the same name will be able to exchange tabs via drag and drop. A notebook with a %NULL group name will not be able to exchange tabs with any other notebook. a `GtkNotebook` the name of the notebook group, or %NULL to unset it Changes the menu label for the page containing @child. a `GtkNotebook` the child widget the menu label, or %NULL for default Creates a new label and sets it as the menu label of @child. a `GtkNotebook` the child widget the label text Sets whether the tab label area will have arrows for scrolling if there are too many tabs to fit in the area. a `GtkNotebook` %TRUE if scroll arrows should be added Sets whether a bevel will be drawn around the notebook pages. This only has a visual effect when the tabs are not shown. a `GtkNotebook` %TRUE if a bevel should be drawn around the notebook Sets whether to show the tabs for the notebook or not. a `GtkNotebook` %TRUE if the tabs should be shown Sets whether the tab can be detached from @notebook to another notebook or widget. Note that two notebooks must share a common group identifier (see [method@Gtk.Notebook.set_group_name]) to allow automatic tabs interchange between them. If you want a widget to interact with a notebook through DnD (i.e.: accept dragged tabs from it) it must be set as a drop destination by adding to it a [class@Gtk.DropTarget] controller that accepts the GType `GTK_TYPE_NOTEBOOK_PAGE`. The `:value` of said drop target will be preloaded with a [class@Gtk.NotebookPage] object that corresponds to the dropped tab, so you can process the value via `::accept` or `::drop` signals. Note that you should use [method@Gtk.Notebook.detach_tab] instead of [method@Gtk.Notebook.remove_page] if you want to remove the tab from the source notebook as part of accepting a drop. Otherwise, the source notebook will think that the dragged tab was removed from underneath the ongoing drag operation, and will initiate a drag cancel animation. ```c static void on_drag_data_received (GtkWidget *widget, GdkDrop *drop, GtkSelectionData *data, guint time, gpointer user_data) { GtkDrag *drag; GtkWidget *notebook; GtkWidget **child; drag = gtk_drop_get_drag (drop); notebook = g_object_get_data (drag, "gtk-notebook-drag-origin"); child = (void*) gtk_selection_data_get_data (data); // process_widget (*child); gtk_notebook_detach_tab (GTK_NOTEBOOK (notebook), *child); } ``` If you want a notebook to accept drags from other widgets, you will have to set your own DnD code to do it. a `GtkNotebook` a child `GtkWidget` whether the tab is detachable or not Changes the tab label for @child. If %NULL is specified for @tab_label, then the page will have the label “page N”. a `GtkNotebook` the page the tab label widget to use, or %NULL for default tab label Creates a new label and sets it as the tab label for the page containing @child. a `GtkNotebook` the page the label text Sets the edge at which the tabs are drawn. a `GtkNotebook`. the edge to draw the tabs at Sets whether the notebook tab can be reordered via drag and drop or not. a `GtkNotebook` a child `GtkWidget` whether the tab is reorderable or not If %TRUE, pressing the right mouse button on the notebook shows a page switching menu. Group name for tab drag and drop. The index of the current page. A selection model with the pages. If %TRUE, scroll arrows are added if there are too many pages to fit. Whether the border should be shown. Whether tabs should be shown. Which side of the notebook holds the tabs. Emitted when the current page should be changed. The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>PgUp</kbd>, <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>PgDn</kbd>, <kbd>Ctrl</kbd>+<kbd>PgUp</kbd> and <kbd>Ctrl</kbd>+<kbd>PgDn</kbd>. whether the page was changed the page index The ::create-window signal is emitted when a detachable tab is dropped on the root window. A handler for this signal can create a window containing a notebook where the tab will be attached. It is also responsible for moving/resizing the window and adding the necessary properties to the notebook (e.g. the `GtkNotebook`:group-name ). a `GtkNotebook` that @page should be added to the tab of @notebook that is being detached Emitted when a tab should be focused. whether the tab has been focused the notebook tab Emitted when focus was moved out. The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>Tab</kbd>, <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Tab</kbd>, <kbd>Ctrl</kbd>+<kbd>←</kbd>, <kbd>Ctrl</kbd>+<kbd>→</kbd>, <kbd>Ctrl</kbd>+<kbd>↑</kbd> and <kbd>Ctrl</kbd>+<kbd>↓</kbd>. the direction to move the focus the ::page-added signal is emitted in the notebook right after a page is added to the notebook. the child `GtkWidget` affected the new page number for @child the ::page-removed signal is emitted in the notebook right after a page is removed from the notebook. the child `GtkWidget` affected the @child page number the ::page-reordered signal is emitted in the notebook right after a page has been reordered. the child `GtkWidget` affected the new page number for @child Emitted when the tab should be reordered. The default bindings for this signal are <kbd>Alt</kbd>+<kbd>Home</kbd>, <kbd>Alt</kbd>+<kbd>End</kbd>, <kbd>Alt</kbd>+<kbd>PgUp</kbd>, <kbd>Alt</kbd>+<kbd>PgDn</kbd>, <kbd>Alt</kbd>+<kbd>←</kbd>, <kbd>Alt</kbd>+<kbd>→</kbd>, <kbd>Alt</kbd>+<kbd>↑</kbd> and <kbd>Alt</kbd>+<kbd>↓</kbd>. whether the tab was moved. the direction to move the tab whether to move to the last position Emitted when a page should be selected. The default binding for this signal is <kbd>␣</kbd>. whether the page was selected whether to move focus Emitted when the user or a function changes the current page. the new current page the index of the page An auxiliary object used by `GtkNotebook`. Returns the notebook child to which @page belongs. the child to which @page belongs a `GtkNotebookPage` The child for this page. Whether the tab is detachable. The label widget displayed in the child's menu entry. The text of the menu widget. The index of the child in the parent. Whether the tab is reorderable by user action. The tab widget for this page. Whether to expand the child's tab. Whether the child's tab should fill the allocated area. The text of the tab widget. The parameter used in the action signals of `GtkNotebook`. the first tab in the notebook the last tab in the notebook Does nothing. Gets the nothing action. This is an action that does nothing and where activating it always fails. The nothing action Used to determine the layout of pages on a sheet when printing multiple pages per sheet. ![](layout-lrtb.png) ![](layout-lrbt.png) ![](layout-rltb.png) ![](layout-rlbt.png) ![](layout-tblr.png) ![](layout-tbrl.png) ![](layout-btlr.png) ![](layout-btrl.png) Sorts items numerically. To obtain the numbers to compare, this sorter evaluates a [class@Gtk.Expression]. Creates a new numeric sorter using the given @expression. Smaller numbers will be sorted first. You can call [method@Gtk.NumericSorter.set_sort_order] to change this. a new `GtkNumericSorter` The expression to evaluate Gets the expression that is evaluated to obtain numbers from items. a `GtkExpression` a `GtkNumericSorter` Gets whether this sorter will sort smaller numbers first. the order of the numbers a `GtkNumericSorter` Sets the expression that is evaluated to obtain numbers from items. Unless an expression is set on @self, the sorter will always compare items as invalid. The expression must have a return type that can be compared numerically, such as %G_TYPE_INT or %G_TYPE_DOUBLE. a `GtkNumericSorter` a `GtkExpression` Sets whether to sort smaller numbers before larger ones. a `GtkNumericSorter` whether to sort smaller numbers first The expression to evaluate on items to get a number to compare with. Whether the sorter will sort smaller numbers first. A `GObject` value in a `GtkExpression`. Creates an expression evaluating to the given `object` with a weak reference. Once the `object` is disposed, it will fail to evaluate. This expression is meant to break reference cycles. If you want to keep a reference to `object`, use [ctor@Gtk.ConstantExpression.new]. a new `GtkExpression` object to watch Gets the object that the expression evaluates to. the object, or `NULL` an object `GtkExpression` Describes the way two values can be compared. These values can be used with a [callback@GLib.CompareFunc]. However, a `GCompareFunc` is allowed to return any integer values. For converting such a value to a `GtkOrdering` value, use [func@Gtk.Ordering.from_cmpfunc]. the first value is smaller than the second the two values are equal the first value is larger than the second Converts the result of a `GCompareFunc` like strcmp() to a `GtkOrdering` value. the corresponding `GtkOrdering` Result of a comparison function An interface for widgets that can be oriented horizontally or vertically. `GtkOrientable` is more flexible in that it allows the orientation to be changed at runtime, allowing the widgets to “flip”. ## CSS nodes `GtkWidget` types implementing the `GtkOrientable` interface will automatically acquire the `horizontal` or `vertical` CSS class depending on the value of the [property@Gtk.Orientable:orientation] property. Retrieves the orientation of the @orientable. the orientation of the @orientable a `GtkOrientable` Sets the orientation of the @orientable. a `GtkOrientable` the orientable’s new orientation The orientation of the orientable. Represents the orientation of widgets and other objects. Typical examples are [class@Box] or [class@GesturePan]. The element is in horizontal orientation. The element is in vertical orientation. Defines how content overflowing a given area should be handled. This is used in [method@Gtk.Widget.set_overflow]. The [property@Gtk.Widget:overflow] property is modeled after the CSS overflow property, but implements it only partially. No change is applied. Content is drawn at the specified position. Content is clipped to the bounds of the area. Content outside the area is not drawn and cannot be interacted with. Places “overlay” widgets on top of a single main child. <picture> <source srcset="overlay-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkOverlay" src="overlay.png"> </picture> The position of each overlay widget is determined by its [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties. E.g. a widget with both alignments set to %GTK_ALIGN_START will be placed at the top left corner of the `GtkOverlay` container, whereas an overlay with halign set to %GTK_ALIGN_CENTER and valign set to %GTK_ALIGN_END will be placed a the bottom edge of the `GtkOverlay`, horizontally centered. The position can be adjusted by setting the margin properties of the child to non-zero values. More complicated placement of overlays is possible by connecting to the [signal@Gtk.Overlay::get-child-position] signal. An overlay’s minimum and natural sizes are those of its main child. The sizes of overlay children are not considered when measuring these preferred sizes. # GtkOverlay as GtkBuildable The `GtkOverlay` implementation of the `GtkBuildable` interface supports placing a child as an overlay by specifying “overlay” as the “type” attribute of a `<child>` element. # CSS nodes `GtkOverlay` has a single CSS node with the name “overlay”. Overlay children whose alignments cause them to be positioned at an edge get the style classes “.left”, “.right”, “.top”, and/or “.bottom” according to their position. Creates a new `GtkOverlay`. a new `GtkOverlay` object. Adds @widget to @overlay. The widget will be stacked on top of the main widget added with [method@Gtk.Overlay.set_child]. The position at which @widget is placed is determined from its [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties. a `GtkOverlay` a `GtkWidget` to be added to the container Gets the child widget of @overlay. the child widget of @overlay a `GtkOverlay` Gets whether @widget should be clipped within the parent. whether the widget is clipped within the parent. a `GtkOverlay` an overlay child of `GtkOverlay` Gets whether @widget's size is included in the measurement of @overlay. whether the widget is measured a `GtkOverlay` an overlay child of `GtkOverlay` Removes an overlay that was added with gtk_overlay_add_overlay(). a `GtkOverlay` a `GtkWidget` to be removed Sets the child widget of @overlay. a `GtkOverlay` the child widget Sets whether @widget should be clipped within the parent. a `GtkOverlay` an overlay child of `GtkOverlay` whether the child should be clipped Sets whether @widget is included in the measured size of @overlay. The overlay will request the size of the largest child that has this property set to %TRUE. Children who are not included may be drawn outside of @overlay's allocation if they are too large. a `GtkOverlay` an overlay child of `GtkOverlay` whether the child should be measured The main child widget. Emitted to determine the position and size of any overlay child widgets. A handler for this signal should fill @allocation with the desired position and size for @widget, relative to the 'main' child of @overlay. The default handler for this signal uses the @widget's halign and valign properties to determine the position and gives the widget its natural size (except that an alignment of %GTK_ALIGN_FILL will cause the overlay to be full-width/height). If the main child is a `GtkScrolledWindow`, the overlays are placed relative to its contents. %TRUE if the @allocation has been filled the child widget to position return location for the allocation The layout manager used by [class@Gtk.Overlay]. It places widgets as overlays on top of the main child. This is not a reusable layout manager, since it expects its widget to be a `GtkOverlay`. It is only listed here so that its layout properties get documented. Creates a new `GtkOverlayLayout` instance. the newly created instance `GtkLayoutChild` subclass for children in a `GtkOverlayLayout`. Retrieves whether the child is clipped. whether the child is clipped a `GtkOverlayLayoutChild` Retrieves whether the child is measured. whether the child is measured a `GtkOverlayLayoutChild` Sets whether to clip this child. a `GtkOverlayLayoutChild` whether to clip this child Sets whether to measure this child. a `GtkOverlayLayoutChild` whether to measure this child Whether the child should be clipped to fit the parent's size. Whether the child size should contribute to the `GtkOverlayLayout`'s measurement. Name for the A3 paper size. Name for the A4 paper size. Name for the A5 paper size. Name for the B5 paper size. Name for the Executive paper size. Name for the Legal paper size. Name for the Letter paper size. The key used by the “Print to file” printer to store whether to collate the printed pages. The key used by the “Print to file” printer to store the default source. The key used by the “Print to file” printer to store the dither used. The key used by the “Print to file” printer to store whether to print the output in duplex. The key used by the “Print to file” printer to store the finishings. The key used by the “Print to file” printer to store the media type. The set of media types is defined in PWG 5101.1-2002 PWG. The key used by the “Print to file” printer to store the number of pages per sheet. The key used by the “Print to file” printer to store the number of pages per sheet in number-up mode. The key used by the “Print to file” printer to store the number of copies. The key used by the “Print to file” printer to store the orientation. The key used by the “Print to file” printer to store the file name of the output without the path to the directory and the file extension. The key used by the “Print to file” printer to store the output bin. The key used by the “Print to file” printer to store the directory to which the output should be written. The key used by the “Print to file” printer to store the format of the output. The supported values are “PS” and “PDF”. The key used by the “Print to file” printer to store the URI to which the output should be written. GTK itself supports only “file://” URIs. The key used by the “Print to file” printer to store the array of page ranges to print. The key used by the “Print to file” printer to store the set of pages to print. The key used by the “Print to file” printer to store the page format. The key used by the “Print to file” printer to store the page height. The key used by the “Print to file” printer to store the paper width. The key used by the “Print to file” printer to store the printer name. The key used by the “Print to file” printer to store the resolution in lines per inch. The key used by the “Print to file” printer to store which pages to print. The key used by the “Print to file” printer to store the printing quality. The key used by the “Print to file” printer to store the resolution in DPI. The key used by the “Print to file” printer to store the horizontal resolution in DPI. The key used by the “Print to file” printer to store the vertical resolution in DPI. The key used by the “Print to file” printer to store whether to reverse the order of the printed pages. The key used by the “Print to file” printer to store the scale. The key used by the “Print to file” printer to store whether to print with colors. The key used by the “Print to file” printer to store 32-bit Windows extra driver. The key used by the “Print to file” printer to store the 32-bit Windows driver version. Use this priority for functionality related to size allocation. It is used internally by GTK+ to compute the sizes of widgets. This priority is higher than %GDK_PRIORITY_REDRAW to avoid resizing a widget which was just redrawn. Represents the packing location of a children in its parent. See [class@WindowControls] for example. The child is packed into the start of the widget The child is packed into the end of the widget Struct defining a pad action entry. the type of pad feature that will trigger this action entry. the 0-indexed button/ring/strip/dial number that will trigger this action entry. the mode that will trigger this action entry, or -1 for all modes. Human readable description of this action entry, this string should be deemed user-visible. action name that will be activated in the `GActionGroup`. The type of a pad action. Action is triggered by a pad button Action is triggered by a pad ring Action is triggered by a pad strip Action is triggered by a pad dial Handles input from the pads found in drawing tablets. Pads are the collection of buttons and tactile sensors often found around the stylus-sensitive area. These buttons and sensors have no implicit meaning, and by default they perform no action. `GtkPadController` is provided to map those to [iface@Gio.Action] objects, thus letting the application give them a more semantic meaning. Buttons and sensors are not constrained to triggering a single action, some %GDK_SOURCE_TABLET_PAD devices feature multiple "modes". All these input elements have one current mode, which may determine the final action being triggered. Pad devices often divide buttons and sensors into groups. All elements in a group share the same current mode, but different groups may have different modes. See [method@Gdk.DevicePad.get_n_groups] and [method@Gdk.DevicePad.get_group_n_modes]. Each of the actions that a given button/strip/ring performs for a given mode is defined by a [struct@Gtk.PadActionEntry]. It contains an action name that will be looked up in the given [iface@Gio.ActionGroup] and activated whenever the specified input element and mode are triggered. A simple example of `GtkPadController` usage: Assigning button 1 in all modes and pad devices to an "invert-selection" action: ```c GtkPadActionEntry *pad_actions[] = { { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection", "pad-actions.invert-selection" }, … }; … action_group = g_simple_action_group_new (); action = g_simple_action_new ("pad-actions.invert-selection", NULL); g_signal_connect (action, "activate", on_invert_selection_activated, NULL); g_action_map_add_action (G_ACTION_MAP (action_group), action); … pad_controller = gtk_pad_controller_new (action_group, NULL); ``` The actions belonging to rings/strips/dials will be activated with a parameter of type %G_VARIANT_TYPE_DOUBLE bearing the value of the given axis, it is required that those are made stateful and accepting this `GVariantType`. For rings the value is the angle of the ring position in degrees with 0 facing up. For strips the value is the absolute position on the strip, normalized to the [0.0, 1.0] range. For dials the value is the relative movement of the dial, normalized so that the value 120 represents one logical scroll wheel detent in the positive direction. Devices that support high-resolution scrolling may send events with fractions of 120 to signify a smaller motion. Creates a new `GtkPadController` that will associate events from @pad to actions. A %NULL pad may be provided so the controller manages all pad devices generically, it is discouraged to mix `GtkPadController` objects with %NULL and non-%NULL @pad argument on the same toplevel window, as execution order is not guaranteed. The `GtkPadController` is created with no mapped actions. In order to map pad events to actions, use [method@Gtk.PadController.set_action_entries] or [method@Gtk.PadController.set_action]. Be aware that pad events will only be delivered to `GtkWindow`s, so adding a pad controller to any other type of widget will not have an effect. A newly created `GtkPadController` `GActionGroup` to trigger actions from A %GDK_SOURCE_TABLET_PAD device, or %NULL to handle all pads Adds an individual action to @controller. This action will only be activated if the given button/ring/strip number in @index is interacted while the current mode is @mode. -1 may be used for simple cases, so the action is triggered on all modes. The given @label should be considered user-visible, so internationalization rules apply. Some windowing systems may be able to use those for user feedback. a `GtkPadController` the type of pad feature that will trigger this action the 0-indexed button/ring/strip number that will trigger this action the mode that will trigger this action, or -1 for all modes. Human readable description of this action, this string should be deemed user-visible. action name that will be activated in the `GActionGroup` A convenience function to add a group of action entries on @controller. See [struct@Gtk.PadActionEntry] and [method@Gtk.PadController.set_action]. a `GtkPadController` the action entries to set on @controller the number of elements in @entries The action group of the controller. The pad of the controller. See also gtk_print_settings_set_orientation(). Portrait mode. Landscape mode. Reverse portrait mode. Reverse landscape mode. A range of pages to print. See also [method@Gtk.PrintSettings.set_page_ranges]. start of page range. end of page range. See also gtk_print_job_set_page_set(). All pages. Even pages. Odd pages. Stores page size, orientation and margins for printing. The idea is that you can get one of these from the page setup dialog and then pass it to the `GtkPrintOperation` when printing. The benefit of splitting this out of the `GtkPrintSettings` is that these affect the actual layout of the page, and thus need to be set long before user prints. ## Margins The margins specified in this object are the “print margins”, i.e. the parts of the page that the printer cannot print on. These are different from the layout margins that a word processor uses; they are typically used to determine the minimal size for the layout margins. To obtain a `GtkPageSetup` use [ctor@Gtk.PageSetup.new] to get the defaults, or use [func@Gtk.print_run_page_setup_dialog] to show the page setup dialog and receive the resulting page setup. ## A page setup dialog ```c static GtkPrintSettings *settings = NULL; static GtkPageSetup *page_setup = NULL; static void do_page_setup (void) { GtkPageSetup *new_page_setup; if (settings == NULL) settings = gtk_print_settings_new (); new_page_setup = gtk_print_run_page_setup_dialog (GTK_WINDOW (main_window), page_setup, settings); if (page_setup) g_object_unref (page_setup); page_setup = new_page_setup; } ``` Creates a new `GtkPageSetup`. a new `GtkPageSetup`. Reads the page setup from the file @file_name. Returns a new `GtkPageSetup` object with the restored page setup, or %NULL if an error occurred. See [method@Gtk.PageSetup.to_file]. the restored `GtkPageSetup` the filename to read the page setup from Desrialize a page setup from an a{sv} variant. The variant must be in the format produced by [method@Gtk.PageSetup.to_gvariant]. a new `GtkPageSetup` object an a{sv} `GVariant` Reads the page setup from the group @group_name in the key file @key_file. Returns a new `GtkPageSetup` object with the restored page setup, or %NULL if an error occurred. the restored `GtkPageSetup` the `GKeyFile` to retrieve the page_setup from the name of the group in the key_file to read to use the default name “Page Setup” Copies a `GtkPageSetup`. a copy of @other the `GtkPageSetup` to copy Gets the bottom margin in units of @unit. the bottom margin a `GtkPageSetup` the unit for the return value Gets the left margin in units of @unit. the left margin a `GtkPageSetup` the unit for the return value Gets the page orientation of the `GtkPageSetup`. the page orientation a `GtkPageSetup` Returns the page height in units of @unit. Note that this function takes orientation and margins into consideration. See [method@Gtk.PageSetup.get_paper_height]. the page height. a `GtkPageSetup` the unit for the return value Returns the page width in units of @unit. Note that this function takes orientation and margins into consideration. See [method@Gtk.PageSetup.get_paper_width]. the page width. a `GtkPageSetup` the unit for the return value Returns the paper height in units of @unit. Note that this function takes orientation, but not margins into consideration. See [method@Gtk.PageSetup.get_page_height]. the paper height. a `GtkPageSetup` the unit for the return value Gets the paper size of the `GtkPageSetup`. the paper size a `GtkPageSetup` Returns the paper width in units of @unit. Note that this function takes orientation, but not margins into consideration. See [method@Gtk.PageSetup.get_page_width]. the paper width. a `GtkPageSetup` the unit for the return value Gets the right margin in units of @unit. the right margin a `GtkPageSetup` the unit for the return value Gets the top margin in units of @unit. the top margin a `GtkPageSetup` the unit for the return value Reads the page setup from the file @file_name. See [method@Gtk.PageSetup.to_file]. %TRUE on success a `GtkPageSetup` the filename to read the page setup from Reads the page setup from the group @group_name in the key file @key_file. %TRUE on success a `GtkPageSetup` the `GKeyFile` to retrieve the page_setup from the name of the group in the key_file to read to use the default name “Page Setup” Sets the bottom margin of the `GtkPageSetup`. a `GtkPageSetup` the new bottom margin in units of @unit the units for @margin Sets the left margin of the `GtkPageSetup`. a `GtkPageSetup` the new left margin in units of @unit the units for @margin Sets the page orientation of the `GtkPageSetup`. a `GtkPageSetup` a `GtkPageOrientation` value Sets the paper size of the `GtkPageSetup` without changing the margins. See [method@Gtk.PageSetup.set_paper_size_and_default_margins]. a `GtkPageSetup` a `GtkPaperSize` Sets the paper size of the `GtkPageSetup` and modifies the margins according to the new paper size. a `GtkPageSetup` a `GtkPaperSize` Sets the right margin of the `GtkPageSetup`. a `GtkPageSetup` the new right margin in units of @unit the units for @margin Sets the top margin of the `GtkPageSetup`. a `GtkPageSetup` the new top margin in units of @unit the units for @margin This function saves the information from @setup to @file_name. %TRUE on success a `GtkPageSetup` the file to save to Serialize page setup to an a{sv} variant. a new, floating, `GVariant` a `GtkPageSetup` This function adds the page setup from @setup to @key_file. a `GtkPageSetup` the `GKeyFile` to save the page setup to the group to add the settings to in @key_file, or %NULL to use the default name “Page Setup” The type of function that is passed to gtk_print_run_page_setup_dialog_async(). This function will be called when the page setup dialog is dismissed, and also serves as destroy notify for @data. the `GtkPageSetup` that has been passed to gtk_print_run_page_setup_dialog_async() user data that has been passed to gtk_print_run_page_setup_dialog_async() Presents a page setup dialog for platforms which don’t provide a native page setup dialog, like Unix. <picture> <source srcset="pagesetupdialog-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkPageSetupUnixDialog" src="pagesetupdialog.png"> </picture> It can be used very much like any other GTK dialog, at the cost of the portability offered by the high-level printing API in [class@Gtk.PrintOperation]. ## CSS nodes `GtkPageSetupUnixDialog` has a single CSS node with the name `window` and style class `.pagesetup`. Creates a new page setup dialog. the new `GtkPageSetupUnixDialog` the title of the dialog transient parent of the dialog Gets the currently selected page setup from the dialog. the current page setup a `GtkPageSetupUnixDialog` Gets the current print settings from the dialog. the current print settings a `GtkPageSetupUnixDialog` Sets the `GtkPageSetup` from which the page setup dialog takes its values. a `GtkPageSetupUnixDialog` a `GtkPageSetup` Sets the `GtkPrintSettings` from which the page setup dialog takes its values. a `GtkPageSetupUnixDialog` a `GtkPrintSettings` Describes the panning direction of a [class@GesturePan]. panned towards the left panned towards the right panned upwards panned downwards Arranges its children in two panes, horizontally or vertically. <picture> <source srcset="panes-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkPaned" src="panes.png"> </picture> The division between the two panes is adjustable by the user by dragging a handle. Child widgets are added to the panes of the widget with [method@Gtk.Paned.set_start_child] and [method@Gtk.Paned.set_end_child]. The division between the two children is set by default from the size requests of the children, but it can be adjusted by the user. A paned widget draws a separator between the two child widgets and a small handle that the user can drag to adjust the division. It does not draw any relief around the children or around the separator. (The space in which the separator is called the gutter.) Often, it is useful to put each child inside a [class@Gtk.Frame] so that the gutter appears as a ridge. No separator is drawn if one of the children is missing. Each child has two options that can be set, "resize" and "shrink". If "resize" is true then, when the `GtkPaned` is resized, that child will expand or shrink along with the paned widget. If "shrink" is true, then that child can be made smaller than its requisition by the user. Setting "shrink" to false allows the application to set a minimum size. If "resize" is false for both children, then this is treated as if "resize" is true for both children. The application can set the position of the slider as if it were set by the user, by calling [method@Gtk.Paned.set_position]. # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.Paned::accept-position] - [signal@Gtk.Paned::cancel-position] - [signal@Gtk.Paned::cycle-child-focus] - [signal@Gtk.Paned::cycle-handle-focus] - [signal@Gtk.Paned::move-handle] - [signal@Gtk.Paned::toggle-handle-focus] # CSS nodes ``` paned ├── <child> ├── separator[.wide] ╰── <child> ``` `GtkPaned` has a main CSS node with name paned, and a subnode for the separator with name separator. The subnode gets a .wide style class when the paned is supposed to be wide. In horizontal orientation, the nodes are arranged based on the text direction, so in left-to-right mode, :first-child will select the leftmost child, while it will select the rightmost child in RTL layouts. ## Creating a paned widget with minimum sizes. ```c GtkWidget *hpaned = gtk_paned_new (GTK_ORIENTATION_HORIZONTAL); GtkWidget *frame1 = gtk_frame_new (NULL); GtkWidget *frame2 = gtk_frame_new (NULL); gtk_widget_set_size_request (hpaned, 200, -1); gtk_paned_set_start_child (GTK_PANED (hpaned), frame1); gtk_paned_set_resize_start_child (GTK_PANED (hpaned), TRUE); gtk_paned_set_shrink_start_child (GTK_PANED (hpaned), FALSE); gtk_widget_set_size_request (frame1, 50, -1); gtk_paned_set_end_child (GTK_PANED (hpaned), frame2); gtk_paned_set_resize_end_child (GTK_PANED (hpaned), FALSE); gtk_paned_set_shrink_end_child (GTK_PANED (hpaned), FALSE); gtk_widget_set_size_request (frame2, 50, -1); ``` Creates a new `GtkPaned` widget. the newly created paned widget the paned’s orientation. Retrieves the end child of the given `GtkPaned`. the end child widget a `GtkPaned` Obtains the position of the divider between the two panes. the position of the divider, in pixels a `GtkPaned` widget Returns whether the [property@Gtk.Paned:end-child] can be resized. true if the end child is resizable a `GtkPaned` Returns whether the [property@Gtk.Paned:start-child] can be resized. true if the start child is resizable a `GtkPaned` Returns whether the [property@Gtk.Paned:end-child] can shrink. true if the end child is shrinkable a `GtkPaned` Returns whether the [property@Gtk.Paned:start-child] can shrink. true if the start child is shrinkable a `GtkPaned` Retrieves the start child of the given `GtkPaned`. the start child widget a `GtkPaned` Gets whether the separator should be wide. %TRUE if the paned should have a wide handle a `GtkPaned` Sets the end child of @paned to @child. If @child is `NULL`, the existing child will be removed. a `GtkPaned` the widget to add Sets the position of the divider between the two panes. a `GtkPaned` widget pixel position of divider, a negative value means that the position is unset Sets whether the [property@Gtk.Paned:end-child] can be resized. a `GtkPaned` true to let the end child be resized Sets whether the [property@Gtk.Paned:start-child] can be resized. a `GtkPaned` true to let the start child be resized Sets whether the [property@Gtk.Paned:end-child] can shrink. a `GtkPaned` true to let the end child be shrunk Sets whether the [property@Gtk.Paned:start-child] can shrink. a `GtkPaned` true to let the start child be shrunk Sets the start child of @paned to @child. If @child is `NULL`, the existing child will be removed. a `GtkPaned` the widget to add Sets whether the separator should be wide. a `GtkPaned` the new value for the [property@Gtk.Paned:wide-handle] property The second child. The largest possible value for the [property@Gtk.Paned:position] property. This property is derived from the size and shrinkability of the widget's children. The smallest possible value for the [property@Gtk.Paned:position] property. This property is derived from the size and shrinkability of the widget's children. Position of the separator in pixels, from the left/top. Whether the [property@Gtk.Paned:position] property has been set. Determines whether the second child expands and shrinks along with the paned widget. Determines whether the first child expands and shrinks along with the paned widget. Determines whether the second child can be made smaller than its requisition. Determines whether the first child can be made smaller than its requisition. The first child. Whether the `GtkPaned` should provide a stronger visual separation. For example, this could be set when a paned contains two [class@Gtk.Notebook]s, whose tab rows would otherwise merge visually. Emitted to accept the current position of the handle when moving it using key bindings. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Return</kbd> or <kbd>Space</kbd>. whether the position was accepted Emitted to cancel moving the position of the handle using key bindings. The position of the handle will be reset to the value prior to moving it. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Escape</kbd>. whether the position was canceled Emitted to cycle the focus between the children of the paned. This is a [keybinding signal](class.SignalAction.html). The default binding is <kbd>F6</kbd>. whether the behavior was cycled whether cycling backward or forward Emitted to cycle whether the paned should grab focus to allow the user to change position of the handle by using key bindings. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>F8</kbd>. whether the behavior was cycled whether cycling backward or forward Emitted to move the handle with key bindings. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>←</kbd>, <kbd>←</kbd>, <kbd>Ctrl</kbd>+<kbd>→</kbd>, <kbd>→</kbd>, <kbd>Ctrl</kbd>+<kbd>↑</kbd>, <kbd>↑</kbd>, <kbd>Ctrl</kbd>+<kbd>↓</kbd>, <kbd>↓</kbd>, <kbd>PgUp</kbd>, <kbd>PgDn</kbd>, <kbd>Home</kbd>, <kbd>End</kbd>. whether the handle was moved a `GtkScrollType` Emitted to accept the current position of the handle and then move focus to the next widget in the focus chain. This is a [keybinding signal](class.SignalAction.html). The default binding is <kbd>Tab</kbd>. whether handle focus was toggled `GtkPaperSize` handles paper sizes. It uses the standard called [PWG 5101.1-2002 PWG: Standard for Media Standardized Names](http://www.pwg.org/standards.html) to name the paper sizes (and to get the data for the page sizes). In addition to standard paper sizes, `GtkPaperSize` allows to construct custom paper sizes with arbitrary dimensions. The `GtkPaperSize` object stores not only the dimensions (width and height) of a paper size and its name, it also provides default print margins. Creates a new `GtkPaperSize` object by parsing a [PWG 5101.1-2002](ftp://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn10-20020226-5101.1.pdf) paper name. If @name is %NULL, the default paper size is returned, see [func@Gtk.PaperSize.get_default]. a new `GtkPaperSize`, use [method@Gtk.PaperSize.free] to free it a paper size name Creates a new `GtkPaperSize` object with the given parameters. a new `GtkPaperSize` object, use [method@Gtk.PaperSize.free] to free it the paper name the human-readable name the paper width, in units of @unit the paper height, in units of @unit the unit for @width and @height. not %GTK_UNIT_NONE. Deserialize a paper size from a `GVariant`. The `GVariant must be in the format produced by [method@Gtk.PaperSize.to_gvariant]. a new `GtkPaperSize` object an a{sv} `GVariant` Creates a new `GtkPaperSize` object by using IPP information. If @ipp_name is not a recognized paper name, @width and @height are used to construct a custom `GtkPaperSize` object. a new `GtkPaperSize`, use [method@Gtk.PaperSize.free] to free it an IPP paper name the paper width, in points the paper height in points Reads a paper size from the group @group_name in the key file @key_file. a new `GtkPaperSize` object with the restored paper size the `GKeyFile` to retrieve the papersize from the name of the group in the key file to read, or %NULL to read the first group Creates a new `GtkPaperSize` object by using PPD information. If @ppd_name is not a recognized PPD paper name, @ppd_display_name, @width and @height are used to construct a custom `GtkPaperSize` object. a new `GtkPaperSize`, use [method@Gtk.PaperSize.free] to free it a PPD paper name the corresponding human-readable name the paper width, in points the paper height in points Copies an existing `GtkPaperSize`. a copy of @other a `GtkPaperSize` Free the given `GtkPaperSize` object. a `GtkPaperSize` Gets the default bottom margin for the `GtkPaperSize`. the default bottom margin a `GtkPaperSize` object the unit for the return value, not %GTK_UNIT_NONE Gets the default left margin for the `GtkPaperSize`. the default left margin a `GtkPaperSize` object the unit for the return value, not %GTK_UNIT_NONE Gets the default right margin for the `GtkPaperSize`. the default right margin a `GtkPaperSize` object the unit for the return value, not %GTK_UNIT_NONE Gets the default top margin for the `GtkPaperSize`. the default top margin a `GtkPaperSize` object the unit for the return value, not %GTK_UNIT_NONE Gets the human-readable name of the `GtkPaperSize`. the human-readable name of @size a `GtkPaperSize` object Gets the paper height of the `GtkPaperSize`, in units of @unit. the paper height a `GtkPaperSize` object the unit for the return value, not %GTK_UNIT_NONE Gets the name of the `GtkPaperSize`. the name of @size a `GtkPaperSize` object Gets the PPD name of the `GtkPaperSize`, which may be %NULL. the PPD name of @size a `GtkPaperSize` object Gets the paper width of the `GtkPaperSize`, in units of @unit. the paper width a `GtkPaperSize` object the unit for the return value, not %GTK_UNIT_NONE Returns %TRUE if @size is not a standard paper size. whether @size is a custom paper size. a `GtkPaperSize` object Compares two `GtkPaperSize` objects. %TRUE, if @size1 and @size2 represent the same paper size a `GtkPaperSize` object another `GtkPaperSize` object Returns %TRUE if @size is an IPP standard paper size. whether @size is not an IPP custom paper size. a `GtkPaperSize` object Changes the dimensions of a @size to @width x @height. a custom `GtkPaperSize` object the new width in units of @unit the new height in units of @unit the unit for @width and @height Serialize a paper size to an `a{sv}` variant. a new, floating, `GVariant` a `GtkPaperSize` This function adds the paper size from @size to @key_file. a `GtkPaperSize` the `GKeyFile` to save the paper size to the group to add the settings to in @key_file Returns the name of the default paper size, which depends on the current locale. the name of the default paper size. The string is owned by GTK and should not be modified. Creates a list of known paper sizes. a newly allocated list of newly allocated `GtkPaperSize` objects whether to include custom paper sizes as defined in the page setup dialog A `GParamSpec` for properties holding a `GtkExpression`. A single-line text entry widget for entering passwords and other secrets. <picture> <source srcset="password-entry-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkPasswordEntry" src="password-entry.png"> </picture> It does not show its contents in clear text, does not allow to copy it to the clipboard, and it shows a warning when Caps Lock is engaged. If the underlying platform allows it, `GtkPasswordEntry` will also place the text in a non-pageable memory area, to avoid it being written out to disk by the operating system. Optionally, it can offer a way to reveal the contents in clear text. `GtkPasswordEntry` provides only minimal API and should be used with the [iface@Gtk.Editable] API. # CSS Nodes ``` entry.password ╰── text ├── image.caps-lock-indicator ┊ ``` `GtkPasswordEntry` has a single CSS node with name entry that carries a .passwordstyle class. The text Css node below it has a child with name image and style class .caps-lock-indicator for the Caps Lock icon, and possibly other children. # Accessibility `GtkPasswordEntry` uses the [enum@Gtk.AccessibleRole.text_box] role. Creates a `GtkPasswordEntry`. a new `GtkPasswordEntry` Gets the menu model set with gtk_password_entry_set_extra_menu(). the menu model a `GtkPasswordEntry` Returns whether the entry is showing an icon to reveal the contents. %TRUE if an icon is shown a `GtkPasswordEntry` Sets a menu model to add when constructing the context menu for @entry. a `GtkPasswordEntry` a `GMenuModel` Sets whether the entry should have a clickable icon to reveal the contents. Setting this to %FALSE also hides the text again. a `GtkPasswordEntry` whether to show the peek icon Whether to activate the default widget when Enter is pressed. A menu model whose contents will be appended to the context menu. The text that will be displayed in the `GtkPasswordEntry` when it is empty and unfocused. Whether to show an icon for revealing the content. Emitted when the entry is activated. The keybindings for this signal are all forms of the Enter key. A `GtkEntryBuffer` that locks the underlying memory to prevent it from being swapped to disk. `GtkPasswordEntry` uses a `GtkPasswordEntryBuffer`. Creates a new `GtkEntryBuffer` using secure memory allocations. the newly created instance Flags that influence the behavior of [method@Widget.pick]. The default behavior, include widgets that are receiving events Include widgets that are insensitive Include widgets that are marked as non-targetable. See [property@Widget:can-target] Displays a `GdkPaintable`. <picture> <source srcset="picture-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkPicture" src="picture.png"> </picture> Many convenience functions are provided to make pictures simple to use. For example, if you want to load an image from a file, and then display it, there’s a convenience function to do this: ```c GtkWidget *widget = gtk_picture_new_for_filename ("myfile.png"); ``` If the file isn’t loaded successfully, the picture will contain a “broken image” icon similar to that used in many web browsers. If you want to handle errors in loading the file yourself, for example by displaying an error message, then load the image with and image loading framework such as libglycin, then create the `GtkPicture` with [ctor@Gtk.Picture.new_for_paintable]. Sometimes an application will want to avoid depending on external data files, such as image files. See the documentation of `GResource` for details. In this case, [ctor@Gtk.Picture.new_for_resource] and [method@Gtk.Picture.set_resource] should be used. `GtkPicture` displays an image at its natural size. See [class@Gtk.Image] if you want to display a fixed-size image, such as an icon. ## Sizing the paintable You can influence how the paintable is displayed inside the `GtkPicture` by changing [property@Gtk.Picture:content-fit]. See [enum@Gtk.ContentFit] for details. [property@Gtk.Picture:can-shrink] can be unset to make sure that paintables are never made smaller than their ideal size - but be careful if you do not know the size of the paintable in use (like when displaying user-loaded images). This can easily cause the picture to grow larger than the screen. And [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] can be used to make sure the paintable doesn't fill all available space but is instead displayed at its original size. ## CSS nodes `GtkPicture` has a single CSS node with the name `picture`. ## Accessibility `GtkPicture` uses the [enum@Gtk.AccessibleRole.img] role. Creates a new empty `GtkPicture` widget. a newly created `GtkPicture` widget. Creates a new `GtkPicture` displaying the given @file. If the file isn’t found or can’t be loaded, the resulting `GtkPicture` is empty. If you need to detect failures to load the file, use an image loading framework such as libglycin to load the file yourself, then create the `GtkPicture` from the texture. a new `GtkPicture` a `GFile` Creates a new `GtkPicture` displaying the file @filename. This is a utility function that calls [ctor@Gtk.Picture.new_for_file]. See that function for details. a new `GtkPicture` a filename Creates a new `GtkPicture` displaying @paintable. The `GtkPicture` will track changes to the @paintable and update its size and contents in response to it. a new `GtkPicture` a `GdkPaintable` Creates a new `GtkPicture` displaying @pixbuf. This is a utility function that calls [ctor@Gtk.Picture.new_for_paintable], See that function for details. The pixbuf must not be modified after passing it to this function. Use [ctor@Gtk.Picture.new_for_paintable] and [ctor@Gdk.Texture.new_for_pixbuf] instead a new `GtkPicture` a `GdkPixbuf` Creates a new `GtkPicture` displaying the resource at @resource_path. This is a utility function that calls [ctor@Gtk.Picture.new_for_file]. See that function for details. a new `GtkPicture` resource path to play back Gets the alternative textual description of the picture. The returned string will be %NULL if the picture cannot be described textually. the alternative textual description of @self. a `GtkPicture` Returns whether the `GtkPicture` respects its contents size. %TRUE if the picture can be made smaller than its contents a `GtkPicture` Returns the fit mode for the content of the `GtkPicture`. See [enum@Gtk.ContentFit] for details. the content fit mode a `GtkPicture` Gets the `GFile` currently displayed if @self is displaying a file. If @self is not displaying a file, for example when [method@Gtk.Picture.set_paintable] was used, then %NULL is returned. The `GFile` displayed by @self. a `GtkPicture` Returns whether the contents are isolated. True if contents are isolated a `GtkPicture` Returns whether the `GtkPicture` preserves its contents aspect ratio. Use [method@Gtk.Picture.get_content_fit] instead. This will now return `FALSE` only if [property@Gtk.Picture:content-fit] is `GTK_CONTENT_FIT_FILL`. Returns `TRUE` otherwise. %TRUE if the self tries to keep the contents' aspect ratio a `GtkPicture` Gets the `GdkPaintable` being displayed by the `GtkPicture`. the displayed paintable a `GtkPicture` Sets an alternative textual description for the picture contents. It is equivalent to the "alt" attribute for images on websites. This text will be made available to accessibility tools. If the picture cannot be described textually, set this property to %NULL. a `GtkPicture` a textual description of the contents If set to %TRUE, then @self can be made smaller than its contents. The contents will then be scaled down when rendering. If you want to still force a minimum size manually, consider using [method@Gtk.Widget.set_size_request]. Also of note is that a similar function for growing does not exist because the grow behavior can be controlled via [method@Gtk.Widget.set_halign] and [method@Gtk.Widget.set_valign]. a `GtkPicture` if @self can be made smaller than its contents Sets how the content should be resized to fit the `GtkPicture`. See [enum@Gtk.ContentFit] for details. a `GtkPicture` the content fit mode Makes @self load and display @file. See [ctor@Gtk.Picture.new_for_file] for details. ::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a `GdkTexture`, and then use [method@Gtk.Image.set_from_paintable]. a `GtkPicture` a `GFile` Makes @self load and display the given @filename. This is a utility function that calls [method@Gtk.Picture.set_file]. ::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a `GdkTexture`, and then use [method@Gtk.Image.set_from_paintable]. a `GtkPicture` the filename to play If set to true, then the contents will be rendered individually. If set to false they will be able to erase or otherwise mix with the background. GTK supports finer grained isolation, in rare cases where you need this, you can use [method@Gtk.Snapshot.push_isolation] yourself to achieve this. By default contents are isolated. a `GtkPicture` if contents are rendered separately If set to %TRUE, the @self will render its contents according to their aspect ratio. That means that empty space may show up at the top/bottom or left/right of @self. If set to %FALSE or if the contents provide no aspect ratio, the contents will be stretched over the picture's whole area. Use [method@Gtk.Picture.set_content_fit] instead. If still used, this method will always set the [property@Gtk.Picture:content-fit] property to `GTK_CONTENT_FIT_CONTAIN` if @keep_aspect_ratio is true, otherwise it will set it to `GTK_CONTENT_FIT_FILL`. a `GtkPicture` whether to keep aspect ratio Makes @self display the given @paintable. If @paintable is `NULL`, nothing will be displayed. See [ctor@Gtk.Picture.new_for_paintable] for details. a `GtkPicture` a `GdkPaintable` Sets a `GtkPicture` to show a `GdkPixbuf`. See [ctor@Gtk.Picture.new_for_pixbuf] for details. This is a utility function that calls [method@Gtk.Picture.set_paintable]. Use [method@Gtk.Picture.set_paintable] instead a `GtkPicture` a `GdkPixbuf` Makes @self load and display the resource at the given @resource_path. This is a utility function that calls [method@Gtk.Picture.set_file]. a `GtkPicture` the resource to set The alternative textual description for the picture. If the `GtkPicture` can be made smaller than the natural size of its contents. How the content should be resized to fit inside the `GtkPicture`. The `GFile` that is displayed or %NULL if none. If the rendering of the contents is isolated from the rest of the widget tree. Whether the GtkPicture will render its contents trying to preserve the aspect ratio. Use [property@Gtk.Picture:content-fit] instead. The `GdkPaintable` to be displayed by this `GtkPicture`. Determines how the size should be computed to achieve the one of the visibility mode for the scrollbars. The scrollbar is always visible. The view size is independent of the content. The scrollbar will appear and disappear as necessary. For example, when all of a `GtkTreeView` can not be seen. The scrollbar should never appear. In this mode the content determines the size. Don't show a scrollbar, but don't force the size to follow the content. This can be used e.g. to make multiple scrolled windows share a scrollbar. Presents a bubble-like popup. <picture> <source srcset="popover-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkPopover" src="popover.png"> </picture> It is primarily meant to provide context-dependent information or options. Popovers are attached to a parent widget. The parent widget must support popover children, as [class@Gtk.MenuButton] and [class@Gtk.PopoverMenuBar] do. If you want to make a custom widget that has an attached popover, you need to call [method@Gtk.Popover.present] in your [vfunc@Gtk.Widget.size_allocate] vfunc, in order to update the positioning of the popover. The position of a popover relative to the widget it is attached to can also be changed with [method@Gtk.Popover.set_position]. By default, it points to the whole widget area, but it can be made to point to a specific area using [method@Gtk.Popover.set_pointing_to]. By default, `GtkPopover` performs a grab, in order to ensure input events get redirected to it while it is shown, and also so the popover is dismissed in the expected situations (clicks outside the popover, or the Escape key being pressed). If no such modal behavior is desired on a popover, [method@Gtk.Popover.set_autohide] may be called on it to tweak its behavior. ## GtkPopover as menu replacement `GtkPopover` is often used to replace menus. The best way to do this is to use the [class@Gtk.PopoverMenu] subclass which supports being populated from a `GMenuModel` with [ctor@Gtk.PopoverMenu.new_from_model]. ```xml <section> <attribute name="display-hint">horizontal-buttons</attribute> <item> <attribute name="label">Cut</attribute> <attribute name="action">app.cut</attribute> <attribute name="verb-icon">edit-cut-symbolic</attribute> </item> <item> <attribute name="label">Copy</attribute> <attribute name="action">app.copy</attribute> <attribute name="verb-icon">edit-copy-symbolic</attribute> </item> <item> <attribute name="label">Paste</attribute> <attribute name="action">app.paste</attribute> <attribute name="verb-icon">edit-paste-symbolic</attribute> </item> </section> ``` # Shortcuts and Gestures `GtkPopover` supports the following keyboard shortcuts: - <kbd>Escape</kbd> closes the popover. - <kbd>Alt</kbd> makes the mnemonics visible. The following signals have default keybindings: - [signal@Gtk.Popover::activate-default] # CSS nodes ``` popover.background[.menu] ├── arrow ╰── contents ╰── <child> ``` `GtkPopover` has a main node with name `popover`, an arrow with name `arrow`, and another node for the content named `contents`. The `popover` node always gets the `.background` style class. It also gets the `.menu` style class if the popover is menu-like, e.g. is a [class@Gtk.PopoverMenu]. Particular uses of `GtkPopover`, such as touch selection popups or magnifiers in `GtkEntry` or `GtkTextView` get style classes like `.touch-selection` or `.magnifier` to differentiate from plain popovers. When styling a popover directly, the `popover` node should usually not have any background. The visible part of the popover can have a shadow. To specify it in CSS, set the box-shadow of the `contents` node. Note that, in order to accomplish appropriate arrow visuals, `GtkPopover` uses custom drawing for the `arrow` node. This makes it possible for the arrow to change its shape dynamically, but it also limits the possibilities of styling it using CSS. In particular, the `arrow` gets drawn over the `content` node's border and shadow, so they look like one shape, which means that the border width of the `content` node and the `arrow` node should be the same. The arrow also does not support any border shape other than solid, no border-radius, only one border width (border-bottom-width is used) and no box-shadow. Creates a new `GtkPopover`. the new `GtkPopover` Returns whether the popover is modal. See [method@Gtk.Popover.set_autohide] for the implications of this. %TRUE if @popover is modal a `GtkPopover` Returns whether the popover will close after a modal child is closed. %TRUE if @popover will close after a modal child. a `GtkPopover` Gets the child widget of @popover. the child widget of @popover a `GtkPopover` Gets whether this popover is showing an arrow pointing at the widget that it is relative to. whether the popover has an arrow a `GtkPopover` Gets whether mnemonics are visible. %TRUE if mnemonics are supposed to be visible in this popover a `GtkPopover` Gets the offset previous set with [method@Gtk.Popover.set_offset]. a `GtkPopover` a location for the x_offset a location for the y_offset Gets the rectangle that the popover points to. If a rectangle to point to has been set, this function will return %TRUE and fill in @rect with such rectangle, otherwise it will return %FALSE and fill in @rect with the parent widget coordinates. %TRUE if a rectangle to point to was set. a `GtkPopover` location to store the rectangle Returns the preferred position of @popover. The preferred position. a `GtkPopover` Pops @popover down. This may have the side-effect of closing a parent popover as well. See [property@Gtk.Popover:cascade-popdown]. a `GtkPopover` Pops @popover up. a `GtkPopover` Allocate a size for the `GtkPopover`. This function needs to be called in size-allocate by widgets who have a `GtkPopover` as child. When using a layout manager, this is happening automatically. To make a popover appear on screen, use [method@Gtk.Popover.popup]. a `GtkPopover` Sets whether @popover is modal. A modal popover will grab the keyboard focus on it when being displayed. Focus will wrap around within the popover. Clicking outside the popover area or pressing Esc will dismiss the popover. Called this function on an already showing popup with a new autohide value different from the current one, will cause the popup to be hidden. a `GtkPopover` %TRUE to dismiss the popover on outside clicks If @cascade_popdown is %TRUE, the popover will be closed when a child modal popover is closed. If %FALSE, @popover will stay visible. A `GtkPopover` %TRUE if the popover should follow a child closing Sets the child widget of @popover. a `GtkPopover` the child widget Sets the default widget of a `GtkPopover`. The default widget is the widget that’s activated when the user presses Enter in a dialog (for example). This function sets or unsets the default widget for a `GtkPopover`. a `GtkPopover` a child widget of @popover to set as the default, or %NULL to unset the default widget for the popover Sets whether this popover should draw an arrow pointing at the widget it is relative to. a `GtkPopover` %TRUE to draw an arrow Sets whether mnemonics should be visible. a `GtkPopover` the new value Sets the offset to use when calculating the position of the popover. These values are used when preparing the [struct@Gdk.PopupLayout] for positioning the popover. a `GtkPopover` the x offset to adjust the position by the y offset to adjust the position by Sets the rectangle that @popover points to. This is in the coordinate space of the @popover parent. a `GtkPopover` rectangle to point to Sets the preferred position for @popover to appear. If the @popover is currently visible, it will be immediately updated. This preference will be respected where possible, although on lack of space (eg. if close to the window edges), the `GtkPopover` may choose to appear on the opposite side. a `GtkPopover` preferred popover position Whether to dismiss the popover on outside clicks. Whether the popover pops down after a child popover. This is used to implement the expected behavior of submenus. The child widget. The default widget inside the popover. Whether to draw an arrow. Whether mnemonics are currently visible in this popover. Rectangle in the parent widget that the popover points to. How to place the popover, relative to its parent. Emitted whend the user activates the default widget. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Enter</kbd>. Emitted when the popover is closed. A single child container with a popover. You should use `GtkPopoverBin` whenever you need to present a [class@Gtk.Popover] to the user. ## Actions `GtkPopoverBin` defines the `menu.popup` action, which can be activated to present the popover to the user. ## CSS nodes `GtkPopoverBin` has a single CSS node with the name `popoverbin`. Creates a new popover bin widget. the newly created popover bin Retrieves the child widget of the popover bin. the child widget a popover bin Retrieves the menu model set using [method@Gtk.PopoverBin.set_menu_model]. the menu model for the popover a popover bin Retrieves the `GtkPopover` set using [method@Gtk.PopoverBin.set_popover]. a popover widget a popover bin Hides the popover from the user. See: [method@Gtk.PopoverBin.popup] a popover bin Presents the popover to the user. Use [method@Gtk.PopoverBin.set_popover] or [method@Gtk.PopoverBin.set_menu_model] to define the popover. See: [method@Gtk.PopoverBin.popdown] a popover bin Sets the child of the popover bin. a popover bin the child of the popover bin Enables or disables input handling. If enabled, the popover bin will pop up the popover on right-click or long press, as expected for a context menu. a popover bin whether to handle input Sets the menu model used to create the popover that will be presented when calling [method@Gtk.PopoverBin.popup]. If @model is `NULL`, the popover will be unset. A [class@Gtk.Popover] will be created from the menu model with [ctor@Gtk.PopoverMenu.new_from_model]. Actions will be connected as documented for this function. If [property@Gtk.PopoverBin:popover] is already set, it will be dissociated from the popover bin, and the property is set to `NULL`. See: [method@Gtk.PopoverBin.set_popover] a popover bin a menu model Sets the `GtkPopover` that will be presented when calling [method@Gtk.PopoverBin.popup]. If @popover is `NULL`, the popover will be unset. If [property@Gtk.PopoverBin:menu-model] is set before calling this function, then the menu model property will be unset. See: [method@Gtk.PopoverBin.set_menu_model] a popover bin a `GtkPopover` The child widget of the popover bin. Whether the popover bin will handle input to trigger the popup. The `GMenuModel` from which the popup will be created. See [method@Gtk.PopoverBin.set_menu_model] for the interaction with the [property@Gtk.PopoverBin:popover] property. The `GtkPopover` that will be popped up when calling [method@Gtk.PopoverBin.popup]. A subclass of `GtkPopover` that implements menu behavior. <picture> <source srcset="menu-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkPopoverMenu" src="menu.png"> </picture> `GtkPopoverMenu` treats its children like menus and allows switching between them. It can open submenus as traditional, nested submenus, or in a more touch-friendly sliding fashion. The property [property@Gtk.PopoverMenu:flags] controls this appearance. `GtkPopoverMenu` is meant to be used primarily with menu models, using [ctor@Gtk.PopoverMenu.new_from_model]. If you need to put other widgets such as a `GtkSpinButton` or a `GtkSwitch` into a popover, you can use [method@Gtk.PopoverMenu.add_child]. For more dialog-like behavior, use a plain `GtkPopover`. ## Menu models The XML format understood by `GtkBuilder` for `GMenuModel` consists of a toplevel `<menu>` element, which contains one or more `<item>` elements. Each `<item>` element contains `<attribute>` and `<link>` elements with a mandatory name attribute. `<link>` elements have the same content model as `<menu>`. Instead of `<link name="submenu">` or `<link name="section">`, you can use `<submenu>` or `<section>` elements. ```xml <menu id='app-menu'> <section> <item> <attribute name='label' translatable='yes'>_New Window</attribute> <attribute name='action'>app.new</attribute> </item> <item> <attribute name='label' translatable='yes'>_About Sunny</attribute> <attribute name='action'>app.about</attribute> </item> <item> <attribute name='label' translatable='yes'>_Quit</attribute> <attribute name='action'>app.quit</attribute> </item> </section> </menu> ``` Attribute values can be translated using gettext, like other `GtkBuilder` content. `<attribute>` elements can be marked for translation with a `translatable="yes"` attribute. It is also possible to specify message context and translator comments, using the context and comments attributes. To make use of this, the `GtkBuilder` must have been given the gettext domain to use. The following attributes are used when constructing menu items: - "label": a user-visible string to display - "use-markup": whether the text in the menu item includes [Pango markup](https://docs.gtk.org/Pango/pango_markup.html) - "action": the prefixed name of the action to trigger - "target": the parameter to use when activating the action - "icon" and "verb-icon": names of icons that may be displayed - "submenu-action": name of an action that may be used to track whether a submenu is open - "hidden-when": a string used to determine when the item will be hidden. Possible values include "action-disabled", "action-missing", "macos-menubar". This is mainly useful for exported menus, see [method@Gtk.Application.set_menubar]. - "custom": a string used to match against the ID of a custom child added with [method@Gtk.PopoverMenu.add_child], [method@Gtk.PopoverMenuBar.add_child], or in the ui file with `<child type="ID">`. The following attributes are used when constructing sections: - "label": a user-visible string to use as section heading - "display-hint": a string used to determine special formatting for the section. Possible values include "horizontal-buttons", "circular-buttons" and "inline-buttons". They all indicate that section should be displayed as a horizontal row of buttons. - "text-direction": a string used to determine the `GtkTextDirection` to use when "display-hint" is set to "horizontal-buttons". Possible values include "rtl", "ltr", and "none". The following attributes are used when constructing submenus: - "label": a user-visible string to display - "icon": icon name to display - "gtk-macos-special": (macOS only, ignored by others) Add special meaning to a menu in the macOS menu bar. See [Using GTK on Apple macOS](osx.html). Menu items will also show accelerators, which are usually associated with actions via [method@Gtk.Application.set_accels_for_action], [method@WidgetClass.add_binding_action] or [method@Gtk.ShortcutController.add_shortcut]. # Shortcuts and Gestures `GtkPopoverMenu` supports the following keyboard shortcuts: - <kbd>Space</kbd> activates the default widget. # CSS Nodes `GtkPopoverMenu` is just a subclass of `GtkPopover` that adds custom content to it, therefore it has the same CSS nodes. It is one of the cases that add a `.menu` style class to the main `popover` node. Menu items have nodes with name `button` and class `.model`. If a section display-hint is set, the section gets a node `box` with class `horizontal` plus a class with the same text as the display hint. Note that said box may not be the direct ancestor of the item `button`s. Thus, for example, to style items in an `inline-buttons` section, select `.inline-buttons button.model`. Other things that may be of interest to style in menus include `label` nodes. # Accessibility `GtkPopoverMenu` uses the [enum@Gtk.AccessibleRole.menu] role, and its items use the [enum@Gtk.AccessibleRole.menu_item], [enum@Gtk.AccessibleRole.checkbox] or [enum@Gtk.AccessibleRole.menu_item_radio] roles, depending on the action they are connected to. Creates a `GtkPopoverMenu` and populates it according to @model. The created buttons are connected to actions found in the `GtkApplicationWindow` to which the popover belongs - typically by means of being attached to a widget that is contained within the `GtkApplicationWindow`s widget hierarchy. Actions can also be added using [method@Gtk.Widget.insert_action_group] on the menus attach widget or on any of its parent widgets. This function creates menus with sliding submenus. See [ctor@Gtk.PopoverMenu.new_from_model_full] for a way to control this. the new `GtkPopoverMenu` a `GMenuModel` Creates a `GtkPopoverMenu` and populates it according to @model. The created buttons are connected to actions found in the action groups that are accessible from the parent widget. This includes the `GtkApplicationWindow` to which the popover belongs. Actions can also be added using [method@Gtk.Widget.insert_action_group] on the parent widget or on any of its parent widgets. the new `GtkPopoverMenu` a `GMenuModel` flags that affect how the menu is created Adds a custom widget to a generated menu. For this to work, the menu model of @popover must have an item with a `custom` attribute that matches @id. %TRUE if @id was found and the widget added a `GtkPopoverMenu` the `GtkWidget` to add the ID to insert @child at Returns the flags that @popover uses to create/display a menu from its model. the `GtkPopoverMenuFlags` a `GtkPopoverMenu` Returns the menu model used to populate the popover. the menu model of @popover a `GtkPopoverMenu` Removes a widget that has previously been added with [method@Gtk.PopoverMenu.add_child] %TRUE if the widget was removed a `GtkPopoverMenu` the `GtkWidget` to remove Sets the flags that @popover uses to create/display a menu from its model. If a model is set and the flags change, contents are rebuilt, so if setting properties individually, set flags before model to avoid a redundant rebuild. a `GtkPopoverMenu` a set of `GtkPopoverMenuFlags` Sets a new menu model on @popover. The existing contents of @popover are removed, and the @popover is populated with new contents according to @model. a `GtkPopoverMenu` a `GMenuModel` The flags that @popover uses to create/display a menu from its model. If a model is set and the flags change, contents are rebuilt, so if setting properties individually, set flags before model to avoid a redundant rebuild. The model from which the menu is made. The name of the visible submenu. Presents a horizontal bar of items that pop up menus when clicked. <picture> <source srcset="menubar-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkPopoverMenuBar" src="menubar.png"> </picture> The only way to create instances of `GtkPopoverMenuBar` is from a `GMenuModel`. # CSS nodes ``` menubar ├── item[.active] ┊ ╰── popover ╰── item ╰── popover ``` `GtkPopoverMenuBar` has a single CSS node with name menubar, below which each item has its CSS node, and below that the corresponding popover. The item whose popover is currently open gets the .active style class. # Accessibility `GtkPopoverMenuBar` uses the [enum@Gtk.AccessibleRole.menu_bar] role, the menu items use the [enum@Gtk.AccessibleRole.menu_item] role and the menus use the [enum@Gtk.AccessibleRole.menu] role. Creates a `GtkPopoverMenuBar` from a `GMenuModel`. a new `GtkPopoverMenuBar` a `GMenuModel` Adds a custom widget to a generated menubar. For this to work, the menu model of @bar must have an item with a `custom` attribute that matches @id. %TRUE if @id was found and the widget added a `GtkPopoverMenuBar` the `GtkWidget` to add the ID to insert @child at Returns the model from which the contents of @bar are taken. a `GMenuModel` a `GtkPopoverMenuBar` Removes a widget that has previously been added with gtk_popover_menu_bar_add_child(). %TRUE if the widget was removed a `GtkPopoverMenuBar` the `GtkWidget` to remove Sets a menu model from which @bar should take its contents. a `GtkPopoverMenuBar` a `GMenuModel` The `GMenuModel` from which the menu bar is created. The model should only contain submenus as toplevel elements. Flags that affect how [class@Gtk.PopoverMenu] widgets built from a [class@Gio.MenuModel] are created and displayed. Submenus are presented as sliding submenus that replace the main menu. Submenus are presented as traditional, nested popovers. Describes which edge of a widget a certain feature is positioned at. For examples, see the tabs of a [class@Notebook], or the label of a [class@Scale]. The feature is at the left edge. The feature is at the right edge. The feature is at the top edge. The feature is at the bottom edge. A print backend. Specifies which features the print dialog should offer. If neither %GTK_PRINT_CAPABILITY_GENERATE_PDF nor %GTK_PRINT_CAPABILITY_GENERATE_PS is specified, GTK assumes that all formats are supported. Print dialog will offer printing even/odd pages. Print dialog will allow to print multiple copies. Print dialog will allow to collate multiple copies. Print dialog will allow to print pages in reverse order. Print dialog will allow to scale the output. The program will send the document to the printer in PDF format The program will send the document to the printer in Postscript format Print dialog will offer a preview Print dialog will offer printing multiple pages per sheet Print dialog will allow to rearrange pages when printing multiple pages per sheet Encapsulates context information that is required when drawing pages for printing. This includes the cairo context and important parameters like page size and resolution. It also lets you easily create [class@Pango.Layout] and [class@Pango.Context] objects that match the font metrics of the cairo surface. `GtkPrintContext` objects get passed to the [signal@Gtk.PrintOperation::begin-print], [signal@Gtk.PrintOperation::end-print], [signal@Gtk.PrintOperation::request-page-setup] and [signal@Gtk.PrintOperation::draw-page] signals on the [class@Gtk.PrintOperation] object. ## Using GtkPrintContext in a ::draw-page callback ```c static void draw_page (GtkPrintOperation *operation, GtkPrintContext *context, int page_nr) { cairo_t *cr; PangoLayout *layout; PangoFontDescription *desc; cr = gtk_print_context_get_cairo_context (context); // Draw a red rectangle, as wide as the paper (inside the margins) cairo_set_source_rgb (cr, 1.0, 0, 0); cairo_rectangle (cr, 0, 0, gtk_print_context_get_width (context), 50); cairo_fill (cr); // Draw some lines cairo_move_to (cr, 20, 10); cairo_line_to (cr, 40, 20); cairo_arc (cr, 60, 60, 20, 0, M_PI); cairo_line_to (cr, 80, 20); cairo_set_source_rgb (cr, 0, 0, 0); cairo_set_line_width (cr, 5); cairo_set_line_cap (cr, CAIRO_LINE_CAP_ROUND); cairo_set_line_join (cr, CAIRO_LINE_JOIN_ROUND); cairo_stroke (cr); // Draw some text layout = gtk_print_context_create_pango_layout (context); pango_layout_set_text (layout, "Hello World! Printing is easy", -1); desc = pango_font_description_from_string ("sans 28"); pango_layout_set_font_description (layout, desc); pango_font_description_free (desc); cairo_move_to (cr, 30, 20); pango_cairo_layout_path (cr, layout); // Font Outline cairo_set_source_rgb (cr, 0.93, 1.0, 0.47); cairo_set_line_width (cr, 0.5); cairo_stroke_preserve (cr); // Font Fill cairo_set_source_rgb (cr, 0, 0.0, 1.0); cairo_fill (cr); g_object_unref (layout); } ``` Creates a new `PangoContext` that can be used with the `GtkPrintContext`. a new Pango context for @context a `GtkPrintContext` Creates a new `PangoLayout` that is suitable for use with the `GtkPrintContext`. a new Pango layout for @context a `GtkPrintContext` Obtains the cairo context that is associated with the `GtkPrintContext`. the cairo context of @context a `GtkPrintContext` Obtains the horizontal resolution of the `GtkPrintContext`, in dots per inch. the horizontal resolution of @context a `GtkPrintContext` Obtains the vertical resolution of the `GtkPrintContext`, in dots per inch. the vertical resolution of @context a `GtkPrintContext` Obtains the hardware printer margins of the `GtkPrintContext`, in units. %TRUE if the hard margins were retrieved a `GtkPrintContext` top hardware printer margin bottom hardware printer margin left hardware printer margin right hardware printer margin Obtains the height of the `GtkPrintContext`, in pixels. the height of @context a `GtkPrintContext` Obtains the `GtkPageSetup` that determines the page dimensions of the `GtkPrintContext`. the page setup of @context a `GtkPrintContext` Returns a `PangoFontMap` that is suitable for use with the `GtkPrintContext`. the font map of @context a `GtkPrintContext` Obtains the width of the `GtkPrintContext`, in pixels. the width of @context a `GtkPrintContext` Sets a new cairo context on a print context. This function is intended to be used when implementing an internal print preview, it is not needed for printing, since GTK itself creates a suitable cairo context in that case. a `GtkPrintContext` the cairo context the horizontal resolution to use with @cr the vertical resolution to use with @cr Asynchronous API to present a print dialog to the user. `GtkPrintDialog` collects the arguments that are needed to present the dialog, such as a title for the dialog and whether it should be modal. The dialog is shown with the [method@Gtk.PrintDialog.setup] function. The actual printing can be done with [method@Gtk.PrintDialog.print] or [method@Gtk.PrintDialog.print_file]. These APIs follows the GIO async pattern, and the results can be obtained by calling the corresponding finish methods. Creates a new `GtkPrintDialog` object. the new `GtkPrintDialog` Returns the label that will be shown on the accept button of the print dialog. the accept label a `GtkPrintDialog` Returns whether the print dialog blocks interaction with the parent window while it is presented. whether the print dialog is modal a `GtkPrintDialog` Returns the page setup. the page setup a `GtkPrintDialog` Returns the print settings for the print dialog. the settings a `GtkPrintDialog` Returns the title that will be shown on the print dialog. the title a `GtkPrintDialog` This function prints content from a stream. If you pass `NULL` as @setup, then this method will present a print dialog. Otherwise, it will attempt to print directly, without user interaction. The @callback will be called when the printing is done. a `GtkPrintDialog` the parent `GtkWindow` the `GtkPrintSetup` to use a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback This function prints a file. If you pass `NULL` as @setup, then this method will present a print dialog. Otherwise, it will attempt to print directly, without user interaction. a `GtkPrintDialog` the parent `GtkWindow` the `GtkPrintSetup` to use the `GFile` to print a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.PrintDialog.print_file] call and returns the results. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. Whether the call was successful a `GtkPrintDialog` a `GAsyncResult` Finishes the [method@Gtk.PrintDialog.print] call and returns the results. If the call was successful, the content to be printed should be written to the returned output stream. Otherwise, `NULL` is returned. The overall results of the print operation will be returned in the [method@Gio.OutputStream.close] call, so if you are interested in the results, you need to explicitly close the output stream (it will be closed automatically if you just unref it). Be aware that the close call may not be instant as it operation will for the printer to finish printing. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. a [class@Gio.OutputStream] a `GtkPrintDialog` a `GAsyncResult` Sets the label that will be shown on the accept button of the print dialog shown for [method@Gtk.PrintDialog.setup]. a `GtkPrintDialog` the new accept label Sets whether the print dialog blocks interaction with the parent window while it is presented. a `GtkPrintDialog` the new value Set the page setup for the print dialog. a `GtkPrintDialog` the new page setup Sets the print settings for the print dialog. a `GtkPrintDialog` the new print settings Sets the title that will be shown on the print dialog. a `GtkPrintDialog` the new title This function presents a print dialog to let the user select a printer, and set up print settings and page setup. The @callback will be called when the dialog is dismissed. The obtained [struct@Gtk.PrintSetup] can then be passed to [method@Gtk.PrintDialog.print] or [method@Gtk.PrintDialog.print_file]. One possible use for this method is to have the user select a printer, then show a page setup UI in the application (e.g. to arrange images on a page), then call [method@Gtk.PrintDialog.print] on @self to do the printing without further user interaction. a `GtkPrintDialog` the parent `GtkWindow` a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.PrintDialog.setup] call. If the call was successful, it returns a [struct@Gtk.PrintSetup] which contains the print settings and page setup information that will be used to print. Note that this function returns a [error@Gtk.DialogError.DISMISSED] error if the user cancels the dialog. the resulting `[struct@Gtk.PrintSetup]` a `GtkPrintDialog` a `GAsyncResult` A label that may be shown on the accept button of a print dialog that is presented by [method@Gtk.PrintDialog.setup]. Whether the print dialog is modal. The page setup to use. The print settings to use. A title that may be shown on the print dialog that is presented by [method@Gtk.PrintDialog.setup]. See also gtk_print_settings_set_duplex(). No duplex. Horizontal duplex. Vertical duplex. Error codes that identify various errors that can occur while using the GTK printing support. An unspecified error occurred. An internal error occurred. A memory allocation failed. An error occurred while loading a page setup or paper size from a key file. Registers an error quark for `GtkPrintOperation` if necessary. The error quark used for `GtkPrintOperation` errors. Represents a job that is sent to a printer. You only need to deal directly with print jobs if you use the non-portable [class@Gtk.PrintUnixDialog] API. Use [method@Gtk.PrintJob.get_surface] to obtain the cairo surface onto which the pages must be drawn. Use [method@Gtk.PrintJob.send] to send the finished job to the printer. If you don’t use cairo `GtkPrintJob` also supports printing of manually generated PostScript, via [method@Gtk.PrintJob.set_source_file]. Creates a new `GtkPrintJob`. a new `GtkPrintJob` the job title a `GtkPrinter` a `GtkPrintSettings` a `GtkPageSetup` Gets whether this job is printed collated. whether the job is printed collated a `GtkPrintJob` Gets the n-up setting for this job. the n-up setting a `GtkPrintJob` Gets the n-up layout setting for this job. the n-up layout a `GtkPrintJob` Gets the number of copies of this job. the number of copies a `GtkPrintJob` Gets the page ranges for this job. a pointer to an array of `GtkPageRange` structs a `GtkPrintJob` return location for the number of ranges Gets the `GtkPageSet` setting for this job. the `GtkPageSet` setting a `GtkPrintJob` Gets the `GtkPrintPages` setting for this job. the `GtkPrintPages` setting a `GtkPrintJob` Gets the `GtkPrinter` of the print job. the printer of @job a `GtkPrintJob` Gets whether this job is printed reversed. whether the job is printed reversed. a `GtkPrintJob` Gets whether the job is printed rotated. whether the job is printed rotated a `GtkPrintJob` Gets the scale for this job. the scale a `GtkPrintJob` Gets the `GtkPrintSettings` of the print job. the settings of @job a `GtkPrintJob` Gets the status of the print job. the status of @job a `GtkPrintJob` Gets a cairo surface onto which the pages of the print job should be rendered. the cairo surface of @job a `GtkPrintJob` Gets the job title. the title of @job a `GtkPrintJob` Returns whether jobs will be tracked after printing. For details, see [method@Gtk.PrintJob.set_track_print_status]. %TRUE if print job status will be reported after printing a `GtkPrintJob` Sends the print job off to the printer. a `GtkPrintJob` function to call when the job completes or an error occurs user data that gets passed to @callback destroy notify for @user_data Sets whether this job is printed collated. a `GtkPrintJob` whether the job is printed collated Sets the n-up setting for this job. a `GtkPrintJob` the n-up value Sets the n-up layout setting for this job. a `GtkPrintJob` the n-up layout setting Sets the number of copies for this job. a `GtkPrintJob` the number of copies Sets the page ranges for this job. a `GtkPrintJob` pointer to an array of `GtkPageRange` structs the length of the @ranges array Sets the `GtkPageSet` setting for this job. a `GtkPrintJob` a `GtkPageSet` setting Sets the `GtkPrintPages` setting for this job. a `GtkPrintJob` the `GtkPrintPages` setting Sets whether this job is printed reversed. a `GtkPrintJob` whether the job is printed reversed Sets whether this job is printed rotated. a `GtkPrintJob` whether to print rotated Sets the scale for this job. 1.0 means unscaled. a `GtkPrintJob` the scale Make the `GtkPrintJob` send an existing document to the printing system. The file can be in any format understood by the platforms printing system (typically PostScript, but on many platforms PDF may work too). See [method@Gtk.Printer.accepts_pdf] and [method@Gtk.Printer.accepts_ps]. This is similar to [method@Gtk.PrintJob.set_source_file], but takes expects an open file descriptor for the file, instead of a filename. %FALSE if an error occurred a `GtkPrintJob` a file descriptor Make the `GtkPrintJob` send an existing document to the printing system. The file can be in any format understood by the platforms printing system (typically PostScript, but on many platforms PDF may work too). See [method@Gtk.Printer.accepts_pdf] and [method@Gtk.Printer.accepts_ps]. %FALSE if an error occurred a `GtkPrintJob` the file to be printed If track_status is %TRUE, the print job will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like “out of paper” issues, and when the print job actually reaches the printer. This function is often implemented using some form of polling, so it should not be enabled unless needed. a `GtkPrintJob` %TRUE to track status after printing Page setup. The printer to send the job to. Printer settings. The title of the print job. %TRUE if the print job will continue to emit status-changed signals after the print data has been setn to the printer. Emitted when the status of a job changes. The signal handler can use [method@Gtk.PrintJob.get_status] to obtain the new status. The type of callback that is passed to gtk_print_job_send(). It is called when the print job has been completely sent. the `GtkPrintJob` user data that has been passed to gtk_print_job_send() a `GError` that contains error information if the sending of the print job failed, otherwise %NULL High-level, portable printing API. It looks a bit different than other GTK dialogs such as the `GtkFileChooser`, since some platforms don’t expose enough infrastructure to implement a good print dialog. On such platforms, `GtkPrintOperation` uses the native print dialog. On platforms which do not provide a native print dialog, GTK uses its own, see [class@Gtk.PrintUnixDialog]. The typical way to use the high-level printing API is to create a `GtkPrintOperation` object with [ctor@Gtk.PrintOperation.new] when the user selects to print. Then you set some properties on it, e.g. the page size, any [class@Gtk.PrintSettings] from previous print operations, the number of pages, the current page, etc. Then you start the print operation by calling [method@Gtk.PrintOperation.run]. It will then show a dialog, let the user select a printer and options. When the user finished the dialog, various signals will be emitted on the `GtkPrintOperation`, the main one being [signal@Gtk.PrintOperation::draw-page], which you are supposed to handle and render the page on the provided [class@Gtk.PrintContext] using Cairo. # The high-level printing API ```c static GtkPrintSettings *settings = NULL; static void do_print (void) { GtkPrintOperation *print; GtkPrintOperationResult res; print = gtk_print_operation_new (); if (settings != NULL) gtk_print_operation_set_print_settings (print, settings); g_signal_connect (print, "begin_print", G_CALLBACK (begin_print), NULL); g_signal_connect (print, "draw_page", G_CALLBACK (draw_page), NULL); res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, GTK_WINDOW (main_window), NULL); if (res == GTK_PRINT_OPERATION_RESULT_APPLY) { if (settings != NULL) g_object_unref (settings); settings = g_object_ref (gtk_print_operation_get_print_settings (print)); } g_object_unref (print); } ``` By default `GtkPrintOperation` uses an external application to do print preview. To implement a custom print preview, an application must connect to the preview signal. The functions [method@Gtk.PrintOperationPreview.render_page], [method@Gtk.PrintOperationPreview.end_preview] and [method@Gtk.PrintOperationPreview.is_selected] are useful when implementing a print preview. Creates a new `GtkPrintOperation`. a new `GtkPrintOperation` Signal emitted after the user has finished changing print settings in the dialog, before the actual rendering starts. Signal emitted when displaying the print dialog. Signal emitted right before “begin-print” if you added a custom widget in the “create-custom-widget” handler. Signal emitted when the print operation run has finished doing everything required for printing. Signal emitted for every page that is printed. Signal emitted after all pages have been rendered. Signal emitted after the “begin-print” signal, but before the actual rendering starts. Signal emitted when a preview is requested from the native dialog. Emitted once for every page that is printed, to give the application a chance to modify the page setup. Emitted at between the various phases of the print operation. Emitted after change of selected printer. Cancels a running print operation. This function may be called from a [signal@Gtk.PrintOperation::begin-print], [signal@Gtk.PrintOperation::paginate] or [signal@Gtk.PrintOperation::draw-page] signal handler to stop the currently running print operation. a `GtkPrintOperation` Signal that drawing of particular page is complete. It is called after completion of page drawing (e.g. drawing in another thread). If [method@Gtk.PrintOperation.set_defer_drawing] was called before, then this function has to be called by application. Otherwise it is called by GTK itself. a `GtkPrintOperation` Returns the default page setup. the default page setup a `GtkPrintOperation` Gets whether page setup selection combos are embedded whether page setup selection combos are embedded a `GtkPrintOperation` Call this when the result of a print operation is %GTK_PRINT_OPERATION_RESULT_ERROR. It can be called either after [method@Gtk.PrintOperation.run] returns, or in the [signal@Gtk.PrintOperation::done] signal handler. The returned `GError` will contain more details on what went wrong. a `GtkPrintOperation` Gets whether there is a selection. whether there is a selection a `GtkPrintOperation` Returns the number of pages that will be printed. Note that this value is set during print preparation phase (%GTK_PRINT_STATUS_PREPARING), so this function should never be called before the data generation phase (%GTK_PRINT_STATUS_GENERATING_DATA). You can connect to the [signal@Gtk.PrintOperation::status-changed] signal and call gtk_print_operation_get_n_pages_to_print() when print status is %GTK_PRINT_STATUS_GENERATING_DATA. This is typically used to track the progress of print operation. the number of pages that will be printed a `GtkPrintOperation` Returns the current print settings. Note that the return value is %NULL until either [method@Gtk.PrintOperation.set_print_settings] or [method@Gtk.PrintOperation.run] have been called. the current print settings of @op. a `GtkPrintOperation` Returns the status of the print operation. Also see [method@Gtk.PrintOperation.get_status_string]. the status of the print operation a `GtkPrintOperation` Returns a string representation of the status of the print operation. The string is translated and suitable for displaying the print status e.g. in a `GtkStatusbar`. Use [method@Gtk.PrintOperation.get_status] to obtain a status value that is suitable for programmatic use. a string representation of the status of the print operation a `GtkPrintOperation` Gets whether the application supports print of selection whether the application supports print of selection a `GtkPrintOperation` A convenience function to find out if the print operation is finished. a print operation is finished if its status is either %GTK_PRINT_STATUS_FINISHED or %GTK_PRINT_STATUS_FINISHED_ABORTED. Note: when you enable print status tracking the print operation can be in a non-finished state even after done has been called, as the operation status then tracks the print job status on the printer. %TRUE, if the print operation is finished. a `GtkPrintOperation` Runs the print operation. Normally that this function does not return until the rendering of all pages is complete. You can connect to the [signal@Gtk.PrintOperation::status-changed] signal on @op to obtain some information about the progress of the print operation. Furthermore, it may use a recursive mainloop to show the print dialog. If you set the [Gtk.PrintOperation:allow-async] property, the operation will run asynchronously if this is supported on the platform. The [signal@Gtk.PrintOperation::done] signal will be emitted with the result of the operation when the it is done (i.e. when the dialog is canceled, or when the print succeeds or fails). ```c if (settings != NULL) gtk_print_operation_set_print_settings (print, settings); if (page_setup != NULL) gtk_print_operation_set_default_page_setup (print, page_setup); g_signal_connect (print, "begin-print", G_CALLBACK (begin_print), &data); g_signal_connect (print, "draw-page", G_CALLBACK (draw_page), &data); res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, parent, &error); if (res == GTK_PRINT_OPERATION_RESULT_ERROR) { error_dialog = gtk_message_dialog_new (GTK_WINDOW (parent), GTK_DIALOG_DESTROY_WITH_PARENT, GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, "Error printing file:\n%s", error->message); g_signal_connect (error_dialog, "response", G_CALLBACK (gtk_window_destroy), NULL); gtk_window_present (GTK_WINDOW (error_dialog)); g_error_free (error); } else if (res == GTK_PRINT_OPERATION_RESULT_APPLY) { if (settings != NULL) g_object_unref (settings); settings = g_object_ref (gtk_print_operation_get_print_settings (print)); } ``` Note that gtk_print_operation_run() can only be called once on a given `GtkPrintOperation`. the result of the print operation. A return value of %GTK_PRINT_OPERATION_RESULT_APPLY indicates that the printing was completed successfully. In this case, it is a good idea to obtain the used print settings with [method@Gtk.PrintOperation.get_print_settings] and store them for reuse with the next print operation. A value of %GTK_PRINT_OPERATION_RESULT_IN_PROGRESS means the operation is running asynchronously, and will emit the [signal@Gtk.PrintOperation::done] signal when done. a `GtkPrintOperation` the action to start Transient parent of the dialog Sets whether gtk_print_operation_run() may return before the print operation is completed. Note that some platforms may not allow asynchronous operation. a `GtkPrintOperation` %TRUE to allow asynchronous operation Sets the current page. If this is called before [method@Gtk.PrintOperation.run], the user will be able to select to print only the current page. Note that this only makes sense for pre-paginated documents. a `GtkPrintOperation` the current page, 0-based Sets the label for the tab holding custom widgets. a `GtkPrintOperation` the label to use, or %NULL to use the default label Makes @default_page_setup the default page setup for @op. This page setup will be used by [method@Gtk.PrintOperation.run], but it can be overridden on a per-page basis by connecting to the [signal@Gtk.PrintOperation::request-page-setup] signal. a `GtkPrintOperation` a `GtkPageSetup` Sets up the `GtkPrintOperation` to wait for calling of [method@Gtk.PrintOperation.draw_page_finish from application. This can be used for drawing page in another thread. This function must be called in the callback of the [signal@Gtk.PrintOperation::draw-page] signal. a `GtkPrintOperation` Embed page size combo box and orientation combo box into page setup page. Selected page setup is stored as default page setup in `GtkPrintOperation`. a `GtkPrintOperation` %TRUE to embed page setup selection in the `GtkPrintUnixDialog` Sets up the `GtkPrintOperation` to generate a file instead of showing the print dialog. The intended use of this function is for implementing “Export to PDF” actions. Currently, PDF is the only supported format. “Print to PDF” support is independent of this and is done by letting the user pick the “Print to PDF” item from the list of printers in the print dialog. a `GtkPrintOperation` the filename for the exported file Sets whether there is a selection to print. Application has to set number of pages to which the selection will draw by [method@Gtk.PrintOperation.set_n_pages] in a handler for the [signal@Gtk.PrintOperation::begin-print] signal. a `GtkPrintOperation` %TRUE indicates that a selection exists Sets the name of the print job. The name is used to identify the job (e.g. in monitoring applications like eggcups). If you don’t set a job name, GTK picks a default one by numbering successive print jobs. a `GtkPrintOperation` a string that identifies the print job Sets the number of pages in the document. This must be set to a positive number before the rendering starts. It may be set in a [signal@Gtk.PrintOperation::begin-print] signal handler. Note that the page numbers passed to the [signal@Gtk.PrintOperation::request-page-setup] and [signal@Gtk.PrintOperation::draw-page] signals are 0-based, i.e. if the user chooses to print all pages, the last ::draw-page signal will be for page @n_pages - 1. a `GtkPrintOperation` the number of pages Sets the print settings for @op. This is typically used to re-establish print settings from a previous print operation, see [method@Gtk.PrintOperation.run]. a `GtkPrintOperation` `GtkPrintSettings` If @show_progress is %TRUE, the print operation will show a progress dialog during the print operation. a `GtkPrintOperation` %TRUE to show a progress dialog Sets whether selection is supported by `GtkPrintOperation`. a `GtkPrintOperation` %TRUE to support selection If track_status is %TRUE, the print operation will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like “out of paper” issues, and when the print job actually reaches the printer. This function is often implemented using some form of polling, so it should not be enabled unless needed. a `GtkPrintOperation` %TRUE to track status after printing Sets up the transformation for the cairo context obtained from `GtkPrintContext` in such a way that distances are measured in units of @unit. a `GtkPrintOperation` the unit to use If @full_page is %TRUE, the transformation for the cairo context obtained from `GtkPrintContext` puts the origin at the top left corner of the page. This may not be the top left corner of the sheet, depending on page orientation and the number of pages per sheet). Otherwise, the origin is at the top left corner of the imageable area (i.e. inside the margins). a `GtkPrintOperation` %TRUE to set up the `GtkPrintContext` for the full page Determines whether the print operation may run asynchronously or not. Some systems don't support asynchronous printing, but those that do will return %GTK_PRINT_OPERATION_RESULT_IN_PROGRESS as the status, and emit the [signal@Gtk.PrintOperation::done] signal when the operation is actually done. The Windows port does not support asynchronous operation at all (this is unlikely to change). On other platforms, all actions except for %GTK_PRINT_OPERATION_ACTION_EXPORT support asynchronous operation. The current page in the document. If this is set before [method@Gtk.PrintOperation.run], the user will be able to select to print only the current page. Note that this only makes sense for pre-paginated documents. Used as the label of the tab containing custom widgets. Note that this property may be ignored on some platforms. If this is %NULL, GTK uses a default label. The `GtkPageSetup` used by default. This page setup will be used by [method@Gtk.PrintOperation.run], but it can be overridden on a per-page basis by connecting to the [signal@Gtk.PrintOperation::request-page-setup] signal. If %TRUE, page size combo box and orientation combo box are embedded into page setup page. The name of a file to generate instead of showing the print dialog. Currently, PDF is the only supported format. The intended use of this property is for implementing “Export to PDF” actions. “Print to PDF” support is independent of this and is done by letting the user pick the “Print to PDF” item from the list of printers in the print dialog. Determines whether there is a selection in your application. This can allow your application to print the selection. This is typically used to make a "Selection" button sensitive. A string used to identify the job (e.g. in monitoring applications like eggcups). If you don't set a job name, GTK picks a default one by numbering successive print jobs. The number of pages in the document. This must be set to a positive number before the rendering starts. It may be set in a [signal@Gtk.PrintOperation::begin-print] signal handler. Note that the page numbers passed to the [signal@Gtk.PrintOperation::request-page-setup] and [signal@Gtk.PrintOperation::draw-page] signals are 0-based, i.e. if the user chooses to print all pages, the last ::draw-page signal will be for page @n_pages - 1. The number of pages that will be printed. Note that this value is set during print preparation phase (%GTK_PRINT_STATUS_PREPARING), so this value should never be get before the data generation phase (%GTK_PRINT_STATUS_GENERATING_DATA). You can connect to the [signal@Gtk.PrintOperation::status-changed] signal and call [method@Gtk.PrintOperation.get_n_pages_to_print] when print status is %GTK_PRINT_STATUS_GENERATING_DATA. This is typically used to track the progress of print operation. The `GtkPrintSettings` used for initializing the dialog. Setting this property is typically used to re-establish print settings from a previous print operation, see [method@Gtk.PrintOperation.run]. Determines whether to show a progress dialog during the print operation. The status of the print operation. A string representation of the status of the print operation. The string is translated and suitable for displaying the print status e.g. in a `GtkStatusbar`. See the [property@Gtk.PrintOperation:status] property for a status value that is suitable for programmatic use. If %TRUE, the print operation will support print of selection. This allows the print dialog to show a "Selection" button. If %TRUE, the print operation will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like “out of paper” issues, and when the print job actually reaches the printer. However, this is often implemented using polling, and should not be enabled unless needed. The transformation for the cairo context obtained from `GtkPrintContext` is set up in such a way that distances are measured in units of @unit. If %TRUE, the transformation for the cairo context obtained from `GtkPrintContext` puts the origin at the top left corner of the page. This may not be the top left corner of the sheet, depending on page orientation and the number of pages per sheet. Otherwise, the origin is at the top left corner of the imageable area (i.e. inside the margins). Emitted after the user has finished changing print settings in the dialog, before the actual rendering starts. A typical use for ::begin-print is to use the parameters from the [class@Gtk.PrintContext] and paginate the document accordingly, and then set the number of pages with [method@Gtk.PrintOperation.set_n_pages]. the `GtkPrintContext` for the current operation Emitted when displaying the print dialog. If you return a widget in a handler for this signal it will be added to a custom tab in the print dialog. You typically return a container widget with multiple widgets in it. The print dialog owns the returned widget, and its lifetime is not controlled by the application. However, the widget is guaranteed to stay around until the [signal@Gtk.PrintOperation::custom-widget-apply] signal is emitted on the operation. Then you can read out any information you need from the widgets. A custom widget that gets embedded in the print dialog Emitted right before ::begin-print if you added a custom widget in the ::create-custom-widget handler. When you get this signal you should read the information from the custom widgets, as the widgets are not guaranteed to be around at a later time. the custom widget added in ::create-custom-widget Emitted when the print operation run has finished doing everything required for printing. @result gives you information about what happened during the run. If @result is %GTK_PRINT_OPERATION_RESULT_ERROR then you can call [method@Gtk.PrintOperation.get_error] for more information. If you enabled print status tracking then [method@Gtk.PrintOperation.is_finished] may still return %FALSE after the ::done signal was emitted. the result of the print operation Emitted for every page that is printed. The signal handler must render the @page_nr's page onto the cairo context obtained from @context using [method@Gtk.PrintContext.get_cairo_context]. ```c static void draw_page (GtkPrintOperation *operation, GtkPrintContext *context, int page_nr, gpointer user_data) { cairo_t *cr; PangoLayout *layout; double width, text_height; int layout_height; PangoFontDescription *desc; cr = gtk_print_context_get_cairo_context (context); width = gtk_print_context_get_width (context); cairo_rectangle (cr, 0, 0, width, HEADER_HEIGHT); cairo_set_source_rgb (cr, 0.8, 0.8, 0.8); cairo_fill (cr); layout = gtk_print_context_create_pango_layout (context); desc = pango_font_description_from_string ("sans 14"); pango_layout_set_font_description (layout, desc); pango_font_description_free (desc); pango_layout_set_text (layout, "some text", -1); pango_layout_set_width (layout, width * PANGO_SCALE); pango_layout_set_alignment (layout, PANGO_ALIGN_CENTER); pango_layout_get_size (layout, NULL, &layout_height); text_height = (double)layout_height / PANGO_SCALE; cairo_move_to (cr, width / 2, (HEADER_HEIGHT - text_height) / 2); pango_cairo_show_layout (cr, layout); g_object_unref (layout); } ``` Use [method@Gtk.PrintOperation.set_use_full_page] and [method@Gtk.PrintOperation.set_unit] before starting the print operation to set up the transformation of the cairo context according to your needs. the `GtkPrintContext` for the current operation the number of the currently printed page (0-based) Emitted after all pages have been rendered. A handler for this signal can clean up any resources that have been allocated in the [signal@Gtk.PrintOperation::begin-print] handler. the `GtkPrintContext` for the current operation Emitted after the ::begin-print signal, but before the actual rendering starts. It keeps getting emitted until a connected signal handler returns %TRUE. The ::paginate signal is intended to be used for paginating a document in small chunks, to avoid blocking the user interface for a long time. The signal handler should update the number of pages using [method@Gtk.PrintOperation.set_n_pages], and return %TRUE if the document has been completely paginated. If you don't need to do pagination in chunks, you can simply do it all in the ::begin-print handler, and set the number of pages from there. %TRUE if pagination is complete the `GtkPrintContext` for the current operation Gets emitted when a preview is requested from the native dialog. The default handler for this signal uses an external viewer application to preview. To implement a custom print preview, an application must return %TRUE from its handler for this signal. In order to use the provided @context for the preview implementation, it must be given a suitable cairo context with [method@Gtk.PrintContext.set_cairo_context]. The custom preview implementation can use [method@Gtk.PrintOperationPreview.is_selected] and [method@Gtk.PrintOperationPreview.render_page] to find pages which are selected for print and render them. The preview must be finished by calling [method@Gtk.PrintOperationPreview.end_preview] (typically in response to the user clicking a close button). %TRUE if the listener wants to take over control of the preview the `GtkPrintOperationPreview` for the current operation the `GtkPrintContext` that will be used the `GtkWindow` to use as window parent Emitted once for every page that is printed. This gives the application a chance to modify the page setup. Any changes done to @setup will be in force only for printing this page. the `GtkPrintContext` for the current operation the number of the currently printed page (0-based) the `GtkPageSetup` Emitted at between the various phases of the print operation. See [enum@Gtk.PrintStatus] for the phases that are being discriminated. Use [method@Gtk.PrintOperation.get_status] to find out the current status. Emitted after change of selected printer. The actual page setup and print settings are passed to the custom widget, which can actualize itself according to this change. the custom widget added in ::create-custom-widget actual page setup actual print settings Determines what action the print operation should perform. A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. Show the print dialog. Start to print without showing the print dialog, based on the current print settings, if possible. Depending on the platform, a print dialog might appear anyway. Show the print preview. Export to a file. This requires the export-filename property to be set. The parent class. Signal emitted when the print operation run has finished doing everything required for printing. Signal emitted after the user has finished changing print settings in the dialog, before the actual rendering starts. Signal emitted after the “begin-print” signal, but before the actual rendering starts. Emitted once for every page that is printed, to give the application a chance to modify the page setup. Signal emitted for every page that is printed. Signal emitted after all pages have been rendered. Emitted at between the various phases of the print operation. Signal emitted when displaying the print dialog. Signal emitted right before “begin-print” if you added a custom widget in the “create-custom-widget” handler. Signal emitted when a preview is requested from the native dialog. Emitted after change of selected printer. The interface that is used to implement print preview. A `GtkPrintOperationPreview` object is passed to the [signal@Gtk.PrintOperation::preview] signal by [class@Gtk.PrintOperation]. Ends a preview. This function must be called to finish a custom print preview. a `GtkPrintOperationPreview` Returns whether the given page is included in the set of pages that have been selected for printing. %TRUE if the page has been selected for printing a `GtkPrintOperationPreview` a page number Renders a page to the preview. This is using the print context that was passed to the [signal@Gtk.PrintOperation::preview] handler together with @preview. A custom print preview should use this function to render the currently selected page. Note that this function requires a suitable cairo context to be associated with the print context. a `GtkPrintOperationPreview` the page to render Ends a preview. This function must be called to finish a custom print preview. a `GtkPrintOperationPreview` Returns whether the given page is included in the set of pages that have been selected for printing. %TRUE if the page has been selected for printing a `GtkPrintOperationPreview` a page number Renders a page to the preview. This is using the print context that was passed to the [signal@Gtk.PrintOperation::preview] handler together with @preview. A custom print preview should use this function to render the currently selected page. Note that this function requires a suitable cairo context to be associated with the print context. a `GtkPrintOperationPreview` the page to render Emitted once for each page that gets rendered to the preview. A handler for this signal should update the @context according to @page_setup and set up a suitable cairo context, using [method@Gtk.PrintContext.set_cairo_context]. the current `GtkPrintContext` the `GtkPageSetup` for the current page The ::ready signal gets emitted once per preview operation, before the first page is rendered. A handler for this signal can be used for setup tasks. the current `GtkPrintContext` a `GtkPrintOperationPreview` the page to render %TRUE if the page has been selected for printing a `GtkPrintOperationPreview` a page number a `GtkPrintOperationPreview` The result of a print operation. A value of this type is returned by [method@Gtk.PrintOperation.run]. An error has occurred. The print settings should be stored. The print operation has been canceled, the print settings should not be stored. The print operation is not complete yet. This value will only be returned when running asynchronously. See also gtk_print_job_set_pages() All pages. Current page. Range of pages. Selected pages. See also gtk_print_settings_set_quality(). Low quality. Normal quality. High quality. Draft quality. Collects the settings of a print dialog in a system-independent way. The main use for this object is that once you’ve printed you can get a settings object that represents the settings the user chose, and the next time you print you can pass that object in so that the user doesn’t have to re-set all his settings. Its also possible to enumerate the settings so that you can easily save the settings for the next time your app runs, or even store them in a document. The predefined keys try to use shared values as much as possible so that moving such a document between systems still works. Creates a new `GtkPrintSettings` object. a new `GtkPrintSettings` object Reads the print settings from @file_name. Returns a new `GtkPrintSettings` object with the restored settings, or %NULL if an error occurred. If the file could not be loaded then error is set to either a `GFileError` or `GKeyFileError`. See [method@Gtk.PrintSettings.to_file]. the restored `GtkPrintSettings` the filename to read the settings from Deserialize print settings from an a{sv} variant. The variant must be in the format produced by [method@Gtk.PrintSettings.to_gvariant]. a new `GtkPrintSettings` object an a{sv} `GVariant` Reads the print settings from the group @group_name in @key_file. Returns a new `GtkPrintSettings` object with the restored settings, or %NULL if an error occurred. If the file could not be loaded then error is set to either `GFileError` or `GKeyFileError`. the restored `GtkPrintSettings` the `GKeyFile` to retrieve the settings from the name of the group to use, or %NULL to use the default “Print Settings” Copies a `GtkPrintSettings` object. a newly allocated copy of @other a `GtkPrintSettings` Calls @func for each key-value pair of @settings. a `GtkPrintSettings` the function to call user data for @func Looks up the string value associated with @key. the string value for @key a `GtkPrintSettings` a key Returns the boolean represented by the value that is associated with @key. The string “true” represents %TRUE, any other string %FALSE. %TRUE, if @key maps to a true value. a `GtkPrintSettings` a key Gets the value of %GTK_PRINT_SETTINGS_COLLATE. whether to collate the printed pages a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE. the default source a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_DITHER. the dithering that is used a `GtkPrintSettings` Returns the double value associated with @key, or 0. the double value of @key a `GtkPrintSettings` a key Returns the floating point number represented by the value that is associated with @key, or @default_val if the value does not represent a floating point number. Floating point numbers are parsed with g_ascii_strtod(). the floating point number associated with @key a `GtkPrintSettings` a key the default value Gets the value of %GTK_PRINT_SETTINGS_DUPLEX. whether to print the output in duplex. a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_FINISHINGS. the finishings a `GtkPrintSettings` Returns the integer value of @key, or 0. the integer value of @key a `GtkPrintSettings` a key Returns the value of @key, interpreted as an integer, or the default value. the integer value of @key a `GtkPrintSettings` a key the default value Returns the value associated with @key, interpreted as a length. The returned value is converted to @units. the length value of @key, converted to @unit a `GtkPrintSettings` a key the unit of the return value Gets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE. The set of media types is defined in PWG 5101.1-2002 PWG. the media type a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_N_COPIES. the number of copies to print a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP. the number of pages per sheet a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT. layout of page in number-up mode a `GtkPrintSettings` Get the value of %GTK_PRINT_SETTINGS_ORIENTATION, converted to a `GtkPageOrientation`. the orientation a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN. the output bin a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES. an array of `GtkPageRange`s. Use g_free() to free the array when it is no longer needed. a `GtkPrintSettings` return location for the length of the returned array Gets the value of %GTK_PRINT_SETTINGS_PAGE_SET. the set of pages to print a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT, converted to @unit. the paper height, in units of @unit a `GtkPrintSettings` the unit for the return value Gets the value of %GTK_PRINT_SETTINGS_PAPER_FORMAT, converted to a `GtkPaperSize`. the paper size a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH, converted to @unit. the paper width, in units of @unit a `GtkPrintSettings` the unit for the return value Gets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES. which pages to print a `GtkPrintSettings` Convenience function to obtain the value of %GTK_PRINT_SETTINGS_PRINTER. the printer name a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI. the resolution in lpi (lines per inch) a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_QUALITY. the print quality a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION. the resolution in dpi a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_X. the horizontal resolution in dpi a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_Y. the vertical resolution in dpi a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_REVERSE. whether to reverse the order of the printed pages a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_SCALE. the scale in percent a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_USE_COLOR. whether to use color a `GtkPrintSettings` Returns %TRUE, if a value is associated with @key. %TRUE, if @key has a value a `GtkPrintSettings` a key Reads the print settings from @file_name. If the file could not be loaded then error is set to either a `GFileError` or `GKeyFileError`. See [method@Gtk.PrintSettings.to_file]. %TRUE on success a `GtkPrintSettings` the filename to read the settings from Reads the print settings from the group @group_name in @key_file. If the file could not be loaded then error is set to either a `GFileError` or `GKeyFileError`. %TRUE on success a `GtkPrintSettings` the `GKeyFile` to retrieve the settings from the name of the group to use, or %NULL to use the default “Print Settings” Associates @value with @key. a `GtkPrintSettings` a key a string value Sets @key to a boolean value. a `GtkPrintSettings` a key a boolean Sets the value of %GTK_PRINT_SETTINGS_COLLATE. a `GtkPrintSettings` whether to collate the output Sets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE. a `GtkPrintSettings` the default source Sets the value of %GTK_PRINT_SETTINGS_DITHER. a `GtkPrintSettings` the dithering that is used Sets @key to a double value. a `GtkPrintSettings` a key a double value Sets the value of %GTK_PRINT_SETTINGS_DUPLEX. a `GtkPrintSettings` a `GtkPrintDuplex` value Sets the value of %GTK_PRINT_SETTINGS_FINISHINGS. a `GtkPrintSettings` the finishings Sets @key to an integer value. a `GtkPrintSettings` a key an integer Associates a length in units of @unit with @key. a `GtkPrintSettings` a key a length the unit of @length Sets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE. The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` the media type Sets the value of %GTK_PRINT_SETTINGS_N_COPIES. a `GtkPrintSettings` the number of copies Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP. a `GtkPrintSettings` the number of pages per sheet Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT. a `GtkPrintSettings` a `GtkNumberUpLayout` value Sets the value of %GTK_PRINT_SETTINGS_ORIENTATION. a `GtkPrintSettings` a page orientation Sets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN. a `GtkPrintSettings` the output bin Sets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES. a `GtkPrintSettings` an array of `GtkPageRange`s the length of @page_ranges Sets the value of %GTK_PRINT_SETTINGS_PAGE_SET. a `GtkPrintSettings` a `GtkPageSet` value Sets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT. a `GtkPrintSettings` the paper height the units of @height Sets the value of %GTK_PRINT_SETTINGS_PAPER_FORMAT, %GTK_PRINT_SETTINGS_PAPER_WIDTH and %GTK_PRINT_SETTINGS_PAPER_HEIGHT. a `GtkPrintSettings` a paper size Sets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH. a `GtkPrintSettings` the paper width the units of @width Sets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES. a `GtkPrintSettings` a `GtkPrintPages` value Convenience function to set %GTK_PRINT_SETTINGS_PRINTER to @printer. a `GtkPrintSettings` the printer name Sets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI. a `GtkPrintSettings` the resolution in lpi (lines per inch) Sets the value of %GTK_PRINT_SETTINGS_QUALITY. a `GtkPrintSettings` a `GtkPrintQuality` value Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION, %GTK_PRINT_SETTINGS_RESOLUTION_X and %GTK_PRINT_SETTINGS_RESOLUTION_Y. a `GtkPrintSettings` the resolution in dpi Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION, %GTK_PRINT_SETTINGS_RESOLUTION_X and %GTK_PRINT_SETTINGS_RESOLUTION_Y. a `GtkPrintSettings` the horizontal resolution in dpi the vertical resolution in dpi Sets the value of %GTK_PRINT_SETTINGS_REVERSE. a `GtkPrintSettings` whether to reverse the output Sets the value of %GTK_PRINT_SETTINGS_SCALE. a `GtkPrintSettings` the scale in percent Sets the value of %GTK_PRINT_SETTINGS_USE_COLOR. a `GtkPrintSettings` whether to use color This function saves the print settings from @settings to @file_name. If the file could not be written then error is set to either a `GFileError` or `GKeyFileError`. %TRUE on success a `GtkPrintSettings` the file to save to Serialize print settings to an a{sv} variant. a new, floating, `GVariant` a `GtkPrintSettings` This function adds the print settings from @settings to @key_file. a `GtkPrintSettings` the `GKeyFile` to save the print settings to the group to add the settings to in @key_file, or %NULL to use the default “Print Settings” Removes any value associated with @key. This has the same effect as setting the value to %NULL. a `GtkPrintSettings` a key Function called by [method@Gtk.PrintSettings.foreach] on every key/value pair inside a [class@Gtk.PrintSettings]. the setting key the setting value The user data provided with the function An auxiliary object for printing that allows decoupling the setup from the printing. A print setup is obtained by calling [method@Gtk.PrintDialog.setup], and can later be passed to print functions such as [method@Gtk.PrintDialog.print]. Print setups can be reused for multiple print calls. Applications may wish to store the page_setup and print_settings from the print setup and copy them to the PrintDialog if they want to keep using them. Returns the page setup of @setup. It may be different from the `GtkPrintDialog`'s page setup if the user changed it during the setup process. the page setup, or `NULL` a `GtkPrintSetup` Returns the print settings of @setup. They may be different from the `GtkPrintDialog`'s settings if the user changed them during the setup process. the print settings, or `NULL` a `GtkPrintSetup` Increase the reference count of @setup. the print setup a `GtkPrintSetup` Decrease the reference count of @setup. If the reference count reaches zero, the object is freed. a `GtkPrintSetup` The status gives a rough indication of the completion of a running print operation. The printing has not started yet; this status is set initially, and while the print dialog is shown. This status is set while the begin-print signal is emitted and during pagination. This status is set while the pages are being rendered. The print job is being sent off to the printer. The print job has been sent to the printer, but is not printed for some reason, e.g. the printer may be stopped. Some problem has occurred during printing, e.g. a paper jam. The printer is processing the print job. The printing has been completed successfully. The printing has been aborted. A print dialog for platforms which don’t provide a native print dialog, like Unix. <picture> <source srcset="printdialog-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkPrintUnixDialog" src="printdialog.png"> </picture> It can be used very much like any other GTK dialog, at the cost of the portability offered by the high-level printing API with [class@Gtk.PrintOperation]. In order to print something with `GtkPrintUnixDialog`, you need to use [method@Gtk.PrintUnixDialog.get_selected_printer] to obtain a [class@Gtk.Printer] object and use it to construct a [class@Gtk.PrintJob] using [ctor@Gtk.PrintJob.new]. `GtkPrintUnixDialog` uses the following response values: - %GTK_RESPONSE_OK: for the “Print” button - %GTK_RESPONSE_APPLY: for the “Preview” button - %GTK_RESPONSE_CANCEL: for the “Cancel” button # GtkPrintUnixDialog as GtkBuildable The `GtkPrintUnixDialog` implementation of the `GtkBuildable` interface exposes its @notebook internal children with the name “notebook”. An example of a `GtkPrintUnixDialog` UI definition fragment: ```xml <object class="GtkPrintUnixDialog" id="dialog1"> <child internal-child="notebook"> <object class="GtkNotebook" id="notebook"> <child> <object type="GtkNotebookPage"> <property name="tab_expand">False</property> <property name="tab_fill">False</property> <property name="tab"> <object class="GtkLabel" id="tablabel"> <property name="label">Tab label</property> </object> </property> <property name="child"> <object class="GtkLabel" id="tabcontent"> <property name="label">Content on notebook tab</property> </object> </property> </object> </child> </object> </child> </object> ``` # CSS nodes `GtkPrintUnixDialog` has a single CSS node with name window. The style classes dialog and print are added. Creates a new `GtkPrintUnixDialog`. a new `GtkPrintUnixDialog` Title of the dialog Transient parent of the dialog Adds a custom tab to the print dialog. a `GtkPrintUnixDialog` the widget to put in the custom tab the widget to use as tab label Gets the current page of the `GtkPrintUnixDialog`. the current page of @dialog a `GtkPrintUnixDialog` Gets whether to embed the page setup. whether to embed the page setup a `GtkPrintUnixDialog` Gets whether there is a selection. whether there is a selection a `GtkPrintUnixDialog` Gets the capabilities that have been set on this `GtkPrintUnixDialog`. the printing capabilities a `GtkPrintUnixDialog` Gets the page setup that is used by the `GtkPrintUnixDialog`. the page setup of @dialog. a `GtkPrintUnixDialog` Gets whether a page setup was set by the user. whether a page setup was set by user. a `GtkPrintUnixDialog` Gets the currently selected printer. the currently selected printer a `GtkPrintUnixDialog` Gets a new `GtkPrintSettings` object that represents the current values in the print dialog. Note that this creates a new object, and you need to unref it if don’t want to keep it. a new `GtkPrintSettings` object with the values from @dialog a `GtkPrintUnixDialog` Gets whether the print dialog allows user to print a selection. whether the application supports print of selection a `GtkPrintUnixDialog` Sets the current page number. If @current_page is not -1, this enables the current page choice for the range of pages to print. a `GtkPrintUnixDialog` the current page number. Embed page size combo box and orientation combo box into page setup page. a `GtkPrintUnixDialog` embed page setup selection Sets whether a selection exists. a `GtkPrintUnixDialog` %TRUE indicates that a selection exists This lets you specify the printing capabilities your application supports. For instance, if you can handle scaling the output then you pass %GTK_PRINT_CAPABILITY_SCALE. If you don’t pass that, then the dialog will only let you select the scale if the printing system automatically handles scaling. a `GtkPrintUnixDialog` the printing capabilities of your application Sets the page setup of the `GtkPrintUnixDialog`. a `GtkPrintUnixDialog` a `GtkPageSetup` Sets the `GtkPrintSettings` for the `GtkPrintUnixDialog`. Typically, this is used to restore saved print settings from a previous print operation before the print dialog is shown. a `GtkPrintUnixDialog` a `GtkPrintSettings` Sets whether the print dialog allows user to print a selection. a `GtkPrintUnixDialog` %TRUE to allow print selection The current page in the document. %TRUE if the page setup controls are embedded. Whether the application has a selection. Capabilities the application can handle. The `GtkPageSetup` object to use. The `GtkPrintSettings` object used for this dialog. The `GtkPrinter` which is selected. Whether the dialog supports selection. Represents a printer. You only need to deal directly with printers if you use the non-portable [class@Gtk.PrintUnixDialog] API. A `GtkPrinter` allows to get status information about the printer, such as its description, its location, the number of queued jobs, etc. Most importantly, a `GtkPrinter` object can be used to create a [class@Gtk.PrintJob] object, which lets you print to the printer. Creates a new `GtkPrinter`. a new `GtkPrinter` the name of the printer a `GtkPrintBackend` whether the printer is virtual Returns whether the printer accepts input in PDF format. %TRUE if @printer accepts PDF a `GtkPrinter` Returns whether the printer accepts input in PostScript format. %TRUE if @printer accepts PostScript a `GtkPrinter` Compares two printers. 0 if the printer match, a negative value if @a < @b, or a positive value if @a > @b a `GtkPrinter` another `GtkPrinter` Returns the backend of the printer. the backend of @printer a `GtkPrinter` Returns the printer’s capabilities. This is useful when you’re using `GtkPrintUnixDialog`’s manual-capabilities setting and need to know which settings the printer can handle and which you must handle yourself. This will return 0 unless the printer’s details are available, see [method@Gtk.Printer.has_details] and [method@Gtk.Printer.request_details]. the printer’s capabilities a `GtkPrinter` Returns default page size of @printer. a newly allocated `GtkPageSetup` with default page size of the printer. a `GtkPrinter` Gets the description of the printer. the description of @printer a `GtkPrinter` Retrieve the hard margins of @printer. These are the margins that define the area at the borders of the paper that the printer cannot print to. Note: This will not succeed unless the printer’s details are available, see [method@Gtk.Printer.has_details] and [method@Gtk.Printer.request_details]. %TRUE iff the hard margins were retrieved a `GtkPrinter` a location to store the top margin in a location to store the bottom margin in a location to store the left margin in a location to store the right margin in Retrieve the hard margins of @printer for @paper_size. These are the margins that define the area at the borders of the paper that the printer cannot print to. Note: This will not succeed unless the printer’s details are available, see [method@Gtk.Printer.has_details] and [method@Gtk.Printer.request_details]. %TRUE iff the hard margins were retrieved a `GtkPrinter` a `GtkPaperSize` a location to store the top margin in a location to store the bottom margin in a location to store the left margin in a location to store the right margin in Gets the name of the icon to use for the printer. the icon name for @printer a `GtkPrinter` Gets the number of jobs currently queued on the printer. the number of jobs on @printer a `GtkPrinter` Returns a description of the location of the printer. the location of @printer a `GtkPrinter` Returns the name of the printer. the name of @printer a `GtkPrinter` Returns the state message describing the current state of the printer. the state message of @printer a `GtkPrinter` Returns whether the printer details are available. %TRUE if @printer details are available a `GtkPrinter` Returns whether the printer is accepting jobs %TRUE if @printer is accepting jobs a `GtkPrinter` Returns whether the printer is currently active (i.e. accepts new jobs). %TRUE if @printer is active a `GtkPrinter` Returns whether the printer is the default printer. %TRUE if @printer is the default a `GtkPrinter` Returns whether the printer is currently paused. A paused printer still accepts jobs, but it is not printing them. %TRUE if @printer is paused a `GtkPrinter` Returns whether the printer is virtual (i.e. does not represent actual printer hardware, but something like a CUPS class). %TRUE if @printer is virtual a `GtkPrinter` Lists all the paper sizes @printer supports. This will return and empty list unless the printer’s details are available, see [method@Gtk.Printer.has_details] and [method@Gtk.Printer.request_details]. a newly allocated list of newly allocated `GtkPageSetup`s. a `GtkPrinter` Requests the printer details. When the details are available, the [signal@Gtk.Printer::details-acquired] signal will be emitted on @printer. a `GtkPrinter` %TRUE if the printer is accepting jobs. %TRUE if this printer can accept PDF. %TRUE if this printer can accept PostScript. The backend for the printer. Icon name to use for the printer. %FALSE if this represents a real hardware device. Number of jobs queued in the printer. Information about the location of the printer. The name of the printer. %TRUE if this printer is paused. A paused printer still accepts jobs, but it does not print them. String giving the current status of the printer. Emitted in response to a request for detailed information about a printer from the print backend. The @success parameter indicates if the information was actually obtained. %TRUE if the details were successfully acquired The type of function passed to gtk_enumerate_printers(). Note that you need to ref @printer, if you want to keep a reference to it after the function has returned. %TRUE to stop the enumeration, %FALSE to continue a `GtkPrinter` user data passed to gtk_enumerate_printers() Displays the progress of a long-running operation. `GtkProgressBar` provides a visual clue that processing is underway. It can be used in two different modes: percentage mode and activity mode. <picture> <source srcset="progressbar-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkProgressBar" src="progressbar.png"> </picture> When an application can determine how much work needs to take place (e.g. read a fixed number of bytes from a file) and can monitor its progress, it can use the `GtkProgressBar` in percentage mode and the user sees a growing bar indicating the percentage of the work that has been completed. In this mode, the application is required to call [method@Gtk.ProgressBar.set_fraction] periodically to update the progress bar. When an application has no accurate way of knowing the amount of work to do, it can use the `GtkProgressBar` in activity mode, which shows activity by a block moving back and forth within the progress area. In this mode, the application is required to call [method@Gtk.ProgressBar.pulse] periodically to update the progress bar. There is quite a bit of flexibility provided to control the appearance of the `GtkProgressBar`. Functions are provided to control the orientation of the bar, optional text can be displayed along with the bar, and the step size used in activity mode can be set. # CSS nodes ``` progressbar[.osd] ├── [text] ╰── trough[.empty][.full] ╰── progress[.pulse] ``` `GtkProgressBar` has a main CSS node with name progressbar and subnodes with names text and trough, of which the latter has a subnode named progress. The text subnode is only present if text is shown. The progress subnode has the style class .pulse when in activity mode. It gets the style classes .left, .right, .top or .bottom added when the progress 'touches' the corresponding end of the GtkProgressBar. The .osd class on the progressbar node is for use in overlays like the one Epiphany has for page loading progress. # Accessibility `GtkProgressBar` uses the [enum@Gtk.AccessibleRole.progress_bar] role and sets the [enum@Gtk.AccessibleProperty.value_min], [enum@Gtk.AccessibleProperty.value_max] and [enum@Gtk.AccessibleProperty.value_now] properties to reflect the progress. Creates a new `GtkProgressBar`. a `GtkProgressBar`. Returns the ellipsizing position of the progress bar. See [method@Gtk.ProgressBar.set_ellipsize]. `PangoEllipsizeMode` a `GtkProgressBar` Returns the current fraction of the task that’s been completed. a fraction from 0.0 to 1.0 a `GtkProgressBar` Returns whether the progress bar is inverted. %TRUE if the progress bar is inverted a `GtkProgressBar` Retrieves the pulse step. See [method@Gtk.ProgressBar.set_pulse_step]. a fraction from 0.0 to 1.0 a `GtkProgressBar` Returns whether the `GtkProgressBar` shows text. See [method@Gtk.ProgressBar.set_show_text]. %TRUE if text is shown in the progress bar a `GtkProgressBar` Retrieves the text that is displayed with the progress bar. The return value is a reference to the text, not a copy of it, so will become invalid if you change the text in the progress bar. the text a `GtkProgressBar` Indicates that some progress has been made, but you don’t know how much. Causes the progress bar to enter “activity mode,” where a block bounces back and forth. Each call to [method@Gtk.ProgressBar.pulse] causes the block to move by a little bit (the amount of movement per pulse is determined by [method@Gtk.ProgressBar.set_pulse_step]). a `GtkProgressBar` Sets the mode used to ellipsize the text. The text is ellipsized if there is not enough space to render the entire string. a `GtkProgressBar` a `PangoEllipsizeMode` Causes the progress bar to “fill in” the given fraction of the bar. The fraction should be between 0.0 and 1.0, inclusive. a `GtkProgressBar` fraction of the task that’s been completed Sets whether the progress bar is inverted. Progress bars normally grow from top to bottom or left to right. Inverted progress bars grow in the opposite direction. a `GtkProgressBar` %TRUE to invert the progress bar Sets the fraction of total progress bar length to move the bouncing block. The bouncing block is moved when [method@Gtk.ProgressBar.pulse] is called. a `GtkProgressBar` fraction between 0.0 and 1.0 Sets whether the progress bar will show text next to the bar. The shown text is either the value of the [property@Gtk.ProgressBar:text] property or, if that is %NULL, the [property@Gtk.ProgressBar:fraction] value, as a percentage. To make a progress bar that is styled and sized suitably for containing text (even if the actual text is blank), set [property@Gtk.ProgressBar:show-text] to %TRUE and [property@Gtk.ProgressBar:text] to the empty string (not %NULL). a `GtkProgressBar` whether to show text Causes the given @text to appear next to the progress bar. If @text is %NULL and [property@Gtk.ProgressBar:show-text] is %TRUE, the current value of [property@Gtk.ProgressBar:fraction] will be displayed as a percentage. If @text is non-%NULL and [property@Gtk.ProgressBar:show-text] is %TRUE, the text will be displayed. In this case, it will not display the progress percentage. If @text is the empty string, the progress bar will still be styled and sized suitably for containing text, as long as [property@Gtk.ProgressBar:show-text] is %TRUE. a `GtkProgressBar` a UTF-8 string The preferred place to ellipsize the string. The text will be ellipsized if the progress bar does not have enough room to display the entire string, specified as a `PangoEllipsizeMode`. Note that setting this property to a value other than %PANGO_ELLIPSIZE_NONE has the side-effect that the progress bar requests only enough space to display the ellipsis ("..."). Another means to set a progress bar's width is [method@Gtk.Widget.set_size_request]. The fraction of total work that has been completed. Invert the direction in which the progress bar grows. The fraction of total progress to move the bounding block when pulsed. Sets whether the progress bar will show a text in addition to the bar itself. The shown text is either the value of the [property@Gtk.ProgressBar:text] property or, if that is %NULL, the [property@Gtk.ProgressBar:fraction] value, as a percentage. To make a progress bar that is styled and sized suitably for showing text (even if the actual text is blank), set [property@Gtk.ProgressBar:show-text] to %TRUE and [property@Gtk.ProgressBar:text] to the empty string (not %NULL). Text to be displayed in the progress bar. Describes limits of a [class@EventController] for handling events targeting other widgets. Events are handled regardless of what their target is. Events are only handled if their target is in the same [iface@Native] (or widget with [property@Gtk.Widget:limit-events] set) as the event controllers widget. Note that some event types have two targets (origin and destination). Describes the stage at which events are fed into a [class@EventController]. Events are not delivered. Events are delivered in the capture phase. The capture phase happens before the bubble phase, runs from the toplevel down to the event widget. This option should only be used on containers that might possibly handle events before their children do. Events are delivered in the bubble phase. The bubble phase happens after the capture phase, and before the default handlers are run. This phase runs from the event widget, up to the toplevel. Events are delivered in the default widget event handlers, note that widget implementations must chain up on button, motion, touch and grab broken handlers for controllers in this phase to be run. A `GObject` property value in a `GtkExpression`. Creates an expression that looks up a property. The object to use is found by evaluating the `expression`, or using the `this` argument when `expression` is `NULL`. If the resulting object conforms to `this_type`, its property named `property_name` will be queried. Otherwise, this expression's evaluation will fail. The given `this_type` must have a property with `property_name`. a new `GtkExpression` The type to expect for the this type Expression to evaluate to get the object to query or `NULL` to query the `this` object name of the property Creates an expression that looks up a property. The object to use is found by evaluating the `expression`, or using the `this` argument when `expression` is `NULL`. If the resulting object conforms to `this_type`, its property specified by `pspec` will be queried. Otherwise, this expression's evaluation will fail. a new `GtkExpression` Expression to evaluate to get the object to query or `NULL` to query the `this` object the `GParamSpec` for the property to query Gets the expression specifying the object of a property expression. the object expression a property `GtkExpression` Gets the `GParamSpec` specifying the property of a property expression. the `GParamSpec` for the property a property `GtkExpression` Base class for widgets which visualize an adjustment. Widgets that are derived from `GtkRange` include [class@Gtk.Scale] and [class@Gtk.Scrollbar]. Apart from signals for monitoring the parameters of the adjustment, `GtkRange` provides properties and methods for setting a “fill level” on range widgets. See [method@Gtk.Range.set_fill_level]. # Shortcuts and Gestures The `GtkRange` slider is draggable. Holding the <kbd>Shift</kbd> key while dragging, or initiating the drag with a long-press will enable the fine-tuning mode. Get the adjustment which is the “model” object for `GtkRange`. a `GtkAdjustment` a `GtkRange` Gets the current position of the fill level indicator. The current fill level A `GtkRange` Gets whether the `GtkRange` respects text direction. See [method@Gtk.Range.set_flippable]. %TRUE if the range is flippable a `GtkRange` Gets whether the range is inverted. See [method@Gtk.Range.set_inverted]. %TRUE if the range is inverted a `GtkRange` This function returns the area that contains the range’s trough, in coordinates relative to @range's origin. This function is useful mainly for `GtkRange` subclasses. a `GtkRange` return location for the range rectangle Gets whether the range is restricted to the fill level. %TRUE if @range is restricted to the fill level. A `GtkRange` Gets the number of digits to round the value to when it changes. See [signal@Gtk.Range::change-value]. the number of digits to round to a `GtkRange` Gets whether the range displays the fill level graphically. %TRUE if @range shows the fill level. A `GtkRange` This function returns sliders range along the long dimension, in widget->window coordinates. This function is useful mainly for `GtkRange` subclasses. a `GtkRange` return location for the slider's start return location for the slider's end This function is useful mainly for `GtkRange` subclasses. See [method@Gtk.Range.set_slider_size_fixed]. whether the range’s slider has a fixed size. a `GtkRange` Gets the current value of the range. current value of the range. a `GtkRange` Sets the adjustment to be used as the “model” object for the `GtkRange` The adjustment indicates the current range value, the minimum and maximum range values, the step/page increments used for keybindings and scrolling, and the page size. The page size is normally 0 for `GtkScale` and nonzero for `GtkScrollbar`, and indicates the size of the visible area of the widget being scrolled. The page size affects the size of the scrollbar slider. a `GtkRange` a `GtkAdjustment` Set the new position of the fill level indicator. The “fill level” is probably best described by its most prominent use case, which is an indicator for the amount of pre-buffering in a streaming media player. In that use case, the value of the range would indicate the current play position, and the fill level would be the position up to which the file/stream has been downloaded. This amount of prebuffering can be displayed on the range’s trough and is themeable separately from the trough. To enable fill level display, use [method@Gtk.Range.set_show_fill_level]. The range defaults to not showing the fill level. Additionally, it’s possible to restrict the range’s slider position to values which are smaller than the fill level. This is controlled by [method@Gtk.Range.set_restrict_to_fill_level] and is by default enabled. a `GtkRange` the new position of the fill level indicator Sets whether the `GtkRange` respects text direction. If a range is flippable, it will switch its direction if it is horizontal and its direction is %GTK_TEXT_DIR_RTL. See [method@Gtk.Widget.get_direction]. a `GtkRange` %TRUE to make the range flippable Sets the step and page sizes for the range. The step size is used when the user clicks the `GtkScrollbar` arrows or moves a `GtkScale` via arrow keys. The page size is used for example when moving via Page Up or Page Down keys. a `GtkRange` step size page size Sets whether to invert the range. Ranges normally move from lower to higher values as the slider moves from top to bottom or left to right. Inverted ranges have higher values at the top or on the right rather than on the bottom or left. a `GtkRange` %TRUE to invert the range Sets the allowable values in the `GtkRange`. The range value is clamped to be between @min and @max. (If the range has a non-zero page size, it is clamped between @min and @max - page-size.) a `GtkRange` minimum range value maximum range value Sets whether the slider is restricted to the fill level. See [method@Gtk.Range.set_fill_level] for a general description of the fill level concept. A `GtkRange` Whether the fill level restricts slider movement. Sets the number of digits to round the value to when it changes. See [signal@Gtk.Range::change-value]. a `GtkRange` the precision in digits, or -1 Sets whether a graphical fill level is show on the trough. See [method@Gtk.Range.set_fill_level] for a general description of the fill level concept. A `GtkRange` Whether a fill level indicator graphics is shown. Sets whether the range’s slider has a fixed size, or a size that depends on its adjustment’s page size. This function is useful mainly for `GtkRange` subclasses. a `GtkRange` %TRUE to make the slider size constant Sets the current value of the range. If the value is outside the minimum or maximum range values, it will be clamped to fit inside them. The range emits the [signal@Gtk.Range::value-changed] signal if the value changes. a `GtkRange` new value of the range The adjustment that is controlled by the range. The fill level (e.g. prebuffering of a network stream). If %TRUE, the direction in which the slider moves is inverted. Controls whether slider movement is restricted to an upper boundary set by the fill level. The number of digits to round the value to when it changes. See [signal@Gtk.Range::change-value]. Controls whether fill level indicator graphics are displayed on the trough. Emitted before clamping a value, to give the application a chance to adjust the bounds. the value before we clamp Emitted when a scroll action is performed on a range. It allows an application to determine the type of scroll event that occurred and the resultant new value. The application can handle the event itself and return %TRUE to prevent further processing. Or, by returning %FALSE, it can pass the event to other handlers until the default GTK handler is reached. The value parameter is unrounded. An application that overrides the ::change-value signal is responsible for clamping the value to the desired number of decimal digits; the default GTK handler clamps the value based on [property@Gtk.Range:round-digits]. %TRUE to prevent other handlers from being invoked for the signal, %FALSE to propagate the signal further the type of scroll action that was performed the new value resulting from the scroll action Virtual function that moves the slider. Used for keybindings. how to move the slider Emitted when the range value changes. Meta-data to be passed to gtk_recent_manager_add_full() when registering a recently used resource. a UTF-8 encoded string, containing the name of the recently used resource to be displayed, or %NULL; a UTF-8 encoded string, containing a short description of the resource, or %NULL; the MIME type of the resource; the name of the application that is registering this recently used resource; command line used to launch this resource; may contain the “\%f” and “\%u” escape characters which will be expanded to the resource file path and URI respectively when the command line is retrieved; a vector of strings containing groups names; whether this resource should be displayed only by the applications that have registered it or not. Contains the metadata associated with an item in the recently used files list. Creates a `GAppInfo` for the specified `GtkRecentInfo` In case of error, @error will be set either with a %GTK_RECENT_MANAGER_ERROR or a %G_IO_ERROR the newly created `GAppInfo` a `GtkRecentInfo` the name of the application that should be mapped to a `GAppInfo`; if %NULL is used then the default application for the MIME type is used Checks whether the resource pointed by @info still exists. At the moment this check is done only on resources pointing to local files. %TRUE if the resource exists a `GtkRecentInfo` Gets the time when the resource was added to the recently used resources list. a `GDateTime` for the time when the resource was added a `GtkRecentInfo` Gets the number of days elapsed since the last update of the resource pointed by @info. a positive integer containing the number of days elapsed since the time this resource was last modified a `GtkRecentInfo` Gets the data regarding the application that has registered the resource pointed by @info. If the command line contains any escape characters defined inside the storage specification, they will be expanded. %TRUE if an application with @app_name has registered this resource inside the recently used list, or %FALSE otherwise. The @app_exec string is owned by the `GtkRecentInfo` and should not be modified or freed a `GtkRecentInfo` the name of the application that has registered this item return location for the string containing the command line return location for the number of times this item was registered return location for the time this item was last registered for this application Retrieves the list of applications that have registered this resource. a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. a `GtkRecentInfo` return location for the length of the returned list Gets the (short) description of the resource. the description of the resource. The returned string is owned by the recent manager, and should not be freed. a `GtkRecentInfo` Gets the name of the resource. If none has been defined, the basename of the resource is obtained. the display name of the resource. The returned string is owned by the recent manager, and should not be freed. a `GtkRecentInfo` Retrieves the icon associated to the resource MIME type. a `GIcon` containing the icon a `GtkRecentInfo` Returns all groups registered for the recently used item @info. The array of returned group names will be %NULL terminated, so length might optionally be %NULL. a newly allocated %NULL terminated array of strings. Use g_strfreev() to free it. a `GtkRecentInfo` return location for the number of groups returned Gets the MIME type of the resource. the MIME type of the resource. The returned string is owned by the recent manager, and should not be freed. a `GtkRecentInfo` Gets the time when the meta-data for the resource was last modified. a `GDateTime` for the time when the resource was last modified a `GtkRecentInfo` Gets the value of the “private” flag. Resources in the recently used list that have this flag set to %TRUE should only be displayed by the applications that have registered them. %TRUE if the private flag was found, %FALSE otherwise a `GtkRecentInfo` Computes a valid UTF-8 string that can be used as the name of the item in a menu or list. For example, calling this function on an item that refers to “file:///foo/bar.txt” will yield “bar.txt”. A newly-allocated string in UTF-8 encoding free it with g_free() an `GtkRecentInfo` Gets the URI of the resource. the URI of the resource. The returned string is owned by the recent manager, and should not be freed. a `tkRecentInfo` Gets a displayable version of the resource’s URI. If the resource is local, it returns a local path; if the resource is not local, it returns the UTF-8 encoded content of [method@Gtk.RecentInfo.get_uri]. a newly allocated UTF-8 string containing the resource’s URI or %NULL. Use g_free() when done using it. a `GtkRecentInfo` Gets the time when the meta-data for the resource was last visited. a `GDateTime` for the time when the resource was last visited a `GtkRecentInfo` Checks whether an application registered this resource using @app_name. %TRUE if an application with name @app_name was found, %FALSE otherwise a `GtkRecentInfo` a string containing an application name Checks whether @group_name appears inside the groups registered for the recently used item @info. %TRUE if the group was found a `GtkRecentInfo` name of a group Checks whether the resource is local or not by looking at the scheme of its URI. %TRUE if the resource is local a `GtkRecentInfo` Gets the name of the last application that have registered the recently used resource represented by @info. an application name. Use g_free() to free it. a `GtkRecentInfo` Checks whether two `GtkRecentInfo` point to the same resource. %TRUE if both `GtkRecentInfo` point to the same resource, %FALSE otherwise a `GtkRecentInfo` a `GtkRecentInfo` Increases the reference count of @recent_info by one. the recent info object with its reference count increased by one a `GtkRecentInfo` Decreases the reference count of @info by one. If the reference count reaches zero, @info is deallocated, and the memory freed. a `GtkRecentInfo` Manages and looks up recently used files. Each recently used file is identified by its URI, and has meta-data associated to it, like the names and command lines of the applications that have registered it, the number of time each application has registered the same file, the mime type of the file and whether the file should be displayed only by the applications that have registered it. The recently used files list is per user. `GtkRecentManager` acts like a database of all the recently used files. You can create new `GtkRecentManager` objects, but it is more efficient to use the default manager created by GTK. Adding a new recently used file is as simple as: ```c GtkRecentManager *manager; manager = gtk_recent_manager_get_default (); gtk_recent_manager_add_item (manager, file_uri); ``` The `GtkRecentManager` will try to gather all the needed information from the file itself through GIO. Looking up the meta-data associated with a recently used file given its URI requires calling [method@Gtk.RecentManager.lookup_item]: ```c GtkRecentManager *manager; GtkRecentInfo *info; GError *error = NULL; manager = gtk_recent_manager_get_default (); info = gtk_recent_manager_lookup_item (manager, file_uri, &error); if (error) { g_warning ("Could not find the file: %s", error->message); g_error_free (error); } else { // Use the info object gtk_recent_info_unref (info); } ``` In order to retrieve the list of recently used files, you can use [method@Gtk.RecentManager.get_items], which returns a list of [struct@Gtk.RecentInfo]. Note that the maximum age of the recently used files list is controllable through the [property@Gtk.Settings:gtk-recent-files-max-age] property. Creates a new recent manager object. Recent manager objects are used to handle the list of recently used resources. A `GtkRecentManager` object monitors the recently used resources list, and emits the [signal@Gtk.RecentManager::changed] signal each time something inside the list changes. `GtkRecentManager` objects are expensive: be sure to create them only when needed. You should use [func@Gtk.RecentManager.get_default] instead. A newly created `GtkRecentManager` object Gets a unique instance of `GtkRecentManager` that you can share in your application without caring about memory management. A unique `GtkRecentManager`. Do not ref or unref it. Adds a new resource, pointed by @uri, into the recently used resources list, using the metadata specified inside the `GtkRecentData` passed in @recent_data. The passed URI will be used to identify this resource inside the list. In order to register the new recently used resource, metadata about the resource must be passed as well as the URI; the metadata is stored in a `GtkRecentData`, which must contain the MIME type of the resource pointed by the URI; the name of the application that is registering the item, and a command line to be used when launching the item. Optionally, a `GtkRecentData` might contain a UTF-8 string to be used when viewing the item instead of the last component of the URI; a short description of the item; whether the item should be considered private - that is, should be displayed only by the applications that have registered it. %TRUE if the new item was successfully added to the recently used resources list, %FALSE otherwise a `GtkRecentManager` a valid URI metadata of the resource Adds a new resource, pointed by @uri, into the recently used resources list. This function automatically retrieves some of the needed metadata and setting other metadata to common default values; it then feeds the data to [method@Gtk.RecentManager.add_full]. See [method@Gtk.RecentManager.add_full] if you want to explicitly define the metadata for the resource pointed by @uri. %TRUE if the new item was successfully added to the recently used resources list a `GtkRecentManager` a valid URI Gets the list of recently used resources. a list of newly allocated `GtkRecentInfo objects`. Use [method@Gtk.RecentInfo.unref] on each item inside the list, and then free the list itself using g_list_free(). a `GtkRecentManager` Checks whether there is a recently used resource registered with @uri inside the recent manager. %TRUE if the resource was found, %FALSE otherwise a `GtkRecentManager` a URI Searches for a URI inside the recently used resources list, and returns a `GtkRecentInfo` containing information about the resource like its MIME type, or its display name. a `GtkRecentInfo` containing information about the resource pointed by @uri, or %NULL if the URI was not registered in the recently used resources list. Free with [method@Gtk.RecentInfo.unref]. a `GtkRecentManager` a URI Changes the location of a recently used resource from @uri to @new_uri. Please note that this function will not affect the resource pointed by the URIs, but only the URI used in the recently used resources list. %TRUE on success a `GtkRecentManager` the URI of a recently used resource the new URI of the recently used resource, or %NULL to remove the item pointed by @uri in the list Purges every item from the recently used resources list. the number of items that have been removed from the recently used resources list a `GtkRecentManager` Removes a resource pointed by @uri from the recently used resources list handled by a recent manager. %TRUE if the item pointed by @uri has been successfully removed by the recently used resources list, and %FALSE otherwise a `GtkRecentManager` the URI of the item you wish to remove The full path to the file to be used to store and read the recently used resources list The size of the recently used resources list. Emitted when the current recently used resources manager changes its contents. This can happen either by calling [method@Gtk.RecentManager.add_item] or by another application. `GtkRecentManagerClass` contains only private data. Error codes for `GtkRecentManager` operations the URI specified does not exists in the recently used resources list. the URI specified is not valid. the supplied string is not UTF-8 encoded. no application has registered the specified item. failure while reading the recently used resources file. failure while writing the recently used resources file. unspecified error. Registers an error quark for [class@RecentManager] errors. the error quark Values for the [property@Gtk.Settings:gtk-interface-reduced-motion] and [property@Gtk.CssProvider:prefers-reduced-motion] properties that indicates the preferred level of motion animations. This information can be used inside CSS via media queries. The user has made no preference known to the system The user has notified the system that they prefer an interface that removes or replaces the types of motion-based animation that either trigger discomfort for those with vestibular motion sensitivity, or distraction for those with attention deficits Represents a request of a screen object in a given orientation. These are primarily used in container implementations when allocating a natural size for children. See [func@distribute_natural_allocation]. A client pointer The minimum size needed for allocation in a given orientation The natural size for allocation in a given orientation Represents the desired size of a widget. See [GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management) for more information. the widget’s desired width the widget’s desired height Allocates a new `GtkRequisition`. The struct is initialized to zero. a new empty `GtkRequisition` Copies a `GtkRequisition`. a copy of @requisition a `GtkRequisition` Frees a `GtkRequisition`. a `GtkRequisition` Predefined values for use as response ids in gtk_dialog_add_button(). All predefined values are negative; GTK leaves values of 0 or greater for application-defined response ids. There is no replacement. Returned if an action widget has no response id, or if the dialog gets programmatically hidden or destroyed Generic response id, not used by GTK dialogs Generic response id, not used by GTK dialogs Returned if the dialog is deleted Returned by OK buttons in GTK dialogs Returned by Cancel buttons in GTK dialogs Returned by Close buttons in GTK dialogs Returned by Yes buttons in GTK dialogs Returned by No buttons in GTK dialogs Returned by Apply buttons in GTK dialogs Returned by Help buttons in GTK dialogs Animates the transition of its child from invisible to visible. The style of transition can be controlled with [method@Gtk.Revealer.set_transition_type]. These animations respect the [property@Gtk.Settings:gtk-enable-animations] setting. # CSS nodes `GtkRevealer` has a single CSS node with name revealer. When styling `GtkRevealer` using CSS, remember that it only hides its contents, not itself. That means applied margin, padding and borders will be visible even when the [property@Gtk.Revealer:reveal-child] property is set to %FALSE. # Accessibility `GtkRevealer` uses the [enum@Gtk.AccessibleRole.group] role. The child of `GtkRevealer`, if set, is always available in the accessibility tree, regardless of the state of the revealer widget. Creates a new `GtkRevealer`. a newly created `GtkRevealer` Gets the child widget of @revealer. the child widget of @revealer a `GtkRevealer` Returns whether the child is fully revealed. In other words, this returns whether the transition to the revealed state is completed. %TRUE if the child is fully revealed a `GtkRevealer` Returns whether the child is currently revealed. This function returns %TRUE as soon as the transition is to the revealed state is started. To learn whether the child is fully revealed (ie the transition is completed), use [method@Gtk.Revealer.get_child_revealed]. %TRUE if the child is revealed. a `GtkRevealer` Returns the amount of time (in milliseconds) that transitions will take. the transition duration a `GtkRevealer` Gets the type of animation that will be used for transitions in @revealer. the current transition type of @revealer a `GtkRevealer` Sets the child widget of @revealer. a `GtkRevealer` the child widget Tells the `GtkRevealer` to reveal or conceal its child. The transition will be animated with the current transition type of @revealer. a `GtkRevealer` %TRUE to reveal the child Sets the duration that transitions will take. a `GtkRevealer` the new duration, in milliseconds Sets the type of animation that will be used for transitions in @revealer. Available types include various kinds of fades and slides. a `GtkRevealer` the new transition type The child widget. Whether the child is revealed and the animation target reached. Whether the revealer should reveal the child. The animation duration, in milliseconds. The type of animation used to transition. These enumeration values describe the possible transitions when the child of a `GtkRevealer` widget is shown or hidden. No transition Fade in Slide in from the left Slide in from the right Slide in from the bottom Slide in from the top Floop in from the left Floop in from the right Floop in from the bottom Floop in from the top Combination of [enum@Gtk.RevealerTransitionType.CROSSFADE] and [enum@Gtk.RevealerTransitionType.SLIDE_RIGHT]. Combination of [enum@Gtk.RevealerTransitionType.CROSSFADE] and [enum@Gtk.RevealerTransitionType.SLIDE_LEFT]. Combination of [enum@Gtk.RevealerTransitionType.CROSSFADE] and [enum@Gtk.RevealerTransitionType.SLIDE_UP]. Combination of [enum@Gtk.RevealerTransitionType.CROSSFADE] and [enum@Gtk.RevealerTransitionType.SLIDE_DOWN]. An interface for widgets that can act as the root of a widget hierarchy. The root widget takes care of providing the connection to the windowing system and manages layout, drawing and event delivery for its widget hierarchy. The obvious example of a `GtkRoot` is `GtkWindow`. To get the display to which a `GtkRoot` belongs, use [method@Gtk.Root.get_display]. `GtkRoot` also maintains the location of keyboard focus inside its widget hierarchy, with [method@Gtk.Root.set_focus] and [method@Gtk.Root.get_focus]. Returns the display that this `GtkRoot` is on. the display of @root a `GtkRoot` Retrieves the current focused widget within the root. Note that this is the widget that would have the focus if the root is active; if the root is not focused then `gtk_widget_has_focus (widget)` will be %FALSE for the widget. the currently focused widget a `GtkRoot` If @focus is not the current focus widget, and is focusable, sets it as the focus widget for the root. If @focus is %NULL, unsets the focus widget for the root. To set the focus to a particular widget in the root, it is usually more convenient to use [method@Gtk.Widget.grab_focus] instead of this function. a `GtkRoot` widget to be the new focus widget, or %NULL to unset the focus widget A priority that can be used when adding a `GtkStyleProvider` for application-specific style information. The priority used for default style information that is used in the absence of themes. Note that this is not very useful for providing default styling for custom style classes - themes are likely to override styling provided at this priority with catch-all `* {...}` rules. The priority used for style information provided via `GtkSettings`. This priority is higher than %GTK_STYLE_PROVIDER_PRIORITY_THEME to let settings override themes. The priority used for style information provided by themes. The priority used for the style information from `$XDG_CONFIG_HOME/gtk-4.0/gtk.css`. You should not use priorities higher than this, to give the user the last word. The `GtkSvgFeatures` that are enabled by default. Allows to select a numeric value with a slider control. <picture> <source srcset="scales-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkScale" src="scales.png"> </picture> To use it, you’ll probably want to investigate the methods on its base class, [class@Gtk.Range], in addition to the methods for `GtkScale` itself. To set the value of a scale, you would normally use [method@Gtk.Range.set_value]. To detect changes to the value, you would normally use the [signal@Gtk.Range::value-changed] signal. Note that using the same upper and lower bounds for the `GtkScale` (through the `GtkRange` methods) will hide the slider itself. This is useful for applications that want to show an undeterminate value on the scale, without changing the layout of the application (such as movie or music players). # GtkScale as GtkBuildable `GtkScale` supports a custom `<marks>` element, which can contain multiple `<mark\>` elements. The “value” and “position” attributes have the same meaning as [method@Gtk.Scale.add_mark] parameters of the same name. If the element is not empty, its content is taken as the markup to show at the mark. It can be translated with the usual ”translatable” and “context” attributes. # Shortcuts and Gestures `GtkPopoverMenu` supports the following keyboard shortcuts: - Arrow keys, <kbd>+</kbd> and <kbd>-</kbd> will increment or decrement by step, or by page when combined with <kbd>Ctrl</kbd>. - <kbd>PgUp</kbd> and <kbd>PgDn</kbd> will increment or decrement by page. - <kbd>Home</kbd> and <kbd>End</kbd> will set the minimum or maximum value. # CSS nodes ``` scale[.fine-tune][.marks-before][.marks-after] ├── [value][.top][.right][.bottom][.left] ├── marks.top │ ├── mark │ ┊ ├── [label] │ ┊ ╰── indicator ┊ ┊ │ ╰── mark ├── marks.bottom │ ├── mark │ ┊ ├── indicator │ ┊ ╰── [label] ┊ ┊ │ ╰── mark ╰── trough ├── [fill] ├── [highlight] ╰── slider ``` `GtkScale` has a main CSS node with name scale and a subnode for its contents, with subnodes named trough and slider. The main node gets the style class .fine-tune added when the scale is in 'fine-tuning' mode. If the scale has an origin (see [method@Gtk.Scale.set_has_origin]), there is a subnode with name highlight below the trough node that is used for rendering the highlighted part of the trough. If the scale is showing a fill level (see [method@Gtk.Range.set_show_fill_level]), there is a subnode with name fill below the trough node that is used for rendering the filled in part of the trough. If marks are present, there is a marks subnode before or after the trough node, below which each mark gets a node with name mark. The marks nodes get either the .top or .bottom style class. The mark node has a subnode named indicator. If the mark has text, it also has a subnode named label. When the mark is either above or left of the scale, the label subnode is the first when present. Otherwise, the indicator subnode is the first. The main CSS node gets the 'marks-before' and/or 'marks-after' style classes added depending on what marks are present. If the scale is displaying the value (see [property@Gtk.Scale:draw-value]), there is subnode with name value. This node will get the .top or .bottom style classes similar to the marks node. # Accessibility `GtkScale` uses the [enum@Gtk.AccessibleRole.slider] role. Creates a new `GtkScale`. a new `GtkScale` the scale’s orientation. the [class@Gtk.Adjustment] which sets the range of the scale, or %NULL to create a new adjustment. Creates a new scale widget with a range from @min to @max. The returns scale will have the given orientation and will let the user input a number between @min and @max (including @min and @max) with the increment @step. @step must be nonzero; it’s the distance the slider moves when using the arrow keys to adjust the scale value. Note that the way in which the precision is derived works best if @step is a power of ten. If the resulting precision is not suitable for your needs, use [method@Gtk.Scale.set_digits] to correct it. a new `GtkScale` the scale’s orientation. minimum value maximum value step increment (tick size) used with keyboard shortcuts Obtains the coordinates where the scale will draw the `PangoLayout` representing the text in the scale. Remember when using the `PangoLayout` function you need to convert to and from pixels using `PANGO_PIXELS()` or `PANGO_SCALE`. If the [property@Gtk.Scale:draw-value] property is %FALSE, the return values are undefined. a `GtkScale` location to store X offset of layout location to store Y offset of layout Adds a mark at @value. A mark is indicated visually by drawing a tick mark next to the scale, and GTK makes it easy for the user to position the scale exactly at the marks value. If @markup is not %NULL, text is shown next to the tick mark. To remove marks from a scale, use [method@Gtk.Scale.clear_marks]. a `GtkScale` the value at which the mark is placed, must be between the lower and upper limits of the scales’ adjustment where to draw the mark. For a horizontal scale, %GTK_POS_TOP and %GTK_POS_LEFT are drawn above the scale, anything else below. For a vertical scale, %GTK_POS_LEFT and %GTK_POS_TOP are drawn to the left of the scale, anything else to the right. Text to be shown at the mark, using Pango markup Removes any marks that have been added. a `GtkScale` Gets the number of decimal places that are displayed in the value. the number of decimal places that are displayed a `GtkScale` Returns whether the current value is displayed as a string next to the slider. whether the current value is displayed as a string a `GtkScale` Returns whether the scale has an origin. %TRUE if the scale has an origin. a `GtkScale` Gets the `PangoLayout` used to display the scale. The returned object is owned by the scale so does not need to be freed by the caller. the [class@Pango.Layout] for this scale, or %NULL if the [property@Gtk.Scale:draw-value] property is %FALSE. A `GtkScale` Obtains the coordinates where the scale will draw the `PangoLayout` representing the text in the scale. Remember when using the `PangoLayout` function you need to convert to and from pixels using `PANGO_PIXELS()` or `PANGO_SCALE`. If the [property@Gtk.Scale:draw-value] property is %FALSE, the return values are undefined. a `GtkScale` location to store X offset of layout location to store Y offset of layout Gets the position in which the current value is displayed. the position in which the current value is displayed a `GtkScale` Sets the number of decimal places that are displayed in the value. Also causes the value of the adjustment to be rounded to this number of digits, so the retrieved value matches the displayed one, if [property@Gtk.Scale:draw-value] is %TRUE when the value changes. If you want to enforce rounding the value when [property@Gtk.Scale:draw-value] is %FALSE, you can set [property@Gtk.Range:round-digits] instead. Note that rounding to a small number of digits can interfere with the smooth autoscrolling that is built into `GtkScale`. As an alternative, you can use [method@Gtk.Scale.set_format_value_func] to format the displayed value yourself. a `GtkScale` the number of decimal places to display, e.g. use 1 to display 1.0, 2 to display 1.00, etc Specifies whether the current value is displayed as a string next to the slider. a `GtkScale` %TRUE to draw the value @func allows you to change how the scale value is displayed. The given function will return an allocated string representing @value. That string will then be used to display the scale's value. If #NULL is passed as @func, the value will be displayed on its own, rounded according to the value of the [property@Gtk.Scale:digits] property. a `GtkScale` function that formats the value user data to pass to @func destroy function for @user_data Sets whether the scale has an origin. If [property@Gtk.Scale:has-origin] is set to %TRUE (the default), the scale will highlight the part of the trough between the origin (bottom or left side) and the current value. a `GtkScale` %TRUE if the scale has an origin Sets the position in which the current value is displayed. a `GtkScale` the position in which the current value is displayed The number of decimal places that are displayed in the value. Whether the current value is displayed as a string next to the slider. Whether the scale has an origin. The position in which the current value is displayed. Provides a button which pops up a scale widget. This kind of widget is commonly used for volume controls in multimedia applications, and GTK provides a [class@Gtk.VolumeButton] subclass that is tailored for this use case. # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.ScaleButton::popup] # CSS nodes ``` scalebutton.scale ╰── button.toggle ╰── <icon> ``` `GtkScaleButton` has a single CSS node with name scalebutton and `.scale` style class, and contains a `button` node with a `.toggle` style class. Creates a `GtkScaleButton`. The new scale button has a range between @min and @max, with a stepping of @step. a new `GtkScaleButton` the minimum value of the scale (usually 0) the maximum value of the scale (usually 100) the stepping of value when a scroll-wheel event, or up/down arrow event occurs (usually 2) a %NULL-terminated array of icon names, or %NULL if you want to set the list later with gtk_scale_button_set_icons() Queries a `GtkScaleButton` and returns its current state. Returns %TRUE if the scale button is pressed in and %FALSE if it is raised. whether the button is pressed a `GtkScaleButton` Gets the `GtkAdjustment` associated with the `GtkScaleButton`’s scale. See [method@Gtk.Range.get_adjustment] for details. the adjustment associated with the scale a `GtkScaleButton` Returns whether the button has a frame. %TRUE if the button has a frame a `GtkScaleButton` Retrieves the minus button of the `GtkScaleButton`. the minus button of the `GtkScaleButton` a `GtkScaleButton` Retrieves the plus button of the `GtkScaleButton.` the plus button of the `GtkScaleButton` a `GtkScaleButton` Retrieves the popup of the `GtkScaleButton`. the popup of the `GtkScaleButton` a `GtkScaleButton` Gets the current value of the scale button. current value of the scale button a `GtkScaleButton` Sets the `GtkAdjustment` to be used as a model for the `GtkScaleButton`’s scale. See [method@Gtk.Range.set_adjustment] for details. a `GtkScaleButton` a `GtkAdjustment` Sets the style of the button. a `GtkScaleButton` whether the button should have a visible frame Sets the icons to be used by the scale button. a `GtkScaleButton` a %NULL-terminated array of icon names Sets the current value of the scale. If the value is outside the minimum or maximum range values, it will be clamped to fit inside them. The scale button emits the [signal@Gtk.ScaleButton::value-changed] signal if the value changes. a `GtkScaleButton` new value of the scale button If the scale button should be pressed in. The `GtkAdjustment` that is used as the model. If the scale button has a frame. The names of the icons to be used by the scale button. The first item in the array will be used in the button when the current value is the lowest value, the second item for the highest value. All the subsequent icons will be used for all the other values, spread evenly over the range of values. If there's only one icon name in the @icons array, it will be used for all the values. If only two icon names are in the @icons array, the first one will be used for the bottom 50% of the scale, and the second one for the top 50%. It is recommended to use at least 3 icons so that the `GtkScaleButton` reflects the current value of the scale better for the users. The value of the scale. Emitted to dismiss the popup. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Escape</kbd>. Emitted to popup the scale widget. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Space</kbd>, <kbd>Enter</kbd> and <kbd>Return</kbd>. Emitted when the value field has changed. the new value a `GtkScale` location to store X offset of layout location to store Y offset of layout Function that formats the value of a scale. See [method@Gtk.Scale.set_format_value_func]. A newly allocated string describing a textual representation of the given numerical value. The `GtkScale` The numeric value to format user data Provides detailed information on how a scroll operation should be performed. Scrolling functions usually allow passing a `NULL` scroll info which will cause the default values to be used and just scroll the element into view. Creates a new scroll info for scrolling an element into view. A new scroll info Checks if horizontal scrolling is enabled. %TRUE if horizontal scrolling is enabled. a `GtkScrollInfo` Checks if vertical scrolling is enabled. %TRUE if vertical scrolling is enabled. a `GtkScrollInfo` Increases the reference count of a `GtkScrollInfo` by one. the passed in `GtkScrollInfo`. a `GtkScrollInfo` Turns horizontal scrolling on or off. a `GtkScrollInfo` if scrolling in the horizontal direction should happen Turns vertical scrolling on or off. a `GtkScrollInfo` if scrolling in the vertical direction should happen Decreases the reference count of a `GtkScrollInfo` by one. If the resulting reference count is zero, frees the self. a `GtkScrollInfo` Passed as argument to various keybinding signals. Scroll in steps. Scroll by pages. Scroll to ends. Scroll in horizontal steps. Scroll by horizontal pages. Scroll to the horizontal ends. Scrolling types. No scrolling. Jump to new location. Step backward. Step forward. Page backward. Page forward. Step up. Step down. Page up. Page down. Step to the left. Step to the right. Page to the left. Page to the right. Scroll to start. Scroll to end. An interface for widgets with native scrolling ability. To implement this interface you should override the [property@Gtk.Scrollable:hadjustment] and [property@Gtk.Scrollable:vadjustment] properties. ## Creating a scrollable widget All scrollable widgets should do the following. - When a parent widget sets the scrollable child widget’s adjustments, the widget should connect to the [signal@Gtk.Adjustment::value-changed] signal. The child widget should then populate the adjustments’ properties as soon as possible, which usually means queueing an allocation right away and populating the properties in the [vfunc@Gtk.Widget.size_allocate] implementation. - Because its preferred size is the size for a fully expanded widget, the scrollable widget must be able to cope with underallocations. This means that it must accept any value passed to its [vfunc@Gtk.Widget.size_allocate] implementation. - When the parent allocates space to the scrollable child widget, the widget must ensure the adjustments’ property values are correct and up to date, for example using [method@Gtk.Adjustment.configure]. - When any of the adjustments emits the [signal@Gtk.Adjustment::value-changed] signal, the scrollable widget should scroll its contents. Returns the size of a non-scrolling border around the outside of the scrollable. An example for this would be treeview headers. GTK can use this information to display overlaid graphics, like the overshoot indication, at the right position. %TRUE if @border has been set a `GtkScrollable` return location for the results Returns the size of a non-scrolling border around the outside of the scrollable. An example for this would be treeview headers. GTK can use this information to display overlaid graphics, like the overshoot indication, at the right position. %TRUE if @border has been set a `GtkScrollable` return location for the results Retrieves the `GtkAdjustment` used for horizontal scrolling. horizontal `GtkAdjustment`. a `GtkScrollable` Gets the horizontal `GtkScrollablePolicy`. The horizontal `GtkScrollablePolicy`. a `GtkScrollable` Retrieves the `GtkAdjustment` used for vertical scrolling. vertical `GtkAdjustment`. a `GtkScrollable` Gets the vertical `GtkScrollablePolicy`. The vertical `GtkScrollablePolicy`. a `GtkScrollable` Sets the horizontal adjustment of the `GtkScrollable`. a `GtkScrollable` a `GtkAdjustment` Sets the `GtkScrollablePolicy`. The policy determines whether horizontal scrolling should start below the minimum width or below the natural width. a `GtkScrollable` the horizontal `GtkScrollablePolicy` Sets the vertical adjustment of the `GtkScrollable`. a `GtkScrollable` a `GtkAdjustment` Sets the `GtkScrollablePolicy`. The policy determines whether vertical scrolling should start below the minimum height or below the natural height. a `GtkScrollable` the vertical `GtkScrollablePolicy` Horizontal `GtkAdjustment` of the scrollable widget. This adjustment is shared between the scrollable widget and its parent. Determines when horizontal scrolling should start. Vertical `GtkAdjustment` of the scrollable widget. This adjustment is shared between the scrollable widget and its parent. Determines when vertical scrolling should start. %TRUE if @border has been set a `GtkScrollable` return location for the results Defines the policy to be used in a scrollable widget when updating the scrolled window adjustments in a given orientation. Scrollable adjustments are based on the minimum size Scrollable adjustments are based on the natural size Shows a horizontal or vertical scrollbar. <picture> <source srcset="scrollbar-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkScrollbar" src="scrollbar.png"> </picture> Its position and movement are controlled by the adjustment that is passed to or created by [ctor@Gtk.Scrollbar.new]. See [class@Gtk.Adjustment] for more details. The [property@Gtk.Adjustment:value] field sets the position of the thumb and must be between [property@Gtk.Adjustment:lower] and [property@Gtk.Adjustment:upper] - [property@Gtk.Adjustment:page-size]. The [property@Gtk.Adjustment:page-size] represents the size of the visible scrollable area. The fields [property@Gtk.Adjustment:step-increment] and [property@Gtk.Adjustment:page-increment] fields are added to or subtracted from the [property@Gtk.Adjustment:value] when the user asks to move by a step (using e.g. the cursor arrow keys) or by a page (using e.g. the Page Down/Up keys). # CSS nodes ``` scrollbar ╰── range[.fine-tune] ╰── trough ╰── slider ``` `GtkScrollbar` has a main CSS node with name scrollbar and a subnode for its contents. The main node gets the .horizontal or .vertical style classes applied, depending on the scrollbar's orientation. The range node gets the style class .fine-tune added when the scrollbar is in 'fine-tuning' mode. Other style classes that may be added to scrollbars inside [class@Gtk.ScrolledWindow] include the positional classes (.left, .right, .top, .bottom) and style classes related to overlay scrolling (.overlay-indicator, .dragging, .hovering). # Accessibility `GtkScrollbar` uses the [enum@Gtk.AccessibleRole.scrollbar] role. Creates a new scrollbar with the given orientation. the new `GtkScrollbar`. the scrollbar’s orientation. the [class@Gtk.Adjustment] to use, or %NULL to create a new adjustment. Returns the scrollbar's adjustment. the scrollbar's adjustment a `GtkScrollbar` Makes the scrollbar use the given adjustment. a `GtkScrollbar` the adjustment to set The `GtkAdjustment` controlled by this scrollbar. Makes its child scrollable. <picture> <source srcset="scrolledwindow-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkScrolledWindow" src="scrolledwindow.png"> </picture> It does so using either internally added scrollbars or externally associated adjustments, and optionally draws a frame around the child. Widgets with native scrolling support, i.e. those whose classes implement the [iface@Gtk.Scrollable] interface, are added directly. For other types of widget, the class [class@Gtk.Viewport] acts as an adaptor, giving scrollability to other widgets. [method@Gtk.ScrolledWindow.set_child] intelligently accounts for whether or not the added child is a `GtkScrollable`. If it isn’t, then it wraps the child in a `GtkViewport`. Therefore, you can just add any child widget and not worry about the details. If [method@Gtk.ScrolledWindow.set_child] has added a `GtkViewport` for you, it will be automatically removed when you unset the child. Unless [property@Gtk.ScrolledWindow:hscrollbar-policy] and [property@Gtk.ScrolledWindow:vscrollbar-policy] are %GTK_POLICY_NEVER or %GTK_POLICY_EXTERNAL, `GtkScrolledWindow` adds internal `GtkScrollbar` widgets around its child. The scroll position of the child, and if applicable the scrollbars, is controlled by the [property@Gtk.ScrolledWindow:hadjustment] and [property@Gtk.ScrolledWindow:vadjustment] that are associated with the `GtkScrolledWindow`. See the docs on [class@Gtk.Scrollbar] for the details, but note that the “step_increment” and “page_increment” fields are only effective if the policy causes scrollbars to be present. If a `GtkScrolledWindow` doesn’t behave quite as you would like, or doesn’t have exactly the right layout, it’s very possible to set up your own scrolling with `GtkScrollbar` and for example a `GtkGrid`. # Touch support `GtkScrolledWindow` has built-in support for touch devices. When a touchscreen is used, swiping will move the scrolled window, and will expose 'kinetic' behavior. This can be turned off with the [property@Gtk.ScrolledWindow:kinetic-scrolling] property if it is undesired. `GtkScrolledWindow` also displays visual 'overshoot' indication when the content is pulled beyond the end, and this situation can be captured with the [signal@Gtk.ScrolledWindow::edge-overshot] signal. If no mouse device is present, the scrollbars will overlaid as narrow, auto-hiding indicators over the content. If traditional scrollbars are desired although no mouse is present, this behaviour can be turned off with the [property@Gtk.ScrolledWindow:overlay-scrolling] property. # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.ScrolledWindow::scroll-child] # CSS nodes `GtkScrolledWindow` has a main CSS node with name scrolledwindow. It gets a .frame style class added when [property@Gtk.ScrolledWindow:has-frame] is %TRUE. It uses subnodes with names overshoot and undershoot to draw the overflow and underflow indications. These nodes get the .left, .right, .top or .bottom style class added depending on where the indication is drawn. `GtkScrolledWindow` also sets the positional style classes (.left, .right, .top, .bottom) and style classes related to overlay scrolling (.overlay-indicator, .dragging, .hovering) on its scrollbars. If both scrollbars are visible, the area where they meet is drawn with a subnode named junction. # Accessibility Until GTK 4.10, `GtkScrolledWindow` used the [enum@Gtk.AccessibleRole.group] role. Starting from GTK 4.12, `GtkScrolledWindow` uses the [enum@Gtk.AccessibleRole.generic] role. Creates a new scrolled window. a new scrolled window Gets the child widget of @scrolled_window. If the scrolled window automatically added a [class@Gtk.Viewport], this function will return the viewport widget, and you can retrieve its child using [method@Gtk.Viewport.get_child]. the child widget of @scrolled_window a `GtkScrolledWindow` Returns the horizontal scrollbar’s adjustment. This is the adjustment used to connect the horizontal scrollbar to the child widget’s horizontal scroll functionality. the horizontal `GtkAdjustment` a `GtkScrolledWindow` Gets whether the scrolled window draws a frame. %TRUE if the @scrolled_window has a frame a `GtkScrolledWindow` Returns the horizontal scrollbar of @scrolled_window. the horizontal scrollbar of the scrolled window. a `GtkScrolledWindow` Returns the specified kinetic scrolling behavior. the scrolling behavior flags. a `GtkScrolledWindow` Returns the maximum content height set. the maximum content height, or -1 a `GtkScrolledWindow` Returns the maximum content width set. the maximum content width, or -1 a `GtkScrolledWindow` Gets the minimal content height of @scrolled_window. the minimal content height a `GtkScrolledWindow` Gets the minimum content width of @scrolled_window. the minimum content width a `GtkScrolledWindow` Returns whether overlay scrolling is enabled for this scrolled window. %TRUE if overlay scrolling is enabled a `GtkScrolledWindow` Gets the placement of the contents with respect to the scrollbars. the current placement value. a `GtkScrolledWindow` Retrieves the current policy values for the horizontal and vertical scrollbars. See [method@Gtk.ScrolledWindow.set_policy]. a `GtkScrolledWindow` location to store the policy for the horizontal scrollbar location to store the policy for the vertical scrollbar Reports whether the natural height of the child will be calculated and propagated through the scrolled window’s requested natural height. whether natural height propagation is enabled. a `GtkScrolledWindow` Reports whether the natural width of the child will be calculated and propagated through the scrolled window’s requested natural width. whether natural width propagation is enabled. a `GtkScrolledWindow` Returns the vertical scrollbar’s adjustment. This is the adjustment used to connect the vertical scrollbar to the child widget’s vertical scroll functionality. the vertical `GtkAdjustment` a `GtkScrolledWindow` Returns the vertical scrollbar of @scrolled_window. the vertical scrollbar of the scrolled window. a `GtkScrolledWindow` Sets the child widget of @scrolled_window. If @child does not implement the [iface@Gtk.Scrollable] interface, the scrolled window will add @child to a [class@Gtk.Viewport] instance and then add the viewport as its child widget. a `GtkScrolledWindow` the child widget Sets the `GtkAdjustment` for the horizontal scrollbar. a `GtkScrolledWindow` the `GtkAdjustment` to use, or %NULL to create a new one Changes the frame drawn around the contents of @scrolled_window. a `GtkScrolledWindow` whether to draw a frame around scrolled window contents Turns kinetic scrolling on or off. Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN. a `GtkScrolledWindow` %TRUE to enable kinetic scrolling Sets the maximum height that @scrolled_window should keep visible. The @scrolled_window will grow up to this height before it starts scrolling the content. It is a programming error to set the maximum content height to a value smaller than [property@Gtk.ScrolledWindow:min-content-height]. a `GtkScrolledWindow` the maximum content height Sets the maximum width that @scrolled_window should keep visible. The @scrolled_window will grow up to this width before it starts scrolling the content. It is a programming error to set the maximum content width to a value smaller than [property@Gtk.ScrolledWindow:min-content-width]. a `GtkScrolledWindow` the maximum content width Sets the minimum height that @scrolled_window should keep visible. Note that this can and (usually will) be smaller than the minimum size of the content. It is a programming error to set the minimum content height to a value greater than [property@Gtk.ScrolledWindow:max-content-height]. a `GtkScrolledWindow` the minimal content height Sets the minimum width that @scrolled_window should keep visible. Note that this can and (usually will) be smaller than the minimum size of the content. It is a programming error to set the minimum content width to a value greater than [property@Gtk.ScrolledWindow:max-content-width]. a `GtkScrolledWindow` the minimal content width Enables or disables overlay scrolling for this scrolled window. a `GtkScrolledWindow` whether to enable overlay scrolling Sets the placement of the contents with respect to the scrollbars for the scrolled window. The default is %GTK_CORNER_TOP_LEFT, meaning the child is in the top left, with the scrollbars underneath and to the right. Other values in [enum@Gtk.CornerType] are %GTK_CORNER_TOP_RIGHT, %GTK_CORNER_BOTTOM_LEFT, and %GTK_CORNER_BOTTOM_RIGHT. See also [method@Gtk.ScrolledWindow.get_placement] and [method@Gtk.ScrolledWindow.unset_placement]. a `GtkScrolledWindow` position of the child window Sets the scrollbar policy for the horizontal and vertical scrollbars. The policy determines when the scrollbar should appear; it is a value from the [enum@Gtk.PolicyType] enumeration. If %GTK_POLICY_ALWAYS, the scrollbar is always present; if %GTK_POLICY_NEVER, the scrollbar is never present; if %GTK_POLICY_AUTOMATIC, the scrollbar is present only if needed (that is, if the slider part of the bar would be smaller than the trough — the display is larger than the page size). a `GtkScrolledWindow` policy for horizontal bar policy for vertical bar Sets whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height. a `GtkScrolledWindow` whether to propagate natural height Sets whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width. a `GtkScrolledWindow` whether to propagate natural width Sets the `GtkAdjustment` for the vertical scrollbar. a `GtkScrolledWindow` the `GtkAdjustment` to use, or %NULL to create a new one Unsets the placement of the contents with respect to the scrollbars. If no window placement is set for a scrolled window, it defaults to %GTK_CORNER_TOP_LEFT. a `GtkScrolledWindow` The child widget. When setting this property, if the child widget does not implement [iface@Gtk.Scrollable], the scrolled window will add the child to a [class@Gtk.Viewport] and then set the viewport as the child. The `GtkAdjustment` for the horizontal position. Whether to draw a frame around the contents. When the horizontal scrollbar is displayed. Use [method@Gtk.ScrolledWindow.set_policy] to set this property. Whether kinetic scrolling is enabled or not. Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN. The maximum content height of @scrolled_window. The maximum content width of @scrolled_window. The minimum content height of @scrolled_window. The minimum content width of @scrolled_window. Whether overlay scrolling is enabled or not. If it is, the scrollbars are only added as traditional widgets when a mouse is present. Otherwise, they are overlaid on top of the content, as narrow indicators. Note that overlay scrolling can also be globally disabled, with the [property@Gtk.Settings:gtk-overlay-scrolling] setting. Whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height. This is useful in cases where an attempt should be made to allocate exactly enough space for the natural size of the child. Whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width. This is useful in cases where an attempt should be made to allocate exactly enough space for the natural size of the child. The `GtkAdjustment` for the vertical position. When the vertical scrollbar is displayed. Use [method@Gtk.ScrolledWindow.set_policy] to set this property. Where the contents are located with respect to the scrollbars. Emitted whenever user initiated scrolling makes the scrolled window firmly surpass the limits defined by the adjustment in that orientation. A similar behavior without edge resistance is provided by the [signal@Gtk.ScrolledWindow::edge-reached] signal. Note: The @pos argument is LTR/RTL aware, so callers should be aware too if intending to provide behavior on horizontal edges. edge side that was hit Emitted whenever user-initiated scrolling makes the scrolled window exactly reach the lower or upper limits defined by the adjustment in that orientation. A similar behavior with edge resistance is provided by the [signal@Gtk.ScrolledWindow::edge-overshot] signal. Note: The @pos argument is LTR/RTL aware, so callers should be aware too if intending to provide behavior on horizontal edges. edge side that was reached Emitted when focus is moved away from the scrolled window by a keybinding. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>Tab</kbd> to move forward and <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Tab</kbd>` to move backward. either %GTK_DIR_TAB_FORWARD or %GTK_DIR_TAB_BACKWARD Emitted when a keybinding that scrolls is pressed. This is a [keybinding signal](class.SignalAction.html). The horizontal or vertical adjustment is updated which triggers a signal that the scrolled window’s child may listen to and scroll itself. whether the scroll happened a `GtkScrollType` describing how much to scroll whether the keybinding scrolls the child horizontally or not Reveals a search entry when search is started. <picture> <source srcset="search-bar-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkSearchBar" src="search-bar.png"> </picture> It can also contain additional widgets, such as drop-down menus, or buttons. The search bar would appear when a search is started through typing on the keyboard, or the application’s search mode is toggled on. For keyboard presses to start a search, the search bar must be told of a widget to capture key events from through [method@Gtk.SearchBar.set_key_capture_widget]. This widget will typically be the top-level window, or a parent container of the search bar. Common shortcuts such as Ctrl+F should be handled as an application action, or through the menu items. You will also need to tell the search bar about which entry you are using as your search entry using [method@Gtk.SearchBar.connect_entry]. ## Creating a search bar The following example shows you how to create a more complex search entry. [A simple example](https://gitlab.gnome.org/GNOME/gtk/tree/main/examples/search-bar.c) # Shortcuts and Gestures `GtkSearchBar` supports the following keyboard shortcuts: - <kbd>Escape</kbd> hides the search bar. # CSS nodes ``` searchbar ╰── revealer ╰── box ├── [child] ╰── [button.close] ``` `GtkSearchBar` has a main CSS node with name searchbar. It has a child node with name revealer that contains a node with name box. The box node contains both the CSS node of the child widget as well as an optional button node which gets the .close style class applied. # Accessibility `GtkSearchBar` uses the [enum@Gtk.AccessibleRole.search] role. Creates a `GtkSearchBar`. You will need to tell it about which widget is going to be your text entry using [method@Gtk.SearchBar.connect_entry]. a new `GtkSearchBar` Connects the `GtkEditable` widget passed as the one to be used in this search bar. The entry should be a descendant of the search bar. Calling this function manually is only required if the entry isn’t the direct child of the search bar (as in our main example). a `GtkSearchBar` a `GtkEditable` Gets the child widget of @bar. the child widget of @bar a `GtkSearchBar` Gets the widget that @bar is capturing key events from. The key capture widget. a `GtkSearchBar` Returns whether the search mode is on or off. whether search mode is toggled on a `GtkSearchBar` Returns whether the close button is shown. whether the close button is shown a `GtkSearchBar` Sets the child widget of @bar. a `GtkSearchBar` the child widget Sets @widget as the widget that @bar will capture key events from. If key events are handled by the search bar, the bar will be shown, and the entry populated with the entered text. Note that despite the name of this function, the events are only 'captured' in the bubble phase, which means that editable child widgets of @widget will receive text input before it gets captured. If that is not desired, you can capture and forward the events yourself with [method@Gtk.EventControllerKey.forward]. a `GtkSearchBar` a `GtkWidget` Switches the search mode on or off. a `GtkSearchBar` the new state of the search mode Shows or hides the close button. Applications that already have a “search” toggle button should not show a close button in their search bar, as it duplicates the role of the toggle button. a `GtkSearchBar` whether the close button will be shown or not The child widget. The key capture widget. Whether the search mode is on and the search bar shown. Whether to show the close button in the search bar. A single-line text entry widget for use as a search entry. The main API for interacting with a `GtkSearchEntry` as entry is the `GtkEditable` interface. <picture> <source srcset="search-entry-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkSearchEntry" src="search-entry.png"> </picture> It will show an inactive symbolic “find” icon when the search entry is empty, and a symbolic “clear” icon when there is text. Clicking on the “clear” icon will empty the search entry. To make filtering appear more reactive, it is a good idea to not react to every change in the entry text immediately, but only after a short delay. To support this, `GtkSearchEntry` emits the [signal@Gtk.SearchEntry::search-changed] signal which can be used instead of the [signal@Gtk.Editable::changed] signal. The [signal@Gtk.SearchEntry::previous-match], [signal@Gtk.SearchEntry::next-match] and [signal@Gtk.SearchEntry::stop-search] signals can be used to implement moving between search results and ending the search. Often, `GtkSearchEntry` will be fed events by means of being placed inside a [class@Gtk.SearchBar]. If that is not the case, you can use [method@Gtk.SearchEntry.set_key_capture_widget] to let it capture key input from another widget. `GtkSearchEntry` provides only minimal API and should be used with the [iface@Gtk.Editable] API. ## Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.SearchEntry::activate] - [signal@Gtk.SearchEntry::next-match] - [signal@Gtk.SearchEntry::previous-match] - [signal@Gtk.SearchEntry::stop-search] ## CSS Nodes ``` entry.search ╰── text ``` `GtkSearchEntry` has a single CSS node with name entry that carries a `.search` style class, and the text node is a child of that. ## Accessibility `GtkSearchEntry` uses the [enum@Gtk.AccessibleRole.search_box] role. Creates a `GtkSearchEntry`. a new `GtkSearchEntry` Gets the input purpose for @entry. The input hints a `GtkSearchEntry` Gets the input purpose of @entry. The input hints a `GtkSearchEntry` Gets the widget that @entry is capturing key events from. The key capture widget. a `GtkSearchEntry` Gets the placeholder text associated with @entry. The placeholder text. a `GtkSearchEntry` Get the delay to be used between the last keypress and the [signal@Gtk.SearchEntry::search-changed] signal being emitted. a delay in milliseconds. a `GtkSearchEntry` Sets the input hints for @entry. a `GtkSearchEntry` the new input hints Sets the input purpose of @entry. a `GtkSearchEntry` the new input purpose Sets @widget as the widget that @entry will capture key events from. Key events are consumed by the search entry to start or continue a search. If the entry is part of a `GtkSearchBar`, it is preferable to call [method@Gtk.SearchBar.set_key_capture_widget] instead, which will reveal the entry in addition to triggering the search entry. Note that despite the name of this function, the events are only 'captured' in the bubble phase, which means that editable child widgets of @widget will receive text input before it gets captured. If that is not desired, you can capture and forward the events yourself with [method@Gtk.EventControllerKey.forward]. a `GtkSearchEntry` a `GtkWidget` Sets the placeholder text associated with @entry. a `GtkSearchEntry` the text to set as a placeholder Set the delay to be used between the last keypress and the [signal@Gtk.SearchEntry::search-changed] signal being emitted. a `GtkSearchEntry` a delay in milliseconds Whether to activate the default widget when Enter is pressed. The hints about input for the `GtkSearchEntry` used to alter the behaviour of input methods. The purpose for the `GtkSearchEntry` input used to alter the behaviour of input methods. The widget that the entry will use to capture key events. Key events are consumed by the search entry to start or continue a search. The text that will be displayed in the `GtkSearchEntry` when it is empty and unfocused. The delay in milliseconds from last keypress to the search changed signal. Emitted when the entry is activated. The keybindings for this signal are all forms of the <kbd>Enter</kbd> key. Emitted when the user initiates a move to the next match for the current search string. This is a [keybinding signal](class.SignalAction.html). Applications should connect to it, to implement moving between matches. The default bindings for this signal is <kbd>Ctrl</kbd>+<kbd>g</kbd>. Emitted when the user initiates a move to the previous match for the current search string. This is a [keybinding signal](class.SignalAction.html). Applications should connect to it, to implement moving between matches. The default bindings for this signal is <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>g</kbd>. Emitted with a delay. The length of the delay can be changed with the [property@Gtk.SearchEntry:search-delay] property. Emitted when the user initiated a search on the entry. Emitted when the user stops a search via keyboard input. This is a [keybinding signal](class.SignalAction.html). Applications should connect to it, to implement hiding the search entry in this case. The default bindings for this signal is <kbd>Escape</kbd>. An interface that adds support for sections to list models. A `GtkSectionModel` groups successive items into so-called sections. List widgets like `GtkListView` and `GtkGridView` then allow displaying section headers for these sections by installing a header factory. Many GTK list models support sections inherently, or they pass through the sections of a model they are wrapping. When the section groupings of a model change, the model will emit the [signal@Gtk.SectionModel::sections-changed] signal by calling the [method@Gtk.SectionModel.sections_changed] function. All sections in the given range then need to be queried again. The [signal@Gio.ListModel::items-changed] signal has the same effect, all sections in that range are invalidated, too. Query the section that covers the given position. The number of items in the section can be computed by `out_end - out_start`. If the position is larger than the number of items, a single range from n_items to G_MAXUINT will be returned. a `GtkSectionModel` the position of the item to query the position of the first item in the section the position of the first item not part of the section anymore. Query the section that covers the given position. The number of items in the section can be computed by `out_end - out_start`. If the position is larger than the number of items, a single range from n_items to G_MAXUINT will be returned. a `GtkSectionModel` the position of the item to query the position of the first item in the section the position of the first item not part of the section anymore. This function emits the [signal@Gtk.SectionModel::sections-changed] signal to notify about changes to sections. It must cover all positions that used to be a section start or that are now a section start. It does not have to cover all positions for which the section has changed. The [signal@Gio.ListModel::items-changed] implies the effect of the [signal@Gtk.SectionModel::sections-changed] signal for all the items it covers. It is recommended that when changes to the items cause section changes in a larger range, that the larger range is included in the emission of the [signal@Gio.ListModel::items-changed] instead of emitting two signals. a `GtkSectionModel` the first changed item the number of changed items Emitted when the start-of-section state of some of the items in @model changes. Note that this signal does not specify the new section state of the items, they need to be queried manually. It is also not necessary for a model to change the section state of any of the items in the section model, though it would be rather useless to emit such a signal. The [signal@Gio.ListModel::items-changed] implies the effect of the [signal@Gtk.SectionModel::sections-changed] signal for all the items it covers. The first item that may have changed number of items with changes The list of virtual functions for the `GtkSectionModel` interface. No function must be implemented, but unless `GtkSectionModel::get_section()` is implemented, the whole model will just be a single section. Return the section that covers the given position. If the position is outside the number of items, returns a single range from n_items to G_MAXUINT a `GtkSectionModel` the position of the item to query the position of the first item in the section the position of the first item not part of the section anymore. A list model that presents the selection from a `GtkSelectionModel`. Creates a new `GtkSelectionFilterModel` that will include the selected items from the underlying selection model. a new `GtkSelectionFilterModel` the selection model to filter Gets the model currently filtered or %NULL if none. The model that gets filtered a `GtkSelectionFilterModel` Sets the model to be filtered. Note that GTK makes no effort to ensure that @model conforms to the item type of @self. It assumes that the caller knows what they are doing and have set up an appropriate filter to ensure that item types match. a `GtkSelectionFilterModel` The model to be filtered The type of items. See [method@Gio.ListModel.get_item_type]. The model being filtered. The number of items. See [method@Gio.ListModel.get_n_items]. Used to control what selections users are allowed to make. No selection is possible. Zero or one element may be selected. Exactly one element is selected. In some circumstances, such as initially or during a search operation, it’s possible for no element to be selected with %GTK_SELECTION_BROWSE. What is really enforced is that the user can’t deselect a currently selected element except by selecting another element. Any number of elements may be selected. The Ctrl key may be used to enlarge the selection, and Shift key to select between the focus and the child pointed to. Some widgets may also allow Click-drag to select a range of elements. An interface that adds support for selection to list models. This support is then used by widgets using list models to add the ability to select and unselect various items. GTK provides default implementations of the most common selection modes such as [class@Gtk.SingleSelection], so you will only need to implement this interface if you want detailed control about how selections should be handled. A `GtkSelectionModel` supports a single boolean per item indicating if an item is selected or not. This can be queried via [method@Gtk.SelectionModel.is_selected]. When the selected state of one or more items changes, the model will emit the [signal@Gtk.SelectionModel::selection-changed] signal by calling the [method@Gtk.SelectionModel.selection_changed] function. The positions given in that signal may have their selection state changed, though that is not a requirement. If new items added to the model via the [signal@Gio.ListModel::items-changed] signal are selected or not is up to the implementation. Note that items added via [signal@Gio.ListModel::items-changed] may already be selected and no [signal@Gtk.SelectionModel::selection-changed] will be emitted for them. So to track which items are selected, it is necessary to listen to both signals. Additionally, the interface can expose functionality to select and unselect items. If these functions are implemented, GTK's list widgets will allow users to select and unselect items. However, `GtkSelectionModel`s are free to only implement them partially or not at all. In that case the widgets will not support the unimplemented operations. When selecting or unselecting is supported by a model, the return values of the selection functions do *not* indicate if selection or unselection happened. They are only meant to indicate complete failure, like when this mode of selecting is not supported by the model. Selections may happen asynchronously, so the only reliable way to find out when an item was selected is to listen to the signals that indicate selection. Gets the set of selected items in a range. This function is an optimization for [method@Gtk.SelectionModel.get_selection] when you are only interested in part of the model's selected state. A common use case is in response to the [signal@Gtk.SelectionModel::selection-changed] signal. A `GtkBitset` that matches the selection state for the given range with all other values being undefined. The bitset must not be modified. a `GtkSelectionModel` start of the queried range number of items in the queried range Checks if the given item is selected. %TRUE if the item is selected a `GtkSelectionModel` the position of the item to query Requests to select all items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items are now selected. a `GtkSelectionModel` Requests to select an item in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the item was selected. a `GtkSelectionModel` the position of the item to select whether previously selected items should be unselected Requests to select a range of items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the range was selected. a `GtkSelectionModel` the first item to select the number of items to select whether previously selected items should be unselected Make selection changes. This is the most advanced selection updating method that allows the most fine-grained control over selection changes. If you can, you should try the simpler versions, as implementations are more likely to implement support for those. Requests that the selection state of all positions set in @mask be updated to the respective value in the @selected bitmask. In pseudocode, it would look something like this: ```c for (i = 0; i < n_items; i++) { // don't change values not in the mask if (!gtk_bitset_contains (mask, i)) continue; if (gtk_bitset_contains (selected, i)) select_item (i); else unselect_item (i); } gtk_selection_model_selection_changed (model, first_changed_item, n_changed_items); ``` @mask and @selected must not be modified. They may refer to the same bitset, which would mean that every item in the set should be selected. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items were updated according to the inputs. a `GtkSelectionModel` bitmask specifying if items should be selected or unselected bitmask specifying which items should be updated Requests to unselect all items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items are now unselected. a `GtkSelectionModel` Requests to unselect an item in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the item was unselected. a `GtkSelectionModel` the position of the item to unselect Requests to unselect a range of items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the range was unselected. a `GtkSelectionModel` the first item to unselect the number of items to unselect Gets the set containing all currently selected items in the model. This function may be slow, so if you are only interested in single item, consider using [method@Gtk.SelectionModel.is_selected] or if you are only interested in a few, consider [method@Gtk.SelectionModel.get_selection_in_range]. a `GtkBitset` containing all the values currently selected in @model. If no items are selected, the bitset is empty. The bitset must not be modified. a `GtkSelectionModel` Gets the set of selected items in a range. This function is an optimization for [method@Gtk.SelectionModel.get_selection] when you are only interested in part of the model's selected state. A common use case is in response to the [signal@Gtk.SelectionModel::selection-changed] signal. A `GtkBitset` that matches the selection state for the given range with all other values being undefined. The bitset must not be modified. a `GtkSelectionModel` start of the queried range number of items in the queried range Checks if the given item is selected. %TRUE if the item is selected a `GtkSelectionModel` the position of the item to query Requests to select all items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items are now selected. a `GtkSelectionModel` Requests to select an item in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the item was selected. a `GtkSelectionModel` the position of the item to select whether previously selected items should be unselected Requests to select a range of items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the range was selected. a `GtkSelectionModel` the first item to select the number of items to select whether previously selected items should be unselected Helper function for implementations of `GtkSelectionModel`. Call this when the selection changes to emit the [signal@Gtk.SelectionModel::selection-changed] signal. a `GtkSelectionModel` the first changed item the number of changed items Make selection changes. This is the most advanced selection updating method that allows the most fine-grained control over selection changes. If you can, you should try the simpler versions, as implementations are more likely to implement support for those. Requests that the selection state of all positions set in @mask be updated to the respective value in the @selected bitmask. In pseudocode, it would look something like this: ```c for (i = 0; i < n_items; i++) { // don't change values not in the mask if (!gtk_bitset_contains (mask, i)) continue; if (gtk_bitset_contains (selected, i)) select_item (i); else unselect_item (i); } gtk_selection_model_selection_changed (model, first_changed_item, n_changed_items); ``` @mask and @selected must not be modified. They may refer to the same bitset, which would mean that every item in the set should be selected. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items were updated according to the inputs. a `GtkSelectionModel` bitmask specifying if items should be selected or unselected bitmask specifying which items should be updated Requests to unselect all items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items are now unselected. a `GtkSelectionModel` Requests to unselect an item in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the item was unselected. a `GtkSelectionModel` the position of the item to unselect Requests to unselect a range of items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the range was unselected. a `GtkSelectionModel` the first item to unselect the number of items to unselect Emitted when the selection state of some of the items in @model changes. Note that this signal does not specify the new selection state of the items, they need to be queried manually. It is also not necessary for a model to change the selection state of any of the items in the selection model, though it would be rather useless to emit such a signal. The first item that may have changed number of items with changes The list of virtual functions for the `GtkSelectionModel` interface. No function must be implemented, but unless `GtkSelectionModel::is_selected()` is implemented, it will not be possible to select items in the set. The model does not need to implement any functions to support either selecting or unselecting items. Of course, if the model does not do that, it means that users cannot select or unselect items in a list widget using the model. All selection functions fall back to `GtkSelectionModel::set_selection()` so it is sufficient to implement just that function for full selection support. Return if the item at the given position is selected. %TRUE if the item is selected a `GtkSelectionModel` the position of the item to query Return a bitset with all currently selected items in the given range. By default, this function will call `GtkSelectionModel::is_selected()` on all items in the given range. A `GtkBitset` that matches the selection state for the given range with all other values being undefined. The bitset must not be modified. a `GtkSelectionModel` start of the queried range number of items in the queried range Select the item in the given position. If the operation is known to fail, return %FALSE. %TRUE if this action was supported and no fallback should be tried. This does not mean the item was selected. a `GtkSelectionModel` the position of the item to select whether previously selected items should be unselected Unselect the item in the given position. If the operation is known to fail, return %FALSE. %TRUE if this action was supported and no fallback should be tried. This does not mean the item was unselected. a `GtkSelectionModel` the position of the item to unselect Select all items in the given range. If the operation is unsupported or known to fail for all items, return %FALSE. %TRUE if this action was supported and no fallback should be tried. This does not mean the range was selected. a `GtkSelectionModel` the first item to select the number of items to select whether previously selected items should be unselected Unselect all items in the given range. If the operation is unsupported or known to fail for all items, return %FALSE. %TRUE if this action was supported and no fallback should be tried. This does not mean the range was unselected. a `GtkSelectionModel` the first item to unselect the number of items to unselect Select all items in the model. If the operation is unsupported or known to fail for all items, return %FALSE. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items are now selected. a `GtkSelectionModel` Unselect all items in the model. If the operation is unsupported or known to fail for all items, return %FALSE. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items are now unselected. a `GtkSelectionModel` Set selection state of all items in mask to selected. See gtk_selection_model_set_selection() for a detailed explanation of this function. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items were updated according to the inputs. a `GtkSelectionModel` bitmask specifying if items should be selected or unselected bitmask specifying which items should be updated Determines how GTK handles the sensitivity of various controls, such as combo box buttons. The control is made insensitive if no action can be triggered The control is always sensitive The control is always insensitive Draws a horizontal or vertical line to separate other widgets. <picture> <source srcset="separator-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkSeparator" src="separator.png"> </picture> A `GtkSeparator` can be used to group the widgets within a window. It displays a line with a shadow to make it appear sunken into the interface. # CSS nodes `GtkSeparator` has a single CSS node with name separator. The node gets one of the .horizontal or .vertical style classes. # Accessibility `GtkSeparator` uses the [enum@Gtk.AccessibleRole.separator] role. Creates a new `GtkSeparator` with the given orientation. a new `GtkSeparator`. the separator’s orientation. Provides a mechanism to share global settings between applications. GTK relies on the platform-specific API for getting desktop-wide settings. On Wayland, the settings are obtained via a settings portal that is part of the Linux desktop APIs for application. On the X window system, this sharing is realized by an [XSettings](http://www.freedesktop.org/wiki/Specifications/xsettings-spec) manager. On macOS, the settings are obtained from `NSUserDefaults`. In the absence of these sharing mechanisms, GTK reads default values for settings from `settings.ini` files in `/etc/gtk-4.0`, `$XDG_CONFIG_DIRS/gtk-4.0` and `$XDG_CONFIG_HOME/gtk-4.0`. These files must be valid key files (see `GKeyFile`), and have a section called Settings. Themes can also provide default values for settings by installing a `settings.ini` file next to their `gtk.css` file. Applications can override system-wide settings by setting the property of the `GtkSettings` object with g_object_set(). This should be restricted to special cases though; `GtkSettings` are not meant as an application configuration facility. There is one `GtkSettings` instance per display. It can be obtained with [func@Gtk.Settings.get_for_display], but in many cases, it is more convenient to use [method@Gtk.Widget.get_settings]. Gets the `GtkSettings` object for the default display, creating it if necessary. See [func@Gtk.Settings.get_for_display]. a `GtkSettings` object. If there is no default display, then returns %NULL. Gets the `GtkSettings` object for @display, creating it if necessary. a `GtkSettings` object a `GdkDisplay` Undoes the effect of calling g_object_set() to install an application-specific value for a setting. After this call, the setting will again follow the session-wide value for this setting. a `GtkSettings` object the name of the setting to reset Whether buttons in dialogs should use the alternative button order. Controls the direction of the sort indicators in sorted list and tree views. By default an arrow pointing down means the column is sorted in ascending order. When set to %TRUE, this order will be inverted. Whether the application prefers to use a dark theme. If a GTK theme includes a dark variant, it will be used instead of the configured theme. Some applications benefit from minimizing the amount of light pollution that interferes with the content. Good candidates for dark themes are photo and video editors that make the actual content get all the attention and minimize the distraction of the chrome. Dark themes should not be used for documents, where large spaces are white/light and the dark chrome creates too much contrast (web browser, text editor...). Use `GtkCssProvider` properties instead The aspect ratio of the text caret. Whether the cursor should blink. Also see the [property@Gtk.Settings:gtk-cursor-blink-timeout] setting, which allows more flexible control over cursor blinking. Length of the cursor blink cycle, in milliseconds. Time after which the cursor stops blinking, in seconds. The timer is reset after each user interaction. Setting this to zero has the same effect as setting [property@Gtk.Settings:gtk-cursor-blink] to %FALSE. Name of the cursor theme to use. Use %NULL to use the default theme. The size to use for cursors. 0 means to use the default size. Determines which buttons should be put in the titlebar of client-side decorated windows, and whether they should be placed on the left or right. The format of the string is button names, separated by commas. A colon separates the buttons that should appear on the left from those on the right. Recognized button names are minimize, maximize, close, icon (the window icon) and menu (a menu button for the fallback app menu). For example, "menu:minimize,maximize,close" specifies a menu on the left, and minimize, maximize and close buttons on the right. Note that buttons will only be shown when they are meaningful. E.g. a menu button only appears when the desktop shell does not show the app menu, and a close button only appears on a window that can be closed. Also note that the setting can be overridden with the [property@Gtk.HeaderBar:decoration-layout] property. Whether builtin GTK dialogs such as the file chooser, the color chooser or the font chooser will use a header bar at the top to show action widgets, or an action area at the bottom. This setting does not affect custom dialogs using `GtkDialog` directly, or message dialogs. The number of pixels the cursor can move before dragging. The maximum distance allowed between two clicks for them to be considered a double click, in pixels. The maximum time to allow between two clicks for them to be considered a double click, in milliseconds. Whether menu items should have visible accelerators which can be activated. Whether to enable toolkit-wide animations. Whether to play any event sounds at all. See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec) for more information on event sounds and sound themes. GTK itself does not support event sounds, you have to use a loadable module like the one that comes with libcanberra. Whether to play event sounds as feedback to user input. See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec) for more information on event sounds and sound themes. GTK itself does not support event sounds, you have to use a loadable module like the one that comes with libcanberra. Whether a middle click on a mouse should paste the 'PRIMARY' clipboard content at the cursor location. How long to show the last input character in hidden entries. This value is in milliseconds. 0 disables showing the last char. 600 is a good value for enabling it. Whether to select the contents of an entry when it is focused. When %TRUE, keyboard navigation and other input-related errors will cause a beep. Since the error bell is implemented using gdk_surface_beep(), the windowing system may offer ways to configure the error bell in many ways, such as flashing the window or similar visual effects. The default font to use. GTK uses the family name and size from this string. How GTK font rendering is set up. When set to [enum@Gtk.FontRendering.MANUAL], GTK respects the low-level font-related settings ([property@Gtk.Settings:gtk-hint-font-metrics], [property@Gtk.Settings:gtk-xft-antialias], [property@Gtk.Settings:gtk-xft-hinting], [property@Gtk.Settings:gtk-xft-hintstyle] and [property@Gtk.Settings:gtk-xft-rgba]) as much as practical. When set to [enum@Gtk.FontRendering.AUTOMATIC], GTK will consider factors such as screen resolution and scale in deciding how to render fonts. Timestamp of the current fontconfig configuration. Whether hinting should be applied to font metrics. Note that this also turns off subpixel positioning of glyphs, since it conflicts with metrics hinting. Name of the icon theme to use. See [class@Gtk.IconTheme] for details about how GTK handles icon themes. Which IM (input method) module should be used by default. This is the input method that will be used if the user has not explicitly chosen another input method from the IM context menu. This also can be a colon-separated list of input methods, which GTK will try in turn until it finds one available on the system. See [class@Gtk.IMContext]. The color scheme used for rendering the user interface. This setting communicates the system-wide preference. The color scheme that is actually used when applying CSS styles can be set with the [property@Gtk.CssProvider:prefers-color-scheme] property. The level of contrast to use for the user interface. This setting communicates the system-wide preference. The contrast level that is actually used when applying CSS styles can be set with the [property@Gtk.CssProvider:prefers-contrast] property. Whether animations should be reduced to essential motions. This setting communicates the system-wide preference. The motion level that is actually used when applying CSS styles can be set with the [property@Gtk.CssProvider:prefers-reduced-motion] property. Whether GTK should make sure that text can be navigated with a caret, even if it is not editable. This is useful when using a screen reader. Whether to select the contents of a selectable label when it is focused. The time for a button or touch press to be considered a “long press”. See [class@Gtk.GestureLongPress]. Whether scrolled windows may use overlaid scrolling indicators. If this is set to %FALSE, scrolled windows will have permanent scrollbars. If the value of this setting is %TRUE, clicking the primary button in a `GtkRange` trough will move the slider, and hence set the range’s value, to the point that you clicked. If it is %FALSE, a primary click will cause the slider/value to move by the range’s page-size towards the point clicked. Whichever action you choose for the primary button, the other action will be available by holding Shift and primary-clicking, or clicking the middle mouse button. A comma-separated list of print backends to use in the print dialog. Available print backends depend on the GTK installation, and may include "file", "cups", "lpr" or "papi". A command to run for displaying the print preview. The command should contain a `%f` placeholder, which will get replaced by the path to the pdf file. The command may also contain a `%s` placeholder, which will get replaced by the path to a file containing the print settings in the format produced by [method@Gtk.PrintSettings.to_file]. The preview application is responsible for removing the pdf file and the print settings file when it is done. Whether GTK should keep track of items inside the recently used resources list. If set to %FALSE, the list will always be empty. The maximum age, in days, of the items inside the recently used resources list. Items older than this setting will be excised from the list. If set to 0, the list will always be empty; if set to -1, no item will be removed. Set to %TRUE if the desktop environment is displaying the app menu, %FALSE if the app should display it itself. This setting is not relevant anymore Set to %TRUE if the desktop environment is displaying the desktop folder, %FALSE if not. This setting is not relevant anymore Set to %TRUE if the desktop environment is displaying the menubar, %FALSE if the app should display it itself. This setting is not relevant anymore When %TRUE, widgets like switches include shapes to indicate their on/off state. The XDG sound theme to use for event sounds. See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec) for more information on event sounds and sound themes. GTK itself does not support event sounds, you have to use a loadable module like the one that comes with libcanberra. Whether two cursors should be displayed for mixed left-to-right and right-to-left text. Name of the theme to load. See [class@Gtk.CssProvider] for details about how GTK finds the CSS stylesheet for a theme. Determines the action to take when a double-click occurs on the titlebar of client-side decorated windows. Recognized actions are minimize, toggle-maximize, menu, lower or none. Determines the action to take when a middle-click occurs on the titlebar of client-side decorated windows. Recognized actions are minimize, toggle-maximize, menu, lower or none. Determines the action to take when a right-click occurs on the titlebar of client-side decorated windows. Recognized actions are minimize, toggle-maximize, menu, lower or none. Whether to antialias fonts. The values are 0 for no, 1 for yes, or -1 for the system default. The font resolution, in 1024 * dots/inch. -1 to use the default value. Whether to enable font hinting. The values are 0 for no, 1 for yes, or -1 for the system default. What degree of font hinting to use. The possible vaues are hintnone, hintslight, hintmedium, hintfull. The type of subpixel antialiasing to use. The possible values are none, rgb, bgr, vrgb, vbgr. Note that GSK does not support subpixel antialiasing, and this setting has no effect on font rendering in GTK. Describes a keyboard shortcut. It contains a description of how to trigger the shortcut via a [class@Gtk.ShortcutTrigger] and a way to activate the shortcut on a widget via a [class@Gtk.ShortcutAction]. The actual work is usually done via [class@Gtk.ShortcutController], which decides if and when to activate a shortcut. Using that controller directly however is rarely necessary as various higher level convenience APIs exist on `GtkWidget`s that make it easier to use shortcuts in GTK. `GtkShortcut` does provide functionality to make it easy for users to work with shortcuts, either by providing informational strings for display purposes or by allowing shortcuts to be configured. Creates a new `GtkShortcut` that is triggered by @trigger and then activates @action. a new `GtkShortcut` The trigger that will trigger the shortcut The action that will be activated upon triggering Creates a new `GtkShortcut` that is triggered by @trigger and then activates @action with arguments given by @format_string. a new `GtkShortcut` The trigger that will trigger the shortcut The action that will be activated upon triggering GVariant format string for arguments or %NULL for no arguments arguments, as given by format string. Gets the action that is activated by this shortcut. the action a `GtkShortcut` Gets the arguments that are passed when activating the shortcut. the arguments a `GtkShortcut` Gets the trigger used to trigger @self. the trigger used a `GtkShortcut` Sets the new action for @self to be @action. a `GtkShortcut` The new action. If the @action is %NULL, the nothing action will be used. Sets the arguments to pass when activating the shortcut. a `GtkShortcut` arguments to pass when activating @self Sets the new trigger for @self to be @trigger. a `GtkShortcut` The new trigger. If the @trigger is %NULL, the never trigger will be used. The action that gets activated by this shortcut. Arguments passed to activation. The trigger that triggers this shortcut. Encodes an action that can be triggered by a keyboard shortcut. `GtkShortcutActions` contain functions that allow easy presentation to end users as well as being printed for debugging. All `GtkShortcutActions` are immutable, you can only specify their properties during construction. If you want to change a action, you have to replace it with a new one. If you need to pass arguments to an action, these are specified by the higher-level `GtkShortcut` object. To activate a `GtkShortcutAction` manually, [method@Gtk.ShortcutAction.activate] can be called. GTK provides various actions: - [class@Gtk.MnemonicAction]: a shortcut action that calls gtk_widget_mnemonic_activate() - [class@Gtk.CallbackAction]: a shortcut action that invokes a given callback - [class@Gtk.SignalAction]: a shortcut action that emits a given signal - [class@Gtk.ActivateAction]: a shortcut action that calls gtk_widget_activate() - [class@Gtk.NamedAction]: a shortcut action that calls gtk_widget_activate_action() - [class@Gtk.NothingAction]: a shortcut action that does nothing Tries to parse the given string into an action. On success, the parsed action is returned. When parsing failed, %NULL is returned. The accepted strings are: - `nothing`, for `GtkNothingAction` - `activate`, for `GtkActivateAction` - `mnemonic-activate`, for `GtkMnemonicAction` - `action(NAME)`, for a `GtkNamedAction` for the action named `NAME` - `signal(NAME)`, for a `GtkSignalAction` for the signal `NAME` a new `GtkShortcutAction` the string to parse Activates the action on the @widget with the given @args. Note that some actions ignore the passed in @flags, @widget or @args. Activation of an action can fail for various reasons. If the action is not supported by the @widget, if the @args don't match the action or if the activation otherwise had no effect, %FALSE will be returned. %TRUE if this action was activated successfully a `GtkShortcutAction` flags to activate with Target of the activation arguments to pass Prints the given action into a string for the developer. This is meant for debugging and logging. The form of the representation may change at any time and is not guaranteed to stay identical. a `GtkShortcutAction` a `GString` to print into Prints the given action into a human-readable string. This is a small wrapper around [method@Gtk.ShortcutAction.print] to help when debugging. a new string a `GtkShortcutAction` Flags that can be passed to action activation. More flags may be added in the future. The action is the only action that can be activated. If this flag is not set, a future activation may select a different action. Manages keyboard shortcuts and their activation. Most common shortcuts are using this controller implicitly, e.g. by adding a mnemonic underline to a [class@Gtk.Label], or by installing a key binding using [method@Gtk.WidgetClass.add_binding], or by adding accelerators to global actions using [method@Gtk.Application.set_accels_for_action]. But it is possible to create your own shortcut controller, and add shortcuts to it. `GtkShortcutController` implements [iface@Gio.ListModel] for querying the shortcuts that have been added to it. # GtkShortcutController as GtkBuildable `GtkShortcutController`s can be created in [class@Gtk.Builder] ui files, to set up shortcuts in the same place as the widgets. An example of a UI definition fragment with `GtkShortcutController`: ```xml <object class='GtkButton'> <child> <object class='GtkShortcutController'> <property name='scope'>managed</property> <child> <object class='GtkShortcut'> <property name='trigger'>&lt;Control&gt;k</property> <property name='action'>activate</property> </object> </child> </object> </child> </object> ``` This example creates a [class@Gtk.ActivateAction] for triggering the `activate` signal of the [class@Gtk.Button]. See [ctor@Gtk.ShortcutAction.parse_string] for the syntax for other kinds of [class@Gtk.ShortcutAction]. See [ctor@Gtk.ShortcutTrigger.parse_string] to learn more about the syntax for triggers. Creates a new shortcut controller. a newly created shortcut controller Creates a new shortcut controller that takes its shortcuts from the given list model. A controller created by this function does not let you add or remove individual shortcuts using the shortcut controller api, but you can change the contents of the model. a newly created shortcut controller a `GListModel` containing shortcuts Adds @shortcut to the list of shortcuts handled by @self. If this controller uses an external shortcut list, this function does nothing. the controller a `GtkShortcut` Gets the mnemonics modifiers for when this controller activates its shortcuts. the controller's mnemonics modifiers a `GtkShortcutController` Gets the scope for when this controller activates its shortcuts. See [method@Gtk.ShortcutController.set_scope] for details. the controller's scope a `GtkShortcutController` Removes @shortcut from the list of shortcuts handled by @self. If @shortcut had not been added to @controller or this controller uses an external shortcut list, this function does nothing. the controller a `GtkShortcut` Sets the controller to use the given modifier for mnemonics. The mnemonics modifiers determines which modifiers need to be pressed to allow activation of shortcuts with mnemonics triggers. GTK normally uses the Alt modifier for mnemonics, except in `GtkPopoverMenu`s, where mnemonics can be triggered without any modifiers. It should be very rarely necessary to change this, and doing so is likely to interfere with other shortcuts. This value is only relevant for local shortcut controllers. Global and managed shortcut controllers will have their shortcuts activated from other places which have their own modifiers for activating mnemonics. a `GtkShortcutController` the new mnemonics_modifiers to use Sets the controller to have the given @scope. The scope allows shortcuts to be activated outside of the normal event propagation. In particular, it allows installing global keyboard shortcuts that can be activated even when a widget does not have focus. With %GTK_SHORTCUT_SCOPE_LOCAL, shortcuts will only be activated when the widget has focus. a `GtkShortcutController` the new scope to use The type of items. See [method@Gio.ListModel.get_item_type]. The modifiers that need to be pressed to allow mnemonics activation. A list model to take shortcuts from. The number of items. See [method@Gio.ListModel.get_n_items]. What scope the shortcuts will be handled in. Type for shortcuts based on user callbacks. true if the action was successful The widget passed to the activation The arguments passed to the activation The user data provided when activating the action `GtkShortcutLabel` displays a single keyboard shortcut or gesture. The main use case for `GtkShortcutLabel` is inside a [class@Gtk.ShortcutsWindow]. This widget will be removed in GTK 5 Creates a new `GtkShortcutLabel` with @accelerator set. This widget will be removed in GTK 5 a newly-allocated `GtkShortcutLabel` the initial accelerator Retrieves the current accelerator of @self. This widget will be removed in GTK 5 the current accelerator. a `GtkShortcutLabel` Retrieves the text that is displayed when no accelerator is set. This widget will be removed in GTK 5 the current text displayed when no accelerator is set. a `GtkShortcutLabel` Sets the accelerator to be displayed by @self. This widget will be removed in GTK 5 a `GtkShortcutLabel` the new accelerator Sets the text to be displayed by @self when no accelerator is set. This widget will be removed in GTK 5 a `GtkShortcutLabel` the text to be displayed when no accelerator is set The accelerator that @self displays. See [property@Gtk.ShortcutsShortcut:accelerator] for the accepted syntax. This widget will be removed in GTK 5 The text that is displayed when no accelerator is set. This widget will be removed in GTK 5 An interface that is used to implement shortcut scopes. This is important for [iface@Gtk.Native] widgets that have their own surface, since the event controllers that are used to implement managed and global scopes are limited to the same native. Examples for widgets implementing `GtkShortcutManager` are [class@Gtk.Window] and [class@Gtk.Popover]. Every widget that implements `GtkShortcutManager` will be used as a `GTK_SHORTCUT_SCOPE_MANAGED`. Add a `GtkShortcutController` to be managed. Remove a `GtkShortcutController` that had previously been added The list of functions that can be implemented for the `GtkShortcutManager` interface. Note that no function is mandatory to implement, the default implementation will work fine. Add a `GtkShortcutController` to be managed. Remove a `GtkShortcutController` that had previously been added Describes where [class@Shortcut]s added to a [class@ShortcutController] get handled. Shortcuts are handled inside the widget the controller belongs to. Shortcuts are handled by the first ancestor that is a [iface@ShortcutManager] Shortcuts are handled by the root widget. Tracks how a `GtkShortcut` can be activated. To find out if a `GtkShortcutTrigger` triggers, you can call [method@Gtk.ShortcutTrigger.trigger] on a `GdkEvent`. `GtkShortcutTriggers` contain functions that allow easy presentation to end users as well as being printed for debugging. All `GtkShortcutTriggers` are immutable, you can only specify their properties during construction. If you want to change a trigger, you have to replace it with a new one. Tries to parse the given string into a trigger. On success, the parsed trigger is returned. When parsing failed, %NULL is returned. The accepted strings are: - `never`, for `GtkNeverTrigger` - a string parsed by gtk_accelerator_parse(), for a `GtkKeyvalTrigger`, e.g. `<Control>C` - underscore, followed by a single character, for `GtkMnemonicTrigger`, e.g. `_l` - two valid trigger strings, separated by a `|` character, for a `GtkAlternativeTrigger`: `<Control>q|<Control>w` Note that you will have to escape the `<` and `>` characters when specifying triggers in XML files, such as GtkBuilder ui files. Use `&lt;` instead of `<` and `&gt;` instead of `>`. a new `GtkShortcutTrigger` the string to parse The types of @trigger1 and @trigger2 are `gconstpointer` only to allow use of this function as a `GCompareFunc`. They must each be a `GtkShortcutTrigger`. An integer less than, equal to, or greater than zero if @trigger1 is found, respectively, to be less than, to match, or be greater than @trigger2. a `GtkShortcutTrigger` a `GtkShortcutTrigger` Checks if @trigger1 and @trigger2 trigger under the same conditions. The types of @one and @two are `gconstpointer` only to allow use of this function with `GHashTable`. They must each be a `GtkShortcutTrigger`. %TRUE if @trigger1 and @trigger2 are equal a `GtkShortcutTrigger` a `GtkShortcutTrigger` Generates a hash value for a `GtkShortcutTrigger`. The output of this function is guaranteed to be the same for a given value only per-process. It may change between different processor architectures or even different versions of GTK. Do not use this function as a basis for building protocols or file formats. The types of @trigger is `gconstpointer` only to allow use of this function with `GHashTable`. They must each be a `GtkShortcutTrigger`. a hash value corresponding to @trigger a `GtkShortcutTrigger` Prints the given trigger into a string for the developer. This is meant for debugging and logging. The form of the representation may change at any time and is not guaranteed to stay identical. a `GtkShortcutTrigger` a `GString` to print into Prints the given trigger into a string. This function is returning a translated string for presentation to end users for example in menu items or in help texts. The @display in use may influence the resulting string in various forms, such as resolving hardware keycodes or by causing display-specific modifier names. The form of the representation may change at any time and is not guaranteed to stay identical. %TRUE if something was printed or %FALSE if the trigger did not have a textual representation suitable for end users. a `GtkShortcutTrigger` `GdkDisplay` to print for a `GString` to print into Gets textual representation for the given trigger. This function is returning a translated string for presentation to end users for example in menu items or in help texts. The @display in use may influence the resulting string in various forms, such as resolving hardware keycodes or by causing display-specific modifier names. The form of the representation may change at any time and is not guaranteed to stay identical. a new string a `GtkShortcutTrigger` `GdkDisplay` to print for Prints the given trigger into a human-readable string. This is a small wrapper around [method@Gtk.ShortcutTrigger.print] to help when debugging. a new string a `GtkShortcutTrigger` Checks if the given @event triggers @self. Whether the event triggered the shortcut a `GtkShortcutTrigger` the event to check %TRUE if mnemonics should trigger. Usually the value of this property is determined by checking that the passed in @event is a Key event and has the right modifiers set. GtkShortcutType specifies the kind of shortcut that is being described. More values may be added to this enumeration over time. The shortcut is a keyboard accelerator. The GtkShortcutsShortcut:accelerator property will be used. The shortcut is a pinch gesture. GTK provides an icon and subtitle. The shortcut is a stretch gesture. GTK provides an icon and subtitle. The shortcut is a clockwise rotation gesture. GTK provides an icon and subtitle. The shortcut is a counterclockwise rotation gesture. GTK provides an icon and subtitle. The shortcut is a two-finger swipe gesture. GTK provides an icon and subtitle. The shortcut is a two-finger swipe gesture. GTK provides an icon and subtitle. The shortcut is a gesture. The GtkShortcutsShortcut:icon property will be used. The shortcut is a swipe gesture. GTK provides an icon and subtitle. The shortcut is a swipe gesture. GTK provides an icon and subtitle. A `GtkShortcutsGroup` represents a group of related keyboard shortcuts or gestures. The group has a title. It may optionally be associated with a view of the application, which can be used to show only relevant shortcuts depending on the application context. This widget is only meant to be used with [class@Gtk.ShortcutsWindow]. The recommended way to construct a `GtkShortcutsGroup` is with [class@Gtk.Builder], by using the `<child>` tag to populate a `GtkShortcutsGroup` with one or more [class@Gtk.ShortcutsShortcut] instances. If you need to add a shortcut programmatically, use [method@Gtk.ShortcutsGroup.add_shortcut]. This widget will be removed in GTK 5 Adds a shortcut to the shortcuts group. This is the programmatic equivalent to using [class@Gtk.Builder] and a `<child>` tag to add the child. Adding children with other API is not appropriate as `GtkShortcutsGroup` manages its children internally. This widget will be removed in GTK 5 a `GtkShortcutsGroup` the `GtkShortcutsShortcut` to add The size group for the accelerator portion of shortcuts in this group. This is used internally by GTK, and must not be modified by applications. This widget will be removed in GTK 5 A rough measure for the number of lines in this group. This is used internally by GTK, and is not useful for applications. This widget will be removed in GTK 5 The title for this group of shortcuts. This widget will be removed in GTK 5 The size group for the textual portion of shortcuts in this group. This is used internally by GTK, and must not be modified by applications. This widget will be removed in GTK 5 An optional view that the shortcuts in this group are relevant for. The group will be hidden if the [property@Gtk.ShortcutsWindow:view-name] property does not match the view of this group. Set this to %NULL to make the group always visible. This widget will be removed in GTK 5 A `GtkShortcutsSection` collects all the keyboard shortcuts and gestures for a major application mode. If your application needs multiple sections, you should give each section a unique [property@Gtk.ShortcutsSection:section-name] and a [property@Gtk.ShortcutsSection:title] that can be shown in the section selector of the [class@Gtk.ShortcutsWindow]. The [property@Gtk.ShortcutsSection:max-height] property can be used to influence how the groups in the section are distributed over pages and columns. This widget is only meant to be used with [class@Gtk.ShortcutsWindow]. The recommended way to construct a `GtkShortcutsSection` is with [class@Gtk.Builder], by using the `<child>` tag to populate a `GtkShortcutsSection` with one or more [class@Gtk.ShortcutsGroup] instances, which in turn contain one or more [class@Gtk.ShortcutsShortcut] objects. If you need to add a group programmatically, use [method@Gtk.ShortcutsSection.add_group]. # Shortcuts and Gestures Pan gestures allow to navigate between sections. The following signals have default keybindings: - [signal@Gtk.ShortcutsSection::change-current-page] This widget will be removed in GTK 5 Adds a group to the shortcuts section. This is the programmatic equivalent to using [class@Gtk.Builder] and a `<child>` tag to add the child. Adding children with the `GtkBox` API is not appropriate, as `GtkShortcutsSection` manages its children internally. This widget will be removed in GTK 5 a `GtkShortcutsSection` the `GtkShortcutsGroup` to add The maximum number of lines to allow per column. This property can be used to influence how the groups in this section are distributed across pages and columns. The default value of 15 should work in most cases. This widget will be removed in GTK 5 A unique name to identify this section among the sections added to the `GtkShortcutsWindow`. Setting the [property@Gtk.ShortcutsWindow:section-name] property to this string will make this section shown in the `GtkShortcutsWindow`. This widget will be removed in GTK 5 The string to show in the section selector of the `GtkShortcutsWindow` for this section. If there is only one section, you don't need to set a title, since the section selector will not be shown in this case. This widget will be removed in GTK 5 A view name to filter the groups in this section by. See [property@Gtk.ShortcutsGroup:view]. Applications are expected to use the [property@Gtk.ShortcutsWindow:view-name] property for this purpose. This widget will be removed in GTK 5 Emitted when we change the current page. The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>PgUp</kbd>, <kbd>PgUp</kbd>, <kbd>Ctrl</kbd>+<kbd>PgDn</kbd>, <kbd>PgDn</kbd>. This widget will be removed in GTK 5 whether the page was changed the offset A `GtkShortcutsShortcut` represents a single keyboard shortcut or gesture with a short text. This widget is only meant to be used with `GtkShortcutsWindow`. This widget will be removed in GTK 5 The size group for the accelerator portion of this shortcut. This is used internally by GTK, and must not be modified by applications. This widget will be removed in GTK 5 The accelerator(s) represented by this object. This property is used if [property@Gtk.ShortcutsShortcut:shortcut-type] is set to %GTK_SHORTCUT_ACCELERATOR. The syntax of this property is (an extension of) the syntax understood by [func@Gtk.accelerator_parse]. Multiple accelerators can be specified by separating them with a space, but keep in mind that the available width is limited. It is also possible to specify ranges of shortcuts, using `...` between the keys. Sequences of keys can be specified using a `+` or `&` between the keys. Examples: - A single shortcut: `<ctl><alt>delete` - Two alternative shortcuts: `<shift>a Home` - A range of shortcuts: `<alt>1...<alt>9` - Several keys pressed together: `Control_L&Control_R` - A sequence of shortcuts or keys: `<ctl>c+<ctl>x` Use "+" instead of "&" when the keys may (or have to be) pressed sequentially (e.g use "t+t" for 'press the t key twice'). Note that `<`, `>` and `&` need to be escaped as `&lt;`, `&gt`; and `&amp`; when used in .ui files. This widget will be removed in GTK 5 A detailed action name. If this is set for a shortcut of type %GTK_SHORTCUT_ACCELERATOR, then GTK will use the accelerators that are associated with the action via [method@Gtk.Application.set_accels_for_action], and setting [property@Gtk.ShortcutsShortcut:accelerator] is not necessary. This widget will be removed in GTK 5 The text direction for which this shortcut is active. If the shortcut is used regardless of the text direction, set this property to %GTK_TEXT_DIR_NONE. This widget will be removed in GTK 5 An icon to represent the shortcut or gesture. This property is used if [property@Gtk.ShortcutsShortcut:shortcut-type] is set to %GTK_SHORTCUT_GESTURE. For the other predefined gesture types, GTK provides an icon on its own. This widget will be removed in GTK 5 %TRUE if an icon has been set. This widget will be removed in GTK 5 The type of shortcut that is represented. This widget will be removed in GTK 5 The subtitle for the shortcut or gesture. This is typically used for gestures and should be a short, one-line text that describes the gesture itself. For the predefined gesture types, GTK provides a subtitle on its own. This widget will be removed in GTK 5 %TRUE if a subtitle has been set. This widget will be removed in GTK 5 The textual description for the shortcut or gesture represented by this object. This should be a short string that can fit in a single line. This widget will be removed in GTK 5 The size group for the textual portion of this shortcut. This is used internally by GTK, and must not be modified by applications. This widget will be removed in GTK 5 A `GtkShortcutsWindow` shows information about the keyboard shortcuts and gestures of an application. The shortcuts can be grouped, and you can have multiple sections in this window, corresponding to the major modes of your application. Additionally, the shortcuts can be filtered by the current view, to avoid showing information that is not relevant in the current application context. The recommended way to construct a `GtkShortcutsWindow` is with [class@Gtk.Builder], by using the `<child>` tag to populate a `GtkShortcutsWindow` with one or more [class@Gtk.ShortcutsSection] objects, which contain one or more [class@Gtk.ShortcutsGroup] instances, which, in turn, contain [class@Gtk.ShortcutsShortcut] instances. If you need to add a section programmatically, use [method@Gtk.ShortcutsWindow.add_section] instead of [method@Gtk.Window.set_child], as the shortcuts window manages its children directly. # A simple example: <picture> <source srcset="gedit-shortcuts-dark.png" media="(prefers-color-scheme: dark)"> <img alt="A simple example" src="gedit-shortcuts.png"> </picture> This example has as single section. As you can see, the shortcut groups are arranged in columns, and spread across several pages if there are too many to find on a single page. The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/main/demos/gtk-demo/shortcuts-gedit.ui). # An example with multiple views: <picture> <source srcset="clocks-shortcuts-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example with multiple views" src="clocks-shortcuts.png"> </picture> This example shows a `GtkShortcutsWindow` that has been configured to show only the shortcuts relevant to the “Stopwatch” view. The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/main/demos/gtk-demo/shortcuts-clocks.ui). # An example with multiple sections: <picture> <source srcset="builder-shortcuts-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example with multiple sections" src="builder-shortcuts.png"> </picture> This example shows a `GtkShortcutsWindow` with two sections, “Editor Shortcuts” and “Terminal Shortcuts”. The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/main/demos/gtk-demo/shortcuts-builder.ui). # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.ShortcutsWindow::close] - [signal@Gtk.ShortcutsWindow::search] # CSS nodes `GtkShortcutsWindow` has a single CSS node with the name `window` and style class `.shortcuts`. This widget will be removed in GTK 5 Adds a section to the shortcuts window. This is the programmatic equivalent to using [class@Gtk.Builder] and a `<child>` tag to add the child. Using [method@Gtk.Window.set_child] is not appropriate as the shortcuts window manages its children internally. This widget will be removed in GTK 5 a `GtkShortcutsWindow` the `GtkShortcutsSection` to add The name of the section to show. This should be the section-name of one of the `GtkShortcutsSection` objects that are in this shortcuts window. This widget will be removed in GTK 5 The view name by which to filter the contents. This should correspond to the [property@Gtk.ShortcutsGroup:view] property of some of the [class@Gtk.ShortcutsGroup] objects that are inside this shortcuts window. Set this to %NULL to show all groups. This widget will be removed in GTK 5 Emitted when the user uses a keybinding to close the window. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is the <kbd>Escape</kbd> key. This widget will be removed in GTK 5 Emitted when the user uses a keybinding to start a search. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Control</kbd>+<kbd>F</kbd>. This widget will be removed in GTK 5 Emits a signal on a widget. Signals that are used in this way are referred to as keybinding signals, and they are expected to be defined with the `G_SIGNAL_ACTION` flag. Creates an action that when activated, emits the given action signal on the provided widget. It will also unpack the args into arguments passed to the signal. a new `GtkShortcutAction` name of the signal to emit Returns the name of the signal that will be emitted. the name of the signal to emit a signal action The name of the signal to emit. Emits signals to manage listitems. Signals are emitted for every listitem in the same order: 1. [signal@Gtk.SignalListItemFactory::setup] is emitted to set up permanent things on the listitem. This usually means constructing the widgets used in the row and adding them to the listitem. 2. [signal@Gtk.SignalListItemFactory::bind] is emitted to bind the item passed via [property@Gtk.ListItem:item] to the widgets that have been created in step 1 or to add item-specific widgets. Signals are connected to listen to changes - both to changes in the item to update the widgets or to changes in the widgets to update the item. After this signal has been called, the listitem may be shown in a list widget. 3. [signal@Gtk.SignalListItemFactory::unbind] is emitted to undo everything done in step 2. Usually this means disconnecting signal handlers. Once this signal has been called, the listitem will no longer be used in a list widget. 4. [signal@Gtk.SignalListItemFactory::bind] and [signal@Gtk.SignalListItemFactory::unbind] may be emitted multiple times again to bind the listitem for use with new items. By reusing listitems, potentially costly setup can be avoided. However, it means code needs to make sure to properly clean up the listitem in step 3 so that no information from the previous use leaks into the next one. 5. [signal@Gtk.SignalListItemFactory::teardown] is emitted to allow undoing the effects of [signal@Gtk.SignalListItemFactory::setup]. After this signal was emitted on a listitem, the listitem will be destroyed and not be used again. Note that during the signal emissions, changing properties on the listitems passed will not trigger notify signals as the listitem's notifications are frozen. See [method@GObject.Object.freeze_notify] for details. For tracking changes in other properties in the listitem, the ::notify signal is recommended. The signal can be connected in the [signal@Gtk.SignalListItemFactory::setup] signal and removed again during [signal@Gtk.SignalListItemFactory::teardown]. Creates a new `GtkSignalListItemFactory`. You need to connect signal handlers before you use it. a new `GtkSignalListItemFactory` Emitted when an object has been bound to an item. The handler for this signal must set to populate the listitem with widgets. After this signal was emitted, the object might be shown in a [class@Gtk.ListView] or other widget. The [signal@Gtk.SignalListItemFactory::unbind] signal is the opposite of this signal and can be used to undo everything done in this signal. The `GObject` to bind Emitted when a newly created listitem needs to be prepared for use. It is the first signal emitted for every listitem. The handler for this signal must call [method@Gtk.ListItem.set_child] to populate the listitem with widgets. The [signal@Gtk.SignalListItemFactory::teardown] signal is the opposite of this signal and can be used to undo everything done in this signal. the `GObject` to set up Emitted when an object is about to be destroyed. It is the last signal ever emitted for this @object. This signal is the opposite of the [signal@Gtk.SignalListItemFactory::setup] signal and should be used to undo everything done in that signal. The `GObject` to tear down Emitted when an object has been unbound from its item. This happens for example when a listitem was removed from use in a list widget and its [property@Gtk.ListItem:item] is about to be unset. This signal is the opposite of the [signal@Gtk.SignalListItemFactory::bind] signal and should be used to undo everything done in that signal. The `GObject` to unbind A selection model that allows selecting a single item. Note that the selection is *persistent* -- if the selected item is removed and re-added in the same [signal@Gio.ListModel::items-changed] emission, it stays selected. In particular, this means that changing the sort order of an underlying sort model will preserve the selection. Creates a new selection to handle @model. a new `GtkSingleSelection` the `GListModel` to manage Checks if autoselect has been enabled or disabled via gtk_single_selection_set_autoselect(). %TRUE if autoselect is enabled a `GtkSingleSelection` If %TRUE, gtk_selection_model_unselect_item() is supported and allows unselecting the selected item. %TRUE to support unselecting a `GtkSingleSelection` Gets the model that @self is wrapping. The model being wrapped a `GtkSingleSelection` Gets the position of the selected item. If no item is selected, %GTK_INVALID_LIST_POSITION is returned. The position of the selected item a `GtkSingleSelection` Gets the selected item. If no item is selected, %NULL is returned. The selected item a `GtkSingleSelection` Enables or disables autoselect. If @autoselect is %TRUE, @self will enforce that an item is always selected. It will select a new item when the currently selected item is deleted and it will disallow unselecting the current item. a `GtkSingleSelection` %TRUE to always select an item If %TRUE, unselecting the current item via gtk_selection_model_unselect_item() is supported. Note that setting [property@Gtk.SingleSelection:autoselect] will cause unselecting to not work, so it practically makes no sense to set both at the same time. a `GtkSingleSelection` %TRUE to allow unselecting Sets the model that @self should wrap. If @model is %NULL, @self will be empty. a `GtkSingleSelection` A `GListModel` to wrap Selects the item at the given position. If the list does not have an item at @position or %GTK_INVALID_LIST_POSITION is given, the behavior depends on the value of the [property@Gtk.SingleSelection:autoselect] property: If it is set, no change will occur and the old item will stay selected. If it is unset, the selection will be unset and no item will be selected. This also applies if [property@Gtk.SingleSelection:can-unselect] is set to %FALSE. a `GtkSingleSelection` the item to select or %GTK_INVALID_LIST_POSITION If the selection will always select an item. If unselecting the selected item is allowed. The type of items. See [method@Gio.ListModel.get_item_type]. The model being managed. The number of items. See [method@Gio.ListModel.get_n_items]. Position of the selected item. The selected item. Groups widgets together so they all request the same size. This is typically useful when you want a column of widgets to have the same size, but you can’t use a [class@Gtk.Grid] or [class@Gtk.Box]. In detail, the size requested for each widget in a `GtkSizeGroup` is the maximum of the sizes that would have been requested for each widget in the size group if they were not in the size group. The [mode][method@Gtk.SizeGroup.set_mode] of the size group determines whether this applies to the horizontal size, the vertical size, or both sizes. Note that size groups only affect the amount of space requested, not the size that the widgets finally receive. If you want the widgets in a `GtkSizeGroup` to actually be the same size, you need to pack them in such a way that they get the size they request and not more. In particular it doesn't make a lot of sense to set [the expand flags][method@Gtk.Widget.set_hexpand] on the widgets that are members of a size group. `GtkSizeGroup` objects are referenced by each widget in the size group, so once you have added all widgets to a `GtkSizeGroup`, you can drop the initial reference to the size group with [method@GObject.Object.unref]. If the widgets in the size group are subsequently destroyed, then they will be removed from the size group and drop their references on the size group; when all widgets have been removed, the size group will be freed. Widgets can be part of multiple size groups; GTK will compute the horizontal size of a widget from the horizontal requisition of all widgets that can be reached from the widget by a chain of size groups with mode [enum@Gtk.SizeGroupMode.HORIZONTAL] or [enum@Gtk.SizeGroupMode.BOTH], and the vertical size from the vertical requisition of all widgets that can be reached from the widget by a chain of size groups with mode [enum@Gtk.SizeGroupMode.VERTICAL] or [enum@Gtk.SizeGroupMode.BOTH]. # Size groups and trading height-for-width ::: warning Generally, size groups don't interact well with widgets that trade height for width (or width for height), such as wrappable labels. Avoid using size groups with such widgets. A size group with mode [enum@Gtk.SizeGroupMode.HORIZONTAL] or [enum@Gtk.SizeGroupMode.VERTICAL] only consults non-contextual sizes of widgets other than the one being measured, since it has no knowledge of what size a widget will get allocated in the other orientation. This can lead to widgets in a group actually requesting different contextual sizes, contrary to the purpose of `GtkSizeGroup`. In contrast, a size group with mode [enum@Gtk.SizeGroupMode.BOTH] can properly propagate the available size in the opposite orientation when measuring widgets in the group, which results in consistent and accurate measurements. In case some mechanism other than a size group is already used to ensure that widgets in a group all get the same size in one orientation (for example, some common ancestor is known to allocate the same width to all its children), and the size group is only really needed to also make the widgets request the same size in the other orientation, it is beneficial to still set the group's mode to [enum@Gtk.SizeGroupMode.BOTH]. This lets the group assume and count on sizes of the widgets in the former orientation being the same, which enables it to propagate the available size as described above. # Alternatives to size groups Size groups have many limitations, such as only influencing size requests but not allocations, and poor height-for-width support. When possible, prefer using dedicated mechanisms that can properly ensure that the widgets get the same size. Various container widgets and layout managers support a homogeneous layout mode, where they will explicitly give the same size to their children (see [property@Gtk.Box:homogeneous]). Using homogeneous mode can also have large performance benefits compared to either the same container in non-homogeneous mode, or to size groups. [class@Gtk.Grid] can be used to position widgets into rows and columns. Members of each column will have the same width among them; likewise, members of each row will have the same height. On top of that, the heights can be made equal between all rows with [property@Gtk.Grid:row-homogeneous], and the widths can be made equal between all columns with [property@Gtk.Grid:column-homogeneous]. # GtkSizeGroup as GtkBuildable Size groups can be specified in a UI definition by placing an `<object>` element with `class="GtkSizeGroup"` somewhere in the UI definition. The widgets that belong to the size group are specified by a `<widgets>` element that may contain multiple `<widget>` elements, one for each member of the size group. The ”name” attribute gives the id of the widget. An example of a UI definition fragment with `GtkSizeGroup`: ```xml <object class="GtkSizeGroup"> <property name="mode">horizontal</property> <widgets> <widget name="radio1"/> <widget name="radio2"/> </widgets> </object> ``` Create a new `GtkSizeGroup`. a newly created `GtkSizeGroup` the mode for the new size group. Adds a widget to a `GtkSizeGroup`. In the future, the requisition of the widget will be determined as the maximum of its requisition and the requisition of the other widgets in the size group. Whether this applies horizontally, vertically, or in both directions depends on the mode of the size group. See [method@Gtk.SizeGroup.set_mode]. When the widget is destroyed or no longer referenced elsewhere, it will be removed from the size group. a `GtkSizeGroup` the `GtkWidget` to add Gets the current mode of the size group. the current mode of the size group. a `GtkSizeGroup` Returns the list of widgets associated with @size_group. a `GSList` of widgets. The list is owned by GTK and should not be modified. a `GtkSizeGroup` Removes a widget from a `GtkSizeGroup`. a `GtkSizeGroup` the `GtkWidget` to remove Sets the `GtkSizeGroupMode` of the size group. The mode of the size group determines whether the widgets in the size group should all have the same horizontal requisition (%GTK_SIZE_GROUP_HORIZONTAL) all have the same vertical requisition (%GTK_SIZE_GROUP_VERTICAL), or should all have the same requisition in both directions (%GTK_SIZE_GROUP_BOTH). a `GtkSizeGroup` the mode to set for the size group. The direction in which the size group affects requested sizes. The mode of the size group determines the directions in which the size group affects the requested sizes of its component widgets. group has no effect group affects horizontal requisition group affects vertical requisition group affects both horizontal and vertical requisition Specifies a preference for height-for-width or width-for-height geometry management. Prefer height-for-width geometry management Prefer width-for-height geometry management Don’t trade height-for-width or width-for-height A list model that presents a slice of another model. This is useful when implementing paging by setting the size to the number of elements per page and updating the offset whenever a different page is opened. `GtkSliceListModel` passes through sections from the underlying model. Creates a new slice model. It presents the slice from @offset to offset + @size of the given @model. A new `GtkSliceListModel` The model to use the offset of the slice maximum size of the slice Gets the model that is currently being used or %NULL if none. The model in use a `GtkSliceListModel` Gets the offset set via gtk_slice_list_model_set_offset(). The offset a `GtkSliceListModel` Gets the size set via gtk_slice_list_model_set_size(). The size a `GtkSliceListModel` Sets the model to show a slice of. The model's item type must conform to @self's item type. a `GtkSliceListModel` The model to be sliced Sets the offset into the original model for this slice. If the offset is too large for the sliced model, @self will end up empty. a `GtkSliceListModel` the new offset to use Sets the maximum size. @self will never have more items than @size. It can however have fewer items if the offset is too large or the model sliced from doesn't have enough items. a `GtkSliceListModel` the maximum size The type of items. See [method@Gio.ListModel.get_item_type]. Child model to take slice from. The number of items. See [method@Gio.ListModel.get_n_items]. Offset of slice. Maximum size of slice. Assists in creating [class@Gsk.RenderNode]s for widgets. It functions in a similar way to a cairo context, and maintains a stack of render nodes and their associated transformations. The node at the top of the stack is the one that `gtk_snapshot_append_…()` functions operate on. Use the `gtk_snapshot_push_…()` functions and [method@Snapshot.pop] to change the current node. The typical way to obtain a `GtkSnapshot` object is as an argument to the [vfunc@Gtk.Widget.snapshot] vfunc. If you need to create your own `GtkSnapshot`, use [ctor@Gtk.Snapshot.new]. Note that `GtkSnapshot` applies some optimizations, so the node it produces may not match the API calls 1:1. For example, it will omit clip nodes if the child node is entirely contained within the clip rectangle. Creates a new `GtkSnapshot`. a newly-allocated `GtkSnapshot` Appends a stroked border rectangle inside the given @outline. The four sides of the border can have different widths and colors. a `GtkSnapshot` the outline of the border the stroke width of the border on the top, right, bottom and left side respectively. the color used on the top, right, bottom and left side. Creates a new [class@Gsk.CairoNode] and appends it to the current render node of @snapshot, without changing the current node. a `cairo_t` suitable for drawing the contents of the newly created render node a `GtkSnapshot` the bounds for the new node Creates a new render node drawing the @color into the given @bounds and appends it to the current render node of @snapshot. You should try to avoid calling this function if @color is transparent. a `GtkSnapshot` the color to draw the bounds for the new node Appends a conic gradient node with the given stops to @snapshot. a `GtkSnapshot` the rectangle to render the gradient into the center point of the conic gradient the clockwise rotation in degrees of the starting angle. 0 means the starting angle is the top. the color stops defining the gradient the number of elements in @stops A convenience method to fill a path with a color. See [method@Gtk.Snapshot.push_fill] if you need to fill a path with more complex content than a color. a `GtkSnapshot` The path describing the area to fill The fill rule to use the color to fill the path with Appends an inset shadow into the box given by @outline. a `GtkSnapshot` outline of the region surrounded by shadow color of the shadow horizontal offset of shadow vertical offset of shadow how far the shadow spreads towards the inside how much blur to apply to the shadow Creates render nodes for rendering @layout in the given foregound @color and appends them to the current node of @snapshot without changing the current node. The current theme's foreground color for a widget can be obtained with [method@Gtk.Widget.get_color]. Note that if the layout does not produce any visible output, then nodes may not be added to the @snapshot. a `GtkSnapshot` the `PangoLayout` to render the foreground color to render the layout in Appends a linear gradient node with the given stops to @snapshot. a `GtkSnapshot` the rectangle to render the linear gradient into the point at which the linear gradient will begin the point at which the linear gradient will finish the color stops defining the gradient the number of elements in @stops Appends @node to the current render node of @snapshot, without changing the current node. If @snapshot does not have a current node yet, @node will become the initial node. a `GtkSnapshot` a `GskRenderNode` Appends an outset shadow node around the box given by @outline. a `GtkSnapshot` outline of the region surrounded by shadow color of the shadow horizontal offset of shadow vertical offset of shadow how far the shadow spreads towards the outside how much blur to apply to the shadow Creates a new render node that pastes the contents copied by a previous call to [method@Gtk.Snapshot.push_copy] a `GtkSnapshot` the bounds for the new node the index of the copy, with 0 being the latest copy, 1 being the copy before that, and so on. Appends a radial gradient node with the given stops to @snapshot. a `GtkSnapshot` the rectangle to render the readial gradient into the center point for the radial gradient the horizontal radius the vertical radius the start position (on the horizontal axis) the end position (on the horizontal axis) the color stops defining the gradient the number of elements in @stops Appends a repeating linear gradient node with the given stops to @snapshot. a `GtkSnapshot` the rectangle to render the linear gradient into the point at which the linear gradient will begin the point at which the linear gradient will finish the color stops defining the gradient the number of elements in @stops Appends a repeating radial gradient node with the given stops to @snapshot. a `GtkSnapshot` the rectangle to render the readial gradient into the center point for the radial gradient the horizontal radius the vertical radius the start position (on the horizontal axis) the end position (on the horizontal axis) the color stops defining the gradient the number of elements in @stops Creates a new render node drawing the @texture into the given @bounds and appends it to the current render node of @snapshot. In contrast to [method@Gtk.Snapshot.append_texture], this function provides control about how the filter that is used when scaling. a `GtkSnapshot` the texture to render the filter to use the bounds for the new node A convenience method to stroke a path with a color. See [method@Gtk.Snapshot.push_stroke] if you need to stroke a path with more complex content than a color. a `GtkSnapshot` The path describing the area to fill The stroke attributes the color to fill the path with Creates a new render node drawing the @texture into the given @bounds and appends it to the current render node of @snapshot. If the texture needs to be scaled to fill @bounds, linear filtering is used. See [method@Gtk.Snapshot.append_scaled_texture] if you need other filtering, such as nearest-neighbour. a `GtkSnapshot` the texture to render the bounds for the new node Returns the node that was constructed by @snapshot and frees @snapshot. See also [method@Gtk.Snapshot.to_node]. a newly-created [class@Gsk.RenderNode] a `GtkSnapshot` Returns a paintable for the node that was constructed by @snapshot and frees @snapshot. a newly-created [iface@Gdk.Paintable] a `GtkSnapshot` The size of the resulting paintable or %NULL to use the bounds of the snapshot Removes the top element from the stack of render nodes and adds it to the nearest [class@Gsk.GLShaderNode] below it. This must be called the same number of times as the number of textures is needed for the shader in [method@Gtk.Snapshot.push_gl_shader]. GTK's new Vulkan-focused rendering does not support this feature. Use [class@Gtk.GLArea] for OpenGL rendering. a `GtkSnapshot` Applies a perspective projection transform. See [method@Gsk.Transform.perspective] for a discussion on the details. a `GtkSnapshot` distance of the z=0 plane Removes the top element from the stack of render nodes, and appends it to the node underneath it. a `GtkSnapshot` Blends together two images with the given blend mode. Until the first call to [method@Gtk.Snapshot.pop], the bottom image for the blend operation will be recorded. After that call, the top image to be blended will be recorded until the second call to [method@Gtk.Snapshot.pop]. Calling this function requires two subsequent calls to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` blend mode to use Blurs an image. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the blur radius to use. Must be positive Clips an image to a rectangle. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the rectangle to clip to Modifies the colors of an image by applying an affine transformation in RGB space. In particular, the colors will be transformed by applying pixel = transpose(color_matrix) * pixel + color_offset for every pixel. The transformation operates on unpremultiplied colors, with color components ordered R, G, B, A. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the color matrix to use the color offset to use Modifies the colors of an image by applying a transfer function for each component. The transfer functions operate on unpremultiplied colors. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the transfer for the red component the transfer for the green component the transfer for the blue component the transfer for the alpha component Until the first call to [method@Gtk.Snapshot.pop], the mask image for the mask operation will be recorded. After that call, the child image will be recorded until the second call to [method@Gtk.Snapshot.pop]. Calling this function requires 2 subsequent calls to gtk_snapshot_pop(). a #GtkSnapshot The Porter/Duff compositing operator to use Stores the current rendering state for later pasting via [method@Gtk.Snapshot.append_paste]. Pasting is possible until the matching call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` Snapshots a cross-fade operation between two images with the given @progress. Until the first call to [method@Gtk.Snapshot.pop], the start image will be snapshot. After that call, the end image will be recorded until the second call to [method@Gtk.Snapshot.pop]. Calling this function requires two subsequent calls to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` progress between 0.0 and 1.0 Inserts a debug node with a message. Debug nodes don't affect the rendering at all, but can be helpful in identifying parts of a render node tree dump, for example in the GTK inspector. a `GtkSnapshot` a printf-style format string arguments for @message Fills the area given by @path and @fill_rule with an image and discards everything outside of it. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. If you want to fill the path with a color, [method@Gtk.Snapshot.append_fill] than rendering new ones, use [method@Gtk.Snapshot.append_fill] may be more convenient. a `GtkSnapshot` The path describing the area to fill The fill rule to use Push a [class@Gsk.GLShaderNode]. The node uses the given [class@Gsk.GLShader] and uniform values Additionally this takes a list of @n_children other nodes which will be passed to the [class@Gsk.GLShaderNode]. The @take_args argument is a block of data to use for uniform arguments, as per types and offsets defined by the @shader. Normally this is generated by [method@Gsk.GLShader.format_args] or [struct@Gsk.ShaderArgsBuilder]. The snapshotter takes ownership of @take_args, so the caller should not free it after this. If the renderer doesn't support GL shaders, or if there is any problem when compiling the shader, then the node will draw pink. You should use [method@Gsk.GLShader.compile] to ensure the @shader will work for the renderer before using it. If the shader requires textures (see [method@Gsk.GLShader.get_n_textures]), then it is expected that you call [method@Gtk.Snapshot.gl_shader_pop_texture] the number of times that are required. Each of these calls will generate a node that is added as a child to the `GskGLShaderNode`, which in turn will render these offscreen and pass as a texture to the shader. Once all textures (if any) are pop:ed, you must call the regular [method@Gtk.Snapshot.pop]. If you want to use pre-existing textures as input to the shader rather than rendering new ones, use [method@Gtk.Snapshot.append_texture] to push a texture node. These will be used directly rather than being re-rendered. For details on how to write shaders, see [class@Gsk.GLShader]. GTK's new Vulkan-focused rendering does not support this feature. Use [class@Gtk.GLArea] for OpenGL rendering. a `GtkSnapshot` The code to run the rectangle to render into Data block with arguments for the shader. Isolates the following drawing operations from previous ones. You can express "everything but these flags" in a forward compatible way by using bit math: `GSK_ISOLATION_ALL & ~(GSK_ISOLATION_BACKGROUND | GSK_ISOLATION_COPY_PASTE)` will isolate everything but background and copy/paste. For what isolation features exist, see [flags@Gsk.Isolation]. Content is isolated until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` features that are isolated Until the first call to [method@Gtk.Snapshot.pop], the mask image for the mask operation will be recorded. After that call, the source image will be recorded until the second call to [method@Gtk.Snapshot.pop]. Calling this function requires 2 subsequent calls to gtk_snapshot_pop(). a #GtkSnapshot mask mode to use Modifies the opacity of an image. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the opacity to use Creates a node that repeats the child node. The child is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the bounds within which to repeat the bounds of the child or %NULL to use the full size of the collected child node Clips an image to a rounded rectangle. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the rounded rectangle to clip to Applies a shadow to an image. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the first shadow specification number of shadow specifications Strokes the given @path with the attributes given by @stroke and an image. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. Note that the strokes are subject to the same transformation as everything else, so uneven scaling will cause horizontal and vertical strokes to have different widths. If you want to stroke the path with a color, [method@Gtk.Snapshot.append_stroke] may be more convenient. a #GtkSnapshot The path to stroke The stroke attributes Creates a render node for the CSS background according to @context, and appends it to the current node of @snapshot, without changing the current node. a `GtkSnapshot` the style context that defines the background X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Creates a render node for the focus outline according to @context, and appends it to the current node of @snapshot, without changing the current node. a `GtkSnapshot` the style context that defines the focus ring X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Creates a render node for the CSS border according to @context, and appends it to the current node of @snapshot, without changing the current node. a `GtkSnapshot` the style context that defines the frame X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Draws a text caret using @snapshot at the specified index of @layout. snapshot to render to a `GtkStyleContext` X origin Y origin the `PangoLayout` of the text the index in the `PangoLayout` the `PangoDirection` of the text Creates a render node for rendering @layout according to the style information in @context, and appends it to the current node of @snapshot, without changing the current node. a `GtkSnapshot` the style context that defines the text X origin of the rectangle Y origin of the rectangle the `PangoLayout` to render Restores @snapshot to the state saved by a preceding call to [method@Snapshot.save] and removes that state from the stack of saved states. a `GtkSnapshot` Rotates @@snapshot's coordinate system by @angle degrees in 2D space - or in 3D speak, rotates around the Z axis. The rotation happens around the origin point of (0, 0) in the @snapshot's current coordinate system. To rotate around axes other than the Z axis, use [method@Gsk.Transform.rotate_3d]. a `GtkSnapshot` the rotation angle, in degrees (clockwise) Rotates @snapshot's coordinate system by @angle degrees around @axis. For a rotation in 2D space, use [method@Gsk.Transform.rotate]. a `GtkSnapshot` the rotation angle, in degrees (clockwise) The rotation axis Makes a copy of the current state of @snapshot and saves it on an internal stack. When [method@Gtk.Snapshot.restore] is called, @snapshot will be restored to the saved state. Multiple calls to [method@Gtk.Snapshot.save] and [method@Gtk.Snapshot.restore] can be nested; each call to `gtk_snapshot_restore()` restores the state from the matching paired `gtk_snapshot_save()`. It is necessary to clear all saved states with corresponding calls to `gtk_snapshot_restore()`. a `GtkSnapshot` Scales @snapshot's coordinate system in 2-dimensional space by the given factors. Use [method@Gtk.Snapshot.scale_3d] to scale in all 3 dimensions. a `GtkSnapshot` scaling factor on the X axis scaling factor on the Y axis Scales @snapshot's coordinate system by the given factors. a `GtkSnapshot` scaling factor on the X axis scaling factor on the Y axis scaling factor on the Z axis Returns the render node that was constructed by @snapshot. Note that this function may return %NULL if nothing has been added to the snapshot or if its content does not produce pixels to be rendered. After calling this function, it is no longer possible to add more nodes to @snapshot. The only function that should be called after this is [method@GObject.Object.unref]. the constructed `GskRenderNode` or %NULL if there are no nodes to render. a `GtkSnapshot` Returns a paintable encapsulating the render node that was constructed by @snapshot. After calling this function, it is no longer possible to add more nodes to @snapshot. The only function that should be called after this is [method@GObject.Object.unref]. a new `GdkPaintable` a `GtkSnapshot` The size of the resulting paintable or %NULL to use the bounds of the snapshot Transforms @snapshot's coordinate system with the given @transform. a `GtkSnapshot` the transform to apply Transforms @snapshot's coordinate system with the given @matrix. a `GtkSnapshot` the matrix to multiply the transform with Translates @snapshot's coordinate system by @point in 2-dimensional space. a `GtkSnapshot` the point to translate the snapshot by Translates @snapshot's coordinate system by @point. a `GtkSnapshot` the point to translate the snapshot by A list model that sorts the elements of another model. The elements are sorted according to a `GtkSorter`. The model is a stable sort. If two items compare equal according to the sorter, the one that appears first in the original model will also appear first after sorting. Note that if you change the sorter, the previous order will have no influence on the new order. If you want that, consider using a `GtkMultiSorter` and appending the previous sorter to it. The model can be set up to do incremental sorting, so that sorting long lists doesn't block the UI. See [method@Gtk.SortListModel.set_incremental] for details. `GtkSortListModel` is a generic model and because of that it cannot take advantage of any external knowledge when sorting. If you run into performance issues with `GtkSortListModel`, it is strongly recommended that you write your own sorting list model. `GtkSortListModel` allows sorting the items into sections. It implements `GtkSectionModel` and when [property@Gtk.SortListModel:section-sorter] is set, it will sort all items with that sorter and items comparing equal with it will be put into the same section. The [property@Gtk.SortListModel:sorter] will then be used to sort items inside their sections. Creates a new sort list model that uses the @sorter to sort @model. a new `GtkSortListModel` the model to sort the `GtkSorter` to sort @model with, Returns whether incremental sorting is enabled. See [method@Gtk.SortListModel.set_incremental]. %TRUE if incremental sorting is enabled a `GtkSortListModel` Gets the model currently sorted or %NULL if none. The model that gets sorted a `GtkSortListModel` Estimates progress of an ongoing sorting operation. The estimate is the number of items that would still need to be sorted to finish the sorting operation if this was a linear algorithm. So this number is not related to how many items are already correctly sorted. If you want to estimate the progress, you can use code like this: ```c pending = gtk_sort_list_model_get_pending (self); model = gtk_sort_list_model_get_model (self); progress = 1.0 - pending / (double) MAX (1, g_list_model_get_n_items (model)); ``` If no sort operation is ongoing - in particular when [property@Gtk.SortListModel:incremental] is %FALSE - this function returns 0. a progress estimate of remaining items to sort a `GtkSortListModel` Gets the section sorter that is used to sort items of @self into sections. the sorter of #self a `GtkSortListModel` Gets the sorter that is used to sort @self. the sorter of #self a `GtkSortListModel` Sets the sort model to do an incremental sort. When incremental sorting is enabled, the `GtkSortListModel` will not do a complete sort immediately, but will instead queue an idle handler that incrementally sorts the items towards their correct position. This of course means that items do not instantly appear in the right place. It also means that the total sorting time is a lot slower. When your filter blocks the UI while sorting, you might consider turning this on. Depending on your model and sorters, this may become interesting around 10,000 to 100,000 items. By default, incremental sorting is disabled. See [method@Gtk.SortListModel.get_pending] for progress information about an ongoing incremental sorting operation. a `GtkSortListModel` %TRUE to sort incrementally Sets the model to be sorted. The @model's item type must conform to the item type of @self. a `GtkSortListModel` The model to be sorted Sets a new section sorter on @self. a `GtkSortListModel` the `GtkSorter` to sort @model with Sets a new sorter on @self. a `GtkSortListModel` the `GtkSorter` to sort @model with If the model should sort items incrementally. The type of items. See [method@Gio.ListModel.get_item_type]. The model being sorted. The number of items. See [method@Gio.ListModel.get_n_items]. Estimate of unsorted items remaining. The section sorter for this model, if one is set. The sorter for this model. Determines the direction of a sort. Sorting is in ascending order. Sorting is in descending order. Describes sorting criteria for a [class@Gtk.SortListModel]. Its primary user is [class@Gtk.SortListModel] The model will use a sorter to determine the order in which its items should appear by calling [method@Gtk.Sorter.compare] for pairs of items. Sorters may change their sorting behavior through their lifetime. In that case, they will emit the [signal@Gtk.Sorter::changed] signal to notify that the sort order is no longer valid and should be updated by calling gtk_sorter_compare() again. GTK provides various pre-made sorter implementations for common sorting operations. [class@Gtk.ColumnView] has built-in support for sorting lists via the [property@Gtk.ColumnViewColumn:sorter] property, where the user can change the sorting by clicking on list headers. Of course, in particular for large lists, it is also possible to subclass `GtkSorter` and provide one's own sorter. Compares two given items according to the sort order implemented by the sorter. Sorters implement a partial order: * It is reflexive, ie a = a * It is antisymmetric, ie if a < b and b < a, then a = b * It is transitive, ie given any 3 items with a ≤ b and b ≤ c, then a ≤ c The sorter may signal it conforms to additional constraints via the return value of [method@Gtk.Sorter.get_order]. %GTK_ORDERING_EQUAL if @item1 == @item2, %GTK_ORDERING_SMALLER if @item1 < @item2, %GTK_ORDERING_LARGER if @item1 > @item2 a `GtkSorter` first item to compare second item to compare Gets the order that @self conforms to. See [enum@Gtk.SorterOrder] for details of the possible return values. This function is intended to allow optimizations. The order a `GtkSorter` Notifies all users of the sorter that it has changed. This emits the [signal@Gtk.Sorter::changed] signal. Users of the sorter should then update the sort order via [method@Gtk.Sorter.compare]. Depending on the @change parameter, it may be possible to update the sort order without a full resorting. Refer to the [enum@Gtk.SorterChange] documentation for details. This function is intended for implementers of `GtkSorter` subclasses and should not be called from other functions. a `GtkSorter` How the sorter changed Compares two given items according to the sort order implemented by the sorter. Sorters implement a partial order: * It is reflexive, ie a = a * It is antisymmetric, ie if a < b and b < a, then a = b * It is transitive, ie given any 3 items with a ≤ b and b ≤ c, then a ≤ c The sorter may signal it conforms to additional constraints via the return value of [method@Gtk.Sorter.get_order]. %GTK_ORDERING_EQUAL if @item1 == @item2, %GTK_ORDERING_SMALLER if @item1 < @item2, %GTK_ORDERING_LARGER if @item1 > @item2 a `GtkSorter` first item to compare second item to compare Gets the order that @self conforms to. See [enum@Gtk.SorterOrder] for details of the possible return values. This function is intended to allow optimizations. The order a `GtkSorter` Emitted whenever the sorter changed. Users of the sorter should then update the sort order again via gtk_sorter_compare(). [class@Gtk.SortListModel] handles this signal automatically. Depending on the @change parameter, it may be possible to update the sort order without a full resorting. Refer to the [enum@Gtk.SorterChange] documentation for details. how the sorter changed Describes changes in a sorter in more detail and allows users to optimize resorting. The sorter change cannot be described by any of the other enumeration values The sort order was inverted. Comparisons that returned %GTK_ORDERING_SMALLER now return %GTK_ORDERING_LARGER and vice versa. Other comparisons return the same values as before. The sorter is less strict: Comparisons may now return %GTK_ORDERING_EQUAL that did not do so before. The sorter is more strict: Comparisons that did return %GTK_ORDERING_EQUAL may not do so anymore. The virtual table for `GtkSorter`. Compare two items. See gtk_sorter_compare() for details. %GTK_ORDERING_EQUAL if @item1 == @item2, %GTK_ORDERING_SMALLER if @item1 < @item2, %GTK_ORDERING_LARGER if @item1 > @item2 a `GtkSorter` first item to compare second item to compare Get the `GtkSorderOrder` that applies to the current sorter. If unimplemented, it returns %GTK_SORTER_ORDER_PARTIAL. The order a `GtkSorter` Describes the type of order that a `GtkSorter` may produce. A partial order. Any `GtkOrdering` is possible. No order, all elements are considered equal. gtk_sorter_compare() will only return %GTK_ORDERING_EQUAL. A total order. gtk_sorter_compare() will only return %GTK_ORDERING_EQUAL if an item is compared with itself. Two different items will never cause this value to be returned. Allows to enter or change numeric values. <picture> <source srcset="spinbutton-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkSpinButton" src="spinbutton.png"> </picture> Rather than having to directly type a number into a `GtkEntry`, `GtkSpinButton` allows the user to click on one of two arrows to increment or decrement the displayed value. A value can still be typed in, with the bonus that it can be checked to ensure it is in a given range. The main properties of a `GtkSpinButton` are through an adjustment. See the [class@Gtk.Adjustment] documentation for more details about an adjustment's properties. Note that `GtkSpinButton` will by default make its entry large enough to accommodate the lower and upper bounds of the adjustment. If this is not desired, the automatic sizing can be turned off by explicitly setting [property@Gtk.Editable:width-chars] to a value != -1. ## Using a GtkSpinButton to get an integer ```c // Provides a function to retrieve an integer value from a GtkSpinButton // and creates a spin button to model percentage values. int grab_int_value (GtkSpinButton *button, gpointer user_data) { return gtk_spin_button_get_value_as_int (button); } void create_integer_spin_button (void) { GtkWidget *window, *button; GtkAdjustment *adjustment; adjustment = gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 0.0); window = gtk_window_new (); // creates the spinbutton, with no decimal places button = gtk_spin_button_new (adjustment, 1.0, 0); gtk_window_set_child (GTK_WINDOW (window), button); gtk_window_present (GTK_WINDOW (window)); } ``` ## Using a GtkSpinButton to get a floating point value ```c // Provides a function to retrieve a floating point value from a // GtkSpinButton, and creates a high precision spin button. float grab_float_value (GtkSpinButton *button, gpointer user_data) { return gtk_spin_button_get_value (button); } void create_floating_spin_button (void) { GtkWidget *window, *button; GtkAdjustment *adjustment; adjustment = gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.0); window = gtk_window_new (); // creates the spinbutton, with three decimal places button = gtk_spin_button_new (adjustment, 0.001, 3); gtk_window_set_child (GTK_WINDOW (window), button); gtk_window_present (GTK_WINDOW (window)); } ``` # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.SpinButton::change-value] # CSS nodes ``` spinbutton.horizontal ├── text │ ├── undershoot.left │ ╰── undershoot.right ├── button.down ╰── button.up ``` ``` spinbutton.vertical ├── button.up ├── text │ ├── undershoot.left │ ╰── undershoot.right ╰── button.down ``` `GtkSpinButton`s main CSS node has the name spinbutton. It creates subnodes for the entry and the two buttons, with these names. The button nodes have the style classes .up and .down. The `GtkText` subnodes (if present) are put below the text node. The orientation of the spin button is reflected in the .vertical or .horizontal style class on the main node. # Accessibility `GtkSpinButton` uses the [enum@Gtk.AccessibleRole.spin_button] role. Creates a new `GtkSpinButton`. The new `GtkSpinButton` the `GtkAdjustment` that this spin button should use specifies by how much the rate of change in the value will accelerate if you continue to hold down an up/down button or arrow key the number of decimal places to display Creates a new `GtkSpinButton` with the given properties. This is a convenience constructor that allows creation of a numeric `GtkSpinButton` without manually creating an adjustment. The value is initially set to the minimum value and a page increment of 10 * @step is the default. The precision of the spin button is equivalent to the precision of @step. Note that the way in which the precision is derived works best if @step is a power of ten. If the resulting precision is not suitable for your needs, use [method@Gtk.SpinButton.set_digits] to correct it. The new `GtkSpinButton` Minimum allowable value Maximum allowable value Increment added or subtracted by spinning the widget Changes the properties of an existing spin button. The adjustment, climb rate, and number of decimal places are updated accordingly. a `GtkSpinButton` a `GtkAdjustment` to replace the spin button’s existing adjustment, or %NULL to leave its current adjustment unchanged the new climb rate the number of decimal places to display in the spin button Retrieves the value set by [method@Gtk.SpinButton.set_activates_default]. %TRUE if the spin button will activate the default widget a `GtkSpinButton` Get the adjustment associated with a `GtkSpinButton`. the `GtkAdjustment` of @spin_button a `GtkSpinButton` Returns the acceleration rate for repeated changes. the acceleration rate a `GtkSpinButton` Fetches the precision of @spin_button. the current precision a `GtkSpinButton` Gets the current step and page the increments used by @spin_button. See [method@Gtk.SpinButton.set_increments]. a `GtkSpinButton` location to store step increment location to store page increment Returns whether non-numeric text can be typed into the spin button. %TRUE if only numeric text can be entered a `GtkSpinButton` Gets the range allowed for @spin_button. See [method@Gtk.SpinButton.set_range]. a `GtkSpinButton` location to store minimum allowed value location to store maximum allowed value Returns whether the values are corrected to the nearest step. %TRUE if values are snapped to the nearest step a `GtkSpinButton` Gets the update behavior of a spin button. See [method@Gtk.SpinButton.set_update_policy]. the current update policy a `GtkSpinButton` Get the value in the @spin_button. the value of @spin_button a `GtkSpinButton` Get the value @spin_button represented as an integer. the value of @spin_button a `GtkSpinButton` Returns whether the spin button’s value wraps around to the opposite limit when the upper or lower limit of the range is exceeded. %TRUE if the spin button wraps around a `GtkSpinButton` Sets whether activating the spin button will activate the default widget for the window containing the spin button. See [signal@Gtk.SpinButton::activate] for what counts as activation. a `GtkSpinButton` %TRUE to activate window’s default widget on activation Replaces the `GtkAdjustment` associated with @spin_button. a `GtkSpinButton` a `GtkAdjustment` to replace the existing adjustment Sets the acceleration rate for repeated changes when you hold down a button or key. a `GtkSpinButton` the rate of acceleration, must be >= 0 Set the precision to be displayed by @spin_button. Up to 20 digit precision is allowed. a `GtkSpinButton` the number of digits after the decimal point to be displayed for the spin button’s value Sets the step and page increments for spin_button. This affects how quickly the value changes when the spin button’s arrows are activated. a `GtkSpinButton` increment applied for a button 1 press. increment applied for a button 2 press. Sets the flag that determines if non-numeric text can be typed into the spin button. a `GtkSpinButton` flag indicating if only numeric entry is allowed Sets the minimum and maximum allowable values for @spin_button. If the current value is outside this range, it will be adjusted to fit within the range, otherwise it will remain unchanged. a `GtkSpinButton` minimum allowable value maximum allowable value Sets the policy as to whether values are corrected to the nearest step increment when a spin button is activated after providing an invalid value. a `GtkSpinButton` a flag indicating if invalid values should be corrected Sets the update behavior of a spin button. This determines whether the spin button is always updated or only when a valid value is set. a `GtkSpinButton` a `GtkSpinButtonUpdatePolicy` value Sets the value of @spin_button. a `GtkSpinButton` the new value Sets the flag that determines if a spin button value wraps around to the opposite limit when the upper or lower limit of the range is exceeded. a `GtkSpinButton` a flag indicating if wrapping behavior is performed Increment or decrement a spin button’s value in a specified direction by a specified amount. a `GtkSpinButton` a `GtkSpinType` indicating the direction to spin step increment to apply in the specified direction Manually force an update of the spin button. a `GtkSpinButton` Whether to activate the default widget when the spin button is activated. See [signal@Gtk.SpinButton::activate] for what counts as activation. The adjustment that holds the value of the spin button. The acceleration rate when you hold down a button or key. The number of decimal places to display. Whether non-numeric characters should be ignored. Whether erroneous values are automatically changed to the spin buttons nearest step increment. Whether the spin button should update always, or only when the value is acceptable. The current value. Whether a spin button should wrap upon reaching its limits. Emitted when the spin button is activated. The keybindings for this signal are all forms of the <kbd>Enter</kbd> key. If the <kbd>Enter</kbd> key results in the value being committed to the spin button, then activation does not occur until <kbd>Enter</kbd> is pressed again. Emitted when the user initiates a value change. This is a [keybinding signal](class.SignalAction.html). Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal are Up/Down and PageUp/PageDown. a `GtkScrollType` to specify the speed and amount of change Emitted to convert the users input into a double value. The signal handler is expected to use [method@Gtk.Editable.get_text] to retrieve the text of the spinbutton and set @new_value to the new value. The default conversion uses g_strtod(). %TRUE for a successful conversion, %FALSE if the input was not handled, and %GTK_INPUT_ERROR if the conversion failed. return location for the new value Emitted to tweak the formatting of the value for display. ```c // show leading zeros static gboolean on_output (GtkSpinButton *spin, gpointer data) { char *text; int value; value = gtk_spin_button_get_value_as_int (spin); text = g_strdup_printf ("%02d", value); gtk_editable_set_text (GTK_EDITABLE (spin), text): g_free (text); return TRUE; } ``` %TRUE if the value has been displayed Emitted when the value is changed. Also see the [signal@Gtk.SpinButton::output] signal. Emitted right after the spinbutton wraps from its maximum to its minimum value or vice-versa. Determines whether the spin button displays values outside the adjustment bounds. See [method@Gtk.SpinButton.set_update_policy]. When refreshing your `GtkSpinButton`, the value is always displayed When refreshing your `GtkSpinButton`, the value is only displayed if it is valid within the bounds of the spin button's adjustment The values of the GtkSpinType enumeration are used to specify the change to make in gtk_spin_button_spin(). Increment by the adjustments step increment. Decrement by the adjustments step increment. Increment by the adjustments page increment. Decrement by the adjustments page increment. Go to the adjustments lower bound. Go to the adjustments upper bound. Change by a specified amount. Displays an icon-size spinning animation. It is often used as an alternative to a [class@Gtk.ProgressBar] for displaying indefinite activity, instead of actual progress. <picture> <source srcset="spinner-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkSpinner" src="spinner.png"> </picture> To start the animation, use [method@Gtk.Spinner.start], to stop it use [method@Gtk.Spinner.stop]. # CSS nodes `GtkSpinner` has a single CSS node with the name spinner. When the animation is active, the :checked pseudoclass is added to this node. # Accessibility `GtkSpinner` uses the [enum@Gtk.AccessibleRole.progress_bar] role. Returns a new spinner widget. Not yet started. a new `GtkSpinner` Returns whether the spinner is spinning. %TRUE if the spinner is active a `GtkSpinner` Sets the activity of the spinner. a `GtkSpinner` whether the spinner should be spinning Starts the animation of the spinner. a `GtkSpinner` Stops the animation of the spinner. a `GtkSpinner` Whether the spinner is spinning Shows one of its children at a time. <picture> <source srcset="stack-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkStack" src="stack.png"> </picture> In contrast to `GtkNotebook`, `GtkStack` does not provide a means for users to change the visible child. Instead, a separate widget such as [class@Gtk.StackSwitcher] or [class@Gtk.StackSidebar] can be used with `GtkStack` to provide this functionality. Transitions between pages can be animated as slides or fades. This can be controlled with [method@Gtk.Stack.set_transition_type]. These animations respect the [property@Gtk.Settings:gtk-enable-animations] setting. `GtkStack` maintains a [class@Gtk.StackPage] object for each added child, which holds additional per-child properties. You obtain the `GtkStackPage` for a child with [method@Gtk.Stack.get_page] and you can obtain a `GtkSelectionModel` containing all the pages with [method@Gtk.Stack.get_pages]. # GtkStack as GtkBuildable To set child-specific properties in a .ui file, create `GtkStackPage` objects explicitly, and set the child widget as a property on it: ```xml <object class="GtkStack" id="stack"> <child> <object class="GtkStackPage"> <property name="name">page1</property> <property name="title">In the beginning…</property> <property name="child"> <object class="GtkLabel"> <property name="label">It was dark</property> </object> </property> </object> </child> ``` # CSS nodes `GtkStack` has a single CSS node named stack. # Accessibility `GtkStack` uses the [enum@Gtk.AccessibleRole.tab_panel] role for the stack pages, which are the accessible parent objects of the child widgets. Creates a new `GtkStack`. a new `GtkStack` Adds a child to @stack. the `GtkStackPage` for @child a `GtkStack` the widget to add Adds a child to @stack. The child is identified by the @name. the `GtkStackPage` for @child a `GtkStack` the widget to add the name for @child Adds a child to @stack. The child is identified by the @name. The @title will be used by `GtkStackSwitcher` to represent @child in a tab bar, so it should be short. the `GtkStackPage` for @child a `GtkStack` the widget to add the name for @child a human-readable title for @child Finds the child with the name given as the argument. Returns %NULL if there is no child with this name. the requested child of the `GtkStack` a `GtkStack` the name of the child to find Gets whether @stack is horizontally homogeneous. whether @stack is horizontally homogeneous. a `GtkStack` Returns whether the `GtkStack` is set up to interpolate between the sizes of children on page switch. %TRUE if child sizes are interpolated A `GtkStack` Returns the `GtkStackPage` object for @child. the `GtkStackPage` for @child a `GtkStack` a child of @stack Returns a `GListModel` that contains the pages of the stack. This can be used to keep an up-to-date view. The model also implements [iface@Gtk.SelectionModel] and can be used to track and modify the visible page. a `GtkSelectionModel` for the stack's children a `GtkStack` Returns the amount of time (in milliseconds) that transitions between pages in @stack will take. the transition duration a `GtkStack` Returns whether the @stack is currently in a transition from one page to another. %TRUE if the transition is currently running, %FALSE otherwise. a `GtkStack` Gets the type of animation that will be used for transitions between pages in @stack. the current transition type of @stack a `GtkStack` Gets whether @stack is vertically homogeneous. whether @stack is vertically homogeneous. a `GtkStack` Gets the currently visible child of @stack. Returns %NULL if there are no visible children. the visible child of the `GtkStack` a `GtkStack` Returns the name of the currently visible child of @stack. Returns %NULL if there is no visible child. the name of the visible child of the `GtkStack` a `GtkStack` Removes a child widget from @stack. a `GtkStack` the child to remove Sets the `GtkStack` to be horizontally homogeneous or not. If it is homogeneous, the `GtkStack` will request the same width for all its children. If it isn't, the stack may change width when a different child becomes visible. a `GtkStack` %TRUE to make @stack horizontally homogeneous Sets whether or not @stack will interpolate its size when changing the visible child. If the [property@Gtk.Stack:interpolate-size] property is set to %TRUE, @stack will interpolate its size between the current one and the one it'll take after changing the visible child, according to the set transition duration. A `GtkStack` the new value Sets the duration that transitions between pages in @stack will take. a `GtkStack` the new duration, in milliseconds Sets the type of animation that will be used for transitions between pages in @stack. Available types include various kinds of fades and slides. The transition type can be changed without problems at runtime, so it is possible to change the animation based on the page that is about to become current. a `GtkStack` the new transition type Sets the `GtkStack` to be vertically homogeneous or not. If it is homogeneous, the `GtkStack` will request the same height for all its children. If it isn't, the stack may change height when a different child becomes visible. a `GtkStack` %TRUE to make @stack vertically homogeneous Makes @child the visible child of @stack. If @child is different from the currently visible child, the transition between the two will be animated with the current transition type of @stack. Note that the @child widget has to be visible itself (see [method@Gtk.Widget.show]) in order to become the visible child of @stack. a `GtkStack` a child of @stack Makes the child with the given name visible. Note that the child widget has to be visible itself (see [method@Gtk.Widget.show]) in order to become the visible child of @stack. a `GtkStack` the name of the child to make visible the transition type to use Makes the child with the given name visible. If @child is different from the currently visible child, the transition between the two will be animated with the current transition type of @stack. Note that the child widget has to be visible itself (see [method@Gtk.Widget.show]) in order to become the visible child of @stack. a `GtkStack` the name of the child to make visible %TRUE if the stack allocates the same width for all children. Whether or not the size should smoothly change during the transition. A selection model with the stack pages. The animation duration, in milliseconds. Whether or not the transition is currently running. The type of animation used to transition. %TRUE if the stack allocates the same height for all children. The widget currently visible in the stack. The name of the widget currently visible in the stack. An auxiliary class used by `GtkStack`. Returns the stack child to which @self belongs. the child to which @self belongs a `GtkStackPage` Returns the icon name of the page. The value of the [property@Gtk.StackPage:icon-name] property a `GtkStackPage` Returns the name of the page. The value of the [property@Gtk.StackPage:name] property a `GtkStackPage` Returns whether the page is marked as “needs attention”. The value of the [property@Gtk.StackPage:needs-attention] property. a `GtkStackPage` Gets the page title. The value of the [property@Gtk.StackPage:title] property a `GtkStackPage` Gets whether underlines in the page title indicate mnemonics. The value of the [property@Gtk.StackPage:use-underline] property a `GtkStackPage` Returns whether @page is visible in its `GtkStack`. This is independent from the [property@Gtk.Widget:visible] property of its widget. %TRUE if @page is visible a `GtkStackPage` Sets the icon name of the page. a `GtkStackPage` the new value to set Sets the name of the page. a `GtkStackPage` the new value to set Sets whether the page is marked as “needs attention”. a `GtkStackPage` the new value to set Sets the page title. a `GtkStackPage` the new value to set Sets whether underlines in the page title indicate mnemonics. a `GtkStackPage` the new value to set Sets whether @page is visible in its `GtkStack`. a `GtkStackPage` The new property value The child that this page is for. The icon name of the child page. The name of the child page. Whether the page requires the user attention. This is used by the [class@Gtk.StackSwitcher] to change the appearance of the corresponding button when a page needs attention and it is not the current one. The title of the child page. If set, an underline in the title indicates a mnemonic. Whether this page is visible. Uses a sidebar to switch between `GtkStack` pages. <picture> <source srcset="sidebar-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkStackSidebar" src="sidebar.png"> </picture> In order to use a `GtkStackSidebar`, you simply use a `GtkStack` to organize your UI flow, and add the sidebar to your sidebar area. You can use [method@Gtk.StackSidebar.set_stack] to connect the `GtkStackSidebar` to the `GtkStack`. # CSS nodes `GtkStackSidebar` has a single CSS node with name stacksidebar and style class .sidebar. When circumstances require it, `GtkStackSidebar` adds the .needs-attention style class to the widgets representing the stack pages. Creates a new `GtkStackSidebar`. the new `GtkStackSidebar` Retrieves the stack. the associated `GtkStack` or %NULL if none has been set explicitly a `GtkStackSidebar` Set the `GtkStack` associated with this `GtkStackSidebar`. The sidebar widget will automatically update according to the order and items within the given `GtkStack`. a `GtkStackSidebar` a `GtkStack` The stack. Shows a row of buttons to switch between `GtkStack` pages. <picture> <source srcset="stackswitcher-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkStackSwitcher" src="stackswitcher.png"> </picture> It acts as a controller for the associated `GtkStack`. All the content for the buttons comes from the properties of the stacks [class@Gtk.StackPage] objects; the button visibility in a `GtkStackSwitcher` widget is controlled by the visibility of the child in the `GtkStack`. It is possible to associate multiple `GtkStackSwitcher` widgets with the same `GtkStack` widget. # CSS nodes `GtkStackSwitcher` has a single CSS node named stackswitcher and style class .stack-switcher. When circumstances require it, `GtkStackSwitcher` adds the .needs-attention style class to the widgets representing the stack pages. # Accessibility `GtkStackSwitcher` uses the [enum@Gtk.AccessibleRole.tab_list] role and uses the [enum@Gtk.AccessibleRole.tab] role for its buttons. # Orientable Since GTK 4.4, `GtkStackSwitcher` implements `GtkOrientable` allowing the stack switcher to be made vertical with `gtk_orientable_set_orientation()`. Create a new `GtkStackSwitcher`. a new `GtkStackSwitcher`. Retrieves the stack. the stack a `GtkStackSwitcher` Sets the stack to control. a `GtkStackSwitcher` a `GtkStack` The stack. Possible transitions between pages in a `GtkStack` widget. New values may be added to this enumeration over time. No transition A cross-fade Slide from left to right Slide from right to left Slide from bottom up Slide from top down Slide from left or right according to the children order Slide from top down or bottom up according to the order Cover the old page by sliding up Cover the old page by sliding down Cover the old page by sliding to the left Cover the old page by sliding to the right Uncover the new page by sliding up Uncover the new page by sliding down Uncover the new page by sliding to the left Uncover the new page by sliding to the right Cover the old page sliding up or uncover the new page sliding down, according to order Cover the old page sliding down or uncover the new page sliding up, according to order Cover the old page sliding left or uncover the new page sliding right, according to order Cover the old page sliding right or uncover the new page sliding left, according to order Pretend the pages are sides of a cube and rotate that cube to the left Pretend the pages are sides of a cube and rotate that cube to the right Pretend the pages are sides of a cube and rotate that cube to the left or right according to the children order Describes a widget state. Widget states are used to match the widget against CSS pseudo-classes. Note that GTK extends the regular CSS classes and sometimes uses different names. State during normal operation Widget is active Widget has a mouse pointer over it Widget is selected Widget is insensitive Widget is inconsistent Widget has the keyboard focus Widget is in a background toplevel window Widget is in left-to-right text direction Widget is in right-to-left text direction Widget is a link The location the widget points to has already been visited Widget is checked Widget is highlighted as a drop target for DND Widget has the visible focus Widget contains the keyboard focus A `GtkStatusbar` widget is usually placed along the bottom of an application's main [class@Gtk.Window]. <picture> <source srcset="statusbar-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkStatusbar" src="statusbar.png"> </picture> A `GtkStatusBar` may provide a regular commentary of the application's status (as is usually the case in a web browser, for example), or may be used to simply output a message when the status changes, (when an upload is complete in an FTP client, for example). Status bars in GTK maintain a stack of messages. The message at the top of the each bar’s stack is the one that will currently be displayed. Any messages added to a statusbar’s stack must specify a context id that is used to uniquely identify the source of a message. This context id can be generated by [method@Gtk.Statusbar.get_context_id], given a message and the statusbar that it will be added to. Note that messages are stored in a stack, and when choosing which message to display, the stack structure is adhered to, regardless of the context identifier of a message. One could say that a statusbar maintains one stack of messages for display purposes, but allows multiple message producers to maintain sub-stacks of the messages they produced (via context ids). Status bars are created using [ctor@Gtk.Statusbar.new]. Messages are added to the bar’s stack with [method@Gtk.Statusbar.push]. The message at the top of the stack can be removed using [method@Gtk.Statusbar.pop]. A message can be removed from anywhere in the stack if its message id was recorded at the time it was added. This is done using [method@Gtk.Statusbar.remove]. ## CSS node `GtkStatusbar` has a single CSS node with name `statusbar`. This widget will be removed in GTK 5 Creates a new `GtkStatusbar` ready for messages. This widget will be removed in GTK 5 the new `GtkStatusbar` Returns a new context identifier, given a description of the actual context. Note that the description is not shown in the UI. This widget will be removed in GTK 5 an integer id a `GtkStatusbar` textual description of what context the new message is being used in Removes the first message in the `GtkStatusbar`’s stack with the given context id. Note that this may not change the displayed message, if the message at the top of the stack has a different context id. This widget will be removed in GTK 5 a `GtkStatusbar` a context identifier Pushes a new message onto a statusbar’s stack. This widget will be removed in GTK 5 a message id that can be used with [method@Gtk.Statusbar.remove]. a `GtkStatusbar` the message’s context id, as returned by gtk_statusbar_get_context_id() the message to add to the statusbar Forces the removal of a message from a statusbar’s stack. The exact @context_id and @message_id must be specified. This widget will be removed in GTK 5 a `GtkStatusbar` a context identifier a message identifier, as returned by [method@Gtk.Statusbar.push] Forces the removal of all messages from a statusbar's stack with the exact @context_id. This widget will be removed in GTK 5 a `GtkStatusbar` a context identifier Emitted whenever a new message is popped off a statusbar's stack. This widget will be removed in GTK 5 the context id of the relevant message/statusbar the message that was just popped Emitted whenever a new message gets pushed onto a statusbar's stack. This widget will be removed in GTK 5 the context id of the relevant message/statusbar the message that was pushed Determines whether to include items by comparing strings to a fixed search term. The strings are obtained from the items by evaluating an expression set with [method@Gtk.StringFilter.set_expression], and they are compared against a search term set with [method@Gtk.StringFilter.set_search]. `GtkStringFilter` has several different modes of comparison - it can match the whole string, just a prefix, or any substring. Use [method@Gtk.StringFilter.set_match_mode] choose a mode. It is also possible to make case-insensitive comparisons, with [method@Gtk.StringFilter.set_ignore_case]. Creates a new string filter. You will want to set up the filter by providing a string to search for and by providing a property to look up on the item. a new `GtkStringFilter` the expression to evaluate Gets the expression that the string filter uses to obtain strings from items. the expression a string filter Returns whether the filter ignores case differences. true if the filter ignores case a string filter Returns the match mode that the filter is using. the match mode of the filter a string filter Gets the search term. the search term a string filter Sets the expression that the string filter uses to obtain strings from items. The expression must have a value type of `G_TYPE_STRING`. a string filter the expression Sets whether the filter ignores case differences. a string filter true to ignore case Sets the match mode for the filter. a string filter the new match mode Sets the string to search for. a string filter the string to search for The expression to evaluate on each item to get a string to compare with. If matching is case sensitive. If exact matches are necessary or if substrings are allowed. The search term. Specifies how search strings are matched inside text. The search string and text must match exactly The search string must be contained as a substring inside the text The text must begin with the search string A list model that wraps an array of strings. The objects in the model are of type [class@Gtk.StringObject] and have a "string" property that can be used inside expressions. `GtkStringList` is well-suited for any place where you would typically use a `char*[]`, but need a list model. ## GtkStringList as GtkBuildable The `GtkStringList` implementation of the `GtkBuildable` interface supports adding items directly using the `<items>` element and specifying `<item>` elements for each item. Each `<item>` element supports the regular translation attributes “translatable”, “context” and “comments”. Here is a UI definition fragment specifying a `GtkStringList` ```xml <object class="GtkStringList"> <items> <item translatable="yes">Factory</item> <item translatable="yes">Home</item> <item translatable="yes">Subway</item> </items> </object> ``` Creates a new `GtkStringList` with the given @strings. a new `GtkStringList` The strings to put in the model Appends @string to @self. The @string will be copied. See [method@Gtk.StringList.take] for a way to avoid that. a `GtkStringList` the string to insert Gets the position of the @string in @self. If @self does not contain @string item, `G_MAXUINT` is returned. the position of the string a `GtkStringList` the string to find Gets the string that is at @position in @self. If @self does not contain @position items, %NULL is returned. This function returns the const char *. To get the object wrapping it, use g_list_model_get_item(). the string at the given position a `GtkStringList` the position to get the string for Removes the string at @position from @self. @position must be smaller than the current length of the list. a `GtkStringList` the position of the string that is to be removed Changes @self by removing @n_removals strings and adding @additions to it. This function is more efficient than [method@Gtk.StringList.append] and [method@Gtk.StringList.remove], because it only emits the ::items-changed signal once for the change. This function copies the strings in @additions. The parameters @position and @n_removals must be correct (ie: @position + @n_removals must be less than or equal to the length of the list at the time this function is called). a `GtkStringList` the position at which to make the change the number of strings to remove The strings to add Adds @string to self at the end, and takes ownership of it. This variant of [method@Gtk.StringList.append] is convenient for formatting strings: ```c gtk_string_list_take (self, g_strdup_print ("%d dollars", lots)); ``` a `GtkStringList` the string to insert The type of items. See [method@Gio.ListModel.get_item_type]. The number of items. See [method@Gio.ListModel.get_n_items]. The strings in the model. The type of items in a `GtkStringList`. A `GtkStringObject` is a wrapper around a `const char*`; it has a [property@Gtk.StringObject:string] property that can be used for property bindings and expressions. Wraps a string in an object for use with `GListModel`. a new `GtkStringObject` The string to wrap Returns the string contained in a `GtkStringObject`. the string of @self a `GtkStringObject` The string. Sorts items by comparing strings. To obtain the strings to compare, this sorter evaluates a [class@Gtk.Expression]. It does the comparison in a linguistically correct way using the current locale by normalizing Unicode strings and possibly case-folding them before performing the comparison. Creates a new string sorter that compares items using the given @expression. Unless an expression is set on it, this sorter will always compare items as invalid. a new `GtkStringSorter` The expression to evaluate Gets which collation method the sorter uses. The collation method a `GtkStringSorter` Gets the expression that is evaluated to obtain strings from items. a `GtkExpression` a `GtkStringSorter` Gets whether the sorter ignores case differences. %TRUE if @self is ignoring case differences a `GtkStringSorter` Sets the collation method to use for sorting. a `GtkStringSorter` the collation method Sets the expression that is evaluated to obtain strings from items. The expression must have the type %G_TYPE_STRING. a `GtkStringSorter` a `GtkExpression` Sets whether the sorter will ignore case differences. a `GtkStringSorter` %TRUE to ignore case differences The collation method to use for sorting. The `GTK_COLLATION_NONE` value is useful when the expression already returns collation keys, or strings that need to be compared byte-by-byte. The default value, `GTK_COLLATION_UNICODE`, compares strings according to the [Unicode collation algorithm](https://www.unicode.org/reports/tr10/). The expression to evaluate on item to get a string to compare with. If sorting is case sensitive. `GtkStyleContext` stores styling information affecting a widget. In order to construct the final style information, `GtkStyleContext` queries information from all attached `GtkStyleProviders`. Style providers can be either attached explicitly to the context through [method@Gtk.StyleContext.add_provider], or to the display through [func@Gtk.StyleContext.add_provider_for_display]. The resulting style is a combination of all providers’ information in priority order. For GTK widgets, any `GtkStyleContext` returned by [method@Gtk.Widget.get_style_context] will already have a `GdkDisplay` and RTL/LTR information set. The style context will also be updated automatically if any of these settings change on the widget. ## Style Classes Widgets can add style classes to their context, which can be used to associate different styles by class. The documentation for individual widgets lists which style classes it uses itself, and which style classes may be added by applications to affect their appearance. # Custom styling in UI libraries and applications If you are developing a library with custom widgets that render differently than standard components, you may need to add a `GtkStyleProvider` yourself with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK priority, either a `GtkCssProvider` or a custom object implementing the `GtkStyleProvider` interface. This way themes may still attempt to style your UI elements in a different way if needed so. If you are using custom styling on an applications, you probably want then to make your style information prevail to the theme’s, so you must use a `GtkStyleProvider` with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION priority, keep in mind that the user settings in `XDG_CONFIG_HOME/gtk-4.0/gtk.css` will still take precedence over your changes, as it uses the %GTK_STYLE_PROVIDER_PRIORITY_USER priority. The relevant API has been moved to [class@Gtk.Widget] where applicable; otherwise, there is no replacement for querying the style machinery. Stylable UI elements should use widgets. Adds a global style provider to @display, which will be used in style construction for all `GtkStyleContexts` under @display. GTK uses this to make styling information from `GtkSettings` available. Note: If both priorities are the same, A `GtkStyleProvider` added through [method@Gtk.StyleContext.add_provider] takes precedence over another added through this function. a `GdkDisplay` a `GtkStyleProvider` the priority of the style provider. The lower it is, the earlier it will be used in the style construction. Typically this will be in the range between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and %GTK_STYLE_PROVIDER_PRIORITY_USER Removes @provider from the global style providers list in @display. a `GdkDisplay` a `GtkStyleProvider` Adds a style class to @context, so later uses of the style context will make use of this new class for styling. In the CSS file format, a `GtkEntry` defining a “search” class, would be matched by: ```css entry.search { ... } ``` While any widget defining a “search” class would be matched by: ```css .search { ... } ``` Use [method@Gtk.Widget.add_css_class] instead a `GtkStyleContext` class name to use in styling Adds a style provider to @context, to be used in style construction. Note that a style provider added by this function only affects the style of the widget to which @context belongs. If you want to affect the style of all widgets, use [func@Gtk.StyleContext.add_provider_for_display]. Note: If both priorities are the same, a `GtkStyleProvider` added through this function takes precedence over another added through [func@Gtk.StyleContext.add_provider_for_display]. Use style classes instead a `GtkStyleContext` a `GtkStyleProvider` the priority of the style provider. The lower it is, the earlier it will be used in the style construction. Typically this will be in the range between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and %GTK_STYLE_PROVIDER_PRIORITY_USER Gets the border for a given state as a `GtkBorder`. This api will be removed in GTK 5 a `GtkStyleContext` return value for the border settings Gets the foreground color for a given state. Use [method@Gtk.Widget.get_color] instead a `GtkStyleContext` return value for the foreground color Returns the `GdkDisplay` to which @context is attached. Use [method@Gtk.Widget.get_display] instead a `GdkDisplay`. a `GtkStyleContext` Gets the margin for a given state as a `GtkBorder`. This api will be removed in GTK 5 a `GtkStyleContext` return value for the margin settings Gets the padding for a given state as a `GtkBorder`. This api will be removed in GTK 5 a `GtkStyleContext` return value for the padding settings Returns the scale used for assets. Use [method@Gtk.Widget.get_scale_factor] instead the scale a `GtkStyleContext` Returns the state used for style matching. This method should only be used to retrieve the `GtkStateFlags` to pass to `GtkStyleContext` methods, like [method@Gtk.StyleContext.get_padding]. If you need to retrieve the current state of a `GtkWidget`, use [method@Gtk.Widget.get_state_flags]. Use [method@Gtk.Widget.get_state_flags] instead the state flags a `GtkStyleContext` Returns %TRUE if @context currently has defined the given class name. Use [method@Gtk.Widget.has_css_class] instead %TRUE if @context has @class_name defined a `GtkStyleContext` a class name Looks up and resolves a color name in the @context color map. This api will be removed in GTK 5 %TRUE if @color_name was found and resolved, %FALSE otherwise a `GtkStyleContext` color name to lookup Return location for the looked up color Removes @class_name from @context. Use [method@Gtk.Widget.remove_css_class] instead a `GtkStyleContext` class name to remove Removes @provider from the style providers list in @context. a `GtkStyleContext` a `GtkStyleProvider` Restores @context state to a previous stage. See [method@Gtk.StyleContext.save]. This API will be removed in GTK 5 a `GtkStyleContext` Saves the @context state. This allows temporary modifications done through [method@Gtk.StyleContext.add_class], [method@Gtk.StyleContext.remove_class], [method@Gtk.StyleContext.set_state] to be quickly reverted in one go through [method@Gtk.StyleContext.restore]. The matching call to [method@Gtk.StyleContext.restore] must be done before GTK returns to the main loop. This API will be removed in GTK 5 a `GtkStyleContext` Attaches @context to the given display. The display is used to add style information from “global” style providers, such as the display's `GtkSettings` instance. If you are using a `GtkStyleContext` returned from [method@Gtk.Widget.get_style_context], you do not need to call this yourself. You should not use this api a `GtkStyleContext` a `GdkDisplay` Sets the scale to use when getting image assets for the style. You should not use this api a `GtkStyleContext` scale Sets the state to be used for style matching. You should not use this api a `GtkStyleContext` state to represent Converts the style context into a string representation. The string representation always includes information about the name, state, id, visibility and style classes of the CSS node that is backing @context. Depending on the flags, more information may be included. This function is intended for testing and debugging of the CSS implementation in GTK. There are no guarantees about the format of the returned string, it may change. This api will be removed in GTK 5 a newly allocated string representing @context a `GtkStyleContext` Flags that determine what to print The display of the style context. Flags that modify the behavior of gtk_style_context_to_string(). New values may be added to this enumeration. Default value. Print the entire tree of CSS nodes starting at the style context's node Show the values of the CSS properties for each node Show information about what changes affect the styles An interface for style information used by [class@Gtk.StyleContext]. See [method@Gtk.StyleContext.add_provider] and [func@Gtk.StyleContext.add_provider_for_display] for adding `GtkStyleProviders`. GTK uses the `GtkStyleProvider` implementation for CSS in [class@Gtk.CssProvider]. A paintable implementation that renders SVG, with animations. `GtkSvg` objects are created by parsing a subset of SVG, including SVG animations. `GtkSvg` fills or strokes paths with symbolic or fixed colors. It can have multiple states, and paths can be included in a subset of the states. The special 'empty' state is always available. States can have animations, and the transition between different states can also be animated. To show a static SVG image, it is enough to load the the SVG and use it like any other paintable. To play an SVG animation, use [method@Gtk.Svg.set_frame_clock] to connect the paintable to a frame clock, and call [method@Gtk.Svg.play] after loading the SVG. The animation can be paused using [method@Gtk.Svg.pause]. To find out what states a `GtkSvg` has, use [method@Gtk.Svg.get_n_states]. To set the current state, use [method@Gtk.Svg.set_state]. ## Error handling Loading an SVG into `GtkSvg` will always produce a (possibly empty) paintable. GTK will drop things that it can't handle and try to make sense of the rest. To track errors during parsing or rendering, connect to the [signal@Gtk.Svg::error] signal. For parsing errors in the `GTK_SVG_ERROR` domain, the functions [func@Gtk.SvgError.get_start], [func@Gtk.SvgError.get_end], [func@Gtk.SvgError.get_element] and [func@Gtk.SvgError.get_attribute] can be used to obtain information about where the error occurred. ## The supported subset of SVG The paintable supports much of SVG 2, with some exceptions. Among the graphical elements, `<textPath>` and `<foreignObject>` are not supported. Among the structural elements, `<a>` and `<view>` are not supported. All filter functions are supported, plus a custom `alpha-level()` function, which implements one particular case of feComponentTransfer. In the `<filter>` element, the following primitives are not supported: feConvolveMatrix, feDiffuseLighting, feMorphology, feSpecularLighting and feTurbulence. Support for the `mask` attribute is limited to just a url referring to the `<mask>` element by ID. In animation elements, the parsing of `begin` and `end` attributes is limited, and the `min` and `max` attributes are not supported. Lastly, there is only minimal CSS support (the style attribute, but not `<style>`), and no interactivity. ## SVG Extensions The paintable supports a number of [custom attributes](icon-format.html) that offer a convenient way to define states, transitions and animations. For example, <circle cx='5' cy='5' r='5' gpa:states='0 1' gpa:animation-type='automatic' gpa:animation-direction='segment' gpa:animation-duration='600ms'/> defines the circle to be shown in states 0 and 1, and animates a segment of the circle. <image src="svg-renderer1.svg"> Note that the generated animations assume a `pathLengh` value of 1. Setting `pathLength` in your SVG is therefore going to interfere with generated animations. To connect general SVG animations to the states of the paintable, use the custom `gpa:states(...)` condition in the `begin` and `end` attributes of SVG animation elements. For example, <animate href='path1' attributeName='fill' begin='gpa:states(0).begin' dur='300ms' fill='freeze' from='black' to='magenta'/> will make the fill color of path1 transition from black to magenta when the renderer enters state 0. <image src="svg-renderer2.svg"> The `gpa:states(...)` condition triggers for upcoming state changes as well, to support fade-out transitions. For example, <animate href='path1' attributeName='opacity' begin='gpa:states(0).end -300ms' dur='300ms' fill='freeze' from='1' to='0'/> will start a fade-out of path1 300ms before state 0 ends. In addition to the `gpa:fill` and `gpa:stroke` attributes, symbolic colors can also be specified as a custom paint server reference, like this: `url(gpa:#warning)`. This works in `fill` and `stroke` attributes, but also when specifying colors in SVG animation attributes like `to` or `values`. Note that the SVG syntax allows for a fallback RGB color to be specified after the url, for compatibility with other SVG consumers: fill='url(gpa:#warning) orange' In contrast to SVG 1.1 and 2.0, we allow the `transform` attribute to be animated with `<animate>`. Creates a new, empty SVG paintable. the paintable Parses the SVG data in @bytes and creates a paintable. the paintable the data Parses the SVG data in the resource and creates a paintable. the paintable the resource path Returns the currently enabled features. the enabled features an SVG paintable Gets the number of states defined in the SVG. Note that there is always an empty state, which does not count towards this number. If this function returns the value N, the meaningful states of the SVG are 0, 1, ..., N - 1 and `GTK_SVG_STATE_EMPTY`. the number of states an SVG paintable Gets the current state of the paintable. the state an SVG paintable Gets the value of the weight property. the weight an SVG paintable Loads SVG content into an existing SVG paintable. To track errors while loading SVG content, connect to the [signal@Gtk.Svg::error] signal. This clears any previously loaded content. an SVG paintable the data to load Loads SVG content into an existing SVG paintable. To track errors while loading SVG content, connect to the [signal@Gtk.Svg::error] signal. This clears any previously loaded content. an SVG paintable the resource path Stop any playing animations and state transitions. Animations can be paused and started repeatedly. an SVG paintable Start playing animations and state transitions. Animations can be paused and started repeatedly. an SVG paintable Serializes the content of the renderer as SVG. The SVG will be similar to the orignally loaded one, but is not guaranteed to be 100% identical. This function serializes the DOM, i.e. the results of parsing the SVG. It does not reflect the effect of applying animations. the serialized contents an SVG paintable Enables or disables features of the SVG paintable. By default, all features are enabled. Note that this call only has an effect before the SVG is loaded. an SVG paintable features to enable Sets a frame clock. Without a frame clock, GtkSvg will not advance animations. an SVG paintable the frame clock Sets the state of the paintable. Use [method@Gtk.Svg.get_n_states] to find out what states @self has. If the paintable is currently playing, the state change will apply transitions that are defined in the SVG. If the paintable is not playing, the state change will take effect instantaneously. an SVG paintable the state to set, as a value between 0 and 63, or `(unsigned int) -1` Sets the weight that is used when rendering. The default value of -1 means to use the font weight from CSS. an SVG paintable the font weight, as a value between -1 and 1000 Serializes the paintable, and saves the result to a file. true, unless an error occurred an SVG paintable the file to save to Enabled features for this paintable. Note that features have to be set before loading SVG data to take effect. Whether the paintable is currently animating its content. To set this property, use the [method@Gtk.Svg.play] and [method@Gtk.Svg.pause] functions. Resource to load SVG data from. This property is meant to create a paintable from a resource in ui files. The current state of the renderer. This can be a number between 0 and 63, or the special value `(unsigned int) -1` to indicate the 'empty' state in which nothing is drawn. If not set to -1, this value overrides the weight used when rendering the paintable. Signals that an error occurred. Errors can occur both during parsing and during rendering. The expected error values are in the [error@Gtk.SvgError] enumeration, context information about the location of parsing errors can be obtained with the various `gtk_svg_error` functions. Parsing errors are never fatal, so the parsing will resume after the error. Errors may however cause parts of the given data or even all of it to not be parsed at all. So it is a useful idea to check that the parsing succeeds by connecting to this signal. ::: note This signal is emitted in the middle of parsing or rendering, and if you handle it, you must be careful. Logging the errors you receive is fine, but modifying the widget hierarchy or changing the paintable state definitively isn't. If in doubt, defer to an idle. the error Error codes in the `GTK_SVG_ERROR` domain for errors that happen during parsing or rendering of SVG. The XML syntax is broken in some way An XML element is invalid (either because it is not part of SVG, or because it is in the wrong place, or because it not implemented in GTK) An attribute is invalid (either because it is not part of SVG, or because it is not implemented in GTK, or its value is problematic) A required attribute is missing A reference does not point to a suitable element An animation could not be updated Rendering is not according to expecations Returns context information about what XML attribute the parsing error occurred in. the attribute name an error in the [error@Gtk.SvgError] domain Returns context information about what XML element the parsing error occurred in. the element name an error in the [error@Gtk.SvgError] domain Returns context information about the end position in the document where the parsing error occurred. the [struct@Gtk.SvgLocation] an error in the [error@Gtk.SvgError] domain Returns context information about the start position in the document where the parsing error occurred. the [struct@Gtk.SvgLocation] an error in the [error@Gtk.SvgError] domain Features of the SVG renderer that can be enabled or disabled. By default, all features except `GTK_SVG_TRADITIONAL_SYMBOLIC` are enabled. New values may be added in the future. Whether to run animations. If disabled, state changes are applied without transitions Whether to use system resources, such as fonts. If disabled, only embedded fonts are used Whether to load external resources, such as images. If disabled, only embedded images are loaded Whether to allow gpa extensions, such as states and transitions This feature is meant for compatibility with old symbolic icons. If this is enabled, fill and stroke attributes are ignored. The used colors are derived from symbolic style classes if present, and the default fill color is the symbolic foreground color. Provides information about a location in an SVG document. The information should be considered approximate; it is meant to provide feedback for errors in an editor. the byte index in document. If unknown, this will be zero (which is also a valid value, but only if all three values are zero) the line index in the document, 0-based the char index in the line, 0-based Shows a "light switch" that has two states: on or off. <picture> <source srcset="switch-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkSwitch" src="switch.png"> </picture> The user can control which state should be active by clicking the empty area, or by dragging the slider. `GtkSwitch` can also express situations where the underlying state changes with a delay. In this case, the slider position indicates the user's recent change (represented by the [property@Gtk.Switch:active] property), while the trough color indicates the present underlying state (represented by the [property@Gtk.Switch:state] property). <picture> <source srcset="switch-state-dark.png" media="(prefers-color-scheme: dark)"> <img alt="GtkSwitch with delayed state change" src="switch-state.png"> </picture> See [signal@Gtk.Switch::state-set] for details. # Shortcuts and Gestures `GtkSwitch` supports pan and drag gestures to move the slider. # CSS nodes ``` switch ├── image ├── image ╰── slider ``` `GtkSwitch` has four css nodes, the main node with the name switch and subnodes for the slider and the on and off images. Neither of them is using any style classes. # Accessibility `GtkSwitch` uses the [enum@Gtk.AccessibleRole.switch] role. Creates a new `GtkSwitch` widget. the newly created `GtkSwitch` instance Gets whether the `GtkSwitch` is in its “on” or “off” state. %TRUE if the `GtkSwitch` is active, and %FALSE otherwise a `GtkSwitch` Gets the underlying state of the `GtkSwitch`. the underlying state a `GtkSwitch` Changes the state of @self to the desired one. a `GtkSwitch` %TRUE if @self should be active, and %FALSE otherwise Sets the underlying state of the `GtkSwitch`. This function is typically called from a [signal@Gtk.Switch::state-set] signal handler in order to set up delayed state changes. See [signal@Gtk.Switch::state-set] for details. a `GtkSwitch` the new state Whether the `GtkSwitch` widget is in its on or off state. The backend state that is controlled by the switch. Applications should usually set the [property@Gtk.Switch:active] property, except when indicating a change to the backend state which occurs separately from the user's interaction. See [signal@Gtk.Switch::state-set] for details. Emitted to animate the switch. Applications should never connect to this signal, but use the [property@Gtk.Switch:active] property. Emitted to change the underlying state. The ::state-set signal is emitted when the user changes the switch position. The default handler calls [method@Gtk.Switch.set_state] with the value of @state. To implement delayed state change, applications can connect to this signal, initiate the change of the underlying state, and call [method@Gtk.Switch.set_state] when the underlying state change is complete. The signal handler should return %TRUE to prevent the default handler from running. %TRUE to stop the signal emission the new state of the switch The indexes of colors passed to symbolic color rendering, such as [vfunc@Gtk.SymbolicPaintable.snapshot_symbolic]. More values may be added over time. The default foreground color Indication color for errors Indication color for warnings Indication color for success The system accent color. An interface that supports symbolic colors in paintables. `GdkPaintable`s implementing the interface will have the [vfunc@Gtk.SymbolicPaintable.snapshot_symbolic] function called and have the colors for drawing symbolic icons passed. At least 5 colors are guaranteed to be passed every time. These 5 colors are the foreground color, and the colors to use for errors, warnings and success information in that order, followed by the system accent color. The system accent color has been added in GTK 4.22. More colors may be added in the future. Snapshots the paintable with the given colors. If less than 5 colors are provided, GTK will pad the array with default colors. a `GtkSymbolicPaintable` a `GdkSnapshot` to snapshot to width to snapshot in height to snapshot in a pointer to an array of colors The number of colors Snapshots the paintable with the given colors and weight. If less than 5 colors are provided, GTK will pad the array with default colors. a `GtkSymbolicPaintable` a `GdkSnapshot` to snapshot to width to snapshot in height to snapshot in a pointer to an array of colors The number of colors The font weight to use (from 1 to 1000, with default 400) Snapshots the paintable with the given colors. If less than 5 colors are provided, GTK will pad the array with default colors. a `GtkSymbolicPaintable` a `GdkSnapshot` to snapshot to width to snapshot in height to snapshot in a pointer to an array of colors The number of colors Snapshots the paintable with the given colors and weight. If less than 5 colors are provided, GTK will pad the array with default colors. a `GtkSymbolicPaintable` a `GdkSnapshot` to snapshot to width to snapshot in height to snapshot in a pointer to an array of colors The number of colors The font weight to use (from 1 to 1000, with default 400) The list of virtual functions for the `GtkSymbolicPaintable` interface. No function must be implemented, default implementations exist for each one. Snapshot the paintable using the given colors. See `GtkSymbolicPaintable::snapshot_symbolic()` for details. If this function is not implemented, [vfunc@Gdk.Paintable.snapshot] will be called. a `GtkSymbolicPaintable` a `GdkSnapshot` to snapshot to width to snapshot in height to snapshot in a pointer to an array of colors The number of colors Like @snapshot_symbolic, but additionally takes a font weight argument. Since: 4.22 a `GtkSymbolicPaintable` a `GdkSnapshot` to snapshot to width to snapshot in height to snapshot in a pointer to an array of colors The number of colors The font weight to use (from 1 to 1000, with default 400) Values that can be passed to the [vfunc@Gtk.Widget.system_setting_changed] vfunc. The values indicate which system setting has changed. Widgets may need to drop caches, or react otherwise. Most of the values correspond to [class@Settings] properties. More values may be added over time. the [property@Gtk.Settings:gtk-xft-dpi] setting has changed The [property@Gtk.Settings:gtk-font-name] setting has changed The font configuration has changed in a way that requires text to be redrawn. This can be any of the [property@Gtk.Settings:gtk-xft-antialias], [property@Gtk.Settings:gtk-xft-hinting], [property@Gtk.Settings:gtk-xft-hintstyle], [property@Gtk.Settings:gtk-xft-rgba] or [property@Gtk.Settings:gtk-fontconfig-timestamp] settings The display has changed The icon theme has changed in a way that requires icons to be looked up again The priority at which the text view validates onscreen lines in an idle job in the background. Uses the default sort function in a [iface@Gtk.TreeSortable]. See also: [method@Gtk.TreeSortable.set_sort_column_id] There is no replacement Disables sorting in a [iface@Gtk.TreeSortable]. See also: [method@Gtk.TreeSortable.set_sort_column_id] There is no replacement A single-line text entry. `GtkText` is the common implementation of single-line text editing that is shared between [class@Gtk.Entry], [class@Gtk.PasswordEntry], [class@Gtk.SpinButton], and other widgets. In all of these, a `GtkText` instance is used as the delegate for the [iface@Gtk.Editable] implementation. A large number of key bindings s supported by default. If the entered text is longer than the allocation of the widget, the widget will scroll so that the cursor position is visible. When using an entry for passwords and other sensitive information, it can be put into “password mode” using [method@Gtk.Text.set_visibility]. In this mode, entered text is displayed using an “invisible” character. By default, GTK picks the best invisible character that is available in the current font, but it can be changed with [method@Gtk.Text.set_invisible_char]. If you want to add icons or progress display in an entry, look at [class@Gtk.Entry]. There are other alternatives for more specialized use cases, such as [class@Gtk.SearchEntry]. If you need multi-line editable text, use [class@Gtk.TextView]. # Shortcuts and Gestures `GtkText` supports the following keyboard shortcuts: - <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. - <kbd>Ctrl</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&sol;</kbd> selects all the text. - <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&bsol;</kbd> unselects all. - <kbd>Ctrl</kbd>+<kbd>Z</kbd> undoes the last modification. - <kbd>Ctrl</kbd>+<kbd>Y</kbd> or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Z</kbd> redoes the last undone modification. - <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd> toggles the text direction. - <kbd>Clear</kbd> clears the content. Additionally, the following signals have default keybindings: - [signal@Gtk.Text::activate] - [signal@Gtk.Text::backspace] - [signal@Gtk.Text::copy-clipboard] - [signal@Gtk.Text::cut-clipboard] - [signal@Gtk.Text::delete-from-cursor] - [signal@Gtk.Text::insert-emoji] - [signal@Gtk.Text::move-cursor] - [signal@Gtk.Text::paste-clipboard] - [signal@Gtk.Text::toggle-overwrite] # Actions `GtkText` defines a set of built-in actions: - `clipboard.copy` copies the contents to the clipboard. - `clipboard.cut` copies the contents to the clipboard and deletes it from the widget. - `clipboard.paste` inserts the contents of the clipboard into the widget. - `menu.popup` opens the context menu. - `misc.insert-emoji` opens the Emoji chooser. - `misc.toggle-visibility` toggles the `GtkText`:visibility property. - `misc.toggle-direction` toggles the text direction. - `selection.delete` deletes the current selection. - `selection.select-all` selects all of the widgets content. - `text.redo` redoes the last change to the contents. - `text.undo` undoes the last change to the contents. - `text.clear` removes all content. # CSS nodes ``` text[.read-only] ├── placeholder ├── undershoot.left ├── undershoot.right ├── [selection] ├── [cursor-handle[.top] ├── [cursor-handle.bottom] ├── [block-cursor] ├── [cursor-handle[.top/.bottom][.insertion-cursor]] ╰── [window.popup] ``` `GtkText` has a main node with the name `text`. Depending on the properties of the widget, the `.read-only` style class may appear. When the entry has a selection, it adds a subnode with the name `selection`. When the entry is in overwrite mode, it adds a subnode with the name `block-cursor` that determines how the block cursor is drawn. The CSS node for a context menu is added as a subnode with the name `popup`. The `undershoot` nodes are used to draw the underflow indication when content is scrolled out of view. These nodes get the `.left` or `.right` style class added depending on where the indication is drawn. When touch is used and touch selection handles are shown, they are using CSS nodes with name `cursor-handle`. They get the `.top` or `.bottom` style class depending on where they are shown in relation to the selection. If there is just a single handle for the text cursor, it gets the style class `.insertion-cursor`. # Accessibility `GtkText` uses the [enum@Gtk.AccessibleRole.none] role, which causes it to be skipped for accessibility. This is because `GtkText` is expected to be used as a delegate for a `GtkEditable` implementation that will be represented to accessibility. Creates a new `GtkText`. the new `GtkText` Creates a new `GtkText` with the specified buffer. a new `GtkText` the buffer to use Determines the positions of the strong and weak cursors for a given character position. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction are inserted. The rectangle positions are in widget coordinates. a text widget the character position location to store the strong cursor position location to store the weak cursor position Returns whether pressing <kbd>Enter</kbd> will activate the default widget for the window containing the widget. See [method@Gtk.Text.set_activates_default]. true if @self will activate the default widget a text widget Gets the attribute list that was set on the text widget. See [method@Gtk.Text.set_attributes]. the attribute list a text widget Get the entry buffer object which holds the text for this widget. the entry buffer object a text widget Returns whether Emoji completion is enabled. true if Emoji completion is enabled a text widget Gets the extra menu model of the text widget. See [method@Gtk.Text.set_extra_menu]. the menu model a text widget Gets the input hints of the text widget. the input hints a text widget Gets the input purpose of the text widget. the input purpose a text widget Retrieves the character displayed when visibility is set to false. Note that GTK does not compute this value unless it needs it, so the value returned by this function is not very useful unless it has been explicitly set with [method@Gtk.Text.set_invisible_char]. the current invisible char, or 0, if @text does not show invisible text at all a text widget Retrieves the maximum allowed length of the contents. See [method@Gtk.Text.set_max_length]. This is equivalent to getting @self's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.get_max_length] on it. the maximum allowed number of characters, or 0 if there is no limit a text widget Gets whether text is overwritten when typing. See [method@Gtk.Text.set_overwrite_mode]. whether text is overwritten when typing a text widget Retrieves the text that will be displayed when the text widget is empty and unfocused See [method@Gtk.Text.set_placeholder_text]. the placeholder text a text widget Returns whether the text widget will grow and shrink with the content. true if @self will propagate the text width a text widget Gets the tab stops for the text widget. See [method@Gtk.Text.set_tabs]. the tab stops a text widget Retrieves the length of the contents. This is equivalent to getting @self's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.get_length] on it. the length of the contents, in characters a text widget Returns whether pasted text will be truncated to the first line. true if @self will truncate pasted multi-line text a text widget Retrieves whether the text is visible. true if the text is visible a text widget Causes the text widget to have the keyboard focus. It behaves like [method@Gtk.Widget.grab_focus], except that it does not select the contents of @self. You only want to call this on some special entries which the user usually doesn't want to replace all text in, such as search-as-you-type entries. true if focus is now inside @self a text widget Sets whether pressing <kbd>Enter</kbd> will activate the default widget. This usually means that the dialog containing @self will be closed, since the default widget is usually one of the dialog buttons. a text widget true to activate window’s default widget on <kbd>Enter</kbd> keypress Apply attributes to the contents of the text widget. a text widget a list of style attributes Set the entry buffer object which holds the text for this widget. a text widget an entry buffer object Sets whether Emoji completion is enabled. If it is, typing ':', followed by a recognized keyword, will pop up a window with suggested Emojis matching the keyword. a text widget true to enable Emoji completion Sets a menu model to add to the context menu of the text widget. a text widget a menu model Sets hints that allow input methods to fine-tune their behaviour. a text widget input hints Sets the input purpose of the text widget. The input purpose can be used by on-screen keyboards and other input methods to adjust their behaviour. a text widget the input purpose Sets the character to use when in “password mode”. By default, GTK picks the best invisible char available in the current font. If you set the invisible char to 0, then the user will get no feedback at all; there will be no text on the screen as they type. a text widget a Unicode character Sets the maximum allowed length of the contents. If the current contents are longer than the given length, they will be truncated to fit. This is equivalent to getting @self's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.set_max_length] on it. a text widget the maximum length of the text, or 0 for no maximum. (other than the maximum length of entries.) The value passed in will be clamped to the range 0-65536 Sets whether the text is overwritten when typing. a text widget new value Sets the text to be displayed when the text widget is empty and unfocused. This can be used to give a visual hint of the expected contents of the text widget. a text widget a string to be displayed when @self is empty and unfocused Sets whether the text widget should grow and shrink with the content. a text widget true to propagate the text width Sets tab stops for the text widget. a text widget tab stops Sets whether pasted text should be truncated to the first line. a text widget true to truncate multi-line text Sets whether the contents of the text widget are visible or not. When visibility is set to false, characters are displayed as the invisible char, and it will also appear that way when the text in the widget is copied to the clipboard. By default, GTK picks the best invisible character available in the current font, but it can be changed with [method@Gtk.Text.set_invisible_char]. Note that you probably want to set [property@Gtk.Text:input-purpose] to [enum@Gtk.InputPurpose.password] or [enum@Gtk.InputPurpose.pin] to inform input methods about the purpose of this widget, in addition to setting visibility to false. a text widget true if the contents of the text widget are displayed as plain text Unsets the invisible char. After calling this, the default invisible char is used again. a text widget Whether to activate the default widget when <kbd>Enter</kbd> is pressed. A list of Pango attributes to apply to the text. This is mainly useful to change the size or weight of the text. The `PangoAttribute`'s @start_index and @end_index must refer to the `GtkEntryBuffer` text, i.e. without the preedit string. The `GtkEntryBuffer` object which stores the text. Whether to suggest Emoji replacements. A menu model whose contents will be appended to the context menu. Which input method module should be used. See [class@Gtk.IMMulticontext]. Setting this to a non-`NULL` value overrides the system-wide input method. See the [property@Gtk.Settings:gtk-im-module] setting. Additional hints that allow input methods to fine-tune their behaviour. The purpose of this text field. This information can be used by on-screen keyboards and other input methods to adjust their behaviour. Note that setting the purpose to [enum@Gtk.InputPurpose.password] or [enum@Gtk.InputPurpose.pin] is independent from setting [property@Gtk.Text:visibility]. The character to used when masking contents (in “password mode”). Whether the invisible char has been set. Maximum number of characters that are allowed. Zero indicates no limit. If text is overwritten when typing. The text that will be displayed in the `GtkText` when it is empty and unfocused. Whether the widget should grow and shrink with the content. Number of pixels scrolled of the screen to the left. Custom tabs for this text widget. When true, pasted multi-line text is truncated to the first line. If false, the text is masked with the “invisible char”. Emitted when the user hits the <kbd>Enter</kbd> key. The default bindings for this signal are all forms of the <kbd>Enter</kbd> key. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Backspace</kbd> and <kbd>Shift</kbd>+<kbd>Backspace</kbd>. Emitted to copy the selection to the clipboard. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>c</kbd> and <kbd>Ctrl</kbd>+<kbd>Insert</kbd>. Emitted to cut the selection to the clipboard. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>x</kbd> and <kbd>Shift</kbd>+<kbd>Delete</kbd>. Emitted when the user initiates a text deletion. This is a [keybinding signal](class.SignalAction.html). If the @type is [enum@Gtk.DeleteType.chars], GTK deletes the selection if there is one, otherwise it deletes the requested number of characters. The default bindings for this signal are <kbd>Delete</kbd> for deleting a character and <kbd>Ctrl</kbd>+<kbd>Delete</kbd> for deleting a word. the granularity of the deletion the number of @type units to delete Emitted when the user initiates the insertion of a fixed string at the cursor. This is a [keybinding signal](class.SignalAction.html). This signal has no default bindings. the string to insert Emitted to present the Emoji chooser. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>.</kbd> and <kbd>Ctrl</kbd>+<kbd>;</kbd> Emitted when the user initiates a cursor movement. If the cursor is not visible in @self, this signal causes the viewport to be moved instead. This is a [keybinding signal](class.SignalAction.html). Applications should not connect to it, but may emit it with [func@GObject.signal_emit_by_name] if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the <kbd>Shift</kbd> modifier extends the selection, the variant without it does not. There are too many key combinations to list them all here. - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move by individual characters/lines - <kbd>Ctrl</kbd>+<kbd>←</kbd>, etc. move by words/paragraphs - <kbd>Home</kbd> and <kbd>End</kbd> move to the ends of the buffer the granularity of the move the number of @step units to move true if the move should extend the selection Emitted to paste the contents of the clipboard. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>v</kbd> and <kbd>Shift</kbd>+<kbd>Insert</kbd>. Emitted when the preedit text changes. If an input method is used, the typed text will not immediately be committed to the buffer. So if you are interested in the text, connect to this signal. the current preedit string Emitted to toggle the overwrite mode. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal is <kbd>Insert</kbd>. Stores text and attributes for display in a `GtkTextView`. You may wish to begin by reading the [text widget conceptual overview](section-text-widget.html), which gives an overview of all the objects and data types related to the text widget and how they work together. GtkTextBuffer can support undoing changes to the buffer content, see [method@Gtk.TextBuffer.set_enable_undo]. Creates a new text buffer. a new text buffer a tag table, or %NULL to create a new one Emits the “apply-tag” signal on @buffer. The default handler for the signal applies @tag to the given range. @start and @end do not have to be in order. a `GtkTextBuffer` a `GtkTextTag` one bound of range to be tagged other bound of range to be tagged Called to indicate that the buffer operations between here and a call to gtk_text_buffer_end_user_action() are part of a single user-visible operation. The operations between gtk_text_buffer_begin_user_action() and gtk_text_buffer_end_user_action() can then be grouped when creating an undo stack. `GtkTextBuffer` maintains a count of calls to gtk_text_buffer_begin_user_action() that have not been closed with a call to gtk_text_buffer_end_user_action(), and emits the “begin-user-action” and “end-user-action” signals only for the outermost pair of calls. This allows you to build user actions from other user actions. The “interactive” buffer mutation functions, such as [method@Gtk.TextBuffer.insert_interactive], automatically call begin/end user action around the buffer operations they perform, so there's no need to add extra calls if you user action consists solely of a single call to one of those functions. a `GtkTextBuffer` The class handler for the `GtkTextBuffer::changed` signal. The class handler for the `GtkTextBuffer::delete-range` signal. Ends a user-visible operation. Should be paired with a call to [method@Gtk.TextBuffer.begin_user_action]. See that function for a full explanation. a `GtkTextBuffer` Inserts a child widget anchor into the text buffer at @iter. The anchor will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode “object replacement character” 0xFFFC. Note that the “slice” variants for obtaining portions of the buffer as a string include this character for child anchors, but the “text” variants do not. E.g. see [method@Gtk.TextBuffer.get_slice] and [method@Gtk.TextBuffer.get_text]. Consider [method@Gtk.TextBuffer.create_child_anchor] as a more convenient alternative to this function. The buffer will add a reference to the anchor, so you can unref it after insertion. a `GtkTextBuffer` location to insert the anchor a `GtkTextChildAnchor` Inserts an image into the text buffer at @iter. The image will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode “object replacement character” 0xFFFC. Note that the “slice” variants for obtaining portions of the buffer as a string include this character for paintable, but the “text” variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and [method@Gtk.TextBuffer.get_text]. a `GtkTextBuffer` location to insert the paintable a `GdkPaintable` The class handler for the `GtkTextBuffer::insert-text` signal. The class handler for the `GtkTextBuffer::mark-deleted` signal. The class handler for the `GtkTextBuffer::mark-set` signal. The class handler for the `GtkTextBuffer::modified-changed` signal. The class handler for the `GtkTextBuffer::paste-done` signal. Redoes the next redoable action on the buffer, if there is one. a `GtkTextBuffer` Emits the “remove-tag” signal. The default handler for the signal removes all occurrences of @tag from the given range. @start and @end don’t have to be in order. a `GtkTextBuffer` a `GtkTextTag` one bound of range to be untagged other bound of range to be untagged Undoes the last undoable action on the buffer, if there is one. a `GtkTextBuffer` Adds a [callback@Gtk.TextBufferCommitNotify] to be called when a change is to be made to the [type@Gtk.TextBuffer]. Functions are explicitly forbidden from making changes to the [type@Gtk.TextBuffer] from this callback. It is intended for tracking changes to the buffer only. It may be advantageous to use [callback@Gtk.TextBufferCommitNotify] over connecting to the [signal@Gtk.TextBuffer::insert-text] or [signal@Gtk.TextBuffer::delete-range] signals to avoid ordering issues with other signal handlers which may further modify the [type@Gtk.TextBuffer]. a handler id which may be used to remove the commit notify callback using [method@Gtk.TextBuffer.remove_commit_notify]. a [type@Gtk.TextBuffer] which notifications should be dispatched to @callback a [callback@Gtk.TextBufferCommitNotify] to call for commit notifications closure data for @commit_notify a callback to free @user_data when @commit_notify is removed Adds the mark at position @where. The mark must not be added to another buffer, and if its name is not %NULL then there must not be another mark in the buffer with the same name. Emits the [signal@Gtk.TextBuffer::mark-set] signal as notification of the mark's initial placement. a `GtkTextBuffer` the mark to add location to place mark Adds @clipboard to the list of clipboards in which the selection contents of @buffer are available. In most cases, @clipboard will be the `GdkClipboard` returned by [method@Gtk.Widget.get_primary_clipboard] for a view of @buffer. a `GtkTextBuffer` a `GdkClipboard` Emits the “apply-tag” signal on @buffer. The default handler for the signal applies @tag to the given range. @start and @end do not have to be in order. a `GtkTextBuffer` a `GtkTextTag` one bound of range to be tagged other bound of range to be tagged Emits the “apply-tag” signal on @buffer. Calls [method@Gtk.TextTagTable.lookup] on the buffer’s tag table to get a `GtkTextTag`, then calls [method@Gtk.TextBuffer.apply_tag]. a `GtkTextBuffer` name of a named `GtkTextTag` one bound of range to be tagged other bound of range to be tagged Performs the appropriate action as if the user hit the delete key with the cursor at the position specified by @iter. In the normal case a single character will be deleted, but when combining accents are involved, more than one character can be deleted, and when precomposed character and accent combinations are involved, less than one character will be deleted. Because the buffer is modified, all outstanding iterators become invalid after calling this function; however, the @iter will be re-initialized to point to the location where text was deleted. %TRUE if the buffer was modified a `GtkTextBuffer` a position in @buffer whether the deletion is caused by user interaction whether the buffer is editable by default Denotes the beginning of an action that may not be undone. This will cause any previous operations in the undo/redo queue to be cleared. This should be paired with a call to [method@Gtk.TextBuffer.end_irreversible_action] after the irreversible action has completed. You may nest calls to gtk_text_buffer_begin_irreversible_action() and gtk_text_buffer_end_irreversible_action() pairs. a `GtkTextBuffer` Called to indicate that the buffer operations between here and a call to gtk_text_buffer_end_user_action() are part of a single user-visible operation. The operations between gtk_text_buffer_begin_user_action() and gtk_text_buffer_end_user_action() can then be grouped when creating an undo stack. `GtkTextBuffer` maintains a count of calls to gtk_text_buffer_begin_user_action() that have not been closed with a call to gtk_text_buffer_end_user_action(), and emits the “begin-user-action” and “end-user-action” signals only for the outermost pair of calls. This allows you to build user actions from other user actions. The “interactive” buffer mutation functions, such as [method@Gtk.TextBuffer.insert_interactive], automatically call begin/end user action around the buffer operations they perform, so there's no need to add extra calls if you user action consists solely of a single call to one of those functions. a `GtkTextBuffer` Copies the currently-selected text to a clipboard. a `GtkTextBuffer` the `GdkClipboard` object to copy to Creates and inserts a child anchor. This is a convenience function which simply creates a child anchor with [ctor@Gtk.TextChildAnchor.new] and inserts it into the buffer with [method@Gtk.TextBuffer.insert_child_anchor]. The new anchor is owned by the buffer; no reference count is returned to the caller of this function. the created child anchor a `GtkTextBuffer` location in the buffer Creates a mark at position @where. If @mark_name is %NULL, the mark is anonymous; otherwise, the mark can be retrieved by name using [method@Gtk.TextBuffer.get_mark]. If a mark has left gravity, and text is inserted at the mark’s current location, the mark will be moved to the left of the newly-inserted text. If the mark has right gravity (@left_gravity = %FALSE), the mark will end up on the right of newly-inserted text. The standard left-to-right cursor is a mark with right gravity (when you type, the cursor stays on the right side of the text you’re typing). The caller of this function does not own a reference to the returned `GtkTextMark`, so you can ignore the return value if you like. Marks are owned by the buffer and go away when the buffer does. Emits the [signal@Gtk.TextBuffer::mark-set] signal as notification of the mark's initial placement. the new `GtkTextMark` object a `GtkTextBuffer` name for mark location to place mark whether the mark has left gravity Creates a tag and adds it to the tag table for @buffer. Equivalent to calling [ctor@Gtk.TextTag.new] and then adding the tag to the buffer’s tag table. The returned tag is owned by the buffer’s tag table, so the ref count will be equal to one. If @tag_name is %NULL, the tag is anonymous. If @tag_name is non-%NULL, a tag called @tag_name must not already exist in the tag table for this buffer. The @first_property_name argument and subsequent arguments are a list of properties to set on the tag, as with g_object_set(). a new tag a `GtkTextBuffer` name of the new tag name of first property to set %NULL-terminated list of property names and values Copies the currently-selected text to a clipboard, then deletes said text if it’s editable. a `GtkTextBuffer` the `GdkClipboard` object to cut to default editability of the buffer Deletes text between @start and @end. The order of @start and @end is not actually relevant; gtk_text_buffer_delete() will reorder them. This function actually emits the “delete-range” signal, and the default handler of that signal deletes the text. Because the buffer is modified, all outstanding iterators become invalid after calling this function; however, the @start and @end will be re-initialized to point to the location where text was deleted. a `GtkTextBuffer` a position in @buffer another position in @buffer Deletes all editable text in the given range. Calls [method@Gtk.TextBuffer.delete] for each editable sub-range of [@start,@end). @start and @end are revalidated to point to the location of the last deleted range, or left untouched if no text was deleted. whether some text was actually deleted a `GtkTextBuffer` start of range to delete end of range whether the buffer is editable by default Deletes @mark, so that it’s no longer located anywhere in the buffer. Removes the reference the buffer holds to the mark, so if you haven’t called g_object_ref() on the mark, it will be freed. Even if the mark isn’t freed, most operations on @mark become invalid, until it gets added to a buffer again with [method@Gtk.TextBuffer.add_mark]. Use [method@Gtk.TextMark.get_deleted] to find out if a mark has been removed from its buffer. The [signal@Gtk.TextBuffer::mark-deleted] signal will be emitted as notification after the mark is deleted. a `GtkTextBuffer` a `GtkTextMark` in @buffer Deletes the mark named @name; the mark must exist. See [method@Gtk.TextBuffer.delete_mark] for details. a `GtkTextBuffer` name of a mark in @buffer Deletes the range between the “insert” and “selection_bound” marks, that is, the currently-selected text. If @interactive is %TRUE, the editability of the selection will be considered (users can’t delete uneditable text). whether there was a non-empty selection to delete a `GtkTextBuffer` whether the deletion is caused by user interaction whether the buffer is editable by default Denotes the end of an action that may not be undone. This will cause any previous operations in the undo/redo queue to be cleared. This should be called after completing modifications to the text buffer after [method@Gtk.TextBuffer.begin_irreversible_action] was called. You may nest calls to gtk_text_buffer_begin_irreversible_action() and gtk_text_buffer_end_irreversible_action() pairs. a `GtkTextBuffer` Ends a user-visible operation. Should be paired with a call to [method@Gtk.TextBuffer.begin_user_action]. See that function for a full explanation. a `GtkTextBuffer` Retrieves the first and last iterators in the buffer, i.e. the entire buffer lies within the range [@start,@end). a `GtkTextBuffer` iterator to initialize with first position in the buffer iterator to initialize with the end iterator Gets whether there is a redoable action in the history. %TRUE if there is a redoable action a `GtkTextBuffer` Gets whether there is an undoable action in the history. %TRUE if there is an undoable action a `GtkTextBuffer` Gets the number of characters in the buffer. Note that characters and bytes are not the same, you can’t e.g. expect the contents of the buffer in string form to be this many bytes long. The character count is cached, so this function is very fast. number of characters in the buffer a `GtkTextBuffer` Gets whether the buffer is saving modifications to the buffer to allow for undo and redo actions. See [method@Gtk.TextBuffer.begin_irreversible_action] and [method@Gtk.TextBuffer.end_irreversible_action] to create changes to the buffer that cannot be undone. %TRUE if undoing and redoing changes to the buffer is allowed. a `GtkTextBuffer` Initializes @iter with the “end iterator,” one past the last valid character in the text buffer. If dereferenced with [method@Gtk.TextIter.get_char], the end iterator has a character value of 0. The entire buffer lies in the range from the first position in the buffer (call [method@Gtk.TextBuffer.get_start_iter] to get character position 0) to the end iterator. a `GtkTextBuffer` iterator to initialize Indicates whether the buffer has some text currently selected. %TRUE if the there is text selected a `GtkTextBuffer` Returns the mark that represents the cursor (insertion point). Equivalent to calling [method@Gtk.TextBuffer.get_mark] to get the mark named “insert”, but very slightly more efficient, and involves less typing. insertion point mark a `GtkTextBuffer` Obtains the location of @anchor within @buffer. a `GtkTextBuffer` an iterator to be initialized a child anchor that appears in @buffer Initializes @iter to the start of the given line. If @line_number is greater than or equal to the number of lines in the @buffer, the end iterator is returned. whether the exact position has been found a `GtkTextBuffer` iterator to initialize line number counting from 0 Obtains an iterator pointing to @byte_index within the given line. @byte_index must be the start of a UTF-8 character. Note bytes, not characters; UTF-8 may encode one character as multiple bytes. If @line_number is greater than or equal to the number of lines in the @buffer, the end iterator is returned. And if @byte_index is off the end of the line, the iterator at the end of the line is returned. whether the exact position has been found a `GtkTextBuffer` iterator to initialize line number counting from 0 byte index from start of line Obtains an iterator pointing to @char_offset within the given line. Note characters, not bytes; UTF-8 may encode one character as multiple bytes. If @line_number is greater than or equal to the number of lines in the @buffer, the end iterator is returned. And if @char_offset is off the end of the line, the iterator at the end of the line is returned. whether the exact position has been found a `GtkTextBuffer` iterator to initialize line number counting from 0 char offset from start of line Initializes @iter with the current position of @mark. a `GtkTextBuffer` iterator to initialize a `GtkTextMark` in @buffer Initializes @iter to a position @char_offset chars from the start of the entire buffer. If @char_offset is -1 or greater than the number of characters in the buffer, @iter is initialized to the end iterator, the iterator one past the last valid character in the buffer. a `GtkTextBuffer` iterator to initialize char offset from start of buffer, counting from 0, or -1 Obtains the number of lines in the buffer. This value is cached, so the function is very fast. number of lines in the buffer a `GtkTextBuffer` Returns the mark named @name in buffer @buffer, or %NULL if no such mark exists in the buffer. a `GtkTextMark` a `GtkTextBuffer` a mark name Gets the maximum number of undo levels to perform. If 0, unlimited undo actions may be performed. Note that this may have a memory usage impact as it requires storing an additional copy of the inserted or removed text within the text buffer. The max number of undo levels allowed (0 indicates unlimited). a `GtkTextBuffer` Indicates whether the buffer has been modified since the last call to [method@Gtk.TextBuffer.set_modified] set the modification flag to %FALSE. Used for example to enable a “save” function in a text editor. %TRUE if the buffer has been modified a `GtkTextBuffer` Returns the mark that represents the selection bound. Equivalent to calling [method@Gtk.TextBuffer.get_mark] to get the mark named “selection_bound”, but very slightly more efficient, and involves less typing. The currently-selected text in @buffer is the region between the “selection_bound” and “insert” marks. If “selection_bound” and “insert” are in the same place, then there is no current selection. [method@Gtk.TextBuffer.get_selection_bounds] is another convenient function for handling the selection, if you just want to know whether there’s a selection and what its bounds are. selection bound mark a `GtkTextBuffer` Returns %TRUE if some text is selected; places the bounds of the selection in @start and @end. If the selection has length 0, then @start and @end are filled in with the same value. @start and @end will be in ascending order. If @start and @end are %NULL, then they are not filled in, but the return value still indicates whether text is selected. whether the selection has nonzero length a `GtkTextBuffer` a `GtkTextBuffer` iterator to initialize with selection start iterator to initialize with selection end Get a content provider for this buffer. It can be used to make the content of @buffer available in a `GdkClipboard`, see [method@Gdk.Clipboard.set_content]. a new `GdkContentProvider`. a `GtkTextBuffer` Returns the text in the range [@start,@end). Excludes undisplayed text (text marked with tags that set the invisibility attribute) if @include_hidden_chars is %FALSE. The returned string includes a 0xFFFC character whenever the buffer contains embedded images, so byte and character indexes into the returned string do correspond to byte and character indexes into the buffer. Contrast with [method@Gtk.TextBuffer.get_text]. Note that 0xFFFC can occur in normal text as well, so it is not a reliable indicator that a paintable or widget is in the buffer. an allocated UTF-8 string a `GtkTextBuffer` start of a range end of a range whether to include invisible text Initialized @iter with the first position in the text buffer. This is the same as using [method@Gtk.TextBuffer.get_iter_at_offset] to get the iter at character offset 0. a `GtkTextBuffer` iterator to initialize Get the `GtkTextTagTable` associated with this buffer. the buffer’s tag table a `GtkTextBuffer` Returns the text in the range [@start,@end). Excludes undisplayed text (text marked with tags that set the invisibility attribute) if @include_hidden_chars is %FALSE. Does not include characters representing embedded images, so byte and character indexes into the returned string do not correspond to byte and character indexes into the buffer. Contrast with [method@Gtk.TextBuffer.get_slice]. an allocated UTF-8 string a `GtkTextBuffer` start of a range end of a range whether to include invisible text Inserts @len bytes of @text at position @iter. If @len is -1, @text must be nul-terminated and will be inserted in its entirety. Emits the “insert-text” signal; insertion actually occurs in the default handler for the signal. @iter is invalidated when insertion occurs (because the buffer contents change), but the default signal handler revalidates it to point to the end of the inserted text. a `GtkTextBuffer` a position in the buffer text in UTF-8 format length of text in bytes, or -1 Inserts @text in @buffer. Simply calls [method@Gtk.TextBuffer.insert], using the current cursor position as the insertion point. a `GtkTextBuffer` text in UTF-8 format length of text, in bytes Inserts a child widget anchor into the text buffer at @iter. The anchor will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode “object replacement character” 0xFFFC. Note that the “slice” variants for obtaining portions of the buffer as a string include this character for child anchors, but the “text” variants do not. E.g. see [method@Gtk.TextBuffer.get_slice] and [method@Gtk.TextBuffer.get_text]. Consider [method@Gtk.TextBuffer.create_child_anchor] as a more convenient alternative to this function. The buffer will add a reference to the anchor, so you can unref it after insertion. a `GtkTextBuffer` location to insert the anchor a `GtkTextChildAnchor` Inserts @text in @buffer. Like [method@Gtk.TextBuffer.insert], but the insertion will not occur if @iter is at a non-editable location in the buffer. Usually you want to prevent insertions at ineditable locations if the insertion results from a user action (is interactive). @default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. Typically the result of [method@Gtk.TextView.get_editable] is appropriate here. whether text was actually inserted a `GtkTextBuffer` a position in @buffer some UTF-8 text length of text in bytes, or -1 default editability of buffer Inserts @text in @buffer. Calls [method@Gtk.TextBuffer.insert_interactive] at the cursor position. @default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. Typically the result of [method@Gtk.TextView.get_editable] is appropriate here. whether text was actually inserted a `GtkTextBuffer` text in UTF-8 format length of text in bytes, or -1 default editability of buffer Inserts the text in @markup at position @iter. @markup will be inserted in its entirety and must be nul-terminated and valid UTF-8. Emits the [signal@Gtk.TextBuffer::insert-text] signal, possibly multiple times; insertion actually occurs in the default handler for the signal. @iter will point to the end of the inserted text on return. a `GtkTextBuffer` location to insert the markup a nul-terminated UTF-8 string containing Pango markup length of @markup in bytes, or -1 Inserts an image into the text buffer at @iter. The image will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode “object replacement character” 0xFFFC. Note that the “slice” variants for obtaining portions of the buffer as a string include this character for paintable, but the “text” variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and [method@Gtk.TextBuffer.get_text]. a `GtkTextBuffer` location to insert the paintable a `GdkPaintable` Copies text, tags, and paintables between @start and @end and inserts the copy at @iter. The order of @start and @end doesn’t matter. Used instead of simply getting/inserting text because it preserves images and tags. If @start and @end are in a different buffer from @buffer, the two buffers must share the same tag table. Implemented via emissions of the ::insert-text and ::apply-tag signals, so expect those. a `GtkTextBuffer` a position in @buffer a position in a `GtkTextBuffer` another position in the same buffer as @start Copies text, tags, and paintables between @start and @end and inserts the copy at @iter. Same as [method@Gtk.TextBuffer.insert_range], but does nothing if the insertion point isn’t editable. The @default_editable parameter indicates whether the text is editable at @iter if no tags enclosing @iter affect editability. Typically the result of [method@Gtk.TextView.get_editable] is appropriate here. whether an insertion was possible at @iter a `GtkTextBuffer` a position in @buffer a position in a `GtkTextBuffer` another position in the same buffer as @start default editability of the buffer Inserts @text into @buffer at @iter, applying the list of tags to the newly-inserted text. The last tag specified must be %NULL to terminate the list. Equivalent to calling [method@Gtk.TextBuffer.insert], then [method@Gtk.TextBuffer.apply_tag] on the inserted text; this is just a convenience function. a `GtkTextBuffer` an iterator in @buffer UTF-8 text length of @text, or -1 first tag to apply to @text %NULL-terminated list of tags to apply Inserts @text into @buffer at @iter, applying the list of tags to the newly-inserted text. Same as [method@Gtk.TextBuffer.insert_with_tags], but allows you to pass in tag names instead of tag objects. a `GtkTextBuffer` position in @buffer UTF-8 text length of @text, or -1 name of a tag to apply to @text more tag names Moves @mark to the new location @where. Emits the [signal@Gtk.TextBuffer::mark-set] signal as notification of the move. a `GtkTextBuffer` a `GtkTextMark` new location for @mark in @buffer Moves the mark named @name (which must exist) to location @where. See [method@Gtk.TextBuffer.move_mark] for details. a `GtkTextBuffer` name of a mark new location for mark Pastes the contents of a clipboard. If @override_location is %NULL, the pasted text will be inserted at the cursor position, or the buffer selection will be replaced if the selection is non-empty. Note: pasting is asynchronous, that is, we’ll ask for the paste data and return, and at some point later after the main loop runs, the paste data will be inserted. a `GtkTextBuffer` the `GdkClipboard` to paste from location to insert pasted text whether the buffer is editable by default This function moves the “insert” and “selection_bound” marks simultaneously. If you move them to the same place in two steps with [method@Gtk.TextBuffer.move_mark], you will temporarily select a region in between their old and new locations, which can be pretty inefficient since the temporarily-selected region will force stuff to be recalculated. This function moves them as a unit, which can be optimized. a `GtkTextBuffer` where to put the cursor Redoes the next redoable action on the buffer, if there is one. a `GtkTextBuffer` Removes all tags in the range between @start and @end. Be careful with this function; it could remove tags added in code unrelated to the code you’re currently writing. That is, using this function is probably a bad idea if you have two or more unrelated code sections that add tags. a `GtkTextBuffer` one bound of range to be untagged other bound of range to be untagged Removes the `GtkTextBufferCommitNotify` handler previously registered with [method@Gtk.TextBuffer.add_commit_notify]. This may result in the `user_data_destroy` being called that was passed when registering the commit notify functions. a `GtkTextBuffer` the notify handler identifier returned from [method@Gtk.TextBuffer.add_commit_notify]. Removes a `GdkClipboard` added with [method@Gtk.TextBuffer.add_selection_clipboard] a `GtkTextBuffer` a `GdkClipboard` added to @buffer by [method@Gtk.TextBuffer.add_selection_clipboard] Emits the “remove-tag” signal. The default handler for the signal removes all occurrences of @tag from the given range. @start and @end don’t have to be in order. a `GtkTextBuffer` a `GtkTextTag` one bound of range to be untagged other bound of range to be untagged Emits the “remove-tag” signal. Calls [method@Gtk.TextTagTable.lookup] on the buffer’s tag table to get a `GtkTextTag`, then calls [method@Gtk.TextBuffer.remove_tag]. a `GtkTextBuffer` name of a `GtkTextTag` one bound of range to be untagged other bound of range to be untagged This function moves the “insert” and “selection_bound” marks simultaneously. If you move them in two steps with [method@Gtk.TextBuffer.move_mark], you will temporarily select a region in between their old and new locations, which can be pretty inefficient since the temporarily-selected region will force stuff to be recalculated. This function moves them as a unit, which can be optimized. a `GtkTextBuffer` where to put the “insert” mark where to put the “selection_bound” mark Sets whether or not to enable undoable actions in the text buffer. Undoable actions in this context are changes to the text content of the buffer. Changes to tags and marks are not tracked. If enabled, the user will be able to undo the last number of actions up to [method@Gtk.TextBuffer.get_max_undo_levels]. See [method@Gtk.TextBuffer.begin_irreversible_action] and [method@Gtk.TextBuffer.end_irreversible_action] to create changes to the buffer that cannot be undone. a `GtkTextBuffer` %TRUE to enable undo Sets the maximum number of undo levels to perform. If 0, unlimited undo actions may be performed. Note that this may have a memory usage impact as it requires storing an additional copy of the inserted or removed text within the text buffer. a `GtkTextBuffer` the maximum number of undo actions to perform Used to keep track of whether the buffer has been modified since the last time it was saved. Whenever the buffer is saved to disk, call `gtk_text_buffer_set_modified (@buffer, FALSE)`. When the buffer is modified, it will automatically toggle on the modified bit again. When the modified bit flips, the buffer emits the [signal@Gtk.TextBuffer::modified-changed] signal. a `GtkTextBuffer` modification flag setting Deletes current contents of @buffer, and inserts @text instead. This is automatically marked as an irreversible action in the undo stack. If you wish to mark this action as part of a larger undo operation, call [method@TextBuffer.delete] and [method@TextBuffer.insert] directly instead. If @len is -1, @text must be nul-terminated. @text must be valid UTF-8. a `GtkTextBuffer` UTF-8 text to insert length of @text in bytes Undoes the last undoable action on the buffer, if there is one. a `GtkTextBuffer` Denotes that the buffer can reapply the last undone action. Denotes that the buffer can undo the last applied action. The position of the insert mark. This is an offset from the beginning of the buffer. It is useful for getting notified when the cursor moves. Denotes if support for undoing and redoing changes to the buffer is allowed. Whether the buffer has some text currently selected. The GtkTextTagTable for the buffer. The text content of the buffer. Without child widgets and images, see [method@Gtk.TextBuffer.get_text] for more information. Emitted to apply a tag to a range of text in a `GtkTextBuffer`. Applying actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @start and @end iters (or has to revalidate them). See also: [method@Gtk.TextBuffer.apply_tag], [method@Gtk.TextBuffer.insert_with_tags], [method@Gtk.TextBuffer.insert_range]. the applied tag the start of the range the tag is applied to the end of the range the tag is applied to Emitted at the beginning of a single user-visible operation on a `GtkTextBuffer`. See also: [method@Gtk.TextBuffer.begin_user_action], [method@Gtk.TextBuffer.insert_interactive], [method@Gtk.TextBuffer.insert_range_interactive], [method@Gtk.TextBuffer.delete_interactive], [method@Gtk.TextBuffer.backspace], [method@Gtk.TextBuffer.delete_selection]. Emitted when the content of a `GtkTextBuffer` has changed. Emitted to delete a range from a `GtkTextBuffer`. Note that if your handler runs before the default handler it must not invalidate the @start and @end iters (or has to revalidate them). The default signal handler revalidates the @start and @end iters to both point to the location where text was deleted. Handlers which run after the default handler (see g_signal_connect_after()) do not have access to the deleted text. See also: [method@Gtk.TextBuffer.delete]. the start of the range to be deleted the end of the range to be deleted Emitted at the end of a single user-visible operation on the `GtkTextBuffer`. See also: [method@Gtk.TextBuffer.end_user_action], [method@Gtk.TextBuffer.insert_interactive], [method@Gtk.TextBuffer.insert_range_interactive], [method@Gtk.TextBuffer.delete_interactive], [method@Gtk.TextBuffer.backspace], [method@Gtk.TextBuffer.delete_selection], [method@Gtk.TextBuffer.backspace]. Emitted to insert a `GtkTextChildAnchor` in a `GtkTextBuffer`. Insertion actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @location iter (or has to revalidate it). The default signal handler revalidates it to be placed after the inserted @anchor. See also: [method@Gtk.TextBuffer.insert_child_anchor]. position to insert @anchor in @textbuffer the `GtkTextChildAnchor` to be inserted Emitted to insert a `GdkPaintable` in a `GtkTextBuffer`. Insertion actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @location iter (or has to revalidate it). The default signal handler revalidates it to be placed after the inserted @paintable. See also: [method@Gtk.TextBuffer.insert_paintable]. position to insert @paintable in @textbuffer the `GdkPaintable` to be inserted Emitted to insert text in a `GtkTextBuffer`. Insertion actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @location iter (or has to revalidate it). The default signal handler revalidates it to point to the end of the inserted text. See also: [method@Gtk.TextBuffer.insert], [method@Gtk.TextBuffer.insert_range]. position to insert @text in @textbuffer the UTF-8 text to be inserted length of the inserted text in bytes Emitted as notification after a `GtkTextMark` is deleted. See also: [method@Gtk.TextBuffer.delete_mark]. The mark that was deleted Emitted as notification after a `GtkTextMark` is set. See also: [method@Gtk.TextBuffer.create_mark], [method@Gtk.TextBuffer.move_mark]. The location of @mark in @textbuffer The mark that is set Emitted when the modified bit of a `GtkTextBuffer` flips. See also: [method@Gtk.TextBuffer.set_modified]. Emitted after paste operation has been completed. This is useful to properly scroll the view to the end of the pasted text. See [method@Gtk.TextBuffer.paste_clipboard] for more details. the `GdkClipboard` pasted from Emitted when a request has been made to redo the previously undone operation. Emitted to remove all occurrences of @tag from a range of text in a `GtkTextBuffer`. Removal actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @start and @end iters (or has to revalidate them). See also: [method@Gtk.TextBuffer.remove_tag]. the tag to be removed the start of the range the tag is removed from the end of the range the tag is removed from Emitted when a request has been made to undo the previous operation or set of operations that have been grouped together. The class structure for `GtkTextBuffer`. The object class structure needs to be the first. The class handler for the `GtkTextBuffer::insert-text` signal. The class handler for the `GtkTextBuffer::insert-paintable` signal. a `GtkTextBuffer` location to insert the paintable a `GdkPaintable` The class handler for the `GtkTextBuffer::insert-child-anchor` signal. a `GtkTextBuffer` location to insert the anchor a `GtkTextChildAnchor` The class handler for the `GtkTextBuffer::delete-range` signal. The class handler for the `GtkTextBuffer::changed` signal. The class handler for the `GtkTextBuffer::modified-changed` signal. The class handler for the `GtkTextBuffer::mark-set` signal. The class handler for the `GtkTextBuffer::mark-deleted` signal. The class handler for the `GtkTextBuffer::apply-tag` signal. a `GtkTextBuffer` a `GtkTextTag` one bound of range to be tagged other bound of range to be tagged The class handler for the `GtkTextBuffer::remove-tag` signal. a `GtkTextBuffer` a `GtkTextTag` one bound of range to be untagged other bound of range to be untagged The class handler for the `GtkTextBuffer::begin-user-action` signal. a `GtkTextBuffer` The class handler for the `GtkTextBuffer::end-user-action` signal. a `GtkTextBuffer` The class handler for the `GtkTextBuffer::paste-done` signal. The class handler for the `GtkTextBuffer::undo` signal a `GtkTextBuffer` The class handler for the `GtkTextBuffer::redo` signal a `GtkTextBuffer` A notification callback used by [method@Gtk.TextBuffer.add_commit_notify]. You may not modify the [class@Gtk.TextBuffer] from a [callback@Gtk.TextBufferCommitNotify] callback and that is enforced by the [class@Gtk.TextBuffer] API. [callback@Gtk.TextBufferCommitNotify] may be used to be notified about changes to the underlying buffer right before-or-after the changes are committed to the underlying B-Tree. This is useful if you want to observe changes to the buffer without other signal handlers potentially modifying state on the way to the default signal handler. When @flags is `GTK_TEXT_BUFFER_NOTIFY_BEFORE_INSERT`, `position` is set to the offset in characters from the start of the buffer where the insertion will occur. `length` is set to the number of characters to be inserted. You may not yet retrieve the text until it has been inserted. You may access the text from `GTK_TEXT_BUFFER_NOTIFY_AFTER_INSERT` using [method@Gtk.TextBuffer.get_slice]. When @flags is `GTK_TEXT_BUFFER_NOTIFY_AFTER_INSERT`, `position` is set to offset in characters where the insertion occurred and `length` is set to the number of characters inserted. When @flags is `GTK_TEXT_BUFFER_NOTIFY_BEFORE_DELETE`, `position` is set to offset in characters where the deletion will occur and `length` is set to the number of characters that will be removed. You may still retrieve the text from this handler using `position` and `length`. When @flags is `GTK_TEXT_BUFFER_NOTIFY_AFTER_DELETE`, `length` is set to zero to denote that the delete-range has already been committed to the underlying B-Tree. You may no longer retrieve the text that has been deleted from the [class@Gtk.TextBuffer]. the text buffer being notified the type of commit notification the position of the text operation the length of the text operation in characters user data passed to the callback Values for [callback@Gtk.TextBufferCommitNotify] to denote the point of the notification. Be notified before text is inserted into the underlying buffer. Be notified after text has been inserted into the underlying buffer. Be notified before text is deleted from the underlying buffer. Be notified after text has been deleted from the underlying buffer. The predicate function used by gtk_text_iter_forward_find_char() and gtk_text_iter_backward_find_char(). %TRUE if the predicate is satisfied, and the iteration should stop, and %FALSE otherwise a Unicode code point data passed to the callback Marks a spot in a `GtkTextBuffer` where child widgets can be “anchored”. The anchor can have multiple widgets anchored, to allow for multiple views. Creates a new `GtkTextChildAnchor`. Usually you would then insert it into a `GtkTextBuffer` with [method@Gtk.TextBuffer.insert_child_anchor]. To perform the creation and insertion in one step, use the convenience function [method@Gtk.TextBuffer.create_child_anchor]. a new `GtkTextChildAnchor` Creates a new `GtkTextChildAnchor` with the given replacement character. Usually you would then insert it into a `GtkTextBuffer` with [method@Gtk.TextBuffer.insert_child_anchor]. a new `GtkTextChildAnchor` a replacement character Determines whether a child anchor has been deleted from the buffer. Keep in mind that the child anchor will be unreferenced when removed from the buffer, so you need to hold your own reference (with g_object_ref()) if you plan to use this function — otherwise all deleted child anchors will also be finalized. %TRUE if the child anchor has been deleted from its buffer a `GtkTextChildAnchor` Gets a list of all widgets anchored at this child anchor. The order in which the widgets are returned is not defined. an array of widgets anchored at @anchor a `GtkTextChildAnchor` return location for the length of the array Reading directions for text. No direction. Left to right text direction. Right to left text direction. Granularity types that extend the text selection. Use the `GtkTextView::extend-selection` signal to customize the selection. Selects the current word. It is triggered by a double-click for example. Selects the current line. It is triggered by a triple-click for example. Iterates over the contents of a `GtkTextBuffer`. You may wish to begin by reading the [text widget conceptual overview](section-text-widget.html), which gives an overview of all the objects and data types related to the text widget and how they work together. Assigns the value of @other to @iter. This function is not useful in applications, because iterators can be assigned with `GtkTextIter i = j;`. The function is used by language bindings. a `GtkTextIter` another `GtkTextIter` Moves backward by one character offset. Returns %TRUE if movement was possible; if @iter was the first in the buffer (character offset 0), this function returns %FALSE for convenience when writing loops. whether movement was possible an iterator Moves @count characters backward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. whether @iter moved and is dereferenceable an iterator number of characters to move Like [method@Gtk.TextIter.forward_cursor_position], but moves backward. %TRUE if we moved a `GtkTextIter` Moves up to @count cursor positions. See [method@Gtk.TextIter.forward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` number of positions to move Same as [method@Gtk.TextIter.forward_find_char], but goes backward from @iter. whether a match was found a `GtkTextIter` function to be called on each character user data for @pred search limit Moves @iter to the start of the previous line. Returns %TRUE if @iter could be moved; i.e. if @iter was at character offset 0, this function returns %FALSE. Therefore, if @iter was already on line 0, but not at the start of the line, @iter is snapped to the start of the line and the function returns %TRUE. (Note that this implies that in a loop calling this function, the line number may not change on every iteration, if your first iteration is on line 0.) whether @iter moved an iterator Moves @count lines backward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. If @count is negative, moves forward by 0 - @count lines. whether @iter moved and is dereferenceable a `GtkTextIter` number of lines to move backward Same as [method@Gtk.TextIter.forward_search], but moves backward. @match_end will never be set to a `GtkTextIter` located after @iter, even if there is a possible @match_start before or at @iter. whether a match was found a `GtkTextIter` where the search begins search string bitmask of flags affecting the search return location for start of match return location for end of match location of last possible @match_start, or %NULL for start of buffer Moves backward to the previous sentence start. If @iter is already at the start of a sentence, moves backward to the next one. Sentence boundaries are determined by Pango and should be correct for nearly any language. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` Calls [method@Gtk.TextIter.backward_sentence_start] up to @count times. If @count is negative, moves forward instead of backward. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` number of sentences to move Moves backward to the next toggle (on or off) of the @tag, or to the next toggle of any tag if @tag is %NULL. If no matching tag toggles are found, returns %FALSE, otherwise %TRUE. Does not return toggles located at @iter, only toggles before @iter. Sets @iter to the location of the toggle, or the start of the buffer if no toggle is found. whether we found a tag toggle before @iter a `GtkTextIter` a `GtkTextTag` Moves @iter backward to the previous visible cursor position. See [method@Gtk.TextIter.backward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` Moves up to @count visible cursor positions. See [method@Gtk.TextIter.backward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` number of positions to move Moves @iter to the start of the previous visible line. Returns %TRUE if @iter could be moved; i.e. if @iter was at character offset 0, this function returns %FALSE. Therefore if @iter was already on line 0, but not at the start of the line, @iter is snapped to the start of the line and the function returns %TRUE. (Note that this implies that in a loop calling this function, the line number may not change on every iteration, if your first iteration is on line 0.) whether @iter moved an iterator Moves @count visible lines backward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. If @count is negative, moves forward by 0 - @count lines. whether @iter moved and is dereferenceable a `GtkTextIter` number of lines to move backward Moves backward to the previous visible word start. If @iter is currently on a word start, moves backward to the next one after that. Word breaks are determined by Pango and should be correct for nearly any language. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` Calls [method@Gtk.TextIter.backward_visible_word_start] up to @count times. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` number of times to move Moves backward to the previous word start. If @iter is currently on a word start, moves backward to the next one after that. Word breaks are determined by Pango and should be correct for nearly any language %TRUE if @iter moved and is not the end iterator a `GtkTextIter` Calls [method@Gtk.TextIter.backward_word_start] up to @count times. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` number of times to move Considering the default editability of the buffer, and tags that affect editability, determines whether text inserted at @iter would be editable. If text inserted at @iter would be editable then the user should be allowed to insert text at @iter. [method@Gtk.TextBuffer.insert_interactive] uses this function to decide whether insertions are allowed at a given position. whether text inserted at @iter would be editable an iterator %TRUE if text is editable by default A qsort()-style function that returns negative if @lhs is less than @rhs, positive if @lhs is greater than @rhs, and 0 if they’re equal. Ordering is in character offset order, i.e. the first character in the buffer is less than the second character in the buffer. -1 if @lhs is less than @rhs, 1 if @lhs is greater, 0 if they are equal a `GtkTextIter` another `GtkTextIter` Creates a dynamically-allocated copy of an iterator. This function is not useful in applications, because iterators can be copied with a simple assignment (`GtkTextIter i = j;`). The function is used by language bindings. a copy of the @iter, free with [method@Gtk.TextIter.free] an iterator Returns whether the character at @iter is within an editable region of text. Non-editable text is “locked” and can’t be changed by the user via `GtkTextView`. If no tags applied to this text affect editability, @default_setting will be returned. You don’t want to use this function to decide whether text can be inserted at @iter, because for insertion you don’t want to know whether the char at @iter is inside an editable range, you want to know whether a new character inserted at @iter would be inside an editable range. Use [method@Gtk.TextIter.can_insert] to handle this case. whether @iter is inside an editable range an iterator %TRUE if text is editable by default Returns %TRUE if @iter points to the start of the paragraph delimiter characters for a line. Delimiters will be either a newline, a carriage return, a carriage return followed by a newline, or a Unicode paragraph separator character. Note that an iterator pointing to the \n of a \r\n pair will not be counted as the end of a line, the line ends before the \r. The end iterator is considered to be at the end of a line, even though there are no paragraph delimiter chars there. whether @iter is at the end of a line an iterator Determines whether @iter ends a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language. %TRUE if @iter is at the end of a sentence. a `GtkTextIter` Returns %TRUE if @tag is toggled off at exactly this point. If @tag is %NULL, returns %TRUE if any tag is toggled off at this point. Note that if this function returns %TRUE, it means that @iter is at the end of the tagged range, but that the character at @iter is outside the tagged range. In other words, unlike [method@Gtk.TextIter.starts_tag], if this function returns %TRUE, [method@Gtk.TextIter.has_tag] will return %FALSE for the same parameters. whether @iter is the end of a range tagged with @tag an iterator a `GtkTextTag` Determines whether @iter ends a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language. %TRUE if @iter is at the end of a word a `GtkTextIter` Tests whether two iterators are equal, using the fastest possible mechanism. This function is very fast; you can expect it to perform better than e.g. getting the character offset for each iterator and comparing the offsets yourself. Also, it’s a bit faster than [method@Gtk.TextIter.compare]. %TRUE if the iterators point to the same place in the buffer a `GtkTextIter` another `GtkTextIter` Moves @iter forward by one character offset. Note that images embedded in the buffer occupy 1 character slot, so this function may actually move onto an image instead of a character, if you have images in your buffer. If @iter is the end iterator or one character before it, @iter will now point at the end iterator, and this function returns %FALSE for convenience when writing loops. whether @iter moved and is dereferenceable an iterator Moves @count characters if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. The return value indicates whether the new position of @iter is different from its original position, and dereferenceable (the last iterator in the buffer is not dereferenceable). If @count is 0, the function does nothing and returns %FALSE. whether @iter moved and is dereferenceable an iterator number of characters to move, may be negative Moves @iter forward by a single cursor position. Cursor positions are (unsurprisingly) positions where the cursor can appear. Perhaps surprisingly, there may not be a cursor position between all characters. The most common example for European languages would be a carriage return/newline sequence. For some Unicode characters, the equivalent of say the letter “a” with an accent mark will be represented as two characters, first the letter then a "combining mark" that causes the accent to be rendered; so the cursor can’t go between those two characters. See also the [struct@Pango.LogAttr] struct and the [func@Pango.break] function. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` Moves up to @count cursor positions. See [method@Gtk.TextIter.forward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` number of positions to move Advances @iter, calling @pred on each character. If @pred returns %TRUE, returns %TRUE and stops scanning. If @pred never returns %TRUE, @iter is set to @limit if @limit is non-%NULL, otherwise to the end iterator. whether a match was found a `GtkTextIter` a function to be called on each character user data for @pred search limit Moves @iter to the start of the next line. If the iter is already on the last line of the buffer, moves the iter to the end of the current line. If after the operation, the iter is at the end of the buffer and not dereferenceable, returns %FALSE. Otherwise, returns %TRUE. whether @iter can be dereferenced an iterator Moves @count lines forward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. If @count is negative, moves backward by 0 - @count lines. whether @iter moved and is dereferenceable a `GtkTextIter` number of lines to move forward Searches forward for @str. Any match is returned by setting @match_start to the first character of the match and @match_end to the first character after the match. The search will not continue past @limit. Note that a search is a linear or O(n) operation, so you may wish to use @limit to avoid locking up your UI on large buffers. @match_start will never be set to a `GtkTextIter` located before @iter, even if there is a possible @match_end after or at @iter. whether a match was found start of search a search string flags affecting how the search is done return location for start of match return location for end of match location of last possible @match_end, or %NULL for the end of the buffer Moves forward to the next sentence end. If @iter is at the end of a sentence, moves to the next end of sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` Calls [method@Gtk.TextIter.forward_sentence_end] @count times. If @count is negative, moves backward instead of forward. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` number of sentences to move Moves @iter forward to the “end iterator”, which points one past the last valid character in the buffer. [method@Gtk.TextIter.get_char] called on the end iterator returns 0, which is convenient for writing loops. a `GtkTextIter` Moves the iterator to point to the paragraph delimiter characters. The possible characters are either a newline, a carriage return, a carriage return/newline in sequence, or the Unicode paragraph separator character. If the iterator is already at the paragraph delimiter characters, moves to the paragraph delimiter characters for the next line. If @iter is on the last line in the buffer, which does not end in paragraph delimiters, moves to the end iterator (end of the last line), and returns %FALSE. %TRUE if we moved and the new location is not the end iterator a `GtkTextIter` Moves forward to the next toggle (on or off) of the @tag, or to the next toggle of any tag if @tag is %NULL. If no matching tag toggles are found, returns %FALSE, otherwise %TRUE. Does not return toggles located at @iter, only toggles after @iter. Sets @iter to the location of the toggle, or to the end of the buffer if no toggle is found. whether we found a tag toggle after @iter a `GtkTextIter` a `GtkTextTag` Moves @iter forward to the next visible cursor position. See [method@Gtk.TextIter.forward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` Moves up to @count visible cursor positions. See [method@Gtk.TextIter.forward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` number of positions to move Moves @iter to the start of the next visible line. Returns %TRUE if there was a next line to move to, and %FALSE if @iter was simply moved to the end of the buffer and is now not dereferenceable, or if @iter was already at the end of the buffer. whether @iter can be dereferenced an iterator Moves @count visible lines forward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. If @count is negative, moves backward by 0 - @count lines. whether @iter moved and is dereferenceable a `GtkTextIter` number of lines to move forward Moves forward to the next visible word end. If @iter is currently on a word end, moves forward to the next one after that. Word breaks are determined by Pango and should be correct for nearly any language %TRUE if @iter moved and is not the end iterator a `GtkTextIter` Calls [method@Gtk.TextIter.forward_visible_word_end] up to @count times. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` number of times to move Moves forward to the next word end. If @iter is currently on a word end, moves forward to the next one after that. Word breaks are determined by Pango and should be correct for nearly any language. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` Calls [method@Gtk.TextIter.forward_word_end] up to @count times. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` number of times to move Free an iterator allocated on the heap. This function is intended for use in language bindings, and is not especially useful for applications, because iterators can simply be allocated on the stack. a dynamically-allocated iterator Returns the `GtkTextBuffer` this iterator is associated with. the buffer an iterator Returns the number of bytes in the line containing @iter, including the paragraph delimiters. number of bytes in the line an iterator The Unicode character at this iterator is returned. Equivalent to operator* on a C++ iterator. If the element at this iterator is a non-character element, such as an image embedded in the buffer, the Unicode “unknown” character 0xFFFC is returned. If invoked on the end iterator, zero is returned; zero is not a valid Unicode character. So you can write a loop which ends when this function returns 0. a Unicode character, or 0 if @iter is not dereferenceable an iterator Returns the number of characters in the line containing @iter, including the paragraph delimiters. number of characters in the line an iterator If the location at @iter contains a child anchor, the anchor is returned. Otherwise, %NULL is returned. the anchor at @iter an iterator Returns the language in effect at @iter. If no tags affecting language apply to @iter, the return value is identical to that of [func@Gtk.get_default_language]. language in effect at @iter an iterator Returns the line number containing the iterator. Lines in a `GtkTextBuffer` are numbered beginning with 0 for the first line in the buffer. a line number an iterator Returns the byte index of the iterator, counting from the start of a newline-terminated line. Remember that `GtkTextBuffer` encodes text in UTF-8, and that characters can require a variable number of bytes to represent. distance from start of line, in bytes an iterator Returns the character offset of the iterator, counting from the start of a newline-terminated line. The first character on the line has offset 0. offset from start of line an iterator Returns a list of all `GtkTextMark` at this location. Because marks are not iterable (they don’t take up any "space" in the buffer, they are just marks in between iterable locations), multiple marks can exist in the same place. The returned list is not in any meaningful order. list of `GtkTextMark` an iterator Returns the character offset of an iterator. Each character in a `GtkTextBuffer` has an offset, starting with 0 for the first character in the buffer. Use [method@Gtk.TextBuffer.get_iter_at_offset] to convert an offset back into an iterator. a character offset an iterator If the element at @iter is a paintable, the paintable is returned. Otherwise, %NULL is returned. the paintable at @iter an iterator Returns the text in the given range. A “slice” is an array of characters encoded in UTF-8 format, including the Unicode “unknown” character 0xFFFC for iterable non-character elements in the buffer, such as images. Because images are encoded in the slice, byte and character offsets in the returned array will correspond to byte offsets in the text buffer. Note that 0xFFFC can occur in normal text as well, so it is not a reliable indicator that a paintable or widget is in the buffer. slice of text from the buffer iterator at start of a range iterator at end of a range Returns a list of tags that apply to @iter, in ascending order of priority. The highest-priority tags are last. The `GtkTextTag`s in the list don’t have a reference added, but you have to free the list itself. list of `GtkTextTag` a `GtkTextIter` Returns text in the given range. If the range contains non-text elements such as images, the character and byte offsets in the returned string will not correspond to character and byte offsets in the buffer. If you want offsets to correspond, see [method@Gtk.TextIter.get_slice]. array of characters from the buffer iterator at start of a range iterator at end of a range Returns a list of `GtkTextTag` that are toggled on or off at this point. If @toggled_on is %TRUE, the list contains tags that are toggled on. If a tag is toggled on at @iter, then some non-empty range of characters following @iter has that tag applied to it. If a tag is toggled off, then some non-empty range following @iter does not have the tag applied to it. tags toggled at this point an iterator %TRUE to get toggled-on tags Returns the number of bytes from the start of the line to the given @iter, not counting bytes that are invisible due to tags with the “invisible” flag toggled on. byte index of @iter with respect to the start of the line a `GtkTextIter` Returns the offset in characters from the start of the line to the given @iter, not counting characters that are invisible due to tags with the “invisible” flag toggled on. offset in visible characters from the start of the line a `GtkTextIter` Returns visible text in the given range. Like [method@Gtk.TextIter.get_slice], but invisible text is not included. Invisible text is usually invisible because a `GtkTextTag` with the “invisible” attribute turned on has been applied to it. slice of text from the buffer iterator at start of range iterator at end of range Returns visible text in the given range. Like [method@Gtk.TextIter.get_text], but invisible text is not included. Invisible text is usually invisible because a `GtkTextTag` with the “invisible” attribute turned on has been applied to it. string containing visible text in the range iterator at start of range iterator at end of range Returns %TRUE if @iter points to a character that is part of a range tagged with @tag. See also [method@Gtk.TextIter.starts_tag] and [method@Gtk.TextIter.ends_tag]. whether @iter is tagged with @tag an iterator a `GtkTextTag` Checks whether @iter falls in the range [@start, @end). @start and @end must be in ascending order. %TRUE if @iter is in the range a `GtkTextIter` start of range end of range Determines whether @iter is inside a sentence (as opposed to in between two sentences, e.g. after a period and before the first letter of the next sentence). Sentence boundaries are determined by Pango and should be correct for nearly any language. %TRUE if @iter is inside a sentence. a `GtkTextIter` Determines whether the character pointed by @iter is part of a natural-language word (as opposed to say inside some whitespace). Word breaks are determined by Pango and should be correct for nearly any language. Note that if [method@Gtk.TextIter.starts_word] returns %TRUE, then this function returns %TRUE too, since @iter points to the first character of the word. %TRUE if @iter is inside a word a `GtkTextIter` Determine if @iter is at a cursor position. See [method@Gtk.TextIter.forward_cursor_position] or [struct@Pango.LogAttr] or [func@Pango.break] for details on what a cursor position is. %TRUE if the cursor can be placed at @iter a `GtkTextIter` Returns %TRUE if @iter is the end iterator. This means it is one past the last dereferenceable iterator in the buffer. [method@Gtk.TextIter.is_end] is the most efficient way to check whether an iterator is the end iterator. whether @iter is the end iterator an iterator Returns %TRUE if @iter is the first iterator in the buffer. whether @iter is the first in the buffer an iterator Swaps the value of @first and @second if @second comes before @first in the buffer. That is, ensures that @first and @second are in sequence. Most text buffer functions that take a range call this automatically on your behalf, so there’s no real reason to call it yourself in those cases. There are some exceptions, such as [method@Gtk.TextIter.in_range], that expect a pre-sorted range. a `GtkTextIter` another `GtkTextIter` Moves iterator @iter to the start of the line @line_number. If @line_number is negative or larger than or equal to the number of lines in the buffer, moves @iter to the start of the last line in the buffer. a `GtkTextIter` line number (counted from 0) Same as [method@Gtk.TextIter.set_line_offset], but works with a byte index. The given byte index must be at the start of a character, it can’t be in the middle of a UTF-8 encoded character. a `GtkTextIter` a byte index relative to the start of @iter’s current line Moves @iter within a line, to a new character (not byte) offset. The given character offset must be less than or equal to the number of characters in the line; if equal, @iter moves to the start of the next line. See [method@Gtk.TextIter.set_line_index] if you have a byte index rather than a character offset. a `GtkTextIter` a character offset relative to the start of @iter’s current line Sets @iter to point to @char_offset. @char_offset counts from the start of the entire text buffer, starting with 0. a `GtkTextIter` a character number Like [method@Gtk.TextIter.set_line_index], but the index is in visible bytes, i.e. text with a tag making it invisible is not counted in the index. a `GtkTextIter` a byte index Like [method@Gtk.TextIter.set_line_offset], but the offset is in visible characters, i.e. text with a tag making it invisible is not counted in the offset. a `GtkTextIter` a character offset Returns %TRUE if @iter begins a paragraph. This is the case if [method@Gtk.TextIter.get_line_offset] would return 0. However this function is potentially more efficient than [method@Gtk.TextIter.get_line_offset], because it doesn’t have to compute the offset, it just has to see whether it’s 0. whether @iter begins a line an iterator Determines whether @iter begins a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language. %TRUE if @iter is at the start of a sentence. a `GtkTextIter` Returns %TRUE if @tag is toggled on at exactly this point. If @tag is %NULL, returns %TRUE if any tag is toggled on at this point. Note that if this function returns %TRUE, it means that @iter is at the beginning of the tagged range, and that the character at @iter is inside the tagged range. In other words, unlike [method@Gtk.TextIter.ends_tag], if this function returns %TRUE, [method@Gtk.TextIter.has_tag] will also return %TRUE for the same parameters. whether @iter is the start of a range tagged with @tag an iterator a `GtkTextTag` Determines whether @iter begins a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language. %TRUE if @iter is at the start of a word a `GtkTextIter` Gets whether a range with @tag applied to it begins or ends at @iter. This is equivalent to (gtk_text_iter_starts_tag() || gtk_text_iter_ends_tag()) whether @tag is toggled on or off at @iter an iterator a `GtkTextTag` Marks a position in a `GtkTextbuffer` that is preserved across modifications. You may wish to begin by reading the [text widget conceptual overview](section-text-widget.html), which gives an overview of all the objects and data types related to the text widget and how they work together. A `GtkTextMark` is like a bookmark in a text buffer; it preserves a position in the text. You can convert the mark to an iterator using [method@Gtk.TextBuffer.get_iter_at_mark]. Unlike iterators, marks remain valid across buffer mutations, because their behavior is defined when text is inserted or deleted. When text containing a mark is deleted, the mark remains in the position originally occupied by the deleted text. When text is inserted at a mark, a mark with “left gravity” will be moved to the beginning of the newly-inserted text, and a mark with “right gravity” will be moved to the end. Note that “left” and “right” here refer to logical direction (left is the toward the start of the buffer); in some languages such as Hebrew the logically-leftmost text is not actually on the left when displayed. Marks are reference counted, but the reference count only controls the validity of the memory; marks can be deleted from the buffer at any time with [method@Gtk.TextBuffer.delete_mark]. Once deleted from the buffer, a mark is essentially useless. Marks optionally have names; these can be convenient to avoid passing the `GtkTextMark` object around. Marks are typically created using the [method@Gtk.TextBuffer.create_mark] function. Creates a text mark. Add it to a buffer using [method@Gtk.TextBuffer.add_mark]. If @name is %NULL, the mark is anonymous; otherwise, the mark can be retrieved by name using [method@Gtk.TextBuffer.get_mark]. If a mark has left gravity, and text is inserted at the mark’s current location, the mark will be moved to the left of the newly-inserted text. If the mark has right gravity (@left_gravity = %FALSE), the mark will end up on the right of newly-inserted text. The standard left-to-right cursor is a mark with right gravity (when you type, the cursor stays on the right side of the text you’re typing). new `GtkTextMark` mark name whether the mark should have left gravity Gets the buffer this mark is located inside. Returns %NULL if the mark is deleted. the mark’s `GtkTextBuffer` a `GtkTextMark` Returns %TRUE if the mark has been removed from its buffer. See [method@Gtk.TextBuffer.add_mark] for a way to add it to a buffer again. whether the mark is deleted a `GtkTextMark` Determines whether the mark has left gravity. %TRUE if the mark has left gravity, %FALSE otherwise a `GtkTextMark` Returns the mark name. Returns %NULL for anonymous marks. mark name a `GtkTextMark` Returns %TRUE if the mark is visible. A cursor is displayed for visible marks. %TRUE if visible a `GtkTextMark` Sets the visibility of @mark. The insertion point is normally visible, i.e. you can see it as a vertical bar. Also, the text widget uses a visible mark to indicate where a drop will occur when dragging-and-dropping text. Most other marks are not visible. Marks are not visible by default. a GtkTextMark visibility of mark Whether the mark has left gravity. When text is inserted at the mark’s current location, if the mark has left gravity it will be moved to the left of the newly-inserted text, otherwise to the right. The name of the mark or %NULL if the mark is anonymous. Flags affecting how a search is done. If neither `GTK_TEXT_SEARCH_VISIBLE_ONLY` nor `GTK_TEXT_SEARCH_TEXT_ONLY` are enabled, the match must be exact; the special 0xFFFC character will match embedded paintables or child widgets. Search only visible data. A search match may have invisible text interspersed. Search only text. A match may have paintables or child widgets mixed inside the matched range. The text will be matched regardless of what case it is in. Can be applied to text contained in a `GtkTextBuffer`. You may wish to begin by reading the [text widget conceptual overview](section-text-widget.html), which gives an overview of all the objects and data types related to the text widget and how they work together. Tags should be in the [class@Gtk.TextTagTable] for a given `GtkTextBuffer` before using them with that buffer. [method@Gtk.TextBuffer.create_tag] is the best way to create tags. See “gtk4-demo” for numerous examples. For each property of `GtkTextTag`, there is a “set” property, e.g. “font-set” corresponds to “font”. These “set” properties reflect whether a property has been set or not. They are maintained by GTK and you should not set them independently. Creates a `GtkTextTag`. a new `GtkTextTag` tag name Emits the [signal@Gtk.TextTagTable::tag-changed] signal on the `GtkTextTagTable` where the tag is included. The signal is already emitted when setting a `GtkTextTag` property. This function is useful for a `GtkTextTag` subclass. a `GtkTextTag` whether the change affects the `GtkTextView` layout Get the tag priority. The tag’s priority. a `GtkTextTag` Sets the priority of a `GtkTextTag`. Valid priorities start at 0 and go to one less than [method@Gtk.TextTagTable.get_size]. Each tag in a table has a unique priority; setting the priority of one tag shifts the priorities of all the other tags in the table to maintain a unique priority for each tag. Higher priority tags “win” if two tags both set the same text attribute. When adding a tag to a tag table, it will be assigned the highest priority in the table by default; so normally the precedence of a set of tags is the order in which they were added to the table, or created with [method@Gtk.TextBuffer.create_tag], which adds the tag to the buffer’s table automatically. a `GtkTextTag` the new priority Whether the margins accumulate or override each other. When set to %TRUE the margins of this tag are added to the margins of any other non-accumulative margins present. When set to %FALSE the margins override one another (the default). Whether breaks are allowed. Whether the `allow-breaks` property is set. Background color as a string. Whether the background color fills the entire line height or only the height of the tagged characters. Whether the `background-full-height` property is set. Background color as a `GdkRGBA`. Whether the `background` property is set. Text direction, e.g. right-to-left or left-to-right. Whether the text can be modified by the user. Whether the `editable` property is set. Whether font fallback is enabled. When set to %TRUE, other fonts will be substituted where the current font is missing glyphs. Whether the `fallback` property is set. Name of the font family, e.g. Sans, Helvetica, Times, Monospace. Whether the `family` property is set. Font description as string, e.g. \"Sans Italic 12\". Note that the initial value of this property depends on the internals of `PangoFontDescription`. Font description as a `PangoFontDescription`. OpenType font features, as a string. Whether the `font-features` property is set. Foreground color as a string. Foreground color as a `GdkRGBA`. Whether the `foreground` property is set. Amount to indent the paragraph, in pixels. A negative value of indent will produce a hanging indentation. That is, the first line will have the full width, and subsequent lines will be indented by the absolute value of indent. Whether the `indent` property is set. Whether to insert hyphens at breaks. Whether the `insert-hyphens` property is set. Whether this text is hidden. Note that there may still be problems with the support for invisible text, in particular when navigating programmatically inside a buffer containing invisible segments. Whether the `invisible` property is set. Left, right, or center justification. Whether the `justification` property is set. The language this text is in, as an ISO code. Pango can use this as a hint when rendering the text. If not set, an appropriate default will be used. Note that the initial value of this property depends on the current locale, see also [func@Gtk.get_default_language]. Whether the `language` property is set. Width of the left margin in pixels. Whether the `left-margin` property is set. Extra spacing between graphemes, in Pango units. Whether the `letter-spacing` property is set. Factor to scale line height by. Whether the `line-height` property is set. The name used to refer to the tag. %NULL for anonymous tags. Style of overline for this text. This property modifies the color of overlines. If not set, overlines will use the foreground color. Whether the `overline-rgba` property is set. Whether the `overline` property is set. The paragraph background color as a string. The paragraph background color as a `GdkRGBA`. Whether the `paragraph-background` property is set. Pixels of blank space above paragraphs. Whether the `pixels-above-lines` property is set. Pixels of blank space below paragraphs. Whether the `pixels-below-lines` property is set. Pixels of blank space between wrapped lines in a paragraph. Whether the `pixels-inside-wrap` property is set. Width of the right margin, in pixels. Whether the `right-margin` property is set. Offset of text above the baseline, in Pango units. Negative values go below the baseline. Whether the `rise` property is set. Font size as a scale factor relative to the default font size. This properly adapts to theme changes, etc. so is recommended. Pango predefines some scales such as %PANGO_SCALE_X_LARGE. Whether the `scale` property is set. Whether this tag represents a single sentence. This affects cursor movement. Whether the `sentence` property is set. How to render invisible characters. Whether the `show-spaces` property is set. Font size in Pango units. Font size in points. Whether the `size` property is set. Font stretch as a `PangoStretch`, e.g. %PANGO_STRETCH_CONDENSED. Whether the `stretch` property is set. Whether to strike through the text. This property modifies the color of strikeouts. If not set, strikeouts will use the foreground color. If the `strikethrough-rgba` property has been set. Whether the `strikethrough` property is set. Font style as a `PangoStyle`, e.g. %PANGO_STYLE_ITALIC. Whether the `style` property is set. Custom tabs for this text. Whether the `tabs` property is set. How to transform the text for display. Whether the `text-transform` property is set. Style of underline for this text. This property modifies the color of underlines. If not set, underlines will use the foreground color. If [property@Gtk.TextTag:underline] is set to %PANGO_UNDERLINE_ERROR, an alternate color may be applied instead of the foreground. Setting this property will always override those defaults. If the `underline-rgba` property has been set. Whether the `underline` property is set. Font variant as a `PangoVariant`, e.g. %PANGO_VARIANT_SMALL_CAPS. Whether the `variant` property is set. Font weight as an integer. Whether the `weight` property is set. Whether this tag represents a single word. This affects line breaks and cursor movement. Whether the `word` property is set. Whether to wrap lines never, at word boundaries, or at character boundaries. Whether the `wrap-mode` property is set. Collects the tags in a `GtkTextBuffer`. You may wish to begin by reading the [text widget conceptual overview](section-text-widget.html), which gives an overview of all the objects and data types related to the text widget and how they work together. # GtkTextTagTables as GtkBuildable The `GtkTextTagTable` implementation of the `GtkBuildable` interface supports adding tags by specifying “tag” as the “type” attribute of a `<child>` element. An example of a UI definition fragment specifying tags: ```xml <object class="GtkTextTagTable"> <child type="tag"> <object class="GtkTextTag"/> </child> </object> ``` Creates a new `GtkTextTagTable`. The table contains no tags by default. a new `GtkTextTagTable` Add a tag to the table. The tag is assigned the highest priority in the table. @tag must not be in a tag table already, and may not have the same name as an already-added tag. %TRUE on success. a `GtkTextTagTable` a `GtkTextTag` Calls @func on each tag in @table, with user data @data. Note that the table may not be modified while iterating over it (you can’t add/remove tags). a `GtkTextTagTable` a function to call on each tag user data Returns the size of the table (number of tags) number of tags in @table a `GtkTextTagTable` Look up a named tag. The tag a `GtkTextTagTable` name of a tag Remove a tag from the table. If a `GtkTextBuffer` has @table as its tag table, the tag is removed from the buffer. The table’s reference to the tag is removed, so the tag will end up destroyed if you don’t have a reference to it. a `GtkTextTagTable` a `GtkTextTag` Emitted every time a new tag is added in the `GtkTextTagTable`. the added tag. Emitted every time a tag in the `GtkTextTagTable` changes. the changed tag. whether the change affects the `GtkTextView` layout. Emitted every time a tag is removed from the `GtkTextTagTable`. The @tag is still valid by the time the signal is emitted, but it is not associated with a tag table any more. the removed tag. A function used with gtk_text_tag_table_foreach(), to iterate over every `GtkTextTag` inside a `GtkTextTagTable`. the `GtkTextTag` data passed to gtk_text_tag_table_foreach() Displays the contents of a [class@Gtk.TextBuffer]. <picture> <source srcset="multiline-text-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkTextView" src="multiline-text.png"> </picture> You may wish to begin by reading the [conceptual overview](section-text-widget.html), which gives an overview of all the objects and data types related to the text widget and how they work together. ## Shortcuts and Gestures `GtkTextView` supports the following keyboard shortcuts: - <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. - <kbd>Ctrl</kbd>+<kbd>Z</kbd> undoes the last modification. - <kbd>Ctrl</kbd>+<kbd>Y</kbd> or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Z</kbd> redoes the last undone modification. - <kbd>Clear</kbd> clears the content. Additionally, the following signals have default keybindings: - [signal@Gtk.TextView::backspace] - [signal@Gtk.TextView::copy-clipboard] - [signal@Gtk.TextView::cut-clipboard] - [signal@Gtk.TextView::delete-from-cursor] - [signal@Gtk.TextView::insert-emoji] - [signal@Gtk.TextView::move-cursor] - [signal@Gtk.TextView::paste-clipboard] - [signal@Gtk.TextView::select-all] - [signal@Gtk.TextView::toggle-cursor-visible] - [signal@Gtk.TextView::toggle-overwrite] ## Actions `GtkTextView` defines a set of built-in actions: - `clipboard.copy` copies the contents to the clipboard. - `clipboard.cut` copies the contents to the clipboard and deletes it from the widget. - `clipboard.paste` inserts the contents of the clipboard into the widget. - `menu.popup` opens the context menu. - `misc.insert-emoji` opens the Emoji chooser. - `selection.delete` deletes the current selection. - `selection.select-all` selects all of the widgets content. - `text.redo` redoes the last change to the contents. - `text.undo` undoes the last change to the contents. - `text.clear` clears the content. ## CSS nodes ``` textview.view ├── border.top ├── border.left ├── text │ ╰── [selection] ├── border.right ├── border.bottom ╰── [window.popup] ``` `GtkTextView` has a main css node with name textview and style class .view, and subnodes for each of the border windows, and the main text area, with names border and text, respectively. The border nodes each get one of the style classes .left, .right, .top or .bottom. A node representing the selection will appear below the text node. If a context menu is opened, the window node will appear as a subnode of the main node. ## Accessibility `GtkTextView` uses the [enum@Gtk.AccessibleRole.text_box] role. Creates a new `GtkTextView`. If you don’t call [method@Gtk.TextView.set_buffer] before using the text view, an empty default buffer will be created for you. Get the buffer with [method@Gtk.TextView.get_buffer]. If you want to specify your own buffer, consider [ctor@Gtk.TextView.new_with_buffer]. a new `GtkTextView` Creates a new `GtkTextView` widget displaying the buffer @buffer. One buffer can be shared among many widgets. @buffer may be %NULL to create a default buffer, in which case this function is equivalent to [ctor@Gtk.TextView.new]. The text view adds its own reference count to the buffer; it does not take over an existing reference. a new `GtkTextView`. a `GtkTextBuffer` The class handler for the `GtkTextView::backspace` keybinding signal. The class handler for the `GtkTextView::copy-clipboard` keybinding signal. The create_buffer vfunc is called to create a `GtkTextBuffer` for the text view. The default implementation is to just call gtk_text_buffer_new(). The class handler for the `GtkTextView::cut-clipboard` keybinding signal The class handler for the `GtkTextView::delete-from-cursor` keybinding signal. The class handler for the `GtkTextView::extend-selection` signal. The class handler for the `GtkTextView::insert-at-cursor` keybinding signal. The class handler for the `GtkTextView::insert-emoji` signal. The class handler for the `GtkTextView::move-cursor` keybinding signal. The class handler for the `GtkTextView::paste-clipboard` keybinding signal. The class handler for the `GtkTextView::set-anchor` keybinding signal. The snapshot_layer vfunc is called before and after the text view is drawing its own text. Applications can override this vfunc in a subclass to draw customized content underneath or above the text. In the %GTK_TEXT_VIEW_LAYER_BELOW_TEXT and %GTK_TEXT_VIEW_LAYER_ABOVE_TEXT layers the drawing is done in the buffer coordinate space. The class handler for the `GtkTextView::toggle-overwrite` keybinding signal. Adds a child widget in the text buffer, at the given @anchor. a `GtkTextView` a `GtkWidget` a `GtkTextChildAnchor` in the `GtkTextBuffer` for @text_view Adds @child at a fixed coordinate in the `GtkTextView`'s text window. The @xpos and @ypos must be in buffer coordinates (see [method@Gtk.TextView.get_iter_location] to convert to buffer coordinates). @child will scroll with the text view. If instead you want a widget that will not move with the `GtkTextView` contents see `GtkOverlay`. a `GtkTextView` a `GtkWidget` X position of child in window coordinates Y position of child in window coordinates Moves the given @iter backward by one display (wrapped) line. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the `GtkTextBuffer`. %TRUE if @iter was moved and is not on the end iterator a `GtkTextView` a `GtkTextIter` Moves the given @iter backward to the next display line start. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the `GtkTextBuffer`. %TRUE if @iter was moved and is not on the end iterator a `GtkTextView` a `GtkTextIter` Converts buffer coordinates to window coordinates. a `GtkTextView` a `GtkTextWindowType` buffer x coordinate buffer y coordinate window x coordinate return location window y coordinate return location Moves the given @iter forward by one display (wrapped) line. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the `GtkTextBuffer`. %TRUE if @iter was moved and is not on the end iterator a `GtkTextView` a `GtkTextIter` Moves the given @iter forward to the next display line end. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the `GtkTextBuffer`. %TRUE if @iter was moved and is not on the end iterator a `GtkTextView` a `GtkTextIter` Returns whether pressing the <kbd>Tab</kbd> key inserts a tab characters. See [method@Gtk.TextView.set_accepts_tab]. %TRUE if pressing the Tab key inserts a tab character, %FALSE if pressing the Tab key moves the keyboard focus. A `GtkTextView` Gets the bottom margin for text in the @text_view. bottom margin in pixels a `GtkTextView` Returns the `GtkTextBuffer` being displayed by this text view. The reference count on the buffer is not incremented; the caller of this function won’t own a new reference. a `GtkTextBuffer` a `GtkTextView` Determine the positions of the strong and weak cursors if the insertion point is at @iter. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction of the paragraph are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the paragraph are inserted. If @iter is %NULL, the actual cursor position is used. Note that if @iter happens to be the actual cursor position, and there is currently an IM preedit sequence being entered, the returned locations will be adjusted to account for the preedit cursor’s offset within the preedit sequence. The rectangle position is in buffer coordinates; use [method@Gtk.TextView.buffer_to_window_coords] to convert these coordinates to coordinates for one of the windows in the text view. a `GtkTextView` a `GtkTextIter` location to store the strong cursor position location to store the weak cursor position Find out whether the cursor should be displayed. whether the insertion mark is visible a `GtkTextView` Returns the default editability of the `GtkTextView`. Tags in the buffer may override this setting for some ranges of text. whether text is editable by default a `GtkTextView` Gets the menu model that gets added to the context menu or %NULL if none has been set. the menu model a `GtkTextView` Gets a `GtkWidget` that has previously been set as gutter. See [method@Gtk.TextView.set_gutter]. @win must be one of %GTK_TEXT_WINDOW_LEFT, %GTK_TEXT_WINDOW_RIGHT, %GTK_TEXT_WINDOW_TOP, or %GTK_TEXT_WINDOW_BOTTOM. a `GtkWidget` a `GtkTextView` a `GtkTextWindowType` Gets the default indentation of paragraphs in @text_view. Tags in the view’s buffer may override the default. The indentation may be negative. number of pixels of indentation a `GtkTextView` Gets the `input-hints` of the `GtkTextView`. the input hints a `GtkTextView` Gets the `input-purpose` of the `GtkTextView`. the input purpose a `GtkTextView` Retrieves the iterator at buffer coordinates @x and @y. Buffer coordinates are coordinates for the entire buffer, not just the currently-displayed portion. If you have coordinates from an event, you have to convert those to buffer coordinates with [method@Gtk.TextView.window_to_buffer_coords]. %TRUE if the position is over text a `GtkTextView` a `GtkTextIter` x position, in buffer coordinates y position, in buffer coordinates Retrieves the iterator pointing to the character at buffer coordinates @x and @y. Buffer coordinates are coordinates for the entire buffer, not just the currently-displayed portion. If you have coordinates from an event, you have to convert those to buffer coordinates with [method@Gtk.TextView.window_to_buffer_coords]. Note that this is different from [method@Gtk.TextView.get_iter_at_location], which returns cursor locations, i.e. positions between characters. %TRUE if the position is over text a `GtkTextView` a `GtkTextIter` if non-%NULL, location to store an integer indicating where in the grapheme the user clicked. It will either be zero, or the number of characters in the grapheme. 0 represents the trailing edge of the grapheme. x position, in buffer coordinates y position, in buffer coordinates Gets a rectangle which roughly contains the character at @iter. The rectangle position is in buffer coordinates; use [method@Gtk.TextView.buffer_to_window_coords] to convert these coordinates to coordinates for one of the windows in the text view. a `GtkTextView` a `GtkTextIter` bounds of the character at @iter Gets the default justification of paragraphs in @text_view. Tags in the buffer may override the default. default justification a `GtkTextView` Gets the default left margin size of paragraphs in the @text_view. Tags in the buffer may override the default. left margin in pixels a `GtkTextView` Gets the `GtkTextIter` at the start of the line containing the coordinate @y. @y is in buffer coordinates, convert from window coordinates with [method@Gtk.TextView.window_to_buffer_coords]. If non-%NULL, @line_top will be filled with the coordinate of the top edge of the line. a `GtkTextView` a `GtkTextIter` a y coordinate return location for top coordinate of the line Gets the y coordinate of the top of the line containing @iter, and the height of the line. The coordinate is a buffer coordinate; convert to window coordinates with [method@Gtk.TextView.buffer_to_window_coords]. a `GtkTextView` a `GtkTextIter` return location for a y coordinate return location for a height Gets the `PangoContext` that is used for rendering LTR directed text layouts. The context may be replaced when CSS changes occur. a `PangoContext` a `GtkTextView` Gets whether the `GtkTextView` uses monospace styling. %TRUE if monospace fonts are desired a `GtkTextView` Returns whether the `GtkTextView` is in overwrite mode or not. whether @text_view is in overwrite mode or not. a `GtkTextView` Gets the default number of pixels to put above paragraphs. Adding this function with [method@Gtk.TextView.get_pixels_below_lines] is equal to the line space between each paragraph. default number of pixels above paragraphs a `GtkTextView` Gets the default number of pixels to put below paragraphs. The line space is the sum of the value returned by this function and the value returned by [method@Gtk.TextView.get_pixels_above_lines]. default number of blank pixels below paragraphs a `GtkTextView` Gets the default number of pixels to put between wrapped lines inside a paragraph. default number of pixels of blank space between wrapped lines a `GtkTextView` Gets the default right margin for text in @text_view. Tags in the buffer may override the default. right margin in pixels a `GtkTextView` Gets the `PangoContext` that is used for rendering RTL directed text layouts. The context may be replaced when CSS changes occur. a `PangoContext` a `GtkTextView` Gets the default tabs for @text_view. Tags in the buffer may override the defaults. The returned array will be %NULL if “standard” (8-space) tabs are used. Free the return value with [method@Pango.TabArray.free]. copy of default tab array, or %NULL if standard tabs are used; must be freed with [method@Pango.TabArray.free]. a `GtkTextView` Gets the top margin for text in the @text_view. top margin in pixels a `GtkTextView` Gets the X,Y offset in buffer coordinates of the top-left corner of the textview's text contents. This allows for more-precise positioning than what is provided by [method@Gtk.TextView.get_visible_rect] as you can discover what device pixel is being quantized for text positioning. You might want this when making ulterior widgets align with quantized device pixels of the textview contents such as line numbers. a `GtkTextView` a location for the X offset a location for the Y offset Fills @visible_rect with the currently-visible region of the buffer, in buffer coordinates. Convert to window coordinates with [method@Gtk.TextView.buffer_to_window_coords]. a `GtkTextView` rectangle to fill Gets the line wrapping for the view. the line wrap setting a `GtkTextView` Allow the `GtkTextView` input method to internally handle key press and release events. If this function returns %TRUE, then no further processing should be done for this key event. See [method@Gtk.IMContext.filter_keypress]. Note that you are expected to call this function from your handler when overriding key event handling. This is needed in the case when you need to insert your own key handling between the input method and the default key event handling of the `GtkTextView`. ```c static gboolean gtk_foo_bar_key_press_event (GtkWidget *widget, GdkEvent *event) { guint keyval; gdk_event_get_keyval ((GdkEvent*)event, &keyval); if (keyval == GDK_KEY_Return || keyval == GDK_KEY_KP_Enter) { if (gtk_text_view_im_context_filter_keypress (GTK_TEXT_VIEW (widget), event)) return TRUE; } // Do some stuff return GTK_WIDGET_CLASS (gtk_foo_bar_parent_class)->key_press_event (widget, event); } ``` %TRUE if the input method handled the key event. a `GtkTextView` the key event Moves a mark within the buffer so that it's located within the currently-visible text area. %TRUE if the mark moved (wasn’t already onscreen) a `GtkTextView` a `GtkTextMark` Updates the position of a child. See [method@Gtk.TextView.add_overlay]. a `GtkTextView` a widget already added with [method@Gtk.TextView.add_overlay] new X position in buffer coordinates new Y position in buffer coordinates Move the iterator a given number of characters visually, treating it as the strong cursor position. If @count is positive, then the new strong cursor position will be @count positions to the right of the old cursor position. If @count is negative then the new strong cursor position will be @count positions to the left of the old cursor position. In the presence of bi-directional text, the correspondence between logical and visual order will depend on the direction of the current run, and there may be jumps when the cursor is moved off of the end of a run. %TRUE if @iter moved and is not on the end iterator a `GtkTextView` a `GtkTextIter` number of characters to move (negative moves left, positive moves right) Moves the cursor to the currently visible region of the buffer. %TRUE if the cursor had to be moved. a `GtkTextView` Removes a child widget from @text_view. a `GtkTextView` the child to remove Ensures that the cursor is shown. This also resets the time that it will stay blinking (or visible, in case blinking is disabled). This function should be called in response to user input (e.g. from derived classes that override the textview's event handlers). a `GtkTextView` Reset the input method context of the text view if needed. This can be necessary in the case where modifying the buffer would confuse on-going input method behavior. a `GtkTextView` Scrolls @text_view the minimum distance such that @mark is contained within the visible area of the widget. a `GtkTextView` a mark in the buffer for @text_view Scrolls @text_view so that @iter is on the screen in the position indicated by @xalign and @yalign. An alignment of 0.0 indicates left or top, 1.0 indicates right or bottom, 0.5 means center. If @use_align is %FALSE, the text scrolls the minimal distance to get the mark onscreen, possibly not scrolling at all. The effective screen for purposes of this function is reduced by a margin of size @within_margin. Note that this function uses the currently-computed height of the lines in the text buffer. Line heights are computed in an idle handler; so this function may not have the desired effect if it’s called before the height computations. To avoid oddness, consider using [method@Gtk.TextView.scroll_to_mark] which saves a point to be scrolled to after line validation. %TRUE if scrolling occurred a `GtkTextView` a `GtkTextIter` margin as a [0.0,0.5) fraction of screen size whether to use alignment arguments (if %FALSE, just get the mark onscreen) horizontal alignment of mark within visible area vertical alignment of mark within visible area Scrolls @text_view so that @mark is on the screen in the position indicated by @xalign and @yalign. An alignment of 0.0 indicates left or top, 1.0 indicates right or bottom, 0.5 means center. If @use_align is %FALSE, the text scrolls the minimal distance to get the mark onscreen, possibly not scrolling at all. The effective screen for purposes of this function is reduced by a margin of size @within_margin. a `GtkTextView` a `GtkTextMark` margin as a [0.0,0.5) fraction of screen size whether to use alignment arguments (if %FALSE, just get the mark onscreen) horizontal alignment of mark within visible area vertical alignment of mark within visible area Sets the behavior of the text widget when the <kbd>Tab</kbd> key is pressed. If @accepts_tab is %TRUE, a tab character is inserted. If @accepts_tab is %FALSE the keyboard focus is moved to the next widget in the focus chain. Focus can always be moved using <kbd>Ctrl</kbd>+<kbd>Tab</kbd>. A `GtkTextView` %TRUE if pressing the Tab key should insert a tab character, %FALSE, if pressing the Tab key should move the keyboard focus. Sets the bottom margin for text in @text_view. Note that this function is confusingly named. In CSS terms, the value set here is padding. a `GtkTextView` bottom margin in pixels Sets @buffer as the buffer being displayed by @text_view. The previous buffer displayed by the text view is unreferenced, and a reference is added to @buffer. If you owned a reference to @buffer before passing it to this function, you must remove that reference yourself; `GtkTextView` will not “adopt” it. a `GtkTextView` a `GtkTextBuffer` Toggles whether the insertion point should be displayed. A buffer with no editable text probably shouldn’t have a visible cursor, so you may want to turn the cursor off. Note that this property may be overridden by the [property@Gtk.Settings:gtk-keynav-use-caret] setting. a `GtkTextView` whether to show the insertion cursor Sets the default editability of the `GtkTextView`. You can override this default setting with tags in the buffer, using the “editable” attribute of tags. a `GtkTextView` whether it’s editable Sets a menu model to add when constructing the context menu for @text_view. You can pass %NULL to remove a previously set extra menu. a `GtkTextView` a `GMenuModel` Places @widget into the gutter specified by @win. @win must be one of %GTK_TEXT_WINDOW_LEFT, %GTK_TEXT_WINDOW_RIGHT, %GTK_TEXT_WINDOW_TOP, or %GTK_TEXT_WINDOW_BOTTOM. a `GtkTextView` a `GtkTextWindowType` a `GtkWidget` Sets the default indentation for paragraphs in @text_view. Tags in the buffer may override the default. a `GtkTextView` indentation in pixels Sets the `input-hints` of the `GtkTextView`. The `input-hints` allow input methods to fine-tune their behaviour. a `GtkTextView` the hints Sets the `input-purpose` of the `GtkTextView`. The `input-purpose` can be used by on-screen keyboards and other input methods to adjust their behaviour. a `GtkTextView` the purpose Sets the default justification of text in @text_view. Tags in the view’s buffer may override the default. a `GtkTextView` justification Sets the default left margin for text in @text_view. Tags in the buffer may override the default. Note that this function is confusingly named. In CSS terms, the value set here is padding. a `GtkTextView` left margin in pixels Sets whether the `GtkTextView` should display text in monospace styling. a `GtkTextView` %TRUE to request monospace styling Changes the `GtkTextView` overwrite mode. a `GtkTextView` %TRUE to turn on overwrite mode, %FALSE to turn it off Sets the default number of blank pixels above paragraphs in @text_view. Tags in the buffer for @text_view may override the defaults. a `GtkTextView` pixels above paragraphs Sets the default number of pixels of blank space to put below paragraphs in @text_view. May be overridden by tags applied to @text_view’s buffer. a `GtkTextView` pixels below paragraphs Sets the default number of pixels of blank space to leave between display/wrapped lines within a paragraph. May be overridden by tags in @text_view’s buffer. a `GtkTextView` default number of pixels between wrapped lines Sets the default right margin for text in the text view. Tags in the buffer may override the default. Note that this function is confusingly named. In CSS terms, the value set here is padding. a `GtkTextView` right margin in pixels Sets the default tab stops for paragraphs in @text_view. Tags in the buffer may override the default. a `GtkTextView` tabs as a `PangoTabArray` Sets the top margin for text in @text_view. Note that this function is confusingly named. In CSS terms, the value set here is padding. a `GtkTextView` top margin in pixels Sets the line wrapping for the view. a `GtkTextView` a `GtkWrapMode` Determines whether @iter is at the start of a display line. See [method@Gtk.TextView.forward_display_line] for an explanation of display lines vs. paragraphs. %TRUE if @iter begins a wrapped line a `GtkTextView` a `GtkTextIter` Converts coordinates on the window identified by @win to buffer coordinates. a `GtkTextView` a `GtkTextWindowType` window x coordinate window y coordinate buffer x coordinate return location buffer y coordinate return location Whether Tab will result in a tab character being entered. The bottom margin for text in the text view. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Don't confuse this property with [property@Gtk.Widget:margin-bottom]. The buffer which is displayed. If the insertion cursor is shown. Whether the text can be modified by the user. A menu model whose contents will be appended to the context menu. Which IM (input method) module should be used for this text_view. See [class@Gtk.IMMulticontext]. Setting this to a non-%NULL value overrides the system-wide IM module setting. See the GtkSettings [property@Gtk.Settings:gtk-im-module] property. Amount to indent the paragraph, in pixels. A negative value of indent will produce a hanging indentation. That is, the first line will have the full width, and subsequent lines will be indented by the absolute value of indent. Additional hints (beyond [property@Gtk.TextView:input-purpose]) that allow input methods to fine-tune their behaviour. The purpose of this text field. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. Left, right, or center justification. The default left margin for text in the text view. Tags in the buffer may override the default. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Whether text should be displayed in a monospace font. If %TRUE, set the .monospace style class on the text view to indicate that a monospace font is desired. Whether entered text overwrites existing contents. Pixels of blank space above paragraphs. Pixels of blank space below paragraphs. Pixels of blank space between wrapped lines in a paragraph. The default right margin for text in the text view. Tags in the buffer may override the default. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Custom tabs for this text. The top margin for text in the text view. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Don't confuse this property with [property@Gtk.Widget:margin-top]. Whether to wrap lines never, at word boundaries, or at character boundaries. Gets emitted when the user asks for it. The ::backspace signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Backspace</kbd> and <kbd>Shift</kbd>+<kbd>Backspace</kbd>. Gets emitted to copy the selection to the clipboard. The ::copy-clipboard signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>c</kbd> and <kbd>Ctrl</kbd>+<kbd>Insert</kbd>. Gets emitted to cut the selection to the clipboard. The ::cut-clipboard signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>x</kbd> and <kbd>Shift</kbd>+<kbd>Delete</kbd>. Gets emitted when the user initiates a text deletion. The ::delete-from-cursor signal is a [keybinding signal](class.SignalAction.html). If the @type is %GTK_DELETE_CHARS, GTK deletes the selection if there is one, otherwise it deletes the requested number of characters. The default bindings for this signal are <kbd>Delete</kbd> for deleting a character, <kbd>Ctrl</kbd>+<kbd>Delete</kbd> for deleting a word and <kbd>Ctrl</kbd>+<kbd>Backspace</kbd> for deleting a word backwards. the granularity of the deletion, as a `GtkDeleteType` the number of @type units to delete Emitted when the selection needs to be extended at @location. %GDK_EVENT_STOP to stop other handlers from being invoked for the event. %GDK_EVENT_PROPAGATE to propagate the event further. the granularity type the location where to extend the selection where the selection should start where the selection should end Gets emitted when the user initiates the insertion of a fixed string at the cursor. The ::insert-at-cursor signal is a [keybinding signal](class.SignalAction.html). This signal has no default bindings. the string to insert Gets emitted to present the Emoji chooser for the @text_view. The ::insert-emoji signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>.</kbd> and <kbd>Ctrl</kbd>+<kbd>;</kbd> Gets emitted when the user initiates a cursor movement. The ::move-cursor signal is a [keybinding signal](class.SignalAction.html). If the cursor is not visible in @text_view, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the <kbd>Shift</kbd> modifier extends the selection, the variant without it does not. There are too many key combinations to list them all here. - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move by individual characters/lines - <kbd>Ctrl</kbd>+<kbd>←</kbd>, etc. move by words/paragraphs - <kbd>Home</kbd> and <kbd>End</kbd> move to the ends of the buffer - <kbd>PgUp</kbd> and <kbd>PgDn</kbd> move vertically by pages - <kbd>Ctrl</kbd>+<kbd>PgUp</kbd> and <kbd>Ctrl</kbd>+<kbd>PgDn</kbd> move horizontally by pages the granularity of the move, as a `GtkMovementStep` the number of @step units to move %TRUE if the move should extend the selection Gets emitted to move the viewport. The ::move-viewport signal is a [keybinding signal](class.SignalAction.html), which can be bound to key combinations to allow the user to move the viewport, i.e. change what part of the text view is visible in a containing scrolled window. There are no default bindings for this signal. the granularity of the movement, as a `GtkScrollStep` the number of @step units to move Gets emitted to paste the contents of the clipboard into the text view. The ::paste-clipboard signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>v</kbd> and <kbd>Shift</kbd>+<kbd>Insert</kbd>. Emitted when preedit text of the active IM changes. If an input method is used, the typed text will not immediately be committed to the buffer. So if you are interested in the text, connect to this signal. This signal is only emitted if the text at the given position is actually editable. the current preedit string Gets emitted to select or unselect the complete contents of the text view. The ::select-all signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>a</kbd> and <kbd>Ctrl</kbd>+<kbd>/</kbd> for selecting and <kbd>Shift</kbd>+<kbd>Ctrl</kbd>+<kbd>a</kbd> and <kbd>Ctrl</kbd>+<kbd>\</kbd> for unselecting. %TRUE to select, %FALSE to unselect Gets emitted when the user initiates settings the "anchor" mark. The ::set-anchor signal is a [keybinding signal](class.SignalAction.html) which gets emitted when the user initiates setting the "anchor" mark. The "anchor" mark gets placed at the same position as the "insert" mark. This signal has no default bindings. Gets emitted to toggle the `cursor-visible` property. The ::toggle-cursor-visible signal is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>F7</kbd>. Gets emitted to toggle the overwrite mode of the text view. The ::toggle-overwrite signal is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Insert</kbd>. The object class structure needs to be the first The class handler for the `GtkTextView::move-cursor` keybinding signal. The class handler for the `GtkTextView::set-anchor` keybinding signal. The class handler for the `GtkTextView::insert-at-cursor` keybinding signal. The class handler for the `GtkTextView::delete-from-cursor` keybinding signal. The class handler for the `GtkTextView::backspace` keybinding signal. The class handler for the `GtkTextView::cut-clipboard` keybinding signal The class handler for the `GtkTextView::copy-clipboard` keybinding signal. The class handler for the `GtkTextView::paste-clipboard` keybinding signal. The class handler for the `GtkTextView::toggle-overwrite` keybinding signal. The create_buffer vfunc is called to create a `GtkTextBuffer` for the text view. The default implementation is to just call gtk_text_buffer_new(). The snapshot_layer vfunc is called before and after the text view is drawing its own text. Applications can override this vfunc in a subclass to draw customized content underneath or above the text. In the %GTK_TEXT_VIEW_LAYER_BELOW_TEXT and %GTK_TEXT_VIEW_LAYER_ABOVE_TEXT layers the drawing is done in the buffer coordinate space. The class handler for the `GtkTextView::extend-selection` signal. The class handler for the `GtkTextView::insert-emoji` signal. Used to reference the layers of `GtkTextView` for the purpose of customized drawing with the ::snapshot_layer vfunc. The layer rendered below the text (but above the background). The layer rendered above the text. Used to reference the parts of `GtkTextView`. Window that floats over scrolling areas. Scrollable text window. Left side border window. Right side border window. Top border window. Bottom border window. Callback type for adding a function to update animations. See [method@Gtk.Widget.add_tick_callback]. `G_SOURCE_CONTINUE` if the tick callback should continue to be called, `G_SOURCE_REMOVE` if it should be removed the widget the frame clock for the widget user data passed to [method@Gtk.Widget.add_tick_callback]. Shows a button which remains “pressed-in” when clicked. <picture> <source srcset="toggle-button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Example GtkToggleButtons" src="toggle-button.png"> </picture> Clicking again will cause the toggle button to return to its normal state. A toggle button is created by calling either [ctor@Gtk.ToggleButton.new] or [ctor@Gtk.ToggleButton.new_with_label]. If using the former, it is advisable to pack a widget, (such as a `GtkLabel` and/or a `GtkImage`), into the toggle button’s container. (See [class@Gtk.Button] for more information). The state of a `GtkToggleButton` can be set specifically using [method@Gtk.ToggleButton.set_active], and retrieved using [method@Gtk.ToggleButton.get_active]. ## Grouping Toggle buttons can be grouped together, to form mutually exclusive groups - only one of the buttons can be toggled at a time, and toggling another one will switch the currently toggled one off. To add a `GtkToggleButton` to a group, use [method@Gtk.ToggleButton.set_group]. ## CSS nodes `GtkToggleButton` has a single CSS node with name button. To differentiate it from a plain `GtkButton`, it gets the `.toggle` style class. ## Accessibility `GtkToggleButton` uses the [enum@Gtk.AccessibleRole.toggle_button] role. ## Creating two `GtkToggleButton` widgets. ```c static void output_state (GtkToggleButton *source, gpointer user_data) { g_print ("Toggle button "%s" is active: %s", gtk_button_get_label (GTK_BUTTON (source)), gtk_toggle_button_get_active (source) ? "Yes" : "No"); } static void make_toggles (void) { GtkWidget *window, *toggle1, *toggle2; GtkWidget *box; const char *text; window = gtk_window_new (); box = gtk_box_new (GTK_ORIENTATION_VERTICAL, 12); text = "Hi, I’m toggle button one"; toggle1 = gtk_toggle_button_new_with_label (text); g_signal_connect (toggle1, "toggled", G_CALLBACK (output_state), NULL); gtk_box_append (GTK_BOX (box), toggle1); text = "Hi, I’m toggle button two"; toggle2 = gtk_toggle_button_new_with_label (text); g_signal_connect (toggle2, "toggled", G_CALLBACK (output_state), NULL); gtk_box_append (GTK_BOX (box), toggle2); gtk_window_set_child (GTK_WINDOW (window), box); gtk_window_present (GTK_WINDOW (window)); } ``` Creates a new toggle button. A widget should be packed into the button, as in [ctor@Gtk.Button.new]. a new toggle button. Creates a new toggle button with a text label. a new toggle button. a string containing the message to be placed in the toggle button. Creates a new `GtkToggleButton` containing a label. The label will be created using [ctor@Gtk.Label.new_with_mnemonic], so underscores in @label indicate the mnemonic for the button. a new `GtkToggleButton` the text of the button, with an underscore in front of the mnemonic character Emits the ::toggled signal on the `GtkToggleButton`. There is no good reason for an application ever to call this function. a `GtkToggleButton`. Queries a `GtkToggleButton` and returns its current state. Returns %TRUE if the toggle button is pressed in and %FALSE if it is raised. whether the button is pressed a `GtkToggleButton`. Sets the status of the toggle button. Set to %TRUE if you want the `GtkToggleButton` to be “pressed in”, and %FALSE to raise it. If the status of the button changes, this action causes the [signal@Gtk.ToggleButton::toggled] signal to be emitted. a `GtkToggleButton`. %TRUE or %FALSE. Adds @self to the group of @group. In a group of multiple toggle buttons, only one button can be active at a time. Setting up groups in a cycle leads to undefined behavior. Note that the same effect can be achieved via the [iface@Gtk.Actionable] API, by using the same action with parameter type and state type 's' for all buttons in the group, and giving each button its own target value. a `GtkToggleButton` another `GtkToggleButton` to form a group with Emits the ::toggled signal on the `GtkToggleButton`. There is no good reason for an application ever to call this function. a `GtkToggleButton`. If the toggle button should be pressed in. The toggle button whose group this widget belongs to. Emitted whenever the `GtkToggleButton`'s state is changed. a `GtkToggleButton`. Represents a widget tooltip. Basic tooltips can be realized simply by using [method@Gtk.Widget.set_tooltip_text] or [method@Gtk.Widget.set_tooltip_markup] without any explicit tooltip object. When you need a tooltip with a little more fancy contents, like adding an image, or you want the tooltip to have different contents per `GtkTreeView` row or cell, you will have to do a little more work: - Set the [property@Gtk.Widget:has-tooltip] property to %TRUE. This will make GTK monitor the widget for motion and related events which are needed to determine when and where to show a tooltip. - Connect to the [signal@Gtk.Widget::query-tooltip] signal. This signal will be emitted when a tooltip is supposed to be shown. One of the arguments passed to the signal handler is a `GtkTooltip` object. This is the object that we are about to display as a tooltip, and can be manipulated in your callback using functions like [method@Gtk.Tooltip.set_icon]. There are functions for setting the tooltip’s markup, setting an image from a named icon, or even putting in a custom widget. - Return %TRUE from your ::query-tooltip handler. This causes the tooltip to be show. If you return %FALSE, it will not be shown. Replaces the widget packed into the tooltip with @custom_widget. @custom_widget does not get destroyed when the tooltip goes away. By default a box with a `GtkImage` and `GtkLabel` is embedded in the tooltip, which can be configured using gtk_tooltip_set_markup() and gtk_tooltip_set_icon(). a `GtkTooltip` a `GtkWidget`, or %NULL to unset the old custom widget. Sets the icon of the tooltip (which is in front of the text) to be @paintable. If @paintable is %NULL, the image will be hidden. a `GtkTooltip` a `GdkPaintable` Sets the icon of the tooltip (which is in front of the text) to be the icon indicated by @gicon with the size indicated by @size. If @gicon is %NULL, the image will be hidden. a `GtkTooltip` a `GIcon` representing the icon Sets the icon of the tooltip (which is in front of the text) to be the icon indicated by @icon_name with the size indicated by @size. If @icon_name is %NULL, the image will be hidden. a `GtkTooltip` an icon name Sets the text of the tooltip to be @markup. The string must be marked up with Pango markup. If @markup is %NULL, the label will be hidden. a `GtkTooltip` a string with Pango markup or %NLL Sets the text of the tooltip to be @text. If @text is %NULL, the label will be hidden. See also [method@Gtk.Tooltip.set_markup]. a `GtkTooltip` a text string Sets the area of the widget, where the contents of this tooltip apply, to be @rect (in widget coordinates). This is especially useful for properly setting tooltips on `GtkTreeView` rows and cells, `GtkIconViews`, etc. For setting tooltips on `GtkTreeView`, please refer to the convenience functions for this: gtk_tree_view_set_tooltip_row() and gtk_tree_view_set_tooltip_cell(). a `GtkTooltip` a `GdkRectangle` A function to set the properties of a cell instead of just using the straight mapping between the cell and the model. This function is useful for customizing the cell renderer. For example, a function might get an* integer from the @tree_model, and render it to the “text” attribute of “cell” by converting it to its written equivalent. See also: gtk_tree_view_column_set_cell_data_func() There is no replacement A `GtkTreeViewColumn` The `GtkCellRenderer` that is being rendered by @tree_column The `GtkTreeModel` being rendered A `GtkTreeIter` of the current row rendered user data Interface for Drag-and-Drop destinations in `GtkTreeView`. List views use widgets to display their contents. You can use [class@Gtk.DropTarget] to implement a drop destination Asks the `GtkTreeDragDest` to insert a row before the path @dest, deriving the contents of the row from @value. If @dest is outside the tree so that inserting before it is impossible, %FALSE will be returned. Also, %FALSE may be returned if the new row is not created for some model-specific reason. Should robustly handle a @dest no longer found in the model! Use list models instead whether a new row was created before position @dest a `GtkTreeDragDest` row to drop in front of data to drop Determines whether a drop is possible before the given @dest_path, at the same depth as @dest_path. i.e., can we drop the data in @value at that location. @dest_path does not have to exist; the return value will almost certainly be %FALSE if the parent of @dest_path doesn’t exist, though. Use list models instead %TRUE if a drop is possible before @dest_path a `GtkTreeDragDest` destination row the data being dropped Asks the `GtkTreeDragDest` to insert a row before the path @dest, deriving the contents of the row from @value. If @dest is outside the tree so that inserting before it is impossible, %FALSE will be returned. Also, %FALSE may be returned if the new row is not created for some model-specific reason. Should robustly handle a @dest no longer found in the model! Use list models instead whether a new row was created before position @dest a `GtkTreeDragDest` row to drop in front of data to drop Determines whether a drop is possible before the given @dest_path, at the same depth as @dest_path. i.e., can we drop the data in @value at that location. @dest_path does not have to exist; the return value will almost certainly be %FALSE if the parent of @dest_path doesn’t exist, though. Use list models instead %TRUE if a drop is possible before @dest_path a `GtkTreeDragDest` destination row the data being dropped Asks the `GtkTreeDragDest` to insert a row before the path dest, deriving the contents of the row from selection_data. whether a new row was created before position @dest a `GtkTreeDragDest` row to drop in front of data to drop Determines whether a drop is possible before the given dest_path, at the same depth as dest_path. %TRUE if a drop is possible before @dest_path a `GtkTreeDragDest` destination row the data being dropped Interface for Drag-and-Drop destinations in `GtkTreeView`. List views use widgets to display their contents. You can use [class@Gtk.DragSource] to implement a drag source Asks the `GtkTreeDragSource` to delete the row at @path, because it was moved somewhere else via drag-and-drop. Returns %FALSE if the deletion fails because @path no longer exists, or for some model-specific reason. Should robustly handle a @path no longer found in the model! Use list models instead %TRUE if the row was successfully deleted a `GtkTreeDragSource` row that was being dragged Asks the `GtkTreeDragSource` to return a `GdkContentProvider` representing the row at @path. Should robustly handle a @path no longer found in the model! Use list models instead a `GdkContentProvider` for the given @path a `GtkTreeDragSource` row that was dragged Asks the `GtkTreeDragSource` whether a particular row can be used as the source of a DND operation. If the source doesn’t implement this interface, the row is assumed draggable. Use list models instead %TRUE if the row can be dragged a `GtkTreeDragSource` row on which user is initiating a drag Asks the `GtkTreeDragSource` to delete the row at @path, because it was moved somewhere else via drag-and-drop. Returns %FALSE if the deletion fails because @path no longer exists, or for some model-specific reason. Should robustly handle a @path no longer found in the model! Use list models instead %TRUE if the row was successfully deleted a `GtkTreeDragSource` row that was being dragged Asks the `GtkTreeDragSource` to return a `GdkContentProvider` representing the row at @path. Should robustly handle a @path no longer found in the model! Use list models instead a `GdkContentProvider` for the given @path a `GtkTreeDragSource` row that was dragged Asks the `GtkTreeDragSource` whether a particular row can be used as the source of a DND operation. If the source doesn’t implement this interface, the row is assumed draggable. Use list models instead %TRUE if the row can be dragged a `GtkTreeDragSource` row on which user is initiating a drag Asks the `GtkTreeDragSource` whether a particular row can be used as the source of a DND operation. %TRUE if the row can be dragged a `GtkTreeDragSource` row on which user is initiating a drag Asks the `GtkTreeDragSource` to fill in selection_data with a representation of the row at path. a `GdkContentProvider` for the given @path a `GtkTreeDragSource` row that was dragged Asks the `GtkTreeDragSource` to delete the row at path, because it was moved somewhere else via drag-and-drop. %TRUE if the row was successfully deleted a `GtkTreeDragSource` row that was being dragged Provides an expander for a tree-like list. It is typically placed as a bottommost child into a `GtkListView` to allow users to expand and collapse children in a list with a [class@Gtk.TreeListModel]. `GtkTreeExpander` provides the common UI elements, gestures and keybindings for this purpose. On top of this, the "listitem.expand", "listitem.collapse" and "listitem.toggle-expand" actions are provided to allow adding custom UI for managing expanded state. It is important to mention that you want to set the [property@Gtk.ListItem:focusable] property to FALSE when using this widget, as you want the keyboard focus to be in the treexpander, and not inside the list to make use of the keybindings. The `GtkTreeListModel` must be set to not be passthrough. Then it will provide [class@Gtk.TreeListRow] items which can be set via [method@Gtk.TreeExpander.set_list_row] on the expander. The expander will then watch that row item automatically. [method@Gtk.TreeExpander.set_child] sets the widget that displays the actual row contents. `GtkTreeExpander` can be modified with properties such as [property@Gtk.TreeExpander:indent-for-icon], [property@Gtk.TreeExpander:indent-for-depth], and [property@Gtk.TreeExpander:hide-expander] to achieve a different appearance. This can even be done to influence individual rows, for example by binding the [property@Gtk.TreeExpander:hide-expander] property to the item count of the model of the treelistrow, to hide the expander for rows without children, even if the row is expandable. ## Shortcuts and Gestures `GtkTreeExpander` supports the following keyboard shortcuts: - <kbd>+</kbd> or <kbd>*</kbd> expands the expander. - <kbd>-</kbd> or <kbd>/</kbd> collapses the expander. - Left and right arrow keys, when combined with <kbd>Shift</kbd> or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>, will expand or collapse, depending on the locale's text direction. - <kbd>Ctrl</kbd>+<kbd>␣</kbd> toggles the expander state. The row can also expand on drag gestures. ## Actions `GtkTreeExpander` defines a set of built-in actions: - `listitem.expand` expands the expander if it can be expanded. - `listitem.collapse` collapses the expander. - `listitem.toggle-expand` tries to expand the expander if it was collapsed or collapses it if it was expanded. ## CSS nodes ``` treeexpander ├── [indent]* ├── [expander] ╰── <child> ``` `GtkTreeExpander` has zero or one CSS nodes with the name "expander" that should display the expander icon. The node will be `:checked` when it is expanded. If the node is not expandable, an "indent" node will be displayed instead. For every level of depth, another "indent" node is prepended. ## Accessibility Until GTK 4.10, `GtkTreeExpander` used the [enum@Gtk.AccessibleRole.group] role. Since GTK 4.12, `GtkTreeExpander` uses the [enum@Gtk.AccessibleRole.button] role. Toggling it will change the `GTK_ACCESSIBLE_STATE_EXPANDED` state. Creates a new `GtkTreeExpander` a new `GtkTreeExpander` Gets the child widget displayed by @self. The child displayed by @self a `GtkTreeExpander` Gets whether the TreeExpander should be hidden in a GtkTreeListRow. TRUE if the expander icon should be hidden. Otherwise FALSE. a `GtkTreeExpander` TreeExpander indents each level of depth with an additional indent. TRUE if the child should be indented . Otherwise FALSE. a `GtkTreeExpander` TreeExpander indents the child by the width of an expander-icon if it is not expandable. TRUE if the child should be indented when not expandable. Otherwise FALSE. a `GtkTreeExpander` Forwards the item set on the `GtkTreeListRow` that @self is managing. This call is essentially equivalent to calling: ```c gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); ``` The item of the row a `GtkTreeExpander` Gets the list row managed by @self. The list row displayed by @self a `GtkTreeExpander` Sets the content widget to display. a `GtkTreeExpander` a `GtkWidget` Sets whether the expander icon should be visible in a GtkTreeListRow. a `GtkTreeExpander` widget TRUE if the expander should be hidden. Otherwise FALSE. Sets if the TreeExpander should indent the child according to its depth. a `GtkTreeExpander` widget TRUE if the child should be indented. Otherwise FALSE. Sets if the TreeExpander should indent the child by the width of an expander-icon when it is not expandable. a `GtkTreeExpander` widget TRUE if the child should be indented without expander. Otherwise FALSE. Sets the tree list row that this expander should manage. a `GtkTreeExpander` widget a `GtkTreeListRow` The child widget with the actual contents. Whether the expander icon should be hidden in a GtkTreeListRow. Note that this property simply hides the icon. The actions and keybinding (i.e. collapse and expand) are not affected by this property. A common use for this property would be to bind to the number of children in a GtkTreeListRow's model in order to hide the expander when a row has no children. TreeExpander indents the child according to its depth. TreeExpander indents the child by the width of an expander-icon if it is not expandable. The item held by this expander's row. The list row to track for expander state. The `GtkTreeIter` is the primary structure for accessing a `GtkTreeModel`. Models are expected to put a unique integer in the @stamp member, and put model-specific data in the three @user_data members. a unique stamp to catch invalid iterators model-specific data model-specific data model-specific data Creates a dynamically allocated tree iterator as a copy of @iter. This function is not intended for use in applications, because you can just copy the structs by value (`GtkTreeIter new_iter = iter;`). You must free this iter with gtk_tree_iter_free(). a newly-allocated copy of @iter a `GtkTreeIter` Frees an iterator that has been allocated by gtk_tree_iter_copy(). This function is mainly used for language bindings. a dynamically allocated tree iterator A GtkTreeIterCompareFunc should return a negative integer, zero, or a positive integer if @a sorts before @b, @a sorts with @b, or @a sorts after @b respectively. If two iters compare as equal, their order in the sorted model is undefined. In order to ensure that the `GtkTreeSortable` behaves as expected, the GtkTreeIterCompareFunc must define a partial order on the model, i.e. it must be reflexive, antisymmetric and transitive. For example, if @model is a product catalogue, then a compare function for the “price” column could be one which returns `price_of(@a) - price_of(@b)`. There is no replacement a negative integer, zero or a positive integer depending on whether @a sorts before, with or after @b The `GtkTreeModel` the comparison is within A `GtkTreeIter` in @model Another `GtkTreeIter` in @model Data passed when the compare func is assigned e.g. by gtk_tree_sortable_set_sort_func() A list model that can create child models on demand. Creates a new empty `GtkTreeListModel` displaying @root with all rows collapsed. a newly created `GtkTreeListModel`. The `GListModel` to use as root %TRUE to pass through items from the models %TRUE to set the autoexpand property and expand the @root model function to call to create the `GListModel` for the children of an item Data to pass to @create_func Function to call to free @user_data Gets whether the model is set to automatically expand new rows that get added. This can be either rows added by changes to the underlying models or via [method@Gtk.TreeListRow.set_expanded]. %TRUE if the model is set to autoexpand a `GtkTreeListModel` Gets the row item corresponding to the child at index @position for @self's root model. If @position is greater than the number of children in the root model, %NULL is returned. Do not confuse this function with [method@Gtk.TreeListModel.get_row]. the child in @position a `GtkTreeListModel` position of the child to get Gets the root model that @self was created with. the root model a `GtkTreeListModel` Gets whether the model is passing through original row items. If this function returns %FALSE, the `GListModel` functions for @self return custom `GtkTreeListRow` objects. You need to call [method@Gtk.TreeListRow.get_item] on these objects to get the original item. If %TRUE, the values of the child models are passed through in their original state. You then need to call [method@Gtk.TreeListModel.get_row] to get the custom `GtkTreeListRow`s. %TRUE if the model is passing through original row items a `GtkTreeListModel` Gets the row object for the given row. If @position is greater than the number of items in @self, %NULL is returned. The row object can be used to expand and collapse rows as well as to inspect its position in the tree. See its documentation for details. This row object is persistent and will refer to the current item as long as the row is present in @self, independent of other rows being added or removed. If @self is set to not be passthrough, this function is equivalent to calling g_list_model_get_item(). Do not confuse this function with [method@Gtk.TreeListModel.get_child_row]. The row item a `GtkTreeListModel` the position of the row to fetch Sets whether the model should autoexpand. If set to %TRUE, the model will recursively expand all rows that get added to the model. This can be either rows added by changes to the underlying models or via [method@Gtk.TreeListRow.set_expanded]. a `GtkTreeListModel` %TRUE to make the model autoexpand its rows If all rows should be expanded by default. The type of items. See [method@Gio.ListModel.get_item_type]. The root model displayed. The number of items. See [method@Gio.ListModel.get_n_items]. Gets whether the model is in passthrough mode. If %FALSE, the `GListModel` functions for this object return custom [class@Gtk.TreeListRow] objects. If %TRUE, the values of the child models are pass through unmodified. Prototype of the function called to create new child models when gtk_tree_list_row_set_expanded() is called. This function can return %NULL to indicate that @item is guaranteed to be a leaf node and will never have children. If it does not have children but may get children later, it should return an empty model that is filled once children arrive. The model tracking the children of @item or %NULL if @item can never have children The item that is being expanded User data passed when registering the function The type of item used by `GtkTreeListModel`. It allows navigating the model as a tree and modify the state of rows. `GtkTreeListRow` instances are created by a `GtkTreeListModel` only when the [property@Gtk.TreeListModel:passthrough] property is not set. There are various support objects that can make use of `GtkTreeListRow` objects, such as the [class@Gtk.TreeExpander] widget that allows displaying an icon to expand or collapse a row or [class@Gtk.TreeListRowSorter] that makes it possible to sort trees properly. If @self is not expanded or @position is greater than the number of children, %NULL is returned. the child in @position a `GtkTreeListRow` position of the child to get If the row is expanded, gets the model holding the children of @self. This model is the model created by the [callback@Gtk.TreeListModelCreateModelFunc] and contains the original items, no matter what value [property@Gtk.TreeListModel:passthrough] is set to. The model containing the children a `GtkTreeListRow` Gets the depth of this row. Rows that correspond to items in the root model have a depth of zero, rows corresponding to items of models of direct children of the root model have a depth of 1 and so on. The depth of a row never changes until the row is removed from its model at which point it will forever return 0. The depth of this row a `GtkTreeListRow` Gets if a row is currently expanded. %TRUE if the row is expanded a `GtkTreeListRow` Gets the item corresponding to this row, The item of this row. This function is only marked as nullable for backwards compatibility reasons. a `GtkTreeListRow` Gets the row representing the parent for @self. That is the row that would need to be collapsed to make this row disappear. If @self is a row corresponding to the root model, %NULL is returned. The value returned by this function never changes until the row is removed from its model at which point it will forever return %NULL. The parent of @self a `GtkTreeListRow` Returns the position in the `GtkTreeListModel` that @self occupies at the moment. The position in the model a `GtkTreeListRow` Checks if a row can be expanded. This does not mean that the row is actually expanded, this can be checked with [method@Gtk.TreeListRow.get_expanded]. If a row is expandable never changes until the row is removed from its model at which point it will forever return %FALSE. %TRUE if the row is expandable a `GtkTreeListRow` Expands or collapses a row. If a row is expanded, the model of calling the [callback@Gtk.TreeListModelCreateModelFunc] for the row's item will be inserted after this row. If a row is collapsed, those items will be removed from the model. If the row is not expandable, this function does nothing. a `GtkTreeListRow` %TRUE if the row should be expanded The model holding the row's children. The depth in the tree of this row. If this row can ever be expanded. If this row is currently expanded. The item held in this row. Applies a gives sorter to the levels in a tree. Here is an example for setting up a column view with a tree model and a `GtkTreeListSorter`: ```c column_sorter = gtk_column_view_get_sorter (view); sorter = gtk_tree_list_row_sorter_new (g_object_ref (column_sorter)); sort_model = gtk_sort_list_model_new (tree_model, sorter); selection = gtk_single_selection_new (sort_model); gtk_column_view_set_model (view, G_LIST_MODEL (selection)); ``` Create a special-purpose sorter that applies the sorting of @sorter to the levels of a `GtkTreeListModel`. Note that this sorter relies on [property@Gtk.TreeListModel:passthrough] being %FALSE as it can only sort [class@Gtk.TreeListRow]s. a new `GtkTreeListRowSorter` a `GtkSorter` Returns the sorter used by @self. the sorter used a `GtkTreeListRowSorter` Sets the sorter to use for items with the same parent. This sorter will be passed the [property@Gtk.TreeListRow:item] of the tree list rows passed to @self. a `GtkTreeListRowSorter` The sorter to use The underlying sorter The tree interface used by GtkTreeView The `GtkTreeModel` interface defines a generic tree interface for use by the `GtkTreeView` widget. It is an abstract interface, and is designed to be usable with any appropriate data structure. The programmer just has to implement this interface on their own data type for it to be viewable by a `GtkTreeView` widget. The model is represented as a hierarchical tree of strongly-typed, columned data. In other words, the model can be seen as a tree where every node has different values depending on which column is being queried. The type of data found in a column is determined by using the GType system (ie. %G_TYPE_INT, %GTK_TYPE_BUTTON, %G_TYPE_POINTER, etc). The types are homogeneous per column across all nodes. It is important to note that this interface only provides a way of examining a model and observing changes. The implementation of each individual model decides how and if changes are made. In order to make life simpler for programmers who do not need to write their own specialized model, two generic models are provided — the `GtkTreeStore` and the `GtkListStore`. To use these, the developer simply pushes data into these models as necessary. These models provide the data structure as well as all appropriate tree interfaces. As a result, implementing drag and drop, sorting, and storing data is trivial. For the vast majority of trees and lists, these two models are sufficient. Models are accessed on a node/column level of granularity. One can query for the value of a model at a certain node and a certain column on that node. There are two structures used to reference a particular node in a model. They are the [struct@Gtk.TreePath] and the [struct@Gtk.TreeIter] (“iter” is short for iterator). Most of the interface consists of operations on a [struct@Gtk.TreeIter]. A path is essentially a potential node. It is a location on a model that may or may not actually correspond to a node on a specific model. A [struct@Gtk.TreePath] can be converted into either an array of unsigned integers or a string. The string form is a list of numbers separated by a colon. Each number refers to the offset at that level. Thus, the path `0` refers to the root node and the path `2:4` refers to the fifth child of the third node. By contrast, a [struct@Gtk.TreeIter] is a reference to a specific node on a specific model. It is a generic struct with an integer and three generic pointers. These are filled in by the model in a model-specific way. One can convert a path to an iterator by calling gtk_tree_model_get_iter(). These iterators are the primary way of accessing a model and are similar to the iterators used by `GtkTextBuffer`. They are generally statically allocated on the stack and only used for a short time. The model interface defines a set of operations using them for navigating the model. It is expected that models fill in the iterator with private data. For example, the `GtkListStore` model, which is internally a simple linked list, stores a list node in one of the pointers. The `GtkTreeModel`Sort stores an array and an offset in two of the pointers. Additionally, there is an integer field. This field is generally filled with a unique stamp per model. This stamp is for catching errors resulting from using invalid iterators with a model. The lifecycle of an iterator can be a little confusing at first. Iterators are expected to always be valid for as long as the model is unchanged (and doesn’t emit a signal). The model is considered to own all outstanding iterators and nothing needs to be done to free them from the user’s point of view. Additionally, some models guarantee that an iterator is valid for as long as the node it refers to is valid (most notably the `GtkTreeStore` and `GtkListStore`). Although generally uninteresting, as one always has to allow for the case where iterators do not persist beyond a signal, some very important performance enhancements were made in the sort model. As a result, the %GTK_TREE_MODEL_ITERS_PERSIST flag was added to indicate this behavior. To help show some common operation of a model, some examples are provided. The first example shows three ways of getting the iter at the location `3:2:5`. While the first method shown is easier, the second is much more common, as you often get paths from callbacks. ## Acquiring a `GtkTreeIter` ```c // Three ways of getting the iter pointing to the location GtkTreePath *path; GtkTreeIter iter; GtkTreeIter parent_iter; // get the iterator from a string gtk_tree_model_get_iter_from_string (model, &iter, "3:2:5"); // get the iterator from a path path = gtk_tree_path_new_from_string ("3:2:5"); gtk_tree_model_get_iter (model, &iter, path); gtk_tree_path_free (path); // walk the tree to find the iterator gtk_tree_model_iter_nth_child (model, &iter, NULL, 3); parent_iter = iter; gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 2); parent_iter = iter; gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 5); ``` This second example shows a quick way of iterating through a list and getting a string and an integer from each row. The populate_model() function used below is not shown, as it is specific to the `GtkListStore`. For information on how to write such a function, see the `GtkListStore` documentation. ## Reading data from a `GtkTreeModel` ```c enum { STRING_COLUMN, INT_COLUMN, N_COLUMNS }; ... GtkTreeModel *list_store; GtkTreeIter iter; gboolean valid; int row_count = 0; // make a new list_store list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT); // Fill the list store with data populate_model (list_store); // Get the first iter in the list, check it is valid and walk // through the list, reading each row. valid = gtk_tree_model_get_iter_first (list_store, &iter); while (valid) { char *str_data; int int_data; // Make sure you terminate calls to gtk_tree_model_get() with a “-1” value gtk_tree_model_get (list_store, &iter, STRING_COLUMN, &str_data, INT_COLUMN, &int_data, -1); // Do something with the data g_print ("Row %d: (%s,%d)\n", row_count, str_data, int_data); g_free (str_data); valid = gtk_tree_model_iter_next (list_store, &iter); row_count++; } ``` The `GtkTreeModel` interface contains two methods for reference counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node(). These two methods are optional to implement. The reference counting is meant as a way for views to let models know when nodes are being displayed. `GtkTreeView` will take a reference on a node when it is visible, which means the node is either in the toplevel or expanded. Being displayed does not mean that the node is currently directly visible to the user in the viewport. Based on this reference counting scheme a caching model, for example, can decide whether or not to cache a node based on the reference count. A file-system based model would not want to keep the entire file hierarchy in memory, but just the folders that are currently expanded in every current view. When working with reference counting, the following rules must be taken into account: - Never take a reference on a node without owning a reference on its parent. This means that all parent nodes of a referenced node must be referenced as well. - Outstanding references on a deleted node are not released. This is not possible because the node has already been deleted by the time the row-deleted signal is received. - Models are not obligated to emit a signal on rows of which none of its siblings are referenced. To phrase this differently, signals are only required for levels in which nodes are referenced. For the root level however, signals must be emitted at all times (however the root level is always referenced when any view is attached). Use [iface@Gio.ListModel] instead Returns the type of the column. the type of the column a `GtkTreeModel` the column index Returns a set of flags supported by this interface. The flags are a bitwise combination of `GtkTreeModel`Flags. The flags supported should not change during the lifetime of the @tree_model. the flags supported by this interface a `GtkTreeModel` Sets @iter to a valid iterator pointing to @path. If @path does not exist, @iter is set to an invalid iterator and %FALSE is returned. %TRUE, if @iter was set a `GtkTreeModel` the uninitialized `GtkTreeIter` the `GtkTreePath` Returns the number of columns supported by @tree_model. the number of columns a `GtkTreeModel` Returns a newly-created `GtkTreePath` referenced by @iter. This path should be freed with gtk_tree_path_free(). a newly-created `GtkTreePath` a `GtkTreeModel` the `GtkTreeIter` Initializes and sets @value to that at @column. When done with @value, g_value_unset() needs to be called to free any allocated memory. a `GtkTreeModel` the `GtkTreeIter` the column to lookup the value at an empty `GValue` to set Sets @iter to point to the first child of @parent. If @parent has no children, %FALSE is returned and @iter is set to be invalid. @parent will remain a valid node after this function has been called. If @parent is %NULL returns the first node, equivalent to `gtk_tree_model_get_iter_first (tree_model, iter);` %TRUE, if @iter has been set to the first child a `GtkTreeModel` the new `GtkTreeIter` to be set to the child the `GtkTreeIter` Returns %TRUE if @iter has children, %FALSE otherwise. %TRUE if @iter has children a `GtkTreeModel` the `GtkTreeIter` to test for children Returns the number of children that @iter has. As a special case, if @iter is %NULL, then the number of toplevel nodes is returned. the number of children of @iter a `GtkTreeModel` the `GtkTreeIter` Sets @iter to point to the node following it at the current level. If there is no next @iter, %FALSE is returned and @iter is set to be invalid. %TRUE if @iter has been changed to the next node a `GtkTreeModel` the `GtkTreeIter` Sets @iter to be the child of @parent, using the given index. The first index is 0. If @n is too big, or @parent has no children, @iter is set to an invalid iterator and %FALSE is returned. @parent will remain a valid node after this function has been called. As a special case, if @parent is %NULL, then the @n-th root node is set. %TRUE, if @parent has an @n-th child a `GtkTreeModel` the `GtkTreeIter` to set to the nth child the `GtkTreeIter` to get the child from the index of the desired child Sets @iter to be the parent of @child. If @child is at the toplevel, and doesn’t have a parent, then @iter is set to an invalid iterator and %FALSE is returned. @child will remain a valid node after this function has been called. @iter will be initialized before the lookup is performed, so @child and @iter cannot point to the same memory location. %TRUE, if @iter is set to the parent of @child a `GtkTreeModel` the new `GtkTreeIter` to set to the parent the `GtkTreeIter` Sets @iter to point to the previous node at the current level. If there is no previous @iter, %FALSE is returned and @iter is set to be invalid. %TRUE if @iter has been changed to the previous node a `GtkTreeModel` the `GtkTreeIter` Lets the tree ref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. This function is primarily meant as a way for views to let caching models know when nodes are being displayed (and hence, whether or not to cache that node). Being displayed means a node is in an expanded branch, regardless of whether the node is currently visible in the viewport. For example, a file-system based model would not want to keep the entire file-hierarchy in memory, just the sections that are currently being displayed by every current view. A model should be expected to be able to get an iter independent of its reffed state. a `GtkTreeModel` the `GtkTreeIter` Emits the ::row-changed signal on @tree_model. See [signal@Gtk.TreeModel::row-changed]. a `GtkTreeModel` a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row Emits the ::row-deleted signal on @tree_model. See [signal@Gtk.TreeModel::row-deleted]. This should be called by models after a row has been removed. The location pointed to by @path should be the location that the row previously was at. It may not be a valid location anymore. Nodes that are deleted are not unreffed, this means that any outstanding references on the deleted node should not be released. a `GtkTreeModel` a `GtkTreePath` pointing to the previous location of the deleted row Emits the ::row-has-child-toggled signal on @tree_model. See [signal@Gtk.TreeModel::row-has-child-toggled]. This should be called by models after the child state of a node changes. a `GtkTreeModel` a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row Emits the ::row-inserted signal on @tree_model. See [signal@Gtk.TreeModel::row-inserted]. a `GtkTreeModel` a `GtkTreePath` pointing to the inserted row a valid `GtkTreeIter` pointing to the inserted row Emits the ::rows-reordered signal on @tree_model. See [signal@Gtk.TreeModel::rows-reordered]. This should be called by models when their rows have been reordered. a `GtkTreeModel` a `GtkTreePath` pointing to the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` Lets the tree unref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. For more information on what this means, see gtk_tree_model_ref_node(). Please note that nodes that are deleted are not unreffed. a `GtkTreeModel` the `GtkTreeIter` Creates a new `GtkTreeModel`, with @child_model as the child_model and @root as the virtual root. A new `GtkTreeModel`. A `GtkTreeModel`. A `GtkTreePath` Calls @func on each node in model in a depth-first fashion. If @func returns %TRUE, then the tree ceases to be walked, and gtk_tree_model_foreach() returns. a `GtkTreeModel` a function to be called on each row user data to passed to @func Gets the value of one or more cells in the row referenced by @iter. The variable argument list should contain integer column numbers, each column number followed by a place to store the value being retrieved. The list is terminated by a -1. For example, to get a value from column 0 with type %G_TYPE_STRING, you would write: `gtk_tree_model_get (model, iter, 0, &place_string_here, -1)`, where `place_string_here` is a #gchararray to be filled with the string. Returned values with type %G_TYPE_OBJECT have to be unreferenced, values with type %G_TYPE_STRING or %G_TYPE_BOXED have to be freed. Other values are passed by value. a `GtkTreeModel` a row in @tree_model pairs of column number and value return locations, terminated by -1 Returns the type of the column. the type of the column a `GtkTreeModel` the column index Returns a set of flags supported by this interface. The flags are a bitwise combination of `GtkTreeModel`Flags. The flags supported should not change during the lifetime of the @tree_model. the flags supported by this interface a `GtkTreeModel` Sets @iter to a valid iterator pointing to @path. If @path does not exist, @iter is set to an invalid iterator and %FALSE is returned. %TRUE, if @iter was set a `GtkTreeModel` the uninitialized `GtkTreeIter` the `GtkTreePath` Initializes @iter with the first iterator in the tree (the one at the path "0"). Returns %FALSE if the tree is empty, %TRUE otherwise. %TRUE, if @iter was set a `GtkTreeModel` the uninitialized `GtkTreeIter` Sets @iter to a valid iterator pointing to @path_string, if it exists. Otherwise, @iter is left invalid and %FALSE is returned. %TRUE, if @iter was set a `GtkTreeModel` an uninitialized `GtkTreeIter` a string representation of a `GtkTreePath` Returns the number of columns supported by @tree_model. the number of columns a `GtkTreeModel` Returns a newly-created `GtkTreePath` referenced by @iter. This path should be freed with gtk_tree_path_free(). a newly-created `GtkTreePath` a `GtkTreeModel` the `GtkTreeIter` Generates a string representation of the iter. This string is a “:” separated list of numbers. For example, “4:10:0:3” would be an acceptable return value for this string. a newly-allocated string a `GtkTreeModel` a `GtkTreeIter` Gets the value of one or more cells in the row referenced by @iter. See [method@Gtk.TreeModel.get], this version takes a va_list for language bindings to use. a `GtkTreeModel` a row in @tree_model va_list of column/return location pairs Initializes and sets @value to that at @column. When done with @value, g_value_unset() needs to be called to free any allocated memory. a `GtkTreeModel` the `GtkTreeIter` the column to lookup the value at an empty `GValue` to set Sets @iter to point to the first child of @parent. If @parent has no children, %FALSE is returned and @iter is set to be invalid. @parent will remain a valid node after this function has been called. If @parent is %NULL returns the first node, equivalent to `gtk_tree_model_get_iter_first (tree_model, iter);` %TRUE, if @iter has been set to the first child a `GtkTreeModel` the new `GtkTreeIter` to be set to the child the `GtkTreeIter` Returns %TRUE if @iter has children, %FALSE otherwise. %TRUE if @iter has children a `GtkTreeModel` the `GtkTreeIter` to test for children Returns the number of children that @iter has. As a special case, if @iter is %NULL, then the number of toplevel nodes is returned. the number of children of @iter a `GtkTreeModel` the `GtkTreeIter` Sets @iter to point to the node following it at the current level. If there is no next @iter, %FALSE is returned and @iter is set to be invalid. %TRUE if @iter has been changed to the next node a `GtkTreeModel` the `GtkTreeIter` Sets @iter to be the child of @parent, using the given index. The first index is 0. If @n is too big, or @parent has no children, @iter is set to an invalid iterator and %FALSE is returned. @parent will remain a valid node after this function has been called. As a special case, if @parent is %NULL, then the @n-th root node is set. %TRUE, if @parent has an @n-th child a `GtkTreeModel` the `GtkTreeIter` to set to the nth child the `GtkTreeIter` to get the child from the index of the desired child Sets @iter to be the parent of @child. If @child is at the toplevel, and doesn’t have a parent, then @iter is set to an invalid iterator and %FALSE is returned. @child will remain a valid node after this function has been called. @iter will be initialized before the lookup is performed, so @child and @iter cannot point to the same memory location. %TRUE, if @iter is set to the parent of @child a `GtkTreeModel` the new `GtkTreeIter` to set to the parent the `GtkTreeIter` Sets @iter to point to the previous node at the current level. If there is no previous @iter, %FALSE is returned and @iter is set to be invalid. %TRUE if @iter has been changed to the previous node a `GtkTreeModel` the `GtkTreeIter` Lets the tree ref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. This function is primarily meant as a way for views to let caching models know when nodes are being displayed (and hence, whether or not to cache that node). Being displayed means a node is in an expanded branch, regardless of whether the node is currently visible in the viewport. For example, a file-system based model would not want to keep the entire file-hierarchy in memory, just the sections that are currently being displayed by every current view. A model should be expected to be able to get an iter independent of its reffed state. a `GtkTreeModel` the `GtkTreeIter` Emits the ::row-changed signal on @tree_model. See [signal@Gtk.TreeModel::row-changed]. a `GtkTreeModel` a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row Emits the ::row-deleted signal on @tree_model. See [signal@Gtk.TreeModel::row-deleted]. This should be called by models after a row has been removed. The location pointed to by @path should be the location that the row previously was at. It may not be a valid location anymore. Nodes that are deleted are not unreffed, this means that any outstanding references on the deleted node should not be released. a `GtkTreeModel` a `GtkTreePath` pointing to the previous location of the deleted row Emits the ::row-has-child-toggled signal on @tree_model. See [signal@Gtk.TreeModel::row-has-child-toggled]. This should be called by models after the child state of a node changes. a `GtkTreeModel` a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row Emits the ::row-inserted signal on @tree_model. See [signal@Gtk.TreeModel::row-inserted]. a `GtkTreeModel` a `GtkTreePath` pointing to the inserted row a valid `GtkTreeIter` pointing to the inserted row Emits the ::rows-reordered signal on @tree_model. See [signal@Gtk.TreeModel::rows-reordered]. This should be called by models when their rows have been reordered. a `GtkTreeModel` a `GtkTreePath` pointing to the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` Emits the ::rows-reordered signal on @tree_model. See [signal@Gtk.TreeModel::rows-reordered]. This should be called by models when their rows have been reordered. a `GtkTreeModel` a `GtkTreePath` pointing to the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` length of @new_order array Lets the tree unref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. For more information on what this means, see gtk_tree_model_ref_node(). Please note that nodes that are deleted are not unreffed. a `GtkTreeModel` the `GtkTreeIter` This signal is emitted when a row in the model has changed. a `GtkTreePath` identifying the changed row a valid `GtkTreeIter` pointing to the changed row This signal is emitted when a row has been deleted. Note that no iterator is passed to the signal handler, since the row is already deleted. This should be called by models after a row has been removed. The location pointed to by @path should be the location that the row previously was at. It may not be a valid location anymore. a `GtkTreePath` identifying the row This signal is emitted when a row has gotten the first child row or lost its last child row. a `GtkTreePath` identifying the row a valid `GtkTreeIter` pointing to the row This signal is emitted when a new row has been inserted in the model. Note that the row may still be empty at this point, since it is a common pattern to first insert an empty row, and then fill it with the desired values. a `GtkTreePath` identifying the new row a valid `GtkTreeIter` pointing to the new row This signal is emitted when the children of a node in the `GtkTreeModel` have been reordered. Note that this signal is not emitted when rows are reordered by DND, since this is implemented by removing and then reinserting the row. a `GtkTreePath` identifying the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` A `GtkTreeModel` which hides parts of an underlying tree model A `GtkTreeModelFilter` is a tree model which wraps another tree model, and can do the following things: - Filter specific rows, based on data from a “visible column”, a column storing booleans indicating whether the row should be filtered or not, or based on the return value of a “visible function”, which gets a model, iter and user_data and returns a boolean indicating whether the row should be filtered or not. - Modify the “appearance” of the model, using a modify function. This is extremely powerful and allows for just changing some values and also for creating a completely different model based on the given child model. - Set a different root node, also known as a “virtual root”. You can pass in a `GtkTreePath` indicating the root node for the filter at construction time. The basic API is similar to `GtkTreeModelSort`. For an example on its usage, see the section on `GtkTreeModelSort`. When using `GtkTreeModelFilter`, it is important to realize that `GtkTreeModelFilter` maintains an internal cache of all nodes which are visible in its clients. The cache is likely to be a subtree of the tree exposed by the child model. `GtkTreeModelFilter` will not cache the entire child model when unnecessary to not compromise the caching mechanism that is exposed by the reference counting scheme. If the child model implements reference counting, unnecessary signals may not be emitted because of reference counting rule 3, see the `GtkTreeModel` documentation. (Note that e.g. `GtkTreeStore` does not implement reference counting and will always emit all signals, even when the receiving node is not visible). Because of this, limitations for possible visible functions do apply. In general, visible functions should only use data or properties from the node for which the visibility state must be determined, its siblings or its parents. Usually, having a dependency on the state of any child node is not possible, unless references are taken on these explicitly. When no such reference exists, no signals may be received for these child nodes (see reference counting rule number 3 in the `GtkTreeModel` section). Determining the visibility state of a given node based on the state of its child nodes is a frequently occurring use case. Therefore, `GtkTreeModelFilter` explicitly supports this. For example, when a node does not have any children, you might not want the node to be visible. As soon as the first row is added to the node’s child level (or the last row removed), the node’s visibility should be updated. This introduces a dependency from the node on its child nodes. In order to accommodate this, `GtkTreeModelFilter` must make sure the necessary signals are received from the child model. This is achieved by building, for all nodes which are exposed as visible nodes to `GtkTreeModelFilter`'s clients, the child level (if any) and take a reference on the first node in this level. Furthermore, for every row-inserted, row-changed or row-deleted signal (also these which were not handled because the node was not cached), `GtkTreeModelFilter` will check if the visibility state of any parent node has changed. Beware, however, that this explicit support is limited to these two cases. For example, if you want a node to be visible only if two nodes in a child’s child level (2 levels deeper) are visible, you are on your own. In this case, either rely on `GtkTreeStore` to emit all signals because it does not implement reference counting, or for models that do implement reference counting, obtain references on these child levels yourself. Use [class@Gtk.FilterListModel] instead. This function should almost never be called. It clears the @filter of any cached iterators that haven’t been reffed with gtk_tree_model_ref_node(). This might be useful if the child model being filtered is static (and doesn’t change often) and there has been a lot of unreffed access to nodes. As a side effect of this function, all unreffed iters will be invalid. A `GtkTreeModelFilter` Sets @filter_iter to point to the row in @filter that corresponds to the row pointed at by @child_iter. If @filter_iter was not set, %FALSE is returned. %TRUE, if @filter_iter was set, i.e. if @child_iter is a valid iterator pointing to a visible row in child model. A `GtkTreeModelFilter` An uninitialized `GtkTreeIter` A valid `GtkTreeIter` pointing to a row on the child model. Converts @child_path to a path relative to @filter. That is, @child_path points to a path in the child model. The rerturned path will point to the same row in the filtered model. If @child_path isn’t a valid path on the child model or points to a row which is not visible in @filter, then %NULL is returned. A newly allocated `GtkTreePath` A `GtkTreeModelFilter` A `GtkTreePath` to convert. Sets @child_iter to point to the row pointed to by @filter_iter. A `GtkTreeModelFilter` An uninitialized `GtkTreeIter` A valid `GtkTreeIter` pointing to a row on @filter. Converts @filter_path to a path on the child model of @filter. That is, @filter_path points to a location in @filter. The returned path will point to the same location in the model not being filtered. If @filter_path does not point to a location in the child model, %NULL is returned. A newly allocated `GtkTreePath` A `GtkTreeModelFilter` A `GtkTreePath` to convert. Returns a pointer to the child model of @filter. A pointer to a `GtkTreeModel` A `GtkTreeModelFilter` Emits ::row_changed for each row in the child model, which causes the filter to re-evaluate whether a row is visible or not. A `GtkTreeModelFilter` With the @n_columns and @types parameters, you give an array of column types for this model (which will be exposed to the parent model/view). The @func, @data and @destroy parameters are for specifying the modify function. The modify function will get called for each data access, the goal of the modify function is to return the data which should be displayed at the location specified using the parameters of the modify function. Note that gtk_tree_model_filter_set_modify_func() can only be called once for a given filter model. A `GtkTreeModelFilter` The number of columns in the filter model. The `GType`s of the columns. A `GtkTreeModelFilterModifyFunc` User data to pass to the modify function Destroy notifier of @data Sets @column of the child_model to be the column where @filter should look for visibility information. @columns should be a column of type %G_TYPE_BOOLEAN, where %TRUE means that a row is visible, and %FALSE if not. Note that gtk_tree_model_filter_set_visible_func() or gtk_tree_model_filter_set_visible_column() can only be called once for a given filter model. A `GtkTreeModelFilter` A `int` which is the column containing the visible information Sets the visible function used when filtering the @filter to be @func. The function should return %TRUE if the given row should be visible and %FALSE otherwise. If the condition calculated by the function changes over time (e.g. because it depends on some global parameters), you must call gtk_tree_model_filter_refilter() to keep the visibility information of the model up-to-date. Note that @func is called whenever a row is inserted, when it may still be empty. The visible function should therefore take special care of empty rows, like in the example below. ```c static gboolean visible_func (GtkTreeModel *model, GtkTreeIter *iter, gpointer data) { // Visible if row is non-empty and first column is “HI” char *str; gboolean visible = FALSE; gtk_tree_model_get (model, iter, 0, &str, -1); if (str && strcmp (str, "HI") == 0) visible = TRUE; g_free (str); return visible; } ``` Note that gtk_tree_model_filter_set_visible_func() or gtk_tree_model_filter_set_visible_column() can only be called once for a given filter model. A `GtkTreeModelFilter` A `GtkTreeModelFilterVisibleFunc`, the visible function User data to pass to the visible function Destroy notifier of @data The child model of the tree model filter. The virtual root of the tree model filter. A function which calculates display values from raw values in the model. It must fill @value with the display value for the column @column in the row indicated by @iter. Since this function is called for each data access, it’s not a particularly efficient operation. There is no replacement the `GtkTreeModelFilter` a `GtkTreeIter` pointing to the row whose display values are determined A `GValue` which is already initialized for with the correct type for the column @column. the column whose display value is determined user data given to gtk_tree_model_filter_set_modify_func() A function which decides whether the row indicated by @iter is visible. There is no replacement Whether the row indicated by @iter is visible. the child model of the `GtkTreeModelFilter` a `GtkTreeIter` pointing to the row in @model whose visibility is determined user data given to gtk_tree_model_filter_set_visible_func() These flags indicate various properties of a `GtkTreeModel`. They are returned by [method@Gtk.TreeModel.get_flags], and must be static for the lifetime of the object. A more complete description of %GTK_TREE_MODEL_ITERS_PERSIST can be found in the overview of this section. There is no replacement iterators survive all signals emitted by the tree the model is a list only, and never has children Type of the callback passed to gtk_tree_model_foreach() to iterate over the rows in a tree model. There is no replacement. %TRUE to stop iterating, %FALSE to continue the `GtkTreeModel` being iterated the current `GtkTreePath` the current `GtkTreeIter` The user data passed to gtk_tree_model_foreach() Signal emitted when a row in the model has changed. a `GtkTreeModel` a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row Signal emitted when a new row has been inserted in the model. a `GtkTreeModel` a `GtkTreePath` pointing to the inserted row a valid `GtkTreeIter` pointing to the inserted row Signal emitted when a row has gotten the first child row or lost its last child row. a `GtkTreeModel` a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row Signal emitted when a row has been deleted. a `GtkTreeModel` a `GtkTreePath` pointing to the previous location of the deleted row Signal emitted when the children of a node in the GtkTreeModel have been reordered. a `GtkTreeModel` a `GtkTreePath` pointing to the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` Get `GtkTreeModelFlags` supported by this interface. the flags supported by this interface a `GtkTreeModel` Get the number of columns supported by the model. the number of columns a `GtkTreeModel` Get the type of the column. the type of the column a `GtkTreeModel` the column index Sets iter to a valid iterator pointing to path. %TRUE, if @iter was set a `GtkTreeModel` the uninitialized `GtkTreeIter` the `GtkTreePath` Gets a newly-created `GtkTreePath` referenced by iter. a newly-created `GtkTreePath` a `GtkTreeModel` the `GtkTreeIter` Initializes and sets value to that at column. a `GtkTreeModel` the `GtkTreeIter` the column to lookup the value at an empty `GValue` to set Sets iter to point to the node following it at the current level. %TRUE if @iter has been changed to the next node a `GtkTreeModel` the `GtkTreeIter` Sets iter to point to the previous node at the current level. %TRUE if @iter has been changed to the previous node a `GtkTreeModel` the `GtkTreeIter` Sets iter to point to the first child of parent. %TRUE, if @iter has been set to the first child a `GtkTreeModel` the new `GtkTreeIter` to be set to the child the `GtkTreeIter` %TRUE if iter has children, %FALSE otherwise. %TRUE if @iter has children a `GtkTreeModel` the `GtkTreeIter` to test for children Gets the number of children that iter has. the number of children of @iter a `GtkTreeModel` the `GtkTreeIter` Sets iter to be the child of parent, using the given index. %TRUE, if @parent has an @n-th child a `GtkTreeModel` the `GtkTreeIter` to set to the nth child the `GtkTreeIter` to get the child from the index of the desired child Sets iter to be the parent of child. %TRUE, if @iter is set to the parent of @child a `GtkTreeModel` the new `GtkTreeIter` to set to the parent the `GtkTreeIter` Lets the tree ref the node. a `GtkTreeModel` the `GtkTreeIter` Lets the tree unref the node. a `GtkTreeModel` the `GtkTreeIter` A GtkTreeModel which makes an underlying tree model sortable The `GtkTreeModelSort` is a model which implements the `GtkTreeSortable` interface. It does not hold any data itself, but rather is created with a child model and proxies its data. It has identical column types to this child model, and the changes in the child are propagated. The primary purpose of this model is to provide a way to sort a different model without modifying it. Note that the sort function used by `GtkTreeModelSort` is not guaranteed to be stable. The use of this is best demonstrated through an example. In the following sample code we create two `GtkTreeView` widgets each with a view of the same data. As the model is wrapped here by a `GtkTreeModelSort`, the two `GtkTreeView`s can each sort their view of the data without affecting the other. By contrast, if we simply put the same model in each widget, then sorting the first would sort the second. ## Using a `GtkTreeModelSort` ```c { GtkTreeView *tree_view1; GtkTreeView *tree_view2; GtkTreeModel *sort_model1; GtkTreeModel *sort_model2; GtkTreeModel *child_model; // get the child model child_model = get_my_model (); // Create the first tree sort_model1 = gtk_tree_model_sort_new_with_model (child_model); tree_view1 = gtk_tree_view_new_with_model (sort_model1); // Create the second tree sort_model2 = gtk_tree_model_sort_new_with_model (child_model); tree_view2 = gtk_tree_view_new_with_model (sort_model2); // Now we can sort the two models independently gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1), COLUMN_1, GTK_SORT_ASCENDING); gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2), COLUMN_1, GTK_SORT_DESCENDING); } ``` To demonstrate how to access the underlying child model from the sort model, the next example will be a callback for the `GtkTreeSelection` `GtkTreeSelection::changed` signal. In this callback, we get a string from COLUMN_1 of the model. We then modify the string, find the same selected row on the child model, and change the row there. ## Accessing the child model of in a selection changed callback ```c void selection_changed (GtkTreeSelection *selection, gpointer data) { GtkTreeModel *sort_model = NULL; GtkTreeModel *child_model; GtkTreeIter sort_iter; GtkTreeIter child_iter; char *some_data = NULL; char *modified_data; // Get the current selected row and the model. if (! gtk_tree_selection_get_selected (selection, &sort_model, &sort_iter)) return; // Look up the current value on the selected row and get // a new value to change it to. gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter, COLUMN_1, &some_data, -1); modified_data = change_the_data (some_data); g_free (some_data); // Get an iterator on the child model, instead of the sort model. gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model), &child_iter, &sort_iter); // Get the child model and change the value of the row. In this // example, the child model is a GtkListStore. It could be any other // type of model, though. child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model)); gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter, COLUMN_1, &modified_data, -1); g_free (modified_data); } ``` Use [class@Gtk.SortListModel] instead Creates a new `GtkTreeModelSort`, with @child_model as the child model. A new `GtkTreeModelSort`. A `GtkTreeModel` This function should almost never be called. It clears the @tree_model_sort of any cached iterators that haven’t been reffed with gtk_tree_model_ref_node(). This might be useful if the child model being sorted is static (and doesn’t change often) and there has been a lot of unreffed access to nodes. As a side effect of this function, all unreffed iters will be invalid. A `GtkTreeModelSort` Sets @sort_iter to point to the row in @tree_model_sort that corresponds to the row pointed at by @child_iter. If @sort_iter was not set, %FALSE is returned. Note: a boolean is only returned since 2.14. %TRUE, if @sort_iter was set, i.e. if @sort_iter is a valid iterator pointer to a visible row in the child model. A `GtkTreeModelSort` An uninitialized `GtkTreeIter` A valid `GtkTreeIter` pointing to a row on the child model Converts @child_path to a path relative to @tree_model_sort. That is, @child_path points to a path in the child model. The returned path will point to the same row in the sorted model. If @child_path isn’t a valid path on the child model, then %NULL is returned. A newly allocated `GtkTreePath` A `GtkTreeModelSort` A `GtkTreePath` to convert Sets @child_iter to point to the row pointed to by @sorted_iter. A `GtkTreeModelSort` An uninitialized `GtkTreeIter` A valid `GtkTreeIter` pointing to a row on @tree_model_sort. Converts @sorted_path to a path on the child model of @tree_model_sort. That is, @sorted_path points to a location in @tree_model_sort. The returned path will point to the same location in the model not being sorted. If @sorted_path does not point to a location in the child model, %NULL is returned. A newly allocated `GtkTreePath` A `GtkTreeModelSort` A `GtkTreePath` to convert Returns the model the `GtkTreeModelSort` is sorting. the "child model" being sorted a `GtkTreeModelSort` > This function is slow. Only use it for debugging and/or testing > purposes. Checks if the given iter is a valid iter for this `GtkTreeModelSort`. %TRUE if the iter is valid, %FALSE if the iter is invalid. A `GtkTreeModelSort`. A `GtkTreeIter` This resets the default sort function to be in the “unsorted” state. That is, it is in the same order as the child model. It will re-sort the model to be in the same order as the child model only if the `GtkTreeModelSort` is in “unsorted” state. A `GtkTreeModelSort` The model of the tree model sort. An opaque structure representing a path to a row in a model. Creates a new `GtkTreePath` This refers to a row. A newly created `GtkTreePath`. Creates a new `GtkTreePath`. The string representation of this path is “0”. A new `GtkTreePath` Creates a new path with @first_index and @varargs as indices. A newly created `GtkTreePath` first integer list of integers terminated by -1 Creates a new path with the given @indices array of @length. A newly created `GtkTreePath` array of indices length of @indices array Creates a new `GtkTreePath` initialized to @path. @path is expected to be a colon separated list of numbers. For example, the string “10:4:0” would create a path of depth 3 pointing to the 11th child of the root node, the 5th child of that 11th child, and the 1st child of that 5th child. If an invalid path string is passed in, %NULL is returned. A newly-created `GtkTreePath` The string representation of a path Appends a new index to a path. As a result, the depth of the path is increased. a `GtkTreePath` the index Compares two paths. If @a appears before @b in a tree, then -1 is returned. If @b appears before @a, then 1 is returned. If the two nodes are equal, then 0 is returned. the relative positions of @a and @b a `GtkTreePath` a `GtkTreePath` to compare with Creates a new `GtkTreePath` as a copy of @path. a new `GtkTreePath` a `GtkTreePath` Moves @path to point to the first child of the current path. a `GtkTreePath` Frees @path. If @path is %NULL, it simply returns. a `GtkTreePath` Returns the current depth of @path. The depth of @path a `GtkTreePath` Returns the current indices of @path. This is an array of integers, each representing a node in a tree. This value should not be freed. The length of the array can be obtained with gtk_tree_path_get_depth(). The current indices a `GtkTreePath` Returns the current indices of @path. This is an array of integers, each representing a node in a tree. It also returns the number of elements in the array. The array should not be freed. The current indices a `GtkTreePath` return location for number of elements returned in the integer array Returns %TRUE if @descendant is a descendant of @path. %TRUE if @descendant is contained inside @path a `GtkTreePath` another `GtkTreePath` Returns %TRUE if @path is a descendant of @ancestor. %TRUE if @ancestor contains @path somewhere below it a `GtkTreePath` another `GtkTreePath` Moves the @path to point to the next node at the current depth. a `GtkTreePath` Prepends a new index to a path. As a result, the depth of the path is increased. a `GtkTreePath` the index Moves the @path to point to the previous node at the current depth, if it exists. %TRUE if @path has a previous node, and the move was made a `GtkTreePath` Generates a string representation of the path. This string is a “:” separated list of numbers. For example, “4:10:0:3” would be an acceptable return value for this string. If the path has depth 0, %NULL is returned. A newly-allocated string a `GtkTreePath` Moves the @path to point to its parent node, if it has a parent. %TRUE if @path has a parent, and the move was made a `GtkTreePath` A GtkTreeRowReference tracks model changes so that it always refers to the same row (a `GtkTreePath` refers to a position, not a fixed row). Create a new GtkTreeRowReference with gtk_tree_row_reference_new(). Use [iface@Gio.ListModel] instead Creates a row reference based on @path. This reference will keep pointing to the node pointed to by @path, so long as it exists. Any changes that occur on @model are propagated, and the path is updated appropriately. If @path isn’t a valid path in @model, then %NULL is returned. a newly allocated `GtkTreeRowReference` a `GtkTreeModel` a valid `GtkTreePath` to monitor You do not need to use this function. Creates a row reference based on @path. This reference will keep pointing to the node pointed to by @path, so long as it exists. If @path isn’t a valid path in @model, then %NULL is returned. However, unlike references created with gtk_tree_row_reference_new(), it does not listen to the model for changes. The creator of the row reference must do this explicitly using gtk_tree_row_reference_inserted(), gtk_tree_row_reference_deleted(), gtk_tree_row_reference_reordered(). These functions must be called exactly once per proxy when the corresponding signal on the model is emitted. This single call updates all row references for that proxy. Since built-in GTK objects like `GtkTreeView` already use this mechanism internally, using them as the proxy object will produce unpredictable results. Further more, passing the same object as @model and @proxy doesn’t work for reasons of internal implementation. This type of row reference is primarily meant by structures that need to carefully monitor exactly when a row reference updates itself, and is not generally needed by most applications. a newly allocated `GtkTreeRowReference` a proxy `GObject` a `GtkTreeModel` a valid `GtkTreePath` to monitor Copies a `GtkTreeRowReference`. a copy of @reference a `GtkTreeRowReference` Free’s @reference. @reference may be %NULL a `GtkTreeRowReference` Returns the model that the row reference is monitoring. the model a `GtkTreeRowReference` Returns a path that the row reference currently points to, or %NULL if the path pointed to is no longer valid. a current path a `GtkTreeRowReference` Returns %TRUE if the @reference is non-%NULL and refers to a current valid path. %TRUE if @reference points to a valid path a `GtkTreeRowReference` Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::row-deleted signal. a `GObject` the path position that was deleted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::row-inserted signal. a `GObject` the row position that was inserted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::rows-reordered signal. a `GObject` the parent path of the reordered signal the iter pointing to the parent of the reordered the new order of rows The selection object for GtkTreeView The `GtkTreeSelection` object is a helper object to manage the selection for a `GtkTreeView` widget. The `GtkTreeSelection` object is automatically created when a new `GtkTreeView` widget is created, and cannot exist independently of this widget. The primary reason the `GtkTreeSelection` objects exists is for cleanliness of code and API. That is, there is no conceptual reason all these functions could not be methods on the `GtkTreeView` widget instead of a separate function. The `GtkTreeSelection` object is gotten from a `GtkTreeView` by calling gtk_tree_view_get_selection(). It can be manipulated to check the selection status of the tree, as well as select and deselect individual rows. Selection is done completely view side. As a result, multiple views of the same model can have completely different selections. Additionally, you cannot change the selection of a row on the model that is not currently displayed by the view without expanding its parents first. One of the important things to remember when monitoring the selection of a view is that the `GtkTreeSelection`::changed signal is mostly a hint. That is, it may only emit one signal when a range of rows is selected. Additionally, it may on occasion emit a `GtkTreeSelection`::changed signal when nothing has happened (mostly as a result of programmers calling select_row on an already selected row). Use [iface@Gtk.SelectionModel] instead Returns the number of rows that have been selected in @tree. Use GtkListView or GtkColumnView The number of rows selected. A `GtkTreeSelection`. Gets the selection mode for @selection. See gtk_tree_selection_set_mode(). Use GtkListView or GtkColumnView the current selection mode a `GtkTreeSelection` Returns the current selection function. Use GtkListView or GtkColumnView The function. A `GtkTreeSelection`. Sets @iter to the currently selected node if @selection is set to %GTK_SELECTION_SINGLE or %GTK_SELECTION_BROWSE. @iter may be NULL if you just want to test if @selection has any selected nodes. @model is filled with the current model as a convenience. This function will not work if you use @selection is %GTK_SELECTION_MULTIPLE. Use GtkListView or GtkColumnView TRUE, if there is a selected node. A `GtkTreeSelection`. A pointer to set to the `GtkTreeModel` The `GtkTreeIter` Creates a list of path of all selected rows. Additionally, if you are planning on modifying the model after calling this function, you may want to convert the returned list into a list of `GtkTreeRowReference`s. To do this, you can use gtk_tree_row_reference_new(). To free the return value, use: ```c g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); ``` Use GtkListView or GtkColumnView A `GList` containing a `GtkTreePath` for each selected row. A `GtkTreeSelection`. A pointer to set to the `GtkTreeModel` Returns the tree view associated with @selection. Use GtkListView or GtkColumnView A `GtkTreeView` A `GtkTreeSelection` Returns the user data for the selection function. Use GtkListView or GtkColumnView The user data. A `GtkTreeSelection`. Returns %TRUE if the row at @iter is currently selected. Use GtkListView or GtkColumnView %TRUE, if @iter is selected A `GtkTreeSelection` A valid `GtkTreeIter` Returns %TRUE if the row pointed to by @path is currently selected. If @path does not point to a valid location, %FALSE is returned Use GtkListView or GtkColumnView %TRUE if @path is selected. A `GtkTreeSelection`. A `GtkTreePath` to check selection on. Selects all the nodes. @selection must be set to %GTK_SELECTION_MULTIPLE mode. Use GtkListView or GtkColumnView A `GtkTreeSelection`. Selects the specified iterator. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The `GtkTreeIter` to be selected. Select the row at @path. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The `GtkTreePath` to be selected. Selects a range of nodes, determined by @start_path and @end_path inclusive. @selection must be set to %GTK_SELECTION_MULTIPLE mode. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The initial node of the range. The final node of the range. Calls a function for each selected node. Note that you cannot modify the tree or selection from within this function. As a result, gtk_tree_selection_get_selected_rows() might be more useful. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The function to call for each selected node. user data to pass to the function. Sets the selection mode of the @selection. If the previous type was %GTK_SELECTION_MULTIPLE, then the anchor is kept selected, if it was previously selected. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The selection mode Sets the selection function. If set, this function is called before any node is selected or unselected, giving some control over which nodes are selected. The select function should return %TRUE if the state of the node may be toggled, and %FALSE if the state of the node should be left unchanged. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The selection function. May be %NULL The selection function’s data. May be %NULL The destroy function for user data. May be %NULL Unselects all the nodes. Use GtkListView or GtkColumnView A `GtkTreeSelection`. Unselects the specified iterator. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The `GtkTreeIter` to be unselected. Unselects the row at @path. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The `GtkTreePath` to be unselected. Unselects a range of nodes, determined by @start_path and @end_path inclusive. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The initial node of the range. The initial node of the range. Selection mode. See gtk_tree_selection_set_mode() for more information on this property. Emitted whenever the selection has (possibly) changed. Please note that this signal is mostly a hint. It may only be emitted once when a range of rows are selected, and it may occasionally be emitted when nothing has happened. A function used by gtk_tree_selection_selected_foreach() to map all selected rows. It will be called on every selected row in the view. There is no replacement The `GtkTreeModel` being viewed The `GtkTreePath` of a selected row A `GtkTreeIter` pointing to a selected row user data A function used by gtk_tree_selection_set_select_function() to filter whether or not a row may be selected. It is called whenever a row's state might change. A return value of %TRUE indicates to @selection that it is okay to change the selection. There is no replacement %TRUE, if the selection state of the row can be toggled A `GtkTreeSelection` A `GtkTreeModel` being viewed The `GtkTreePath` of the row in question %TRUE, if the path is currently selected user data The interface for sortable models used by GtkTreeView `GtkTreeSortable` is an interface to be implemented by tree models which support sorting. The `GtkTreeView` uses the methods provided by this interface to sort the model. There is no replacement for this interface. You should use [class@Gtk.SortListModel] to wrap your list model instead Fills in @sort_column_id and @order with the current sort column and the order. It returns %TRUE unless the @sort_column_id is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID or %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID. %TRUE if the sort column is not one of the special sort column ids. A `GtkTreeSortable` The sort column id to be filled in The `GtkSortType` to be filled in Returns %TRUE if the model has a default sort function. This is used primarily by GtkTreeViewColumns in order to determine if a model can go back to the default state, or not. %TRUE, if the model has a default sort function A `GtkTreeSortable` Sets the default comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the model will sort using this function. If @sort_func is %NULL, then there will be no default comparison function. This means that once the model has been sorted, it can’t go back to the default state. In this case, when the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted. A `GtkTreeSortable` The comparison function User data to pass to @sort_func Destroy notifier of @user_data Sets the current sort column to be @sort_column_id. The @sortable will resort itself to reflect this change, after emitting a `GtkTreeSortable::sort-column-changed` signal. @sort_column_id may either be a regular column id, or one of the following special values: - %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID: the default sort function will be used, if it is set - %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID: no sorting will occur A `GtkTreeSortable` the sort column id to set The sort order of the column Sets the comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is the same as @sort_column_id, then the model will sort using this function. A `GtkTreeSortable` the sort column id to set the function for The comparison function User data to pass to @sort_func Destroy notifier of @user_data Emits a `GtkTreeSortable::sort-column-changed` signal on @sortable. A `GtkTreeSortable` Fills in @sort_column_id and @order with the current sort column and the order. It returns %TRUE unless the @sort_column_id is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID or %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID. %TRUE if the sort column is not one of the special sort column ids. A `GtkTreeSortable` The sort column id to be filled in The `GtkSortType` to be filled in Returns %TRUE if the model has a default sort function. This is used primarily by GtkTreeViewColumns in order to determine if a model can go back to the default state, or not. %TRUE, if the model has a default sort function A `GtkTreeSortable` Sets the default comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the model will sort using this function. If @sort_func is %NULL, then there will be no default comparison function. This means that once the model has been sorted, it can’t go back to the default state. In this case, when the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted. A `GtkTreeSortable` The comparison function User data to pass to @sort_func Destroy notifier of @user_data Sets the current sort column to be @sort_column_id. The @sortable will resort itself to reflect this change, after emitting a `GtkTreeSortable::sort-column-changed` signal. @sort_column_id may either be a regular column id, or one of the following special values: - %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID: the default sort function will be used, if it is set - %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID: no sorting will occur A `GtkTreeSortable` the sort column id to set The sort order of the column Sets the comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is the same as @sort_column_id, then the model will sort using this function. A `GtkTreeSortable` the sort column id to set the function for The comparison function User data to pass to @sort_func Destroy notifier of @user_data Emits a `GtkTreeSortable::sort-column-changed` signal on @sortable. A `GtkTreeSortable` The ::sort-column-changed signal is emitted when the sort column or sort order of @sortable is changed. The signal is emitted before the contents of @sortable are resorted. Signal emitted when the sort column or sort order of sortable is changed. A `GtkTreeSortable` Fills in sort_column_id and order with the current sort column and the order. %TRUE if the sort column is not one of the special sort column ids. A `GtkTreeSortable` The sort column id to be filled in The `GtkSortType` to be filled in Sets the current sort column to be sort_column_id. A `GtkTreeSortable` the sort column id to set The sort order of the column Sets the comparison function used when sorting to be sort_func. A `GtkTreeSortable` the sort column id to set the function for The comparison function User data to pass to @sort_func Destroy notifier of @user_data Sets the default comparison function used when sorting to be sort_func. A `GtkTreeSortable` The comparison function User data to pass to @sort_func Destroy notifier of @user_data %TRUE if the model has a default sort function. %TRUE, if the model has a default sort function A `GtkTreeSortable` A tree-like data structure that can be used with the [class@Gtk.TreeView]. The `GtkTreeStore` object is a list model for use with a `GtkTreeView` widget. It implements the [iface@Gtk.TreeModel] interface, and consequently, can use all of the methods available there. It also implements the [iface@Gtk.TreeSortable] interface so it can be sorted by the view. Finally, it also implements the tree [drag][iface@Gtk.TreeDragSource] and [drop][iface@Gtk.TreeDragDest] interfaces. `GtkTreeStore` is deprecated since GTK 4.10, and should not be used in newly written code. You should use [class@Gtk.TreeListModel] for a tree-like model object. ## GtkTreeStore as GtkBuildable The GtkTreeStore implementation of the `GtkBuildable` interface allows to specify the model columns with a `<columns>` element that may contain multiple `<column>` elements, each specifying one model column. The “type” attribute specifies the data type for the column. An example of a UI Definition fragment for a tree store: ```xml <object class="GtkTreeStore"> <columns> <column type="gchararray"/> <column type="gchararray"/> <column type="gint"/> </columns> </object> ``` Use [class@Gtk.TreeListModel] instead Creates a new tree store. The tree store will have @n_columns, with each column using the corresponding type passed to this function. Note that only types derived from standard GObject fundamental types are supported. As an example: ```c gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING, GDK_TYPE_TEXTURE); ``` will create a new `GtkTreeStore` with three columns of type `int`, `gchararray`, and `GdkTexture` respectively. Use [class@Gtk.TreeListModel] instead a new `GtkTreeStore` number of columns in the tree store all `GType` types for the columns, from first to last Creates a new tree store. This constructor is meant for language bindings. Use [class@Gtk.TreeListModel] instead a new `GtkTreeStore` number of columns in the tree store an array of `GType` types for the columns, from first to last Appends a new row to @tree_store. If @parent is non-%NULL, then it will append the new row after the last child of @parent, otherwise it will append a row to the top level. The @iter parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set to the appended row A valid `GtkTreeIter` Removes all rows from @tree_store Use [class@Gtk.TreeListModel] instead a `GtkTreeStore` Creates a new row at @position. If parent is non-%NULL, then the row will be made a child of @parent. Otherwise, the row will be created at the toplevel. If @position is `-1` or is larger than the number of rows at that level, then the new row will be inserted to the end of the list. The @iter parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set to the new row A valid `GtkTreeIter` position to insert the new row, or -1 for last Inserts a new row after @sibling. If @sibling is %NULL, then the row will be prepended to @parent’s children. If @parent and @sibling are %NULL, then the row will be prepended to the toplevel. If both @sibling and @parent are set, then @parent must be the parent of @sibling. When @sibling is set, @parent is optional. The @iter parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set to the new row A valid `GtkTreeIter` A valid `GtkTreeIter` Inserts a new row before @sibling. If @sibling is %NULL, then the row will be appended to @parent’s children. If @parent and @sibling are %NULL, then the row will be appended to the toplevel. If both @sibling and @parent are set, then @parent must be the parent of @sibling. When @sibling is set, @parent is optional. The @iter parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set to the new row A valid `GtkTreeIter` A valid `GtkTreeIter` Creates a new row at the given @position. The @iter parameter will be changed to point to this new row. If @position is -1, or larger than the number of rows on the list, then the new row will be appended to the list. The row will be filled with the values given to this function. Calling gtk_tree_store_insert_with_values (tree_store, iter, position, ...) has the same effect as calling ```c gtk_tree_store_insert (tree_store, iter, position); gtk_tree_store_set (tree_store, iter, ...); ``` with the different that the former will only emit a row_inserted signal, while the latter will emit row_inserted, row_changed and if the tree store is sorted, rows_reordered. Since emitting the rows_reordered signal repeatedly can affect the performance of the program, gtk_tree_store_insert_with_values() should generally be preferred when inserting rows in a sorted tree store. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set the new row A valid `GtkTreeIter` position to insert the new row, or -1 to append after existing rows pairs of column number and value, terminated with -1 A variant of gtk_tree_store_insert_with_values() which takes the columns and values as two arrays, instead of varargs. This function is mainly intended for language bindings. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set the new row A valid `GtkTreeIter` position to insert the new row, or -1 for last an array of column numbers an array of GValues the length of the @columns and @values arrays Checks if @iter is an ancestor of @descendant. Use [class@Gtk.TreeListModel] instead true if @iter is an ancestor of @descendant, and false otherwise A `GtkTreeStore` A valid `GtkTreeIter` A valid `GtkTreeIter` Returns the depth of the position pointed by the iterator The depth will be 0 for anything on the root level, 1 for anything down a level, etc. Use [class@Gtk.TreeListModel] instead The depth of the position pointed by the iterator A `GtkTreeStore` A valid `GtkTreeIter` Checks if the given iter is a valid iter for this `GtkTreeStore`. This function is slow. Only use it for debugging and/or testing purposes. Use [class@Gtk.TreeListModel] instead true if the iter is valid, and false otherwise a tree store the iterator to check Moves @iter in @tree_store to the position after @position. @iter and @position should be in the same level. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the start of the level. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` A `GtkTreeIter`. A `GtkTreeIter`. Moves @iter in @tree_store to the position before @position. @iter and @position should be in the same level. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the end of the level. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` A `GtkTreeIter` A `GtkTreeIter` Prepends a new row to @tree_store. If @parent is non-%NULL, then it will prepend the new row before the first child of @parent, otherwise it will prepend a row to the top level. The `iter` parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set to the prepended row A valid `GtkTreeIter` Removes @iter from @tree_store. After being removed, @iter is set to the next valid row at that level, or invalidated if it previously pointed to the last one. Use [class@Gtk.TreeListModel] instead true if @iter is still valid, and false otherwise A `GtkTreeStore` A valid `GtkTreeIter` Reorders the children of @parent in @tree_store to follow the order indicated by @new_order. Note that this function only works with unsorted stores. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` the parent of the children to re-order an array of integers mapping the new position of each child to its old position before the re-ordering, i.e. `new_order[newpos] = oldpos` Sets the value of one or more cells in the row referenced by @iter. The variable argument list should contain integer column numbers, each column number followed by the value to be set. The list is terminated by a value of `-1`. For example, to set column 0 with type `G_TYPE_STRING` to “Foo”, you would write ```c gtk_tree_store_set (store, iter, 0, "Foo", -1); ``` The value will be referenced by the store if it is a `G_TYPE_OBJECT`, and it will be copied if it is a `G_TYPE_STRING` or `G_TYPE_BOXED`. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` A valid `GtkTreeIter` for the row being modified pairs of column number and value, terminated with -1 Sets the type of the columns in a tree store. This function is meant primarily for types that inherit from `GtkTreeStore`, and should only be used when constructing a new `GtkTreeStore`. This functions cannot be called after a row has been added, or a method on the `GtkTreeModel` interface is called on the tree store. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` Number of columns for the tree store An array of `GType` types, one for each column A version of gtk_tree_store_set() using `va_list`. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` A valid `GtkTreeIter` for the row being modified va_list of column/value pairs Sets the data in the cell specified by @iter and @column. The type of @value must be convertible to the type of the column. Use [class@Gtk.TreeListModel] instead a `GtkTreeStore` A valid `GtkTreeIter` for the row being modified column number to modify new value for the cell A variant of gtk_tree_store_set_valist() which takes the columns and values as two arrays, instead of using variadic arguments. This function is mainly intended for language bindings or in case the number of columns to change is not known until run-time. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` A valid `GtkTreeIter` for the row being modified an array of column numbers an array of GValues the length of the @columns and @values arrays Swaps @a and @b in the same level of @tree_store. Note that this function only works with unsorted stores. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore`. A `GtkTreeIter`. Another `GtkTreeIter`. A widget for displaying both trees and lists <picture> <source srcset="list-and-tree-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkTreeView" src="list-and-tree.png"> </picture> Widget that displays any object that implements the [iface@Gtk.TreeModel] interface. Please refer to the [tree widget conceptual overview](section-tree-widget.html) for an overview of all the objects and data types related to the tree widget and how they work together. ## Coordinate systems in GtkTreeView API Several different coordinate systems are exposed in the `GtkTreeView` API. These are: ![](tree-view-coordinates.png) - Widget coordinates: Coordinates relative to the widget (usually `widget->window`). - Bin window coordinates: Coordinates relative to the window that GtkTreeView renders to. - Tree coordinates: Coordinates relative to the entire scrollable area of GtkTreeView. These coordinates start at (0, 0) for row 0 of the tree. Several functions are available for converting between the different coordinate systems. The most common translations are between widget and bin window coordinates and between bin window and tree coordinates. For the former you can use [method@Gtk.TreeView.convert_widget_to_bin_window_coords] (and vice versa), for the latter [method@Gtk.TreeView.convert_bin_window_to_tree_coords] (and vice versa). ## `GtkTreeView` as `GtkBuildable` The `GtkTreeView` implementation of the `GtkBuildable` interface accepts [class@Gtk.TreeViewColumn] objects as `<child>` elements and exposes the internal [class@Gtk.TreeSelection] in UI definitions. An example of a UI definition fragment with `GtkTreeView`: ```xml <object class="GtkTreeView" id="treeview"> <property name="model">liststore1</property> <child> <object class="GtkTreeViewColumn" id="test-column"> <property name="title">Test</property> <child> <object class="GtkCellRendererText" id="test-renderer"/> <attributes> <attribute name="text">1</attribute> </attributes> </child> </object> </child> <child internal-child="selection"> <object class="GtkTreeSelection" id="selection"> <signal name="changed" handler="on_treeview_selection_changed"/> </object> </child> </object> ``` ## CSS nodes ``` treeview.view ├── header │ ├── button │ │ ╰── [sort-indicator] ┊ ┊ │ ╰── button │ ╰── [sort-indicator] │ ├── [rubberband] ╰── [dndtarget] ``` `GtkTreeView` has a main CSS node with name `treeview` and style class `.view`. It has a subnode with name `header`, which is the parent for all the column header widgets' CSS nodes. Each column header consists of a `button`, which among other content, has a child with name `sort-indicator`, which carries the `.ascending` or `.descending` style classes when the column header should show a sort indicator. The CSS is expected to provide a suitable image using the `-gtk-icon-source` property. For rubberband selection, a subnode with name `rubberband` is used. For the drop target location during DND, a subnode with name `dndtarget` is used. Use [class@Gtk.ListView] for lists, and [class@Gtk.ColumnView] for tabular lists Creates a new `GtkTreeView` widget. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A newly created `GtkTreeView` widget. Creates a new `GtkTreeView` widget with the model initialized to @model. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A newly created `GtkTreeView` widget. the model. Activates the cell determined by @path and @column. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` The `GtkTreePath` to be activated. The `GtkTreeViewColumn` to be activated. Appends @column to the list of columns. If @tree_view has “fixed_height” mode enabled, then @column must have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The number of columns in @tree_view after appending. A `GtkTreeView`. The `GtkTreeViewColumn` to add. Recursively collapses all visible, expanded nodes in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. Collapses a row (hides its child rows, if they exist). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if the row was collapsed. a `GtkTreeView` path to a row in the @tree_view Resizes all columns to their optimal width. Only works after the treeview has been realized. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. Converts bin_window coordinates to coordinates for the tree (the full scrollable area of the tree). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` X coordinate relative to bin_window Y coordinate relative to bin_window return location for tree X coordinate return location for tree Y coordinate Converts bin_window coordinates to widget relative coordinates. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` bin_window X coordinate bin_window Y coordinate return location for widget X coordinate return location for widget Y coordinate Converts tree coordinates (coordinates in full scrollable area of the tree) to bin_window coordinates. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` tree X coordinate tree Y coordinate return location for X coordinate relative to bin_window return location for Y coordinate relative to bin_window Converts tree coordinates (coordinates in full scrollable area of the tree) to widget coordinates. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` X coordinate relative to the tree Y coordinate relative to the tree return location for widget X coordinate return location for widget Y coordinate Converts widget coordinates to coordinates for the bin_window. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` X coordinate relative to the widget Y coordinate relative to the widget return location for bin_window X coordinate return location for bin_window Y coordinate Converts widget coordinates to coordinates for the tree (the full scrollable area of the tree). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` X coordinate relative to the widget Y coordinate relative to the widget return location for tree X coordinate return location for tree Y coordinate Creates a `cairo_surface_t` representation of the row at @path. This image is used for a drag icon. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a newly-allocated surface of the drag icon. a `GtkTreeView` a `GtkTreePath` in @tree_view Turns @tree_view into a drop destination for automatic DND. Calling this method sets `GtkTreeView`:reorderable to %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` the target formats that the drag will support the bitmask of possible actions for a drag from this widget Turns @tree_view into a drag source for automatic DND. Calling this method sets `GtkTreeView`:reorderable to %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` Mask of allowed buttons to start drag the target formats that the drag will support the bitmask of possible actions for a drag from this widget Recursively expands all nodes in the @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. Opens the row so its children are visible. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if the row existed and had children a `GtkTreeView` path to a row whether to recursively expand, or just expand immediate children Expands the row at @path. This will also expand all parent rows of @path as necessary. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. path to a row. Gets the setting set by gtk_tree_view_set_activate_on_single_click(). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if row-activated will be emitted on a single click a `GtkTreeView` Fills the bounding rectangle in bin_window coordinates for the cell at the row specified by @path and the column specified by @column. If @path is %NULL, or points to a node not found in the tree, the @y and @height fields of the rectangle will be filled with 0. If @column is %NULL, the @x and @width fields will be filled with 0. The returned rectangle is equivalent to the @background_area passed to gtk_cell_renderer_render(). These background areas tile to cover the entire bin window. Contrast with the @cell_area, returned by gtk_tree_view_get_cell_area(), which returns only the cell itself, excluding surrounding borders and the tree expander area. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` a `GtkTreePath` for the row, or %NULL to get only horizontal coordinates a `GtkTreeViewColumn` for the column, or %NULL to get only vertical coordinates rectangle to fill with cell background rect Fills the bounding rectangle in bin_window coordinates for the cell at the row specified by @path and the column specified by @column. If @path is %NULL, or points to a path not currently displayed, the @y and @height fields of the rectangle will be filled with 0. If @column is %NULL, the @x and @width fields will be filled with 0. The sum of all cell rects does not cover the entire tree; there are extra pixels in between rows, for example. The returned rectangle is equivalent to the @cell_area passed to gtk_cell_renderer_render(). This function is only valid if @tree_view is realized. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` a `GtkTreePath` for the row, or %NULL to get only horizontal coordinates a `GtkTreeViewColumn` for the column, or %NULL to get only vertical coordinates rectangle to fill with cell rect Gets the `GtkTreeViewColumn` at the given position in the #tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The `GtkTreeViewColumn`, or %NULL if the position is outside the range of columns. A `GtkTreeView`. The position of the column, counting from 0. Returns a `GList` of all the `GtkTreeViewColumn`s currently in @tree_view. The returned list must be freed with g_list_free (). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A list of `GtkTreeViewColumn`s A `GtkTreeView` Fills in @path and @focus_column with the current path and focus column. If the cursor isn’t currently set, then *@path will be %NULL. If no column currently has focus, then *@focus_column will be %NULL. The returned `GtkTreePath` must be freed with gtk_tree_path_free() when you are done with it. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` A pointer to be filled with the current cursor path A pointer to be filled with the current focus column Determines the destination row for a given position. @drag_x and @drag_y are expected to be in widget coordinates. This function is only meaningful if @tree_view is realized. Therefore this function will always return %FALSE if @tree_view is not realized or does not have a model. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead whether there is a row at the given position, %TRUE if this is indeed the case. a `GtkTreeView` the position to determine the destination row for the position to determine the destination row for Return location for the path of the highlighted row Return location for the drop position, or %NULL Gets information about the row that is highlighted for feedback. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` Return location for the path of the highlighted row Return location for the drop position Returns whether or not the tree allows to start interactive searching by typing in text. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead whether or not to let the user search interactively A `GtkTreeView` Returns whether or not tree lines are drawn in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if tree lines are drawn in @tree_view, %FALSE otherwise. a `GtkTreeView`. Returns the column that is the current expander column, or %NULL if none has been set. This column has the expander arrow drawn next to it. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The expander column. A `GtkTreeView` Returns whether fixed height mode is turned on for @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if @tree_view is in fixed height mode a `GtkTreeView` Returns which grid lines are enabled in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView`GridLines value indicating which grid lines are enabled. a `GtkTreeView` Returns whether all header columns are clickable. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if all header columns are clickable, otherwise %FALSE A `GtkTreeView`. Returns %TRUE if the headers on the @tree_view are visible. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead Whether the headers are visible or not. A `GtkTreeView`. Returns whether hover expansion mode is turned on for @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if @tree_view is in hover expansion mode a `GtkTreeView` Returns whether hover selection mode is turned on for @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if @tree_view is in hover selection mode a `GtkTreeView` Returns the amount, in pixels, of extra indentation for child levels in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the amount of extra indentation for child levels in @tree_view. A return value of 0 means that this feature is disabled. a `GtkTreeView`. Returns the model the `GtkTreeView` is based on. Returns %NULL if the model is unset. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeModel` a `GtkTreeView` Queries the number of columns in the given @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The number of columns in the @tree_view a `GtkTreeView` Finds the path at the point (@x, @y), relative to bin_window coordinates. That is, @x and @y are relative to an events coordinates. Widget-relative coordinates must be converted using gtk_tree_view_convert_widget_to_bin_window_coords(). It is primarily for things like popup menus. If @path is non-%NULL, then it will be filled with the `GtkTreePath` at that point. This path should be freed with gtk_tree_path_free(). If @column is non-%NULL, then it will be filled with the column at that point. @cell_x and @cell_y return the coordinates relative to the cell background (i.e. the @background_area passed to gtk_cell_renderer_render()). This function is only meaningful if @tree_view is realized. Therefore this function will always return %FALSE if @tree_view is not realized or does not have a model. For converting widget coordinates (eg. the ones you get from GtkWidget::query-tooltip), please see gtk_tree_view_convert_widget_to_bin_window_coords(). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if a row exists at that coordinate. A `GtkTreeView`. The x position to be identified (relative to bin_window). The y position to be identified (relative to bin_window). A pointer to a `GtkTreePath` pointer to be filled in A pointer to a `GtkTreeViewColumn` pointer to be filled in A pointer where the X coordinate relative to the cell can be placed A pointer where the Y coordinate relative to the cell can be placed Retrieves whether the user can reorder the tree via drag-and-drop. See gtk_tree_view_set_reorderable(). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if the tree can be reordered. a `GtkTreeView` Returns the current row separator function. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the current row separator function. a `GtkTreeView` Returns whether rubber banding is turned on for @tree_view. If the selection mode is %GTK_SELECTION_MULTIPLE, rubber banding will allow the user to select multiple rows by dragging the mouse. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if rubber banding in @tree_view is enabled. a `GtkTreeView` Gets the column searched on by the interactive search code. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the column the interactive search code searches in. A `GtkTreeView` Returns the `GtkEntry` which is currently in use as interactive search entry for @tree_view. In case the built-in entry is being used, %NULL will be returned. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the entry currently in use as search entry. A `GtkTreeView` Returns the compare function currently in use. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the currently used compare function for the search code. A `GtkTreeView` Gets the `GtkTreeSelection` associated with @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeSelection` object. A `GtkTreeView`. Returns whether or not expanders are drawn in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if expanders are drawn in @tree_view, %FALSE otherwise. a `GtkTreeView`. Returns the column of @tree_view’s model which is being used for displaying tooltips on @tree_view’s rows. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the index of the tooltip column that is currently being used, or -1 if this is disabled. a `GtkTreeView` This function is supposed to be used in a ::query-tooltip signal handler for `GtkTreeView`. The @x, @y and @keyboard_tip values which are received in the signal handler, should be passed to this function without modification. The return value indicates whether there is a tree view row at the given coordinates (%TRUE) or not (%FALSE) for mouse tooltips. For keyboard tooltips the row returned will be the cursor row. When %TRUE, then any of @model, @path and @iter which have been provided will be set to point to that row and the corresponding model. @x and @y will always be converted to be relative to @tree_view’s bin_window if @keyboard_tooltip is %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead whether or not the given tooltip context points to a row a `GtkTreeView` the x coordinate (relative to widget coordinates) the y coordinate (relative to widget coordinates) whether this is a keyboard tooltip or not a pointer to receive a `GtkTreeModel` a pointer to receive a `GtkTreePath` a pointer to receive a `GtkTreeIter` Sets @start_path and @end_path to be the first and last visible path. Note that there may be invisible paths in between. The paths should be freed with gtk_tree_path_free() after use. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE, if valid paths were placed in @start_path and @end_path. A `GtkTreeView` Return location for start of region Return location for end of region Fills @visible_rect with the currently-visible region of the buffer, in tree coordinates. Convert to bin_window coordinates with gtk_tree_view_convert_tree_to_bin_window_coords(). Tree coordinates start at 0,0 for row 0 of the tree, and cover the entire scrollable area of the tree. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` rectangle to fill This inserts the @column into the @tree_view at @position. If @position is -1, then the column is inserted at the end. If @tree_view has “fixed_height” mode enabled, then @column must have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The number of columns in @tree_view after insertion. A `GtkTreeView`. The `GtkTreeViewColumn` to be inserted. The position to insert @column in. Creates a new `GtkTreeViewColumn` and inserts it into the @tree_view at @position. If @position is -1, then the newly created column is inserted at the end. The column is initialized with the attributes given. If @tree_view has “fixed_height” mode enabled, then the new column will have its sizing property set to be GTK_TREE_VIEW_COLUMN_FIXED. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The number of columns in @tree_view after insertion. A `GtkTreeView` The position to insert the new column in The title to set the header to The `GtkCellRenderer` A %NULL-terminated list of attributes Convenience function that inserts a new column into the `GtkTreeView` with the given cell renderer and a `GtkTreeCellDataFunc` to set cell renderer attributes (normally using data from the model). See also gtk_tree_view_column_set_cell_data_func(), gtk_tree_view_column_pack_start(). If @tree_view has “fixed_height” mode enabled, then the new column will have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead number of columns in the tree view post-insert a `GtkTreeView` Position to insert, -1 for append column title cell renderer for column function to set attributes of cell renderer data for @func destroy notifier for @data Determine whether the point (@x, @y) in @tree_view is blank, that is no cell content nor an expander arrow is drawn at the location. If so, the location can be considered as the background. You might wish to take special action on clicks on the background, such as clearing a current selection, having a custom context menu or starting rubber banding. The @x and @y coordinate that are provided must be relative to bin_window coordinates. Widget-relative coordinates must be converted using gtk_tree_view_convert_widget_to_bin_window_coords(). For converting widget coordinates (eg. the ones you get from GtkWidget::query-tooltip), please see gtk_tree_view_convert_widget_to_bin_window_coords(). The @path, @column, @cell_x and @cell_y arguments will be filled in likewise as for gtk_tree_view_get_path_at_pos(). Please see gtk_tree_view_get_path_at_pos() for more information. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if the area at the given coordinates is blank, %FALSE otherwise. A `GtkTreeView` The x position to be identified (relative to bin_window) The y position to be identified (relative to bin_window) A pointer to a `GtkTreePath` pointer to be filled in A pointer to a `GtkTreeViewColumn` pointer to be filled in A pointer where the X coordinate relative to the cell can be placed A pointer where the Y coordinate relative to the cell can be placed Returns whether a rubber banding operation is currently being done in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if a rubber banding operation is currently being done in @tree_view. a `GtkTreeView` Calls @func on all expanded rows. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` A function to be called User data to be passed to the function. Moves @column to be after to @base_column. If @base_column is %NULL, then @column is placed in the first position. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` The `GtkTreeViewColumn` to be moved. The `GtkTreeViewColumn` to be moved relative to Removes @column from @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The number of columns in @tree_view after removing. A `GtkTreeView`. The `GtkTreeViewColumn` to remove. Activates the cell determined by @path and @column. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` The `GtkTreePath` to be activated. The `GtkTreeViewColumn` to be activated. Returns %TRUE if the node pointed to by @path is expanded in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if #path is expanded. A `GtkTreeView`. A `GtkTreePath` to test expansion state. Moves the alignments of @tree_view to the position specified by @column and @path. If @column is %NULL, then no horizontal scrolling occurs. Likewise, if @path is %NULL no vertical scrolling occurs. At a minimum, one of @column or @path need to be non-%NULL. @row_align determines where the row is placed, and @col_align determines where @column is placed. Both are expected to be between 0.0 and 1.0. 0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 means center. If @use_align is %FALSE, then the alignment arguments are ignored, and the tree does the minimum amount of work to scroll the cell onto the screen. This means that the cell will be scrolled to the edge closest to its current position. If the cell is currently visible on the screen, nothing is done. This function only works if the model is set, and @path is a valid row on the model. If the model changes before the @tree_view is realized, the centered path will be modified to reflect this change. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. The path of the row to move to The `GtkTreeViewColumn` to move horizontally to whether to use alignment arguments, or %FALSE. The vertical alignment of the row specified by @path. The horizontal alignment of the column specified by @column. Scrolls the tree view such that the top-left corner of the visible area is @tree_x, @tree_y, where @tree_x and @tree_y are specified in tree coordinates. The @tree_view must be realized before this function is called. If it isn't, you probably want to be using gtk_tree_view_scroll_to_cell(). If either @tree_x or @tree_y are -1, then that direction isn’t scrolled. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` X coordinate of new top-left pixel of visible area, or -1 Y coordinate of new top-left pixel of visible area, or -1 Cause the `GtkTreeView`::row-activated signal to be emitted on a single click instead of a double click. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to emit row-activated on a single click Sets a user function for determining where a column may be dropped when dragged. This function is called on every column pair in turn at the beginning of a column drag to determine where a drop can take place. The arguments passed to @func are: the @tree_view, the `GtkTreeViewColumn` being dragged, the two `GtkTreeViewColumn`s determining the drop spot, and @user_data. If either of the `GtkTreeViewColumn` arguments for the drop spot are %NULL, then they indicate an edge. If @func is set to be %NULL, then @tree_view reverts to the default behavior of allowing all columns to be dropped everywhere. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. A function to determine which columns are reorderable User data to be passed to @func Destroy notifier for @user_data Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular row. If @focus_column is not %NULL, then focus is given to the column specified by it. Additionally, if @focus_column is specified, and @start_editing is %TRUE, then editing should be started in the specified cell. This function is often followed by @gtk_widget_grab_focus (@tree_view) in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized. If @path is invalid for @model, the current cursor (if any) will be unset and the function will return without failing. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` A `GtkTreePath` A `GtkTreeViewColumn` %TRUE if the specified cell should start being edited. Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular row. If @focus_column is not %NULL, then focus is given to the column specified by it. If @focus_column and @focus_cell are not %NULL, and @focus_column contains 2 or more editable or activatable cells, then focus is given to the cell specified by @focus_cell. Additionally, if @focus_column is specified, and @start_editing is %TRUE, then editing should be started in the specified cell. This function is often followed by @gtk_widget_grab_focus (@tree_view) in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized. If @path is invalid for @model, the current cursor (if any) will be unset and the function will return without failing. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` A `GtkTreePath` A `GtkTreeViewColumn` A `GtkCellRenderer` %TRUE if the specified cell should start being edited. Sets the row that is highlighted for feedback. If @path is %NULL, an existing highlight is removed. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` The path of the row to highlight Specifies whether to drop before, after or into the row If @enable_search is set, then the user can type in text to search through the tree interactively (this is sometimes called "typeahead find"). Note that even if this is %FALSE, the user can still initiate a search using the “start-interactive-search” key binding. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` %TRUE, if the user can search interactively Sets whether to draw lines interconnecting the expanders in @tree_view. This does not have any visible effects for lists. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to enable tree line drawing, %FALSE otherwise. Sets the column to draw the expander arrow at. It must be in @tree_view. If @column is %NULL, then the expander arrow is always at the first visible column. If you do not want expander arrow to appear in your tree, set the expander column to a hidden column. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` %NULL, or the column to draw the expander arrow at. Enables or disables the fixed height mode of @tree_view. Fixed height mode speeds up `GtkTreeView` by assuming that all rows have the same height. Only enable this option if all rows are the same height and all columns are of type %GTK_TREE_VIEW_COLUMN_FIXED. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to enable fixed height mode Sets which grid lines to draw in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` a `GtkTreeView`GridLines value indicating which grid lines to enable. Allow the column title buttons to be clicked. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. %TRUE if the columns are clickable. Sets the visibility state of the headers. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. %TRUE if the headers are visible Enables or disables the hover expansion mode of @tree_view. Hover expansion makes rows expand or collapse if the pointer moves over them. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to enable hover selection mode Enables or disables the hover selection mode of @tree_view. Hover selection makes the selected row follow the pointer. Currently, this works only for the selection modes %GTK_SELECTION_SINGLE and %GTK_SELECTION_BROWSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to enable hover selection mode Sets the amount of extra indentation for child levels to use in @tree_view in addition to the default indentation. The value should be specified in pixels, a value of 0 disables this feature and in this case only the default indentation will be used. This does not have any visible effects for lists. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` the amount, in pixels, of extra indentation in @tree_view. Sets the model for a `GtkTreeView`. If the @tree_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. The model. This function is a convenience function to allow you to reorder models that support the `GtkTreeDragSourceIface` and the `GtkTreeDragDestIface`. Both `GtkTreeStore` and `GtkListStore` support these. If @reorderable is %TRUE, then the user can reorder the model by dragging and dropping rows. The developer can listen to these changes by connecting to the model’s `GtkTreeModel::row-inserted` and `GtkTreeModel::row-deleted` signals. The reordering is implemented by setting up the tree view as a drag source and destination. Therefore, drag and drop can not be used in a reorderable view for any other purpose. This function does not give you any degree of control over the order -- any reordering is allowed. If more control is needed, you should probably handle drag and drop manually. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. %TRUE, if the tree can be reordered. Sets the row separator function, which is used to determine whether a row should be drawn as a separator. If the row separator function is %NULL, no separators are drawn. This is the default value. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` a `GtkTreeView`RowSeparatorFunc user data to pass to @func destroy notifier for @data Enables or disables rubber banding in @tree_view. If the selection mode is %GTK_SELECTION_MULTIPLE, rubber banding will allow the user to select multiple rows by dragging the mouse. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to enable rubber banding Sets @column as the column where the interactive search code should search in for the current model. If the search column is set, users can use the “start-interactive-search” key binding to bring up search popup. The enable-search property controls whether simply typing text will also start an interactive search. Note that @column refers to a column of the current model. The search column is reset to -1 when the model is changed. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` the column of the model to search in, or -1 to disable searching Sets the entry which the interactive search code will use for this @tree_view. This is useful when you want to provide a search entry in our interface at all time at a fixed position. Passing %NULL for @entry will make the interactive search code use the built-in popup entry again. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` the entry the interactive search code of @tree_view should use Sets the compare function for the interactive search capabilities; note that somewhat like strcmp() returning 0 for equality `GtkTreeView`SearchEqualFunc returns %FALSE on matches. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` the compare function to use during the search user data to pass to @search_equal_func Destroy notifier for @search_user_data Sets whether to draw and enable expanders and indent child rows in @tree_view. When disabled there will be no expanders visible in trees and there will be no way to expand and collapse rows by default. Also note that hiding the expanders will disable the default indentation. You can set a custom indentation in this case using gtk_tree_view_set_level_indentation(). This does not have any visible effects for lists. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to enable expander drawing, %FALSE otherwise. Sets the tip area of @tooltip to the area @path, @column and @cell have in common. For example if @path is %NULL and @column is set, the tip area will be set to the full area covered by @column. See also gtk_tooltip_set_tip_area(). Note that if @path is not specified and @cell is set and part of a column containing the expander, the tooltip might not show and hide at the correct position. In such cases @path must be set to the current node under the mouse cursor for this function to operate correctly. See also gtk_tree_view_set_tooltip_column() for a simpler alternative. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` a `GtkTooltip` a `GtkTreePath` a `GtkTreeViewColumn` a `GtkCellRenderer` If you only plan to have simple (text-only) tooltips on full rows, you can use this function to have `GtkTreeView` handle these automatically for you. @column should be set to the column in @tree_view’s model containing the tooltip texts, or -1 to disable this feature. When enabled, `GtkWidget:has-tooltip` will be set to %TRUE and @tree_view will connect a `GtkWidget::query-tooltip` signal handler. Note that the signal handler sets the text with gtk_tooltip_set_markup(), so &, <, etc have to be escaped in the text. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` an integer, which is a valid column number for @tree_view’s model Sets the tip area of @tooltip to be the area covered by the row at @path. See also gtk_tree_view_set_tooltip_column() for a simpler alternative. See also gtk_tooltip_set_tip_area(). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` a `GtkTooltip` a `GtkTreePath` Undoes the effect of gtk_tree_view_enable_model_drag_dest(). Calling this method sets `GtkTreeView`:reorderable to %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` Undoes the effect of gtk_tree_view_enable_model_drag_source(). Calling this method sets `GtkTreeView`:reorderable to %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` The activate-on-single-click property specifies whether the "row-activated" signal will be emitted after a single click. Setting the ::fixed-height-mode property to %TRUE speeds up `GtkTreeView` by assuming that all rows have the same height. Only enable this option if all rows are the same height. Please see gtk_tree_view_set_fixed_height_mode() for more information on this option. Enables or disables the hover expansion mode of @tree_view. Hover expansion makes rows expand or collapse if the pointer moves over them. This mode is primarily intended for treeviews in popups, e.g. in `GtkComboBox` or `GtkEntryCompletion`. Enables or disables the hover selection mode of @tree_view. Hover selection makes the selected row follow the pointer. Currently, this works only for the selection modes %GTK_SELECTION_SINGLE and %GTK_SELECTION_BROWSE. This mode is primarily intended for treeviews in popups, e.g. in `GtkComboBox` or `GtkEntryCompletion`. Extra indentation for each level. %TRUE if the view has expanders. The number of columns of the treeview has changed. The position of the cursor (focused cell) has changed. The `GtkTreeView`::move-cursor signal is a [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user presses one of the cursor keys. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. In contrast to gtk_tree_view_set_cursor() and gtk_tree_view_set_cursor_on_cell() when moving horizontally `GtkTreeView`::move-cursor does not reset the current selection. %TRUE if @step is supported, %FALSE otherwise. the granularity of the move, as a `GtkMovementStep`. %GTK_MOVEMENT_LOGICAL_POSITIONS, %GTK_MOVEMENT_VISUAL_POSITIONS, %GTK_MOVEMENT_DISPLAY_LINES, %GTK_MOVEMENT_PAGES and %GTK_MOVEMENT_BUFFER_ENDS are supported. %GTK_MOVEMENT_LOGICAL_POSITIONS and %GTK_MOVEMENT_VISUAL_POSITIONS are treated identically. the direction to move: +1 to move forwards; -1 to move backwards. The resulting movement is undefined for all other values. whether to extend the selection whether to modify the selection The "row-activated" signal is emitted when the method [method@Gtk.TreeView.row_activated] is called. This signal is emitted when the user double-clicks a treeview row with the [property@Gtk.TreeView:activate-on-single-click] property set to %FALSE, or when the user single-clicks a row when that property set to %TRUE. This signal is also emitted when a non-editable row is selected and one of the keys: <kbd>Space</kbd>, <kbd>Shift</kbd>+<kbd>Space</kbd>, <kbd>Return</kbd> or <kbd>Enter</kbd> is pressed. For selection handling refer to the [tree widget conceptual overview](section-tree-widget.html) as well as `GtkTreeSelection`. the `GtkTreePath` for the activated row the `GtkTreeViewColumn` in which the activation occurred The given row has been collapsed (child nodes are hidden). the tree iter of the collapsed row a tree path that points to the row The given row has been expanded (child nodes are shown). the tree iter of the expanded row a tree path that points to the row The given row is about to be collapsed (hide its children nodes). Use this signal if you need to control the collapsibility of individual rows. %FALSE to allow collapsing, %TRUE to reject the tree iter of the row to collapse a tree path that points to the row The given row is about to be expanded (show its children nodes). Use this signal if you need to control the expandability of individual rows. %FALSE to allow expansion, %TRUE to reject the tree iter of the row to expand a tree path that points to the row A `GtkTreeView` The `GtkTreePath` to be activated. The `GtkTreeViewColumn` to be activated. A visible column in a [class@Gtk.TreeView] widget The `GtkTreeViewColumn` object represents a visible column in a `GtkTreeView` widget. It allows to set properties of the column header, and functions as a holding pen for the cell renderers which determine how the data in the column is displayed. Please refer to the [tree widget conceptual overview](section-tree-widget.html) for an overview of all the objects and data types related to the tree widget and how they work together, and to the [class@Gtk.TreeView] documentation for specifics about the CSS node structure for treeviews and their headers. Use [class@Gtk.ColumnView] and [class@Gtk.ColumnViewColumn] instead of [class@Gtk.TreeView] to show a tabular list Creates a new `GtkTreeViewColumn`. Use GtkColumnView instead A newly created `GtkTreeViewColumn`. Creates a new `GtkTreeViewColumn` using @area to render its cells. Use GtkColumnView instead A newly created `GtkTreeViewColumn`. the `GtkCellArea` that the newly created column should use to layout cells. Creates a new `GtkTreeViewColumn` with a number of default values. This is equivalent to calling gtk_tree_view_column_set_title(), gtk_tree_view_column_pack_start(), and gtk_tree_view_column_set_attributes() on the newly created `GtkTreeViewColumn`. Here’s a simple example: ```c enum { TEXT_COLUMN, COLOR_COLUMN, N_COLUMNS }; // ... { GtkTreeViewColumn *column; GtkCellRenderer *renderer = gtk_cell_renderer_text_new (); column = gtk_tree_view_column_new_with_attributes ("Title", renderer, "text", TEXT_COLUMN, "foreground", COLOR_COLUMN, NULL); } ``` Use GtkColumnView instead A newly created `GtkTreeViewColumn`. The title to set the header to The `GtkCellRenderer` A %NULL-terminated list of attributes Adds an attribute mapping to the list in @tree_column. The @column is the column of the model to get a value from, and the @attribute is the parameter on @cell_renderer to be set from the value. So for example if column 2 of the model contains strings, you could have the “text” attribute of a `GtkCellRendererText` get its values from column 2. Use GtkColumnView instead A `GtkTreeViewColumn` the `GtkCellRenderer` to set attributes on An attribute on the renderer The column position on the model to get the attribute from. Obtains the horizontal position and size of a cell in a column. If the cell is not found in the column, @start_pos and @width are not changed and %FALSE is returned. Use GtkColumnView instead %TRUE if @cell belongs to @tree_column a `GtkTreeViewColumn` a `GtkCellRenderer` return location for the horizontal position of @cell within @tree_column return location for the width of @cell Obtains the width and height needed to render the column. This is used primarily by the `GtkTreeView`. Use GtkColumnView instead A `GtkTreeViewColumn`. location to return x offset of a cell relative to @cell_area location to return y offset of a cell relative to @cell_area location to return width needed to render a cell location to return height needed to render a cell Returns %TRUE if any of the cells packed into the @tree_column are visible. For this to be meaningful, you must first initialize the cells with gtk_tree_view_column_cell_set_cell_data() Use GtkColumnView instead %TRUE, if any of the cells packed into the @tree_column are currently visible A `GtkTreeViewColumn` Sets the cell renderer based on the @tree_model and @iter. That is, for every attribute mapping in @tree_column, it will get a value from the set column on the @iter, and use that value to set the attribute on the cell renderer. This is used primarily by the `GtkTreeView`. Use GtkColumnView instead A `GtkTreeViewColumn`. The `GtkTreeModel` to get the cell renderers attributes from. The `GtkTreeIter` to get the cell renderer’s attributes from. %TRUE, if the row has children %TRUE, if the row has visible children Unsets all the mappings on all renderers on the @tree_column. Use GtkColumnView instead A `GtkTreeViewColumn` Clears all existing attributes previously set with gtk_tree_view_column_set_attributes(). Use GtkColumnView instead a `GtkTreeViewColumn` a `GtkCellRenderer` to clear the attribute mapping on. Emits the “clicked” signal on the column. This function will only work if @tree_column is clickable. Use GtkColumnView instead a `GtkTreeViewColumn` Sets the current keyboard focus to be at @cell, if the column contains 2 or more editable and activatable cells. Use GtkColumnView instead A `GtkTreeViewColumn` A `GtkCellRenderer` Returns the current x alignment of @tree_column. This value can range between 0.0 and 1.0. Use GtkColumnView instead The current alignent of @tree_column. A `GtkTreeViewColumn`. Returns the button used in the treeview column header Use GtkColumnView instead The button for the column header. A `GtkTreeViewColumn` Returns %TRUE if the user can click on the header for the column. Use GtkColumnView instead %TRUE if user can click the column header. a `GtkTreeViewColumn` Returns %TRUE if the column expands to fill available space. Use GtkColumnView instead %TRUE if the column expands to fill available space. A `GtkTreeViewColumn`. Gets the fixed width of the column. This may not be the actual displayed width of the column; for that, use gtk_tree_view_column_get_width(). Use GtkColumnView instead The fixed width of the column. A `GtkTreeViewColumn`. Returns the maximum width in pixels of the @tree_column, or -1 if no maximum width is set. Use GtkColumnView instead The maximum width of the @tree_column. A `GtkTreeViewColumn`. Returns the minimum width in pixels of the @tree_column, or -1 if no minimum width is set. Use GtkColumnView instead The minimum width of the @tree_column. A `GtkTreeViewColumn`. Returns %TRUE if the @tree_column can be reordered by the user. Use GtkColumnView instead %TRUE if the @tree_column can be reordered by the user. A `GtkTreeViewColumn` Returns %TRUE if the @tree_column can be resized by the end user. Use GtkColumnView instead %TRUE, if the @tree_column can be resized. A `GtkTreeViewColumn` Returns the current type of @tree_column. Use GtkColumnView instead The type of @tree_column. A `GtkTreeViewColumn`. Gets the logical @sort_column_id that the model sorts on when this column is selected for sorting. See [method@Gtk.TreeViewColumn.set_sort_column_id]. Use GtkColumnView instead the current @sort_column_id for this column, or -1 if this column can’t be used for sorting a `GtkTreeViewColumn` Gets the value set by gtk_tree_view_column_set_sort_indicator(). Use GtkColumnView instead whether the sort indicator arrow is displayed a `GtkTreeViewColumn` Gets the value set by gtk_tree_view_column_set_sort_order(). Use GtkColumnView instead the sort order the sort indicator is indicating a `GtkTreeViewColumn` Returns the spacing of @tree_column. Use GtkColumnView instead the spacing of @tree_column. A `GtkTreeViewColumn`. Returns the title of the widget. Use GtkColumnView instead the title of the column. This string should not be modified or freed. A `GtkTreeViewColumn`. Returns the `GtkTreeView` wherein @tree_column has been inserted. If @column is currently not inserted in any tree view, %NULL is returned. Use GtkColumnView instead The tree view wherein @column has been inserted A `GtkTreeViewColumn` Returns %TRUE if @tree_column is visible. Use GtkColumnView instead whether the column is visible or not. If it is visible, then the tree will show the column. A `GtkTreeViewColumn`. Returns the `GtkWidget` in the button on the column header. If a custom widget has not been set then %NULL is returned. Use GtkColumnView instead The `GtkWidget` in the column header A `GtkTreeViewColumn` Returns the current size of @tree_column in pixels. Use GtkColumnView instead The current width of @tree_column. A `GtkTreeViewColumn`. Returns the current X offset of @tree_column in pixels. Use GtkColumnView instead The current X offset of @tree_column. A `GtkTreeViewColumn`. Adds the @cell to end of the column. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Use GtkColumnView instead A `GtkTreeViewColumn`. The `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @tree_column. Packs the @cell into the beginning of the column. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Use GtkColumnView instead A `GtkTreeViewColumn`. The `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @tree_column. Flags the column, and the cell renderers added to this column, to have their sizes renegotiated. Use GtkColumnView instead A `GtkTreeViewColumn` Sets the alignment of the title or custom widget inside the column header. The alignment determines its location inside the button -- 0.0 for left, 0.5 for center, 1.0 for right. Use GtkColumnView instead A `GtkTreeViewColumn`. The alignment, which is between [0.0 and 1.0] inclusive. Sets the attributes in the list as the attributes of @tree_column. The attributes should be in attribute/column order, as in gtk_tree_view_column_add_attribute(). All existing attributes are removed, and replaced with the new attributes. Use GtkColumnView instead A `GtkTreeViewColumn` the `GtkCellRenderer` we’re setting the attributes of A %NULL-terminated list of attributes Sets the `GtkTreeCellDataFunc` to use for the column. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of @tree_column's cell renderer as appropriate. @func may be %NULL to remove an older one. Use GtkColumnView instead A `GtkTreeViewColumn` A `GtkCellRenderer` The `GtkTreeCellDataFunc` to use. The user data for @func. The destroy notification for @func_data Sets the header to be active if @clickable is %TRUE. When the header is active, then it can take keyboard focus, and can be clicked. Use GtkColumnView instead A `GtkTreeViewColumn`. %TRUE if the header is active. Sets the column to take available extra space. This space is shared equally amongst all columns that have the expand set to %TRUE. If no column has this option set, then the last column gets all extra space. By default, every column is created with this %FALSE. Along with “fixed-width”, the “expand” property changes when the column is resized by the user. Use GtkColumnView instead A `GtkTreeViewColumn`. %TRUE if the column should expand to fill available space. If @fixed_width is not -1, sets the fixed width of @tree_column; otherwise unsets it. The effective value of @fixed_width is clamped between the minimum and maximum width of the column; however, the value stored in the “fixed-width” property is not clamped. If the column sizing is %GTK_TREE_VIEW_COLUMN_GROW_ONLY or %GTK_TREE_VIEW_COLUMN_AUTOSIZE, setting a fixed width overrides the automatically calculated width. Note that @fixed_width is only a hint to GTK; the width actually allocated to the column may be greater or less than requested. Along with “expand”, the “fixed-width” property changes when the column is resized by the user. Use GtkColumnView instead A `GtkTreeViewColumn`. The new fixed width, in pixels, or -1. Sets the maximum width of the @tree_column. If @max_width is -1, then the maximum width is unset. Note, the column can actually be wider than max width if it’s the last column in a view. In this case, the column expands to fill any extra space. Use GtkColumnView instead A `GtkTreeViewColumn`. The maximum width of the column in pixels, or -1. Sets the minimum width of the @tree_column. If @min_width is -1, then the minimum width is unset. Use GtkColumnView instead A `GtkTreeViewColumn`. The minimum width of the column in pixels, or -1. If @reorderable is %TRUE, then the column can be reordered by the end user dragging the header. Use GtkColumnView instead A `GtkTreeViewColumn` %TRUE, if the column can be reordered. If @resizable is %TRUE, then the user can explicitly resize the column by grabbing the outer edge of the column button. If resizable is %TRUE and sizing mode of the column is %GTK_TREE_VIEW_COLUMN_AUTOSIZE, then the sizing mode is changed to %GTK_TREE_VIEW_COLUMN_GROW_ONLY. Use GtkColumnView instead A `GtkTreeViewColumn` %TRUE, if the column can be resized Sets the growth behavior of @tree_column to @type. Use GtkColumnView instead A `GtkTreeViewColumn`. The `GtkTreeViewColumn`Sizing. Sets the logical @sort_column_id that this column sorts on when this column is selected for sorting. Doing so makes the column header clickable. Use GtkColumnView instead a `GtkTreeViewColumn` The @sort_column_id of the model to sort on. Call this function with a @setting of %TRUE to display an arrow in the header button indicating the column is sorted. Call gtk_tree_view_column_set_sort_order() to change the direction of the arrow. Use GtkColumnView instead a `GtkTreeViewColumn` %TRUE to display an indicator that the column is sorted Changes the appearance of the sort indicator. This does not actually sort the model. Use gtk_tree_view_column_set_sort_column_id() if you want automatic sorting support. This function is primarily for custom sorting behavior, and should be used in conjunction with gtk_tree_sortable_set_sort_column_id() to do that. For custom models, the mechanism will vary. The sort indicator changes direction to indicate normal sort or reverse sort. Note that you must have the sort indicator enabled to see anything when calling this function; see gtk_tree_view_column_set_sort_indicator(). Use GtkColumnView instead a `GtkTreeViewColumn` sort order that the sort indicator should indicate Sets the spacing field of @tree_column, which is the number of pixels to place between cell renderers packed into it. Use GtkColumnView instead A `GtkTreeViewColumn`. distance between cell renderers in pixels. Sets the title of the @tree_column. If a custom widget has been set, then this value is ignored. Use GtkColumnView instead A `GtkTreeViewColumn`. The title of the @tree_column. Sets the visibility of @tree_column. Use GtkColumnView instead A `GtkTreeViewColumn`. %TRUE if the @tree_column is visible. Sets the widget in the header to be @widget. If widget is %NULL, then the header button is set with a `GtkLabel` set to the title of @tree_column. Use GtkColumnView instead A `GtkTreeViewColumn`. A child `GtkWidget` The `GtkCellArea` used to layout cell renderers for this column. If no area is specified when creating the tree view column with gtk_tree_view_column_new_with_area() a horizontally oriented `GtkCellAreaBox` will be used. Logical sort column ID this column sorts on when selected for sorting. Setting the sort column ID makes the column header clickable. Set to -1 to make the column unsortable. Emitted when the column's header has been clicked. Function type for determining whether @column can be dropped in a particular spot (as determined by @prev_column and @next_column). In left to right locales, @prev_column is on the left of the potential drop spot, and @next_column is on the right. In right to left mode, this is reversed. This function should return %TRUE if the spot is a valid drop spot. Please note that returning %TRUE does not actually indicate that the column drop was made, but is meant only to indicate a possible drop spot to the user. There is no replacement. %TRUE, if @column can be dropped in this spot A `GtkTreeView` The `GtkTreeViewColumn` being dragged A `GtkTreeViewColumn` on one side of @column A `GtkTreeViewColumn` on the other side of @column user data The sizing method the column uses to determine its width. Please note that %GTK_TREE_VIEW_COLUMN_AUTOSIZE are inefficient for large views, and can make columns appear choppy. There is no replacement. Columns only get bigger in reaction to changes in the model Columns resize to be the optimal size every time the model changes. Columns are a fixed numbers of pixels wide. An enum for determining where a dropped row goes. There is no replacement. dropped row is inserted before dropped row is inserted after dropped row becomes a child or is inserted before dropped row becomes a child or is inserted after Used to indicate which grid lines to draw in a tree view. There is no replacement No grid lines. Horizontal grid lines. Vertical grid lines. Horizontal and vertical grid lines. Function used for gtk_tree_view_map_expanded_rows(). There is no replacement. A `GtkTreeView` The path that’s expanded user data Function type for determining whether the row pointed to by @iter should be rendered as a separator. A common way to implement this is to have a boolean column in the model, whose values the `GtkTreeViewRowSeparatorFunc` returns. There is no replacement. %TRUE if the row is a separator the `GtkTreeModel` a `GtkTreeIter` pointing at a row in @model user data A function used for checking whether a row in @model matches a search key string entered by the user. Note the return value is reversed from what you would normally expect, though it has some similarity to strcmp() returning 0 for equal strings. There is no replacement. %FALSE if the row matches, %TRUE otherwise. the `GtkTreeModel` being searched the search column set by gtk_tree_view_set_search_column() the key string to compare with a `GtkTreeIter` pointing the row of @model that should be compared with @key. user data from gtk_tree_view_set_search_equal_func() A `GtkExpression` that tries to evaluate each of its expressions until it succeeds. If all expressions fail to evaluate, the `GtkTryExpression`'s evaluation fails as well. Creates a `GtkExpression` with an array of expressions. When evaluated, the `GtkTryExpression` tries to evaluate each of its expressions until it succeeds. If all expressions fail to evaluate, the `GtkTryExpression`'s evaluation fails as well. The value type of the expressions in the array must match. a new `GtkExpression` The number of expressions The array of expressions See also gtk_print_settings_set_paper_width(). No units. Dimensions in points. Dimensions in inches. Dimensions in millimeters Asynchronous API to open a uri with an application. `GtkUriLauncher` collects the arguments that are needed to open the uri. Depending on system configuration, user preferences and available APIs, this may or may not show an app chooser dialog or launch the default application right away. The operation is started with the [method@Gtk.UriLauncher.launch] function. To launch a file, use [class@Gtk.FileLauncher]. Creates a new `GtkUriLauncher` object. the new `GtkUriLauncher` the uri to open Returns whether the launcher is likely to succeed in launching an application for its uri. This can be used to disable controls that trigger the launcher when they are known not to work. false if the launcher is known not to support the uri, true otherwise an uri launcher the parent window Gets the uri that will be opened. the uri an uri launcher Launches an application to open the uri. This may present an app chooser dialog to the user. an uri launcher the parent window a cancellable to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.UriLauncher.launch] call and returns the result. true if an application was launched an uri launcher the result Sets the uri that will be opened. an uri launcher the uri The uri to launch. Evaluates to true if @value was initialized with `GTK_TYPE_EXPRESSION` a `GValue` Shows a `GtkMediaStream` with media controls. <picture> <source srcset="video-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkVideo" src="video.png"> </picture> The controls are available separately as [class@Gtk.MediaControls]. If you just want to display a video without controls, you can treat it like any other paintable and for example put it into a [class@Gtk.Picture]. `GtkVideo` aims to cover use cases such as previews, embedded animations, etc. It supports autoplay, looping, and simple media controls. It does not have support for video overlays, multichannel audio, device selection, or input. If you are writing a full-fledged video player, you may want to use the [iface@Gdk.Paintable] API and a media framework such as Gstreamer directly. Creates a new empty `GtkVideo`. a new `GtkVideo` Creates a `GtkVideo` to play back the given @file. a new `GtkVideo` a `GFile` Creates a `GtkVideo` to play back the given @filename. This is a utility function that calls [ctor@Gtk.Video.new_for_file], See that function for details. a new `GtkVideo` filename to play back Creates a `GtkVideo` to play back the given @stream. a new `GtkVideo` a `GtkMediaStream` Creates a `GtkVideo` to play back the resource at the given @resource_path. This is a utility function that calls [ctor@Gtk.Video.new_for_file]. a new `GtkVideo` resource path to play back Returns %TRUE if videos have been set to loop. %TRUE if streams should autoplay a `GtkVideo` Gets the file played by @self or %NULL if not playing back a file. The file played by @self a `GtkVideo` Returns whether graphics offload is enabled. See [class@Gtk.GraphicsOffload] for more information on graphics offload. the graphics offload status a `GtkVideo` Returns %TRUE if videos have been set to loop. %TRUE if streams should loop a `GtkVideo` Gets the media stream managed by @self or %NULL if none. The media stream managed by @self a `GtkVideo` Sets whether @self automatically starts playback when it becomes visible or when a new file gets loaded. a `GtkVideo` whether media streams should autoplay Makes @self play the given @file. a `GtkVideo` the file to play Makes @self play the given @filename. This is a utility function that calls gtk_video_set_file(), a `GtkVideo` the filename to play Sets whether to enable graphics offload. See [class@Gtk.GraphicsOffload] for more information on graphics offload. a `GtkVideo` the new graphics offload status Sets whether new files loaded by @self should be set to loop. a `GtkVideo` whether media streams should loop Sets the media stream to be played back. @self will take full control of managing the media stream. If you want to manage a media stream yourself, consider using a [class@Gtk.Picture] for display. If you want to display a file, consider using [method@Gtk.Video.set_file] instead. a `GtkVideo` The media stream to play or %NULL to unset Makes @self play the resource at the given @resource_path. This is a utility function that calls [method@Gtk.Video.set_file]. a `GtkVideo` the resource to set If the video should automatically begin playing. The file played by this video if the video is playing a file. Whether to enable graphics offload. If new media files should be set to loop. The media-stream played Implements scrollability for widgets that don't support scrolling on their own. Use `GtkViewport` to scroll child widgets such as `GtkGrid`, `GtkBox`, and so on. The `GtkViewport` will start scrolling content only if allocated less than the child widget’s minimum size in a given orientation. # CSS nodes `GtkViewport` has a single CSS node with name `viewport`. # Accessibility Until GTK 4.10, `GtkViewport` used the [enum@Gtk.AccessibleRole.group] role. Starting from GTK 4.12, `GtkViewport` uses the [enum@Gtk.AccessibleRole.generic] role. Creates a new `GtkViewport`. The new viewport uses the given adjustments, or default adjustments if none are given. a new `GtkViewport` horizontal adjustment vertical adjustment Gets the child widget of @viewport. the child widget of @viewport a `GtkViewport` Gets whether the viewport is scrolling to keep the focused child in view. %TRUE if the viewport keeps the focus child scrolled to view a `GtkViewport` Scrolls a descendant of the viewport into view. The viewport and the descendant must be visible and mapped for this function to work, otherwise no scrolling will be performed. a `GtkViewport` a descendant widget of the viewport details of how to perform the scroll operation or NULL to scroll into view Sets the child widget of @viewport. a `GtkViewport` the child widget Sets whether the viewport should automatically scroll to keep the focused child in view. a `GtkViewport` whether to keep the focus widget scrolled to view The child widget. Whether to scroll when the focus changes. Before 4.6.2, this property was mistakenly defaulting to FALSE, so if your code needs to work with older versions, consider setting it explicitly to TRUE. `GtkVolumeButton` is a `GtkScaleButton` subclass tailored for volume control. <picture> <source srcset="volumebutton-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkVolumeButton" src="volumebutton.png"> </picture> This widget will be removed in GTK 5 Creates a `GtkVolumeButton`. The button has a range between 0.0 and 1.0, with a stepping of 0.02. Volume values can be obtained and modified using the functions from [class@Gtk.ScaleButton]. This widget will be removed in GTK 5 a new `GtkVolumeButton` Whether to use symbolic icons as the icons. Note that if the symbolic icons are not available in your installed theme, then the normal (potentially colorful) icons will be used. This widget will be removed in GTK 5 The base class for all widgets. It manages the widget lifecycle, layout, states and style. ### Height-for-width Geometry Management GTK uses a height-for-width (and width-for-height) geometry management system. Height-for-width means that a widget can change how much vertical space it needs, depending on the amount of horizontal space that it is given (and similar for width-for-height). The most common example is a label that reflows to fill up the available width, wraps to fewer lines, and therefore needs less height. Height-for-width geometry management is implemented in GTK by way of two virtual methods: - [vfunc@Gtk.Widget.get_request_mode] - [vfunc@Gtk.Widget.measure] There are some important things to keep in mind when implementing height-for-width and when using it in widget implementations. If you implement a direct `GtkWidget` subclass that supports height-for-width or width-for-height geometry management for itself or its child widgets, the [vfunc@Gtk.Widget.get_request_mode] virtual function must be implemented as well and return the widget's preferred request mode. The default implementation of this virtual function returns %GTK_SIZE_REQUEST_CONSTANT_SIZE, which means that the widget will only ever get -1 passed as the for_size value to its [vfunc@Gtk.Widget.measure] implementation. The geometry management system will query a widget hierarchy in only one orientation at a time. When widgets are initially queried for their minimum sizes it is generally done in two initial passes in the [enum@Gtk.SizeRequestMode] chosen by the toplevel. For example, when queried in the normal %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH mode: First, the default minimum and natural width for each widget in the interface will be computed using [method@Gtk.Widget.measure] with an orientation of %GTK_ORIENTATION_HORIZONTAL and a for_size of -1. Because the preferred widths for each widget depend on the preferred widths of their children, this information propagates up the hierarchy, and finally a minimum and natural width is determined for the entire toplevel. Next, the toplevel will use the minimum width to query for the minimum height contextual to that width using [method@Gtk.Widget.measure] with an orientation of %GTK_ORIENTATION_VERTICAL and a for_size of the just computed width. This will also be a highly recursive operation. The minimum height for the minimum width is normally used to set the minimum size constraint on the toplevel. After the toplevel window has initially requested its size in both dimensions it can go on to allocate itself a reasonable size (or a size previously specified with [method@Gtk.Window.set_default_size]). During the recursive allocation process it’s important to note that request cycles will be recursively executed while widgets allocate their children. Each widget, once allocated a size, will go on to first share the space in one orientation among its children and then request each child's height for its target allocated width or its width for allocated height, depending. In this way a widget will typically be requested its size a number of times before actually being allocated a size. The size a widget is finally allocated can of course differ from the size it has requested. For this reason, `GtkWidget` caches a small number of results to avoid re-querying for the same sizes in one allocation cycle. If a widget does move content around to intelligently use up the allocated size then it must support the request in both `GtkSizeRequestMode`s even if the widget in question only trades sizes in a single orientation. For instance, a [class@Gtk.Label] that does height-for-width word wrapping will not expect to have [vfunc@Gtk.Widget.measure] with an orientation of %GTK_ORIENTATION_VERTICAL called because that call is specific to a width-for-height request. In this case the label must return the height required for its own minimum possible width. By following this rule any widget that handles height-for-width or width-for-height requests will always be allocated at least enough space to fit its own content. Here are some examples of how a %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH widget generally deals with width-for-height requests: ```c static void foo_widget_measure (GtkWidget *widget, GtkOrientation orientation, int for_size, int *minimum_size, int *natural_size, int *minimum_baseline, int *natural_baseline) { if (orientation == GTK_ORIENTATION_HORIZONTAL) { // Calculate minimum and natural width } else // VERTICAL { if (i_am_in_height_for_width_mode) { int min_width, dummy; // First, get the minimum width of our widget GTK_WIDGET_GET_CLASS (widget)->measure (widget, GTK_ORIENTATION_HORIZONTAL, -1, &min_width, &dummy, &dummy, &dummy); // Now use the minimum width to retrieve the minimum and natural height to display // that width. GTK_WIDGET_GET_CLASS (widget)->measure (widget, GTK_ORIENTATION_VERTICAL, min_width, minimum_size, natural_size, &dummy, &dummy); } else { // ... some widgets do both. } } } ``` Often a widget needs to get its own request during size request or allocation. For example, when computing height it may need to also compute width. Or when deciding how to use an allocation, the widget may need to know its natural size. In these cases, the widget should be careful to call its virtual methods directly, like in the code example above. It will not work to use the wrapper function [method@Gtk.Widget.measure] inside your own [vfunc@Gtk.Widget.size_allocate] implementation. These return a request adjusted by [class@Gtk.SizeGroup], the widget's align and expand flags, as well as its CSS style. If a widget used the wrappers inside its virtual method implementations, then the adjustments (such as widget margins) would be applied twice. GTK therefore does not allow this and will warn if you try to do it. Of course if you are getting the size request for another widget, such as a child widget, you must use [method@Gtk.Widget.measure]; otherwise, you would not properly consider widget margins, [class@Gtk.SizeGroup], and so forth. GTK also supports baseline vertical alignment of widgets. This means that widgets are positioned such that the typographical baseline of widgets in the same row are aligned. This happens if a widget supports baselines, has a vertical alignment using baselines, and is inside a widget that supports baselines and has a natural “row” that it aligns to the baseline, or a baseline assigned to it by the grandparent. Baseline alignment support for a widget is also done by the [vfunc@Gtk.Widget.measure] virtual function. It allows you to report both a minimum and natural size. If a widget ends up baseline aligned it will be allocated all the space in the parent as if it was %GTK_ALIGN_FILL, but the selected baseline can be found via [method@Gtk.Widget.get_baseline]. If the baseline has a value other than -1 you need to align the widget such that the baseline appears at the position. ### GtkWidget as GtkBuildable The `GtkWidget` implementation of the `GtkBuildable` interface supports various custom elements to specify additional aspects of widgets that are not directly expressed as properties. If the widget uses a [class@Gtk.LayoutManager], `GtkWidget` supports a custom `<layout>` element, used to define layout properties: ```xml <object class="GtkGrid" id="my_grid"> <child> <object class="GtkLabel" id="label1"> <property name="label">Description</property> <layout> <property name="column">0</property> <property name="row">0</property> <property name="row-span">1</property> <property name="column-span">1</property> </layout> </object> </child> <child> <object class="GtkEntry" id="description_entry"> <layout> <property name="column">1</property> <property name="row">0</property> <property name="row-span">1</property> <property name="column-span">1</property> </layout> </object> </child> </object> ``` `GtkWidget` allows style information such as style classes to be associated with widgets, using the custom `<style>` element: ```xml <object class="GtkButton" id="button1"> <style> <class name="my-special-button-class"/> <class name="dark-button"/> </style> </object> ``` `GtkWidget` allows defining accessibility information, such as properties, relations, and states, using the custom `<accessibility>` element: ```xml <object class="GtkButton" id="button1"> <accessibility> <property name="label">Download</property> <relation name="labelled-by">label1</relation> </accessibility> </object> ``` ### Building composite widgets from template XML `GtkWidget `exposes some facilities to automate the procedure of creating composite widgets using "templates". To create composite widgets with `GtkBuilder` XML, one must associate the interface description with the widget class at class initialization time using [method@Gtk.WidgetClass.set_template]. The interface description semantics expected in composite template descriptions is slightly different from regular [class@Gtk.Builder] XML. Unlike regular interface descriptions, [method@Gtk.WidgetClass.set_template] will expect a `<template>` tag as a direct child of the toplevel `<interface>` tag. The `<template>` tag must specify the “class” attribute which must be the type name of the widget. Optionally, the “parent” attribute may be specified to specify the direct parent type of the widget type; this is ignored by `GtkBuilder` but can be used by UI design tools to introspect what kind of properties and internal children exist for a given type when the actual type does not exist. The XML which is contained inside the `<template>` tag behaves as if it were added to the `<object>` tag defining the widget itself. You may set properties on a widget by inserting `<property>` tags into the `<template>` tag, and also add `<child>` tags to add children and extend a widget in the normal way you would with `<object>` tags. Additionally, `<object>` tags can also be added before and after the initial `<template>` tag in the normal way, allowing one to define auxiliary objects which might be referenced by other widgets declared as children of the `<template>` tag. Since, unlike the `<object>` tag, the `<template>` tag does not contain an “id” attribute, if you need to refer to the instance of the object itself that the template will create, simply refer to the template class name in an applicable element content. Here is an example of a template definition, which includes an example of this in the `<signal>` tag: ```xml <interface> <template class="FooWidget" parent="GtkBox"> <property name="orientation">horizontal</property> <property name="spacing">4</property> <child> <object class="GtkButton" id="hello_button"> <property name="label">Hello World</property> <signal name="clicked" handler="hello_button_clicked" object="FooWidget" swapped="yes"/> </object> </child> <child> <object class="GtkButton" id="goodbye_button"> <property name="label">Goodbye World</property> </object> </child> </template> </interface> ``` Typically, you'll place the template fragment into a file that is bundled with your project, using `GResource`. In order to load the template, you need to call [method@Gtk.WidgetClass.set_template_from_resource] from the class initialization of your `GtkWidget` type: ```c static void foo_widget_class_init (FooWidgetClass *klass) { // ... gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass), "/com/example/ui/foowidget.ui"); } ``` You will also need to call [method@Gtk.Widget.init_template] from the instance initialization function: ```c static void foo_widget_init (FooWidget *self) { gtk_widget_init_template (GTK_WIDGET (self)); // Initialize the rest of the widget... } ``` as well as calling [method@Gtk.Widget.dispose_template] from the dispose function: ```c static void foo_widget_dispose (GObject *gobject) { FooWidget *self = FOO_WIDGET (gobject); // Dispose objects for which you have a reference... // Clear the template children for this widget type gtk_widget_dispose_template (GTK_WIDGET (self), FOO_TYPE_WIDGET); G_OBJECT_CLASS (foo_widget_parent_class)->dispose (gobject); } ``` You can access widgets defined in the template using the [method@Gtk.Widget.get_template_child] function, but you will typically declare a pointer in the instance private data structure of your type using the same name as the widget in the template definition, and call [method@Gtk.WidgetClass.bind_template_child_full] (or one of its wrapper macros [func@Gtk.widget_class_bind_template_child] and [func@Gtk.widget_class_bind_template_child_private]) with that name, e.g. ```c typedef struct { GtkWidget *hello_button; GtkWidget *goodbye_button; } FooWidgetPrivate; G_DEFINE_TYPE_WITH_PRIVATE (FooWidget, foo_widget, GTK_TYPE_BOX) static void foo_widget_dispose (GObject *gobject) { gtk_widget_dispose_template (GTK_WIDGET (gobject), FOO_TYPE_WIDGET); G_OBJECT_CLASS (foo_widget_parent_class)->dispose (gobject); } static void foo_widget_class_init (FooWidgetClass *klass) { // ... G_OBJECT_CLASS (klass)->dispose = foo_widget_dispose; gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass), "/com/example/ui/foowidget.ui"); gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (klass), FooWidget, hello_button); gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (klass), FooWidget, goodbye_button); } static void foo_widget_init (FooWidget *widget) { gtk_widget_init_template (GTK_WIDGET (widget)); } ``` You can also use [method@Gtk.WidgetClass.bind_template_callback_full] (or is wrapper macro [func@Gtk.widget_class_bind_template_callback]) to connect a signal callback defined in the template with a function visible in the scope of the class, e.g. ```c // the signal handler has the instance and user data swapped // because of the swapped="yes" attribute in the template XML static void hello_button_clicked (FooWidget *self, GtkButton *button) { g_print ("Hello, world!\n"); } static void foo_widget_class_init (FooWidgetClass *klass) { // ... gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass), "/com/example/ui/foowidget.ui"); gtk_widget_class_bind_template_callback (GTK_WIDGET_CLASS (klass), hello_button_clicked); } ``` Obtains the default reading direction. See [func@Gtk.Widget.set_default_direction]. the current default direction Sets the default reading direction for widgets. See [method@Gtk.Widget.set_direction]. the new default direction, either [enum@Gtk.TextDirection.ltr] or [enum@Gtk.TextDirection.rtl] Computes whether a container should give this widget extra space when possible. Tests if a given point is contained in the widget. The coordinates for (x, y) must be in widget coordinates, so (0, 0) is assumed to be the top left of @widget's content area. true if @widget contains the point (x, y) the widget to query X coordinate to test, relative to @widget's origin Y coordinate to test, relative to @widget's origin Vfunc called when the CSS used by widget was changed. Widgets should then discard their caches that depend on CSS and queue resizes or redraws accordingly. The default implementation will take care of this for all the default CSS properties, so implementations must chain up. Signal emitted when the text direction of a widget changes. Vfunc for gtk_widget_child_focus() Gets whether the widget prefers a height-for-width layout or a width-for-height layout. Single-child widgets generally propagate the preference of their child, more complex widgets need to request something either in context of their children or in context of their allocation capabilities. The `GtkSizeRequestMode` preferred by @widget. a `GtkWidget` instance Causes @widget to have the keyboard focus for the window that it belongs to. If @widget is not focusable, or its [vfunc@Gtk.Widget.grab_focus] implementation cannot transfer the focus to a descendant of @widget that is focusable, it will not take focus and false will be returned. Calling [method@Gtk.Widget.grab_focus] on an already focused widget is allowed, should not have an effect, and return true. true if focus is now inside @widget a widget Reverses the effects of [method.Gtk.Widget.show]. This is causing the widget to be hidden (invisible to the user). Use [method@Gtk.Widget.set_visible] instead a widget Emits the [signal@Gtk.Widget::keynav-failed] signal on the widget. This function should be called whenever keyboard navigation within a single widget hits a boundary. The return value of this function should be interpreted in a way similar to the return value of [method@Gtk.Widget.child_focus]. When true is returned, stay in the widget, the failed keyboard navigation is ok and/or there is nowhere we can/should move the focus to. When false is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling [method@Gtk.Widget.child_focus] on the widget’s toplevel. The default [signal@Gtk.Widget::keynav-failed] handler returns false for [enum@Gtk.DirectionType.tab-forward] and [enum@Gtk.DirectionType.tab-backward]. For the other values of [enum@Gtk.DirectionType] it returns true. Whenever the default handler returns true, it also calls [method@Gtk.Widget.error_bell] to notify the user of the failed keyboard navigation. A use case for providing an own implementation of `::keynav-failed` (either by connecting to it or by overriding it) would be a row of [class@Gtk.Entry] widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys. true if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard navigation attempt in its parent widget a widget direction of focus movement Causes a widget to be mapped if it isn’t already. This function is only for use in widget implementations. a widget Measures @widget in the orientation @orientation and for the given @for_size. As an example, if @orientation is %GTK_ORIENTATION_HORIZONTAL and @for_size is 300, this functions will compute the minimum and natural width of @widget if it is allocated at a height of 300 pixels. See [GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management) for a more details on implementing `GtkWidgetClass.measure()`. A `GtkWidget` instance the orientation to measure Size for the opposite of @orientation, i.e. if @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height the widget should be measured with. The %GTK_ORIENTATION_VERTICAL case is analogous. This way, both height-for-width and width-for-height requests can be implemented. If no size is known, -1 can be passed. location to store the minimum size location to store the natural size location to store the baseline position for the minimum size, or -1 to report no baseline location to store the baseline position for the natural size, or -1 to report no baseline Emits the [signal@Gtk.Widget::mnemonic-activate] signal. true if the signal has been handled a widget true if there are other widgets with the same mnemonic Signal emitted when a change of focus is requested Signal emitted when “has-tooltip” is %TRUE and the hover timeout has expired with the cursor hovering “above” widget; or emitted when widget got focus in keyboard mode. Creates the GDK resources associated with a widget. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped automatically. Realizing a widget requires all the widget’s parent widgets to be realized; calling this function realizes the widget’s parents in addition to @widget itself. If a widget is not yet inside a toplevel window when you realize it, bad things will happen. This function is primarily used in widget implementations, and isn’t very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as [signal@Gtk.Widget::realize]. a widget Called when the widget gets added to a `GtkRoot` widget. Must chain up Set the focus child of the widget. This function is only suitable for widget implementations. If you want a certain widget to get the input focus, call [method@Gtk.Widget.grab_focus] on it. a widget a direct child widget of @widget or `NULL` to unset the focus child Flags a widget to be displayed. Any widget that isn’t shown will not appear on the screen. Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen. When a toplevel widget is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their toplevel widget is realized and mapped. Use [method@Gtk.Widget.set_visible] instead a widget Called to set the allocation, if the widget does not have a layout manager. Vfunc called when a new snapshot of the widget has to be taken. Signal emitted when the widget state changes, see gtk_widget_get_state_flags(). Emitted when a system setting was changed. Must chain up. Causes a widget to be unmapped if it’s currently mapped. This function is only for use in widget implementations. a widget Causes a widget to be unrealized. This frees all GDK resources associated with the widget. This function is only useful in widget implementations. a widget Called when the widget is about to be removed from its `GtkRoot` widget. Must chain up Enables or disables an action installed with [method@Gtk.WidgetClass.install_action]. a widget action name, such as "clipboard.paste" whether the action is now enabled Activates the widget. The activation will emit the signal set using [method@Gtk.WidgetClass.set_activate_signal] during class initialization. Activation is what happens when you press <kbd>Enter</kbd> on a widget. If you wish to handle the activation keybinding yourself, it is recommended to use [method@Gtk.WidgetClass.add_shortcut] with an action created with [ctor@Gtk.SignalAction.new]. If @widget is not activatable, the function returns false. true if the widget was activated a widget that is activatable Activates an action for the widget. The action is looked up in the action groups associated with @widget and its ancestors. This is a wrapper around [method@Gtk.Widget.activate_action_variant] that constructs the @args variant according to @format_string. true if the action was activated a widget the name of the action to activate `GVariant` format string for arguments arguments, as given by format string Activates an action for the widget. The action is looked up in the action groups associated with @widget and its ancestors. If the action is in an action group added with [method@Gtk.Widget.insert_action_group], the @name is expected to be prefixed with the prefix that was used when the group was inserted. The arguments must match the actions expected parameter type, as returned by [method@Gio.Action.get_parameter_type]. true if the action was activated a widget the name of the action to activate parameters to use Activates the `default.activate` action for the widget. The action is looked up in the same was as for [method@Gtk.Widget.activate_action]. a widget Adds an event controller to the widget. The event controllers of a widget handle the events that are propagated to the widget. You will usually want to call this function right after creating any kind of [class@Gtk.EventController]. a widget an event controller that hasn't been added to a widget yet Adds a style class to the widget. After calling this function, the widget’s style will match for @css_class, according to CSS matching rules. Use [method@Gtk.Widget.remove_css_class] to remove the style again. a widget style class to add to @widget, without the leading period Adds a widget to the list of mnemonic labels for this widget. See [method@Gtk.Widget.list_mnemonic_labels]. Note that the list of mnemonic labels for the widget is cleared when the widget is destroyed, so the caller must make sure to update its internal state at this point as well. a widget a widget that acts as a mnemonic label for @widget Queues an animation frame update and adds a callback to be called before each frame. Until the tick callback is removed, it will be called frequently (usually at the frame rate of the output device or as quickly as the application can be repainted, whichever is slower). For this reason, is most suitable for handling graphics that change every frame or every few frames. The tick callback does not automatically imply a relayout or repaint. If you want a repaint or relayout, and aren’t changing widget properties that would trigger that (for example, changing the text of a label), then you will have to call [method@Gtk.Widget.queue_resize] or [method@Gtk.Widget.queue_draw] yourself. [method@Gdk.FrameClock.get_frame_time] should generally be used for timing continuous animations and [method@Gdk.FrameTimings.get_predicted_presentation_time] should be used if you are trying to display isolated frames at particular times. This is a more convenient alternative to connecting directly to the [signal@Gdk.FrameClock::update] signal of the frame clock, since you don't have to worry about when a frame clock is assigned to a widget. To remove a tick callback, pass the ID that is returned by this function to [method@Gtk.Widget.remove_tick_callback]. an ID for this callback a widget function to call for updating animations data to pass to @callback function to call to free @user_data Assigns size, position, (optionally) a baseline and transform to a child widget. In this function, the allocation and baseline may be adjusted. The given allocation will be forced to be bigger than the widget's minimum size, as well as at least 0×0 in size. This function is only used by widget implementations. For a version that does not take a transform, see [method@Gtk.Widget.size_allocate]. a widget new width new height new baseline, or -1 transformation to be applied Called by widgets as the user moves around the window using keyboard shortcuts. The @direction argument indicates what kind of motion is taking place (up, down, left, right, tab forward, tab backward). This function calls the [vfunc@Gtk.Widget.focus] virtual function; widgets can override the virtual function in order to implement appropriate focus behavior. The default `focus()` virtual function for a widget should return true if moving in @direction left the focus on a focusable location inside that widget, and false if moving in @direction moved the focus outside the widget. When returning true, widgets normally call [method@Gtk.Widget.grab_focus] to place the focus accordingly; when returning false, they don’t modify the current focus location. This function is used by custom widget implementations; if you're writing an app, you’d use [method@Gtk.Widget.grab_focus] to move the focus to a particular widget. true if focus ended up inside @widget a widget direction of focus movement Computes the bounds for @widget in the coordinate space of @target. The bounds of widget are (the bounding box of) the region that it is expected to draw in. See the [coordinate system](coordinates.html) overview to learn more. If the operation is successful, true is returned. If @widget has no bounds or the bounds cannot be expressed in @target's coordinate space (for example if both widgets are in different windows), false is returned and @bounds is set to the zero rectangle. It is valid for @widget and @target to be the same widget. true if the bounds could be computed the widget to query the target widget the rectangle taking the bounds Computes whether a parent widget should give this widget extra space when possible. Widgets with children should check this, rather than looking at [method@Gtk.Widget.get_hexpand] or [method@Gtk.Widget.get_vexpand]. This function already checks whether the widget is visible, so visibility does not need to be checked separately. Non-visible widgets are not expanded. The computed expand value uses either the expand setting explicitly set on the widget itself, or, if none has been explicitly set, the widget may expand if some of its children do. whether widget tree rooted here should be expanded a widget expand direction Translates the given @point in @widget's coordinates to coordinates in @target’s coordinate system. In order to perform this operation, both widgets must share a a common ancestor. If that is not the case, @out_point is set to (0, 0) and false is returned. true if @src_widget and @dest_widget have a common ancestor, false otherwise the widget to query the widget to transform into a point in @widget's coordinate system set to the corresponding coordinates in @target's coordinate system Computes a matrix suitable to describe a transformation from @widget's coordinate system into @target's coordinate system. The transform can not be computed in certain cases, for example when @widget and @target do not share a common ancestor. In that case @out_transform gets set to the identity matrix. To learn more about widget coordinate systems, see the coordinate system [overview](coordinates.html). true if the transform could be computed a widget the target widget that the matrix will transform to location to store the final transformation Tests if a given point is contained in the widget. The coordinates for (x, y) must be in widget coordinates, so (0, 0) is assumed to be the top left of @widget's content area. true if @widget contains the point (x, y) the widget to query X coordinate to test, relative to @widget's origin Y coordinate to test, relative to @widget's origin Creates a new `PangoContext` that is configured for the widget. The `PangoContext` will have the appropriate font map, font options, font description, and base direction set. See also [method@Gtk.Widget.get_pango_context]. the new `PangoContext` a widget Creates a new `PangoLayout` that is configured for the widget. The `PangoLayout` will have the appropriate font map, font description, and base direction set. If you keep a `PangoLayout` created in this way around, you need to re-create it when the widgets `PangoContext` is replaced. This can be tracked by listening to changes of the [property@Gtk.Widget:root] property on the widget. the new `PangoLayout` a widget text to set on the layout Clears the template children for the widget. This function is the opposite of [method@Gtk.Widget.init_template], and it is used to clear all the template children from a widget instance. If you bound a template child to a field in the instance structure, or in the instance private data structure, the field will be set to `NULL` after this function returns. You should call this function inside the `GObjectClass.dispose()` implementation of any widget that called [method@Gtk.Widget.init_template]. Typically, you will want to call this function last, right before chaining up to the parent type's dispose implementation, e.g. ```c static void some_widget_dispose (GObject *gobject) { SomeWidget *self = SOME_WIDGET (gobject); // Clear the template data for SomeWidget gtk_widget_dispose_template (GTK_WIDGET (self), SOME_TYPE_WIDGET); G_OBJECT_CLASS (some_widget_parent_class)->dispose (gobject); } ``` the widget with a template the type of the widget to finalize the template for Checks to see if a drag movement has passed the GTK drag threshold. true if the drag threshold has been passed a widget X coordinate of start of drag Y coordinate of start of drag current X coordinate current Y coordinate Notifies the user about an input-related error on the widget. If the [property@Gtk.Settings:gtk-error-bell] setting is true, it calls [method@Gdk.Surface.beep], otherwise it does nothing. Note that the effect of [method@Gdk.Surface.beep] can be configured in many ways, depending on the windowing backend and the desktop environment or window manager that is used. a widget Returns the baseline that has currently been allocated to the widget. This function is intended to be used when implementing handlers for the `GtkWidget`Class.snapshot() function, and when allocating child widgets in `GtkWidget`Class.size_allocate(). Use [method@Gtk.Widget.get_baseline] instead the baseline of the @widget, or -1 if none the widget to query Returns the height that has currently been allocated to the widget. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). Use [method@Gtk.Widget.get_height] instead the height of the @widget the widget to query Returns the width that has currently been allocated to the widget. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). Use [method@Gtk.Widget.get_width] instead the width of the @widget the widget to query Retrieves the widget’s allocation. Note, when implementing a layout widget: a widget’s allocation will be its “adjusted” allocation, that is, the widget’s parent typically calls [method@Gtk.Widget.size_allocate] with an allocation, and that allocation is then adjusted (to handle margin and alignment for example) before assignment to the widget. [method@Gtk.Widget.get_allocation] returns the adjusted allocation that was actually assigned to the widget. The adjusted allocation is guaranteed to be completely contained within the [method@Gtk.Widget.size_allocate] allocation, however. So a layout widget is guaranteed that its children stay inside the assigned bounds, but not that they have exactly the bounds the widget assigned. Use [method@Gtk.Widget.compute_bounds], [method@Gtk.Widget.get_width] or [method@Gtk.Widget.get_height] instead. a widget a pointer to a `GtkAllocation` to copy to Gets the first ancestor of the widget with type @widget_type. For example, `gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)` gets the first `GtkBox` that’s an ancestor of @widget. No reference will be added to the returned widget; it should not be unreferenced. Note that unlike [method@Gtk.Widget.is_ancestor], this function considers @widget to be an ancestor of itself. the ancestor widget a widget ancestor type Returns the baseline that has currently been allocated to the widget. This function is intended to be used when implementing handlers for the `GtkWidgetClass.snapshot()` function, and when allocating child widgets in `GtkWidgetClass.size_allocate()`. the baseline of the @widget, or -1 if none the widget to query Determines whether the input focus can enter the widget or any of its children. See [method@Gtk.Widget.set_can_focus]. true if the input focus can enter @widget a widget Queries whether the widget can be the target of pointer events. true if @widget can receive pointer events a widget Gets the value set with [method@Gtk.Widget.set_child_visible]. If you feel a need to use this function, your code probably needs reorganization. This function is only useful for widget implementations and should never be called by an application. true if the widget is mapped with the parent a widget Gets the clipboard object for the widget. This is a utility function to get the clipboard object for the display that @widget is using. Note that this function always works, even when @widget is not realized yet. the appropriate clipboard object a widget Gets the current foreground color for the widget’s style. This function should only be used in snapshot implementations that need to do custom drawing with the foreground color. a widget return location for the color Returns the list of style classes applied to the widget. a `NULL`-terminated list of css classes currently applied to @widget a widget Returns the CSS name of the widget. the CSS name a widget Gets the cursor set on the widget. See [method@Gtk.Widget.set_cursor] for details. the cursor that is set on @widget a widget Gets the reading direction for the widget. See [method@Gtk.Widget.set_direction]. the reading direction for the widget a widget Get the display for the window that the widget belongs to. This function can only be called after the widget has been added to a widget hierarchy with a `GtkRoot` at the top. In general, you should only create display-specific resources when a widget has been realized, and you should free those resources when the widget is unrealized. the display for this widget a widget Returns the widget’s first child. This function is primarily meant for widget implementations. the widget's first child a widget Returns the focus child of the widget. the current focus child of @widget a widget Returns whether the widget should grab focus when it is clicked with the mouse. See [method@Gtk.Widget.set_focus_on_click]. true if the widget should grab focus when it is clicked with the mouse a widget Determines whether the widget can own the input focus. See [method@Gtk.Widget.set_focusable]. true if @widget can own the input focus a widget Gets the font map of the widget. See [method@Gtk.Widget.set_font_map]. the font map of @widget a widget Returns the `cairo_font_options_t` of the widget. Seee [method@Gtk.Widget.set_font_options]. the `cairo_font_options_t` of widget a widget Obtains the frame clock for a widget. The frame clock is a global “ticker” that can be used to drive animations and repaints. The most common reason to get the frame clock is to call [method@Gdk.FrameClock.get_frame_time], in order to get a time to use for animating. For example you might record the start of the animation with an initial value from [method@Gdk.FrameClock.get_frame_time], and then update the animation by calling [method@Gdk.FrameClock.get_frame_time] again during each repaint. [method@Gdk.FrameClock.request_phase] will result in a new frame on the clock, but won’t necessarily repaint any widgets. To repaint a widget, you have to use [method@Gtk.Widget.queue_draw] which invalidates the widget (thus scheduling it to receive a draw on the next frame). [method@Gtk.Widget.queue_draw] will also end up requesting a frame on the appropriate frame clock. A widget’s frame clock will not change while the widget is mapped. Reparenting a widget (which implies a temporary unmap) can change the widget’s frame clock. Unrealized widgets do not have a frame clock. the frame clock a widget Gets the horizontal alignment of the widget. For backwards compatibility reasons this method will never return one of the baseline alignments, but instead it will convert it to [enum@Gtk.Align.fill] or [enum@Gtk.Align.center]. Baselines are not supported for horizontal alignment. the horizontal alignment of @widget a widget Returns the current value of the `has-tooltip` property. current value of `has-tooltip` on @widget a widget Returns the content height of the widget. This function returns the height passed to its size-allocate implementation, which is the height you should be using in [vfunc@Gtk.Widget.snapshot]. For pointer events, see [method@Gtk.Widget.contains]. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). The height of @widget a widget Gets whether the widget would like any available extra horizontal space. When a user resizes a window, widgets with expand set to true generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand. Widgets with children should use [method@Gtk.Widget.compute_expand] rather than this function, to see whether any of its children, has the expand flag set. If any child of a widget wants to expand, the parent may ask to expand also. This function only looks at the widget’s own hexpand flag, rather than computing whether the entire widget tree rooted at this widget wants to expand. whether hexpand flag is set a widget Gets whether the `hexpand` flag has been explicitly set. If [property@Gtk.Widget:hexpand] property is set, then it overrides any computed expand value based on child widgets. If `hexpand` is not set, then the expand value depends on whether any children of the widget would like to expand. There are few reasons to use this function, but it’s here for completeness and consistency. whether hexpand has been explicitly set a widget Returns the widget’s last child. This function is primarily meant for widget implementations. the widget's last child a widget Retrieves the layout manager of the widget. See [method@Gtk.Widget.set_layout_manager]. the layout manager of @widget a widget Gets the value of the [property@Gtk.Widget:limit-events] property. a `GtkWidget` Returns whether the widget is mapped. true if the widget is mapped a widget Gets the bottom margin of the widget. The bottom margin of @widget a widget Gets the end margin of the widget. The end margin of @widget a widget Gets the start margin of the widget. The start margin of @widget a widget Gets the top margin of the widget. The top margin of @widget a widget Retrieves the name of a widget. See [method@Gtk.Widget.set_name] for the significance of widget names. name of the widget a widget Returns the nearest `GtkNative` ancestor of the widget. This function will return `NULL` if the widget is not contained inside a widget tree with a native ancestor. `GtkNative` widgets will return themselves here. the `GtkNative` ancestor of @widget a widget Returns the widget’s next sibling. This function is primarily meant for widget implementations. the widget's next sibling a widget Fetches the requested opacity for the widget. See [method@Gtk.Widget.set_opacity]. the requested opacity for this widget a widget Returns the widget’s overflow value. The widget's overflow value a widget Gets a `PangoContext` that is configured for the widget. The `PangoContext` will have the appropriate font map, font description, and base direction set. Unlike the context returned by [method@Gtk.Widget.create_pango_context], this context is owned by the widget (it can be used until the screen for the widget changes or the widget is removed from its toplevel), and will be updated to match any changes to the widget’s attributes. This can be tracked by listening to changes of the [property@Gtk.Widget:root] property on the widget. the `PangoContext` for the widget a widget Returns the parent widget of the widget. the parent widget of @widget a widget Retrieves the minimum and natural size of a widget, taking into account the widget’s preference for height-for-width management. This is used to retrieve a suitable size by container widgets which do not impose any restrictions on the child placement. It can be used to deduce toplevel window and menu sizes as well as child widgets in free-form containers such as `GtkFixed`. Handle with care. Note that the natural height of a height-for-width widget will generally be a smaller size than the minimum height, since the required height for the natural width is generally smaller than the required height for the minimum width. Use [method@Gtk.Widget.measure] if you want to support baseline alignment. a `GtkWidget` instance location for storing the minimum size location for storing the natural size Returns the widget’s previous sibling. This function is primarily meant for widget implementations. the widget's previous sibling a widget Gets the primary clipboard of the widget. This is a utility function to get the primary clipboard object for the display that @widget is using. Note that this function always works, even when @widget is not realized yet. the appropriate clipboard object a widget Determines whether the widget is realized. true if @widget is realized a widget Determines whether the widget is always treated as the default widget within its toplevel when it has the focus, even if another widget is the default. See [method@Gtk.Widget.set_receives_default]. true if @widget acts as the default widget when focused a widget Gets whether the widget prefers a height-for-width layout or a width-for-height layout. Single-child widgets generally propagate the preference of their child, more complex widgets need to request something either in context of their children or in context of their allocation capabilities. The `GtkSizeRequestMode` preferred by @widget. a `GtkWidget` instance Returns the `GtkRoot` widget of the widget. This function will return `NULL` if the widget is not contained inside a widget tree with a root widget. `GtkRoot` widgets will return themselves here. the root widget of @widget a widget Retrieves the internal scale factor that maps from window coordinates to the actual device pixels. On traditional systems this is 1, on high density outputs, it can be a higher value (typically 2). See [method@Gdk.Surface.get_scale_factor]. Note that modern systems may support *fractional* scaling, where the scale factor is not an integer. On such systems, this function will return the next higher integer value, but you probably want to use [method@Gdk.Surface.get_scale] to get the fractional scale value. the scale factor for @widget a widget Returns the widget’s sensitivity. This function returns the value that has been set using [method@Gtk.Widget.set_sensitive]). The effective sensitivity of a widget is however determined by both its own and its parent widget’s sensitivity. See [method@Gtk.Widget.is_sensitive]. true if the widget is sensitive a widget Gets the settings object holding the settings used for the widget. Note that this function can only be called when the `GtkWidget` is attached to a toplevel, since the settings object is specific to a particular display. If you want to monitor the widget for changes in its settings, connect to the `notify::display` signal. the relevant settings object a widget Returns the content width or height of the widget. Which dimension is returned depends on @orientation. This is equivalent to calling [method@Gtk.Widget.get_width] for [enum@Gtk.Orientation.horizontal] or [method@Gtk.Widget.get_height] for [enum@Gtk.Orientation.vertical], but can be used when writing orientation-independent code, such as when implementing [iface@Gtk.Orientable] widgets. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). the size of @widget in @orientation a widget the orientation to query Gets the size request that was explicitly set for the widget. A value of -1 stored in @width or @height indicates that that dimension has not been set explicitly and the natural requisition of the widget will be used instead. See [method@Gtk.Widget.set_size_request]. To get the size a widget will actually request, call [method@Gtk.Widget.measure] instead of this function. a widget return location for width return location for height Returns the widget state as a flag set. It is worth mentioning that the effective [flags@Gtk.StateFlags.insensitive] state will be returned, that is, also based on parent insensitivity, even if @widget itself is sensitive. Also note that if you are looking for a way to obtain the [flags@Gtk.StateFlags] to pass to a [class@Gtk.StyleContext] method, you should look at [method@Gtk.StyleContext.get_state]. the state flags of widget a widget Returns the style context associated to the widget. The returned object is guaranteed to be the same for the lifetime of @widget. Style contexts will be removed in GTK 5 the widgets style context a widget Fetches an object build from the template XML for @widget_type in the widget. This will only report children which were previously declared with [method@Gtk.WidgetClass.bind_template_child_full] or one of its variants. This function is only meant to be called for code which is private to the @widget_type which declared the child and is meant for language bindings which cannot easily make use of the GObject structure offsets. the object built in the template XML with the id @name a widget The type of the widget class that defines the child in the template ID of the child defined in the template XML Gets the contents of the tooltip for the widget. If the tooltip has not been set using [method@Gtk.Widget.set_tooltip_markup], this function returns `NULL`. the tooltip text a widget Gets the contents of the tooltip for the widget. If the @widget's tooltip was set using [method@Gtk.Widget.set_tooltip_markup], this function will return the escaped text. the tooltip text a widget Gets the vertical alignment of the widget. the vertical alignment of @widget a widget Gets whether the widget would like any available extra vertical space. See [method@Gtk.Widget.get_hexpand] for more detail. whether vexpand flag is set a widget Gets whether the `vexpand` flag has been explicitly set. See [method@Gtk.Widget.get_hexpand_set] for more detail. whether vexpand has been explicitly set a widget Determines whether the widget is visible. If you want to take into account whether the widget’s parent is also marked as visible, use [method@Gtk.Widget.is_visible] instead. This function does not check if the widget is obscured in any way. See [method@Gtk.Widget.set_visible]. true if the widget is visible a widget Returns the content width of the widget. This function returns the width passed to its size-allocate implementation, which is the width you should be using in [vfunc@Gtk.Widget.snapshot]. For pointer events, see [method@Gtk.Widget.contains]. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). The width of @widget a widget Causes @widget to have the keyboard focus for the window that it belongs to. If @widget is not focusable, or its [vfunc@Gtk.Widget.grab_focus] implementation cannot transfer the focus to a descendant of @widget that is focusable, it will not take focus and false will be returned. Calling [method@Gtk.Widget.grab_focus] on an already focused widget is allowed, should not have an effect, and return true. true if focus is now inside @widget a widget Returns whether a style class is currently applied to the widget. true if @css_class is currently applied to @widget a widget style class, without the leading period Determines whether the widget is the current default widget within its toplevel. true if @widget is the current default widget within its toplevel a widget Determines if the widget has the global input focus. See [method@Gtk.Widget.is_focus] for the difference between having the global input focus, and only having the focus within a toplevel. true if the widget has the global input focus a widget Determines if the widget should show a visible indication that it has the global input focus. This is a convenience function that takes into account whether focus indication should currently be shown in the toplevel window of @widget. See [method@Gtk.Window.get_focus_visible] for more information about focus indication. To find out if the widget has the global input focus, use [method@Gtk.Widget.has_focus]. true if the widget should display a “focus rectangle” a widget Reverses the effects of [method.Gtk.Widget.show]. This is causing the widget to be hidden (invisible to the user). Use [method@Gtk.Widget.set_visible] instead a widget Returns whether the widget is currently being destroyed. This information can sometimes be used to avoid doing unnecessary work. true if @widget is being destroyed a widget Creates and initializes child widgets defined in templates. This function must be called in the instance initializer for any class which assigned itself a template using [method@Gtk.WidgetClass.set_template]. It is important to call this function in the instance initializer of a widget subclass and not in `GObject.constructed()` or `GObject.constructor()` for two reasons: - derived widgets will assume that the composite widgets defined by its parent classes have been created in their relative instance initializers - when calling `g_object_new()` on a widget with composite templates, it’s important to build the composite widgets before the construct properties are set. Properties passed to `g_object_new()` should take precedence over properties set in the private template XML A good rule of thumb is to call this function as the first thing in an instance initialization function. a widget Inserts an action group into the widget's actions. Children of @widget that implement [iface@Gtk.Actionable] can then be associated with actions in @group by setting their “action-name” to @prefix.`action-name`. Note that inheritance is defined for individual actions. I.e. even if you insert a group with prefix @prefix, actions with the same prefix will still be inherited from the parent, unless the group contains an action with the same name. If @group is `NULL`, a previously inserted group for @name is removed from @widget. a widget the prefix for actions in @group an action group Sets the parent widget of the widget. In contrast to [method@Gtk.Widget.set_parent], this function inserts @widget at a specific position into the list of children of the @parent widget. It will be placed after @previous_sibling, or at the beginning if @previous_sibling is `NULL`. After calling this function, `gtk_widget_get_prev_sibling (widget)` will return @previous_sibling. If @parent is already set as the parent widget of @widget, this function can also be used to reorder @widget in the child widget list of @parent. This function is primarily meant for widget implementations; if you are just using a widget, you *must* use its own API for adding children. a widget the parent widget to insert @widget into the new previous sibling of @widget Sets the parent widget of the widget. In contrast to [method@Gtk.Widget.set_parent], this function inserts @widget at a specific position into the list of children of the @parent widget. It will be placed before @next_sibling, or at the end if @next_sibling is `NULL`. After calling this function, `gtk_widget_get_next_sibling (widget)` will return @next_sibling. If @parent is already set as the parent widget of @widget, this function can also be used to reorder @widget in the child widget list of @parent. This function is primarily meant for widget implementations; if you are just using a widget, you *must* use its own API for adding children. a widget the parent widget to insert @widget into the new next sibling of @widget Determines whether the widget is a descendent of @ancestor. true if @ancestor contains @widget as a child, grandchild, great grandchild, etc a widget another `GtkWidget` Determines whether the widget can be drawn to. A widget can be drawn if it is mapped and visible. true if @widget is drawable a widget Determines if the widget is the focus widget within its toplevel. This does not mean that the [property@Gtk.Widget:has-focus] property is necessarily set; [property@Gtk.Widget:has-focus] will only be set if the toplevel widget additionally has the global input focus. true if the widget is the focus widget a widget Returns the widget’s effective sensitivity. This means it is sensitive itself and also its parent widget is sensitive. true if the widget is effectively sensitive a widget Determines whether the widget and all its parents are marked as visible. This function does not check if the widget is obscured in any way. See also [method@Gtk.Widget.get_visible] and [method@Gtk.Widget.set_visible]. true if the widget and all its parents are visible a widget Emits the [signal@Gtk.Widget::keynav-failed] signal on the widget. This function should be called whenever keyboard navigation within a single widget hits a boundary. The return value of this function should be interpreted in a way similar to the return value of [method@Gtk.Widget.child_focus]. When true is returned, stay in the widget, the failed keyboard navigation is ok and/or there is nowhere we can/should move the focus to. When false is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling [method@Gtk.Widget.child_focus] on the widget’s toplevel. The default [signal@Gtk.Widget::keynav-failed] handler returns false for [enum@Gtk.DirectionType.tab-forward] and [enum@Gtk.DirectionType.tab-backward]. For the other values of [enum@Gtk.DirectionType] it returns true. Whenever the default handler returns true, it also calls [method@Gtk.Widget.error_bell] to notify the user of the failed keyboard navigation. A use case for providing an own implementation of `::keynav-failed` (either by connecting to it or by overriding it) would be a row of [class@Gtk.Entry] widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys. true if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard navigation attempt in its parent widget a widget direction of focus movement Returns the widgets for which this widget is the target of a mnemonic. Typically, these widgets will be labels. See, for example, [method@Gtk.Label.set_mnemonic_widget]. The widgets in the list are not individually referenced. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets, you must call `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first, and then unref all the widgets afterwards. the list of mnemonic labels a widget Causes a widget to be mapped if it isn’t already. This function is only for use in widget implementations. a widget Measures @widget in the orientation @orientation and for the given @for_size. As an example, if @orientation is %GTK_ORIENTATION_HORIZONTAL and @for_size is 300, this functions will compute the minimum and natural width of @widget if it is allocated at a height of 300 pixels. See [GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management) for a more details on implementing `GtkWidgetClass.measure()`. A `GtkWidget` instance the orientation to measure Size for the opposite of @orientation, i.e. if @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height the widget should be measured with. The %GTK_ORIENTATION_VERTICAL case is analogous. This way, both height-for-width and width-for-height requests can be implemented. If no size is known, -1 can be passed. location to store the minimum size location to store the natural size location to store the baseline position for the minimum size, or -1 to report no baseline location to store the baseline position for the natural size, or -1 to report no baseline Emits the [signal@Gtk.Widget::mnemonic-activate] signal. true if the signal has been handled a widget true if there are other widgets with the same mnemonic Returns a list model to track the children of the widget. Calling this function will enable extra internal bookkeeping to track children and emit signals on the returned listmodel. It may slow down operations a lot. Applications should try hard to avoid calling this function because of the slowdowns. a list model tracking @widget's children a widget Returns a list model to track the event controllers of the widget. Calling this function will enable extra internal bookkeeping to track controllers and emit signals on the returned listmodel. It may slow down operations a lot. Applications should try hard to avoid calling this function because of the slowdowns. a list model tracking @widget's controllers a widget Finds the descendant of the widget closest to a point. The point (x, y) must be given in widget coordinates, so (0, 0) is assumed to be the top left of @widget's content area. Usually widgets will return `NULL` if the given coordinate is not contained in @widget checked via [method@Gtk.Widget.contains]. Otherwise they will recursively try to find a child that does not return `NULL`. Widgets are however free to customize their picking algorithm. This function is used on the toplevel to determine the widget below the mouse cursor for purposes of hover highlighting and delivering events. the widget's descendant at (x, y) the widget to query x coordinate to test, relative to @widget's origin y coordinate to test, relative to @widget's origin flags to influence what is picked Flags the widget for a rerun of the [vfunc@Gtk.Widget.size_allocate] function. Use this function instead of [method@Gtk.Widget.queue_resize] when the @widget's size request didn't change but it wants to reposition its contents. An example user of this function is [method@Gtk.Widget.set_halign]. This function is only for use in widget implementations. a widget Schedules this widget to be redrawn. The redraw will happen in the paint phase of the current or the next frame. This means @widget's [vfunc@Gtk.Widget.snapshot] implementation will be called. a widget Flags a widget to have its size renegotiated. This should be called when a widget for some reason has a new size request. For example, when you change the text in a [class@Gtk.Label], the label queues a resize to ensure there’s enough space for the new text. Note that you cannot call gtk_widget_queue_resize() on a widget from inside its implementation of the [vfunc@Gtk.Widget.size_allocate] virtual method. Calls to gtk_widget_queue_resize() from inside [vfunc@Gtk.Widget.size_allocate] will be silently ignored. This function is only for use in widget implementations. a widget Creates the GDK resources associated with a widget. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped automatically. Realizing a widget requires all the widget’s parent widgets to be realized; calling this function realizes the widget’s parents in addition to @widget itself. If a widget is not yet inside a toplevel window when you realize it, bad things will happen. This function is primarily used in widget implementations, and isn’t very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as [signal@Gtk.Widget::realize]. a widget Removes an event controller from the widget. The removed event controller will not receive any more events, and should not be used again. Widgets will remove all event controllers automatically when they are destroyed, there is normally no need to call this function. a widget an event controller Removes a style from the widget. After this, the style of @widget will stop matching for @css_class. a widget style class to remove from @widget, without the leading period Removes a widget from the list of mnemonic labels for this widget. See [method@Gtk.Widget.list_mnemonic_labels]. The widget must have previously been added to the list with [method@Gtk.Widget.add_mnemonic_label]. a widget a widget that is a mnemonic label for @widget Removes a tick callback previously registered with [method@Gtk.Widget.add_tick_callback]. a widget an ID returned by [method@Gtk.Widget.add_tick_callback] Sets whether the input focus can enter the widget or any of its children. Applications should set @can_focus to false to mark a widget as for pointer/touch use only. Note that having @can_focus be true is only one of the necessary conditions for being focusable. A widget must also be sensitive and focusable and not have an ancestor that is marked as not can-focus in order to receive input focus. See [method@Gtk.Widget.grab_focus] for actually setting the input focus on a widget. a widget whether the input focus can enter the widget or any of its children Sets whether the widget can be the target of pointer events. a widget whether this widget should be able to receive pointer events Sets whether the widget should be mapped along with its parent. The child visibility can be set for widget before it is added to a container with [method@Gtk.Widget.set_parent], to avoid mapping children unnecessary before immediately unmapping them. However it will be reset to its default state of true when the widget is removed from a container. Note that changing the child visibility of a widget does not queue a resize on the widget. Most of the time, the size of a widget is computed from all visible children, whether or not they are mapped. If this is not the case, the container can queue a resize itself. This function is only useful for widget implementations and should never be called by an application. a widget whether @widget should be mapped along with its parent Replaces the current style classes of the widget with @classes. a widget `NULL`-terminated list of style classes Sets the cursor to be shown when the pointer hovers over the widget. If the @cursor is `NULL`, @widget will use the cursor inherited from its parent. a widget the new cursor Sets the cursor to be shown when the pointer hovers over the widget. This is a utility function that creates a cursor via [ctor@Gdk.Cursor.new_from_name] and then sets it on @widget with [method@Gtk.Widget.set_cursor]. See those functions for details. On top of that, this function allows @name to be `NULL`, which will do the same as calling [method@Gtk.Widget.set_cursor] with a `NULL` cursor. a widget the name of the cursor Sets the reading direction on the widget. This direction controls the primary direction for widgets containing text, and also the direction in which the children of a container are packed. The ability to set the direction is present in order so that correct localization into languages with right-to-left reading directions can be done. Generally, applications will let the default reading direction prevail, except for widgets where the children are arranged in an order that is explicitly visual rather than logical (such as buttons for text justification). If the direction is set to [enum@Gtk.TextDirection.none], then the value set by [func@Gtk.Widget.set_default_direction] will be used. a widget the new direction Set the focus child of the widget. This function is only suitable for widget implementations. If you want a certain widget to get the input focus, call [method@Gtk.Widget.grab_focus] on it. a widget a direct child widget of @widget or `NULL` to unset the focus child Sets whether the widget should grab focus when it is clicked with the mouse. Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard focus removed from the main area of the application. a widget whether the widget should grab focus when clicked with the mouse Sets whether the widget can own the input focus. Widget implementations should set @focusable to true in their init() function if they want to receive keyboard input. Note that having @focusable be true is only one of the necessary conditions for being focusable. A widget must also be sensitive and can-focus and not have an ancestor that is marked as not can-focus in order to receive input focus. See [method@Gtk.Widget.grab_focus] for actually setting the input focus on a widget. a widget whether or not @widget can own the input focus Sets the font map to use for text rendering in the widget. The font map is the object that is used to look up fonts. Setting a custom font map can be useful in special situations, e.g. when you need to add application-specific fonts to the set of available fonts. When not set, the widget will inherit the font map from its parent. a widget a `PangoFontMap` Sets the `cairo_font_options_t` used for text rendering in the widget. When not set, the default font options for the `GdkDisplay` will be used. a widget a `cairo_font_options_t` struct to unset any previously set default font options Sets the horizontal alignment of the widget. a widget the horizontal alignment Sets the `has-tooltip` property on the widget. a widget whether or not @widget has a tooltip Sets whether the widget would like any available extra horizontal space. When a user resizes a window, widgets with expand set to true generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand. Call this function to set the expand flag if you would like your widget to become larger horizontally when the window has extra room. By default, widgets automatically expand if any of their children want to expand. (To see if a widget will automatically expand given its current children and state, call [method@Gtk.Widget.compute_expand]. A widget can decide how the expandability of children affects its own expansion by overriding the `compute_expand` virtual method on `GtkWidget`.). Setting hexpand explicitly with this function will override the automatic expand behavior. This function forces the widget to expand or not to expand, regardless of children. The override occurs because [method@Gtk.Widget.set_hexpand] sets the hexpand-set property (see [method@Gtk.Widget.set_hexpand_set]) which causes the widget’s hexpand value to be used, rather than looking at children and widget state. a widget whether to expand Sets whether the hexpand flag will be used. The [property@Gtk.Widget:hexpand-set] property will be set automatically when you call [method@Gtk.Widget.set_hexpand] to set hexpand, so the most likely reason to use this function would be to unset an explicit expand flag. If hexpand is set, then it overrides any computed expand value based on child widgets. If hexpand is not set, then the expand value depends on whether any children of the widget would like to expand. There are few reasons to use this function, but it’s here for completeness and consistency. a widget value for hexpand-set property Sets the layout manager to use for measuring and allocating children of the widget. a widget a layout manager Sets whether the widget acts like a modal dialog, with respect to event delivery. a `GtkWidget` whether to limit events Sets the bottom margin of the widget. a widget the bottom margin Sets the end margin of the widget. a widget the end margin Sets the start margin of the widget. a widget the start margin Sets the top margin of the widget. a widget the top margin Sets a widgets name. Setting a name allows you to refer to the widget from a CSS file. You can apply a style to widgets with a particular name in the CSS file. See the documentation for the CSS syntax (on the same page as the docs for [class@Gtk.StyleContext]. Note that the CSS syntax has certain special characters to delimit and represent elements in a selector (period, #, >, *...), so using these will make your widget impossible to match by name. Any combination of alphanumeric symbols, dashes and underscores will suffice. a widget name for the widget Requests the widget to be rendered partially transparent. An opacity of 0 is fully transparent and an opacity of 1 is fully opaque. Opacity works on both toplevel widgets and child widgets, although there are some limitations: For toplevel widgets, applying opacity depends on the capabilities of the windowing system. On X11, this has any effect only on X displays with a compositing manager, see [method@Gdk.Display.is_composited]. On Windows and Wayland it will always work, although setting a window’s opacity after the window has been shown may cause some flicker. Note that the opacity is inherited through inclusion — if you set a toplevel to be partially translucent, all of its content will appear translucent, since it is ultimatively rendered on that toplevel. The opacity value itself is not inherited by child widgets (since that would make widgets deeper in the hierarchy progressively more translucent). As a consequence, [class@Gtk.Popover] instances and other [iface@Gtk.Native] widgets with their own surface will use their own opacity value, and thus by default appear non-translucent, even if they are attached to a toplevel that is translucent. a widget desired opacity, between 0 and 1 Sets how the widget treats content that is drawn outside the it's content area. See the definition of [enum@Gtk.Overflow] for details. This setting is provided for widget implementations and should not be used by application code. The default value is [enum@Gtk.Overflow.visible]. a widget desired overflow value Sets the parent widget of the widget. This takes care of details such as updating the state and style of the child to reflect its new location and resizing the parent. The opposite function is [method@Gtk.Widget.unparent]. This function is useful only when implementing subclasses of `GtkWidget`. a widget parent widget Sets whether the widget will be treated as the default widget within its toplevel when it has the focus, even if another widget is the default. a widget whether or not @widget can be a default widget Sets the sensitivity of the widget. A widget is sensitive if the user can interact with it. Insensitive widgets are “grayed out” and the user can’t interact with them. Insensitive widgets are known as “inactive”, “disabled”, or “ghosted” in some other toolkits. a widget true to make the widget sensitive Sets the minimum size of the widget. That is, the widget’s size request will be at least @width by @height. You can use this function to force a widget to be larger than it normally would be. In most cases, [method@Gtk.Window.set_default_size] is a better choice for toplevel windows than this function; setting the default size will still allow users to shrink the window. Setting the size request will force them to leave the window at least as large as the size request. Note the inherent danger of setting any fixed size - themes, translations into other languages, different fonts, and user action can all change the appropriate size for a given widget. So, it is basically impossible to hardcode a size that will always work. The size request of a widget is the smallest size a widget can accept while still functioning well and drawing itself correctly. However in some strange cases a widget may be allocated less than its requested size, and in many cases a widget may be allocated more space than it requested. If the size request in a given direction is -1 (unset), then the “natural” size request of the widget will be used instead. The size request set here does not include any margin from the properties [property@Gtk.Widget:margin-start], [property@Gtk.Widget:margin-end], [property@Gtk.Widget:margin-top], and [property@Gtk.Widget:margin-bottom], but it does include pretty much all other padding or border properties set by any subclass of `GtkWidget`. a widget width @widget should request, or -1 to unset height @widget should request, or -1 to unset Turns on flag values in the current widget state. Typical widget states are insensitive, prelighted, etc. This function accepts the values [flags@Gtk.StateFlags.dir-ltr] and [flags@Gtk.StateFlags.dir-rtl] but ignores them. If you want to set the widget's direction, use [method@Gtk.Widget.set_direction]. This function is for use in widget implementations. a widget state flags to turn on whether to clear state before turning on @flags Sets the contents of the tooltip for widget. @markup must contain Pango markup. This function will take care of setting the [property@Gtk.Widget:has-tooltip] as a side effect, and of the default handler for the [signal@Gtk.Widget::query-tooltip] signal. See also [method@Gtk.Tooltip.set_markup]. a widget the contents of the tooltip for @widget Sets the contents of the tooltip for the widget. If @text contains any markup, it will be escaped. This function will take care of setting [property@Gtk.Widget:has-tooltip] as a side effect, and of the default handler for the [signal@Gtk.Widget::query-tooltip] signal. See also [method@Gtk.Tooltip.set_text]. a widget the contents of the tooltip for @widget Sets the vertical alignment of the widget. a widget the vertical alignment Sets whether the widget would like any available extra vertical space. See [method@Gtk.Widget.set_hexpand] for more detail. a widget whether to expand Sets whether the vexpand flag will be used. See [method@Gtk.Widget.set_hexpand_set] for more detail. the widget value for vexpand-set property Sets the visibility state of @widget. Note that setting this to true doesn’t mean the widget is actually viewable, see [method@Gtk.Widget.get_visible]. a widget whether the widget should be shown or not Returns whether the widget should contribute to the measuring and allocation of its parent. This is false for invisible children, but also for children that have their own surface, such as [class@Gtk.Popover] instances. true if child should be included in measuring and allocating a widget Flags a widget to be displayed. Any widget that isn’t shown will not appear on the screen. Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen. When a toplevel widget is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their toplevel widget is realized and mapped. Use [method@Gtk.Widget.set_visible] instead a widget Allocates widget with a transformation that translates the origin to the position in @allocation. This is a simple form of [method@Gtk.Widget.allocate]. a widget position and size to be allocated to @widget the baseline of the child, or -1 Snapshots a child of the widget. When a widget receives a call to the snapshot function, it must send synthetic [vfunc@Gtk.Widget.snapshot] calls to all children. This function provides a convenient way of doing this. A widget, when it receives a call to its [vfunc@Gtk.Widget.snapshot] function, calls gtk_widget_snapshot_child() once for each child, passing in the @snapshot the widget received. This function takes care of translating the origin of @snapshot, and deciding whether the child needs to be snapshot. It does nothing for children that implement `GtkNative`. a widget a child of @widget snapshot as passed to the widget. In particular, no calls to [method@Gtk.Snapshot.translate] or other transform calls should have been made Translates coordinates relative to @src_widget’s allocation to coordinates relative to @dest_widget’s allocations. In order to perform this operation, both widget must share a common ancestor. If that is not the case, @dest_x and @dest_y are set to 0 and false is returned. Use [method@Gtk.Widget.compute_point] instead true if @src_widget and @dest_widget have a common ancestor, false otherwise a widget another widget X position in widget coordinates of @src_widget Y position in widget coordinates of @src_widget location to store X position in widget coordinates of @dest_widget location to store Y position in widget coordinates of @dest_widget Triggers a tooltip query on the display of the widget. a widget Causes a widget to be unmapped if it’s currently mapped. This function is only for use in widget implementations. a widget Removes @widget from its parent. This function is only for use in widget implementations, typically in dispose. a widget Causes a widget to be unrealized. This frees all GDK resources associated with the widget. This function is only useful in widget implementations. a widget Turns off flag values for the current widget state. See [method@Gtk.Widget.set_state_flags]. This function is for use in widget implementations. a widget state flags to turn off Whether the widget or any of its descendents can accept the input focus. This property is meant to be set by widget implementations, typically in their instance init function. Whether the widget can receive pointer events. A list of css classes applied to this widget. The name of this widget in the CSS tree. This property is meant to be set by widget implementations, typically in their instance init function. The cursor used by @widget. Whether the widget should grab focus when it is clicked with the mouse. This property is only relevant for widgets that can take focus. Whether this widget itself will accept the input focus. How to distribute horizontal space if widget gets extra space. Whether the widget is the default widget. Whether the widget has the input focus. Enables or disables the emission of the [signal@Gtk.Widget::query-tooltip] signal on @widget. A true value indicates that @widget can have a tooltip, in this case the widget will be queried using [signal@Gtk.Widget::query-tooltip] to determine whether it will provide a tooltip or not. Overrides for height request of the widget. If this is -1, the natural request will be used. Whether to expand horizontally. Whether to use the `hexpand` property. The [class@Gtk.LayoutManager] instance to use to compute the preferred size of the widget, and allocate its children. This property is meant to be set by widget implementations, typically in their instance init function. Makes this widget act like a modal dialog, with respect to event delivery. Global event controllers will not handle events with targets inside the widget, unless they are set up to ignore propagation limits. See [method@Gtk.EventController.set_propagation_limit]. Margin on bottom side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [method@Gtk.Widget.set_size_request] for example. Margin on end of widget, horizontally. This property supports left-to-right and right-to-left text directions. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [method@Gtk.Widget.set_size_request] for example. Margin on start of widget, horizontally. This property supports left-to-right and right-to-left text directions. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [method@Gtk.Widget.set_size_request] for example. Margin on top side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [method@Gtk.Widget.set_size_request] for example. The name of the widget. The requested opacity of the widget. How content outside the widget's content area is treated. This property is meant to be set by widget implementations, typically in their instance init function. The parent widget of this widget. Whether the widget will receive the default action when it is focused. The `GtkRoot` widget of the widget tree containing this widget. This will be `NULL` if the widget is not contained in a root widget. The scale factor of the widget. Whether the widget responds to input. Sets the text of tooltip to be the given string, which is marked up with Pango markup. Also see [method@Gtk.Tooltip.set_markup]. This is a convenience property which will take care of getting the tooltip shown if the given string is not `NULL`: [property@Gtk.Widget:has-tooltip] will automatically be set to true and there will be taken care of [signal@Gtk.Widget::query-tooltip] in the default signal handler. Note that if both [property@Gtk.Widget:tooltip-text] and [property@Gtk.Widget:tooltip-markup] are set, the last one wins. Sets the text of tooltip to be the given string. Also see [method@Gtk.Tooltip.set_text]. This is a convenience property which will take care of getting the tooltip shown if the given string is not `NULL`: [property@Gtk.Widget:has-tooltip] will automatically be set to true and there will be taken care of [signal@Gtk.Widget::query-tooltip] in the default signal handler. Note that if both [property@Gtk.Widget:tooltip-text] and [property@Gtk.Widget:tooltip-markup] are set, the last one wins. How to distribute vertical space if widget gets extra space. Whether to expand vertically. Whether to use the `vexpand` property. Whether the widget is visible. Overrides for width request of the widget. If this is -1, the natural request will be used. Signals that all holders of a reference to the widget should release the reference that they hold. May result in finalization of the widget if all references are released. This signal is not suitable for saving widget state. Emitted when the text direction of a widget changes. the previous text direction Emitted when @widget is hidden. Emitted if keyboard navigation fails. See [method@Gtk.Widget.keynav_failed] for details. true if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard navigation attempt in its parent widget the direction of movement Emitted when @widget is going to be mapped. A widget is mapped when the widget is visible (which is controlled with [property@Gtk.Widget:visible]) and all its parents up to the toplevel widget are also visible. The `::map` signal can be used to determine whether a widget will be drawn, for instance it can resume an animation that was stopped during the emission of [signal@Gtk.Widget::unmap]. Emitted when a widget is activated via a mnemonic. The default handler for this signal activates @widget if @group_cycling is false, or just makes @widget grab focus if @group_cycling is true. true to stop other handlers from being invoked for the event, false to propagate the event further true if there are other widgets with the same mnemonic Emitted when the focus is moved. The `::move-focus` signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Tab</kbd> to move forward, and <kbd>Shift</kbd>+<kbd>Tab</kbd> to move backward. the direction of the focus move Emitted when the widget’s tooltip is about to be shown. This happens when the [property@Gtk.Widget:has-tooltip] property is true and the hover timeout has expired with the cursor hovering above @widget; or emitted when @widget got focus in keyboard mode. Using the given coordinates, the signal handler should determine whether a tooltip should be shown for @widget. If this is the case true should be returned, false otherwise. Note that if @keyboard_mode is true, the values of @x and @y are undefined and should not be used. The signal handler is free to manipulate @tooltip with the therefore destined function calls. true if @tooltip should be shown right now, false otherwise the x coordinate of the cursor position in widget coordinates the y coordinate of the cursor position in widget coordinates true if the tooltip was triggered using the keyboard a `GtkTooltip` Emitted when @widget is associated with a `GdkSurface`. This means that [method@Gtk.Widget.realize] has been called or the widget has been mapped (that is, it is going to be drawn). Emitted when @widget is shown. Emitted when the widget state changes. See [method@Gtk.Widget.get_state_flags]. the previous state flags Emitted when @widget is going to be unmapped. A widget is unmapped when either it or any of its parents up to the toplevel widget have been set as hidden. As `::unmap` indicates that a widget will not be shown any longer, it can be used to, for example, stop an animation on the widget. Emitted when the `GdkSurface` associated with @widget is destroyed. This means that [method@Gtk.Widget.unrealize] has been called or the widget has been unmapped (that is, it is going to be hidden). The type of the callback functions used for activating actions installed with [method@Gtk.WidgetClass.install_action]. The @parameter must match the @parameter_type of the action. the widget to which the action belongs the action name parameter for activation The object class structure needs to be the first element in the widget class structure in order for the class mechanism to work correctly. This allows a GtkWidgetClass pointer to be cast to a GObjectClass pointer. Signal emitted when widget is shown a widget Signal emitted when widget is hidden. a widget Signal emitted when widget is going to be mapped, that is when the widget is visible (which is controlled with gtk_widget_set_visible()) and all its parents up to the toplevel widget are also visible. a widget Signal emitted when widget is going to be unmapped, which means that either it or any of its parents up to the toplevel widget have been set as hidden. a widget Signal emitted when widget is associated with a `GdkSurface`, which means that gtk_widget_realize() has been called or the widget has been mapped (that is, it is going to be drawn). a widget Signal emitted when the GdkSurface associated with widget is destroyed, which means that gtk_widget_unrealize() has been called or the widget has been unmapped (that is, it is going to be hidden). a widget Called when the widget gets added to a `GtkRoot` widget. Must chain up Called when the widget is about to be removed from its `GtkRoot` widget. Must chain up Called to set the allocation, if the widget does not have a layout manager. Signal emitted when the widget state changes, see gtk_widget_get_state_flags(). Signal emitted when the text direction of a widget changes. Called to get the request mode, if the widget does not have a layout manager. This allows a widget to tell its parent container whether it prefers to be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH means the widget prefers to have `GtkWidgetClass.measure()` called first to get the default width (passing a for_size of -1), then again to get the height for said default width. %GTK_SIZE_REQUEST_CONSTANT_SIZE disables any height-for-width or width-for-height geometry management for said widget and is the default return. It’s important to note that any widget which trades height-for-width or width-for-height must respond properly to a for_size value >= -1 passed to `GtkWidgetClass.measure`, for both possible orientations. The `GtkSizeRequestMode` preferred by @widget. a `GtkWidget` instance Called to obtain the minimum and natural size of the widget, if the widget does not have a layout manager. Depending on the orientation parameter, the passed for_size can be interpreted as width or height. A widget will never be allocated less than its minimum size. A `GtkWidget` instance the orientation to measure Size for the opposite of @orientation, i.e. if @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height the widget should be measured with. The %GTK_ORIENTATION_VERTICAL case is analogous. This way, both height-for-width and width-for-height requests can be implemented. If no size is known, -1 can be passed. location to store the minimum size location to store the natural size location to store the baseline position for the minimum size, or -1 to report no baseline location to store the baseline position for the natural size, or -1 to report no baseline Activates the @widget if @group_cycling is %FALSE, and just grabs the focus if @group_cycling is %TRUE. true if the signal has been handled a widget true if there are other widgets with the same mnemonic Causes @widget to have the keyboard focus for the `GtkWindow` it’s inside. true if focus is now inside @widget a widget Vfunc for gtk_widget_child_focus() Sets the focused child of a widget. Must chain up a widget a direct child widget of @widget or `NULL` to unset the focus child Signal emitted when a change of focus is requested Signal emitted if keyboard navigation fails. true if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard navigation attempt in its parent widget a widget direction of focus movement Signal emitted when “has-tooltip” is %TRUE and the hover timeout has expired with the cursor hovering “above” widget; or emitted when widget got focus in keyboard mode. Computes whether a container should give this widget extra space when possible. Vfunc called when the CSS used by widget was changed. Widgets should then discard their caches that depend on CSS and queue resizes or redraws accordingly. The default implementation will take care of this for all the default CSS properties, so implementations must chain up. Emitted when a system setting was changed. Must chain up. Vfunc called when a new snapshot of the widget has to be taken. Vfunc for gtk_widget_contains(). true if @widget contains the point (x, y) the widget to query X coordinate to test, relative to @widget's origin Y coordinate to test, relative to @widget's origin Creates a new shortcut for @widget_class that calls the given @callback with arguments according to @format_string. The arguments and format string must be provided in the same way as with [ctor@GLib.Variant.new]. This function is a convenience wrapper around [method@Gtk.WidgetClass.add_shortcut] and must be called during class initialization. It does not provide for user data, if you need that, you will have to use [method@Gtk.WidgetClass.add_shortcut] with a custom shortcut. the class to add the binding to key value of binding to install key modifier of binding to install the callback to call upon activation `GVariant` format string for arguments arguments, as given by format string Creates a new shortcut for @widget_class that activates the given @action_name with arguments read according to @format_string. The arguments and format string must be provided in the same way as with [ctor@GLib.Variant.new]. This function is a convenience wrapper around [method@Gtk.WidgetClass.add_shortcut] and must be called during class initialization. the class to add the binding to key value of binding to install key modifier of binding to install the action to activate `GVariant` format string for arguments arguments, as given by format string Creates a new shortcut for @widget_class that emits the given action @signal with arguments read according to @format_string. The arguments and format string must be provided in the same way as with [ctor@GLib.Variant.new]. This function is a convenience wrapper around [method@Gtk.WidgetClass.add_shortcut] and must be called during class initialization. the class to add the binding to key value of binding to install key modifier of binding to install the signal to execute `GVariant` format string for arguments arguments, as given by format string Installs a shortcut in @widget_class. Every instance created for @widget_class or its subclasses will inherit this shortcut and trigger it. Shortcuts added this way will be triggered in the [enum@Gtk.PropagationPhase.bubble] phase, which means they may also trigger if child widgets have focus. This function must only be used in class initialization functions otherwise it is not guaranteed that the shortcut will be installed. the class to add the shortcut to the shortcut to add Associates a name to be used in GtkBuilder XML with a symbol. This function is not supported after [method@Gtk.WidgetClass.set_template_scope] has been used on @widget_class. See [method@Gtk.BuilderCScope.add_callback_symbol]. Note that this must be called from a composite widget classes class initializer after calling [method@Gtk.WidgetClass.set_template]. a widget class name of the callback as expected in the template XML the callback symbol Assigns an object declared in the class template XML to be set to a location on a freshly built instance’s private data, or alternatively accessible via [method@Gtk.Widget.get_template_child]. The struct can point either into the public instance, then you should use `G_STRUCT_OFFSET(WidgetType, member)` for @struct_offset, or in the private struct, then you should use `G_PRIVATE_OFFSET(WidgetType, member)`. An explicit strong reference will be held automatically for the duration of your instance’s life cycle, it will be released automatically when `GObjectClass.dispose()` runs on your instance and if a nonzero @struct_offset is specified, then the automatic location in your instance public or private data will be set to `NULL`. You can however access an automated child pointer the first time your classes `GObjectClass.dispose()` runs, or alternatively in [signal@Gtk.Widget::destroy]. If @internal_child is specified, [vfunc@Gtk.Buildable.get_internal_child] will be automatically implemented by the widget class so there is no need to implement it manually. The wrapper macros [func@Gtk.widget_class_bind_template_child], [func@Gtk.widget_class_bind_template_child_internal], [func@Gtk.widget_class_bind_template_child_private] and [func@Gtk.widget_class_bind_template_child_internal_private] might be more convenient to use. Note that this must be called from a composite widget classes class initializer after calling [method@Gtk.WidgetClass.set_template]. a widget class ID of the child defined in the template XML whether the child should be accessible as an “internal-child” when this class is used in GtkBuilder XML The offset into the composite widget’s instance public or private structure where the automated child pointer should be set, or 0 to not assign the pointer Retrieves the accessible role used by the given widget class. Different accessible roles have different states, and are rendered differently by assistive technologies. See also: [method@Gtk.Accessible.get_accessible_role]. the accessible role for the widget class a widget class Retrieves the signal id for the activation signal. The activation signal is set using [method@Gtk.WidgetClass.set_activate_signal]. a signal id, or 0 if the widget class does not specify an activation signal a widget class Gets the name used by this class for matching in CSS code. See [method@Gtk.WidgetClass.set_css_name] for details. the CSS name of the given class class to set the name on Retrieves the type of the [class@Gtk.LayoutManager] used by widgets of class @widget_class. See also: [method@Gtk.WidgetClass.set_layout_manager_type]. type of a `GtkLayoutManager` subclass, or `G_TYPE_INVALID` a widget class Adds an action for all instances of a widget class. This function should be called at class initialization time. Actions installed by this function are stateless. The only state they have is whether they are enabled or not (which can be changed with [method@Gtk.Widget.action_set_enabled]). a widget class a prefixed action name, such as "clipboard.paste" the parameter type callback to use when the action is activated Installs an action called @action_name on @widget_class and binds its state to the value of the @property_name property. This function will perform a few sanity checks on the property selected via @property_name. Namely, the property must exist, must be readable, writable and must not be construct-only. There are also restrictions on the type of the given property, it must be boolean, int, unsigned int, double or string. If any of these conditions are not met, a critical warning will be printed and no action will be added. The state type of the action matches the property type. If the property is boolean, the action will have no parameter and toggle the property value. Otherwise, the action will have a parameter of the same type as the property. a widget class name of the action name of a property in instances of @widget_class or any parent class Returns details about an action that has been installed for @widget_class. See [method@Gtk.WidgetClass.install_action] for details on how to install actions. Note that this function will also return actions defined by parent classes. You can identify those by looking at @owner. true if the action was found a widget class position of the action to query return location for the type where the action was defined return location for the action name return location for the parameter type return location for the property name Sets the accessible role used by the given widget class. Different accessible roles have different states, and are rendered differently by assistive technologies. a widget class the accessible role to use Sets the activation signal for a widget class. The signal will be emitted when calling [method@Gtk.Widget.activate]. The @signal_id must have been registered with [function.GObject.signal_new] or [func@GObject.signal_newv] before calling this function. a widget class the id for the activate signal Sets the activation signal for a widget class. The signal id will by looked up by @signal_name. The signal will be emitted when calling [method@Gtk.Widget.activate]. The @signal_name must have been registered with [function.GObject.signal_new] or [func@GObject.signal_newv] before calling this function. a widget class the name of the activate signal of @widget_type Sets the name to be used for CSS matching of widgets. If this function is not called for a given class, the name set on the parent class is used. By default, `GtkWidget` uses the name "widget". class to set the name on name to use Sets the type to be used for creating layout managers for widgets of @widget_class. The given @type must be a subtype of [class@Gtk.LayoutManager]. This function should only be called from class init functions of widgets. a widget class the object type that implements the `GtkLayoutManager` for @widget_class This should be called at class initialization time to specify the `GtkBuilder` XML to be used to extend a widget. For convenience, [method@Gtk.WidgetClass.set_template_from_resource] is also provided. Note that any class that installs templates must call [method@Gtk.Widget.init_template] in the widget’s instance initializer. a widget class `GBytes` holding the `GtkBuilder` XML A convenience function that calls [method@Gtk.WidgetClass.set_template] with the contents of a resource. Note that any class that installs templates must call [method@Gtk.Widget.init_template] in the widget’s instance initializer. a widget class resource path to load the template from Overrides the default scope to be used when parsing the class template. This function is intended for language bindings. Note that this must be called from a composite widget classes class initializer after calling [method@Gtk.WidgetClass.set_template]. a widget class `GtkBuilderScope` to use when loading the class template A `GdkPaintable` that displays the contents of a widget. `GtkWidgetPaintable` will also take care of the widget not being in a state where it can be drawn (like when it isn't shown) and just draw nothing or where it does not have a size (like when it is hidden) and report no size in that case. Of course, `GtkWidgetPaintable` allows you to monitor widgets for size changes by emitting the [signal@Gdk.Paintable::invalidate-size] signal whenever the size of the widget changes as well as for visual changes by emitting the [signal@Gdk.Paintable::invalidate-contents] signal whenever the widget changes. You can use a `GtkWidgetPaintable` everywhere a `GdkPaintable` is allowed, including using it on a `GtkPicture` (or one of its parents) that it was set on itself via gtk_picture_set_paintable(). The paintable will take care of recursion when this happens. If you do this however, ensure that the [property@Gtk.Picture:can-shrink] property is set to %TRUE or you might end up with an infinitely growing widget. Creates a new widget paintable observing the given widget. a new `GtkWidgetPaintable` a `GtkWidget` Returns the widget that is observed or %NULL if none. the observed widget. a `GtkWidgetPaintable` Sets the widget that should be observed. a `GtkWidgetPaintable` the widget to observe The observed widget or %NULL if none. A toplevel window which can contain other widgets. <picture> <source srcset="window-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkWindow" src="window.png"> </picture> Windows normally have decorations that are under the control of the windowing system and allow the user to manipulate the window (resize it, move it, close it,...). # GtkWindow as GtkBuildable The `GtkWindow` implementation of the [iface@Gtk.Buildable] interface supports setting a child as the titlebar by specifying “titlebar” as the “type” attribute of a `<child>` element. # Shortcuts and Gestures `GtkWindow` supports the following keyboard shortcuts: - <kbd>F10</kbd> activates the menubar, if present. - <kbd>Alt</kbd> makes the mnemonics visible while pressed. The following signals have default keybindings: - [signal@Gtk.Window::activate-default] - [signal@Gtk.Window::activate-focus] - [signal@Gtk.Window::enable-debugging] # Actions `GtkWindow` defines a set of built-in actions: - `default.activate` activates the default widget. - `window.minimize` minimizes the window. - `window.toggle-maximized` maximizes or restores the window. - `window.close` closes the window. # CSS nodes ``` window.background [.csd / .solid-csd / .ssd] [.maximized / .fullscreen / .tiled] ├── <child> ╰── <titlebar child>.titlebar [.default-decoration] ``` `GtkWindow` has a main CSS node with name window and style class .background. Style classes that are typically used with the main CSS node are .csd (when client-side decorations are in use), .solid-csd (for client-side decorations without invisible borders), .ssd (used by mutter when rendering server-side decorations). GtkWindow also represents window states with the following style classes on the main node: .maximized, .fullscreen, .tiled (when supported, also .tiled-top, .tiled-left, .tiled-right, .tiled-bottom). `GtkWindow` subclasses often add their own discriminating style classes, such as .dialog, .popup or .tooltip. Generally, some CSS properties don't make sense on the toplevel window node, such as margins or padding. When client-side decorations without invisible borders are in use (i.e. the .solid-csd style class is added to the main window node), the CSS border of the toplevel window is used for resize drags. In the .csd case, the shadow area outside of the window can be used to resize it. `GtkWindow` adds the .titlebar and .default-decoration style classes to the widget that is added as a titlebar child. # Accessibility `GtkWindow` uses the [enum@Gtk.AccessibleRole.window] role. From GTK 4.12 to 4.18, it used the [enum@Gtk.AccessibleRole.application] role. Creates a new `GtkWindow`. To get an undecorated window (without window borders), use [method@Gtk.Window.set_decorated]. All top-level windows created by this function are stored in an internal top-level window list. This list can be obtained from [func@Gtk.Window.list_toplevels]. Due to GTK keeping a reference to the window internally, this function does not return a reference to the caller. To delete a `GtkWindow`, call [method@Gtk.Window.destroy]. a new `GtkWindow` Returns the fallback icon name for windows. The returned string is owned by GTK and should not be modified. It is only valid until the next call to [func@Gtk.Window.set_default_icon_name]. the fallback icon name for windows Returns the list of all existing toplevel windows. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets or add new ones, be aware that the list of toplevels will change and emit the "items-changed" signal. the list of toplevel widgets Returns the list of all existing toplevel windows. The widgets in the list are not individually referenced. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets, you must call `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first, and then unref all the widgets afterwards. list of toplevel widgets Sets whether the window should request startup notification. By default, after showing the first window, GTK calls [method@Gdk.Toplevel.set_startup_id]. Call this function to disable the automatic startup notification. You might do this if your first window is a splash screen, and you want to delay notification until after your real main window has been shown, for example. In that example, you would disable startup notification temporarily, show your splash screen, then re-enable it so that showing the main window would automatically result in notification. true to automatically do startup notification Sets an icon to be used as fallback. The fallback icon is used for windows that haven't had [method@Gtk.Window.set_icon_name] called on them. the name of the themed icon Opens or closes the [interactive debugger](running.html#interactive-debugging). The debugger offers access to the widget hierarchy of the application and to useful debugging tools. This function allows applications that already use <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>I</kbd> (or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>) for their own key shortcuts to add a different shortcut to open the Inspector. If you are not overriding the default key shortcuts for the Inspector, you should not use this function. true to enable interactive debugging Activates the default widget for the window. Activates the current focused widget within the window. Class handler for the [signal@Window::close-request] signal. Whether the window should be destroyed Class handler for the `GtkWindow::enable-debugging` keybinding signal. Signal gets emitted when the set of accelerators or mnemonics that are associated with window changes. Requests that the window is closed. This is similar to what happens when a window manager close button is clicked. This function can be used with close buttons in custom titlebars. a window Drops the internal reference GTK holds on toplevel windows. the window to destroy Asks to place the window in the fullscreen state. Note that you shouldn’t assume the window is definitely fullscreen afterward, because other entities (e.g. the user or window manager) unfullscreen it again, and not all window managers honor requests to fullscreen windows. If a window is not explicitly fullscreened or unfullscreened before it is shown, the initial state is at the window managers discretion. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications of the [property@Gtk.Window:fullscreened] property. a window Asks to place the window in the fullscreen state on the given monitor. Note that you shouldn't assume the window is definitely fullscreen afterward, or that the windowing system allows fullscreen windows on any given monitor. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications of the [property@Gtk.Window:fullscreened] property. a window which monitor to go fullscreen on Gets the application object associated with the window. the application a window Gets the child widget of the window. the child widget of @window a window Returns whether the window has been set to have decorations. true if the window has been set to have decorations a window Gets the default size of the window. A value of 0 for the width or height indicates that a default size has not been explicitly set for that dimension, so the “natural” size of the window will be used. This function is the recommended way for [saving window state across restarts of applications](https://developer.gnome.org/documentation/tutorials/save-state.html). a window location to store the default width location to store the default height Returns the default widget for @window. the default widget a window Returns whether the window has been set to have a close button. true if the window has been set to have a close button a window Returns whether the window will be destroyed with its transient parent. true if the window will be destroyed with its transient parent a window Retrieves the current focused widget within the window. Note that this is the widget that would have the focus if the toplevel window focused; if the toplevel window is not focused then `gtk_widget_has_focus (widget)` will not be false for the widget. the currently focused widget a window Gets whether “focus rectangles” are supposed to be visible. true if “focus rectangles” are supposed to be visible in this window a window Returns the gravity that is used when changing the window size programmatically. the gravity a window Returns the group for the window. If the window has no group, then the default group is returned. the window group for @window or the default group a window Returns whether this window reacts to <kbd>F10</kbd> presses by activating a menubar it contains. true if the window handles <kbd>F10</kbd> a window Returns whether the window will be hidden instead of destroyed when the close button is clicked. true if the window will be hidden a window Returns the name of the themed icon for the window. the icon name a window Gets whether mnemonics are supposed to be visible. true if mnemonics are supposed to be visible in this window a window Returns whether the window is modal. true if the window is set to be modal and establishes a grab when shown a window Gets whether the user can resize the window. true if the user can resize the window a window Retrieves the title of the window. the title a window Returns the titlebar that has been set with [method@Gtk.Window.set_titlebar]. the titlebar a window Fetches the transient parent for this window. the transient parent a window Returns whether the window has an explicit window group. true if @window has an explicit window group a window Returns whether the window is part of the current active toplevel. The active toplevel is the window receiving keystrokes. The return value is %TRUE if the window is active toplevel itself. You might use this function if you wanted to draw a widget differently in an active window from a widget in an inactive window. true if the window part of the current active window. a window Retrieves the current fullscreen state of the window. Note that since fullscreening is ultimately handled by the window manager and happens asynchronously to an application request, you shouldn’t assume the return value of this function changing immediately (or at all), as an effect of calling [method@Gtk.Window.fullscreen] or [method@Gtk.Window.unfullscreen]. If the window isn't yet mapped, the value returned will whether the initial requested state is fullscreen. whether the window is fullscreen a window Retrieves the current maximized state of the window. Note that since maximization is ultimately handled by the window manager and happens asynchronously to an application request, you shouldn’t assume the return value of this function changing immediately (or at all), as an effect of calling [method@Gtk.Window.maximize] or [method@Gtk.Window.unmaximize]. If the window isn't yet mapped, the value returned will whether the initial requested state is maximized. whether the window is maximized a window Retrieves the current suspended state of the window. A window being suspended means it's currently not visible to the user, for example by being on a inactive workspace, minimized, obstructed. whether the window is suspended a window Asks to maximize the window, so that it fills the screen. Note that you shouldn’t assume the window is definitely maximized afterward, because other entities (e.g. the user or window manager) could unmaximize it again, and not all window managers support maximization. It’s permitted to call this function before showing a window, in which case the window will be maximized when it appears onscreen initially. If a window is not explicitly maximized or unmaximized before it is shown, the initial state is at the window managers discretion. For example, it might decide to maximize a window that almost fills the screen. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications on the [property@Gtk.Window:maximized] property. a window Asks to minimize the window. Note that you shouldn’t assume the window is definitely minimized afterward, because the windowing system might not support this functionality; other entities (e.g. the user or the window manager) could unminimize it again, or there may not be a window manager in which case minimization isn’t possible, etc. It’s permitted to call this function before showing a window, in which case the window will be minimized before it ever appears onscreen. You can track result of this operation via the [property@Gdk.Toplevel:state] property. a window Presents a window to the user. This may mean raising the window in the stacking order, unminimizing it, moving it to the current desktop and/or giving it the keyboard focus (possibly dependent on the user’s platform, window manager and preferences). If @window is hidden, this function also makes it visible. a window Presents a window to the user in response to an user interaction. See [method@Gtk.Window.present] for more details. The timestamp should be gathered when the window was requested to be shown (when clicking a link for example), rather than once the window is ready to be shown. Use [method@Gtk.Window.present] a window the timestamp of the user interaction (typically a button or key press event) which triggered this call Sets or unsets the application object associated with the window. The application will be kept alive for at least as long as it has any windows associated with it (see [method@Gio.Application.hold] for a way to keep it alive without windows). Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it by setting the @application to %NULL. This is equivalent to calling [method@Gtk.Application.remove_window] and/or [method@Gtk.Application.add_window] on the old/new applications as relevant. a window a `GtkApplication` Sets the child widget of the window. a window the child widget Sets whether the window should be decorated. By default, windows are decorated with a title bar, resize controls, etc. Some window managers allow GTK to disable these decorations, creating a borderless window. If you set the decorated property to false using this function, GTK will do its best to convince the window manager not to decorate the window. Depending on the system, this function may not have any effect when called on a window that is already visible, so you should call it before calling [method@Gtk.Widget.show]. On Windows, this function always works, since there’s no window manager policy involved. a window true to decorate the window Sets the default size of a window. The default size of a window is the size that will be used if no other constraints apply. The default size will be updated whenever the window is resized to reflect the new size, unless the window is forced to a size, like when it is maximized or fullscreened. If the window’s minimum size request is larger than the default, the default will be ignored. Setting the default size to a value <= 0 will cause it to be ignored and the natural size request will be used instead. It is possible to do this while the window is showing to "reset" it to its initial size. Unlike [method@Gtk.Widget.set_size_request], which sets a size request for a widget and thus would keep users from shrinking the window, this function only sets the initial size, just as if the user had resized the window themselves. Users can still shrink the window again as they normally would. Setting a default size of -1 means to use the “natural” default size (the size request of the window). If you use this function to reestablish a previously saved window size, note that the appropriate size to save is the one returned by [method@Gtk.Window.get_default_size]. Using the window allocation directly will not work in all circumstances and can lead to growing or shrinking windows. a window width in pixels, or -1 to unset the default width height in pixels, or -1 to unset the default height Sets the default widget. The default widget is the widget that is activated when the user presses <kbd>Enter</kbd> in a dialog (for example). a window widget to be the default Sets whether the window should be deletable. By default, windows have a close button in the window frame. Some window managers allow GTK to disable this button. If you set the deletable property to false using this function, GTK will do its best to convince the window manager not to show a close button. Depending on the system, this function may not have any effect when called on a window that is already visible, so you should call it before calling [method@Gtk.Widget.show]. On Windows, this function always works, since there’s no window manager policy involved. a window true to decorate the window as deletable Sets whether to destroy the window when the transient parent is destroyed. This is useful for dialogs that shouldn’t persist beyond the lifetime of the main window they are associated with, for example. a window whether to destroy the window with its transient parent Sets the display where the window is displayed. If the window is already mapped, it will be unmapped, and then remapped on the new display. a window a display Sets the focus widget. If @focus is not the current focus widget, and is focusable, sets it as the focus widget for the window. If @focus is %NULL, unsets the focus widget for this window. To set the focus to a particular widget in the toplevel, it is usually more convenient to use [method@Gtk.Widget.grab_focus] instead of this function. a window the new focus widget Sets whether “focus rectangles” are supposed to be visible. This property is maintained by GTK based on user input, and should not be set by applications. a window the new value Sets the gravity that is used when changing the window size programmatically. a window the new gravity Sets whether this window should react to <kbd>F10</kbd> presses by activating a menubar it contains. a window true to make @window handle <kbd>F10</kbd> Sets whether clicking the close button will hide the window instead of destroying it. a window whether to hide the window when it is closed Sets the icon for the window from a named themed icon. See the docs for [class@Gtk.IconTheme] for more details. On some platforms, the window icon is not used at all. Note that this has nothing to do with the WM_ICON_NAME property which is mentioned in the ICCCM. a window the name of the themed icon Sets whether mnemonics are supposed to be visible. This property is maintained by GTK based on user input, and should not be set by applications. a window the new value Sets a window modal or non-modal. Modal windows prevent interaction with other windows in the same application. To keep modal dialogs on top of main application windows, use [method@Gtk.Window.set_transient_for] to make the dialog transient for the parent; most window managers will then disallow lowering the dialog below the parent. a window whether the window is modal Sets whether the user can resize a window. Windows are user resizable by default. a window true if the user can resize this window Sets the startup notification ID. Startup notification identifiers are used by desktop environment to track application startup, to provide user feedback and other features. This function changes the corresponding property on the underlying `GdkSurface`. Normally, startup identifier is managed automatically and you should only use this function in special cases like transferring focus from other processes. You should use this function before calling [method@Gtk.Window.present] or any equivalent function generating a window map event. This function is only useful on Wayland or X11, not with other GDK backends. a window a string with startup-notification identifier Sets the title of the window. The title of a window will be displayed in its title bar; on the X Window System, the title bar is rendered by the window manager so exactly how the title appears to users may vary according to a user’s exact configuration. The title should help a user distinguish this window from other windows they may have open. A good title might include the application name and current document filename, for example. Passing `NULL` does the same as setting the title to an empty string. a window title of the window Sets a custom titlebar for the window. A typical widget used here is [class@Gtk.HeaderBar], as it provides various features expected of a titlebar while allowing the addition of child widgets to it. If you set a custom titlebar, GTK will do its best to convince the window manager not to put its own titlebar on the window. Depending on the system, this function may not work for a window that is already visible, so you set the titlebar before calling [method@Gtk.Widget.show]. a window the widget to use as titlebar Sets a transient parent for the window. Dialog windows should be set transient for the main application window they were spawned from. This allows window managers to e.g. keep the dialog on top of the main window, or center the dialog over the main window. [ctor@Gtk.Dialog.new_with_buttons] and other convenience functions in GTK will sometimes call this function on your behalf. Passing `NULL` for @parent unsets the current transient window. On Windows, this function puts the child window on top of the parent, much as the window manager would have done on X. a window parent window Asks to remove the fullscreen state for the window, and return to its previous state. Note that you shouldn’t assume the window is definitely not fullscreen afterward, because other entities (e.g. the user or window manager) could fullscreen it again, and not all window managers honor requests to unfullscreen windows; normally the window will end up restored to its normal state. Just don’t write code that crashes if not. If a window is not explicitly fullscreened or unfullscreened before it is shown, the initial state is at the window managers discretion. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications of the [property@Gtk.Window:fullscreened] property. a window Asks to unmaximize the window. Note that you shouldn’t assume the window is definitely unmaximized afterward, because other entities (e.g. the user or window manager) maximize it again, and not all window managers honor requests to unmaximize. If a window is not explicitly maximized or unmaximized before it is shown, the initial state is at the window managers discretion. For example, it might decide to maximize a window that almost fills the screen. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications on the [property@Gtk.Window:maximized] property. a window Asks to unminimize the window. Note that you shouldn’t assume the window is definitely unminimized afterward, because the windowing system might not support this functionality; other entities (e.g. the user or the window manager) could minimize it again, or there may not be a window manager in which case minimization isn’t possible, etc. You can track result of this operation via the [property@Gdk.Toplevel:state] property. a window The `GtkApplication` associated with the window. The application will be kept alive for at least as long as it has any windows associated with it (see g_application_hold() for a way to keep it alive without windows). Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it by setting the this property to `NULL`. The child widget. Whether the window should have a frame (also known as *decorations*). The default height of the window. The default widget. The default width of the window. Whether the window frame should have a close button. If this window should be destroyed when the parent is destroyed. The display that will display this window. Whether 'focus rectangles' are currently visible in this window. This property is maintained by GTK based on user input and should not be set by applications. The focus widget. Whether the window is fullscreen. Setting this property is the equivalent of calling [method@Gtk.Window.fullscreen] or [method@Gtk.Window.unfullscreen]; either operation is asynchronous, which means you will need to connect to the ::notify signal in order to know whether the operation was successful. The gravity to use when resizing the window programmatically. Gravity describes which point of the window we want to keep fixed (meaning that the window will grow in the opposite direction). For example, a gravity of `GTK_WINDOW_GRAVITY_TOP_RIGHT` means that we want the to fix top right corner of the window. Whether the window frame should handle <kbd>F10</kbd> for activating menubars. If this window should be hidden instead of destroyed when the user clicks the close button. Specifies the name of the themed icon to use as the window icon. See [class@Gtk.IconTheme] for more details. Whether the toplevel is the currently active window. Whether the window is maximized. Setting this property is the equivalent of calling [method@Gtk.Window.maximize] or [method@Gtk.Window.unmaximize]; either operation is asynchronous, which means you will need to connect to the ::notify signal in order to know whether the operation was successful. Whether mnemonics are currently visible in this window. This property is maintained by GTK based on user input, and should not be set by applications. If true, the window is modal. If true, users can resize the window. A write-only property for setting window's startup notification identifier. Whether the window is suspended. See [method@Gtk.Window.is_suspended] for details about what suspended means. The title of the window. The titlebar widget. The transient parent of the window. Emitted when the user activates the default widget. This is a [keybinding signal](class.SignalAction.html). The keybindings for this signal are all forms of the <kbd>Enter</kbd> key. Emitted when the user activates the currently focused widget of @window. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>␣</kbd>. Emitted when the user clicks on the close button of the window. true to stop other handlers from being invoked for the signal Emitted when the user enables or disables interactive debugging. When @toggle is true, interactive debugging is toggled on or off, when it is false, the debugger will be pointed at the widget under the pointer. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>I</kbd> and <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>. true if the key binding was handled toggle the debugger Emitted when the set of accelerators or mnemonics that are associated with the window changes. Use [class@Gtk.Shortcut] and [class@Gtk.EventController] to implement keyboard shortcuts The parent class. Activates the current focused widget within the window. Activates the default widget for the window. Signal gets emitted when the set of accelerators or mnemonics that are associated with window changes. Class handler for the `GtkWindow::enable-debugging` keybinding signal. Whether the window should be destroyed Shows window frame controls. Typical window frame controls are minimize, maximize and close buttons, and the window icon. <picture> <source srcset="windowcontrols-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkWindowControls" src="windowcontrols.png"> </picture> `GtkWindowControls` only displays start or end side of the controls (see [property@Gtk.WindowControls:side]), so it's intended to be always used in pair with another `GtkWindowControls` for the opposite side, for example: ```xml <object class="GtkBox"> <child> <object class="GtkWindowControls"> <property name="side">start</property> </object> </child> ... <child> <object class="GtkWindowControls"> <property name="side">end</property> </object> </child> </object> ``` # CSS nodes ``` windowcontrols ├── [image.icon] ├── [button.minimize] ├── [button.maximize] ╰── [button.close] ``` A `GtkWindowControls`' CSS node is called windowcontrols. It contains subnodes corresponding to each title button. Which of the title buttons exist and where they are placed exactly depends on the desktop environment and [property@Gtk.WindowControls:decoration-layout] value. When [property@Gtk.WindowControls:empty] is true, it gets the .empty style class. # Accessibility `GtkWindowControls` uses the [enum@Gtk.AccessibleRole.group] role. Creates a new `GtkWindowControls`. a new `GtkWindowControls` the side Gets the decoration layout of this window controls widget the decoration layout a window controls widget Gets whether the widget has any window buttons. true if the widget has window buttons a window controls widget Gets the side to which this window controls widget belongs. the side a window controls widget Returns whether platform native window controls are shown. true if native window controls are shown a window controls widget Sets the decoration layout for the title buttons. This overrides the [property@Gtk.Settings:gtk-decoration-layout] setting. The format of the string is button names, separated by commas. A colon separates the buttons that should appear on the left from those on the right. Recognized button names are minimize, maximize, close and icon (the window icon). For example, “icon:minimize,maximize,close” specifies a icon on the left, and minimize, maximize and close buttons on the right. If [property@Gtk.WindowControls:side] value is [enum@Gtk.PackType.start], @self will display the part before the colon, otherwise after that. a window controls widget a decoration layout, or `NULL` to unset the layout Determines which part of decoration layout the window controls widget uses. See [property@Gtk.WindowControls:decoration-layout]. a window controls widget a side Sets whether platform native window controls are used. This option shows the "stoplight" buttons on macOS. For Linux, this option has no effect. See also [Using GTK on Apple macOS](osx.html?native-window-controls). a window_controls widget true to show native window controls The decoration layout for window buttons. If this property is not set, the [property@Gtk.Settings:gtk-decoration-layout] setting is used. Whether the widget has any window buttons. Whether the widget shows start or end side of the decoration layout. See [property@Gtk.WindowControls:decoration_layout]. Whether to show platform native close/minimize/maximize buttons. For macOS, the [property@Gtk.HeaderBar:decoration-layout] property controls the use of native window controls. On other platforms, this option has no effect. See also [Using GTK on Apple macOS](osx.html?native-window-controls). Determines which point or edge of a window is meant to remain fixed when a window changes size. The top left corner The top edge The top right corner The left edge The center pointer The right edge The bottom left corner the bottom edge The bottom right corner The top left or top right corner, depending on the text direction The top right or top left corner, depending on the text direction The left or right edge, depending on the text direction The right or left edge, depending on the text direction The bottom left or top right corner, depending on the text direction The bottom right or top left corner, depending on the text direction Creates groups of windows that behave like separate applications. It achieves this by limiting the effect of GTK grabs and modality to windows in the same group. A window can be a member in at most one window group at a time. Windows that have not been explicitly assigned to a group are implicitly treated like windows of the default window group. `GtkWindowGroup` objects are referenced by each window in the group, so once you have added all windows to a `GtkWindowGroup`, you can drop the initial reference to the window group with g_object_unref(). If the windows in the window group are subsequently destroyed, then they will be removed from the window group and drop their references on the window group; when all window have been removed, the window group will be freed. Creates a new `GtkWindowGroup` object. Modality of windows only affects windows within the same `GtkWindowGroup`. a new `GtkWindowGroup`. Adds a window to a `GtkWindowGroup`. a `GtkWindowGroup` the `GtkWindow` to add Returns a list of the `GtkWindows` that belong to @window_group. A newly-allocated list of windows inside the group. a `GtkWindowGroup` Removes a window from a `GtkWindowGroup`. a `GtkWindowGroup` the `GtkWindow` to remove Implements titlebar functionality for a window. When added into a window, it can be dragged to move the window, and it implements the right click, double click and middle click behaviors that are expected of a titlebar. # CSS nodes `GtkWindowHandle` has a single CSS node with the name `windowhandle`. # Accessibility Until GTK 4.10, `GtkWindowHandle` used the [enum@Gtk.AccessibleRole.group] role. Starting from GTK 4.12, `GtkWindowHandle` uses the [enum@Gtk.AccessibleRole.generic] role. Creates a new `GtkWindowHandle`. a new `GtkWindowHandle`. Gets the child widget of @self. the child widget of @self a `GtkWindowHandle` Sets the child widget of @self. a `GtkWindowHandle` the child widget The child widget. Describes a type of line wrapping. do not wrap lines; just make the text area wider wrap text, breaking lines anywhere the cursor can appear (between characters, usually - if you want to be technical, between graphemes, see pango_get_log_attrs()) wrap text, breaking lines in between words wrap text, breaking lines in between words, or if that is not enough, also between graphemes Generates an accessible description of an accelerator. This function is similar to [func@Gtk.accelerator_get_label] but it is meant for accessibility layers labels rather than user-facing labels. The output of this function is fit for [enum@Gtk.AccessibleProperty.KEY_SHORTCUTS]. For more information, see the [WAI-ARIA](https://www.w3.org/TR/wai-aria/#aria-keyshortcuts) reference. a newly-allocated string representing the accelerator accelerator keyval accelerator modifier mask Gets the modifier mask. The modifier mask determines which modifiers are considered significant for keyboard accelerators. This includes all keyboard modifiers except for `GDK_LOCK_MASK`. the modifier mask for accelerators Converts an accelerator keyval and modifier mask into a string which can be used to represent the accelerator to the user. a newly-allocated string representing the accelerator accelerator keyval accelerator modifier mask Converts an accelerator keyval and modifier mask into a string that can be displayed to the user. The string may be translated. This function is similar to [func@Gtk.accelerator_get_label], but handling keycodes. This is only useful for system-level components, applications should use [func@Gtk.accelerator_get_label] instead. a newly-allocated string representing the accelerator a `GdkDisplay` accelerator keyval accelerator keycode accelerator modifier mask Converts an accelerator keyval and modifier mask into a string that can be parsed by [func@Gtk.accelerator_parse]. For example, if you pass in `GDK_KEY_q` and `GDK_CONTROL_MASK`, this function returns `<Control>q`. If you need to display accelerators in the user interface, see [func@Gtk.accelerator_get_label]. a newly-allocated accelerator name accelerator keyval accelerator modifier mask Converts an accelerator keyval and modifier mask into a string that can be parsed by [func@Gtk.accelerator_parse_with_keycode]. This is similar to [func@Gtk.accelerator_name] but handling keycodes. This is only useful for system-level components, applications should use [func@Gtk.accelerator_name] instead. a newly allocated accelerator name. a `GdkDisplay` accelerator keyval accelerator keycode accelerator modifier mask Parses a string representing an accelerator. The format looks like “`<Control>a`” or “`<Shift><Alt>F1`”. The parser is fairly liberal and allows lower or upper case, and also abbreviations such as “`<Ctl>`” and “`<Ctrl>`”. Key names are parsed using [func@Gdk.keyval_from_name]. For character keys the name is not the symbol, but the lowercase name, e.g. one would use “`<Ctrl>minus`” instead of “`<Ctrl>-`”. Modifiers are enclosed in angular brackets `<>`, and match the [flags@Gdk.ModifierType] mask: - `<Shift>` for `GDK_SHIFT_MASK` - `<Ctrl>` for `GDK_CONTROL_MASK` - `<Alt>` for `GDK_ALT_MASK` - `<Meta>` for `GDK_META_MASK` - `<Super>` for `GDK_SUPER_MASK` - `<Hyper>` for `GDK_HYPER_MASK` If the parse operation fails, @accelerator_key and @accelerator_mods will be set to 0 (zero). whether parsing succeeded string representing an accelerator return location for accelerator keyval return location for accelerator modifier mask Parses a string representing an accelerator. This is similar to [func@Gtk.accelerator_parse] but handles keycodes as well. This is only useful for system-level components, applications should use [func@Gtk.accelerator_parse] instead. If @accelerator_codes is given and the result stored in it is non-%NULL, the result must be freed with g_free(). If a keycode is present in the accelerator and no @accelerator_codes is given, the parse will fail. If the parse fails, @accelerator_key, @accelerator_mods and @accelerator_codes will be set to 0 (zero). true if parsing succeeded string representing an accelerator the `GdkDisplay` to look up @accelerator_codes in return location for accelerator keyval return location for accelerator keycodes return location for accelerator modifier mask Determines whether a given keyval and modifier mask constitute a valid keyboard accelerator. For example, the `GDK_KEY_a` keyval plus `GDK_CONTROL_MASK` mask is valid, and matches the “Ctrl+a” accelerator. But, you can't, for instance, use the `GDK_KEY_Control_L` keyval as an accelerator. true if the accelerator is valid a GDK keyval modifier mask Initializes @value with the appropriate type for the @property. This function is mostly meant for language bindings, in conjunction with gtk_accessible_update_property_value(). a `GtkAccessibleProperty` an uninitialized `GValue` Initializes @value with the appropriate type for the @relation. This function is mostly meant for language bindings, in conjunction with gtk_accessible_update_relation_value(). a `GtkAccessibleRelation` an uninitialized `GValue` Initializes @value with the appropriate type for the @state. This function is mostly meant for language bindings, in conjunction with gtk_accessible_update_relation_state(). a `GtkAccessibleState` an uninitialized `GValue` Initializes @iter to point to @target. If @target is not found, finds the next value after it. If no value >= @target exists in @set, this function returns %FALSE. %TRUE if a value was found. a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` target value to start iterating at Set to the found value in @set Initializes an iterator for @set and points it to the first value in @set. If @set is empty, %FALSE is returned and @value is set to %G_MAXUINT. %TRUE if @set isn't empty. a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` Set to the first value in @set Initializes an iterator for @set and points it to the last value in @set. If @set is empty, %FALSE is returned. %TRUE if @set isn't empty. a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` Set to the last value in @set Adds the @callback to the scope of @builder under its own name. This is a convenience wrapper of [method@Gtk.BuilderCScope.add_callback_symbol]. a `GtkBuilderCScope` The callback pointer Registers an error quark for [class@Gtk.Builder] errors. the error quark Checks that the GTK library in use is compatible with the given version. Generally you would pass in the constants %GTK_MAJOR_VERSION, %GTK_MINOR_VERSION, %GTK_MICRO_VERSION as the three arguments to this function; that produces a check that the library in use is compatible with the version of GTK the application or module was compiled against. Compatibility is defined by two things: first the version of the running library is newer than the version @required_major.required_minor.@required_micro. Second the running library must be binary compatible with the version @required_major.required_minor.@required_micro (same major version.) This function is primarily for GTK modules; the module can call this function to check that it wasn’t loaded into an incompatible version of GTK. However, such a check isn’t completely reliable, since the module may be linked against an old version of GTK and calling the old version of gtk_check_version(), but still get loaded into an application using a newer version of GTK. %NULL if the GTK library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by GTK and should not be modified or freed. the required major version the required minor version the required micro version Registers an error quark for VFL error parsing. the error quark Registers an error quark for CSS parsing errors. the error quark Registers an error quark for CSS parsing warnings. the warning quark Registers an error quark for an operation that requires a dialog if necessary. the error quark Prevents GTK from using the specified portals. This should only be used in portal implementations, apps must not call it. a %NULL-terminated array of portal interface names to disable Prevents GTK from using portals. This is equivalent to setting `GDK_DEBUG=no-portals` in the environment. This should only be used in portal implementations, apps must not call it. Prevents [func@Gtk.init] and [func@Gtk.init_check] from calling `setlocale()`. You would want to use this function if you wanted to set the locale for your program to something other than the user’s locale, or if you wanted to set different values for different locale categories. Most programs should not need to call this function. Distributes @extra_space to child @sizes by bringing smaller children up to natural size first. The remaining space will be added to the @minimum_size member of the `GtkRequestedSize` struct. If all sizes reach their natural size then the remaining space is returned. The remainder of @extra_space after redistributing space to @sizes. Extra space to redistribute among children after subtracting minimum sizes and any child padding from the overall allocation Number of requests to fit into the allocation An array of structs with a client pointer and a minimum/natural size in the orientation of the allocation. Gets a property of the `GtkEditable` delegate for @object. This is helper function that should be called in the `get_property` function of your `GtkEditable` implementation, before handling your own properties. %TRUE if the property was found a `GObject` a property ID value to set the `GParamSpec` for the property Sets a property on the `GtkEditable` delegate for @object. This is a helper function that should be called in the `set_property` function of your `GtkEditable` implementation, before handling your own properties. %TRUE if the property was found a `GObject` a property ID value to set the `GParamSpec` for the property Overrides the `GtkEditable` properties for @class. This is a helper function that should be called in class_init, after installing your own properties. Note that your class must have "text", "cursor-position", "selection-bound", "editable", "width-chars", "max-width-chars", "xalign" and "enable-undo" properties for this function to work. To handle the properties in your set_property and get_property functions, you can either use [func@Gtk.Editable.delegate_set_property] and [func@Gtk.Editable.delegate_get_property] (if you are using a delegate), or remember the @first_prop offset and add it to the values in the [enum@Gtk.EditableProperties] enumeration to get the property IDs for these properties. the number of properties that were installed a `GObjectClass` property ID to use for the first property Calls a function for all printers that are known to GTK. If @func returns true, the enumeration is stopped. a function to call for each printer user data to pass to @func function to call if @data is no longer needed if true, wait in a recursive mainloop until all printers are enumerated; otherwise return early Registers an error quark for `GtkFileChooser` errors. The error quark used for `GtkFileChooser` errors. Returns the binary age as passed to `libtool`. If `libtool` means nothing to you, don't worry about it. the binary age of the GTK library Returns the GTK debug flags that are currently active. This function is intended for GTK modules that want to adjust their debug output based on GTK debug flags. the GTK debug flags. Returns the `PangoLanguage` for the default language currently in effect. Note that this can change over the life of an application. The default language is derived from the current locale. It determines, for example, whether GTK uses the right-to-left or left-to-right text direction. This function is equivalent to [func@Pango.Language.get_default]. See that function for details. the default language Returns the interface age as passed to `libtool`. If `libtool` means nothing to you, don't worry about it. the interface age of the GTK library Gets the direction of the current locale. This is the expected reading direction for text and UI. This function depends on the current locale being set with `setlocale()` and will default to setting the `GTK_TEXT_DIR_LTR` direction otherwise. `GTK_TEXT_DIR_NONE` will never be returned. GTK sets the default text direction according to the locale during [func@Gtk.init], and you should normally use [method@Gtk.Widget.get_direction] or [func@Gtk.Widget.get_default_direction] to obtain the current direction. This function is only needed rare cases when the locale is changed after GTK has already been initialized. In this case, you can use it to update the default text direction as follows: ```c #include <locale.h> static void update_locale (const char *new_locale) { setlocale (LC_ALL, new_locale); gtk_widget_set_default_direction (gtk_get_locale_direction ()); } ``` the direction of the current locale Returns the major version number of the GTK library. For example, in GTK version 3.1.5 this is 3. This function is in the library, so it represents the GTK library your code is running against. Contrast with the %GTK_MAJOR_VERSION macro, which represents the major version of the GTK headers you have included when compiling your code. the major version number of the GTK library Returns the micro version number of the GTK library. For example, in GTK version 3.1.5 this is 5. This function is in the library, so it represents the GTK library your code is are running against. Contrast with the %GTK_MICRO_VERSION macro, which represents the micro version of the GTK headers you have included when compiling your code. the micro version number of the GTK library Returns the minor version number of the GTK library. For example, in GTK version 3.1.5 this is 1. This function is in the library, so it represents the GTK library your code is are running against. Contrast with the %GTK_MINOR_VERSION macro, which represents the minor version of the GTK headers you have included when compiling your code. the minor version number of the GTK library GTK supports Drag-and-Drop in tree views with a high-level and a low-level API. The low-level API consists of the GTK DND API, augmented by some treeview utility functions: gtk_tree_view_set_drag_dest_row(), gtk_tree_view_get_drag_dest_row(), gtk_tree_view_get_dest_row_at_pos(), gtk_tree_view_create_row_drag_icon(), gtk_tree_set_row_drag_data() and gtk_tree_get_row_drag_data(). This API leaves a lot of flexibility, but nothing is done automatically, and implementing advanced features like hover-to-open-rows or autoscrolling on top of this API is a lot of work. On the other hand, if you write to the high-level API, then all the bookkeeping of rows is done for you, as well as things like hover-to-open and auto-scroll, but your models have to implement the `GtkTreeDragSource` and `GtkTreeDragDest` interfaces. Converts a color from HSV space to RGB. Input values must be in the [0.0, 1.0] range; output values will be in the same range. Hue Saturation Value Return value for the red component Return value for the green component Return value for the blue component Registers an error quark for [class@Gtk.IconTheme] errors. the error quark Initializes GTK. This function must be called before using any other GTK functions in your GUI applications. It will initialize everything needed to operate the toolkit. In particular, it will open the default display (see [func@Gdk.Display.get_default]). If you are using [class@Gtk.Application], you usually don't have to call this function; the [vfunc@Gio.Application.startup] handler does it for you. Though, if you are using `GApplication` methods that will be invoked before `startup`, such as `local_command_line`, you may need to initialize GTK explicitly. This function will terminate your program if it was unable to initialize the windowing system for some reason. If you want your program to fall back to a textual interface, call [func@Gtk.init_check] instead. GTK calls `signal (SIGPIPE, SIG_IGN)` during initialization, to ignore SIGPIPE signals, since these are almost never wanted in graphical applications. If you do need to handle SIGPIPE for some reason, reset the handler after gtk_init(), but notice that other libraries (e.g. libdbus or gvfs) might do similar things. Initializes GTK. This function does the same work as [func@Gtk.init] with only a single change: It does not terminate the program if the windowing system can’t be initialized. Instead it returns false on failure. This way the application can fall back to some other means of communication with the user - for example a curses or command line interface. true if the windowing system has been successfully initialized, false otherwise Returns whether GTK has been initialized. See [func@Gtk.init]. the initialization status Finds the `GtkNative` associated with the surface. the `GtkNative` that is associated with @surface a `GdkSurface` Converts the result of a `GCompareFunc` like strcmp() to a `GtkOrdering` value. the corresponding `GtkOrdering` Result of a comparison function Returns the name of the default paper size, which depends on the current locale. the name of the default paper size. The string is owned by GTK and should not be modified. Creates a list of known paper sizes. a newly allocated list of newly allocated `GtkPaperSize` objects whether to include custom paper sizes as defined in the page setup dialog Creates a new `GParamSpec` instance for a property holding a `GtkExpression`. See `g_param_spec_internal()` for details on the property strings. a newly created property specification canonical name of the property a user-readable name for the property a user-readable description of the property flags for the property Registers an error quark for `GtkPrintOperation` if necessary. The error quark used for `GtkPrintOperation` errors. Runs a page setup dialog, letting the user modify the values from @page_setup. If the user cancels the dialog, the returned `GtkPageSetup` is identical to the passed in @page_setup, otherwise it contains the modifications done in the dialog. Note that this function may use a recursive mainloop to show the page setup dialog. See [func@Gtk.print_run_page_setup_dialog_async] if this is a problem. a new `GtkPageSetup` transient parent an existing `GtkPageSetup` a `GtkPrintSettings` Runs a page setup dialog, letting the user modify the values from @page_setup. In contrast to [func@Gtk.print_run_page_setup_dialog], this function returns after showing the page setup dialog on platforms that support this, and calls @done_cb from a signal handler for the ::response signal of the dialog. transient parent an existing `GtkPageSetup` a `GtkPrintSettings` a function to call when the user saves the modified page setup user data to pass to @done_cb Registers an error quark for [class@RecentManager] errors. the error quark Renders an activity indicator (such as in `GtkSpinner`). The state %GTK_STATE_FLAG_CHECKED determines whether there is activity going on. a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders an arrow pointing to @angle. Typical arrow rendering at 0, 1⁄2 π;, π; and 3⁄2 π: ![](arrows.png) a `GtkStyleContext` a `cairo_t` arrow angle from 0 to 2 * %G_PI, being 0 the arrow pointing to the north X origin of the render area Y origin of the render area square side for render area Renders the background of an element. Typical background rendering, showing the effect of `background-image`, `border-width` and `border-radius`: ![](background.png) a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a checkmark (as in a `GtkCheckButton`). The %GTK_STATE_FLAG_CHECKED state determines whether the check is on or off, and %GTK_STATE_FLAG_INCONSISTENT determines whether it should be marked as undefined. Typical checkmark rendering: ![](checks.png) a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders an expander (as used in `GtkTreeView` and `GtkExpander`) in the area defined by @x, @y, @width, @height. The state %GTK_STATE_FLAG_CHECKED determines whether the expander is collapsed or expanded. Typical expander rendering: ![](expanders.png) a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a focus indicator on the rectangle determined by @x, @y, @width, @height. Typical focus rendering: ![](focus.png) a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a frame around the rectangle defined by @x, @y, @width, @height. Examples of frame rendering, showing the effect of `border-image`, `border-color`, `border-width`, `border-radius` and junctions: ![](frames.png) a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a handle (as in `GtkPaned` and `GtkWindow`’s resize grip), in the rectangle determined by @x, @y, @width, @height. Handles rendered for the paned and grip classes: ![](handles.png) a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders the icon in @texture at the specified @x and @y coordinates. This function will render the icon in @texture at exactly its size, regardless of scaling factors, which may not be appropriate when drawing on displays with high pixel densities. a `GtkStyleContext` a `cairo_t` a `GdkTexture` containing the icon to draw X position for the @texture Y position for the @texture Renders @layout on the coordinates @x, @y a `GtkStyleContext` a `cairo_t` X origin Y origin the `PangoLayout` to render Renders a line from (x0, y0) to (x1, y1). a `GtkStyleContext` a `cairo_t` X coordinate for the origin of the line Y coordinate for the origin of the line X coordinate for the end of the line Y coordinate for the end of the line Renders an option mark (as in a radio button), the %GTK_STATE_FLAG_CHECKED state will determine whether the option is on or off, and %GTK_STATE_FLAG_INCONSISTENT whether it should be marked as undefined. Typical option mark rendering: ![](options.png) a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Converts a color from RGB space to HSV. Input values must be in the [0.0, 1.0] range; output values will be in the same range. Red Green Blue Return value for the hue component Return value for the saturation component Return value for the value component Sets the GTK debug flags. the debug flags to set A convenience function for showing an application’s about dialog. The constructed dialog is associated with the parent window and reused for future invocations of this function. the parent top-level window the name of the first property value of first property, followed by more pairs of property name and value, `NULL`-terminated This function launches the default application for showing a given uri, or shows an error dialog if that fails. Use [method@Gtk.FileLauncher.launch] or [method@Gtk.UriLauncher.launch] instead parent window the uri to show timestamp from the event that triggered this call, or %GDK_CURRENT_TIME This function launches the default application for showing a given uri. The @callback will be called when the launch is completed. This is the recommended call to be used as it passes information necessary for sandbox helpers to parent their dialogs properly. Use [method@Gtk.FileLauncher.launch] or [method@Gtk.UriLauncher.launch] instead parent window the uri to show timestamp from the event that triggered this call, or %GDK_CURRENT_TIME a `GCancellable` to cancel the launch a callback to call when the action is complete data to pass to @callback Finishes the gtk_show_uri() call and returns the result of the operation. Use [method@Gtk.FileLauncher.launch] or [method@Gtk.UriLauncher.launch] instead %TRUE if the URI was shown successfully. Otherwise, %FALSE is returned and @error is set the `GtkWindow` passed to gtk_show_uri() `GAsyncResult` that was passed to @callback Returns context information about what XML attribute the parsing error occurred in. the attribute name an error in the [error@Gtk.SvgError] domain Returns context information about what XML element the parsing error occurred in. the element name an error in the [error@Gtk.SvgError] domain Returns context information about the end position in the document where the parsing error occurred. the [struct@Gtk.SvgLocation] an error in the [error@Gtk.SvgError] domain Returns context information about the start position in the document where the parsing error occurred. the [struct@Gtk.SvgLocation] an error in the [error@Gtk.SvgError] domain Checks whether a `GtkAccessible` implementation has its accessible property set to the expected value, and raises an assertion if the condition is not satisfied. a `GtkAccessible` a `GtkAccessibleProperty` the value of @property Checks whether a `GtkAccessible` implementation has its accessible relation set to the expected value, and raises an assertion if the condition is not satisfied. a `GtkAccessible` a `GtkAccessibleRelation` the expected value of @relation Checks whether a `GtkAccessible` implementation has the given @role, and raises an assertion if the condition is failed. a `GtkAccessible` a `GtkAccessibleRole` Checks whether a `GtkAccessible` implementation has its accessible state set to the expected value, and raises an assertion if the condition is not satisfied. a `GtkAccessible` a `GtkAccessibleRelation` the expected value of @state Prints an assertion message for gtk_test_accessible_assert_role(). a domain a file name the line in @file a function name in @file the expression being tested a `GtkAccessible` the expected `GtkAccessibleRole` the actual `GtkAccessibleRole` Checks whether the accessible @property of @accessible is set to a specific value. the value of the accessible property a `GtkAccessible` a `GtkAccessibleProperty` the expected value of @property Checks whether the accessible @relation of @accessible is set to a specific value. the value of the accessible relation a `GtkAccessible` a `GtkAccessibleRelation` the expected value of @relation Checks whether the accessible @state of @accessible is set to a specific value. the value of the accessible state a `GtkAccessible` a `GtkAccessibleState` the expected value of @state Checks whether the `GtkAccessible` has @property set. %TRUE if the @property is set in the @accessible a `GtkAccessible` a `GtkAccessibleProperty` Checks whether the `GtkAccessible` has @relation set. %TRUE if the @relation is set in the @accessible a `GtkAccessible` a `GtkAccessibleRelation` Checks whether the `GtkAccessible:accessible-role` of the accessible is @role. %TRUE if the role matches a `GtkAccessible` a `GtkAccessibleRole` Checks whether the `GtkAccessible` has @state set. %TRUE if the @state is set in the @accessible a `GtkAccessible` a `GtkAccessibleState` This function is used to initialize a GTK test program. It will in turn call g_test_init() and gtk_init() to properly initialize the testing framework and graphical toolkit. It’ll also set the program’s locale to “C”. This is done to make test program environments as deterministic as possible. Like gtk_init() and g_test_init(), any known arguments will be processed and stripped from @argc and @argv. Address of the `argc` parameter of the main() function. Changed if any arguments were handled. Address of the `argv` parameter of main(). Any parameters understood by g_test_init() or gtk_init() are stripped before return. currently unused Return the type ids that have been registered after calling gtk_test_register_all_types(). 0-terminated array of type ids location to store number of types Force registration of all core GTK object types. This allows to refer to any of those object types via g_type_from_name() after calling this function. Enters the main loop and waits for @widget to be “drawn”. In this context that means it waits for the frame clock of @widget to have run a full styling, layout and drawing cycle. This function is intended to be used for syncing with actions that depend on @widget relayouting or on interaction with the display server. the widget to wait for Creates a content provider for dragging @path from @tree_model. Use list models instead a new `GdkContentProvider` a `GtkTreeModel` a row in @tree_model Obtains a @tree_model and @path from value of target type %GTK_TYPE_TREE_ROW_DATA. The returned path must be freed with gtk_tree_path_free(). Use list models instead %TRUE if @selection_data had target type %GTK_TYPE_TREE_ROW_DATA is otherwise valid a `GValue` a `GtkTreeModel` row in @tree_model Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::row-deleted signal. a `GObject` the path position that was deleted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::row-inserted signal. a `GObject` the row position that was inserted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::rows-reordered signal. a `GObject` the parent path of the reordered signal the iter pointing to the parent of the reordered the new order of rows Retrieves the `GtkExpression` stored inside the given `value`, and acquires a reference to it. a `GtkExpression` a `GValue` initialized with type `GTK_TYPE_EXPRESSION` Retrieves the `GtkExpression` stored inside the given `value`. a `GtkExpression` a `GValue` initialized with type `GTK_TYPE_EXPRESSION` Stores the given `GtkExpression` inside `value`. The `GValue` will acquire a reference to the `expression`. a `GValue` initialized with type `GTK_TYPE_EXPRESSION` a `GtkExpression` Stores the given `GtkExpression` inside `value`. This function transfers the ownership of the `expression` to the `GValue`. a `GValue` initialized with type `GTK_TYPE_EXPRESSION` a `GtkExpression` Binds a callback function defined in a template to the @widget_class. This macro is a convenience wrapper around [method@Gtk.WidgetClass.bind_template_callback_full]. It is not supported after [method@Gtk.WidgetClass.set_template_scope] has been called on @widget_class. a widget class the callback symbol Binds a child widget defined in a template to the @widget_class. This macro is a convenience wrapper around [method@Gtk.WidgetClass.bind_template_child_full]. This macro will use the offset of the @member_name inside the @TypeName instance structure. a widget class the type name of this widget name of the instance member in the instance struct for @data_type Binds a child widget defined in a template to the @widget_class. Additionally, the child widget is made available as an internal child in `GtkBuilder`, under the name @member_name. This macro is a convenience wrapper around [method@Gtk.WidgetClass.bind_template_child_full]. This macro will use the offset of the @member_name inside the @TypeName instance structure. a widget class the type name, in CamelCase name of the instance member in the instance struct for @data_type Binds a child widget defined in a template to the @widget_class. Additionally, the child is made available as an internal child in `GtkBuilder`, under the name @member_name. This macro is a convenience wrapper around [method@Gtk.WidgetClass.bind_template_child_full]. This macro will use the offset of the @member_name inside the @TypeName private data structure. a widget class the type name, in CamelCase name of the instance private member on the private struct for @data_type Binds a child widget defined in a template to the @widget_class. This macro is a convenience wrapper around [method@GtkWidgetClass.bind_template_child_full]. This macro will use the offset of the @member_name inside the @TypeName private data structure (it uses `G_PRIVATE_OFFSET()`, so the private struct must be added with `G_ADD_PRIVATE())`. a widget class the type name of this widget name of the instance private member in the private struct for @data_type soup3-0.9.0/gir-files/HarfBuzz-0.0.gir000064400000000000000000035154531046102023000153350ustar 00000000000000 Data type for booleans. Data type for holding Unicode codepoints. Also used to hold glyph IDs. Data type for holding color values. Colors are eight bits per channel RGB plus alpha transparency. A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the extents for a font, for horizontal-direction text segments. Extents must be returned in an #hb_glyph_extents output parameter. A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the extents for a font, for vertical-direction text segments. Extents must be returned in an #hb_glyph_extents output parameter. A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the advance for a specified glyph, in horizontal-direction text segments. Advances must be returned in an #hb_position_t output parameter. A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the advances for a sequence of glyphs, in horizontal-direction text segments. A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the kerning-adjustment value for a glyph-pair in the specified font, for horizontal text segments. A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the (X,Y) coordinates (in scaled units) of the origin for a glyph, for horizontal-direction text segments. Each coordinate must be returned in an #hb_position_t output parameter. A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the (X,Y) coordinates (in scaled units) of the origin for requested glyph, for horizontal-direction text segments. Each coordinate must be returned in a the x/y #hb_position_t output parameters. A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the advance for a specified glyph, in vertical-direction text segments. Advances must be returned in an #hb_position_t output parameter. A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the advances for a sequence of glyphs, in vertical-direction text segments. A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the kerning-adjustment value for a glyph-pair in the specified font, for vertical text segments. A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the (X,Y) coordinates (in scaled units) of the origin for a glyph, for vertical-direction text segments. Each coordinate must be returned in an #hb_position_t output parameter. A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the (X,Y) coordinates (in scaled units) of the origin for requested glyph, for vertical-direction text segments. Each coordinate must be returned in a the x/y #hb_position_t output parameters. Data type for bitmasks. An integral type representing an OpenType 'name' table name identifier. There are predefined name IDs, as well as name IDs return from other API. These can be used to fetch name strings from a font face. Data type for holding a single coordinate value. Contour points and other multi-dimensional data are stored as tuples of #hb_position_t's. Data type for tag identifiers. Tags are four byte integers, each byte representing a character. Tags are used to identify tables, design-variation axes, scripts, languages, font features, and baselines with human-readable names. Used when getting or setting AAT feature selectors. Indicates that there is no selector index corresponding to the selector of interest. Tests whether a cluster level does not group cluster values by graphemes. Requires that the level be valid. #hb_buffer_cluster_level_t to test Tests whether a cluster level groups cluster values by graphemes. Requires that the level be valid. #hb_buffer_cluster_level_t to test Tests whether a cluster level groups cluster values into monotone order. Requires that the level be valid. #hb_buffer_cluster_level_t to test The default code point for replacing invalid characters in a given encoding. Set to U+FFFD REPLACEMENT CHARACTER. Unused #hb_codepoint_t value. Constructs an #hb_color_t from four integers. blue channel value green channel value red channel value alpha channel value Tests whether a text direction moves backward (from right to left, or from bottom to top). Requires that the direction be valid. #hb_direction_t to test Tests whether a text direction moves forward (from left to right, or from top to bottom). Requires that the direction be valid. #hb_direction_t to test Tests whether a text direction is horizontal. Requires that the direction be valid. #hb_direction_t to test Tests whether a text direction is valid. #hb_direction_t to test Tests whether a text direction is vertical. Requires that the direction be valid. #hb_direction_t to test Reverses a text direction. Requires that the direction be valid. #hb_direction_t to reverse Special setting for #hb_feature_t.start to apply the feature from the start of the buffer. Constant signifying that a font does not have any named-instance index set. This is the default of a font. An unset #hb_language_t. Special value for language index indicating default or unsupported language. Special value for feature index indicating unsupported feature. Special value for script index indicating unsupported script. Special value for variations index indicating unsupported variation. Maximum number of OpenType tags that can correspond to a give #hb_language_t. Maximum number of OpenType tags that can correspond to a give #hb_script_t. Do not use. Constructs an #hb_tag_t from four character literals. 1st character of the tag 2nd character of the tag 3rd character of the tag 4th character of the tag [Tibetan] Maximum valid Unicode code point. See Unicode 6.1 for details on the maximum decomposition length. Extracts four character literals from an #hb_tag_t. an #hb_tag_t Structure representing a setting for an #hb_aat_layout_feature_type_t. The selector's name identifier The value to turn the selector on The value to turn the selector off The selectors defined for specifying AAT feature settings. Initial, unset feature selector for #HB_AAT_LAYOUT_FEATURE_TYPE_ALL_TYPOGRAPHIC for #HB_AAT_LAYOUT_FEATURE_TYPE_ALL_TYPOGRAPHIC for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_SUBSTITUTION for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_SUBSTITUTION for #HB_AAT_LAYOUT_FEATURE_TYPE_LINGUISTIC_REARRANGEMENT for #HB_AAT_LAYOUT_FEATURE_TYPE_LINGUISTIC_REARRANGEMENT for #HB_AAT_LAYOUT_FEATURE_TYPE_NUMBER_SPACING for #HB_AAT_LAYOUT_FEATURE_TYPE_NUMBER_SPACING for #HB_AAT_LAYOUT_FEATURE_TYPE_NUMBER_SPACING for #HB_AAT_LAYOUT_FEATURE_TYPE_NUMBER_SPACING for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_DIACRITICS_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_DIACRITICS_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_DIACRITICS_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_POSITION for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_POSITION for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_POSITION for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_POSITION for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_POSITION for #HB_AAT_LAYOUT_FEATURE_TYPE_FRACTIONS for #HB_AAT_LAYOUT_FEATURE_TYPE_FRACTIONS for #HB_AAT_LAYOUT_FEATURE_TYPE_FRACTIONS for #HB_AAT_LAYOUT_FEATURE_TYPE_OVERLAPPING_CHARACTERS_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_OVERLAPPING_CHARACTERS_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_DESIGN_COMPLEXITY_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_DESIGN_COMPLEXITY_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_DESIGN_COMPLEXITY_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_DESIGN_COMPLEXITY_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_DESIGN_COMPLEXITY_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLE_OPTIONS for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLE_OPTIONS for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLE_OPTIONS for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLE_OPTIONS for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLE_OPTIONS for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLE_OPTIONS for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE for #HB_AAT_LAYOUT_FEATURE_TYPE_NUMBER_CASE for #HB_AAT_LAYOUT_FEATURE_TYPE_NUMBER_CASE for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_KANA_SPACING_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_KANA_SPACING_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_SPACING_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_SPACING_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_SPACING_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_UNICODE_DECOMPOSITION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_UNICODE_DECOMPOSITION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_UNICODE_DECOMPOSITION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_UNICODE_DECOMPOSITION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_UNICODE_DECOMPOSITION_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_UNICODE_DECOMPOSITION_TYPE Deprecated; use #HB_AAT_LAYOUT_FEATURE_SELECTOR_RUBY_KANA_OFF instead Deprecated; use #HB_AAT_LAYOUT_FEATURE_SELECTOR_RUBY_KANA_ON instead for #HB_AAT_LAYOUT_FEATURE_TYPE_RUBY_KANA for #HB_AAT_LAYOUT_FEATURE_TYPE_RUBY_KANA for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_SYMBOL_ALTERNATIVES_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_SYMBOL_ALTERNATIVES_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_SYMBOL_ALTERNATIVES_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_SYMBOL_ALTERNATIVES_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_SYMBOL_ALTERNATIVES_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_SYMBOL_ALTERNATIVES_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_ALTERNATIVES_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_ALTERNATIVES_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_ALTERNATIVES_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_ALTERNATIVES_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_ALTERNATIVES_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_ALTERNATIVES_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_VERTICAL_ROMAN_PLACEMENT_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_VERTICAL_ROMAN_PLACEMENT_TYPE Deprecated; use #HB_AAT_LAYOUT_FEATURE_SELECTOR_CJK_ITALIC_ROMAN_OFF instead Deprecated; use #HB_AAT_LAYOUT_FEATURE_SELECTOR_CJK_ITALIC_ROMAN_ON instead for #HB_AAT_LAYOUT_FEATURE_TYPE_ITALIC_CJK_ROMAN for #HB_AAT_LAYOUT_FEATURE_TYPE_ITALIC_CJK_ROMAN for #HB_AAT_LAYOUT_FEATURE_TYPE_CASE_SENSITIVE_LAYOUT for #HB_AAT_LAYOUT_FEATURE_TYPE_CASE_SENSITIVE_LAYOUT for #HB_AAT_LAYOUT_FEATURE_TYPE_CASE_SENSITIVE_LAYOUT for #HB_AAT_LAYOUT_FEATURE_TYPE_CASE_SENSITIVE_LAYOUT for #HB_AAT_LAYOUT_FEATURE_TYPE_ALTERNATE_KANA for #HB_AAT_LAYOUT_FEATURE_TYPE_ALTERNATE_KANA for #HB_AAT_LAYOUT_FEATURE_TYPE_ALTERNATE_KANA for #HB_AAT_LAYOUT_FEATURE_TYPE_ALTERNATE_KANA for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_CONTEXTUAL_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_CONTEXTUAL_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_CONTEXTUAL_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_CONTEXTUAL_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_CONTEXTUAL_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_CONTEXTUAL_ALTERNATIVES for #HB_AAT_LAYOUT_FEATURE_TYPE_LOWER_CASE for #HB_AAT_LAYOUT_FEATURE_TYPE_LOWER_CASE for #HB_AAT_LAYOUT_FEATURE_TYPE_LOWER_CASE for #HB_AAT_LAYOUT_FEATURE_TYPE_UPPER_CASE for #HB_AAT_LAYOUT_FEATURE_TYPE_UPPER_CASE for #HB_AAT_LAYOUT_FEATURE_TYPE_UPPER_CASE for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_ROMAN_SPACING_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_ROMAN_SPACING_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_ROMAN_SPACING_TYPE for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_ROMAN_SPACING_TYPE Fetches the name identifier of the specified feature type in the face's `name` table. Name identifier of the requested feature type #hb_face_t to work upon The #hb_aat_layout_feature_type_t of the requested feature type Fetches a list of the selectors available for the specified feature in the given face. If upon return, @default_index is set to #HB_AAT_LAYOUT_NO_SELECTOR_INDEX, then the feature type is non-exclusive. Otherwise, @default_index is the index of the selector that is selected by default. Number of all available feature selectors #hb_face_t to work upon The #hb_aat_layout_feature_type_t of the requested feature type offset of the first feature type to retrieve Input = the maximum number of selectors to return; Output = the actual number of selectors returned (may be zero) A buffer pointer. The selectors available for the feature type queries. The index of the feature's default selector, if any The possible feature types defined for AAT shaping, from Apple [Font Feature Registry](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html). Initial, unset feature type [All Typographic Features](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type0) [Ligatures](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type1) [Cursive Connection](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type2) [Letter Case](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type3) [Vertical Substitution](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type4) [Linguistic Rearrangement](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type5) [Number Spacing](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type6) [Smart Swash](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type8) [Diacritics](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type9) [Vertical Position](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type10) [Fractions](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type11) [Overlapping Characters](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type13) [Typographic Extras](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type14) [Mathematical Extras](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type15) [Ornament Sets](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type16) [Character Alternatives](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type17) [Design Complexity](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type18) [Style Options](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type19) [Character Shape](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type20) [Number Case](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type21) [Text Spacing](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type22) [Transliteration](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type23) [Annotation](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type24) [Kana Spacing](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type25) [Ideographic Spacing](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type26) [Unicode Decomposition](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type27) [Ruby Kana](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type28) [CJK Symbol Alternatives](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type29) [Ideographic Alternatives](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type30) [CJK Vertical Roman Placement](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type31) [Italic CJK Roman](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type32) [Case Sensitive Layout](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type33) [Alternate Kana](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type34) [Stylistic Alternatives](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type35) [Contextual Alternatives](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type36) [Lower Case](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type37) [Upper Case](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type38) [Language Tag](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type39) [CJK Roman Spacing](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html#Type103) Fetches a list of the AAT feature types included in the specified face. Number of all available feature types. #hb_face_t to work upon offset of the first feature type to retrieve Input = the maximum number of feature types to return; Output = the actual number of feature types returned (may be zero) Array of feature types found Tests whether the specified face includes any positioning information in the `kerx` table. <note>Note: does not examine the `GPOS` table.</note> `true` if data found, `false` otherwise #hb_face_t to work upon Tests whether the specified face includes any substitutions in the `morx` or `mort` tables. <note>Note: does not examine the `GSUB` table.</note> `true` if data found, `false` otherwise #hb_face_t to work upon Tests whether the specified face includes any tracking information in the `trak` table. `true` if data found, `false` otherwise #hb_face_t to work upon Makes a writable copy of @blob. The new blob, or nullptr if allocation failed A blob. Creates a new "blob" object wrapping @data. The @mode parameter is used to negotiate ownership and lifecycle of @data. New blob, or the empty blob if something failed or if @length is zero. Destroy with hb_blob_destroy(). Pointer to blob data. Length of @data in bytes. Memory mode for @data. Data parameter to pass to @destroy. Callback to call when @data is not needed anymore. Creates a new blob containing the data from the specified binary font file. The filename is passed directly to the system on all platforms, except on Windows, where the filename is interpreted as UTF-8. Only if the filename is not valid UTF-8, it will be interpreted according to the system codepage. An #hb_blob_t pointer with the content of the file, or hb_blob_get_empty() if failed. A font filename Creates a new blob containing the data from the specified file. The filename is passed directly to the system on all platforms, except on Windows, where the filename is interpreted as UTF-8. Only if the filename is not valid UTF-8, it will be interpreted according to the system codepage. An #hb_blob_t pointer with the content of the file, or `NULL` if failed. A filename Creates a new "blob" object wrapping @data. The @mode parameter is used to negotiate ownership and lifecycle of @data. Note that this function returns a freshly-allocated empty blob even if @length is zero. This is in contrast to hb_blob_create(), which returns the singleton empty blob (as returned by hb_blob_get_empty()) if @length is zero. New blob, or `NULL` if failed. Destroy with hb_blob_destroy(). Pointer to blob data. Length of @data in bytes. Memory mode for @data. Data parameter to pass to @destroy. Callback to call when @data is not needed anymore. Returns a blob that represents a range of bytes in @parent. The new blob is always created with #HB_MEMORY_MODE_READONLY, meaning that it will never modify data in the parent blob. The parent data is not expected to be modified, and will result in undefined behavior if it is. Makes @parent immutable. New blob, or the empty blob if something failed or if @length is zero or @offset is beyond the end of @parent's data. Destroy with hb_blob_destroy(). Parent blob. Start offset of sub-blob within @parent, in bytes. Length of sub-blob. Decreases the reference count on @blob, and if it reaches zero, destroys @blob, freeing all memory, possibly calling the destroy-callback the blob was created for if it has not been called already. See TODO:link object types for more information. a blob. Fetches the data from a blob. the byte data of @blob. a blob. The length in bytes of the data retrieved Tries to make blob data writable (possibly copying it) and return pointer to data. Fails if blob has been made immutable, or if memory allocation fails. Writable blob data, or `NULL` if failed. a blob. output length of the writable data. Returns the singleton empty blob. See TODO:link object types for more information. The empty blob. Fetches the length of a blob's data. the length of @blob data in bytes. a blob. Fetches the user data associated with the specified key, attached to the specified font-functions structure. A pointer to the user data a blob The user-data key to query Tests whether a blob is immutable. `true` if @blob is immutable, `false` otherwise a blob. Makes a blob immutable. a blob Increases the reference count on @blob. See TODO:link object types for more information. @blob. a blob. Attaches a user-data key/data pair to the specified blob. `true` if success, `false` otherwise An #hb_blob_t The user-data key to set A pointer to the user data to set A callback to call when @data is not needed anymore Whether to replace an existing data with the same key Data type for blobs. A blob wraps a chunk of binary data and facilitates its lifecycle management between a client program and HarfBuzz. Appends a character with the Unicode value of @codepoint to @buffer, and gives it the initial cluster value of @cluster. Clusters can be any thing the client wants, they are usually used to refer to the index of the character in the input text stream and are output in #hb_glyph_info_t.cluster field. This function does not check the validity of @codepoint, it is up to the caller to ensure it is a valid Unicode code point. An #hb_buffer_t A Unicode code point. The cluster value of @codepoint. Appends characters from @text array to @buffer. The @item_offset is the position of the first character from @text that will be appended, and @item_length is the number of character. When shaping part of a larger text (e.g. a run of text from a paragraph), instead of passing just the substring corresponding to the run, it is preferable to pass the whole paragraph and specify the run start and length as @item_offset and @item_length, respectively, to give HarfBuzz the full context to be able, for example, to do cross-run Arabic shaping or properly handle combining marks at stat of run. This function does not check the validity of @text, it is up to the caller to ensure it contains a valid Unicode scalar values. In contrast, hb_buffer_add_utf32() can be used that takes similar input but performs sanity-check on the input. a #hb_buffer_t to append characters to. an array of Unicode code points to append. the length of the @text, or -1 if it is `NULL` terminated. the offset of the first code point to add to the @buffer. the number of code points to add to the @buffer, or -1 for the end of @text (assuming it is `NULL` terminated). Similar to hb_buffer_add_codepoints(), but allows only access to first 256 Unicode code points that can fit in 8-bit strings. <note>Has nothing to do with non-Unicode Latin-1 encoding.</note> An #hb_buffer_t an array of UTF-8 characters to append the length of the @text, or -1 if it is `NULL` terminated the offset of the first character to add to the @buffer the number of characters to add to the @buffer, or -1 for the end of @text (assuming it is `NULL` terminated) See hb_buffer_add_codepoints(). Replaces invalid UTF-16 characters with the @buffer replacement code point, see hb_buffer_set_replacement_codepoint(). An #hb_buffer_t An array of UTF-16 characters to append The length of the @text, or -1 if it is `NULL` terminated The offset of the first character to add to the @buffer The number of characters to add to the @buffer, or -1 for the end of @text (assuming it is `NULL` terminated) See hb_buffer_add_codepoints(). Replaces invalid UTF-32 characters with the @buffer replacement code point, see hb_buffer_set_replacement_codepoint(). An #hb_buffer_t An array of UTF-32 characters to append The length of the @text, or -1 if it is `NULL` terminated The offset of the first character to add to the @buffer The number of characters to add to the @buffer, or -1 for the end of @text (assuming it is `NULL` terminated) See hb_buffer_add_codepoints(). Replaces invalid UTF-8 characters with the @buffer replacement code point, see hb_buffer_set_replacement_codepoint(). An #hb_buffer_t An array of UTF-8 characters to append. The length of the @text, or -1 if it is `NULL` terminated. The offset of the first character to add to the @buffer. The number of characters to add to the @buffer, or -1 for the end of @text (assuming it is `NULL` terminated). Check if allocating memory for the buffer succeeded. `true` if @buffer memory allocation succeeded, `false` otherwise. An #hb_buffer_t Append (part of) contents of another buffer to this buffer. An #hb_buffer_t source #hb_buffer_t start index into source buffer to copy. Use 0 to copy from start of buffer. end index into source buffer to copy. Use @UINT_MAX (or ((unsigned int) -1)) to copy to end of buffer. Similar to hb_buffer_reset(), but does not clear the Unicode functions and the replacement code point. An #hb_buffer_t Data type for holding HarfBuzz's clustering behavior options. The cluster level dictates one aspect of how HarfBuzz will treat non-base characters during shaping. In @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES, non-base characters are merged into the cluster of the base character that precedes them. There is also cluster merging every time the clusters will otherwise become non-monotone. In @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS, non-base characters are initially assigned their own cluster values, which are not merged into preceding base clusters. This allows HarfBuzz to perform additional operations like reorder sequences of adjacent marks. The output is still monotone, but the cluster values are more granular. In @HB_BUFFER_CLUSTER_LEVEL_CHARACTERS, non-base characters are assigned their own cluster values, which are not merged into preceding base clusters. Moreover, the cluster values are not merged into monotone order. This is the most granular cluster level, and it is useful for clients that need to know the exact cluster values of each character, but is harder to use for clients, since clusters might appear in any order. In @HB_BUFFER_CLUSTER_LEVEL_GRAPHEMES, non-base characters are merged into the cluster of the base character that precedes them. This is similar to the Unicode Grapheme Cluster algorithm, but it is not exactly the same. The output is not forced to be monotone. This is useful for clients that want to use HarfBuzz as a cheap implementation of the Unicode Grapheme Cluster algorithm. @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES is the default, because it maintains backward compatibility with older versions of HarfBuzz. New client programs that do not need to maintain such backward compatibility are recommended to use @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS instead of the default. Return cluster values grouped by graphemes into monotone order. Return cluster values grouped into monotone order. Don't group cluster values. Only group clusters, but don't enforce monotone order. Default cluster level, equal to @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES. The type of #hb_buffer_t contents. Initial value for new buffer. The buffer contains input characters (before shaping). The buffer contains output glyphs (after shaping). Creates a new #hb_buffer_t with all properties to defaults. A newly allocated #hb_buffer_t with a reference count of 1. The initial reference count should be released with hb_buffer_destroy() when you are done using the #hb_buffer_t. This function never returns `NULL`. If memory cannot be allocated, a special #hb_buffer_t object will be returned on which hb_buffer_allocation_successful() returns `false`. Creates a new #hb_buffer_t, similar to hb_buffer_create(). The only difference is that the buffer is configured similarly to @src. A newly allocated #hb_buffer_t, similar to hb_buffer_create(). An #hb_buffer_t Deserializes glyphs @buffer from textual representation in the format produced by hb_buffer_serialize_glyphs(). `true` if the full string was parsed, `false` otherwise. an #hb_buffer_t buffer. string to deserialize the size of @buf, or -1 if it is `NULL`-terminated output pointer to the character after last consumed one. font for getting glyph IDs the #hb_buffer_serialize_format_t of the input @buf Deserializes Unicode @buffer from textual representation in the format produced by hb_buffer_serialize_unicode(). `true` if the full string was parsed, `false` otherwise. an #hb_buffer_t buffer. string to deserialize the size of @buf, or -1 if it is `NULL`-terminated output pointer to the character after last consumed one. the #hb_buffer_serialize_format_t of the input @buf Deallocate the @buffer. Decreases the reference count on @buffer by one. If the result is zero, then @buffer and all associated resources are freed. See hb_buffer_reference(). An #hb_buffer_t If dottedcircle_glyph is (hb_codepoint_t) -1 then #HB_BUFFER_DIFF_FLAG_DOTTED_CIRCLE_PRESENT and #HB_BUFFER_DIFF_FLAG_NOTDEF_PRESENT are never returned. This should be used by most callers if just comparing two buffers is needed. a buffer. other buffer to compare to. glyph id of U+25CC DOTTED CIRCLE, or (hb_codepoint_t) -1. allowed absolute difference in position values. Flags from comparing two #hb_buffer_t's. Buffer with different #hb_buffer_content_type_t cannot be meaningfully compared in any further detail. For buffers with differing length, the per-glyph comparison is not attempted, though we do still scan reference buffer for dotted circle and `.notdef` glyphs. If the buffers have the same length, we compare them glyph-by-glyph and report which aspect(s) of the glyph info/position are different. equal buffers. buffers with different #hb_buffer_content_type_t. buffers with differing length. `.notdef` glyph is present in the reference buffer. dotted circle glyph is present in the reference buffer. difference in #hb_glyph_info_t.codepoint difference in #hb_glyph_info_t.cluster difference in #hb_glyph_flags_t. difference in #hb_glyph_position_t. Flags for #hb_buffer_t. the default buffer flag. flag indicating that special handling of the beginning of text paragraph can be applied to this buffer. Should usually be set, unless you are passing to the buffer only part of the text without the full context. flag indicating that special handling of the end of text paragraph can be applied to this buffer, similar to @HB_BUFFER_FLAG_BOT. flag indication that character with Default_Ignorable Unicode property should use the corresponding glyph from the font, instead of hiding them (done by replacing them with the space glyph and zeroing the advance width.) This flag takes precedence over @HB_BUFFER_FLAG_REMOVE_DEFAULT_IGNORABLES. flag indication that character with Default_Ignorable Unicode property should be removed from glyph string instead of hiding them (done by replacing them with the space glyph and zeroing the advance width.) @HB_BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES takes precedence over this flag. Since: 1.8.0 flag indicating that a dotted circle should not be inserted in the rendering of incorrect character sequences (such at <0905 093E>). Since: 2.4.0 flag indicating that the hb_shape() call and its variants should perform various verification processes on the results of the shaping operation on the buffer. If the verification fails, then either a buffer message is sent, if a message handler is installed on the buffer, or a message is written to standard error. In either case, the shaping result might be modified to show the failed output. Since: 3.4.0 flag indicating that the @HB_GLYPH_FLAG_UNSAFE_TO_CONCAT glyph-flag should be produced by the shaper. By default it will not be produced since it incurs a cost. Since: 4.0.0 flag indicating that the @HB_GLYPH_FLAG_SAFE_TO_INSERT_TATWEEL glyph-flag should be produced by the shaper. By default it will not be produced. Since: 5.1.0 All currently defined flags: Since: 4.4.0 Fetches the cluster level of a buffer. The #hb_buffer_cluster_level_t dictates one aspect of how HarfBuzz will treat non-base characters during shaping. The cluster level of @buffer An #hb_buffer_t Fetches the type of @buffer contents. Buffers are either empty, contain characters (before shaping), or contain glyphs (the result of shaping). The type of @buffer contents An #hb_buffer_t See hb_buffer_set_direction() The direction of the @buffer. An #hb_buffer_t Fetches an empty #hb_buffer_t. The empty buffer Fetches the #hb_buffer_flags_t of @buffer. The @buffer flags An #hb_buffer_t Returns @buffer glyph information array. Returned pointer is valid as long as @buffer contents are not modified. The @buffer glyph information array. The value valid as long as buffer has not been modified. An #hb_buffer_t The output-array length. Returns @buffer glyph position array. Returned pointer is valid as long as @buffer contents are not modified. If buffer did not have positions before, the positions will be initialized to zeros, unless this function is called from within a buffer message callback (see hb_buffer_set_message_func()), in which case `NULL` is returned. The @buffer glyph position array. The value valid as long as buffer has not been modified. An #hb_buffer_t The output length See hb_buffer_set_invisible_glyph(). The @buffer invisible #hb_codepoint_t An #hb_buffer_t See hb_buffer_set_language(). The #hb_language_t of the buffer. Must not be freed by the caller. An #hb_buffer_t Returns the number of items in the buffer. The @buffer length. The value valid as long as buffer has not been modified. An #hb_buffer_t See hb_buffer_set_not_found_glyph(). The @buffer not-found #hb_codepoint_t An #hb_buffer_t See hb_buffer_set_not_found_variation_selector_glyph(). The @buffer not-found-variation-selector #hb_codepoint_t An #hb_buffer_t See hb_buffer_set_random_state(). The @buffer random state An #hb_buffer_t Fetches the #hb_codepoint_t that replaces invalid entries for a given encoding when adding text to @buffer. The @buffer replacement #hb_codepoint_t An #hb_buffer_t Fetches the script of @buffer. The #hb_script_t of the @buffer An #hb_buffer_t Sets @props to the #hb_segment_properties_t of @buffer. An #hb_buffer_t The output #hb_segment_properties_t Fetches the Unicode-functions structure of a buffer. The Unicode-functions structure An #hb_buffer_t Fetches the user data associated with the specified key, attached to the specified buffer. A pointer to the user data An #hb_buffer_t The user-data key to query Sets unset buffer segment properties based on buffer Unicode contents. If buffer is not empty, it must have content type #HB_BUFFER_CONTENT_TYPE_UNICODE. If buffer script is not set (ie. is #HB_SCRIPT_INVALID), it will be set to the Unicode script of the first character in the buffer that has a script other than #HB_SCRIPT_COMMON, #HB_SCRIPT_INHERITED, and #HB_SCRIPT_UNKNOWN. Next, if buffer direction is not set (ie. is #HB_DIRECTION_INVALID), it will be set to the natural horizontal direction of the buffer script as returned by hb_script_get_horizontal_direction(). If hb_script_get_horizontal_direction() returns #HB_DIRECTION_INVALID, then #HB_DIRECTION_LTR is used. Finally, if buffer language is not set (ie. is #HB_LANGUAGE_INVALID), it will be set to the process's default language as returned by hb_language_get_default(). This may change in the future by taking buffer script into consideration when choosing a language. Note that hb_language_get_default() is NOT threadsafe the first time it is called. See documentation for that function for details. An #hb_buffer_t Returns whether @buffer has glyph position data. A buffer gains position data when hb_buffer_get_glyph_positions() is called on it, and cleared of position data when hb_buffer_clear_contents() is called. `true` if the @buffer has position array, `false` otherwise. an #hb_buffer_t. A callback method for #hb_buffer_t. The method gets called with the #hb_buffer_t it was set on, the #hb_font_t the buffer is shaped with and a message describing what step of the shaping process will be performed. Returning `false` from this method will skip this shaping step and move to the next one. `true` to perform the shaping step, `false` to skip it. An #hb_buffer_t to work upon The #hb_font_t the @buffer is shaped with `NULL`-terminated message passed to the function User data pointer passed by the caller Reorders a glyph buffer to have canonical in-cluster glyph order / position. The resulting clusters should behave identical to pre-reordering clusters. <note>This has nothing to do with Unicode normalization.</note> An #hb_buffer_t Pre allocates memory for @buffer to fit at least @size number of items. `true` if @buffer memory allocation succeeded, `false` otherwise An #hb_buffer_t Number of items to pre allocate. Increases the reference count on @buffer by one. This prevents @buffer from being destroyed until a matching call to hb_buffer_destroy() is made. The referenced #hb_buffer_t. An #hb_buffer_t Resets the buffer to its initial status, as if it was just newly created with hb_buffer_create(). An #hb_buffer_t Reverses buffer contents. An #hb_buffer_t Reverses buffer clusters. That is, the buffer contents are reversed, then each cluster (consecutive items having the same cluster number) are reversed again. An #hb_buffer_t Reverses buffer contents between @start and @end. An #hb_buffer_t start index end index Serializes @buffer into a textual representation of its content, whether Unicode codepoints or glyph identifiers and positioning information. This is useful for showing the contents of the buffer, for example during debugging. See the documentation of hb_buffer_serialize_unicode() and hb_buffer_serialize_glyphs() for a description of the output format. The number of serialized items. an #hb_buffer_t buffer. the first item in @buffer to serialize. the last item in @buffer to serialize. output string to write serialized buffer into. the size of @buf. if not `NULL`, will be set to the number of bytes written into @buf. the #hb_font_t used to shape this buffer, needed to read glyph names and extents. If `NULL`, an empty font will be used. the #hb_buffer_serialize_format_t to use for formatting the output. the #hb_buffer_serialize_flags_t that control what glyph properties to serialize. Flags that control what glyph information are serialized in hb_buffer_serialize_glyphs(). serialize glyph names, clusters and positions. do not serialize glyph cluster. do not serialize glyph position information. do no serialize glyph name. serialize glyph extents. serialize glyph flags. Since: 1.5.0 do not serialize glyph advances, glyph offsets will reflect absolute glyph positions. Since: 1.8.0. Note: when this flag is used with a partial range of the buffer (i.e. @start is not 0), calculating the absolute positions has a cost proportional to @start. If the buffer is serialized in many small chunks, this can lead to quadratic behavior. It is recommended to use a larger @buf_size to minimize this cost. All currently defined flags. Since: 4.4.0 Parses a string into an #hb_buffer_serialize_format_t. Does not check if @str is a valid buffer serialization format, use hb_buffer_serialize_list_formats() to get the list of supported formats. The parsed #hb_buffer_serialize_format_t. a string to parse length of @str, or -1 if string is `NULL` terminated The buffer serialization and de-serialization format used in hb_buffer_serialize_glyphs() and hb_buffer_deserialize_glyphs(). a human-readable, plain text format. a machine-readable JSON format. invalid format. Converts @format to the string corresponding it, or `NULL` if it is not a valid #hb_buffer_serialize_format_t. A `NULL` terminated string corresponding to @format. Should not be freed. an #hb_buffer_serialize_format_t to convert. Serializes @buffer into a textual representation of its glyph content, useful for showing the contents of the buffer, for example during debugging. There are currently two supported serialization formats: ## text A human-readable, plain text format. The serialized glyphs will look something like: ``` [uni0651=0@518,0+0|uni0628=0+1897] ``` - The serialized glyphs are delimited with `[` and `]`. - Glyphs are separated with `|` - Each glyph starts with glyph name, or glyph index if #HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES flag is set. Then, - If #HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set, `=` then #hb_glyph_info_t.cluster. - If #HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS is not set, the #hb_glyph_position_t in the format: - If #hb_glyph_position_t.x_offset and #hb_glyph_position_t.y_offset are not both 0, `@x_offset,y_offset`. Then, - `+x_advance`, then `,y_advance` if #hb_glyph_position_t.y_advance is not 0. Then, - If #HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS is set, the #hb_glyph_extents_t in the format `<x_bearing,y_bearing,width,height>` ## json A machine-readable, structured format. The serialized glyphs will look something like: ``` [{"g":"uni0651","cl":0,"dx":518,"dy":0,"ax":0,"ay":0}, {"g":"uni0628","cl":0,"dx":0,"dy":0,"ax":1897,"ay":0}] ``` Each glyph is a JSON object, with the following properties: - `g`: the glyph name or glyph index if #HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES flag is set. - `cl`: #hb_glyph_info_t.cluster if #HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set. - `dx`,`dy`,`ax`,`ay`: #hb_glyph_position_t.x_offset, #hb_glyph_position_t.y_offset, #hb_glyph_position_t.x_advance and #hb_glyph_position_t.y_advance respectively, if #HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS is not set. - `xb`,`yb`,`w`,`h`: #hb_glyph_extents_t.x_bearing, #hb_glyph_extents_t.y_bearing, #hb_glyph_extents_t.width and #hb_glyph_extents_t.height respectively if #HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS is set. The number of serialized items. an #hb_buffer_t buffer. the first item in @buffer to serialize. the last item in @buffer to serialize. output string to write serialized buffer into. the size of @buf. if not `NULL`, will be set to the number of bytes written into @buf. the #hb_font_t used to shape this buffer, needed to read glyph names and extents. If `NULL`, an empty font will be used. the #hb_buffer_serialize_format_t to use for formatting the output. the #hb_buffer_serialize_flags_t that control what glyph properties to serialize. Returns a list of supported buffer serialization formats. A string array of buffer serialization formats. Should not be freed. Serializes @buffer into a textual representation of its content, when the buffer contains Unicode codepoints (i.e., before shaping). This is useful for showing the contents of the buffer, for example during debugging. There are currently two supported serialization formats: ## text A human-readable, plain text format. The serialized codepoints will look something like: ```  <U+0651=0|U+0628=1> ``` - Glyphs are separated with `|` - Unicode codepoints are expressed as zero-padded four (or more) digit hexadecimal numbers preceded by `U+` - If #HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set, the cluster will be indicated with a `=` then #hb_glyph_info_t.cluster. ## json A machine-readable, structured format. The serialized codepoints will be a list of objects with the following properties: - `u`: the Unicode codepoint as a decimal integer - `cl`: #hb_glyph_info_t.cluster if #HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set. For example: ``` [{u:1617,cl:0},{u:1576,cl:1}] ``` The number of serialized items. an #hb_buffer_t buffer. the first item in @buffer to serialize. the last item in @buffer to serialize. output string to write serialized buffer into. the size of @buf. if not `NULL`, will be set to the number of bytes written into @buf. the #hb_buffer_serialize_format_t to use for formatting the output. the #hb_buffer_serialize_flags_t that control what glyph properties to serialize. Sets the cluster level of a buffer. The #hb_buffer_cluster_level_t dictates one aspect of how HarfBuzz will treat non-base characters during shaping. An #hb_buffer_t The cluster level to set on the buffer Sets the type of @buffer contents. Buffers are either empty, contain characters (before shaping), or contain glyphs (the result of shaping). You rarely need to call this function, since a number of other functions transition the content type for you. Namely: - A newly created buffer starts with content type %HB_BUFFER_CONTENT_TYPE_INVALID. Calling hb_buffer_reset(), hb_buffer_clear_contents(), as well as calling hb_buffer_set_length() with an argument of zero all set the buffer content type to invalid as well. - Calling hb_buffer_add_utf8(), hb_buffer_add_utf16(), hb_buffer_add_utf32(), hb_buffer_add_codepoints() and hb_buffer_add_latin1() expect that buffer is either empty and have a content type of invalid, or that buffer content type is %HB_BUFFER_CONTENT_TYPE_UNICODE, and they also set the content type to Unicode if they added anything to an empty buffer. - Finally hb_shape() and hb_shape_full() expect that the buffer is either empty and have content type of invalid, or that buffer content type is %HB_BUFFER_CONTENT_TYPE_UNICODE, and upon success they set the buffer content type to %HB_BUFFER_CONTENT_TYPE_GLYPHS. The above transitions are designed such that one can use a buffer in a loop of "reset : add-text : shape" without needing to ever modify the content type manually. An #hb_buffer_t The type of buffer contents to set Set the text flow direction of the buffer. No shaping can happen without setting @buffer direction, and it controls the visual direction for the output glyphs; for RTL direction the glyphs will be reversed. Many layout features depend on the proper setting of the direction, for example, reversing RTL text before shaping, then shaping with LTR direction is not the same as keeping the text in logical order and shaping with RTL direction. An #hb_buffer_t the #hb_direction_t of the @buffer Sets @buffer flags to @flags. See #hb_buffer_flags_t. An #hb_buffer_t The buffer flags to set Sets the #hb_codepoint_t that replaces invisible characters in the shaping result. If set to zero (default), the glyph for the U+0020 SPACE character is used. Otherwise, this value is used verbatim. An #hb_buffer_t the invisible #hb_codepoint_t Sets the language of @buffer to @language. Languages are crucial for selecting which OpenType feature to apply to the buffer which can result in applying language-specific behaviour. Languages are orthogonal to the scripts, and though they are related, they are different concepts and should not be confused with each other. Use hb_language_from_string() to convert from BCP 47 language tags to #hb_language_t. An #hb_buffer_t An hb_language_t to set Similar to hb_buffer_pre_allocate(), but clears any new items added at the end. `true` if @buffer memory allocation succeeded, `false` otherwise. An #hb_buffer_t The new length of @buffer Sets the implementation function for #hb_buffer_message_func_t. An #hb_buffer_t Callback function Data to pass to @func The function to call when @user_data is not needed anymore Sets the #hb_codepoint_t that replaces characters not found in the font during shaping. The not-found glyph defaults to zero, sometimes known as the ".notdef" glyph. This API allows for differentiating the two. An #hb_buffer_t the not-found #hb_codepoint_t Sets the #hb_codepoint_t that replaces variation-selector characters not resolved in the font during shaping. The not-found-variation-selector glyph defaults to #HB_CODEPOINT_INVALID, in which case an unresolved variation-selector will be removed from the glyph string during shaping. This API allows for changing that and retaining a glyph, such that the situation can be detected by the client and handled accordingly (e.g. by using a different font). An #hb_buffer_t the not-found-variation-selector #hb_codepoint_t Sets the random state of the buffer. The state changes every time a glyph uses randomness (eg. the `rand` OpenType feature). This function together with hb_buffer_get_random_state() allow for transferring the current random state to a subsequent buffer, to get better randomness distribution. Defaults to 1 and when buffer contents are cleared. A value of 0 disables randomness during shaping. An #hb_buffer_t the new random state Sets the #hb_codepoint_t that replaces invalid entries for a given encoding when adding text to @buffer. Default is #HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT. An #hb_buffer_t the replacement #hb_codepoint_t Sets the script of @buffer to @script. Script is crucial for choosing the proper shaping behaviour for scripts that require it (e.g. Arabic) and the which OpenType features defined in the font to be applied. You can pass one of the predefined #hb_script_t values, or use hb_script_from_string() or hb_script_from_iso15924_tag() to get the corresponding script from an ISO 15924 script tag. An #hb_buffer_t An #hb_script_t to set. Sets the segment properties of the buffer, a shortcut for calling hb_buffer_set_direction(), hb_buffer_set_script() and hb_buffer_set_language() individually. An #hb_buffer_t An #hb_segment_properties_t to use Sets the Unicode-functions structure of a buffer to @unicode_funcs. An #hb_buffer_t The Unicode-functions structure Attaches a user-data key/data pair to the specified buffer. `true` if success, `false` otherwise An #hb_buffer_t The user-data key A pointer to the user data A callback to call when @data is not needed anymore Whether to replace an existing data with the same key The main structure holding the input text and its properties before shaping, and output glyphs and their information after shaping. Allocates @nmemb elements of @size bytes each, initialized to zero, using the allocator set at compile-time. Typically just calloc(). A pointer to the allocated memory. The number of elements to allocate. The size of each element. Fetches the alpha channel of the given @color. Alpha channel value an #hb_color_t we are interested in its channels. Fetches the blue channel of the given @color. Blue channel value an #hb_color_t we are interested in its channels. Fetches the green channel of the given @color. Green channel value an #hb_color_t we are interested in its channels. Fetches the red channel of the given @color. Red channel value an #hb_color_t we are interested in its channels. Fetches a list of color stops from the given color line object. Note that due to variations being applied, the returned color stops may be out of order. It is the callers responsibility to ensure that color stops are sorted by their offset before they are used. the total number of color stops in @color_line a #hb_color_line_t object the index of the first color stop to return Input = the maximum number of feature tags to return; Output = the actual number of feature tags returned (may be zero) Array of #hb_color_stop_t to populate A virtual method for the #hb_color_line_t to fetch color stops. the total number of color stops in @color_line a #hb_color_line_t object the data accompanying @color_line the index of the first color stop to return Input = the maximum number of feature tags to return; Output = the actual number of feature tags returned (may be zero) Array of #hb_color_stop_t to populate the data accompanying this method Fetches the extend mode of the color line object. the extend mode of @color_line a #hb_color_line_t object A virtual method for the @hb_color_line_t to fetches the extend mode. the extend mode of @color_line a #hb_color_line_t object the data accompanying @color_line the data accompanying this method A struct containing color information for a gradient. Information about a color stop on a color line. Color lines typically have offsets ranging between 0 and 1, but that is not required. Note: despite @color being unpremultiplied here, interpolation in gradients shall happen in premultiplied space. See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr) section for details. the offset of the color stop whether the color is the foreground the color, unpremultiplied A virtual method for destroy user-data callbacks. the data to be destroyed Converts a string to an #hb_direction_t. Matching is loose and applies only to the first letter. For examples, "LTR" and "left-to-right" will both return #HB_DIRECTION_LTR. Unmatched strings will return #HB_DIRECTION_INVALID. The #hb_direction_t matching @str String to convert Length of @str, or -1 if it is `NULL`-terminated The direction of a text segment or buffer. A segment can also be tested for horizontal or vertical orientation (irrespective of specific direction) with HB_DIRECTION_IS_HORIZONTAL() or HB_DIRECTION_IS_VERTICAL(). Initial, unset direction. Text is set horizontally from left to right. Text is set horizontally from right to left. Text is set vertically from top to bottom. Text is set vertically from bottom to top. Converts an #hb_direction_t to a string. The string corresponding to @direction The #hb_direction_t to convert Perform a "close-path" draw operation. draw functions associated draw data passed by the caller current draw state A virtual method for the #hb_draw_funcs_t to perform a "close-path" draw operation. draw functions object The data accompanying the draw functions in hb_font_draw_glyph() current draw state User data pointer passed to hb_draw_funcs_set_close_path_func() Perform a "cubic-to" draw operation. draw functions associated draw data passed by the caller current draw state X component of first control point Y component of first control point X component of second control point Y component of second control point X component of target point Y component of target point A virtual method for the #hb_draw_funcs_t to perform a "cubic-to" draw operation. draw functions object The data accompanying the draw functions in hb_font_draw_glyph() current draw state X component of first control point Y component of first control point X component of second control point Y component of second control point X component of target point Y component of target point User data pointer passed to hb_draw_funcs_set_cubic_to_func() Creates a new draw callbacks object. A newly allocated #hb_draw_funcs_t with a reference count of 1. The initial reference count should be released with hb_draw_funcs_destroy when you are done using the #hb_draw_funcs_t. This function never returns `NULL`. If memory cannot be allocated, a special singleton #hb_draw_funcs_t object will be returned. Deallocate the @dfuncs. Decreases the reference count on @dfuncs by one. If the result is zero, then @dfuncs and all associated resources are freed. See hb_draw_funcs_reference(). draw functions Fetches the singleton empty draw-functions structure. The empty draw-functions structure Fetches the user-data associated with the specified key, attached to the specified draw-functions structure. A pointer to the user data The draw-functions structure The user-data key to query Checks whether @dfuncs is immutable. `true` if @dfuncs is immutable, `false` otherwise draw functions Makes @dfuncs object immutable. draw functions Increases the reference count on @dfuncs by one. This prevents @dfuncs from being destroyed until a matching call to hb_draw_funcs_destroy() is made. The referenced #hb_draw_funcs_t. draw functions Sets close-path callback to the draw functions object. draw functions object close-path callback Data to pass to @func The function to call when @user_data is not needed anymore Sets cubic-to callback to the draw functions object. draw functions cubic-to callback Data to pass to @func The function to call when @user_data is not needed anymore Sets line-to callback to the draw functions object. draw functions object line-to callback Data to pass to @func The function to call when @user_data is not needed anymore Sets move-to callback to the draw functions object. draw functions object move-to callback Data to pass to @func The function to call when @user_data is not needed anymore Sets quadratic-to callback to the draw functions object. draw functions object quadratic-to callback Data to pass to @func The function to call when @user_data is not needed anymore Attaches a user-data key/data pair to the specified draw-functions structure. `true` if success, `false` otherwise The draw-functions structure The user-data key A pointer to the user data A callback to call when @data is not needed anymore Whether to replace an existing data with the same key Glyph draw callbacks. #hb_draw_move_to_func_t, #hb_draw_line_to_func_t and #hb_draw_cubic_to_func_t calls are necessary to be defined but we translate #hb_draw_quadratic_to_func_t calls to #hb_draw_cubic_to_func_t if the callback isn't defined. Perform a "line-to" draw operation. draw functions associated draw data passed by the caller current draw state X component of target point Y component of target point A virtual method for the #hb_draw_funcs_t to perform a "line-to" draw operation. draw functions object The data accompanying the draw functions in hb_font_draw_glyph() current draw state X component of target point Y component of target point User data pointer passed to hb_draw_funcs_set_line_to_func() Perform a "move-to" draw operation. draw functions associated draw data passed by the caller current draw state X component of target point Y component of target point A virtual method for the #hb_draw_funcs_t to perform a "move-to" draw operation. draw functions object The data accompanying the draw functions in hb_font_draw_glyph() current draw state X component of target point Y component of target point User data pointer passed to hb_draw_funcs_set_move_to_func() Perform a "quadratic-to" draw operation. draw functions associated draw data passed by the caller current draw state X component of control point Y component of control point X component of target point Y component of target point A virtual method for the #hb_draw_funcs_t to perform a "quadratic-to" draw operation. draw functions object The data accompanying the draw functions in hb_font_draw_glyph() current draw state X component of control point Y component of control point X component of target point Y component of target point User data pointer passed to hb_draw_funcs_set_quadratic_to_func() Current drawing state. Whether there is an open path X component of the start of current path Y component of the start of current path X component of current point Y component of current point Add table for @tag with data provided by @blob to the face. @face must be created using hb_face_builder_create(). A face object created with hb_face_builder_create() The #hb_tag_t of the table to add The blob containing the table data to add Creates a #hb_face_t that can be used with hb_face_builder_add_table(). After tables are added to the face, it can be compiled to a binary font file by calling hb_face_reference_blob(). New face. Set the ordering of tables for serialization. Any tables not specified in the tags list will be ordered after the tables in tags, ordered by the default sort ordering. A face object created with hb_face_builder_create() ordered list of table tags terminated by %HB_TAG_NONE Collects the mapping from Unicode characters to nominal glyphs of the @face, and optionally all of the Unicode characters covered by @face. A face object The map to add Unicode-to-glyph mapping to The set to add Unicode characters to, or `NULL` Collects all of the Unicode characters covered by @face and adds them to the #hb_set_t set @out. A face object The set to add Unicode characters to Collects all Unicode "Variation Selector" characters covered by @face and adds them to the #hb_set_t set @out. A face object The set to add Variation Selector characters to Collects all Unicode characters for @variation_selector covered by @face and adds them to the #hb_set_t set @out. A face object The Variation Selector to query The set to add Unicode characters to Fetches the number of faces in a blob. Number of faces in @blob a blob. Constructs a new face object from the specified blob and a face index into that blob. The face index is used for blobs of file formats such as TTC and DFont that can contain more than one face. Face indices within such collections are zero-based. <note>Note: If the blob font format is not a collection, @index is ignored. Otherwise, only the lower 16-bits of @index are used. The unmodified @index can be accessed via hb_face_get_index().</note> <note>Note: The high 16-bits of @index, if non-zero, are used by hb_font_create() to load named-instances in variable fonts. See hb_font_create() for details.</note> The new face object #hb_blob_t to work upon The index of the face within @blob Variant of hb_face_create(), built for those cases where it is more convenient to provide data for individual tables instead of the whole font data. With the caveat that hb_face_get_table_tags() would not work with faces created this way. You can address that by calling the hb_face_set_get_table_tags_func() function and setting the appropriate callback. Creates a new face object from the specified @user_data and @reference_table_func, with the @destroy callback. The new face object Table-referencing function A pointer to the user data A callback to call when @data is not needed anymore A thin wrapper around hb_blob_create_from_file_or_fail() followed by hb_face_create_or_fail(). The new face object, or `NULL` if no face is found at the specified index or the file cannot be read. A font filename The index of the face within the file A thin wrapper around the face loader functions registered with HarfBuzz. If @loader_name is `NULL` or the empty string, the first available loader is used. For example, the FreeType ("ft") loader might be able to load WOFF and WOFF2 files if FreeType is built with those features, whereas the OpenType ("ot") loader will not. The new face object, or `NULL` if the file cannot be read or the loader fails to load the face. A font filename The index of the face within the file The name of the loader to use, or `NULL` Like hb_face_create(), but returns `NULL` if the blob data contains no usable font face at the specified index. The new face object, or `NULL` if no face is found at the specified index. #hb_blob_t to work upon The index of the face within @blob A thin wrapper around the face loader functions registered with HarfBuzz. If @loader_name is `NULL` or the empty string, the first available loader is used. For example, the FreeType ("ft") loader might be able to load WOFF and WOFF2 files if FreeType is built with those features, whereas the OpenType ("ot") loader will not. The new face object, or `NULL` if the loader fails to load the face. #hb_blob_t to work upon The index of the face within @blob The name of the loader to use, or `NULL` Decreases the reference count on a face object. When the reference count reaches zero, the face is destroyed, freeing all memory. A face object Fetches the singleton empty face object. The empty face object Fetches the glyph-count value of the specified face object. The glyph-count value of @face A face object Fetches the face-index corresponding to the given face. <note>Note: face indices within a collection are zero-based.</note> The index of @face. A face object Fetches a list of all table tags for a face, if possible. The list returned will begin at the offset provided Total number of tables, or zero if it is not possible to list A face object The index of first table tag to retrieve Input = the maximum number of table tags to return; Output = the actual number of table tags returned (may be zero) The array of table tags found Fetches the units-per-em (UPEM) value of the specified face object. Typical UPEM values for fonts are 1000, or 2048, but any value in between 16 and 16,384 is allowed for OpenType fonts. The upem value of @face A face object Fetches the user data associated with the specified key, attached to the specified face object. A pointer to the user data A face object The user-data key to query Tests whether the given face object is immutable. `true` is @face is immutable, `false` otherwise A face object Retrieves the list of face loaders supported by HarfBuzz. a `NULL`-terminated array of supported face loaders constant strings. The returned array is owned by HarfBuzz and should not be modified or freed. Makes the given face object immutable. A face object Increases the reference count on a face object. The @face object A face object Fetches a pointer to the binary blob that contains the specified face. If referencing the face data is not possible, this function creates a blob out of individual table blobs if hb_face_get_table_tags() works with this face, otherwise it returns an empty blob. A pointer to the blob for @face A face object Fetches a reference to the specified table within the specified face. Returns an empty blob if referencing table data is not possible. A pointer to the @tag table within @face A face object The #hb_tag_t of the table to query Sets the table-tag-fetching function for the specified face object. A face object The table-tag-fetching function A pointer to the user data, to be destroyed by @destroy when not needed anymore A callback to call when @func is not needed anymore Sets the glyph count for a face object to the specified value. This API is used in rare circumstances. A face object The glyph-count value to assign Assigns the specified face-index to @face. Fails if the face is immutable. <note>Note: changing the index has no effect on the face itself This only changes the value returned by hb_face_get_index().</note> A face object The index to assign Sets the units-per-em (upem) for a face object to the specified value. This API is used in rare circumstances. A face object The units-per-em value to assign Attaches a user-data key/data pair to the given face object. `true` if success, `false` otherwise A face object The user-data key to set A pointer to the user data A callback to call when @data is not needed anymore Whether to replace an existing data with the same key Data type for holding font faces. Parses a string into a #hb_feature_t. The format for specifying feature strings follows. All valid CSS font-feature-settings values other than 'normal' and the global values are also accepted, though not documented below. CSS string escapes are not supported. The range indices refer to the positions between Unicode characters. The position before the first character is always 0. The format is Python-esque. Here is how it all works: <informaltable pgwide='1' align='left' frame='none'> <tgroup cols='5'> <thead> <row><entry>Syntax</entry> <entry>Value</entry> <entry>Start</entry> <entry>End</entry></row> </thead> <tbody> <row><entry>Setting value:</entry></row> <row><entry>kern</entry> <entry>1</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature on</entry></row> <row><entry>+kern</entry> <entry>1</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature on</entry></row> <row><entry>-kern</entry> <entry>0</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature off</entry></row> <row><entry>kern=0</entry> <entry>0</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature off</entry></row> <row><entry>kern=1</entry> <entry>1</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature on</entry></row> <row><entry>aalt=2</entry> <entry>2</entry> <entry>0</entry> <entry>∞</entry> <entry>Choose 2nd alternate</entry></row> <row><entry>Setting index:</entry></row> <row><entry>kern[]</entry> <entry>1</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature on</entry></row> <row><entry>kern[:]</entry> <entry>1</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature on</entry></row> <row><entry>kern[5:]</entry> <entry>1</entry> <entry>5</entry> <entry>∞</entry> <entry>Turn feature on, partial</entry></row> <row><entry>kern[:5]</entry> <entry>1</entry> <entry>0</entry> <entry>5</entry> <entry>Turn feature on, partial</entry></row> <row><entry>kern[3:5]</entry> <entry>1</entry> <entry>3</entry> <entry>5</entry> <entry>Turn feature on, range</entry></row> <row><entry>kern[3]</entry> <entry>1</entry> <entry>3</entry> <entry>3+1</entry> <entry>Turn feature on, single char</entry></row> <row><entry>Mixing it all:</entry></row> <row><entry>aalt[3:5]=2</entry> <entry>2</entry> <entry>3</entry> <entry>5</entry> <entry>Turn 2nd alternate on for range</entry></row> </tbody> </tgroup> </informaltable> `true` if @str is successfully parsed, `false` otherwise a string to parse length of @str, or -1 if string is `NULL` terminated the #hb_feature_t to initialize with the parsed values The #hb_feature_t is the structure that holds information about requested feature application. The feature will be applied with the given value to all glyphs which are in clusters between @start (inclusive) and @end (exclusive). Setting start to #HB_FEATURE_GLOBAL_START and end to #HB_FEATURE_GLOBAL_END specifies that the feature always applies to the entire buffer. The #hb_tag_t tag of the feature The value of the feature. 0 disables the feature, non-zero (usually 1) enables the feature. For features implemented as lookup type 3 (like 'salt') the @value is a one based index into the alternates. the cluster to start applying this feature setting (inclusive). the cluster to end applying this feature setting (exclusive). Converts a #hb_feature_t into a `NULL`-terminated string in the format understood by hb_feature_from_string(). The client in responsible for allocating big enough size for @buf, 128 bytes is more than enough. Note that the feature value will be omitted if it is '1', but the string won't include any whitespace. an #hb_feature_t to convert output string the allocated size of @buf Converts a #hb_feature_t into a `NULL`-terminated string in the format understood by hb_feature_from_string(). The client in responsible for allocating big enough size for @buf, 128 bytes is more than enough. Note that the feature value will be omitted if it is '1', but the string won't include any whitespace. an #hb_feature_t to convert output string the allocated size of @buf Adds the origin coordinates to an (X,Y) point coordinate, in the specified glyph ID in the specified font. Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of @direction. #hb_font_t to work upon The glyph ID to query The direction of the text segment Input = The original X coordinate Output = The X coordinate plus the X-coordinate of the origin Input = The original Y coordinate Output = The Y coordinate plus the Y-coordinate of the origin Notifies the @font that underlying font data has changed. This has the effect of increasing the serial as returned by hb_font_get_serial(), which invalidates internal caches. #hb_font_t to work upon Constructs a new font object from the specified face. <note>Note: If @face's index value (as passed to hb_face_create() has non-zero top 16-bits, those bits minus one are passed to hb_font_set_var_named_instance(), effectively loading a named-instance of a variable font, instead of the default-instance. This allows specifying which named-instance to load by default when creating the face.</note> The new font object a face. Constructs a sub-font font object from the specified @parent font, replicating the parent's properties. The new sub-font font object The parent font object Decreases the reference count on the given font object. When the reference count reaches zero, the font is destroyed, freeing all memory. #hb_font_t to work upon Draws the outline that corresponds to a glyph in the specified @font. This is an older name for hb_font_draw_glyph_or_fail(), with no return value. The outline is returned by way of calls to the callbacks of the @dfuncs objects, with @draw_data passed to them. #hb_font_t to work upon The glyph ID #hb_draw_funcs_t to draw to User data to pass to draw callbacks A virtual method for the #hb_font_funcs_t of an #hb_font_t object. Use hb_font_draw_glyph_func_or_fail_t instead. #hb_font_t to work upon @font user data pointer The glyph ID to query The draw functions to send the shape data to The data accompanying the draw functions User data pointer passed by the caller Draws the outline that corresponds to a glyph in the specified @font. This is a newer name for hb_font_draw_glyph(), that returns `false` if the font has no outlines for the glyph. The outline is returned by way of calls to the callbacks of the @dfuncs objects, with @draw_data passed to them. `true` if glyph was drawn, `false` otherwise #hb_font_t to work upon The glyph ID #hb_draw_funcs_t to draw to User data to pass to draw callbacks A virtual method for the #hb_font_funcs_t of an #hb_font_t object. `true` if glyph was drawn, `false` otherwise #hb_font_t to work upon @font user data pointer The glyph ID to query The draw functions to send the shape data to The data accompanying the draw functions User data pointer passed by the caller Font-wide extent values, measured in scaled units. Note that typically @ascender is positive and @descender negative, in coordinate systems that grow up. The height of typographic ascenders. The depth of typographic descenders. The suggested line-spacing gap. Creates a new #hb_font_funcs_t structure of font functions. The font-functions structure Decreases the reference count on a font-functions structure. When the reference count reaches zero, the font-functions structure is destroyed, freeing all memory. The font-functions structure Fetches an empty font-functions structure. The font-functions structure Fetches the user data associated with the specified key, attached to the specified font-functions structure. A pointer to the user data The font-functions structure The user-data key to query Tests whether a font-functions structure is immutable. `true` if @ffuncs is immutable, `false` otherwise The font-functions structure Makes a font-functions structure immutable. The font-functions structure Increases the reference count on a font-functions structure. The font-functions structure The font-functions structure Sets the implementation function for #hb_font_draw_glyph_func_t. Use hb_font_funcs_set_draw_glyph_or_fail_func instead. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_draw_glyph_or_fail_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_font_h_extents_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_font_v_extents_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_contour_point_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_extents_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_from_name_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Deprecated. Use hb_font_funcs_set_nominal_glyph_func() and hb_font_funcs_set_variation_glyph_func() instead. The font-functions structure callback function data to pass to @func function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_h_advance_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_h_advances_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_h_kerning_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_h_origin_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_h_origins_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_name_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_shape_func_t, which is the same as #hb_font_draw_glyph_func_t. Use hb_font_funcs_set_draw_glyph_func() instead A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_v_advance_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_v_advances_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_v_kerning_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_v_origin_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_glyph_v_origins_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_nominal_glyph_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_get_nominal_glyphs_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_font_paint_glyph_func_t. Use hb_font_funcs_set_paint_glyph_or_fail_func() instead. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is no longer needed Sets the implementation function for #hb_font_paint_glyph_or_fail_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is no longer needed Attaches a user-data key/data pair to the specified font-functions structure. `true` if success, `false` otherwise The font-functions structure The user-data key to set A pointer to the user data set A callback to call when @data is not needed anymore Whether to replace an existing data with the same key Sets the implementation function for #hb_font_get_variation_glyph_func_t. A font-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Data type containing a set of virtual methods used for working on #hb_font_t font objects. HarfBuzz provides a lightweight default function for each of the methods in #hb_font_funcs_t. Client programs can implement their own replacements for the individual font functions, as needed, and replace the default by calling the setter for a method. Fetches the empty font object. The empty font object Fetches the extents for a font in a text segment of the specified direction. Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of @direction. #hb_font_t to work upon The direction of the text segment The #hb_font_extents_t retrieved Fetches the face associated with the specified font object. The #hb_face_t value #hb_font_t to work upon This method should retrieve the extents for a font. #hb_font_t to work upon @font user data pointer The font extents retrieved User data pointer passed by the caller Fetches the glyph ID for a Unicode code point in the specified font, with an optional variation selector. If @variation_selector is 0, calls hb_font_get_nominal_glyph(); otherwise calls hb_font_get_variation_glyph(). `true` if data found, `false` otherwise #hb_font_t to work upon The Unicode code point to query A variation-selector code point The glyph ID retrieved Fetches the advance for a glyph ID from the specified font, in a text segment of the specified direction. Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of @direction. #hb_font_t to work upon The glyph ID to query The direction of the text segment The horizontal advance retrieved The vertical advance retrieved A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the advance for a specified glyph. The method must return an #hb_position_t. The advance of @glyph within @font #hb_font_t to work upon @font user data pointer The glyph ID to query User data pointer passed by the caller Fetches the advances for a sequence of glyph IDs in the specified font, in a text segment of the specified direction. Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of @direction. #hb_font_t to work upon The direction of the text segment The number of glyph IDs in the sequence queried The first glyph ID to query The stride between successive glyph IDs The first advance retrieved The stride between successive advances A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the advances for a sequence of glyphs. #hb_font_t to work upon @font user data pointer The number of glyph IDs in the sequence queried The first glyph ID to query The stride between successive glyph IDs The first advance retrieved The stride between successive advances User data pointer passed by the caller Fetches the (x,y) coordinates of a specified contour-point index in the specified glyph, within the specified font. `true` if data found, `false` otherwise #hb_font_t to work upon The glyph ID to query The contour-point index to query The X value retrieved for the contour point The Y value retrieved for the contour point Fetches the (X,Y) coordinates of a specified contour-point index in the specified glyph ID in the specified font, with respect to the origin in a text segment in the specified direction. Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of @direction. `true` if data found, `false` otherwise #hb_font_t to work upon The glyph ID to query The contour-point index to query The direction of the text segment The X value retrieved for the contour point The Y value retrieved for the contour point A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the (X,Y) coordinates (in scaled units) for a specified contour point in a glyph. Each coordinate must be returned as an #hb_position_t output parameter. `true` if data found, `false` otherwise #hb_font_t to work upon @font user data pointer The glyph ID to query The contour-point index to query The X value retrieved for the contour point The Y value retrieved for the contour point User data pointer passed by the caller Fetches the #hb_glyph_extents_t data for a glyph ID in the specified font. `true` if data found, `false` otherwise #hb_font_t to work upon The glyph ID to query The #hb_glyph_extents_t retrieved Fetches the #hb_glyph_extents_t data for a glyph ID in the specified font, with respect to the origin in a text segment in the specified direction. Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of @direction. `true` if data found, `false` otherwise #hb_font_t to work upon The glyph ID to query The direction of the text segment The #hb_glyph_extents_t retrieved A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the extents for a specified glyph. Extents must be returned in an #hb_glyph_extents output parameter. `true` if data found, `false` otherwise #hb_font_t to work upon @font user data pointer The glyph ID to query The #hb_glyph_extents_t retrieved User data pointer passed by the caller Fetches the glyph ID that corresponds to a name string in the specified @font. <note>Note: @len == -1 means the name string is null-terminated.</note> `true` if data found, `false` otherwise #hb_font_t to work upon The name string to query The length of the name queried The glyph ID retrieved A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the glyph ID that corresponds to a glyph-name string. `true` if data found, `false` otherwise #hb_font_t to work upon @font user data pointer The name string to query The length of the name queried The glyph ID retrieved User data pointer passed by the caller A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the glyph ID for a specified Unicode code point font, with an optional variation selector. `true` if data found, `false` otherwise #hb_font_t to work upon @font user data pointer The Unicode code point to query The variation-selector code point to query The glyph ID retrieved User data pointer passed by the caller Fetches the advance for a glyph ID in the specified font, for horizontal text segments. The advance of @glyph within @font #hb_font_t to work upon The glyph ID to query Fetches the advances for a sequence of glyph IDs in the specified font, for horizontal text segments. #hb_font_t to work upon The number of glyph IDs in the sequence queried The first glyph ID to query The stride between successive glyph IDs The first advance retrieved The stride between successive advances Fetches the kerning-adjustment value for a glyph-pair in the specified font, for horizontal text segments. <note>It handles legacy kerning only (as returned by the corresponding #hb_font_funcs_t function).</note> The kerning adjustment value #hb_font_t to work upon The glyph ID of the left glyph in the glyph pair The glyph ID of the right glyph in the glyph pair Fetches the (X,Y) coordinates of the origin for a glyph ID in the specified font, for horizontal text segments. `true` if data found, `false` otherwise #hb_font_t to work upon The glyph ID to query The X coordinate of the origin The Y coordinate of the origin Fetches the (X,Y) coordinates of the origin for requested glyph IDs in the specified font, for horizontal text segments. `true` if data found, `false` otherwise #hb_font_t to work upon The number of glyph IDs in the sequence queried The first glyph ID to query The stride between successive glyph IDs The first X coordinate of the origin retrieved The stride between successive X coordinates The first Y coordinate of the origin retrieved The stride between successive Y coordinates Fetches the kerning-adjustment value for a glyph-pair in the specified font. Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of @direction. #hb_font_t to work upon The glyph ID of the first glyph in the glyph pair to query The glyph ID of the second glyph in the glyph pair to query The direction of the text segment The horizontal kerning-adjustment value retrieved The vertical kerning-adjustment value retrieved This method should retrieve the kerning-adjustment value for a glyph-pair in the specified font, for horizontal text segments. #hb_font_t to work upon @font user data pointer The glyph ID of the first glyph in the glyph pair The glyph ID of the second glyph in the glyph pair User data pointer passed by the caller Fetches the glyph-name string for a glyph ID in the specified @font. According to the OpenType specification, glyph names are limited to 63 characters and can only contain (a subset of) ASCII. `true` if data found, `false` otherwise #hb_font_t to work upon The glyph ID to query Name string retrieved for the glyph ID Length of the glyph-name string retrieved A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the glyph name that corresponds to a glyph ID. The name should be returned in a string output parameter. `true` if data found, `false` otherwise #hb_font_t to work upon @font user data pointer The glyph ID to query Name string retrieved for the glyph ID Length of the glyph-name string retrieved User data pointer passed by the caller Fetches the (X,Y) coordinates of the origin for a glyph in the specified font. Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of @direction. #hb_font_t to work upon The glyph ID to query The direction of the text segment The X coordinate retrieved for the origin The Y coordinate retrieved for the origin A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the (X,Y) coordinates (in scaled units) of the origin for a glyph. Each coordinate must be returned in an #hb_position_t output parameter. `true` if data found, `false` otherwise #hb_font_t to work upon @font user data pointer The glyph ID to query The X coordinate of the origin The Y coordinate of the origin User data pointer passed by the caller A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the (X,Y) coordinates (in scaled units) of the origin for each requested glyph. Each coordinate value must be returned in an #hb_position_t in the two output parameters. `true` if data found, `false` otherwise #hb_font_t to work upon @font user data pointer number of glyphs to query The first glyph ID to query The stride between successive glyph IDs The first origin X coordinate retrieved The stride between successive origin X coordinates The first origin Y coordinate retrieved The stride between successive origin Y coordinates User data pointer passed by the caller Fetches the glyph shape that corresponds to a glyph in the specified @font. The shape is returned by way of calls to the callbacks of the @dfuncs objects, with @draw_data passed to them. Use hb_font_draw_glyph() instead #hb_font_t to work upon The glyph ID #hb_draw_funcs_t to draw to User data to pass to draw callbacks A virtual method for the #hb_font_funcs_t of an #hb_font_t object. Use #hb_font_draw_glyph_func_t instead #hb_font_t to work upon @font user data pointer The glyph ID to query The draw functions to send the shape data to The data accompanying the draw functions User data pointer passed by the caller Fetches the advance for a glyph ID in the specified font, for vertical text segments. The advance of @glyph within @font #hb_font_t to work upon The glyph ID to query Fetches the advances for a sequence of glyph IDs in the specified font, for vertical text segments. #hb_font_t to work upon The number of glyph IDs in the sequence queried The first glyph ID to query The stride between successive glyph IDs The first advance retrieved The stride between successive advances Fetches the kerning-adjustment value for a glyph-pair in the specified font, for vertical text segments. <note>It handles legacy kerning only (as returned by the corresponding #hb_font_funcs_t function).</note> The kerning adjustment value #hb_font_t to work upon The glyph ID of the top glyph in the glyph pair The glyph ID of the bottom glyph in the glyph pair Fetches the (X,Y) coordinates of the origin for a glyph ID in the specified font, for vertical text segments. `true` if data found, `false` otherwise #hb_font_t to work upon The glyph ID to query The X coordinate of the origin The Y coordinate of the origin Fetches the (X,Y) coordinates of the origin for requested glyph IDs in the specified font, for vertical text segments. `true` if data found, `false` otherwise #hb_font_t to work upon The number of glyph IDs in the sequence queried The first glyph ID to query The stride between successive glyph IDs The first X coordinate of the origin retrieved The stride between successive X coordinates The first Y coordinate of the origin retrieved The stride between successive Y coordinates Fetches the extents for a specified font, for horizontal text segments. `true` if data found, `false` otherwise #hb_font_t to work upon The font extents retrieved Fetches the nominal glyph ID for a Unicode code point in the specified font. This version of the function should not be used to fetch glyph IDs for code points modified by variation selectors. For variation-selector support, user hb_font_get_variation_glyph() or use hb_font_get_glyph(). `true` if data found, `false` otherwise #hb_font_t to work upon The Unicode code point to query The glyph ID retrieved A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the nominal glyph ID for a specified Unicode code point. Glyph IDs must be returned in a #hb_codepoint_t output parameter. `true` if data found, `false` otherwise #hb_font_t to work upon @font user data pointer The Unicode code point to query The glyph ID retrieved User data pointer passed by the caller Fetches the nominal glyph IDs for a sequence of Unicode code points. Glyph IDs must be returned in a #hb_codepoint_t output parameter. Stops at the first unsupported glyph ID. the number of code points processed #hb_font_t to work upon number of code points to query The first Unicode code point to query The stride between successive code points The first glyph ID retrieved The stride between successive glyph IDs A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the nominal glyph IDs for a sequence of Unicode code points. Glyph IDs must be returned in a #hb_codepoint_t output parameter. the number of code points processed #hb_font_t to work upon @font user data pointer number of code points to query The first Unicode code point to query The stride between successive code points The first glyph ID retrieved The stride between successive glyph IDs User data pointer passed by the caller Fetches the parent font of @font. The parent font object #hb_font_t to work upon Fetches the horizontal and vertical points-per-em (ppem) of a font. #hb_font_t to work upon Horizontal ppem value Vertical ppem value Fetches the "point size" of a font. Used in CoreText to implement optical sizing. Point size. A value of zero means "not set." #hb_font_t to work upon Fetches the horizontal and vertical scale of a font. #hb_font_t to work upon Horizontal scale value Vertical scale value Returns the internal serial number of the font. The serial number is increased every time a setting on the font is changed, using a setter function. serial number #hb_font_t to work upon Fetches the "synthetic boldness" parameters of a font. #hb_font_t to work upon return location for horizontal value return location for vertical value return location for in-place value Fetches the "synthetic slant" of a font. Synthetic slant. By default is zero. #hb_font_t to work upon Fetches the user-data object associated with the specified key, attached to the specified font object. Pointer to the user data #hb_font_t to work upon The user-data key to query Fetches the extents for a specified font, for vertical text segments. `true` if data found, `false` otherwise #hb_font_t to work upon The font extents retrieved Fetches the list of variation coordinates (in design-space units) currently set on a font. <note>Note that if no variation coordinates are set, this function may return %NULL.</note> <note>If variations have been set on the font using normalized coordinates (i.e. via hb_font_set_var_coords_normalized()), the design coordinates will have NaN (Not a Number) values.</note> Return value is valid as long as variation coordinates of the font are not modified. coordinates array #hb_font_t to work upon Number of coordinates retrieved Fetches the list of normalized variation coordinates currently set on a font. <note>Note that if no variation coordinates are set, this function may return %NULL.</note> Return value is valid as long as variation coordinates of the font are not modified. coordinates array #hb_font_t to work upon Number of coordinates retrieved Returns the currently-set named-instance index of the font. Named-instance index or %HB_FONT_NO_VAR_NAMED_INSTANCE. a font. Fetches the glyph ID for a Unicode code point when followed by by the specified variation-selector code point, in the specified font. `true` if data found, `false` otherwise #hb_font_t to work upon The Unicode code point to query The variation-selector code point to query The glyph ID retrieved A virtual method for the #hb_font_funcs_t of an #hb_font_t object. This method should retrieve the glyph ID for a specified Unicode code point followed by a specified Variation Selector code point. Glyph IDs must be returned in a #hb_codepoint_t output parameter. `true` if data found, `false` otherwise #hb_font_t to work upon @font user data pointer The Unicode code point to query The variation-selector code point to query The glyph ID retrieved User data pointer passed by the caller Fetches the glyph ID from @font that matches the specified string. Strings of the format `gidDDD` or `uniUUUU` are parsed automatically. <note>Note: @len == -1 means the string is null-terminated.</note> `true` if data found, `false` otherwise #hb_font_t to work upon string to query The length of the string @s The glyph ID corresponding to the string requested Fetches the name of the specified glyph ID in @font and returns it in string @s. If the glyph ID has no name in @font, a string of the form `gidDDD` is generated, with `DDD` being the glyph ID. According to the OpenType specification, glyph names are limited to 63 characters and can only contain (a subset of) ASCII. #hb_font_t to work upon The glyph ID to query The string containing the glyph name Length of string @s Tests whether a font object is immutable. `true` if @font is immutable, `false` otherwise #hb_font_t to work upon Tests whether a font is synthetic. A synthetic font is one that has either synthetic slant or synthetic bold set on it. `true` if the font is synthetic, `false` otherwise. #hb_font_t to work upon Retrieves the list of font functions supported by HarfBuzz. a `NULL`-terminated array of supported font functions constant strings. The returned array is owned by HarfBuzz and should not be modified or freed. Makes @font immutable. #hb_font_t to work upon Paints the glyph. This function is similar to hb_font_paint_glyph_or_fail(), but if painting a color glyph failed, it will fall back to painting an outline monochrome glyph. The painting instructions are returned by way of calls to the callbacks of the @funcs object, with @paint_data passed to them. If the font has color palettes (see hb_ot_color_has_palettes()), then @palette_index selects the palette to use. If the font only has one palette, this will be 0. #hb_font_t to work upon The glyph ID #hb_paint_funcs_t to paint with User data to pass to paint callbacks The index of the font's color palette to use The foreground color, unpremultipled A virtual method for the #hb_font_funcs_t of an #hb_font_t object. Use hb_font_paint_glyph_or_fail_func_t instead. #hb_font_t to work upon @font user data pointer The glyph ID to query The paint functions to use The data accompanying the paint functions The color palette to use The foreground color User data pointer passed by the caller Paints a color glyph. This function is similar to, but lower-level than, hb_font_paint_glyph(). It is suitable for clients that need more control. If there are no color glyphs available, it will return `false`. The client can then fall back to hb_font_draw_glyph_or_fail() for the monochrome outline glyph. The painting instructions are returned by way of calls to the callbacks of the @funcs object, with @paint_data passed to them. If the font has color palettes (see hb_ot_color_has_palettes()), then @palette_index selects the palette to use. If the font only has one palette, this will be 0. `true` if glyph was painted, `false` otherwise #hb_font_t to work upon The glyph ID #hb_paint_funcs_t to paint with User data to pass to paint callbacks The index of the font's color palette to use The foreground color, unpremultipled A virtual method for the #hb_font_funcs_t of an #hb_font_t object. `true` if glyph was painted, `false` otherwise #hb_font_t to work upon @font user data pointer The glyph ID to query The paint functions to use The data accompanying the paint functions The color palette to use The foreground color User data pointer passed by the caller Increases the reference count on the given font object. The @font object #hb_font_t to work upon Sets @face as the font-face value of @font. #hb_font_t to work upon The #hb_face_t to assign Replaces the font-functions structure attached to a font, updating the font's user-data with @font-data and the @destroy callback. #hb_font_t to work upon The font-functions structure. Data to attach to @font The function to call when @font_data is not needed anymore Replaces the user data attached to a font, updating the font's @destroy callback. #hb_font_t to work upon Data to attach to @font The function to call when @font_data is not needed anymore Sets the font-functions structure to use for a font, based on the specified name. If @name is `NULL` or the empty string, the default (first) functioning font-functions are used. This default can be changed by setting the `HB_FONT_FUNCS` environment variable to the name of the desired font-functions. `true` if the font-functions was found and set, `false` otherwise #hb_font_t to work upon The name of the font-functions structure to use, or `NULL` Sets the parent font of @font. #hb_font_t to work upon The parent font object to assign Sets the horizontal and vertical pixels-per-em (PPEM) of a font. These values are used for pixel-size-specific adjustment to shaping and draw results, though for the most part they are unused and can be left unset. #hb_font_t to work upon Horizontal ppem value to assign Vertical ppem value to assign Sets the "point size" of a font. Set to zero to unset. Used in CoreText to implement optical sizing. <note>Note: There are 72 points in an inch.</note> #hb_font_t to work upon font size in points. Sets the horizontal and vertical scale of a font. The font scale is a number related to, but not the same as, font size. Typically the client establishes a scale factor to be used between the two. For example, 64, or 256, which would be the fractional-precision part of the font scale. This is necessary because #hb_position_t values are integer types and you need to leave room for fractional values in there. For example, to set the font size to 20, with 64 levels of fractional precision you would call `hb_font_set_scale(font, 20 * 64, 20 * 64)`. In the example above, even what font size 20 means is up to you. It might be 20 pixels, or 20 points, or 20 millimeters. HarfBuzz does not care about that. You can set the point size of the font using hb_font_set_ptem(), and the pixel size using hb_font_set_ppem(). The choice of scale is yours but needs to be consistent between what you set here, and what you expect out of #hb_position_t as well has draw / paint API output values. Fonts default to a scale equal to the UPEM value of their face. A font with this setting is sometimes called an "unscaled" font. #hb_font_t to work upon Horizontal scale value to assign Vertical scale value to assign Sets the "synthetic boldness" of a font. Positive values for @x_embolden / @y_embolden make a font bolder, negative values thinner. Typical values are in the 0.01 to 0.05 range. The default value is zero. Synthetic boldness is applied by offsetting the contour points of the glyph shape. Synthetic boldness is applied when rendering a glyph via hb_font_draw_glyph_or_fail(). If @in_place is `false`, then glyph advance-widths are also adjusted, otherwise they are not. The in-place mode is useful for simulating [font grading](https://fonts.google.com/knowledge/glossary/grade). #hb_font_t to work upon the amount to embolden horizontally the amount to embolden vertically whether to embolden glyphs in-place Sets the "synthetic slant" of a font. By default is zero. Synthetic slant is the graphical skew applied to the font at rendering time. HarfBuzz needs to know this value to adjust shaping results, metrics, and style values to match the slanted rendering. <note>Note: The glyph shape fetched via the hb_font_draw_glyph_or_fail() function is slanted to reflect this value as well.</note> <note>Note: The slant value is a ratio. For example, a 20% slant would be represented as a 0.2 value.</note> #hb_font_t to work upon synthetic slant value. Attaches a user-data key/data pair to the specified font object. `true` if success, `false` otherwise #hb_font_t to work upon The user-data key A pointer to the user data A callback to call when @data is not needed anymore Whether to replace an existing data with the same key Applies a list of variation coordinates (in design-space units) to a font. Note that this overrides all existing variations set on @font. Axes not included in @coords will be effectively set to their default values. #hb_font_t to work upon Array of variation coordinates to apply Number of coordinates to apply Applies a list of variation coordinates (in normalized units) to a font. Note that this overrides all existing variations set on @font. Axes not included in @coords will be effectively set to their default values. <note>Note: Coordinates should be normalized to 2.14.</note> #hb_font_t to work upon Array of variation coordinates to apply Number of coordinates to apply Sets design coords of a font from a named-instance index. a font. named instance index. Change the value of one variation axis on the font. Note: This function is expensive to be called repeatedly. If you want to set multiple variation axes at the same time, use hb_font_set_variations() instead. #hb_font_t to work upon The #hb_tag_t tag of the variation-axis name The value of the variation axis Applies a list of font-variation settings to a font. Note that this overrides all existing variations set on @font. Axes not included in @variations will be effectively set to their default values. #hb_font_t to work upon Array of variation settings to apply Number of variations to apply Subtracts the origin coordinates from an (X,Y) point coordinate, in the specified glyph ID in the specified font. Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of @direction. #hb_font_t to work upon The glyph ID to query The direction of the text segment Input = The original X coordinate Output = The X coordinate minus the X-coordinate of the origin Input = The original Y coordinate Output = The Y coordinate minus the Y-coordinate of the origin Data type for holding fonts. Frees the memory pointed to by @ptr, using the allocator set at compile-time. Typically just free(). The pointer to the memory to free. Creates an #hb_face_t face object from the specified font blob and face index. This is similar in functionality to hb_face_create_from_blob_or_fail(), but uses the FreeType library for loading the font blob. This can be useful, for example, to load WOFF and WOFF2 font data. The new face object, or `NULL` if loading fails (eg. blob does not contain valid font data). A blob The index of the face within the blob Creates an #hb_face_t face object from the specified font file and face index. This is similar in functionality to hb_face_create_from_file_or_fail(), but uses the FreeType library for loading the font file. This can be useful, for example, to load WOFF and WOFF2 font data. The new face object, or `NULL` if no face is found at the specified index or the file cannot be read. A font filename The index of the face within the file Refreshes the state of @font when the underlying FT_Face has changed. This function should be called after changing the size or variation-axis settings on the FT_Face. #hb_font_t to work upon Fetches the FT_Face associated with the specified #hb_font_t font object. This function works with #hb_font_t objects created by hb_ft_font_create() or hb_ft_font_create_referenced(). the FT_Face found or `NULL` #hb_font_t to work upon Fetches the FT_Load_Glyph load flags of the specified #hb_font_t. For more information, see <https://freetype.org/freetype2/docs/reference/ft2-glyph_retrieval.html#ft_load_xxx> This function works with #hb_font_t objects created by hb_ft_font_create() or hb_ft_font_create_referenced(). FT_Load_Glyph flags found, or 0 #hb_font_t to work upon Configures the font-functions structure of the specified #hb_font_t font object to use FreeType font functions. In particular, you can use this function to configure an existing #hb_face_t face object for use with FreeType font functions even if that #hb_face_t face object was initially created with hb_face_create(), and therefore was not initially configured to use FreeType font functions. An #hb_font_t object created with hb_ft_font_create() is preconfigured for FreeType font functions and does not require this function to be used. Note that if you modify the underlying #hb_font_t after calling this function, you need to call hb_ft_hb_font_changed() to update the underlying FT_Face. <note>Note: Internally, this function creates an FT_Face. </note> #hb_font_t to work upon Sets the FT_Load_Glyph load flags for the specified #hb_font_t. For more information, see <https://freetype.org/freetype2/docs/reference/ft2-glyph_retrieval.html#ft_load_xxx> This function works with #hb_font_t objects created by hb_ft_font_create() or hb_ft_font_create_referenced(). #hb_font_t to work upon The FreeType load flags to set Releases an FT_Face previously obtained with hb_ft_font_lock_face(). #hb_font_t to work upon Refreshes the state of the underlying FT_Face of @font when the hb_font_t @font has changed. This function should be called after changing the size or variation-axis settings on the @font. This call is fast if nothing has changed on @font. Note that as of version 11.0.0, calling this function is not necessary, as HarfBuzz will automatically detect changes to the font and update the underlying FT_Face as needed. true if changed, false otherwise #hb_font_t to work upon Callback function for hb_face_get_table_tags(). Total number of tables, or zero if it is not possible to list A face object The index of first table tag to retrieve Input = the maximum number of table tags to return; Output = the actual number of table tags returned (may be zero) The array of table tags found User data pointer passed by the caller Creates an #hb_blob_t blob from the specified GBytes data structure. the new #hb_blob_t blob object the GBytes structure to work upon Fetches a Unicode-functions structure that is populated with the appropriate GLib function for each method. a pointer to the #hb_unicode_funcs_t Unicode-functions structure Fetches the GUnicodeScript identifier that corresponds to the specified #hb_script_t script. the GUnicodeScript identifier found The #hb_script_t to query Fetches the #hb_script_t script that corresponds to the specified GUnicodeScript identifier. the #hb_script_t script found The GUnicodeScript identifier to query Glyph extent values, measured in font units. Note that @height is negative, in coordinate systems that grow up. Distance from the x-origin to the left extremum of the glyph. Distance from the top extremum of the glyph to the y-origin. Distance from the left extremum of the glyph to the right extremum. Distance from the top extremum of the glyph to the bottom extremum. Flags for #hb_glyph_info_t. Indicates that if input text is broken at the beginning of the cluster this glyph is part of, then both sides need to be re-shaped, as the result might be different. On the flip side, it means that when this flag is not present, then it is safe to break the glyph-run at the beginning of this cluster, and the two sides will represent the exact same result one would get if breaking input text at the beginning of this cluster and shaping the two sides separately. This can be used to optimize paragraph layout, by avoiding re-shaping of each line after line-breaking. Indicates that if input text is changed on one side of the beginning of the cluster this glyph is part of, then the shaping results for the other side might change. Note that the absence of this flag will NOT by itself mean that it IS safe to concat text. Only two pieces of text both of which clear of this flag can be concatenated safely. This can be used to optimize paragraph layout, by avoiding re-shaping of each line after line-breaking, by limiting the reshaping to a small piece around the breaking position only, even if the breaking position carries the #HB_GLYPH_FLAG_UNSAFE_TO_BREAK or when hyphenation or other text transformation happens at line-break position, in the following way: 1. Iterate back from the line-break position until the first cluster start position that is NOT unsafe-to-concat, 2. shape the segment from there till the end of line, 3. check whether the resulting glyph-run also is clear of the unsafe-to-concat at its start-of-text position; if it is, just splice it into place and the line is shaped; If not, move on to a position further back that is clear of unsafe-to-concat and retry from there, and repeat. At the start of next line a similar algorithm can be implemented. That is: 1. Iterate forward from the line-break position until the first cluster start position that is NOT unsafe-to-concat, 2. shape the segment from beginning of the line to that position, 3. check whether the resulting glyph-run also is clear of the unsafe-to-concat at its end-of-text position; if it is, just splice it into place and the beginning is shaped; If not, move on to a position further forward that is clear of unsafe-to-concat and retry up to there, and repeat. A slight complication will arise in the implementation of the algorithm above, because while our buffer API has a way to return flags for position corresponding to start-of-text, there is currently no position corresponding to end-of-text. This limitation can be alleviated by shaping more text than needed and looking for unsafe-to-concat flag within text clusters. The #HB_GLYPH_FLAG_UNSAFE_TO_BREAK flag will always imply this flag. To use this flag, you must enable the buffer flag @HB_BUFFER_FLAG_PRODUCE_UNSAFE_TO_CONCAT during shaping, otherwise the buffer flag will not be reliably produced. Since: 4.0.0 In scripts that use elongation (Arabic, Mongolian, Syriac, etc.), this flag signifies that it is safe to insert a U+0640 TATWEEL character before this cluster for elongation. This flag does not determine the script-specific elongation places, but only when it is safe to do the elongation without interrupting text shaping. Since: 5.1.0 All the currently defined flags. Returns glyph flags encoded within a #hb_glyph_info_t. The #hb_glyph_flags_t encoded within @info a #hb_glyph_info_t The #hb_glyph_info_t is the structure that holds information about the glyphs and their relation to input text. either a Unicode code point (before shaping) or a glyph index (after shaping). the index of the character in the original text that corresponds to this #hb_glyph_info_t, or whatever the client passes to hb_buffer_add(). More than one #hb_glyph_info_t can have the same @cluster value, if they resulted from the same character (e.g. one to many glyph substitution), and when more than one character gets merged in the same glyph (e.g. many to one glyph substitution) the #hb_glyph_info_t will have the smallest cluster value of them. By default some characters are merged into the same cluster (e.g. combining marks have the same cluster as their bases) even if they are separate glyphs, hb_buffer_set_cluster_level() allow selecting more fine-grained cluster handling. The #hb_glyph_position_t is the structure that holds the positions of the glyph in both horizontal and vertical directions. All positions in #hb_glyph_position_t are relative to the current point. how much the line advances after drawing this glyph when setting text in horizontal direction. how much the line advances after drawing this glyph when setting text in vertical direction. how much the glyph moves on the X-axis before drawing it, this should not affect how much the line advances. how much the glyph moves on the Y-axis before drawing it, this should not affect how much the line advances. Functions for querying AAT Layout features in the font face. HarfBuzz supports all of the AAT tables used to implement shaping. Other AAT tables and their associated features are not supported. Blobs wrap a chunk of binary data to handle lifecycle management of data while it is passed between client and HarfBuzz. Blobs are primarily used to create font faces, but also to access font face tables, as well as pass around other binary data. Buffers serve a dual role in HarfBuzz; before shaping, they hold the input characters that are passed to hb_shape(), and after shaping they hold the output glyphs. The input buffer is a sequence of Unicode codepoints, with associated attributes such as direction and script. The output buffer is a sequence of glyphs, with associated attributes such as position and cluster. Common data types used across HarfBuzz are defined here. These API have been deprecated in favor of newer API, or because they were deemed unnecessary. Functions for drawing (extracting) glyph shapes. The #hb_draw_funcs_t struct can be used with hb_font_draw_glyph(). A font face is an object that represents a single face from within a font family. More precisely, a font face represents a single face in a binary font file. Font faces are typically built from a binary blob and a face index. Font faces are used to create fonts. A font face can be created from a binary blob using hb_face_create(). The face index is used to select a face from a binary blob that contains multiple faces. For example, a binary blob that contains both a regular and a bold face can be used to create two font faces, one for each face index. Functions for working with font objects. A font object represents a font face at a specific size and with certain other parameters (pixels-per-em, points-per-em, variation settings) specified. Font objects are created from font face objects, and are used as input to hb_shape(), among other things. Client programs can optionally pass in their own functions that implement the basic, lower-level queries of font objects. This set of font functions is defined by the virtual methods in #hb_font_funcs_t. HarfBuzz provides a built-in set of lightweight default functions for each method in #hb_font_funcs_t. The default font functions are implemented in terms of the #hb_font_funcs_t methods of the parent font object. This allows client programs to override only the methods they need to, and otherwise inherit the parent font's implementation, if any. Functions for using HarfBuzz with the FreeType library. HarfBuzz supports using FreeType to provide face and font data. <note>Note that FreeType is not thread-safe, therefore these functions are not thread-safe either.</note> Functions for using HarfBuzz with the GLib library. HarfBuzz supports using GLib to provide Unicode data, by attaching GLib functions to the virtual methods in a #hb_unicode_funcs_t function structure. Map objects are integer-to-integer hash-maps. Currently they are not used in the HarfBuzz public API, but are provided for client's use if desired. Functions for fetching color-font information from OpenType font faces. HarfBuzz supports `COLR`/`CPAL`, `sbix`, `CBDT`, and `SVG` color fonts. Functions for using OpenType fonts with hb_shape(). Note that fonts returned by hb_font_create() default to using these functions, so most clients would never need to call these functions directly. Functions for querying OpenType Layout features in the font face. See the [OpenType specification](http://www.microsoft.com/typography/otspec/) for details. Functions for fetching mathematics layout data from OpenType fonts. HarfBuzz itself does not implement a math layout solution. The functions and types provided can be used by client programs to access the font data necessary for typesetting OpenType Math layout. Functions for fetching metadata from fonts. Functions for fetching metrics from fonts. Functions for fetching name strings from OpenType fonts. Support functions for OpenType shaping related queries. Functions for fetching information about OpenType Variable Fonts. Functions for painting glyphs. The main purpose of these functions is to paint (extract) color glyph layers from the COLRv1 table, but the API works for drawing ordinary outlines and images as well. The #hb_paint_funcs_t struct can be used with hb_font_paint_glyph(). Set objects represent a mathematical set of integer values. They are used in non-shaping APIs to query certain sets of characters or glyphs, or other integer values. Shaping is the central operation of HarfBuzz. Shaping operates on buffers, which are sequences of Unicode characters that use the same font and have the same text direction, script, and language. After shaping the buffer contains the output glyphs and their positions. Shape plans are an internal mechanism. Each plan contains state describing how HarfBuzz will shape a particular text segment, based on the combination of segment properties and the capabilities in the font face in use. Shape plans are not used for shaping directly, but can be queried to access certain information about how shaping will perform, given a set of specific input parameters (script, language, direction, features, etc.). Most client programs will not need to deal with shape plans directly. Functions for fetching style information from fonts. Unicode functions are used to access Unicode character properties. With these functions, client programs can query various properties from the Unicode Character Database for any code point, such as General Category (gc), Script (sc), Canonical Combining Class (ccc), etc. Client programs can optionally pass in their own Unicode functions that implement the same queries. The set of functions available is defined by the virtual methods in #hb_unicode_funcs_t. HarfBuzz provides built-in default functions for each method in #hb_unicode_funcs_t. These functions and macros allow accessing version of the HarfBuzz library used at compile- as well as run-time, and to direct code conditionally based on those versions, again, at compile- or run-time. Converts @str representing a BCP 47 language tag to the corresponding #hb_language_t. The #hb_language_t corresponding to the BCP 47 language tag. a string representing a BCP 47 language tag length of the @str, or -1 if it is `NULL`-terminated. Fetch the default language from current locale. <note>Note that the first time this function is called, it calls "setlocale (LC_CTYPE, nullptr)" to fetch current locale. The underlying setlocale function is, in many implementations, NOT threadsafe. To avoid problems, call this function once before multiple threads can call it. This function is only used from hb_buffer_guess_segment_properties() by HarfBuzz itself.</note> The default language of the locale as an #hb_language_t Check whether a second language tag is the same or a more specific version of the provided language tag. For example, "fa_IR.utf8" is a more specific tag for "fa" or for "fa_IR". `true` if languages match, `false` otherwise. The #hb_language_t to work on Another #hb_language_t Data type for languages. Each #hb_language_t corresponds to a BCP 47 language tag. Converts an #hb_language_t to a string. A `NULL`-terminated string representing the @language. Must not be freed by the caller. The #hb_language_t to convert Converts an #hb_language_t to a string. A `NULL`-terminated string representing the @language. Must not be freed by the caller. The #hb_language_t to convert Allocates @size bytes of memory, using the allocator set at compile-time. Typically just malloc(). A pointer to the allocated memory. The size of the memory to allocate. Tests whether memory allocation for a set was successful. `true` if allocation succeeded, `false` otherwise A map Clears out the contents of @map. A map Allocate a copy of @map. Newly-allocated map. A map Creates a new, initially empty map. The new #hb_map_t Removes @key and its stored value from @map. A map The key to delete Decreases the reference count on a map. When the reference count reaches zero, the map is destroyed, freeing all memory. A map Fetches the value stored for @key in @map. A map The key to query Fetches the singleton empty #hb_map_t. The empty #hb_map_t Returns the number of key-value pairs in the map. The population of @map A map Fetches the user data associated with the specified key, attached to the specified map. A pointer to the user data A map The user-data key to query Tests whether @key is an element of @map. `true` if @key is found in @map, `false` otherwise A map The key to query Creates a hash representing @map. A hash of @map. A map Tests whether @map is empty (contains no elements). `true` if @map is empty A map Tests whether @map and @other are equal (contain the same elements). `true` if the two maps are equal, `false` otherwise. A map Another map Add the keys of @map to @keys. A map A set Fetches the next key/value pair in @map. Set @idx to -1 to get started. If the map is modified during iteration, the behavior is undefined. The order in which the key/values are returned is undefined. `true` if there was a next value, `false` otherwise A map Iterator internal state Key retrieved Value retrieved Increases the reference count on a map. The map A map Stores @key:@value in the map. A map The key to store in the map The value to store for @key Attaches a user-data key/data pair to the specified map. `true` if success, `false` otherwise A map The user-data key to set A pointer to the user data to set A callback to call when @data is not needed anymore Whether to replace an existing data with the same key Data type for holding integer-to-integer hash maps. Add the contents of @other to @map. A map Another map Add the values of @map to @values. A map A set Data type holding the memory modes available to client programs. Regarding these various memory-modes: - In no case shall the HarfBuzz client modify memory that is passed to HarfBuzz in a blob. If there is any such possibility, @HB_MEMORY_MODE_DUPLICATE should be used such that HarfBuzz makes a copy immediately, - Use @HB_MEMORY_MODE_READONLY otherwise, unless you really really really know what you are doing, - @HB_MEMORY_MODE_WRITABLE is appropriate if you really made a copy of data solely for the purpose of passing to HarfBuzz and doing that just once (no reuse!), - If the font is mmap()ed, it's okay to use @HB_MEMORY_MODE_READONLY_MAY_MAKE_WRITABLE, however, using that mode correctly is very tricky. Use @HB_MEMORY_MODE_READONLY instead. HarfBuzz immediately makes a copy of the data. HarfBuzz client will never modify the data, and HarfBuzz will never modify the data. HarfBuzz client made a copy of the data solely for HarfBuzz, so HarfBuzz may modify the data. See above Fetches a list of all color layers for the specified glyph index in the specified face. The list returned will begin at the offset provided. Total number of layers available for the glyph index queried #hb_face_t to work upon The glyph index to query offset of the first layer to retrieve Input = the maximum number of layers to return; Output = the actual number of layers returned (may be zero) The array of layers found Tests where a face includes COLRv1 paint data for @glyph. `true` if data found, `false` otherwise #hb_face_t to work upon The glyph index to query Fetches the PNG image for a glyph. This function takes a font object, not a face object, as input. To get an optimally sized PNG blob, the PPEM values must be set on the @font object. If PPEM is unset, the blob returned will be the largest PNG available. If the glyph has no PNG image, the singleton empty blob is returned. An #hb_blob_t containing the PNG image for the glyph, if available #hb_font_t to work upon a glyph index Fetches the SVG document for a glyph. The blob may be either plain text or gzip-encoded. If the glyph has no SVG document, the singleton empty blob is returned. An #hb_blob_t containing the SVG document of the glyph, if available #hb_face_t to work upon a svg glyph index Tests whether a face includes a `COLR` table with data according to COLRv0. `true` if data found, `false` otherwise #hb_face_t to work upon Tests where a face includes a `COLR` table with data according to COLRv1. `true` if data found, `false` otherwise #hb_face_t to work upon Tests whether a face includes a `CPAL` color-palette table. `true` if data found, `false` otherwise #hb_face_t to work upon Tests whether a face has PNG glyph images (either in `CBDT` or `sbix` tables). `true` if data found, `false` otherwise #hb_face_t to work upon Tests whether a face includes any `SVG` glyph images. `true` if data found, `false` otherwise. #hb_face_t to work upon. Pairs of glyph and color index. A color index of 0xFFFF does not refer to a palette color, but indicates that the foreground color should be used. the glyph ID of the layer the palette color index of the layer Fetches the `name` table Name ID that provides display names for the specified color in a face's `CPAL` color palette. Display names can be generic (e.g., "Background") or specific (e.g., "Eye color"). the Name ID found for the color. #hb_face_t to work upon The index of the color Flags that describe the properties of color palette. Default indicating that there is nothing special to note about a color palette. Flag indicating that the color palette is appropriate to use when displaying the font on a light background such as white. Flag indicating that the color palette is appropriate to use when displaying the font on a dark background such as black. Fetches a list of the colors in a color palette. After calling this function, @colors will be filled with the palette colors. If @colors is NULL, the function will just return the number of total colors without storing any actual colors; this can be used for allocating a buffer of suitable size before calling hb_ot_color_palette_get_colors() a second time. The RGBA values in the palette are unpremultiplied. See the OpenType spec [CPAL](https://learn.microsoft.com/en-us/typography/opentype/spec/cpal) section for details. the total number of colors in the palette #hb_face_t to work upon the index of the color palette to query offset of the first color to retrieve Input = the maximum number of colors to return; Output = the actual number of colors returned (may be zero) The array of #hb_color_t records found Fetches the number of color palettes in a face. the number of palettes found #hb_face_t to work upon Fetches the flags defined for a color palette. the #hb_ot_color_palette_flags_t of the requested color palette #hb_face_t to work upon The index of the color palette Fetches the `name` table Name ID that provides display names for a `CPAL` color palette. Palette display names can be generic (e.g., "Default") or provide specific, themed names (e.g., "Spring", "Summer", "Fall", and "Winter"). the Named ID found for the palette. If the requested palette has no name the result is #HB_OT_NAME_ID_INVALID. #hb_face_t to work upon The index of the color palette Sets the font functions to use when working with @font to the HarfBuzz's native implementation. This is the default for fonts newly created. #hb_font_t to work upon Baseline tags from [Baseline Tags](https://docs.microsoft.com/en-us/typography/opentype/spec/baselinetags) registry. The baseline used by alphabetic scripts such as Latin, Cyrillic and Greek. In vertical writing mode, the alphabetic baseline for characters rotated 90 degrees clockwise. (This would not apply to alphabetic characters that remain upright in vertical writing mode, since these characters are not rotated.) The hanging baseline. In horizontal direction, this is the horizontal line from which syllables seem, to hang in Tibetan and other similar scripts. In vertical writing mode, for Tibetan (or some other similar script) characters rotated 90 degrees clockwise. Ideographic character face bottom or left edge, if the direction is horizontal or vertical, respectively. Ideographic character face top or right edge, if the direction is horizontal or vertical, respectively. The center of the ideographic character face. Since: 4.0.0 Ideographic em-box bottom or left edge, if the direction is horizontal or vertical, respectively. Ideographic em-box top or right edge baseline, The center of the ideographic em-box. Since: 4.0.0 if the direction is horizontal or vertical, respectively. The baseline about which mathematical characters are centered. In vertical writing mode when mathematical characters rotated 90 degrees clockwise, are centered. Fetches a list of all feature indexes in the specified face's GSUB table or GPOS table, underneath the specified scripts, languages, and features. If no list of scripts is provided, all scripts will be queried. If no list of languages is provided, all languages will be queried. If no list of features is provided, all features will be queried. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The array of scripts to collect features for, terminated by %HB_TAG_NONE The array of languages to collect features for, terminated by %HB_TAG_NONE The array of features to collect, terminated by %HB_TAG_NONE The set of feature indexes found for the query Fetches the mapping from feature tags to feature indexes for the specified script and language. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The index of the requested script tag The index of the requested language tag The map of feature tag to feature index. Fetches a list of all feature-lookup indexes in the specified face's GSUB table or GPOS table, underneath the specified scripts, languages, and features. If no list of scripts is provided, all scripts will be queried. If no list of languages is provided, all languages will be queried. If no list of features is provided, all features will be queried. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The array of scripts to collect lookups for, terminated by %HB_TAG_NONE The array of languages to collect lookups for, terminated by %HB_TAG_NONE The array of features to collect lookups for, terminated by %HB_TAG_NONE The array of lookup indexes found for the query Fetches a list of the characters defined as having a variant under the specified "Character Variant" ("cvXX") feature tag. Number of total sample characters in the cvXX feature. #hb_face_t to work upon table tag to query, "GSUB" or "GPOS". index of feature to query. offset of the first character to retrieve Input = the maximum number of characters to return; Output = the actual number of characters returned (may be zero) A buffer pointer. The Unicode codepoints of the characters for which this feature provides glyph variants. Fetches a list of all lookups enumerated for the specified feature, in the specified face's GSUB table or GPOS table. The list returned will begin at the offset provided. Total number of lookups. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The index of the requested feature offset of the first lookup to retrieve Input = the maximum number of lookups to return; Output = the actual number of lookups returned (may be zero) The array of lookup indexes found for the query Fetches name indices from feature parameters for "Stylistic Set" ('ssXX') or "Character Variant" ('cvXX') features. `true` if data found, `false` otherwise #hb_face_t to work upon table tag to query, "GSUB" or "GPOS". index of feature to query. The ‘name’ table name ID that specifies a string for a user-interface label for this feature. The ‘name’ table name ID that specifies a string that an application can use for tooltip text for this feature. The ‘name’ table name ID that specifies sample text that illustrates the effect of this feature. Number of named parameters. The first ‘name’ table name ID used to specify strings for user-interface labels for the feature parameters. (Must be zero if numParameters is zero.) Fetches a list of all lookups enumerated for the specified feature, in the specified face's GSUB table or GPOS table, enabled at the specified variations index. The list returned will begin at the offset provided. Total number of lookups. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The index of the feature to query The index of the feature variation to query offset of the first lookup to retrieve Input = the maximum number of lookups to return; Output = the actual number of lookups returned (may be zero) The array of lookups found for the query Fetches a list of all attachment points for the specified glyph in the GDEF table of the face. The list returned will begin at the offset provided. Useful if the client program wishes to cache the list. Total number of attachment points for @glyph. The #hb_face_t to work on The #hb_codepoint_t code point to query offset of the first attachment point to retrieve Input = the maximum number of attachment points to return; Output = the actual number of attachment points returned (may be zero) The array of attachment points found for the query Fetches a baseline value from the face. `true` if found baseline value in the font. a font a baseline tag text direction. script tag. language tag, currently unused. baseline value if found. Fetches a baseline value from the face. This function is like hb_ot_layout_get_baseline() but takes #hb_script_t and #hb_language_t instead of OpenType #hb_tag_t. `true` if found baseline value in the font. a font a baseline tag text direction. script. language, currently unused. baseline value if found. Fetches a baseline value from the face, and synthesizes it if the font does not have it. a font a baseline tag text direction. script tag. language tag, currently unused. baseline value if found. Fetches a baseline value from the face, and synthesizes it if the font does not have it. This function is like hb_ot_layout_get_baseline_with_fallback() but takes #hb_script_t and #hb_language_t instead of OpenType #hb_tag_t. a font a baseline tag text direction. script. language, currently unused. baseline value if found. Fetches script/language-specific font extents. These values are looked up in the `BASE` table's `MinMax` records. If no such extents are found, the default extents for the font are fetched. As such, the return value of this function can for the most part be ignored. Note that the per-script/language extents do not have a line-gap value, and the line-gap is set to zero in that case. `true` if found script/language-specific font extents. a font text direction. script tag. language tag. font extents if found. Fetches script/language-specific font extents. These values are looked up in the `BASE` table's `MinMax` records. If no such extents are found, the default extents for the font are fetched. As such, the return value of this function can for the most part be ignored. Note that the per-script/language extents do not have a line-gap value, and the line-gap is set to zero in that case. This function is like hb_ot_layout_get_font_extents() but takes #hb_script_t and #hb_language_t instead of OpenType #hb_tag_t. `true` if found script/language-specific font extents. a font text direction. script. language. font extents if found. Fetches the GDEF class of the requested glyph in the specified face. The #hb_ot_layout_glyph_class_t glyph class of the given code point in the GDEF table of the face. The #hb_face_t to work on The #hb_codepoint_t code point to query Retrieves the set of all glyphs from the face that belong to the requested glyph class in the face's GDEF table. The #hb_face_t to work on The #hb_ot_layout_glyph_class_t GDEF class to retrieve The #hb_set_t set of all glyphs belonging to the requested class. Fetches the dominant horizontal baseline tag used by @script. dominant baseline tag for the @script. a script tag. Fetches a list of the caret positions defined for a ligature glyph in the GDEF table of the font. The list returned will begin at the offset provided. Note that a ligature that is formed from n characters will have n-1 caret positions. The first character is not represented in the array, since its caret position is the glyph position. The positions returned by this function are 'unshaped', and will have to be fixed up for kerning that may be applied to the ligature glyph. Total number of ligature caret positions for @glyph. The #hb_font_t to work on The #hb_direction_t text direction to use The #hb_codepoint_t code point to query offset of the first caret position to retrieve Input = the maximum number of caret positions to return; Output = the actual number of caret positions returned (may be zero) The array of caret positions found for the query Fetches optical-size feature data (i.e., the `size` feature from GPOS). Note that the subfamily_id and the subfamily name string (accessible via the subfamily_name_id) as used here are defined as pertaining only to fonts within a font family that differ specifically in their respective size ranges; other ways to differentiate fonts within a subfamily are not covered by the `size` feature. For more information on this distinction, see the [`size` feature documentation]( https://docs.microsoft.com/en-us/typography/opentype/spec/features_pt#tag-size). `true` if data found, `false` otherwise #hb_face_t to work upon The design size of the face The identifier of the face within the font subfamily The ‘name’ table name ID of the face within the font subfamily The minimum size of the recommended size range for the face The maximum size of the recommended size range for the face The GDEF classes defined for glyphs. Glyphs not matching the other classifications Spacing, single characters, capable of accepting marks Glyphs that represent ligation of multiple characters Non-spacing, combining glyphs that represent marks Spacing glyphs that represent part of a single character Tests whether a face has any glyph classes defined in its GDEF table. `true` if data found, `false` otherwise #hb_face_t to work upon Tests whether the specified face includes any GPOS positioning. `true` if the face has GPOS data, `false` otherwise #hb_face_t to work upon Tests whether the specified face includes any GSUB substitutions. `true` if data found, `false` otherwise #hb_face_t to work upon Fetches the index of a given feature tag in the specified face's GSUB table or GPOS table, underneath the specified script and language. `true` if the feature is found, `false` otherwise #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The index of the requested script tag The index of the requested language tag #hb_tag_t of the feature tag requested The index of the requested feature Fetches a list of all features in the specified face's GSUB table or GPOS table, underneath the specified script and language. The list returned will begin at the offset provided. Total number of features. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The index of the requested script tag The index of the requested language tag offset of the first feature tag to retrieve Input = the maximum number of feature tags to return; Output: the actual number of feature tags returned (may be zero) The array of feature indexes found for the query Fetches a list of all features in the specified face's GSUB table or GPOS table, underneath the specified script and language. The list returned will begin at the offset provided. Total number of feature tags. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The index of the requested script tag The index of the requested language tag offset of the first feature tag to retrieve Input = the maximum number of feature tags to return; Output = the actual number of feature tags returned (may be zero) The array of #hb_tag_t feature tags found for the query Fetches the tag of a requested feature index in the given face's GSUB or GPOS table, underneath the specified script and language. `true` if the feature is found, `false` otherwise #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The index of the requested script tag The index of the requested language tag The index of the requested feature The #hb_tag_t of the requested feature Fetches the index of a requested feature in the given face's GSUB or GPOS table, underneath the specified script and language. `true` if the feature is found, `false` otherwise #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The index of the requested script tag The index of the requested language tag The index of the requested feature Collects alternates of glyphs from a given GSUB lookup index. For one-to-one GSUB glyph substitutions, this function collects the substituted glyph. For lookups that assign multiple alternates to a glyph, all alternate glyphs are collected. For other lookup types, nothing is performed and `false` is returned. The `alternate_count` mapping will contain the number of alternates for each glyph id. Upon entry, this mapping should contain the glyph ids as keys, and the number of alternates currently known for each glyph id as values. The `alternate_glyphs` mapping will contain the alternate glyph ids for each glyph id. The mapping is encoded in the following way, upon entry and after processing: If G is the glyph id, and A0, A1, ..., A(n-1) are the alternate glyph ids, the mapping will contain the following entries: (G + (i << 24)) -> A(i) for i = 0, 1, ..., n-1 where n is the number of alternates for G as per `alternate_count`. `true` if alternates were collected, `false` otherwise. a face. index of the feature lookup to query. mapping from glyph index to number of alternates for that glyph. mapping from encoded glyph index and alternate index, to alternate glyph ids. Fetches a list of all glyphs affected by the specified lookup in the specified face's GSUB table or GPOS table. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The index of the feature lookup to query Array of glyphs preceding the substitution range Array of input glyphs that would be substituted by the lookup Array of glyphs following the substitution range Array of glyphs that would be the substituted output of the lookup Fetches alternates of a glyph from a given GSUB lookup index. Note that for one-to-one GSUB glyph substitutions, this function fetches the substituted glyph. Total number of alternates found in the specific lookup index for the given glyph id. a face. index of the feature lookup to query. a glyph id. starting offset. Input = the maximum number of alternate glyphs to return; Output = the actual number of alternate glyphs returned (may be zero). A glyphs buffer. Alternate glyphs associated with the glyph id. Fetches the optical bound of a glyph positioned at the margin of text. The direction identifies which edge of the glyph to query. Adjustment value. Negative values mean the glyph will stick out of the margin. a font. index of the feature lookup to query. edge of the glyph to query. a glyph id. Compute the transitive closure of glyphs needed for a specified lookup. #hb_face_t to work upon index of the feature lookup to query Array of glyphs comprising the transitive closure of the lookup Tests whether a specified lookup in the specified face would trigger a substitution on the given glyph sequence. `true` if a substitution would be triggered, `false` otherwise #hb_face_t to work upon The index of the lookup to query The sequence of glyphs to query for substitution The length of the glyph sequence #hb_bool_t indicating whether pre-/post-context are disallowed in substitutions Compute the transitive closure of glyphs needed for all of the provided lookups. #hb_face_t to work upon The set of lookups to query Array of glyphs comprising the transitive closure of the lookups Fetches the index of a given language tag in the specified face's GSUB table or GPOS table, underneath the specified script tag. `true` if the language tag is found, `false` otherwise #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The index of the requested script tag The #hb_tag_t of the requested language The index of the requested language Fetches a list of language tags in the given face's GSUB or GPOS table, underneath the specified script index. The list returned will begin at the offset provided. Total number of language tags. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The index of the requested script tag offset of the first language tag to retrieve Input = the maximum number of language tags to return; Output = the actual number of language tags returned (may be zero) Array of language tags found in the table Fetches the index of the first language tag fom @language_tags that is present in the specified face's GSUB or GPOS table, underneath the specified script index. If none of the given language tags is found, `false` is returned and @language_index is set to the default language index. `true` if one of the given language tags is found, `false` otherwise #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The index of the requested script tag The number of languages in the specified script The array of language tags The index of the requested language Fetches the index of the first language tag fom @language_tags that is present in the specified face's GSUB or GPOS table, underneath the specified script index. If none of the given language tags is found, `false` is returned and @language_index is set to #HB_OT_LAYOUT_DEFAULT_LANGUAGE_INDEX and @chosen_language is set to #HB_TAG_NONE. `true` if one of the given language tags is found, `false` otherwise #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The index of the requested script tag The number of languages in the specified script The array of language tags The index of the chosen language #hb_tag_t of the chosen language Deprecated since 2.0.0 #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS Array of #hb_tag_t script tags The index of the chosen script #hb_tag_t of the chosen script Fetches a list of feature variations in the specified face's GSUB table or GPOS table, at the specified variation coordinates. `true` if feature variations were found, `false` otherwise. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS The variation coordinates to query The number of variation coordinates The array of feature variations found for the query Fetches the index if a given script tag in the specified face's GSUB table or GPOS table. `true` if the script is found, `false` otherwise #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS #hb_tag_t of the script tag requested The index of the requested script tag Fetches a list of all feature tags in the given face's GSUB or GPOS table. Note that there might be duplicate feature tags, belonging to different script/language-system pairs of the table. Total number of feature tags. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS offset of the first feature tag to retrieve Input = the maximum number of feature tags to return; Output = the actual number of feature tags returned (may be zero) Array of feature tags found in the table Fetches the total number of lookups enumerated in the specified face's GSUB table or GPOS table. Total number of lookups. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS Fetches a list of all scripts enumerated in the specified face's GSUB table or GPOS table. The list returned will begin at the offset provided. Total number of script tags. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS offset of the first script tag to retrieve Input = the maximum number of script tags to return; Output = the actual number of script tags returned (may be zero) The array of #hb_tag_t script tags found for the query Selects an OpenType script for @table_tag from the @script_tags array. If the table does not have any of the requested scripts, then `DFLT`, `dflt`, and `latn` tags are tried in that order. If the table still does not have any of these scripts, @script_index is set to #HB_OT_LAYOUT_NO_SCRIPT_INDEX and @chosen_script is set to #HB_TAG_NONE. `true` if one of the requested scripts is selected, `false` if a fallback script is selected or if no scripts are selected. #hb_face_t to work upon #HB_OT_TAG_GSUB or #HB_OT_TAG_GPOS Number of script tags in the array Array of #hb_tag_t script tags The index of the requested script #hb_tag_t of the requested script The 'MATH' table constants, refer to [OpenType documentation](https://docs.microsoft.com/en-us/typography/opentype/spec/math#mathconstants-table) For more explanations. scriptPercentScaleDown scriptScriptPercentScaleDown delimitedSubFormulaMinHeight displayOperatorMinHeight mathLeading axisHeight accentBaseHeight flattenedAccentBaseHeight subscriptShiftDown subscriptTopMax subscriptBaselineDropMin superscriptShiftUp superscriptShiftUpCramped superscriptBottomMin superscriptBaselineDropMax subSuperscriptGapMin superscriptBottomMaxWithSubscript spaceAfterScript upperLimitGapMin upperLimitBaselineRiseMin lowerLimitGapMin lowerLimitBaselineDropMin stackTopShiftUp stackTopDisplayStyleShiftUp stackBottomShiftDown stackBottomDisplayStyleShiftDown stackGapMin stackDisplayStyleGapMin stretchStackTopShiftUp stretchStackBottomShiftDown stretchStackGapAboveMin stretchStackGapBelowMin fractionNumeratorShiftUp fractionNumeratorDisplayStyleShiftUp fractionDenominatorShiftDown fractionDenominatorDisplayStyleShiftDown fractionNumeratorGapMin fractionNumDisplayStyleGapMin fractionRuleThickness fractionDenominatorGapMin fractionDenomDisplayStyleGapMin skewedFractionHorizontalGap skewedFractionVerticalGap overbarVerticalGap overbarRuleThickness overbarExtraAscender underbarVerticalGap underbarRuleThickness underbarExtraDescender radicalVerticalGap radicalDisplayStyleVerticalGap radicalRuleThickness radicalExtraAscender radicalKernBeforeDegree radicalKernAfterDegree radicalDegreeBottomRaisePercent Fetches the specified math constant. For most constants, the value returned is an #hb_position_t. However, if the requested constant is #HB_OT_MATH_CONSTANT_SCRIPT_PERCENT_SCALE_DOWN, #HB_OT_MATH_CONSTANT_SCRIPT_SCRIPT_PERCENT_SCALE_DOWN or #HB_OT_MATH_CONSTANT_RADICAL_DEGREE_BOTTOM_RAISE_PERCENT, then the return value is an integer between 0 and 100 representing that percentage. the requested constant or zero #hb_font_t to work upon #hb_ot_math_constant_t the constant to retrieve Fetches the GlyphAssembly for the specified font, glyph index, and direction. Returned are a list of #hb_ot_math_glyph_part_t glyph parts that can be used to draw the glyph and an italics-correction value (if one is defined in the font). <note>The @direction parameter is only used to select between horizontal or vertical directions for the construction. Even though all #hb_direction_t values are accepted, only the result of #HB_DIRECTION_IS_HORIZONTAL is considered.</note> the total number of parts in the glyph assembly #hb_font_t to work upon The index of the glyph to stretch direction of the stretching (horizontal or vertical) offset of the first glyph part to retrieve Input = maximum number of glyph parts to return; Output = actual number of parts returned the glyph parts returned italics correction of the glyph assembly Fetches an italics-correction value (if one exists) for the specified glyph index. the italics correction of the glyph or zero #hb_font_t to work upon The glyph index from which to retrieve the value Fetches the math kerning (cut-ins) value for the specified font, glyph index, and @kern. If the MathKern table is found, the function examines it to find a height value that is greater or equal to @correction_height. If such a height value is found, corresponding kerning value from the table is returned. If no such height value is found, the last kerning value is returned. requested kerning value or zero #hb_font_t to work upon The glyph index from which to retrieve the value The #hb_ot_math_kern_t from which to retrieve the value the correction height to use to determine the kerning. Fetches the raw MathKern (cut-in) data for the specified font, glyph index, and @kern. The corresponding list of kern values and correction heights is returned as a list of #hb_ot_math_kern_entry_t structs. See also #hb_ot_math_get_glyph_kerning, which handles selecting the appropriate kern value for a given correction height. <note>For a glyph with @n defined kern values (where @n > 0), there are only @n−1 defined correction heights, as each correction height defines a boundary past which the next kern value should be selected. Therefore, only the #hb_ot_math_kern_entry_t.kern_value of the uppermost #hb_ot_math_kern_entry_t actually comes from the font; its corresponding #hb_ot_math_kern_entry_t.max_correction_height is always set to <code>INT32_MAX</code>.</note> the total number of kern values available or zero #hb_font_t to work upon The glyph index from which to retrieve the kernings The #hb_ot_math_kern_t from which to retrieve the kernings offset of the first kern entry to retrieve Input = the maximum number of kern entries to return; Output = the actual number of kern entries returned array of kern entries returned Fetches a top-accent-attachment value (if one exists) for the specified glyph index. For any glyph that does not have a top-accent-attachment value - that is, a glyph not covered by the `MathTopAccentAttachment` table (or, when @font has no `MathTopAccentAttachment` table or no `MATH` table, any glyph) - the function synthesizes a value, returning the position at one-half the glyph's advance width. the top accent attachment of the glyph or 0.5 * the advance width of @glyph #hb_font_t to work upon The glyph index from which to retrieve the value Fetches the MathGlyphConstruction for the specified font, glyph index, and direction. The corresponding list of size variants is returned as a list of #hb_ot_math_glyph_variant_t structs. <note>The @direction parameter is only used to select between horizontal or vertical directions for the construction. Even though all #hb_direction_t values are accepted, only the result of #HB_DIRECTION_IS_HORIZONTAL is considered.</note> the total number of size variants available or zero #hb_font_t to work upon The index of the glyph to stretch The direction of the stretching (horizontal or vertical) offset of the first variant to retrieve Input = the maximum number of variants to return; Output = the actual number of variants returned array of variants returned Fetches the MathVariants table for the specified font and returns the minimum overlap of connecting glyphs that are required to draw a glyph assembly in the specified direction. <note>The @direction parameter is only used to select between horizontal or vertical directions for the construction. Even though all #hb_direction_t values are accepted, only the result of #HB_DIRECTION_IS_HORIZONTAL is considered.</note> requested minimum connector overlap or zero #hb_font_t to work upon direction of the stretching (horizontal or vertical) Flags for math glyph parts. This is an extender glyph part that can be repeated to reach the desired length. Data type to hold information for a "part" component of a math-variant glyph. Large variants for stretchable math glyphs (such as parentheses) can be constructed on the fly from parts. The glyph index of the variant part The length of the connector on the starting side of the variant part The length of the connector on the ending side of the variant part The total advance of the part #hb_ot_math_glyph_part_flags_t flags for the part Data type to hold math-variant information for a glyph. The glyph index of the variant The advance width of the variant Tests whether a face has a `MATH` table. `true` if the table is found, `false` otherwise #hb_face_t to test Tests whether the given glyph index is an extended shape in the face. `true` if the glyph is an extended shape, `false` otherwise #hb_face_t to work upon The glyph index to test Data type to hold math kerning (cut-in) information for a glyph. The maximum height at which this entry should be used The kern value of the entry The math kerning-table types defined for the four corners of a glyph. The top right corner of the glyph. The top left corner of the glyph. The bottom right corner of the glyph. The bottom left corner of the glyph. Fetches all available feature types. Number of all available feature types. a face object iteration's start offset buffer size as input, filled size as output entries tags buffer It fetches metadata entry of a given tag from a font. A blob containing the blob. a #hb_face_t object. tag of metadata you like to have. Known metadata tags from https://docs.microsoft.com/en-us/typography/opentype/spec/meta Design languages. Text, using only Basic Latin (ASCII) characters. Indicates languages and/or scripts for the user audiences that the font was primarily designed for. Supported languages. Text, using only Basic Latin (ASCII) characters. Indicates languages and/or scripts that the font is declared to be capable of supporting. Fetches metrics value corresponding to @metrics_tag from @font. Whether found the requested metrics in the font. an #hb_font_t object. tag of metrics value you like to fetch. result of metrics value from the font. Fetches metrics value corresponding to @metrics_tag from @font, and synthesizes a value if it the value is missing in the font. an #hb_font_t object. tag of metrics value you like to fetch. result of metrics value from the font. Fetches metrics value corresponding to @metrics_tag from @font with the current font variation settings applied. The requested metric value. an #hb_font_t object. tag of metrics value you like to fetch. Fetches horizontal metrics value corresponding to @metrics_tag from @font with the current font variation settings applied. The requested metric value. an #hb_font_t object. tag of metrics value you like to fetch. Fetches vertical metrics value corresponding to @metrics_tag from @font with the current font variation settings applied. The requested metric value. an #hb_font_t object. tag of metrics value you like to fetch. Metric tags corresponding to [MVAR Value Tags](https://docs.microsoft.com/en-us/typography/opentype/spec/mvar#value-tags) horizontal ascender. horizontal descender. horizontal line gap. horizontal clipping ascent. horizontal clipping descent. vertical ascender. vertical descender. vertical line gap. horizontal caret rise. horizontal caret run. horizontal caret offset. vertical caret rise. vertical caret run. vertical caret offset. x height. cap height. subscript em x size. subscript em y size. subscript em x offset. subscript em y offset. superscript em x size. superscript em y size. superscript em x offset. superscript em y offset. strikeout size. strikeout offset. underline size. underline offset. Structure representing a name ID in a particular language. name ID language Fetches a font name from the OpenType 'name' table. If @language is #HB_LANGUAGE_INVALID, English ("en") is assumed. Returns string in UTF-16 encoding. A NUL terminator is always written for convenience, and isn't included in the output @text_size. full length of the requested string, or 0 if not found. font face. OpenType name identifier to fetch. language to fetch the name for. input size of @text buffer, and output size of text written to buffer. buffer to write fetched name into. Fetches a font name from the OpenType 'name' table. If @language is #HB_LANGUAGE_INVALID, English ("en") is assumed. Returns string in UTF-32 encoding. A NUL terminator is always written for convenience, and isn't included in the output @text_size. full length of the requested string, or 0 if not found. font face. OpenType name identifier to fetch. language to fetch the name for. input size of @text buffer, and output size of text written to buffer. buffer to write fetched name into. Fetches a font name from the OpenType 'name' table. If @language is #HB_LANGUAGE_INVALID, English ("en") is assumed. Returns string in UTF-8 encoding. A NUL terminator is always written for convenience, and isn't included in the output @text_size. full length of the requested string, or 0 if not found. font face. OpenType name identifier to fetch. language to fetch the name for. input size of @text buffer, and output size of text written to buffer. buffer to write fetched name into. An enum type representing the pre-defined name IDs. For more information on these fields, see the [OpenType spec](https://docs.microsoft.com/en-us/typography/opentype/spec/name#name-ids). Copyright notice Font Family name Font Subfamily name Unique font identifier Full font name that reflects all family and relevant subfamily descriptors Version string PostScript name for the font Trademark Manufacturer Name Designer Description URL of font vendor URL of typeface designer License Description URL where additional licensing information can be found Typographic Family name Typographic Subfamily name Compatible Full Name for MacOS Sample text PostScript CID findfont name WWS Family Name WWS Subfamily Name Light Background Palette Dark Background Palette Variations PostScript Name Prefix Value to represent a nonexistent name ID. Enumerates all available name IDs and language combinations. Returned array is owned by the @face and should not be modified. It can be used as long as @face is alive. Array of available name entries. font face. number of returned entries. Computes the transitive closure of glyphs needed for a specified input buffer under the given font and feature list. The closure is computed as a set, not as a list. #hb_font_t to work upon The input buffer to compute from The features enabled on the buffer The number of features enabled on the buffer The #hb_set_t set of glyphs comprising the transitive closure of the query Computes the complete set of GSUB or GPOS lookups that are applicable under a given @shape_plan. #hb_shape_plan_t to query GSUB or GPOS The #hb_set_t set of lookups returned Fetches the list of OpenType feature tags enabled for a shaping plan, if possible. Total number of feature tagss. A shaping plan The index of first feature to retrieve Input = the maximum number of features to return; Output = the actual number of features returned (may be zero) The array of enabled feature Converts an #hb_language_t to an #hb_tag_t. use hb_ot_tags_from_script_and_language() instead an #hb_language_t to convert. Converts a language tag to an #hb_language_t. The #hb_language_t corresponding to @tag. an language tag Converts a script tag to an #hb_script_t. The #hb_script_t corresponding to @tag. a script tag Converts an #hb_script_t to script tags. use hb_ot_tags_from_script_and_language() instead an #hb_script_t to convert. output #hb_tag_t. output #hb_tag_t. Converts an #hb_script_t and an #hb_language_t to script and language tags. an #hb_script_t to convert. an #hb_language_t to convert. maximum number of script tags to retrieve (IN) and actual number of script tags retrieved (OUT) array of size at least @script_count to store the script tag results maximum number of language tags to retrieve (IN) and actual number of language tags retrieved (OUT) array of size at least @language_count to store the language tag results Converts a script tag and a language tag to an #hb_script_t and an #hb_language_t. a script tag a language tag the #hb_script_t corresponding to @script_tag. the #hb_language_t corresponding to @script_tag and @language_tag. Flags for #hb_ot_var_axis_info_t. The axis should not be exposed directly in user interfaces. Data type for holding variation-axis values. The minimum, default, and maximum values are in un-normalized, user scales. <note>Note: at present, the only flag defined for @flags is #HB_OT_VAR_AXIS_FLAG_HIDDEN.</note> Index of the axis in the variation-axis array The #hb_tag_t tag identifying the design variation of the axis The `name` table Name ID that provides display names for the axis The #hb_ot_var_axis_flags_t flags for the axis The minimum value on the variation axis that the font covers The position on the variation axis corresponding to the font's defaults The maximum value on the variation axis that the font covers Use #hb_ot_var_axis_info_t instead. axis tag axis name identifier minimum value of the axis default value of the axis maximum value of the axis Fetches the variation-axis information corresponding to the specified axis tag in the specified face. use hb_ot_var_find_axis_info() instead #hb_face_t to work upon The #hb_tag_t of the variation axis to query The index of the variation axis The #hb_ot_var_axis_info_t of the axis tag queried Fetches the variation-axis information corresponding to the specified axis tag in the specified face. `true` if data found, `false` otherwise #hb_face_t to work upon The #hb_tag_t of the variation axis to query The #hb_ot_var_axis_info_t of the axis tag queried Fetches a list of all variation axes in the specified face. The list returned will begin at the offset provided. use hb_ot_var_get_axis_infos() instead #hb_face_t to work upon offset of the first lookup to retrieve Input = the maximum number of variation axes to return; Output = the actual number of variation axes returned (may be zero) The array of variation axes found Fetches the number of OpenType variation axes included in the face. the number of variation axes defined The #hb_face_t to work on Fetches a list of all variation axes in the specified face. The list returned will begin at the offset provided. the number of variation axes in the face #hb_face_t to work upon offset of the first lookup to retrieve Input = the maximum number of variation axes to return; Output = the actual number of variation axes returned (may be zero) The array of variation axes found Fetches the number of named instances included in the face. the number of named instances defined The #hb_face_t to work on Tests whether a face includes any OpenType variation data in the `fvar` table. `true` if data found, `false` otherwise The #hb_face_t to work on Fetches the design-space coordinates corresponding to the given named instance in the face. the number of variation axes in the face The #hb_face_t to work on The index of the named instance to query Input = the maximum number of coordinates to return; Output = the actual number of coordinates returned (may be zero) The array of coordinates found for the query Fetches the `name` table Name ID that provides display names for the "PostScript name" defined for the given named instance in the face. the Name ID found for the PostScript name The #hb_face_t to work on The index of the named instance to query Fetches the `name` table Name ID that provides display names for the "Subfamily name" defined for the given named instance in the face. the Name ID found for the Subfamily name The #hb_face_t to work on The index of the named instance to query Normalizes the given design-space coordinates. The minimum and maximum values for the axis are mapped to the interval [-1,1], with the default axis value mapped to 0. The normalized values have 14 bits of fixed-point sub-integer precision as per OpenType specification. Any additional scaling defined in the face's `avar` table is also applied, as described at https://docs.microsoft.com/en-us/typography/opentype/spec/avar Note: @coords_length must be the same as the number of axes in the face, as for example returned by hb_ot_var_get_axis_count(). Otherwise, the behavior is undefined. The #hb_face_t to work on The length of the coordinate array The design-space coordinates to normalize The normalized coordinates Normalizes all of the coordinates in the given list of variation axes. The #hb_face_t to work on The array of variations to normalize The number of variations to normalize The array of normalized coordinates The length of the coordinate array Perform a "color" paint operation. paint functions associated data passed by the caller whether the color is the foreground The color to use A virtual method for the #hb_paint_funcs_t to paint a color everywhere within the current clip. paint functions object The data accompanying the paint functions in hb_font_paint_glyph() whether the color is the foreground The color to use, unpremultiplied User data pointer passed to hb_paint_funcs_set_color_func() Perform a "color-glyph" paint operation. paint functions associated data passed by the caller the glyph ID the font A virtual method for the #hb_paint_funcs_t to render a color glyph by glyph index. `true` if the glyph was painted, `false` otherwise. paint functions object The data accompanying the paint functions in hb_font_paint_glyph() the glyph ID the font User data pointer passed to hb_paint_funcs_set_color_glyph_func() The values of this enumeration describe the compositing modes that can be used when combining temporary redirected drawing with the backdrop. See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr) section for details. clear destination layer (bounded) replace destination layer (bounded) ignore the source draw source layer on top of destination layer (bounded) draw destination on top of source draw source where there was destination content (unbounded) leave destination only where there was source content (unbounded) draw source where there was no destination content (unbounded) leave destination only where there was no source content draw source on top of destination content and only there leave destination on top of source content and only there (unbounded) source and destination are shown where there is only one of them source and destination layers are accumulated source and destination are complemented and multiplied. This causes the result to be at least as light as the lighter inputs. multiplies or screens, depending on the lightness of the destination color. replaces the destination with the source if it is darker, otherwise keeps the source. replaces the destination with the source if it is lighter, otherwise keeps the source. brightens the destination color to reflect the source color. darkens the destination color to reflect the source color. Multiplies or screens, dependent on source color. Darkens or lightens, dependent on source color. Takes the difference of the source and destination color. Produces an effect similar to difference, but with lower contrast. source and destination layers are multiplied. This causes the result to be at least as dark as the darker inputs. Creates a color with the hue of the source and the saturation and luminosity of the target. Creates a color with the saturation of the source and the hue and luminosity of the target. Painting with this mode onto a gray area produces no change. Creates a color with the hue and saturation of the source and the luminosity of the target. This preserves the gray levels of the target and is useful for coloring monochrome images or tinting color images. Creates a color with the luminosity of the source and the hue and saturation of the target. This produces an inverse effect to @HB_PAINT_COMPOSITE_MODE_HSL_COLOR. Gets the custom palette color for @color_index. `true` if found, `false` otherwise paint functions associated data passed by the caller color index fetched color A virtual method for the #hb_paint_funcs_t to fetch a color from the custom color palette. Custom palette colors override the colors from the fonts selected color palette. It is not necessary to override all palette entries; for entries that should be taken from the font palette, return `false`. This function might get called multiple times, but the custom palette is expected to remain unchanged for duration of a hb_font_paint_glyph() call. `true` if found, `false` otherwise paint functions object The data accompanying the paint functions in hb_font_paint_glyph() the color index fetched color User data pointer passed to hb_paint_funcs_set_pop_group_func() The values of this enumeration determine how color values outside the minimum and maximum defined offset on a #hb_color_line_t are determined. See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr) section for details. Outside the defined interval, the color of the closest color stop is used. The color line is repeated over repeated multiples of the defined interval The color line is repeated over repeated intervals, as for the repeat mode. However, in each repeated interval, the ordering of color stops is the reverse of the adjacent interval. Creates a new #hb_paint_funcs_t structure of paint functions. The initial reference count of 1 should be released with hb_paint_funcs_destroy() when you are done using the #hb_paint_funcs_t. This function never returns `NULL`. If memory cannot be allocated, a special singleton #hb_paint_funcs_t object will be returned. the paint-functions structure Decreases the reference count on a paint-functions structure. When the reference count reaches zero, the structure is destroyed, freeing all memory. The paint-functions structure Fetches the singleton empty paint-functions structure. The empty paint-functions structure Fetches the user-data associated with the specified key, attached to the specified paint-functions structure. A pointer to the user data The paint-functions structure The user-data key to query Tests whether a paint-functions structure is immutable. `true` if @funcs is immutable, `false` otherwise The paint-functions structure Makes a paint-functions structure immutable. After this call, all attempts to set one of the callbacks on @funcs will fail. The paint-functions structure Increases the reference count on a paint-functions structure. This prevents @funcs from being destroyed until a matching call to hb_paint_funcs_destroy() is made. The paint-functions structure The paint-functions structure Sets the paint-color callback on the paint functions struct. A paint functions struct The paint-color callback Data to pass to @func Function to call when @user_data is no longer needed Sets the color-glyph callback on the paint functions struct. A paint functions struct The color-glyph callback Data to pass to @func Function to call when @user_data is no longer needed Sets the custom-palette-color callback on the paint functions struct. A paint functions struct The custom-palette-color callback Data to pass to @func Function to call when @user_data is no longer needed Sets the paint-image callback on the paint functions struct. A paint functions struct The paint-image callback Data to pass to @func Function to call when @user_data is no longer needed Sets the linear-gradient callback on the paint functions struct. A paint functions struct The linear-gradient callback Data to pass to @func Function to call when @user_data is no longer needed Sets the pop-clip callback on the paint functions struct. A paint functions struct The pop-clip callback Data to pass to @func Function to call when @user_data is no longer needed Sets the pop-group callback on the paint functions struct. A paint functions struct The pop-group callback Data to pass to @func Function to call when @user_data is no longer needed Sets the pop-transform callback on the paint functions struct. A paint functions struct The pop-transform callback Data to pass to @func Function to call when @user_data is no longer needed Sets the push-clip-glyph callback on the paint functions struct. A paint functions struct The push-clip-glyph callback Data to pass to @func Function to call when @user_data is no longer needed Sets the push-clip-rect callback on the paint functions struct. A paint functions struct The push-clip-rectangle callback Data to pass to @func Function to call when @user_data is no longer needed Sets the push-group callback on the paint functions struct. A paint functions struct The push-group callback Data to pass to @func Function to call when @user_data is no longer needed Sets the push-transform callback on the paint functions struct. A paint functions struct The push-transform callback Data to pass to @func Function to call when @user_data is no longer needed Sets the radial-gradient callback on the paint functions struct. A paint functions struct The radial-gradient callback Data to pass to @func Function to call when @user_data is no longer needed Sets the sweep-gradient callback on the paint functions struct. A paint functions struct The sweep-gradient callback Data to pass to @func Function to call when @user_data is no longer needed Attaches a user-data key/data pair to the specified paint-functions structure. `true` if success, `false` otherwise The paint-functions structure The user-data key A pointer to the user data A callback to call when @data is not needed anymore Whether to replace an existing data with the same key Glyph paint callbacks. The callbacks assume that the caller maintains a stack of current transforms, clips and intermediate surfaces, as evidenced by the pairs of push/pop callbacks. The push/pop calls will be properly nested, so it is fine to store the different kinds of object on a single stack. Not all callbacks are required for all kinds of glyphs. For rendering COLRv0 or non-color outline glyphs, the gradient callbacks are not needed, and the composite callback only needs to handle simple alpha compositing (#HB_PAINT_COMPOSITE_MODE_SRC_OVER). The paint-image callback is only needed for glyphs with image blobs in the CBDT, sbix or SVG tables. The custom-palette-color callback is only necessary if you want to override colors from the font palette with custom colors. Perform a "image" paint operation. paint functions associated data passed by the caller image data width of the raster image in pixels, or 0 height of the raster image in pixels, or 0 the image format as a tag Deprecated. set to 0.0 the extents of the glyph A virtual method for the #hb_paint_funcs_t to paint a glyph image. This method is called for glyphs with image blobs in the CBDT, sbix or SVG tables. The @format identifies the kind of data that is contained in @image. Possible values include #HB_PAINT_IMAGE_FORMAT_PNG, #HB_PAINT_IMAGE_FORMAT_SVG and #HB_PAINT_IMAGE_FORMAT_BGRA. The image dimensions and glyph extents are provided if available, and should be used to size and position the image. Whether the operation was successful. paint functions object The data accompanying the paint functions in hb_font_paint_glyph() the image data width of the raster image in pixels, or 0 height of the raster image in pixels, or 0 the image format as a tag Deprecated. Always set to 0.0. glyph extents for desired rendering User data pointer passed to hb_paint_funcs_set_image_func() Perform a "linear-gradient" paint operation. paint functions associated data passed by the caller Color information for the gradient X coordinate of the first point Y coordinate of the first point X coordinate of the second point Y coordinate of the second point X coordinate of the third point Y coordinate of the third point A virtual method for the #hb_paint_funcs_t to paint a linear gradient everywhere within the current clip. The @color_line object contains information about the colors of the gradients. It is only valid for the duration of the callback, you cannot keep it around. The coordinates of the points are interpreted according to the current transform. See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr) section for details on how the points define the direction of the gradient, and how to interpret the @color_line. paint functions object The data accompanying the paint functions in hb_font_paint_glyph() Color information for the gradient X coordinate of the first point Y coordinate of the first point X coordinate of the second point Y coordinate of the second point X coordinate of the third point Y coordinate of the third point User data pointer passed to hb_paint_funcs_set_linear_gradient_func() Perform a "pop-clip" paint operation. paint functions associated data passed by the caller A virtual method for the #hb_paint_funcs_t to undo the effect of a prior call to the #hb_paint_funcs_push_clip_glyph_func_t or #hb_paint_funcs_push_clip_rectangle_func_t vfuncs. paint functions object The data accompanying the paint functions in hb_font_paint_glyph() User data pointer passed to hb_paint_funcs_set_pop_clip_func() Perform a "pop-group" paint operation. paint functions associated data passed by the caller the compositing mode to use A virtual method for the #hb_paint_funcs_t to undo the effect of a prior call to the #hb_paint_funcs_push_group_func_t vfunc. This call stops the redirection to the intermediate surface, and then composites it on the previous surface, using the compositing mode passed to this call. paint functions object The data accompanying the paint functions in hb_font_paint_glyph() the compositing mode to use User data pointer passed to hb_paint_funcs_set_pop_group_func() Perform a "pop-transform" paint operation. paint functions associated data passed by the caller A virtual method for the #hb_paint_funcs_t to undo the effect of a prior call to the #hb_paint_funcs_push_transform_func_t vfunc. paint functions object The data accompanying the paint functions in hb_font_paint_glyph() User data pointer passed to hb_paint_funcs_set_pop_transform_func() Perform a "push-clip-glyph" paint operation. paint functions associated data passed by the caller the glyph ID the font A virtual method for the #hb_paint_funcs_t to clip subsequent paint calls to the outline of a glyph. The coordinates of the glyph outline are expected in the current @font scale (ie. the results of calling hb_font_draw_glyph() with @font). The outline is transformed by the current transform. This clip is applied in addition to the current clip, and remains in effect until a matching call to the #hb_paint_funcs_pop_clip_func_t vfunc. paint functions object The data accompanying the paint functions in hb_font_paint_glyph() the glyph ID the font User data pointer passed to hb_paint_funcs_set_push_clip_glyph_func() Perform a "push-clip-rect" paint operation. paint functions associated data passed by the caller min X for the rectangle min Y for the rectangle max X for the rectangle max Y for the rectangle A virtual method for the #hb_paint_funcs_t to clip subsequent paint calls to a rectangle. The coordinates of the rectangle are interpreted according to the current transform. This clip is applied in addition to the current clip, and remains in effect until a matching call to the #hb_paint_funcs_pop_clip_func_t vfunc. paint functions object The data accompanying the paint functions in hb_font_paint_glyph() min X for the rectangle min Y for the rectangle max X for the rectangle max Y for the rectangle User data pointer passed to hb_paint_funcs_set_push_clip_rectangle_func() Push the transform reflecting the font's scale and slant settings onto the paint functions. paint functions associated data passed by the caller a font Perform a "push-group" paint operation. paint functions associated data passed by the caller A virtual method for the #hb_paint_funcs_t to use an intermediate surface for subsequent paint calls. The drawing will be redirected to an intermediate surface until a matching call to the #hb_paint_funcs_pop_group_func_t vfunc. paint functions object The data accompanying the paint functions in hb_font_paint_glyph() User data pointer passed to hb_paint_funcs_set_push_group_func() Push the inverse of the transform reflecting the font's scale and slant settings onto the paint functions. paint functions associated data passed by the caller a font Perform a "push-transform" paint operation. paint functions associated data passed by the caller xx component of the transform matrix yx component of the transform matrix xy component of the transform matrix yy component of the transform matrix dx component of the transform matrix dy component of the transform matrix A virtual method for the #hb_paint_funcs_t to apply a transform to subsequent paint calls. This transform is applied after the current transform, and remains in effect until a matching call to the #hb_paint_funcs_pop_transform_func_t vfunc. paint functions object The data accompanying the paint functions in hb_font_paint_glyph() xx component of the transform matrix yx component of the transform matrix xy component of the transform matrix yy component of the transform matrix dx component of the transform matrix dy component of the transform matrix User data pointer passed to hb_paint_funcs_set_push_transform_func() Perform a "radial-gradient" paint operation. paint functions associated data passed by the caller Color information for the gradient X coordinate of the first circle's center Y coordinate of the first circle's center radius of the first circle X coordinate of the second circle's center Y coordinate of the second circle's center radius of the second circle A virtual method for the #hb_paint_funcs_t to paint a radial gradient everywhere within the current clip. The @color_line object contains information about the colors of the gradients. It is only valid for the duration of the callback, you cannot keep it around. The coordinates of the points are interpreted according to the current transform. See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr) section for details on how the points define the direction of the gradient, and how to interpret the @color_line. paint functions object The data accompanying the paint functions in hb_font_paint_glyph() Color information for the gradient X coordinate of the first circle's center Y coordinate of the first circle's center radius of the first circle X coordinate of the second circle's center Y coordinate of the second circle's center radius of the second circle User data pointer passed to hb_paint_funcs_set_radial_gradient_func() Perform a "sweep-gradient" paint operation. paint functions associated data passed by the caller Color information for the gradient X coordinate of the circle's center Y coordinate of the circle's center the start angle the end angle A virtual method for the #hb_paint_funcs_t to paint a sweep gradient everywhere within the current clip. The @color_line object contains information about the colors of the gradients. It is only valid for the duration of the callback, you cannot keep it around. The coordinates of the points are interpreted according to the current transform. See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr) section for details on how the points define the direction of the gradient, and how to interpret the @color_line. paint functions object The data accompanying the paint functions in hb_font_paint_glyph() Color information for the gradient X coordinate of the circle's center Y coordinate of the circle's center the start angle, in radians the end angle, in radians User data pointer passed to hb_paint_funcs_set_sweep_gradient_func() Reallocates the memory pointed to by @ptr to @size bytes, using the allocator set at compile-time. Typically just realloc(). A pointer to the reallocated memory. The pointer to the memory to reallocate. The new size of the memory. Callback function for hb_face_create_for_tables(). The @tag is the tag of the table to reference, and the special tag #HB_TAG_NONE is used to reference the blob of the face itself. If referencing the face blob is not possible, it is recommended to set hb_get_table_tags_func_t on the @face to allow hb_face_reference_blob() to create a face blob out of individual table blobs. A pointer to the @tag table within @face or `NULL` if the table is not found or cannot be referenced. an #hb_face_t to reference table for the tag of the table to reference User data pointer passed by the caller Converts an ISO 15924 script tag to a corresponding #hb_script_t. An #hb_script_t corresponding to the ISO 15924 tag. an #hb_tag_t representing an ISO 15924 tag. Converts a string @str representing an ISO 15924 script tag to a corresponding #hb_script_t. Shorthand for hb_tag_from_string() then hb_script_from_iso15924_tag(). An #hb_script_t corresponding to the ISO 15924 tag. a string representing an ISO 15924 tag. length of the @str, or -1 if it is `NULL`-terminated. Fetches the #hb_direction_t of a script when it is set horizontally. All right-to-left scripts will return #HB_DIRECTION_RTL. All left-to-right scripts will return #HB_DIRECTION_LTR. Scripts that can be written either right-to-left or left-to-right will return #HB_DIRECTION_INVALID. Unknown scripts will return #HB_DIRECTION_LTR. The horizontal #hb_direction_t of @script The #hb_script_t to query Data type for scripts. Each #hb_script_t's value is an #hb_tag_t corresponding to the four-letter values defined by [ISO 15924](https://unicode.org/iso15924/). See also the Script (sc) property of the Unicode Character Database. `Zyyy` `Zinh` `Zzzz` `Arab` `Armn` `Beng` `Cyrl` `Deva` `Geor` `Grek` `Gujr` `Guru` `Hang` `Hani` `Hebr` `Hira` `Knda` `Kana` `Laoo` `Latn` `Mlym` `Orya` `Taml` `Telu` `Thai` `Tibt` `Bopo` `Brai` `Cans` `Cher` `Ethi` `Khmr` `Mong` `Mymr` `Ogam` `Runr` `Sinh` `Syrc` `Thaa` `Yiii` `Dsrt` `Goth` `Ital` `Buhd` `Hano` `Tglg` `Tagb` `Cprt` `Limb` `Linb` `Osma` `Shaw` `Tale` `Ugar` `Bugi` `Copt` `Glag` `Khar` `Talu` `Xpeo` `Sylo` `Tfng` `Bali` `Xsux` `Nkoo` `Phag` `Phnx` `Cari` `Cham` `Kali` `Lepc` `Lyci` `Lydi` `Olck` `Rjng` `Saur` `Sund` `Vaii` `Avst` `Bamu` `Egyp` `Armi` `Phli` `Prti` `Java` `Kthi` `Lisu` `Mtei` `Sarb` `Orkh` `Samr` `Lana` `Tavt` `Batk` `Brah` `Mand` `Cakm` `Merc` `Mero` `Plrd` `Shrd` `Sora` `Takr` `Bass`, Since: 0.9.30 `Aghb`, Since: 0.9.30 `Dupl`, Since: 0.9.30 `Elba`, Since: 0.9.30 `Gran`, Since: 0.9.30 `Khoj`, Since: 0.9.30 `Sind`, Since: 0.9.30 `Lina`, Since: 0.9.30 `Mahj`, Since: 0.9.30 `Mani`, Since: 0.9.30 `Mend`, Since: 0.9.30 `Modi`, Since: 0.9.30 `Mroo`, Since: 0.9.30 `Nbat`, Since: 0.9.30 `Narb`, Since: 0.9.30 `Perm`, Since: 0.9.30 `Hmng`, Since: 0.9.30 `Palm`, Since: 0.9.30 `Pauc`, Since: 0.9.30 `Phlp`, Since: 0.9.30 `Sidd`, Since: 0.9.30 `Tirh`, Since: 0.9.30 `Wara`, Since: 0.9.30 `Ahom`, Since: 0.9.30 `Hluw`, Since: 0.9.30 `Hatr`, Since: 0.9.30 `Mult`, Since: 0.9.30 `Hung`, Since: 0.9.30 `Sgnw`, Since: 0.9.30 `Adlm`, Since: 1.3.0 `Bhks`, Since: 1.3.0 `Marc`, Since: 1.3.0 `Osge`, Since: 1.3.0 `Tang`, Since: 1.3.0 `Newa`, Since: 1.3.0 `Gonm`, Since: 1.6.0 `Nshu`, Since: 1.6.0 `Soyo`, Since: 1.6.0 `Zanb`, Since: 1.6.0 `Dogr`, Since: 1.8.0 `Gong`, Since: 1.8.0 `Rohg`, Since: 1.8.0 `Maka`, Since: 1.8.0 `Medf`, Since: 1.8.0 `Sogo`, Since: 1.8.0 `Sogd`, Since: 1.8.0 `Elym`, Since: 2.4.0 `Nand`, Since: 2.4.0 `Hmnp`, Since: 2.4.0 `Wcho`, Since: 2.4.0 `Chrs`, Since: 2.6.7 `Diak`, Since: 2.6.7 `Kits`, Since: 2.6.7 `Yezi`, Since: 2.6.7 `Cpmn`, Since: 3.0.0 `Ougr`, Since: 3.0.0 `Tnsa`, Since: 3.0.0 `Toto`, Since: 3.0.0 `Vith`, Since: 3.0.0 `Zmth`, Since: 3.4.0 `Kawi`, Since: 5.2.0 `Nagm`, Since: 5.2.0 `Gara`, Since: 10.0.0 `Gukh`, Since: 10.0.0 `Krai`, Since: 10.0.0 `Onao`, Since: 10.0.0 `Sunu`, Since: 10.0.0 `Todr`, Since: 10.0.0 `Tutg`, Since: 10.0.0 `Berf`, Since: 11.5.0 `Sidt`, Since: 11.5.0 `Tayo`, Since: 11.5.0 `Tols`, Since: 11.5.0 No script set Converts an #hb_script_t to a corresponding ISO 15924 script tag. An #hb_tag_t representing an ISO 15924 script tag. an #hb_script_t to convert. Checks the equality of two #hb_segment_properties_t's. `true` if all properties of @a equal those of @b, `false` otherwise. first #hb_segment_properties_t to compare. second #hb_segment_properties_t to compare. Creates a hash representing @p. A hash of @p. #hb_segment_properties_t to hash. Fills in missing fields of @p from @src in a considered manner. First, if @p does not have direction set, direction is copied from @src. Next, if @p and @src have the same direction (which can be unset), if @p does not have script set, script is copied from @src. Finally, if @p and @src have the same direction and script (which either can be unset), if @p does not have language set, language is copied from @src. #hb_segment_properties_t to fill in. #hb_segment_properties_t to fill in from. The structure that holds various text properties of an #hb_buffer_t. Can be set and retrieved using hb_buffer_set_segment_properties() and hb_buffer_get_segment_properties(), respectively. the #hb_direction_t of the buffer, see hb_buffer_set_direction(). the #hb_script_t of the buffer, see hb_buffer_set_script(). the #hb_language_t of the buffer, see hb_buffer_set_language(). Adds @codepoint to @set. A set The element to add to @set Adds all of the elements from @first to @last (inclusive) to @set. A set The first element to add to @set The final element to add to @set Adds @num_codepoints codepoints to a set at once. The codepoints array must be in increasing order, with size at least @num_codepoints. A set Array of codepoints to add Length of @sorted_codepoints Tests whether memory allocation for a set was successful. `true` if allocation succeeded, `false` otherwise A set Clears out the contents of a set. A set Allocate a copy of @set. Newly-allocated set. A set Creates a new, initially empty set. The new #hb_set_t Removes @codepoint from @set. A set Removes @codepoint from @set Removes all of the elements from @first to @last (inclusive) from @set. If @last is #HB_SET_VALUE_INVALID, then all values greater than or equal to @first are removed. A set The first element to remove from @set The final element to remove from @set Decreases the reference count on a set. When the reference count reaches zero, the set is destroyed, freeing all memory. A set Fetches the singleton empty #hb_set_t. The empty #hb_set_t Finds the largest element in the set. maximum of @set, or #HB_SET_VALUE_INVALID if @set is empty. A set Finds the smallest element in the set. minimum of @set, or #HB_SET_VALUE_INVALID if @set is empty. A set Returns the number of elements in the set. The population of @set A set Fetches the user data associated with the specified key, attached to the specified set. A pointer to the user data A set The user-data key to query Tests whether @codepoint belongs to @set. `true` if @codepoint is in @set, `false` otherwise A set The element to query Creates a hash representing @set. A hash of @set. A set Makes @set the intersection of @set and @other. A set Another set Inverts the contents of @set. A set Tests whether a set is empty (contains no elements). `true` if @set is empty a set. Tests whether @set and @other are equal (contain the same elements). `true` if the two sets are equal, `false` otherwise. A set Another set Returns whether the set is inverted. `true` if the set is inverted, `false` otherwise A set Tests whether @set is a subset of @larger_set. `true` if the @set is a subset of (or equal to) @larger_set, `false` otherwise. A set Another set Fetches the next element in @set that is greater than current value of @codepoint. Set @codepoint to #HB_SET_VALUE_INVALID to get started. `true` if there was a next value, `false` otherwise A set Input = Code point to query Output = Code point retrieved Finds the next element in @set that is greater than @codepoint. Writes out codepoints to @out, until either the set runs out of elements, or @size codepoints are written, whichever comes first. the number of values written. A set Outputting codepoints starting after this one. Use #HB_SET_VALUE_INVALID to get started. An array of codepoints to write to. The maximum number of codepoints to write out. Fetches the next consecutive range of elements in @set that are greater than current value of @last. Set @last to #HB_SET_VALUE_INVALID to get started. `true` if there was a next range, `false` otherwise A set The first code point in the range Input = The current last code point in the range Output = The last code point in the range Fetches the previous element in @set that is lower than current value of @codepoint. Set @codepoint to #HB_SET_VALUE_INVALID to get started. `true` if there was a previous value, `false` otherwise A set Input = Code point to query Output = Code point retrieved Fetches the previous consecutive range of elements in @set that are greater than current value of @last. Set @first to #HB_SET_VALUE_INVALID to get started. `true` if there was a previous range, `false` otherwise A set Input = The current first code point in the range Output = The first code point in the range The last code point in the range Increases the reference count on a set. The set A set Makes the contents of @set equal to the contents of @other. A set Another set Attaches a user-data key/data pair to the specified set. `true` if success, `false` otherwise A set The user-data key to set A pointer to the user data to set A callback to call when @data is not needed anymore Whether to replace an existing data with the same key Subtracts the contents of @other from @set. A set Another set Makes @set the symmetric difference of @set and @other. A set Another set Data type for holding a set of integers. #hb_set_t's are used to gather and contain glyph IDs, Unicode code points, and various other collections of discrete values. Makes @set the union of @set and @other. A set Another set Shapes @buffer using @font turning its Unicode characters content to positioned glyphs. If @features is not `NULL`, it will be used to control the features applied during shaping. If two @features have the same tag but overlapping ranges the value of the feature with the higher index takes precedence. an #hb_font_t to use for shaping an #hb_buffer_t to shape an array of user specified #hb_feature_t or `NULL` the length of @features array See hb_shape() for details. If @shaper_list is not `NULL`, the specified shapers will be used in the given order, otherwise the default shapers list will be used. false if all shapers failed, true otherwise an #hb_font_t to use for shaping an #hb_buffer_t to shape an array of user specified #hb_feature_t or `NULL` the length of @features array a `NULL`-terminated array of shapers to use or `NULL` Retrieves the list of shapers supported by HarfBuzz. a `NULL`-terminated array of supported shapers constant string. The returned array is owned by HarfBuzz and should not be modified or freed. Constructs a shaping plan for a combination of @face, @user_features, @props, and @shaper_list. The shaping plan #hb_face_t to use The #hb_segment_properties_t of the segment The list of user-selected features The number of user-selected features List of shapers to try The variable-font version of #hb_shape_plan_create. Constructs a shaping plan for a combination of @face, @user_features, @props, and @shaper_list, plus the variation-space coordinates @coords. The shaping plan #hb_face_t to use The #hb_segment_properties_t of the segment The list of user-selected features The number of user-selected features The list of variation-space coordinates The number of variation-space coordinates List of shapers to try Creates a cached shaping plan suitable for reuse, for a combination of @face, @user_features, @props, and @shaper_list. The shaping plan #hb_face_t to use The #hb_segment_properties_t of the segment The list of user-selected features The number of user-selected features List of shapers to try The variable-font version of #hb_shape_plan_create_cached. Creates a cached shaping plan suitable for reuse, for a combination of @face, @user_features, @props, and @shaper_list, plus the variation-space coordinates @coords. The shaping plan #hb_face_t to use The #hb_segment_properties_t of the segment The list of user-selected features The number of user-selected features The list of variation-space coordinates The number of variation-space coordinates List of shapers to try Decreases the reference count on the given shaping plan. When the reference count reaches zero, the shaping plan is destroyed, freeing all memory. A shaping plan Executes the given shaping plan on the specified buffer, using the given @font and @features. `true` if success, `false` otherwise. A shaping plan The #hb_font_t to use The #hb_buffer_t to work upon Features to enable The number of features to enable Fetches the singleton empty shaping plan. The empty shaping plan Fetches the shaper from a given shaping plan. The shaper A shaping plan Fetches the user data associated with the specified key, attached to the specified shaping plan. A pointer to the user data A shaping plan The user-data key to query Increases the reference count on the given shaping plan. @shape_plan A shaping plan Attaches a user-data key/data pair to the given shaping plan. `true` if success, `false` otherwise. A shaping plan The user-data key to set A pointer to the user data A callback to call when @data is not needed anymore Whether to replace an existing data with the same key Data type for holding a shaping plan. Shape plans contain information about how HarfBuzz will shape a particular text segment, based on the segment's properties and the capabilities in the font face in use. Shape plans can be queried about how shaping will perform, given a set of specific input parameters (script, language, direction, features, etc.). Searches variation axes of a #hb_font_t object for a specific axis first, if not set, first tries to get default style values in `STAT` table then tries to polyfill from different tables of the font. Corresponding axis or default value to a style tag. a #hb_font_t object. a style tag. Defined by [OpenType Design-Variation Axis Tag Registry](https://docs.microsoft.com/en-us/typography/opentype/spec/dvaraxisreg). Used to vary between non-italic and italic. A value of 0 can be interpreted as "Roman" (non-italic); a value of 1 can be interpreted as (fully) italic. Used to vary design to suit different text sizes. Non-zero. Values can be interpreted as text size, in points. Used to vary between upright and slanted text. Values must be greater than -90 and less than +90. Values can be interpreted as the angle, in counter-clockwise degrees, of oblique slant from whatever the designer considers to be upright for that font design. Typical right-leaning Italic fonts have a negative slant angle (typically around -12) same as @HB_STYLE_TAG_SLANT_ANGLE expression as ratio. Typical right-leaning Italic fonts have a positive slant ratio (typically around 0.2) Used to vary width of text from narrower to wider. Non-zero. Values can be interpreted as a percentage of whatever the font designer considers “normal width” for that font design. Used to vary stroke thicknesses or other design details to give variation from lighter to blacker. Values can be interpreted in direct comparison to values for usWeightClass in the OS/2 table, or the CSS font-weight property. Converts a string into an #hb_tag_t. Valid tags are four characters. Shorter input strings will be padded with spaces. Longer input strings will be truncated. The #hb_tag_t corresponding to @str String to convert Length of @str, or -1 if it is `NULL`-terminated Converts an #hb_tag_t to a string and returns it in @buf. Strings will be four characters long. #hb_tag_t to convert Converted string Retrieves the Canonical Combining Class (ccc) property of code point @unicode. The #hb_unicode_combining_class_t of @unicode The Unicode-functions structure The code point to query A virtual method for the #hb_unicode_funcs_t structure. This method should retrieve the Canonical Combining Class (ccc) property for a specified Unicode code point. The #hb_unicode_combining_class_t of @unicode A Unicode-functions structure The code point to query User data pointer passed by the caller Data type for the Canonical_Combining_Class (ccc) property from the Unicode Character Database. <note>Note: newer versions of Unicode may add new values. Client programs should be ready to handle any value in the 0..254 range being returned from hb_unicode_combining_class().</note> Spacing and enclosing marks; also many vowel and consonant signs, even if nonspacing Marks which overlay a base letter or symbol Diacritic nukta marks in Brahmi-derived scripts Hiragana/Katakana voicing marks Viramas [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Hebrew] [Arabic] [Arabic] [Arabic] [Arabic] [Arabic] [Arabic] [Arabic] [Arabic] [Arabic] [Syriac] [Telugu] [Telugu] [Thai] [Thai] [Lao] [Lao] [Tibetan] [Tibetan] [Tibetan] Since: 7.2.0 Marks attached at the bottom left Marks attached directly below Marks attached directly above Marks attached at the top right Distinct marks at the bottom left Distinct marks directly below Distinct marks at the bottom right Distinct marks to the left Distinct marks to the right Distinct marks at the top left Distinct marks directly above Distinct marks at the top right Distinct marks subtending two bases Distinct marks extending above two bases Greek iota subscript only Invalid combining class Fetches the composition of a sequence of two Unicode code points. Calls the composition function of the specified Unicode-functions structure @ufuncs. `true` if @a and @b composed, `false` otherwise The Unicode-functions structure The first Unicode code point to compose The second Unicode code point to compose The composition of @a, @b A virtual method for the #hb_unicode_funcs_t structure. This method should compose a sequence of two input Unicode code points by canonical equivalence, returning the composed code point in a #hb_codepoint_t output parameter (if successful). The method must return an #hb_bool_t indicating the success of the composition. `true` is @a,@b composed, `false` otherwise A Unicode-functions structure The first code point to compose The second code point to compose The composed code point user data pointer passed by the caller Fetches the decomposition of a Unicode code point. Calls the decomposition function of the specified Unicode-functions structure @ufuncs. `true` if @ab was decomposed, `false` otherwise The Unicode-functions structure Unicode code point to decompose The first code point of the decomposition of @ab The second code point of the decomposition of @ab Fetches the compatibility decomposition of a Unicode code point. Deprecated. length of @decomposed. The Unicode-functions structure Code point to decompose Compatibility decomposition of @u Fully decompose @u to its Unicode compatibility decomposition. The codepoints of the decomposition will be written to @decomposed. The complete length of the decomposition will be returned. If @u has no compatibility decomposition, zero should be returned. The Unicode standard guarantees that a buffer of length #HB_UNICODE_MAX_DECOMPOSITION_LEN codepoints will always be sufficient for any compatibility decomposition plus an terminating value of 0. Consequently, @decompose must be allocated by the caller to be at least this length. Implementations of this function type must ensure that they do not write past the provided array. number of codepoints in the full compatibility decomposition of @u, or 0 if no decomposition available. a Unicode function structure codepoint to decompose address of codepoint array (of length #HB_UNICODE_MAX_DECOMPOSITION_LEN) to write decomposition into user data pointer as passed to hb_unicode_funcs_set_decompose_compatibility_func() A virtual method for the #hb_unicode_funcs_t structure. This method should decompose an input Unicode code point, returning the two decomposed code points in #hb_codepoint_t output parameters (if successful). The method must return an #hb_bool_t indicating the success of the composition. `true` if @ab decomposed, `false` otherwise A Unicode-functions structure The code point to decompose The first decomposed code point The second decomposed code point user data pointer passed by the caller Don't use. Not used by HarfBuzz. a Unicode-function structure The code point to query A virtual method for the #hb_unicode_funcs_t structure. A Unicode-functions structure The code point to query User data pointer passed by the caller Creates a new #hb_unicode_funcs_t structure of Unicode functions. The Unicode-functions structure Parent Unicode-functions structure Decreases the reference count on a Unicode-functions structure. When the reference count reaches zero, the Unicode-functions structure is destroyed, freeing all memory. The Unicode-functions structure Fetches a pointer to the default Unicode-functions structure that is used when no functions are explicitly set on #hb_buffer_t. a pointer to the #hb_unicode_funcs_t Unicode-functions structure Fetches the singleton empty Unicode-functions structure. The empty Unicode-functions structure Fetches the parent of the Unicode-functions structure @ufuncs. The parent Unicode-functions structure The Unicode-functions structure Fetches the user-data associated with the specified key, attached to the specified Unicode-functions structure. A pointer to the user data The Unicode-functions structure The user-data key to query Tests whether the specified Unicode-functions structure is immutable. `true` if @ufuncs is immutable, `false` otherwise The Unicode-functions structure Makes the specified Unicode-functions structure immutable. The Unicode-functions structure Increases the reference count on a Unicode-functions structure. The Unicode-functions structure The Unicode-functions structure Sets the implementation function for #hb_unicode_combining_class_func_t. A Unicode-functions structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_unicode_compose_func_t. A Unicode-functions structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_unicode_decompose_compatibility_func_t. A Unicode-functions structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_unicode_decompose_func_t. A Unicode-functions structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_unicode_eastasian_width_func_t. a Unicode-function structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_unicode_general_category_func_t. A Unicode-functions structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_unicode_mirroring_func_t. A Unicode-functions structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Sets the implementation function for #hb_unicode_script_func_t. A Unicode-functions structure The callback function to assign Data to pass to @func The function to call when @user_data is not needed anymore Attaches a user-data key/data pair to the specified Unicode-functions structure. `true` if success, `false` otherwise The Unicode-functions structure The user-data key A pointer to the user data A callback to call when @data is not needed anymore Whether to replace an existing data with the same key Data type containing a set of virtual methods used for accessing various Unicode character properties. HarfBuzz provides a default function for each of the methods in #hb_unicode_funcs_t. Client programs can implement their own replacements for the individual Unicode functions, as needed, and replace the default by calling the setter for a method. Retrieves the General Category (gc) property of code point @unicode. The #hb_unicode_general_category_t of @unicode The Unicode-functions structure The code point to query A virtual method for the #hb_unicode_funcs_t structure. This method should retrieve the General Category property for a specified Unicode code point. The #hb_unicode_general_category_t of @unicode A Unicode-functions structure The code point to query User data pointer passed by the caller Data type for the "General_Category" (gc) property from the Unicode Character Database. [Cc] [Cf] [Cn] [Co] [Cs] [Ll] [Lm] [Lo] [Lt] [Lu] [Mc] [Me] [Mn] [Nd] [Nl] [No] [Pc] [Pd] [Pe] [Pf] [Pi] [Po] [Ps] [Sc] [Sk] [Sm] [So] [Zl] [Zp] [Zs] Retrieves the Bi-directional Mirroring Glyph code point defined for code point @unicode. The #hb_codepoint_t of the Mirroring Glyph for @unicode The Unicode-functions structure The code point to query A virtual method for the #hb_unicode_funcs_t structure. This method should retrieve the Bi-Directional Mirroring Glyph code point for a specified Unicode code point. <note>Note: If a code point does not have a specified Bi-Directional Mirroring Glyph defined, the method should return the original code point.</note> The #hb_codepoint_t of the Mirroring Glyph for @unicode A Unicode-functions structure The code point to query User data pointer passed by the caller Retrieves the #hb_script_t script to which code point @unicode belongs. The #hb_script_t of @unicode The Unicode-functions structure The code point to query A virtual method for the #hb_unicode_funcs_t structure. This method should retrieve the Script property for a specified Unicode code point. The #hb_script_t of @unicode A Unicode-functions structure The code point to query User data pointer passed by the caller Data structure for holding user-data keys. Parses a string into a #hb_variation_t. The format for specifying variation settings follows. All valid CSS font-variation-settings values other than 'normal' and 'inherited' are also accepted, though, not documented below. The format is a tag, optionally followed by an equals sign, followed by a number. For example `wght=500`, or `slnt=-7.5`. `true` if @str is successfully parsed, `false` otherwise a string to parse length of @str, or -1 if string is `NULL` terminated the #hb_variation_t to initialize with the parsed values Data type for holding variation data. Registered OpenType variation-axis tags are listed in [OpenType Axis Tag Registry](https://docs.microsoft.com/en-us/typography/opentype/spec/dvaraxisreg). The #hb_tag_t tag of the variation-axis name The value of the variation axis Converts an #hb_variation_t into a `NULL`-terminated string in the format understood by hb_variation_from_string(). The client in responsible for allocating big enough size for @buf, 128 bytes is more than enough. Note that the string won't include any whitespace. an #hb_variation_t to convert output string the allocated size of @buf Converts an #hb_variation_t into a `NULL`-terminated string in the format understood by hb_variation_from_string(). The client in responsible for allocating big enough size for @buf, 128 bytes is more than enough. Note that the string won't include any whitespace. an #hb_variation_t to convert output string the allocated size of @buf soup3-0.9.0/gir-files/Pango-1.0.gir000064400000000000000000026642141046102023000146460ustar 00000000000000 A `PangoGlyph` represents a single glyph in the output form of a string. The `PangoGlyphUnit` type is used to store dimensions within Pango. Dimensions are stored in 1/PANGO_SCALE of a device unit. (A device unit might be a pixel for screen display, or a point on a printer.) PANGO_SCALE is currently 1024, and may change in the future (unlikely though), but you should not depend on its exact value. The PANGO_PIXELS() macro can be used to convert from glyph units into device units with correct rounding. A `PangoLayoutRun` represents a single run within a `PangoLayoutLine`. It is simply an alternate name for [struct@Pango.GlyphItem]. See the [struct@Pango.GlyphItem] docs for details on the fields. Whether the segment should be shifted to center around the baseline. This is mainly used in vertical writing directions. Whether this run holds ellipsized text. Whether to add a hyphen at the end of the run during shaping. Extracts the *ascent* from a `PangoRectangle` representing glyph extents. The ascent is the distance from the baseline to the highest point of the character. This is positive if the glyph ascends above the baseline. a `PangoRectangle` Value for @start_index in `PangoAttribute` that indicates the beginning of the text. Value for @end_index in `PangoAttribute` that indicates the end of the text. `PangoAlignment` describes how to align the lines of a `PangoLayout` within the available space. If the `PangoLayout` is set to justify using [method@Pango.Layout.set_justify], this only affects partial lines. See [method@Pango.Layout.set_auto_dir] for how text direction affects the interpretation of `PangoAlignment` values. Put all available space on the right Center the line within the available space Put all available space on the left The `PangoAnalysis` structure stores information about the properties of a segment of text. unused, reserved unused, reserved the font for this segment. the bidirectional level for this segment. the glyph orientation for this segment (A `PangoGravity`). boolean flags for this segment (Since: 1.16). the detected script for this segment (A `PangoScript`) (Since: 1.18). the detected language for this segment. extra attributes for this segment. The `PangoAttrClass` structure stores the type and operations for a particular type of attribute. The functions in this structure should not be called directly. Instead, one should use the wrapper functions provided for `PangoAttribute`. the type ID for this attribute function to duplicate an attribute of this type (see [method@Pango.Attribute.copy]) function to free an attribute of this type (see [method@Pango.Attribute.destroy]) function to check two attributes of this type for equality (see [method@Pango.Attribute.equal]) The `PangoAttrColor` structure is used to represent attributes that are colors. the common portion of the attribute the `PangoColor` which is the value of the attribute Type of a function that can duplicate user data for an attribute. new copy of @user_data. user data to copy Type of a function filtering a list of attributes. %TRUE if the attribute should be selected for filtering, %FALSE otherwise. a Pango attribute user data passed to the function The `PangoAttrFloat` structure is used to represent attributes with a float or double value. the common portion of the attribute the value of the attribute The `PangoAttrFontDesc` structure is used to store an attribute that sets all aspects of the font description at once. the common portion of the attribute the font description which is the value of this attribute Create a new font description attribute. This attribute allows setting family, style, weight, variant, stretch, and size simultaneously. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the font description The `PangoAttrFontFeatures` structure is used to represent OpenType font features as an attribute. the common portion of the attribute the features, as a string in CSS syntax Create a new font features tag attribute. You can use this attribute to select OpenType font features like small-caps, alternative glyphs, ligatures, etc. for fonts that support them. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] a string with OpenType font features, with the syntax of the [CSS font-feature-settings property](https://www.w3.org/TR/css-fonts-4/#font-rend-desc) The `PangoAttrInt` structure is used to represent attributes with an integer or enumeration value. the common portion of the attribute the value of the attribute A `PangoAttrIterator` is used to iterate through a `PangoAttrList`. A new iterator is created with [method@Pango.AttrList.get_iterator]. Once the iterator is created, it can be advanced through the style changes in the text using [method@Pango.AttrIterator.next]. At each style change, the range of the current style segment and the attributes currently in effect can be queried. Copy a `PangoAttrIterator`. the newly allocated `PangoAttrIterator`, which should be freed with [method@Pango.AttrIterator.destroy] a `PangoAttrIterator` Destroy a `PangoAttrIterator` and free all associated memory. a `PangoAttrIterator` Find the current attribute of a particular type at the iterator location. When multiple attributes of the same type overlap, the attribute whose range starts closest to the current location is used. the current attribute of the given type, or %NULL if no attribute of that type applies to the current location. a `PangoAttrIterator` the type of attribute to find Gets a list of all attributes at the current position of the iterator. a list of all attributes for the current range. To free this value, call [method@Pango.Attribute.destroy] on each value and g_slist_free() on the list. a `PangoAttrIterator` Get the font and other attributes at the current iterator position. a `PangoAttrIterator` a `PangoFontDescription` to fill in with the current values. The family name in this structure will be set using [method@Pango.FontDescription.set_family_static] using values from an attribute in the `PangoAttrList` associated with the iterator, so if you plan to keep it around, you must call: `pango_font_description_set_family (desc, pango_font_description_get_family (desc))`. location to store language tag for item, or %NULL if none is found. location in which to store a list of non-font attributes at the the current position; only the highest priority value of each attribute will be added to this list. In order to free this value, you must call [method@Pango.Attribute.destroy] on each member. Advance the iterator until the next change of style. %FALSE if the iterator is at the end of the list, otherwise %TRUE a `PangoAttrIterator` Get the range of the current segment. Note that the stored return values are signed, not unsigned like the values in `PangoAttribute`. To deal with this API oversight, stored return values that wouldn't fit into a signed integer are clamped to %G_MAXINT. a PangoAttrIterator location to store the start of the range location to store the end of the range The `PangoAttrLanguage` structure is used to represent attributes that are languages. the common portion of the attribute the `PangoLanguage` which is the value of the attribute Create a new language tag attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] language tag A `PangoAttrList` represents a list of attributes that apply to a section of text. The attributes in a `PangoAttrList` are, in general, allowed to overlap in an arbitrary fashion. However, if the attributes are manipulated only through [method@Pango.AttrList.change], the overlap between properties will meet stricter criteria. Since the `PangoAttrList` structure is stored as a linear list, it is not suitable for storing attributes for large amounts of text. In general, you should not use a single `PangoAttrList` for more than one paragraph of text. Create a new empty attribute list with a reference count of one. the newly allocated `PangoAttrList`, which should be freed with [method@Pango.AttrList.unref] Insert the given attribute into the `PangoAttrList`. It will replace any attributes of the same type on that segment and be merged with any adjoining attributes that are identical. This function is slower than [method@Pango.AttrList.insert] for creating an attribute list in order (potentially much slower for large lists). However, [method@Pango.AttrList.insert] is not suitable for continually changing a set of attributes since it never removes or combines existing attributes. a `PangoAttrList` the attribute to insert Copy @list and return an identical new list. the newly allocated `PangoAttrList`, with a reference count of one, which should be freed with [method@Pango.AttrList.unref]. Returns %NULL if @list was %NULL. a `PangoAttrList` Checks whether @list and @other_list contain the same attributes and whether those attributes apply to the same ranges. Beware that this will return wrong values if any list contains duplicates. %TRUE if the lists are equal, %FALSE if they aren't a `PangoAttrList` the other `PangoAttrList` Given a `PangoAttrList` and callback function, removes any elements of @list for which @func returns %TRUE and inserts them into a new list. the new `PangoAttrList` or %NULL if no attributes of the given types were found a `PangoAttrList` callback function; returns %TRUE if an attribute should be filtered out Data to be passed to @func Gets a list of all attributes in @list. a list of all attributes in @list. To free this value, call [method@Pango.Attribute.destroy] on each value and g_slist_free() on the list. a `PangoAttrList` Create a iterator initialized to the beginning of the list. @list must not be modified until this iterator is freed. the newly allocated `PangoAttrIterator`, which should be freed with [method@Pango.AttrIterator.destroy] a `PangoAttrList` Insert the given attribute into the `PangoAttrList`. It will be inserted after all other attributes with a matching @start_index. a `PangoAttrList` the attribute to insert Insert the given attribute into the `PangoAttrList`. It will be inserted before all other attributes with a matching @start_index. a `PangoAttrList` the attribute to insert Increase the reference count of the given attribute list by one. The attribute list passed in a `PangoAttrList` This function opens up a hole in @list, fills it in with attributes from the left, and then merges @other on top of the hole. This operation is equivalent to stretching every attribute that applies at position @pos in @list by an amount @len, and then calling [method@Pango.AttrList.change] with a copy of each attribute in @other in sequence (offset in position by @pos, and limited in length to @len). This operation proves useful for, for instance, inserting a pre-edit string in the middle of an edit buffer. For backwards compatibility, the function behaves differently when @len is 0. In this case, the attributes from @other are not imited to @len, and are just overlayed on top of @list. This mode is useful for merging two lists of attributes together. a `PangoAttrList` another `PangoAttrList` the position in @list at which to insert @other the length of the spliced segment. (Note that this must be specified since the attributes in @other may only be present at some subsection of this range) Serializes a `PangoAttrList` to a string. In the resulting string, serialized attributes are separated by newlines or commas. Individual attributes are serialized to a string of the form [START END] TYPE VALUE Where START and END are the indices (with -1 being accepted in place of MAXUINT), TYPE is the nickname of the attribute value type, e.g. _weight_ or _stretch_, and the value is serialized according to its type: Optionally, START and END can be omitted to indicate unlimited extent. - enum values as nick or numeric value - boolean values as _true_ or _false_ - integers and floats as numbers - strings as string, optionally quoted - font features as quoted string - PangoLanguage as string - PangoFontDescription as serialized by [method@Pango.FontDescription.to_string], quoted - PangoColor as serialized by [method@Pango.Color.to_string] Examples: 0 10 foreground red, 5 15 weight bold, 0 200 font-desc "Sans 10" 0 -1 weight 700 0 100 family Times weight bold To parse the returned value, use [func@Pango.AttrList.from_string]. Note that shape attributes can not be serialized. a newly allocated string a `PangoAttrList` Decrease the reference count of the given attribute list by one. If the result is zero, free the attribute list and the attributes it contains. a `PangoAttrList` Update indices of attributes in @list for a change in the text they refer to. The change that this function applies is removing @remove bytes at position @pos and inserting @add bytes instead. Attributes that fall entirely in the (@pos, @pos + @remove) range are removed. Attributes that start or end inside the (@pos, @pos + @remove) range are shortened to reflect the removal. Attributes start and end positions are updated if they are behind @pos + @remove. a `PangoAttrList` the position of the change the number of removed bytes the number of added bytes Deserializes a `PangoAttrList` from a string. This is the counterpart to [method@Pango.AttrList.to_string]. See that functions for details about the format. a new `PangoAttrList` a string The `PangoAttrShape` structure is used to represent attributes which impose shape restrictions. the common portion of the attribute the ink rectangle to restrict to the logical rectangle to restrict to user data set (see [func@Pango.AttrShape.new_with_data]) copy function for the user data destroy function for the user data Create a new shape attribute. A shape is used to impose a particular ink and logical rectangle on the result of shaping a particular glyph. This might be used, for instance, for embedding a picture or a widget inside a `PangoLayout`. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] ink rectangle to assign to each character logical rectangle to assign to each character Creates a new shape attribute. Like [func@Pango.AttrShape.new], but a user data pointer is also provided; this pointer can be accessed when later rendering the glyph. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] ink rectangle to assign to each character logical rectangle to assign to each character user data pointer function to copy @data when the attribute is copied. If %NULL, @data is simply copied as a pointer function to free @data when the attribute is freed The `PangoAttrSize` structure is used to represent attributes which set font size. the common portion of the attribute size of font, in units of 1/%PANGO_SCALE of a point (for %PANGO_ATTR_SIZE) or of a device unit (for %PANGO_ATTR_ABSOLUTE_SIZE) whether the font size is in device units or points. This field is only present for compatibility with Pango-1.8.0 (%PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE. Create a new font-size attribute in fractional points. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the font size, in %PANGO_SCALE-ths of a point Create a new font-size attribute in device units. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the font size, in %PANGO_SCALE-ths of a device unit The `PangoAttrString` structure is used to represent attributes with a string value. the common portion of the attribute the string which is the value of the attribute The `PangoAttrType` distinguishes between different types of attributes. Along with the predefined values, it is possible to allocate additional values for custom attributes using [func@AttrType.register]. The predefined values are given below. The type of structure used to store the attribute is listed in parentheses after the description. does not happen language ([struct@Pango.AttrLanguage]) font family name list ([struct@Pango.AttrString]) font slant style ([struct@Pango.AttrInt]) font weight ([struct@Pango.AttrInt]) font variant (normal or small caps) ([struct@Pango.AttrInt]) font stretch ([struct@Pango.AttrInt]) font size in points scaled by %PANGO_SCALE ([struct@Pango.AttrInt]) font description ([struct@Pango.AttrFontDesc]) foreground color ([struct@Pango.AttrColor]) background color ([struct@Pango.AttrColor]) whether the text has an underline ([struct@Pango.AttrInt]) whether the text is struck-through ([struct@Pango.AttrInt]) baseline displacement ([struct@Pango.AttrInt]) shape ([struct@Pango.AttrShape]) font size scale factor ([struct@Pango.AttrFloat]) whether fallback is enabled ([struct@Pango.AttrInt]) letter spacing ([struct@PangoAttrInt]) underline color ([struct@Pango.AttrColor]) strikethrough color ([struct@Pango.AttrColor]) font size in pixels scaled by %PANGO_SCALE ([struct@Pango.AttrInt]) base text gravity ([struct@Pango.AttrInt]) gravity hint ([struct@Pango.AttrInt]) OpenType font features ([struct@Pango.AttrFontFeatures]). Since 1.38 foreground alpha ([struct@Pango.AttrInt]). Since 1.38 background alpha ([struct@Pango.AttrInt]). Since 1.38 whether breaks are allowed ([struct@Pango.AttrInt]). Since 1.44 how to render invisible characters ([struct@Pango.AttrInt]). Since 1.44 whether to insert hyphens at intra-word line breaks ([struct@Pango.AttrInt]). Since 1.44 whether the text has an overline ([struct@Pango.AttrInt]). Since 1.46 overline color ([struct@Pango.AttrColor]). Since 1.46 line height factor ([struct@Pango.AttrFloat]). Since: 1.50 line height ([struct@Pango.AttrInt]). Since: 1.50 override segmentation to classify the range of the attribute as a single word ([struct@Pango.AttrInt]). Since 1.50 override segmentation to classify the range of the attribute as a single sentence ([struct@Pango.AttrInt]). Since 1.50 baseline displacement ([struct@Pango.AttrInt]). Since 1.50 font-relative size change ([struct@Pango.AttrInt]). Since 1.50 Fetches the attribute type name. The attribute type name is the string passed in when registering the type using [func@Pango.AttrType.register]. The returned value is an interned string (see g_intern_string() for what that means) that should not be modified or freed. the type ID name (which may be %NULL), or %NULL if @type is a built-in Pango attribute type or invalid. an attribute type ID to fetch the name for Allocate a new attribute type ID. The attribute type name can be accessed later by using [func@Pango.AttrType.get_name]. the new type ID. an identifier for the type The `PangoAttribute` structure represents the common portions of all attributes. Particular types of attributes include this structure as their initial portion. The common portion of the attribute holds the range to which the value in the type-specific part of the attribute applies and should be initialized using [method@Pango.Attribute.init]. By default, an attribute will have an all-inclusive range of [0,%G_MAXUINT]. the class structure holding information about the type of the attribute the start index of the range (in bytes). end index of the range (in bytes). The character at this index is not included in the range. Returns the attribute cast to `PangoAttrColor`. This is mainly useful for language bindings. The attribute as `PangoAttrColor`, or %NULL if it's not a color attribute A `PangoAttribute` such as foreground Returns the attribute cast to `PangoAttrFloat`. This is mainly useful for language bindings. The attribute as `PangoAttrFloat`, or %NULL if it's not a floating point attribute A `PangoAttribute` such as scale Returns the attribute cast to `PangoAttrFontDesc`. This is mainly useful for language bindings. The attribute as `PangoAttrFontDesc`, or %NULL if it's not a font description attribute A `PangoAttribute` representing a font description Returns the attribute cast to `PangoAttrFontFeatures`. This is mainly useful for language bindings. The attribute as `PangoAttrFontFeatures`, or %NULL if it's not a font features attribute A `PangoAttribute` representing font features Returns the attribute cast to `PangoAttrInt`. This is mainly useful for language bindings. The attribute as `PangoAttrInt`, or %NULL if it's not an integer attribute A `PangoAttribute` such as weight Returns the attribute cast to `PangoAttrLanguage`. This is mainly useful for language bindings. The attribute as `PangoAttrLanguage`, or %NULL if it's not a language attribute A `PangoAttribute` representing a language Returns the attribute cast to `PangoAttrShape`. This is mainly useful for language bindings. The attribute as `PangoAttrShape`, or %NULL if it's not a shape attribute A `PangoAttribute` representing a shape Returns the attribute cast to `PangoAttrSize`. This is mainly useful for language bindings. The attribute as `PangoAttrSize`, or NULL if it's not a size attribute A `PangoAttribute` representing a size Returns the attribute cast to `PangoAttrString`. This is mainly useful for language bindings. The attribute as `PangoAttrString`, or %NULL if it's not a string attribute A `PangoAttribute` such as family Make a copy of an attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy]. a `PangoAttribute` Destroy a `PangoAttribute` and free all associated memory. a `PangoAttribute`. Compare two attributes for equality. This compares only the actual value of the two attributes and not the ranges that the attributes apply to. %TRUE if the two attributes have the same value a `PangoAttribute` another `PangoAttribute` Initializes @attr's klass to @klass, it's start_index to %PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING and end_index to %PANGO_ATTR_INDEX_TO_TEXT_END such that the attribute applies to the entire text by default. a `PangoAttribute` a `PangoAttrClass` An enumeration that affects baseline shifts between runs. Leave the baseline unchanged Shift the baseline to the superscript position, relative to the previous run Shift the baseline to the subscript position, relative to the previous run `PangoBidiType` represents the bidirectional character type of a Unicode character. The values in this enumeration are specified by the [Unicode bidirectional algorithm](http://www.unicode.org/reports/tr9/). Use fribidi for this information Left-to-Right Left-to-Right Embedding Left-to-Right Override Right-to-Left Right-to-Left Arabic Right-to-Left Embedding Right-to-Left Override Pop Directional Format European Number European Number Separator European Number Terminator Arabic Number Common Number Separator Nonspacing Mark Boundary Neutral Paragraph Separator Segment Separator Whitespace Other Neutrals Left-to-Right isolate. Since 1.48.6 Right-to-Left isolate. Since 1.48.6 First strong isolate. Since 1.48.6 Pop directional isolate. Since 1.48.6 Determines the bidirectional type of a character. The bidirectional type is specified in the Unicode Character Database. A simplified version of this function is available as [func@unichar_direction]. the bidirectional character type, as used in the Unicode bidirectional algorithm. a Unicode character The `PangoColor` structure is used to represent a color in an uncalibrated RGB color-space. value of red component value of green component value of blue component Creates a copy of @src. The copy should be freed with [method@Pango.Color.free]. Primarily used by language bindings, not that useful otherwise (since colors can just be copied by assignment in C). the newly allocated `PangoColor`, which should be freed with [method@Pango.Color.free] color to copy Frees a color allocated by [method@Pango.Color.copy]. an allocated `PangoColor` Fill in the fields of a color from a string specification. The string can either one of a large set of standard names. (Taken from the CSS Color [specification](https://www.w3.org/TR/css-color-4/#named-colors), or it can be a value in the form `#rgb`, `#rrggbb`, `#rrrgggbbb` or `#rrrrggggbbbb`, where `r`, `g` and `b` are hex digits of the red, green, and blue components of the color, respectively. (White in the four forms is `#fff`, `#ffffff`, `#fffffffff` and `#ffffffffffff`.) %TRUE if parsing of the specifier succeeded, otherwise %FALSE a `PangoColor` structure in which to store the result a string specifying the new color Fill in the fields of a color from a string specification. The string can either one of a large set of standard names. (Taken from the CSS Color [specification](https://www.w3.org/TR/css-color-4/#named-colors), or it can be a hexadecimal value in the form `#rgb`, `#rrggbb`, `#rrrgggbbb` or `#rrrrggggbbbb` where `r`, `g` and `b` are hex digits of the red, green, and blue components of the color, respectively. (White in the four forms is `#fff`, `#ffffff`, `#fffffffff` and `#ffffffffffff`.) Additionally, parse strings of the form `#rgba`, `#rrggbbaa`, `#rrrrggggbbbbaaaa`, if @alpha is not %NULL, and set @alpha to the value specified by the hex digits for `a`. If no alpha component is found in @spec, @alpha is set to 0xffff (for a solid color). %TRUE if parsing of the specifier succeeded, otherwise %FALSE a `PangoColor` structure in which to store the result return location for alpha a string specifying the new color Returns a textual specification of @color. The string is in the hexadecimal form `#rrrrggggbbbb`, where `r`, `g` and `b` are hex digits representing the red, green, and blue components respectively. a newly-allocated text string that must be freed with g_free(). a `PangoColor` A `PangoContext` stores global information used to control the itemization process. The information stored by `PangoContext` includes the fontmap used to look up fonts, and default values such as the default language, default gravity, or default font. To obtain a `PangoContext`, use [method@Pango.FontMap.create_context]. Creates a new `PangoContext` initialized to default values. This function is not particularly useful as it should always be followed by a [method@Pango.Context.set_font_map] call, and the function [method@Pango.FontMap.create_context] does these two steps together and hence users are recommended to use that. If you are using Pango as part of a higher-level system, that system may have it's own way of create a `PangoContext`. For instance, the GTK toolkit has, among others, `gtk_widget_get_pango_context()`. Use those instead. the newly allocated `PangoContext`, which should be freed with g_object_unref(). Forces a change in the context, which will cause any `PangoLayout` using this context to re-layout. This function is only useful when implementing a new backend for Pango, something applications won't do. Backends should call this function if they have attached extra data to the context and such data is changed. a `PangoContext` Retrieves the base direction for the context. See [method@Pango.Context.set_base_dir]. the base direction for the context. a `PangoContext` Retrieves the base gravity for the context. See [method@Pango.Context.set_base_gravity]. the base gravity for the context. a `PangoContext` Retrieve the default font description for the context. a pointer to the context's default font description. This value must not be modified or freed. a `PangoContext` Gets the `PangoFontMap` used to look up fonts for this context. the font map for the. `PangoContext` This value is owned by Pango and should not be unreferenced. a `PangoContext` Retrieves the gravity for the context. This is similar to [method@Pango.Context.get_base_gravity], except for when the base gravity is %PANGO_GRAVITY_AUTO for which [func@Pango.Gravity.get_for_matrix] is used to return the gravity from the current context matrix. the resolved gravity for the context. a `PangoContext` Retrieves the gravity hint for the context. See [method@Pango.Context.set_gravity_hint] for details. the gravity hint for the context. a `PangoContext` Retrieves the global language tag for the context. the global language tag. a `PangoContext` Gets the transformation matrix that will be applied when rendering with this context. See [method@Pango.Context.set_matrix]. the matrix, or %NULL if no matrix has been set (which is the same as the identity matrix). The returned matrix is owned by Pango and must not be modified or freed. a `PangoContext` Get overall metric information for a particular font description. Since the metrics may be substantially different for different scripts, a language tag can be provided to indicate that the metrics should be retrieved that correspond to the script(s) used by that language. The `PangoFontDescription` is interpreted in the same way as by [func@itemize], and the family name may be a comma separated list of names. If characters from multiple of these families would be used to render the string, then the returned fonts would be a composite of the metrics for the fonts loaded for the individual families. a `PangoFontMetrics` object. The caller must call [method@Pango.FontMetrics.unref] when finished using the object. a `PangoContext` a `PangoFontDescription` structure. %NULL means that the font description from the context will be used. language tag used to determine which script to get the metrics for. %NULL means that the language tag from the context will be used. If no language tag is set on the context, metrics for the default language (as determined by [func@Pango.Language.get_default] will be returned. Returns whether font rendering with this context should round glyph positions and widths. a `PangoContext` Returns the current serial number of @context. The serial number is initialized to an small number larger than zero when a new context is created and is increased whenever the context is changed using any of the setter functions, or the `PangoFontMap` it uses to find fonts has changed. The serial may wrap, but will never have the value 0. Since it can wrap, never compare it with "less than", always use "not equals". This can be used to automatically detect changes to a `PangoContext`, and is only useful when implementing objects that need update when their `PangoContext` changes, like `PangoLayout`. The current serial number of @context. a `PangoContext` List all families for a context. a `PangoContext` location to store a pointer to an array of `PangoFontFamily`. This array should be freed with g_free(). location to store the number of elements in @descs Loads the font in one of the fontmaps in the context that is the closest match for @desc. the newly allocated `PangoFont` that was loaded, or %NULL if no font matched. a `PangoContext` a `PangoFontDescription` describing the font to load Load a set of fonts in the context that can be used to render a font matching @desc. the newly allocated `PangoFontset` loaded, or %NULL if no font matched. a `PangoContext` a `PangoFontDescription` describing the fonts to load a `PangoLanguage` the fonts will be used for Sets the base direction for the context. The base direction is used in applying the Unicode bidirectional algorithm; if the @direction is %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL, then the value will be used as the paragraph direction in the Unicode bidirectional algorithm. A value of %PANGO_DIRECTION_WEAK_LTR or %PANGO_DIRECTION_WEAK_RTL is used only for paragraphs that do not contain any strong characters themselves. a `PangoContext` the new base direction Sets the base gravity for the context. The base gravity is used in laying vertical text out. a `PangoContext` the new base gravity Set the default font description for the context a `PangoContext` the new pango font description Sets the font map to be searched when fonts are looked-up in this context. This is only for internal use by Pango backends, a `PangoContext` obtained via one of the recommended methods should already have a suitable font map. a `PangoContext` the `PangoFontMap` to set. Sets the gravity hint for the context. The gravity hint is used in laying vertical text out, and is only relevant if gravity of the context as returned by [method@Pango.Context.get_gravity] is set to %PANGO_GRAVITY_EAST or %PANGO_GRAVITY_WEST. a `PangoContext` the new gravity hint Sets the global language tag for the context. The default language for the locale of the running process can be found using [func@Pango.Language.get_default]. a `PangoContext` the new language tag. Sets the transformation matrix that will be applied when rendering with this context. Note that reported metrics are in the user space coordinates before the application of the matrix, not device-space coordinates after the application of the matrix. So, they don't scale with the matrix, though they may change slightly for different matrices, depending on how the text is fit to the pixel grid. a `PangoContext` a `PangoMatrix`, or %NULL to unset any existing matrix. (No matrix set is the same as setting the identity matrix.) Sets whether font rendering with this context should round glyph positions and widths to integral positions, in device units. This is useful when the renderer can't handle subpixel positioning of glyphs. The default value is to round glyph positions, to remain compatible with previous Pango behavior. a `PangoContext` whether to round glyph positions A `PangoCoverage` structure is a map from Unicode characters to [enum@Pango.CoverageLevel] values. It is often necessary in Pango to determine if a particular font can represent a particular character, and also how well it can represent that character. The `PangoCoverage` is a data structure that is used to represent that information. It is an opaque structure with no public fields. Create a new `PangoCoverage` the newly allocated `PangoCoverage`, initialized to %PANGO_COVERAGE_NONE with a reference count of one, which should be freed with [method@Pango.Coverage.unref]. Convert data generated from [method@Pango.Coverage.to_bytes] back to a `PangoCoverage`. This returns %NULL a newly allocated `PangoCoverage` binary data representing a `PangoCoverage` the size of @bytes in bytes Copy an existing `PangoCoverage`. the newly allocated `PangoCoverage`, with a reference count of one, which should be freed with [method@Pango.Coverage.unref]. a `PangoCoverage` Determine whether a particular index is covered by @coverage. the coverage level of @coverage for character @index_. a `PangoCoverage` the index to check Set the coverage for each index in @coverage to be the max (better) value of the current coverage for the index and the coverage for the corresponding index in @other. This function does nothing a `PangoCoverage` another `PangoCoverage` Increase the reference count on the `PangoCoverage` by one. Use g_object_ref instead @coverage a `PangoCoverage` Modify a particular index within @coverage a `PangoCoverage` the index to modify the new level for @index_ Convert a `PangoCoverage` structure into a flat binary format. This returns %NULL a `PangoCoverage` location to store result (must be freed with g_free()) location to store size of result Decrease the reference count on the `PangoCoverage` by one. If the result is zero, free the coverage and all associated memory. Use g_object_unref instead a `PangoCoverage` `PangoCoverageLevel` is used to indicate how well a font can represent a particular Unicode character for a particular script. Since 1.44, only %PANGO_COVERAGE_NONE and %PANGO_COVERAGE_EXACT will be returned. The character is not representable with the font. The character is represented in a way that may be comprehensible but is not the correct graphical form. For instance, a Hangul character represented as a a sequence of Jamos, or a Latin transliteration of a Cyrillic word. The character is represented as basically the correct graphical form, but with a stylistic variant inappropriate for the current script. The character is represented as the correct graphical form. Extracts the *descent* from a `PangoRectangle` representing glyph extents. The descent is the distance from the baseline to the lowest point of the character. This is positive if the glyph descends below the baseline. a `PangoRectangle` `PangoDirection` represents a direction in the Unicode bidirectional algorithm. Not every value in this enumeration makes sense for every usage of `PangoDirection`; for example, the return value of [func@unichar_direction] and [func@find_base_dir] cannot be `PANGO_DIRECTION_WEAK_LTR` or `PANGO_DIRECTION_WEAK_RTL`, since every character is either neutral or has a strong direction; on the other hand `PANGO_DIRECTION_NEUTRAL` doesn't make sense to pass to [func@itemize_with_base_dir]. The `PANGO_DIRECTION_TTB_LTR`, `PANGO_DIRECTION_TTB_RTL` values come from an earlier interpretation of this enumeration as the writing direction of a block of text and are no longer used. See `PangoGravity` for how vertical text is handled in Pango. If you are interested in text direction, you should really use fribidi directly. `PangoDirection` is only retained because it is used in some public apis. A strong left-to-right direction A strong right-to-left direction Deprecated value; treated the same as `PANGO_DIRECTION_RTL`. Deprecated value; treated the same as `PANGO_DIRECTION_LTR` A weak left-to-right direction A weak right-to-left direction No direction specified `PangoEllipsizeMode` describes what sort of ellipsization should be applied to text. In the ellipsization process characters are removed from the text in order to make it fit to a given width and replaced with an ellipsis. No ellipsization Omit characters at the start of the text Omit characters in the middle of the text Omit characters at the end of the text A `PangoFont` is used to represent a font in a rendering-system-independent manner. Frees an array of font descriptions. Just use pango_font_description_free in a loop a pointer to an array of `PangoFontDescription`, may be %NULL number of font descriptions in @descs Loads data previously created via [method@Pango.Font.serialize]. For a discussion of the supported format, see that function. Note: to verify that the returned font is identical to the one that was serialized, you can compare @bytes to the result of serializing the font again. a new `PangoFont` a `PangoContext` the bytes containing the data Returns a description of the font, with font size set in points. Use [method@Pango.Font.describe_with_absolute_size] if you want the font size in device units. a newly-allocated `PangoFontDescription` object. a `PangoFont` Computes the coverage map for a given font and language tag. a newly-allocated `PangoCoverage` object. a `PangoFont` the language tag Obtain the OpenType features that are provided by the font. These are passed to the rendering system, together with features that have been explicitly set via attributes. Note that this does not include OpenType features which the rendering system enables by default. a `PangoFont` Array to features in the length of @features the number of used items in @features Gets the font map for which the font was created. Note that the font maintains a *weak* reference to the font map, so if all references to font map are dropped, the font map will be finalized even if there are fonts created with the font map that are still alive. In that case this function will return %NULL. It is the responsibility of the user to ensure that the font map is kept alive. In most uses this is not an issue as a `PangoContext` holds a reference to the font map. the `PangoFontMap` for the font a `PangoFont` Gets the logical and ink extents of a glyph within a font. The coordinate system for each rectangle has its origin at the base line and horizontal origin of the character with increasing coordinates extending to the right and down. The macros PANGO_ASCENT(), PANGO_DESCENT(), PANGO_LBEARING(), and PANGO_RBEARING() can be used to convert from the extents rectangle to more traditional font metrics. The units of the rectangles are in 1/PANGO_SCALE of a device unit. If @font is %NULL, this function gracefully sets some sane values in the output variables and returns. a `PangoFont` the glyph index rectangle used to store the extents of the glyph as drawn rectangle used to store the logical extents of the glyph Gets overall metric information for a font. Since the metrics may be substantially different for different scripts, a language tag can be provided to indicate that the metrics should be retrieved that correspond to the script(s) used by that language. If @font is %NULL, this function gracefully sets some sane values in the output variables and returns. a `PangoFontMetrics` object. The caller must call [method@Pango.FontMetrics.unref] when finished using the object. a `PangoFont` language tag used to determine which script to get the metrics for, or %NULL to indicate to get the metrics for the entire font. Returns a description of the font, with font size set in points. Use [method@Pango.Font.describe_with_absolute_size] if you want the font size in device units. a newly-allocated `PangoFontDescription` object. a `PangoFont` Returns a description of the font, with absolute font size set in device units. Use [method@Pango.Font.describe] if you want the font size in points. a newly-allocated `PangoFontDescription` object. a `PangoFont` Computes the coverage map for a given font and language tag. a newly-allocated `PangoCoverage` object. a `PangoFont` the language tag Gets the `PangoFontFace` to which @font belongs. Note that this function can return `NULL` in cases where the font outlives its font map. the `PangoFontFace` a `PangoFont` Obtain the OpenType features that are provided by the font. These are passed to the rendering system, together with features that have been explicitly set via attributes. Note that this does not include OpenType features which the rendering system enables by default. a `PangoFont` Array to features in the length of @features the number of used items in @features Gets the font map for which the font was created. Note that the font maintains a *weak* reference to the font map, so if all references to font map are dropped, the font map will be finalized even if there are fonts created with the font map that are still alive. In that case this function will return %NULL. It is the responsibility of the user to ensure that the font map is kept alive. In most uses this is not an issue as a `PangoContext` holds a reference to the font map. the `PangoFontMap` for the font a `PangoFont` Gets the logical and ink extents of a glyph within a font. The coordinate system for each rectangle has its origin at the base line and horizontal origin of the character with increasing coordinates extending to the right and down. The macros PANGO_ASCENT(), PANGO_DESCENT(), PANGO_LBEARING(), and PANGO_RBEARING() can be used to convert from the extents rectangle to more traditional font metrics. The units of the rectangles are in 1/PANGO_SCALE of a device unit. If @font is %NULL, this function gracefully sets some sane values in the output variables and returns. a `PangoFont` the glyph index rectangle used to store the extents of the glyph as drawn rectangle used to store the logical extents of the glyph Get a `hb_font_t` object backing this font. Note that the objects returned by this function are cached and immutable. If you need to make changes to the `hb_font_t`, use [hb_font_create_sub_font()](https://harfbuzz.github.io/harfbuzz-hb-font.html#hb-font-create-sub-font). the `hb_font_t` object backing the font a `PangoFont` Returns the languages that are supported by @font. If the font backend does not provide this information, %NULL is returned. For the fontconfig backend, this corresponds to the FC_LANG member of the FcPattern. The returned array is only valid as long as the font and its fontmap are valid. an array of `PangoLanguage` a `PangoFont` Gets overall metric information for a font. Since the metrics may be substantially different for different scripts, a language tag can be provided to indicate that the metrics should be retrieved that correspond to the script(s) used by that language. If @font is %NULL, this function gracefully sets some sane values in the output variables and returns. a `PangoFontMetrics` object. The caller must call [method@Pango.FontMetrics.unref] when finished using the object. a `PangoFont` language tag used to determine which script to get the metrics for, or %NULL to indicate to get the metrics for the entire font. Returns whether the font provides a glyph for this character. `TRUE` if @font can render @wc a `PangoFont` a Unicode character Serializes the @font in a way that can be uniquely identified. There are no guarantees about the format of the output across different versions of Pango. The intended use of this function is testing, benchmarking and debugging. The format is not meant as a permanent storage format. To recreate a font from its serialized form, use [func@Pango.Font.deserialize]. a `GBytes` containing the serialized form of @font a `PangoFont` a newly-allocated `PangoFontDescription` object. a `PangoFont` a newly-allocated `PangoCoverage` object. a `PangoFont` the language tag a `PangoFont` the glyph index rectangle used to store the extents of the glyph as drawn rectangle used to store the logical extents of the glyph a `PangoFontMetrics` object. The caller must call [method@Pango.FontMetrics.unref] when finished using the object. a `PangoFont` language tag used to determine which script to get the metrics for, or %NULL to indicate to get the metrics for the entire font. the `PangoFontMap` for the font a `PangoFont` a `PangoFont` Array to features in the length of @features the number of used items in @features Specifies whether a font should or should not have color glyphs. The font should not have color glyphs The font should have color glyphs The font may or may not use color A `PangoFontDescription` describes a font in an implementation-independent manner. `PangoFontDescription` structures are used both to list what fonts are available on the system and also for specifying the characteristics of a font to load. Creates a new font description structure with all fields unset. the newly allocated `PangoFontDescription`, which should be freed using [method@Pango.FontDescription.free]. Determines if the style attributes of @new_match are a closer match for @desc than those of @old_match are, or if @old_match is %NULL, determines if @new_match is a match at all. Approximate matching is done for weight and style; other style attributes must match exactly. Style attributes are all attributes other than family and size-related attributes. Approximate matching for style considers %PANGO_STYLE_OBLIQUE and %PANGO_STYLE_ITALIC as matches, but not as good a match as when the styles are equal. Note that @old_match must match @desc. %TRUE if @new_match is a better match a `PangoFontDescription` a `PangoFontDescription`, or %NULL a `PangoFontDescription` Make a copy of a `PangoFontDescription`. the newly allocated `PangoFontDescription`, which should be freed with [method@Pango.FontDescription.free], or %NULL if @desc was %NULL. a `PangoFontDescription`, may be %NULL Make a copy of a `PangoFontDescription`, but don't duplicate allocated fields. This is like [method@Pango.FontDescription.copy], but only a shallow copy is made of the family name and other allocated fields. The result can only be used until @desc is modified or freed. This is meant to be used when the copy is only needed temporarily. the newly allocated `PangoFontDescription`, which should be freed with [method@Pango.FontDescription.free], or %NULL if @desc was %NULL. a `PangoFontDescription`, may be %NULL Compares two font descriptions for equality. Two font descriptions are considered equal if the fonts they describe are provably identical. This means that their masks do not have to match, as long as other fields are all the same. (Two font descriptions may result in identical fonts being loaded, but still compare %FALSE.) %TRUE if the two font descriptions are identical, %FALSE otherwise. a `PangoFontDescription` another `PangoFontDescription` Frees a font description. a `PangoFontDescription`, may be %NULL Returns the color field of the font description. This field determines whether the font description should match fonts that have color glyphs, or fonts that don't. a `PangoFontDescription` Gets the family name field of a font description. See [method@Pango.FontDescription.set_family]. the family name field for the font description, or %NULL if not previously set. This has the same life-time as the font description itself and should not be freed. a `PangoFontDescription`. Gets the features field of a font description. See [method@Pango.FontDescription.set_features]. the features field for the font description, or %NULL if not previously set. This has the same life-time as the font description itself and should not be freed. a `PangoFontDescription` Gets the gravity field of a font description. See [method@Pango.FontDescription.set_gravity]. the gravity field for the font description. Use [method@Pango.FontDescription.get_set_fields] to find out if the field was explicitly set or not. a `PangoFontDescription` Determines which fields in a font description have been set. a bitmask with bits set corresponding to the fields in @desc that have been set. a `PangoFontDescription` Gets the size field of a font description. See [method@Pango.FontDescription.set_size]. the size field for the font description in points or device units. You must call [method@Pango.FontDescription.get_size_is_absolute] to find out which is the case. Returns 0 if the size field has not previously been set or it has been set to 0 explicitly. Use [method@Pango.FontDescription.get_set_fields] to find out if the field was explicitly set or not. a `PangoFontDescription` Determines whether the size of the font is in points (not absolute) or device units (absolute). See [method@Pango.FontDescription.set_size] and [method@Pango.FontDescription.set_absolute_size]. whether the size for the font description is in points or device units. Use [method@Pango.FontDescription.get_set_fields] to find out if the size field of the font description was explicitly set or not. a `PangoFontDescription` Gets the stretch field of a font description. See [method@Pango.FontDescription.set_stretch]. the stretch field for the font description. Use [method@Pango.FontDescription.get_set_fields] to find out if the field was explicitly set or not. a `PangoFontDescription`. Gets the style field of a `PangoFontDescription`. See [method@Pango.FontDescription.set_style]. the style field for the font description. Use [method@Pango.FontDescription.get_set_fields] to find out if the field was explicitly set or not. a `PangoFontDescription` Gets the variant field of a `PangoFontDescription`. See [method@Pango.FontDescription.set_variant]. the variant field for the font description. Use [method@Pango.FontDescription.get_set_fields] to find out if the field was explicitly set or not. a `PangoFontDescription`. Gets the variations field of a font description. See [method@Pango.FontDescription.set_variations]. the variations field for the font description, or %NULL if not previously set. This has the same life-time as the font description itself and should not be freed. a `PangoFontDescription` Gets the weight field of a font description. See [method@Pango.FontDescription.set_weight]. the weight field for the font description. Use [method@Pango.FontDescription.get_set_fields] to find out if the field was explicitly set or not. a `PangoFontDescription` Computes a hash of a `PangoFontDescription` structure. This is suitable to be used, for example, as an argument to g_hash_table_new(). The hash value is independent of @desc->mask. the hash value. a `PangoFontDescription` Merges the fields that are set in @desc_to_merge into the fields in @desc. If @replace_existing is %FALSE, only fields in @desc that are not already set are affected. If %TRUE, then fields that are already set will be replaced as well. If @desc_to_merge is %NULL, this function performs nothing. a `PangoFontDescription` the `PangoFontDescription` to merge from, or %NULL if %TRUE, replace fields in @desc with the corresponding values from @desc_to_merge, even if they are already exist. Merges the fields that are set in @desc_to_merge into the fields in @desc, without copying allocated fields. This is like [method@Pango.FontDescription.merge], but only a shallow copy is made of the family name and other allocated fields. @desc can only be used until @desc_to_merge is modified or freed. This is meant to be used when the merged font description is only needed temporarily. a `PangoFontDescription` the `PangoFontDescription` to merge from if %TRUE, replace fields in @desc with the corresponding values from @desc_to_merge, even if they are already exist. Sets the size field of a font description, in device units. This is mutually exclusive with [method@Pango.FontDescription.set_size] which sets the font size in points. a `PangoFontDescription` the new size, in Pango units. There are %PANGO_SCALE Pango units in one device unit. For an output backend where a device unit is a pixel, a @size value of 10 * PANGO_SCALE gives a 10 pixel font. Sets the color field of a font description. This field determines whether the font description should match fonts that have color glyphs, or fonts that don't. a `PangoFontDescription`. the `PangoFontColor` value Sets the family name field of a font description. The family name represents a family of related font styles, and will resolve to a particular `PangoFontFamily`. In some uses of `PangoFontDescription`, it is also possible to use a comma separated list of family names for this field. a `PangoFontDescription`. a string representing the family name. Sets the family name field of a font description, without copying the string. This is like [method@Pango.FontDescription.set_family], except that no copy of @family is made. The caller must make sure that the string passed in stays around until @desc has been freed or the name is set again. This function can be used if @family is a static string such as a C string literal, or if @desc is only needed temporarily. a `PangoFontDescription` a string representing the family name Sets the features field of a font description. OpenType font features allow to enable or disable certain optional features of a font, such as tabular numbers. The format of the features string is comma-separated list of feature assignments, with each assignment being one of these forms: FEATURE=n where FEATURE must be a 4 character tag that identifies and OpenType feature, and n an integer (depending on the feature, the allowed values may be 0, 1 or bigger numbers). Unknown features are ignored. Note that font features set in this way are enabled for the entire text that is using the font, which is not appropriate for all OpenType features. The intended use case is to select character variations (features cv01 - c99), style sets (ss01 - ss20) and the like. Pango does not currently have a way to find supported OpenType features of a font. Both harfbuzz and freetype have API for this. See for example [hb_ot_layout_table_get_feature_tags](https://harfbuzz.github.io/harfbuzz-hb-ot-layout.html#hb-ot-layout-table-get-feature-tags). Features that are not supported by the font are silently ignored. a `PangoFontDescription`. a string representing the features Sets the features field of a font description. This is like [method@Pango.FontDescription.set_features], except that no copy of @featuresis made. The caller must make sure that the string passed in stays around until @desc has been freed or the name is set again. This function can be used if @features is a static string such as a C string literal, or if @desc is only needed temporarily. a `PangoFontDescription` a string representing the features Sets the gravity field of a font description. The gravity field specifies how the glyphs should be rotated. If @gravity is %PANGO_GRAVITY_AUTO, this actually unsets the gravity mask on the font description. This function is seldom useful to the user. Gravity should normally be set on a `PangoContext`. a `PangoFontDescription` the gravity for the font description. Sets the size field of a font description in fractional points. This is mutually exclusive with [method@Pango.FontDescription.set_absolute_size]. a `PangoFontDescription` the size of the font in points, scaled by %PANGO_SCALE. (That is, a @size value of 10 * PANGO_SCALE is a 10 point font. The conversion factor between points and device units depends on system configuration and the output device. For screen display, a logical DPI of 96 is common, in which case a 10 point font corresponds to a 10 * (96 / 72) = 13.3 pixel font. Use [method@Pango.FontDescription.set_absolute_size] if you need a particular size in device units. Sets the stretch field of a font description. The [enum@Pango.Stretch] field specifies how narrow or wide the font should be. a `PangoFontDescription` the stretch for the font description Sets the style field of a `PangoFontDescription`. The [enum@Pango.Style] enumeration describes whether the font is slanted and the manner in which it is slanted; it can be either %PANGO_STYLE_NORMAL, %PANGO_STYLE_ITALIC, or %PANGO_STYLE_OBLIQUE. Most fonts will either have a italic style or an oblique style, but not both, and font matching in Pango will match italic specifications with oblique fonts and vice-versa if an exact match is not found. a `PangoFontDescription` the style for the font description Sets the variant field of a font description. The [enum@Pango.Variant] can either be %PANGO_VARIANT_NORMAL or %PANGO_VARIANT_SMALL_CAPS. a `PangoFontDescription` the variant type for the font description. Sets the variations field of a font description. OpenType font variations allow to select a font instance by specifying values for a number of axes, such as width or weight. The format of the variations string is AXIS1=VALUE,AXIS2=VALUE... with each AXIS a 4 character tag that identifies a font axis, and each VALUE a floating point number. Unknown axes are ignored, and values are clamped to their allowed range. Pango does not currently have a way to find supported axes of a font. Both harfbuzz and freetype have API for this. See for example [hb_ot_var_get_axis_infos](https://harfbuzz.github.io/harfbuzz-hb-ot-var.html#hb-ot-var-get-axis-infos). a `PangoFontDescription`. a string representing the variations Sets the variations field of a font description. This is like [method@Pango.FontDescription.set_variations], except that no copy of @variations is made. The caller must make sure that the string passed in stays around until @desc has been freed or the name is set again. This function can be used if @variations is a static string such as a C string literal, or if @desc is only needed temporarily. a `PangoFontDescription` a string representing the variations Sets the weight field of a font description. The weight field specifies how bold or light the font should be. In addition to the values of the [enum@Pango.Weight] enumeration, other intermediate numeric values are possible. a `PangoFontDescription` the weight for the font description. Creates a filename representation of a font description. The filename is identical to the result from calling [method@Pango.FontDescription.to_string], but with underscores instead of characters that are untypical in filenames, and in lower case only. a new string that must be freed with g_free(). a `PangoFontDescription` Creates a string representation of a font description. See [func@Pango.FontDescription.from_string] for a description of the format of the string representation. The family list in the string description will only have a terminating comma if the last word of the list is a valid style option. a new string that must be freed with g_free(). a `PangoFontDescription` Unsets some of the fields in a `PangoFontDescription`. The unset fields will get back to their default values. a `PangoFontDescription` bitmask of fields in the @desc to unset. Creates a new font description from a string representation. The string must have the form [FAMILY-LIST] [STYLE-OPTIONS] [SIZE] [VARIATIONS] [FEATURES] where FAMILY-LIST is a comma-separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace-separated list of words where each word describes one of style, variant, weight, stretch, or gravity, and SIZE is a decimal number (size in points) or optionally followed by the unit modifier "px" for absolute size. The following words are understood as styles: "Normal", "Roman", "Oblique", "Italic". The following words are understood as variants: "Small-Caps", "All-Small-Caps", "Petite-Caps", "All-Petite-Caps", "Unicase", "Title-Caps". The following words are understood as weights: "Thin", "Ultra-Light", "Extra-Light", "Light", "Semi-Light", "Demi-Light", "Book", "Regular", "Medium", "Semi-Bold", "Demi-Bold", "Bold", "Ultra-Bold", "Extra-Bold", "Heavy", "Black", "Ultra-Black", "Extra-Black". The following words are understood as stretch values: "Ultra-Condensed", "Extra-Condensed", "Condensed", "Semi-Condensed", "Semi-Expanded", "Expanded", "Extra-Expanded", "Ultra-Expanded". The following words are understood as gravity values: "Not-Rotated", "South", "Upside-Down", "North", "Rotated-Left", "East", "Rotated-Right", "West". The following words are understood as color values: "With-Color", "Without-Color". VARIATIONS is a comma-separated list of font variations of the form @‍axis1=value,axis2=value,... FEATURES is a comma-separated list of font features of the form \#‍feature1=value,feature2=value,... The =value part can be ommitted if the value is 1. Any one of the options may be absent. If FAMILY-LIST is absent, then the family_name field of the resulting font description will be initialized to %NULL. If STYLE-OPTIONS is missing, then all style options will be set to the default values. If SIZE is missing, the size in the resulting font description will be set to 0. A typical example: Cantarell Italic Light 15 @‍wght=200 #‍tnum=1 a new `PangoFontDescription`. string representation of a font description. A `PangoFontFace` is used to represent a group of fonts with the same family, slant, weight, and width, but varying sizes. Returns a font description that matches the face. The resulting font description will have the family, style, variant, weight and stretch of the face, but its size field will be unset. a newly-created `PangoFontDescription` structure holding the description of the face. Use [method@Pango.FontDescription.free] to free the result. a `PangoFontFace` Gets a name representing the style of this face. Note that a font family may contain multiple faces with the same name (e.g. a variable and a non-variable face for the same style). the face name for the face. This string is owned by the face object and must not be modified or freed. a `PangoFontFace`. Gets the `PangoFontFamily` that @face belongs to. the `PangoFontFamily` a `PangoFontFace` Returns whether a `PangoFontFace` is synthesized. This will be the case if the underlying font rendering engine creates this face from another face, by shearing, emboldening, lightening or modifying it in some other way. whether @face is synthesized a `PangoFontFace` List the available sizes for a font. This is only applicable to bitmap fonts. For scalable fonts, stores %NULL at the location pointed to by @sizes and 0 at the location pointed to by @n_sizes. The sizes returned are in Pango units and are sorted in ascending order. a `PangoFontFace`. location to store a pointer to an array of int. This array should be freed with g_free(). location to store the number of elements in @sizes Returns a font description that matches the face. The resulting font description will have the family, style, variant, weight and stretch of the face, but its size field will be unset. a newly-created `PangoFontDescription` structure holding the description of the face. Use [method@Pango.FontDescription.free] to free the result. a `PangoFontFace` Gets a name representing the style of this face. Note that a font family may contain multiple faces with the same name (e.g. a variable and a non-variable face for the same style). the face name for the face. This string is owned by the face object and must not be modified or freed. a `PangoFontFace`. Gets the `PangoFontFamily` that @face belongs to. the `PangoFontFamily` a `PangoFontFace` Returns whether a `PangoFontFace` is synthesized. This will be the case if the underlying font rendering engine creates this face from another face, by shearing, emboldening, lightening or modifying it in some other way. whether @face is synthesized a `PangoFontFace` List the available sizes for a font. This is only applicable to bitmap fonts. For scalable fonts, stores %NULL at the location pointed to by @sizes and 0 at the location pointed to by @n_sizes. The sizes returned are in Pango units and are sorted in ascending order. a `PangoFontFace`. location to store a pointer to an array of int. This array should be freed with g_free(). location to store the number of elements in @sizes the face name for the face. This string is owned by the face object and must not be modified or freed. a `PangoFontFace`. a newly-created `PangoFontDescription` structure holding the description of the face. Use [method@Pango.FontDescription.free] to free the result. a `PangoFontFace` a `PangoFontFace`. location to store a pointer to an array of int. This array should be freed with g_free(). location to store the number of elements in @sizes whether @face is synthesized a `PangoFontFace` the `PangoFontFamily` a `PangoFontFace` A `PangoFontFamily` is used to represent a family of related font faces. The font faces in a family share a common design, but differ in slant, weight, width or other aspects. Gets the `PangoFontFace` of @family with the given name. the `PangoFontFace`, or %NULL if no face with the given name exists. a `PangoFontFamily` the name of a face. If the name is %NULL, the family's default face (fontconfig calls it "Regular") will be returned. Gets the name of the family. The name is unique among all fonts for the font backend and can be used in a `PangoFontDescription` to specify that a face from this family is desired. the name of the family. This string is owned by the family object and must not be modified or freed. a `PangoFontFamily` A monospace font is a font designed for text display where the the characters form a regular grid. For Western languages this would mean that the advance width of all characters are the same, but this categorization also includes Asian fonts which include double-width characters: characters that occupy two grid cells. g_unichar_iswide() returns a result that indicates whether a character is typically double-width in a monospace font. The best way to find out the grid-cell size is to call [method@Pango.FontMetrics.get_approximate_digit_width], since the results of [method@Pango.FontMetrics.get_approximate_char_width] may be affected by double-width characters. %TRUE if the family is monospace. a `PangoFontFamily` A variable font is a font which has axes that can be modified to produce different faces. Such axes are also known as _variations_; see [method@Pango.FontDescription.set_variations] for more information. %TRUE if the family is variable a `PangoFontFamily` Lists the different font faces that make up @family. The faces in a family share a common design, but differ in slant, weight, width and other aspects. Note that the returned faces are not in any particular order, and multiple faces may have the same name or characteristics. `PangoFontFamily` also implemented the [iface@Gio.ListModel] interface for enumerating faces. a `PangoFontFamily` location to store an array of pointers to `PangoFontFace` objects, or %NULL. This array should be freed with g_free() when it is no longer needed. location to store number of elements in @faces. Gets the `PangoFontFace` of @family with the given name. the `PangoFontFace`, or %NULL if no face with the given name exists. a `PangoFontFamily` the name of a face. If the name is %NULL, the family's default face (fontconfig calls it "Regular") will be returned. Gets the name of the family. The name is unique among all fonts for the font backend and can be used in a `PangoFontDescription` to specify that a face from this family is desired. the name of the family. This string is owned by the family object and must not be modified or freed. a `PangoFontFamily` A monospace font is a font designed for text display where the the characters form a regular grid. For Western languages this would mean that the advance width of all characters are the same, but this categorization also includes Asian fonts which include double-width characters: characters that occupy two grid cells. g_unichar_iswide() returns a result that indicates whether a character is typically double-width in a monospace font. The best way to find out the grid-cell size is to call [method@Pango.FontMetrics.get_approximate_digit_width], since the results of [method@Pango.FontMetrics.get_approximate_char_width] may be affected by double-width characters. %TRUE if the family is monospace. a `PangoFontFamily` A variable font is a font which has axes that can be modified to produce different faces. Such axes are also known as _variations_; see [method@Pango.FontDescription.set_variations] for more information. %TRUE if the family is variable a `PangoFontFamily` Lists the different font faces that make up @family. The faces in a family share a common design, but differ in slant, weight, width and other aspects. Note that the returned faces are not in any particular order, and multiple faces may have the same name or characteristics. `PangoFontFamily` also implemented the [iface@Gio.ListModel] interface for enumerating faces. a `PangoFontFamily` location to store an array of pointers to `PangoFontFace` objects, or %NULL. This array should be freed with g_free() when it is no longer needed. location to store number of elements in @faces. Is this a monospace font Is this a variable font The type of items contained in this list. The number of items contained in this list. The name of the family a `PangoFontFamily` location to store an array of pointers to `PangoFontFace` objects, or %NULL. This array should be freed with g_free() when it is no longer needed. location to store number of elements in @faces. the name of the family. This string is owned by the family object and must not be modified or freed. a `PangoFontFamily` %TRUE if the family is monospace. a `PangoFontFamily` %TRUE if the family is variable a `PangoFontFamily` the `PangoFontFace`, or %NULL if no face with the given name exists. a `PangoFontFamily` the name of a face. If the name is %NULL, the family's default face (fontconfig calls it "Regular") will be returned. A `PangoFontMap` represents the set of fonts available for a particular rendering system. This is a virtual object with implementations being specific to particular rendering systems. Forces a change in the fontmap, which will cause any `PangoContext` using this fontmap to change. This function is only useful when implementing a new backend for Pango, something applications won't do. Backends should call this function if they have attached extra data to the fontmap and such data is changed. a `PangoFontMap` Gets a font family by name. the `PangoFontFamily` a `PangoFontMap` a family name Returns the current serial number of @fontmap. The serial number is initialized to an small number larger than zero when a new fontmap is created and is increased whenever the fontmap is changed. It may wrap, but will never have the value 0. Since it can wrap, never compare it with "less than", always use "not equals". The fontmap can only be changed using backend-specific API, like changing fontmap resolution. This can be used to automatically detect changes to a `PangoFontMap`, like in `PangoContext`. The current serial number of @fontmap. a `PangoFontMap` List all families for a fontmap. Note that the returned families are not in any particular order. `PangoFontMap` also implemented the [iface@Gio.ListModel] interface for enumerating families. a `PangoFontMap` location to store a pointer to an array of `PangoFontFamily` *. This array should be freed with g_free(). location to store the number of elements in @families Load the font in the fontmap that is the closest match for @desc. the newly allocated `PangoFont` loaded, or %NULL if no font matched. a `PangoFontMap` the `PangoContext` the font will be used with a `PangoFontDescription` describing the font to load Load a set of fonts in the fontmap that can be used to render a font matching @desc. the newly allocated `PangoFontset` loaded, or %NULL if no font matched. a `PangoFontMap` the `PangoContext` the font will be used with a `PangoFontDescription` describing the font to load a `PangoLanguage` the fonts will be used for Loads a font file with one or more fonts into the `PangoFontMap`. The added fonts will take precedence over preexisting fonts with the same name. True if the font file is successfully loaded into the fontmap, false if an error occurred. a `PangoFontMap` Path to the font file Forces a change in the fontmap, which will cause any `PangoContext` using this fontmap to change. This function is only useful when implementing a new backend for Pango, something applications won't do. Backends should call this function if they have attached extra data to the fontmap and such data is changed. a `PangoFontMap` Creates a `PangoContext` connected to @fontmap. This is equivalent to [ctor@Pango.Context.new] followed by [method@Pango.Context.set_font_map]. If you are using Pango as part of a higher-level system, that system may have it's own way of create a `PangoContext`. For instance, the GTK toolkit has, among others, gtk_widget_get_pango_context(). Use those instead. the newly allocated `PangoContext`, which should be freed with g_object_unref(). a `PangoFontMap` Gets a font family by name. the `PangoFontFamily` a `PangoFontMap` a family name Returns the current serial number of @fontmap. The serial number is initialized to an small number larger than zero when a new fontmap is created and is increased whenever the fontmap is changed. It may wrap, but will never have the value 0. Since it can wrap, never compare it with "less than", always use "not equals". The fontmap can only be changed using backend-specific API, like changing fontmap resolution. This can be used to automatically detect changes to a `PangoFontMap`, like in `PangoContext`. The current serial number of @fontmap. a `PangoFontMap` List all families for a fontmap. Note that the returned families are not in any particular order. `PangoFontMap` also implemented the [iface@Gio.ListModel] interface for enumerating families. a `PangoFontMap` location to store a pointer to an array of `PangoFontFamily` *. This array should be freed with g_free(). location to store the number of elements in @families Load the font in the fontmap that is the closest match for @desc. the newly allocated `PangoFont` loaded, or %NULL if no font matched. a `PangoFontMap` the `PangoContext` the font will be used with a `PangoFontDescription` describing the font to load Load a set of fonts in the fontmap that can be used to render a font matching @desc. the newly allocated `PangoFontset` loaded, or %NULL if no font matched. a `PangoFontMap` the `PangoContext` the font will be used with a `PangoFontDescription` describing the font to load a `PangoLanguage` the fonts will be used for Returns a new font that is like @font, except that it is scaled by @scale, its backend-dependent configuration (e.g. cairo font options) is replaced by the one in @context, and its variations are replaced by @variations. Note that the scaling here is meant to be linear, so this scaling can be used to render a font on a hi-dpi display without changing its optical size. the modified font a `PangoFontMap` a font in @fontmap the scale factor to apply a `PangoContext` font variations to use The type of items contained in this list. The number of items contained in this list. The `PangoFontMapClass` structure holds the virtual functions for a particular `PangoFontMap` implementation. parent `GObjectClass` a function to load a font with a given description. See pango_font_map_load_font(). the newly allocated `PangoFont` loaded, or %NULL if no font matched. a `PangoFontMap` the `PangoContext` the font will be used with a `PangoFontDescription` describing the font to load A function to list available font families. See pango_font_map_list_families(). a `PangoFontMap` location to store a pointer to an array of `PangoFontFamily` *. This array should be freed with g_free(). location to store the number of elements in @families a function to load a fontset with a given given description suitable for a particular language. See pango_font_map_load_fontset(). the newly allocated `PangoFontset` loaded, or %NULL if no font matched. a `PangoFontMap` the `PangoContext` the font will be used with a `PangoFontDescription` describing the font to load a `PangoLanguage` the fonts will be used for the type of rendering-system-dependent engines that can handle fonts of this fonts loaded with this fontmap. a function to get the serial number of the fontmap. See pango_font_map_get_serial(). The current serial number of @fontmap. a `PangoFontMap` See pango_font_map_changed() a `PangoFontMap` the `PangoFontFamily` a `PangoFontMap` a family name The bits in a `PangoFontMask` correspond to the set fields in a `PangoFontDescription`. the font family is specified. the font style is specified. the font variant is specified. the font weight is specified. the font stretch is specified. the font size is specified. The font gravity is specified. OpenType font variations are specified. OpenType font features are specified. Font color is specified. A `PangoFontMetrics` structure holds the overall metric information for a font. The information in a `PangoFontMetrics` structure may be restricted to a script. The fields of this structure are private to implementations of a font backend. See the documentation of the corresponding getters for documentation of their meaning. For an overview of the most important metrics, see: <picture> <source srcset="fontmetrics-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Font metrics" src="fontmetrics-light.png"> </picture> Gets the approximate character width for a font metrics structure. This is merely a representative value useful, for example, for determining the initial size for a window. Actual characters in text will be wider and narrower than this. the character width, in Pango units. a `PangoFontMetrics` structure Gets the approximate digit width for a font metrics structure. This is merely a representative value useful, for example, for determining the initial size for a window. Actual digits in text can be wider or narrower than this, though this value is generally somewhat more accurate than the result of pango_font_metrics_get_approximate_char_width() for digits. the digit width, in Pango units. a `PangoFontMetrics` structure Gets the ascent from a font metrics structure. The ascent is the distance from the baseline to the logical top of a line of text. (The logical top may be above or below the top of the actual drawn ink. It is necessary to lay out the text to figure where the ink will be.) the ascent, in Pango units. a `PangoFontMetrics` structure Gets the descent from a font metrics structure. The descent is the distance from the baseline to the logical bottom of a line of text. (The logical bottom may be above or below the bottom of the actual drawn ink. It is necessary to lay out the text to figure where the ink will be.) the descent, in Pango units. a `PangoFontMetrics` structure Gets the line height from a font metrics structure. The line height is the recommended distance between successive baselines in wrapped text using this font. If the line height is not available, 0 is returned. the height, in Pango units a `PangoFontMetrics` structure Gets the suggested position to draw the strikethrough. The value returned is the distance *above* the baseline of the top of the strikethrough. the suggested strikethrough position, in Pango units. a `PangoFontMetrics` structure Gets the suggested thickness to draw for the strikethrough. the suggested strikethrough thickness, in Pango units. a `PangoFontMetrics` structure Gets the suggested position to draw the underline. The value returned is the distance *above* the baseline of the top of the underline. Since most fonts have underline positions beneath the baseline, this value is typically negative. the suggested underline position, in Pango units. a `PangoFontMetrics` structure Gets the suggested thickness to draw for the underline. the suggested underline thickness, in Pango units. a `PangoFontMetrics` structure Increase the reference count of a font metrics structure by one. @metrics a `PangoFontMetrics` structure, may be %NULL Decrease the reference count of a font metrics structure by one. If the result is zero, frees the structure and any associated memory. a `PangoFontMetrics` structure, may be %NULL An enumeration that affects font sizes for superscript and subscript positioning and for (emulated) Small Caps. Leave the font size unchanged Change the font to a size suitable for superscripts Change the font to a size suitable for subscripts Change the font to a size suitable for Small Caps A `PangoFontset` represents a set of `PangoFont` to use when rendering text. A `PangoFontset` is the result of resolving a `PangoFontDescription` against a particular `PangoContext`. It has operations for finding the component font for a particular Unicode character, and for finding a composite set of metrics for the entire fontset. Iterates through all the fonts in a fontset, calling @func for each one. If @func returns %TRUE, that stops the iteration. a `PangoFontset` Callback function data to pass to the callback function Returns the font in the fontset that contains the best glyph for a Unicode character. a `PangoFont` a `PangoFontset` a Unicode character a function to get the language of the fontset. Get overall metric information for the fonts in the fontset. a `PangoFontMetrics` object a `PangoFontset` Iterates through all the fonts in a fontset, calling @func for each one. If @func returns %TRUE, that stops the iteration. a `PangoFontset` Callback function data to pass to the callback function Returns the font in the fontset that contains the best glyph for a Unicode character. a `PangoFont` a `PangoFontset` a Unicode character Get overall metric information for the fonts in the fontset. a `PangoFontMetrics` object a `PangoFontset` The `PangoFontsetClass` structure holds the virtual functions for a particular `PangoFontset` implementation. parent `GObjectClass` a function to get the font in the fontset that contains the best glyph for the given Unicode character; see [method@Pango.Fontset.get_font] a `PangoFont` a `PangoFontset` a Unicode character a function to get overall metric information for the fonts in the fontset; see [method@Pango.Fontset.get_metrics] a `PangoFontMetrics` object a `PangoFontset` a function to get the language of the fontset. a function to loop over the fonts in the fontset. See [method@Pango.Fontset.foreach] a `PangoFontset` Callback function data to pass to the callback function Callback used when enumerating fonts in a fontset. See [method@Pango.Fontset.foreach]. if %TRUE, stop iteration and return immediately. a `PangoFontset` a font from @fontset callback data `PangoFontsetSimple` is a implementation of the abstract `PangoFontset` base class as an array of fonts. When creating a `PangoFontsetSimple`, you have to provide the array of fonts that make up the fontset. Creates a new `PangoFontsetSimple` for the given language. the newly allocated `PangoFontsetSimple` a `PangoLanguage` tag Adds a font to the fontset. The fontset takes ownership of @font. a `PangoFontsetSimple`. a `PangoFont`. Returns the number of fonts in the fontset. the size of @fontset a `PangoFontsetSimple`. The way this unknown glyphs are rendered is backend specific. For example, a box with the hexadecimal Unicode code-point of the character written in it is what is done in the most common backends. a Unicode character A `PangoGlyph` value that indicates a zero-width empty glpyh. This is useful for example in shaper modules, to use as the glyph for various zero-width Unicode characters (those passing [func@is_zero_width]). A `PangoGlyph` value for invalid input. `PangoLayout` produces one such glyph per invalid input UTF-8 byte and such a glyph is rendered as a crossed box. Note that this value is defined such that it has the %PANGO_GLYPH_UNKNOWN_FLAG set. Flag used in `PangoGlyph` to turn a `gunichar` value of a valid Unicode character into an unknown-character glyph for that `gunichar`. Such unknown-character glyphs may be rendered as a 'hex box'. Whether a `PangoGravity` represents a gravity that results in reversal of text direction. the `PangoGravity` to check Whether a `PangoGravity` represents vertical writing directions. the `PangoGravity` to check The `PangoGlyphGeometry` structure contains width and positioning information for a single glyph. Note that @width is not guaranteed to be the same as the glyph extents. Kerning and other positioning applied during shaping will affect both the @width and the @x_offset for the glyphs in the glyph string that results from shaping. The information in this struct is intended for rendering the glyphs, as follows: 1. Assume the current point is (x, y) 2. Render the current glyph at (x + x_offset, y + y_offset), 3. Advance the current point to (x + width, y) 4. Render the next glyph the logical width to use for the the character. horizontal offset from nominal character position. vertical offset from nominal character position. A `PangoGlyphInfo` structure represents a single glyph with positioning information and visual attributes. the glyph itself. the positional information about the glyph. the visual attributes of the glyph. A `PangoGlyphItem` is a pair of a `PangoItem` and the glyphs resulting from shaping the items text. As an example of the usage of `PangoGlyphItem`, the results of shaping text with `PangoLayout` is a list of `PangoLayoutLine`, each of which contains a list of `PangoGlyphItem`. corresponding `PangoItem` corresponding `PangoGlyphString` shift of the baseline, relative to the baseline of the containing line. Positive values shift upwards horizontal displacement to apply before the glyph item. Positive values shift right horizontal displacement to apply after th glyph item. Positive values shift right Splits a shaped item (`PangoGlyphItem`) into multiple items based on an attribute list. The idea is that if you have attributes that don't affect shaping, such as color or underline, to avoid affecting shaping, you filter them out ([method@Pango.AttrList.filter]), apply the shaping process and then reapply them to the result using this function. All attributes that start or end inside a cluster are applied to that cluster; for instance, if half of a cluster is underlined and the other-half strikethrough, then the cluster will end up with both underline and strikethrough attributes. In these cases, it may happen that @item->extra_attrs for some of the result items can have multiple attributes of the same type. This function takes ownership of @glyph_item; it will be reused as one of the elements in the list. a list of glyph items resulting from splitting @glyph_item. Free the elements using [method@Pango.GlyphItem.free], the list using g_slist_free(). a shaped item text that @list applies to a `PangoAttrList` Make a deep copy of an existing `PangoGlyphItem` structure. the newly allocated `PangoGlyphItem` a `PangoGlyphItem` Frees a `PangoGlyphItem` and resources to which it points. a `PangoGlyphItem` Given a `PangoGlyphItem` and the corresponding text, determine the width corresponding to each character. When multiple characters compose a single cluster, the width of the entire cluster is divided equally among the characters. See also [method@Pango.GlyphString.get_logical_widths]. a `PangoGlyphItem` text that @glyph_item corresponds to (glyph_item->item->offset is an offset from the start of @text) an array whose length is the number of characters in glyph_item (equal to `glyph_item->item->num_chars`) to be filled in with the resulting character widths. Adds spacing between the graphemes of @glyph_item to give the effect of typographic letter spacing. a `PangoGlyphItem` text that @glyph_item corresponds to (glyph_item->item->offset is an offset from the start of @text) logical attributes for the item (the first logical attribute refers to the position before the first character in the item) amount of letter spacing to add in Pango units. May be negative, though too large negative values will give ugly results. Modifies @orig to cover only the text after @split_index, and returns a new item that covers the text before @split_index that used to be in @orig. You can think of @split_index as the length of the returned item. @split_index may not be 0, and it may not be greater than or equal to the length of @orig (that is, there must be at least one byte assigned to each item, you can't create a zero-length item). This function is similar in function to pango_item_split() (and uses it internally.) the newly allocated item representing text before @split_index, which should be freed with pango_glyph_item_free(). a `PangoItem` text to which positions in @orig apply byte index of position to split item, relative to the start of the item A `PangoGlyphItemIter` is an iterator over the clusters in a `PangoGlyphItem`. The *forward direction* of the iterator is the logical direction of text. That is, with increasing @start_index and @start_char values. If @glyph_item is right-to-left (that is, if `glyph_item->item->analysis.level` is odd), then @start_glyph decreases as the iterator moves forward. Moreover, in right-to-left cases, @start_glyph is greater than @end_glyph. An iterator should be initialized using either pango_glyph_item_iter_init_start() or pango_glyph_item_iter_init_end(), for forward and backward iteration respectively, and walked over using any desired mixture of pango_glyph_item_iter_next_cluster() and pango_glyph_item_iter_prev_cluster(). A common idiom for doing a forward iteration over the clusters is: ``` PangoGlyphItemIter cluster_iter; gboolean have_cluster; for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter, glyph_item, text); have_cluster; have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter)) { ... } ``` Note that @text is the start of the text for layout, which is then indexed by `glyph_item->item->offset` to get to the text of @glyph_item. The @start_index and @end_index values can directly index into @text. The @start_glyph, @end_glyph, @start_char, and @end_char values however are zero-based for the @glyph_item. For each cluster, the item pointed at by the start variables is included in the cluster while the one pointed at by end variables is not. None of the members of a `PangoGlyphItemIter` should be modified manually. Make a shallow copy of an existing `PangoGlyphItemIter` structure. the newly allocated `PangoGlyphItemIter` a `PangoGlyphItem`Iter Frees a `PangoGlyphItem`Iter. a `PangoGlyphItemIter` Initializes a `PangoGlyphItemIter` structure to point to the last cluster in a glyph item. See `PangoGlyphItemIter` for details of cluster orders. %FALSE if there are no clusters in the glyph item a `PangoGlyphItemIter` the glyph item to iterate over text corresponding to the glyph item Initializes a `PangoGlyphItemIter` structure to point to the first cluster in a glyph item. See `PangoGlyphItemIter` for details of cluster orders. %FALSE if there are no clusters in the glyph item a `PangoGlyphItemIter` the glyph item to iterate over text corresponding to the glyph item Advances the iterator to the next cluster in the glyph item. See `PangoGlyphItemIter` for details of cluster orders. %TRUE if the iterator was advanced, %FALSE if we were already on the last cluster. a `PangoGlyphItemIter` Moves the iterator to the preceding cluster in the glyph item. See `PangoGlyphItemIter` for details of cluster orders. %TRUE if the iterator was moved, %FALSE if we were already on the first cluster. a `PangoGlyphItemIter` A `PangoGlyphString` is used to store strings of glyphs with geometry and visual attribute information. The storage for the glyph information is owned by the structure which simplifies memory management. number of glyphs in this glyph string array of glyph information logical cluster info, indexed by the byte index within the text corresponding to the glyph string Create a new `PangoGlyphString`. the newly allocated `PangoGlyphString`, which should be freed with [method@Pango.GlyphString.free]. Copy a glyph string and associated storage. the newly allocated `PangoGlyphString` a `PangoGlyphString` Compute the logical and ink extents of a glyph string. See the documentation for [method@Pango.Font.get_glyph_extents] for details about the interpretation of the rectangles. Examples of logical (red) and ink (green) rects: ![](rects1.png) ![](rects2.png) a `PangoGlyphString` a `PangoFont` rectangle used to store the extents of the glyph string as drawn rectangle used to store the logical extents of the glyph string Computes the extents of a sub-portion of a glyph string. The extents are relative to the start of the glyph string range (the origin of their coordinate system is at the start of the range, not at the start of the entire glyph string). a `PangoGlyphString` start index end index (the range is the set of bytes with indices such that start <= index < end) a `PangoFont` rectangle used to store the extents of the glyph string range as drawn rectangle used to store the logical extents of the glyph string range Free a glyph string and associated storage. a `PangoGlyphString`, may be %NULL Given a `PangoGlyphString` and corresponding text, determine the width corresponding to each character. When multiple characters compose a single cluster, the width of the entire cluster is divided equally among the characters. See also [method@Pango.GlyphItem.get_logical_widths]. a `PangoGlyphString` the text corresponding to the glyphs the length of @text, in bytes the embedding level of the string an array whose length is the number of characters in text (equal to `g_utf8_strlen (text, length)` unless text has `NUL` bytes) to be filled in with the resulting character widths. Computes the logical width of the glyph string. This can also be computed using [method@Pango.GlyphString.extents]. However, since this only computes the width, it's much faster. This is in fact only a convenience function that computes the sum of @geometry.width for each glyph in the @glyphs. the logical width of the glyph string. a `PangoGlyphString` Converts from character position to x position. The X position is measured from the left edge of the run. Character positions are obtained using font metrics for ligatures where available, and computed by dividing up each cluster into equal portions, otherwise. <picture> <source srcset="glyphstring-positions-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Glyph positions" src="glyphstring-positions-light.png"> </picture> the glyphs return from [func@shape] the text for the run the number of bytes (not characters) in @text. the analysis information return from [func@itemize] the byte index within @text whether we should compute the result for the beginning (%FALSE) or end (%TRUE) of the character. location to store result Converts from character position to x position. This variant of [method@Pango.GlyphString.index_to_x] additionally accepts a `PangoLogAttr` array. The grapheme boundary information in it can be used to disambiguate positioning inside some complex clusters. the glyphs return from [func@shape] the text for the run the number of bytes (not characters) in @text. the analysis information return from [func@itemize] `PangoLogAttr` array for @text the byte index within @text whether we should compute the result for the beginning (%FALSE) or end (%TRUE) of the character. location to store result Resize a glyph string to the given length. a `PangoGlyphString`. the new length of the string Convert from x offset to character position. Character positions are computed by dividing up each cluster into equal portions. In scripts where positioning within a cluster is not allowed (such as Thai), the returned value may not be a valid cursor position; the caller must combine the result with the logical attributes for the text to compute the valid cursor position. the glyphs returned from [func@shape] the text for the run the number of bytes (not characters) in text. the analysis information return from [func@itemize] the x offset (in Pango units) location to store calculated byte index within @text location to store a boolean indicating whether the user clicked on the leading or trailing edge of the character A `PangoGlyphVisAttr` structure communicates information between the shaping and rendering phases. Currently, it contains cluster start and color information. More attributes may be added in the future. Clusters are stored in visual order, within the cluster, glyphs are always ordered in logical order, since visual order is meaningless; that is, in Arabic text, accent glyphs follow the glyphs for the base character. set for the first logical glyph in each cluster. `PangoGravity` represents the orientation of glyphs in a segment of text. This is useful when rendering vertical text layouts. In those situations, the layout is rotated using a non-identity [struct@Pango.Matrix], and then glyph orientation is controlled using `PangoGravity`. Not every value in this enumeration makes sense for every usage of `PangoGravity`; for example, %PANGO_GRAVITY_AUTO only can be passed to [method@Pango.Context.set_base_gravity] and can only be returned by [method@Pango.Context.get_base_gravity]. See also: [enum@Pango.GravityHint] Glyphs stand upright (default) <img align="right" valign="center" src="m-south.png"> Glyphs are rotated 90 degrees counter-clockwise. <img align="right" valign="center" src="m-east.png"> Glyphs are upside-down. <img align="right" valign="cener" src="m-north.png"> Glyphs are rotated 90 degrees clockwise. <img align="right" valign="center" src="m-west.png"> Gravity is resolved from the context matrix Finds the gravity that best matches the rotation component in a `PangoMatrix`. the gravity of @matrix, which will never be %PANGO_GRAVITY_AUTO, or %PANGO_GRAVITY_SOUTH if @matrix is %NULL a `PangoMatrix` Returns the gravity to use in laying out a `PangoItem`. The gravity is determined based on the script, base gravity, and hint. If @base_gravity is %PANGO_GRAVITY_AUTO, it is first replaced with the preferred gravity of @script. To get the preferred gravity of a script, pass %PANGO_GRAVITY_AUTO and %PANGO_GRAVITY_HINT_STRONG in. resolved gravity suitable to use for a run of text with @script `PangoScript` to query base gravity of the paragraph orientation hint Returns the gravity to use in laying out a single character or `PangoItem`. The gravity is determined based on the script, East Asian width, base gravity, and hint, This function is similar to [func@Pango.Gravity.get_for_script] except that this function makes a distinction between narrow/half-width and wide/full-width characters also. Wide/full-width characters always stand *upright*, that is, they always take the base gravity, whereas narrow/full-width characters are always rotated in vertical context. If @base_gravity is %PANGO_GRAVITY_AUTO, it is first replaced with the preferred gravity of @script. resolved gravity suitable to use for a run of text with @script and @wide. `PangoScript` to query %TRUE for wide characters as returned by g_unichar_iswide() base gravity of the paragraph orientation hint Converts a `PangoGravity` value to its natural rotation in radians. Note that [method@Pango.Matrix.rotate] takes angle in degrees, not radians. So, to call [method@Pango.Matrix,rotate] with the output of this function you should multiply it by (180. / G_PI). the rotation value corresponding to @gravity. gravity to query, should not be %PANGO_GRAVITY_AUTO `PangoGravityHint` defines how horizontal scripts should behave in a vertical context. That is, English excerpts in a vertical paragraph for example. See also [enum@Pango.Gravity] scripts will take their natural gravity based on the base gravity and the script. This is the default. always use the base gravity set, regardless of the script. for scripts not in their natural direction (eg. Latin in East gravity), choose per-script gravity such that every script respects the line progression. This means, Latin and Arabic will take opposite gravities and both flow top-to-bottom for example. The `PangoItem` structure stores information about a segment of text. You typically obtain `PangoItems` by itemizing a piece of text with [func@itemize]. byte offset of the start of this item in text. length of this item in bytes. number of Unicode characters in the item. analysis results for the item. Creates a new `PangoItem` structure initialized to default values. the newly allocated `PangoItem`, which should be freed with [method@Pango.Item.free]. Add attributes to a `PangoItem`. The idea is that you have attributes that don't affect itemization, such as font features, so you filter them out using [method@Pango.AttrList.filter], itemize your text, then reapply the attributes to the resulting items using this function. The @iter should be positioned before the range of the item, and will be advanced past it. This function is meant to be called in a loop over the items resulting from itemization, while passing the iter to each call. a `PangoItem` a `PangoAttrIterator` Copy an existing `PangoItem` structure. the newly allocated `PangoItem` a `PangoItem` Free a `PangoItem` and all associated memory. a `PangoItem`, may be %NULL Returns the character offset of the item from the beginning of the itemized text. If the item has not been obtained from Pango's itemization machinery, then the character offset is not available. In that case, this function returns -1. the character offset of the item from the beginning of the itemized text, or -1 a `PangoItem` Modifies @orig to cover only the text after @split_index, and returns a new item that covers the text before @split_index that used to be in @orig. You can think of @split_index as the length of the returned item. @split_index may not be 0, and it may not be greater than or equal to the length of @orig (that is, there must be at least one byte assigned to each item, you can't create a zero-length item). @split_offset is the length of the first item in chars, and must be provided because the text used to generate the item isn't available, so `pango_item_split()` can't count the char length of the split items itself. new item representing text before @split_index, which should be freed with [method@Pango.Item.free]. a `PangoItem` byte index of position to split item, relative to the start of the item number of chars between start of @orig and @split_index Extracts the *left bearing* from a `PangoRectangle` representing glyph extents. The left bearing is the distance from the horizontal origin to the farthest left point of the character. This is positive for characters drawn completely to the right of the glyph origin. a `PangoRectangle` The `PangoLanguage` structure is used to represent a language. `PangoLanguage` pointers can be efficiently copied and compared with each other. Get a string that is representative of the characters needed to render a particular language. The sample text may be a pangram, but is not necessarily. It is chosen to be demonstrative of normal text in the language, as well as exposing font feature requirements unique to the language. It is suitable for use as sample text in a font selection dialog. If @language is %NULL, the default language as found by [func@Pango.Language.get_default] is used. If Pango does not have a sample string for @language, the classic "The quick brown fox..." is returned. This can be detected by comparing the returned pointer value to that returned for (non-existent) language code "xx". That is, compare to: ``` pango_language_get_sample_string (pango_language_from_string ("xx")) ``` the sample string a `PangoLanguage` Determines the scripts used to to write @language. If nothing is known about the language tag @language, or if @language is %NULL, then %NULL is returned. The list of scripts returned starts with the script that the language uses most and continues to the one it uses least. The value @num_script points at will be set to the number of scripts in the returned array (or zero if %NULL is returned). Most languages use only one script for writing, but there are some that use two (Latin and Cyrillic for example), and a few use three (Japanese for example). Applications should not make any assumptions on the maximum number of scripts returned though, except that it is positive if the return value is not %NULL, and it is a small number. The [method@Pango.Language.includes_script] function uses this function internally. Note: while the return value is declared as `PangoScript`, the returned values are from the `GUnicodeScript` enumeration, which may have more values. Callers need to handle unknown values. An array of `PangoScript` values, with the number of entries in the array stored in @num_scripts, or %NULL if Pango does not have any information about this particular language tag (also the case if @language is %NULL). a `PangoLanguage` location to return number of scripts Determines if @script is one of the scripts used to write @language. The returned value is conservative; if nothing is known about the language tag @language, %TRUE will be returned, since, as far as Pango knows, @script might be used to write @language. This routine is used in Pango's itemization process when determining if a supplied language tag is relevant to a particular section of text. It probably is not useful for applications in most circumstances. This function uses [method@Pango.Language.get_scripts] internally. %TRUE if @script is one of the scripts used to write @language or if nothing is known about @language (including the case that @language is %NULL), %FALSE otherwise. a `PangoLanguage` a `PangoScript` Checks if a language tag matches one of the elements in a list of language ranges. A language tag is considered to match a range in the list if the range is '*', the range is exactly the tag, or the range is a prefix of the tag, and the character after it in the tag is '-'. %TRUE if a match was found a language tag (see [func@Pango.Language.from_string]), %NULL is allowed and matches nothing but '*' a list of language ranges, separated by ';', ':', ',', or space characters. Each element must either be '*', or a RFC 3066 language range canonicalized as by [func@Pango.Language.from_string] Gets the RFC-3066 format string representing the given language tag. Returns (transfer none): a string representing the language tag a language tag. Convert a language tag to a `PangoLanguage`. The language tag must be in a RFC-3066 format. `PangoLanguage` pointers can be efficiently copied (copy the pointer) and compared with other language tags (compare the pointer.) This function first canonicalizes the string by converting it to lowercase, mapping '_' to '-', and stripping all characters other than letters and '-'. Use [func@Pango.Language.get_default] if you want to get the `PangoLanguage` for the current locale of the process. a `PangoLanguage` a string representing a language tag Returns the `PangoLanguage` for the current locale of the process. On Unix systems, this is the return value is derived from `setlocale (LC_CTYPE, NULL)`, and the user can affect this through the environment variables LC_ALL, LC_CTYPE or LANG (checked in that order). The locale string typically is in the form lang_COUNTRY, where lang is an ISO-639 language code, and COUNTRY is an ISO-3166 country code. For instance, sv_FI for Swedish as written in Finland or pt_BR for Portuguese as written in Brazil. On Windows, the C library does not use any such environment variables, and setting them won't affect the behavior of functions like ctime(). The user sets the locale through the Regional Options in the Control Panel. The C library (in the setlocale() function) does not use country and language codes, but country and language names spelled out in English. However, this function does check the above environment variables, and does return a Unix-style locale string based on either said environment variables or the thread's current locale. Your application should call `setlocale(LC_ALL, "")` for the user settings to take effect. GTK does this in its initialization functions automatically (by calling gtk_set_locale()). See the setlocale() manpage for more details. Note that the default language can change over the life of an application. Also note that this function will not do the right thing if you use per-thread locales with uselocale(). In that case, you should just call pango_language_from_string() yourself. the default language as a `PangoLanguage` Returns the list of languages that the user prefers. The list is specified by the `PANGO_LANGUAGE` or `LANGUAGE` environment variables, in order of preference. Note that this list does not necessarily include the language returned by [func@Pango.Language.get_default]. When choosing language-specific resources, such as the sample text returned by [method@Pango.Language.get_sample_string], you should first try the default language, followed by the languages returned by this function. a %NULL-terminated array of `PangoLanguage`* A `PangoLayout` structure represents an entire paragraph of text. While complete access to the layout capabilities of Pango is provided using the detailed interfaces for itemization and shaping, using that functionality directly involves writing a fairly large amount of code. `PangoLayout` provides a high-level driver for formatting entire paragraphs of text at once. This includes paragraph-level functionality such as line breaking, justification, alignment and ellipsization. A `PangoLayout` is initialized with a `PangoContext`, UTF-8 string and set of attributes for that string. Once that is done, the set of formatted lines can be extracted from the object, the layout can be rendered, and conversion between logical character positions within the layout's text, and the physical position of the resulting glyphs can be made. There are a number of parameters to adjust the formatting of a `PangoLayout`. The following image shows adjustable parameters (on the left) and font metrics (on the right): <picture> <source srcset="layout-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Pango Layout Parameters" src="layout-light.png"> </picture> The following images demonstrate the effect of alignment and justification on the layout of text: | | | | --- | --- | | ![align=left](align-left.png) | ![align=left, justify](align-left-justify.png) | | ![align=center](align-center.png) | ![align=center, justify](align-center-justify.png) | | ![align=right](align-right.png) | ![align=right, justify](align-right-justify.png) | It is possible, as well, to ignore the 2-D setup, and simply treat the results of a `PangoLayout` as a list of lines. Create a new `PangoLayout` object with attributes initialized to default values for a particular `PangoContext`. the newly allocated `PangoLayout` a `PangoContext` Loads data previously created via [method@Pango.Layout.serialize]. For a discussion of the supported format, see that function. Note: to verify that the returned layout is identical to the one that was serialized, you can compare @bytes to the result of serializing the layout again. a new `PangoLayout` a `PangoContext` the bytes containing the data `PangoLayoutDeserializeFlags` Forces recomputation of any state in the `PangoLayout` that might depend on the layout's context. This function should be called if you make changes to the context subsequent to creating the layout. a `PangoLayout` Creates a deep copy-by-value of the layout. The attribute list, tab array, and text from the original layout are all copied by value. the newly allocated `PangoLayout` a `PangoLayout` Gets the alignment for the layout: how partial lines are positioned within the horizontal space available. the alignment a `PangoLayout` Gets the attribute list for the layout, if any. a `PangoAttrList` a `PangoLayout` Gets whether to calculate the base direction for the layout according to its contents. See [method@Pango.Layout.set_auto_dir]. %TRUE if the bidirectional base direction is computed from the layout's contents, %FALSE otherwise a `PangoLayout` Gets the Y position of baseline of the first line in @layout. baseline of first line, from top of @layout a `PangoLayout` Given an index within a layout, determines the positions that of the strong and weak cursors if the insertion point is at that index. This is a variant of [method@Pango.Layout.get_cursor_pos] that applies font metric information about caret slope and offset to the positions it returns. <picture> <source srcset="caret-metrics-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Caret metrics" src="caret-metrics-light.png"> </picture> a `PangoLayout` the byte index of the cursor location to store the strong cursor position location to store the weak cursor position Returns the number of Unicode characters in the the text of @layout. the number of Unicode characters in the text of @layout a `PangoLayout` Retrieves the `PangoContext` used for this layout. the `PangoContext` for the layout a `PangoLayout` Given an index within a layout, determines the positions that of the strong and weak cursors if the insertion point is at that index. The position of each cursor is stored as a zero-width rectangle with the height of the run extents. <picture> <source srcset="cursor-positions-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Cursor positions" src="cursor-positions-light.png"> </picture> The strong cursor location is the location where characters of the directionality equal to the base direction of the layout are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the layout are inserted. The following example shows text with both a strong and a weak cursor. <picture> <source srcset="split-cursor-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Strong and weak cursors" src="split-cursor-light.png"> </picture> The strong cursor has a little arrow pointing to the right, the weak cursor to the left. Typing a 'c' in this situation will insert the character after the 'b', and typing another Hebrew character, like 'ג', will insert it at the end. a `PangoLayout` the byte index of the cursor location to store the strong cursor position location to store the weak cursor position Gets the text direction at the given character position in @layout. the text direction at @index a `PangoLayout` the byte index of the char Gets the type of ellipsization being performed for @layout. See [method@Pango.Layout.set_ellipsize]. Use [method@Pango.Layout.is_ellipsized] to query whether any paragraphs were actually ellipsized. the current ellipsization mode for @layout a `PangoLayout` Computes the logical and ink extents of @layout. Logical extents are usually what you want for positioning things. Note that both extents may have non-zero x and y. You may want to use those to offset where you render the layout. Not doing that is a very typical bug that shows up as right-to-left layouts not being correctly positioned in a layout with a set width. The extents are given in layout coordinates and in Pango units; layout coordinates begin at the top left corner of the layout. a `PangoLayout` rectangle used to store the extents of the layout as drawn rectangle used to store the logical extents of the layout Gets the font description for the layout, if any. a pointer to the layout's font description, or %NULL if the font description from the layout's context is inherited. a `PangoLayout` Gets the height of layout used for ellipsization. See [method@Pango.Layout.set_height] for details. the height, in Pango units if positive, or number of lines if negative. a `PangoLayout` Gets the paragraph indent width in Pango units. A negative value indicates a hanging indentation. the indent in Pango units a `PangoLayout` Returns an iterator to iterate over the visual extents of the layout. the new `PangoLayoutIter` a `PangoLayout` Gets whether each complete line should be stretched to fill the entire width of the layout. the justify value a `PangoLayout` Gets whether the last line should be stretched to fill the entire width of the layout. the justify value a `PangoLayout` Retrieves a particular line from a `PangoLayout`. Use the faster [method@Pango.Layout.get_line_readonly] if you do not plan to modify the contents of the line (glyphs, glyph widths, etc.). the requested `PangoLayoutLine`, or %NULL if the index is out of range. This layout line can be ref'ed and retained, but will become invalid if changes are made to the `PangoLayout`. a `PangoLayout` the index of a line, which must be between 0 and `pango_layout_get_line_count(layout) - 1`, inclusive. Retrieves the count of lines for the @layout. the line count `PangoLayout` Retrieves a particular line from a `PangoLayout`. This is a faster alternative to [method@Pango.Layout.get_line], but the user is not expected to modify the contents of the line (glyphs, glyph widths, etc.). the requested `PangoLayoutLine`, or %NULL if the index is out of range. This layout line can be ref'ed and retained, but will become invalid if changes are made to the `PangoLayout`. No changes should be made to the line. a `PangoLayout` the index of a line, which must be between 0 and `pango_layout_get_line_count(layout) - 1`, inclusive. Gets the line spacing factor of @layout. See [method@Pango.Layout.set_line_spacing]. a `PangoLayout` Returns the lines of the @layout as a list. Use the faster [method@Pango.Layout.get_lines_readonly] if you do not plan to modify the contents of the lines (glyphs, glyph widths, etc.). a `GSList` containing the lines in the layout. This points to internal data of the `PangoLayout` and must be used with care. It will become invalid on any change to the layout's text or properties. a `PangoLayout` Returns the lines of the @layout as a list. This is a faster alternative to [method@Pango.Layout.get_lines], but the user is not expected to modify the contents of the lines (glyphs, glyph widths, etc.). a `GSList` containing the lines in the layout. This points to internal data of the `PangoLayout` and must be used with care. It will become invalid on any change to the layout's text or properties. No changes should be made to the lines. a `PangoLayout` Retrieves an array of logical attributes for each character in the @layout. a `PangoLayout` location to store a pointer to an array of logical attributes. This value must be freed with g_free(). location to store the number of the attributes in the array. (The stored value will be one more than the total number of characters in the layout, since there need to be attributes corresponding to both the position before the first character and the position after the last character.) Retrieves an array of logical attributes for each character in the @layout. This is a faster alternative to [method@Pango.Layout.get_log_attrs]. The returned array is part of @layout and must not be modified. Modifying the layout will invalidate the returned array. The number of attributes returned in @n_attrs will be one more than the total number of characters in the layout, since there need to be attributes corresponding to both the position before the first character and the position after the last character. an array of logical attributes a `PangoLayout` location to store the number of the attributes in the array Computes the logical and ink extents of @layout in device units. This function just calls [method@Pango.Layout.get_extents] followed by two [func@extents_to_pixels] calls, rounding @ink_rect and @logical_rect such that the rounded rectangles fully contain the unrounded one (that is, passes them as first argument to [func@Pango.extents_to_pixels]). a `PangoLayout` rectangle used to store the extents of the layout as drawn rectangle used to store the logical extents of the layout Determines the logical width and height of a `PangoLayout` in device units. [method@Pango.Layout.get_size] returns the width and height scaled by %PANGO_SCALE. This is simply a convenience function around [method@Pango.Layout.get_pixel_extents]. a `PangoLayout` location to store the logical width location to store the logical height Returns the current serial number of @layout. The serial number is initialized to an small number larger than zero when a new layout is created and is increased whenever the layout is changed using any of the setter functions, or the `PangoContext` it uses has changed. The serial may wrap, but will never have the value 0. Since it can wrap, never compare it with "less than", always use "not equals". This can be used to automatically detect changes to a `PangoLayout`, and is useful for example to decide whether a layout needs redrawing. To force the serial to be increased, use [method@Pango.Layout.context_changed]. The current serial number of @layout. a `PangoLayout` Obtains whether @layout is in single paragraph mode. See [method@Pango.Layout.set_single_paragraph_mode]. %TRUE if the layout does not break paragraphs at paragraph separator characters, %FALSE otherwise a `PangoLayout` Determines the logical width and height of a `PangoLayout` in Pango units. This is simply a convenience function around [method@Pango.Layout.get_extents]. a `PangoLayout` location to store the logical width location to store the logical height Gets the amount of spacing between the lines of the layout. the spacing in Pango units a `PangoLayout` Gets the current `PangoTabArray` used by this layout. If no `PangoTabArray` has been set, then the default tabs are in use and %NULL is returned. Default tabs are every 8 spaces. The return value should be freed with [method@Pango.TabArray.free]. a copy of the tabs for this layout a `PangoLayout` Gets the text in the layout. The returned text should not be freed or modified. the text in the @layout a `PangoLayout` Counts the number of unknown glyphs in @layout. This function can be used to determine if there are any fonts available to render all characters in a certain string, or when used in combination with %PANGO_ATTR_FALLBACK, to check if a certain font supports all the characters in the string. The number of unknown glyphs in @layout a `PangoLayout` Gets the width to which the lines of the `PangoLayout` should wrap. the width in Pango units, or -1 if no width set. a `PangoLayout` Gets the wrap mode for the layout. Use [method@Pango.Layout.is_wrapped] to query whether any paragraphs were actually wrapped. active wrap mode. a `PangoLayout` Converts from byte @index_ within the @layout to line and X position. The X position is measured from the left edge of the line. a `PangoLayout` the byte index of a grapheme within the layout an integer indicating the edge of the grapheme to retrieve the position of. If > 0, the trailing edge of the grapheme, if 0, the leading of the grapheme location to store resulting line index. (which will between 0 and pango_layout_get_line_count(layout) - 1) location to store resulting position within line (%PANGO_SCALE units per device unit) Converts from an index within a `PangoLayout` to the onscreen position corresponding to the grapheme at that index. The returns is represented as rectangle. Note that `pos->x` is always the leading edge of the grapheme and `pos->x + pos->width` the trailing edge of the grapheme. If the directionality of the grapheme is right-to-left, then `pos->width` will be negative. a `PangoLayout` byte index within @layout rectangle in which to store the position of the grapheme Queries whether the layout had to ellipsize any paragraphs. This returns %TRUE if the ellipsization mode for @layout is not %PANGO_ELLIPSIZE_NONE, a positive width is set on @layout, and there are paragraphs exceeding that width that have to be ellipsized. %TRUE if any paragraphs had to be ellipsized, %FALSE otherwise a `PangoLayout` Queries whether the layout had to wrap any paragraphs. This returns %TRUE if a positive width is set on @layout, and there are paragraphs exceeding the layout width that have to be wrapped. %TRUE if any paragraphs had to be wrapped, %FALSE otherwise a `PangoLayout` Computes a new cursor position from an old position and a direction. If @direction is positive, then the new position will cause the strong or weak cursor to be displayed one position to right of where it was with the old cursor position. If @direction is negative, it will be moved to the left. In the presence of bidirectional text, the correspondence between logical and visual order will depend on the direction of the current run, and there may be jumps when the cursor is moved off of the end of a run. Motion here is in cursor positions, not in characters, so a single call to this function may move the cursor over multiple characters when multiple characters combine to form a single grapheme. a `PangoLayout` whether the moving cursor is the strong cursor or the weak cursor. The strong cursor is the cursor corresponding to text insertion in the base direction for the layout. the byte index of the current cursor position if 0, the cursor was at the leading edge of the grapheme indicated by @old_index, if > 0, the cursor was at the trailing edge. direction to move cursor. A negative value indicates motion to the left location to store the new cursor byte index. A value of -1 indicates that the cursor has been moved off the beginning of the layout. A value of %G_MAXINT indicates that the cursor has been moved off the end of the layout. number of characters to move forward from the location returned for @new_index to get the position where the cursor should be displayed. This allows distinguishing the position at the beginning of one line from the position at the end of the preceding line. @new_index is always on the line where the cursor should be displayed. Serializes the @layout for later deserialization via [func@Pango.Layout.deserialize]. There are no guarantees about the format of the output across different versions of Pango and [func@Pango.Layout.deserialize] will reject data that it cannot parse. The intended use of this function is testing, benchmarking and debugging. The format is not meant as a permanent storage format. a `GBytes` containing the serialized form of @layout a `PangoLayout` `PangoLayoutSerializeFlags` Sets the alignment for the layout: how partial lines are positioned within the horizontal space available. The default alignment is %PANGO_ALIGN_LEFT. a `PangoLayout` the alignment Sets the text attributes for a layout object. References @attrs, so the caller can unref its reference. a `PangoLayout` a `PangoAttrList` Sets whether to calculate the base direction for the layout according to its contents. When this flag is on (the default), then paragraphs in @layout that begin with strong right-to-left characters (Arabic and Hebrew principally), will have right-to-left layout, paragraphs with letters from other scripts will have left-to-right layout. Paragraphs with only neutral characters get their direction from the surrounding paragraphs. When %FALSE, the choice between left-to-right and right-to-left layout is done according to the base direction of the layout's `PangoContext`. (See [method@Pango.Context.set_base_dir]). When the auto-computed direction of a paragraph differs from the base direction of the context, the interpretation of %PANGO_ALIGN_LEFT and %PANGO_ALIGN_RIGHT are swapped. a `PangoLayout` if %TRUE, compute the bidirectional base direction from the layout's contents Sets the type of ellipsization being performed for @layout. Depending on the ellipsization mode @ellipsize text is removed from the start, middle, or end of text so they fit within the width and height of layout set with [method@Pango.Layout.set_width] and [method@Pango.Layout.set_height]. If the layout contains characters such as newlines that force it to be layed out in multiple paragraphs, then whether each paragraph is ellipsized separately or the entire layout is ellipsized as a whole depends on the set height of the layout. The default value is %PANGO_ELLIPSIZE_NONE. See [method@Pango.Layout.set_height] for details. a `PangoLayout` the new ellipsization mode for @layout Sets the default font description for the layout. If no font description is set on the layout, the font description from the layout's context is used. a `PangoLayout` the new `PangoFontDescription` to unset the current font description Sets the height to which the `PangoLayout` should be ellipsized at. There are two different behaviors, based on whether @height is positive or negative. If @height is positive, it will be the maximum height of the layout. Only lines would be shown that would fit, and if there is any text omitted, an ellipsis added. At least one line is included in each paragraph regardless of how small the height value is. A value of zero will render exactly one line for the entire layout. If @height is negative, it will be the (negative of) maximum number of lines per paragraph. That is, the total number of lines shown may well be more than this value if the layout contains multiple paragraphs of text. The default value of -1 means that the first line of each paragraph is ellipsized. This behavior may be changed in the future to act per layout instead of per paragraph. File a bug against pango at [https://gitlab.gnome.org/gnome/pango](https://gitlab.gnome.org/gnome/pango) if your code relies on this behavior. Height setting only has effect if a positive width is set on @layout and ellipsization mode of @layout is not %PANGO_ELLIPSIZE_NONE. The behavior is undefined if a height other than -1 is set and ellipsization mode is set to %PANGO_ELLIPSIZE_NONE, and may change in the future. a `PangoLayout`. the desired height of the layout in Pango units if positive, or desired number of lines if negative. Sets the width in Pango units to indent each paragraph. A negative value of @indent will produce a hanging indentation. That is, the first line will have the full width, and subsequent lines will be indented by the absolute value of @indent. The indent setting is ignored if layout alignment is set to %PANGO_ALIGN_CENTER. The default value is 0. a `PangoLayout` the amount by which to indent Sets whether each complete line should be stretched to fill the entire width of the layout. Stretching is typically done by adding whitespace, but for some scripts (such as Arabic), the justification may be done in more complex ways, like extending the characters. Note that this setting is not implemented and so is ignored in Pango older than 1.18. Note that tabs and justification conflict with each other: Justification will move content away from its tab-aligned positions. The default value is %FALSE. Also see [method@Pango.Layout.set_justify_last_line]. a `PangoLayout` whether the lines in the layout should be justified Sets whether the last line should be stretched to fill the entire width of the layout. This only has an effect if [method@Pango.Layout.set_justify] has been called as well. The default value is %FALSE. a `PangoLayout` whether the last line in the layout should be justified Sets a factor for line spacing. Typical values are: 0, 1, 1.5, 2. The default values is 0. If @factor is non-zero, lines are placed so that baseline2 = baseline1 + factor * height2 where height2 is the line height of the second line (as determined by the font(s)). In this case, the spacing set with [method@Pango.Layout.set_spacing] is ignored. If @factor is zero (the default), spacing is applied as before. Note: for semantics that are closer to the CSS line-height property, see [func@Pango.attr_line_height_new]. a `PangoLayout` the new line spacing factor Sets the layout text and attribute list from marked-up text. See [Pango Markup](pango_markup.html)). Replaces the current text and attribute list. This is the same as [method@Pango.Layout.set_markup_with_accel], but the markup text isn't scanned for accelerators. a `PangoLayout` marked-up text length of marked-up text in bytes, or -1 if @markup is `NUL`-terminated Sets the layout text and attribute list from marked-up text. See [Pango Markup](pango_markup.html)). Replaces the current text and attribute list. If @accel_marker is nonzero, the given character will mark the character following it as an accelerator. For example, @accel_marker might be an ampersand or underscore. All characters marked as an accelerator will receive a %PANGO_UNDERLINE_LOW attribute, and the first character so marked will be returned in @accel_char. Two @accel_marker characters following each other produce a single literal @accel_marker character. a `PangoLayout` marked-up text (see [Pango Markup](pango_markup.html)) length of marked-up text in bytes, or -1 if @markup is `NUL`-terminated marker for accelerators in the text return location for first located accelerator Sets the single paragraph mode of @layout. If @setting is %TRUE, do not treat newlines and similar characters as paragraph separators; instead, keep all text in a single paragraph, and display a glyph for paragraph separator characters. Used when you want to allow editing of newlines on a single text line. The default value is %FALSE. a `PangoLayout` new setting Sets the amount of spacing in Pango units between the lines of the layout. When placing lines with spacing, Pango arranges things so that line2.top = line1.bottom + spacing The default value is 0. Note: Since 1.44, Pango is using the line height (as determined by the font) for placing lines when the line spacing factor is set to a non-zero value with [method@Pango.Layout.set_line_spacing]. In that case, the @spacing set with this function is ignored. Note: for semantics that are closer to the CSS line-height property, see [func@Pango.attr_line_height_new]. a `PangoLayout` the amount of spacing Sets the tabs to use for @layout, overriding the default tabs. `PangoLayout` will place content at the next tab position whenever it meets a Tab character (U+0009). By default, tabs are every 8 spaces. If @tabs is %NULL, the default tabs are reinstated. @tabs is copied into the layout; you must free your copy of @tabs yourself. Note that tabs and justification conflict with each other: Justification will move content away from its tab-aligned positions. The same is true for alignments other than %PANGO_ALIGN_LEFT. a `PangoLayout` a `PangoTabArray` Sets the text of the layout. This function validates @text and renders invalid UTF-8 with a placeholder glyph. Note that if you have used [method@Pango.Layout.set_markup] or [method@Pango.Layout.set_markup_with_accel] on @layout before, you may want to call [method@Pango.Layout.set_attributes] to clear the attributes set on the layout from the markup as this function does not clear attributes. a `PangoLayout` the text maximum length of @text, in bytes. -1 indicates that the string is nul-terminated and the length should be calculated. The text will also be truncated on encountering a nul-termination even when @length is positive. Sets the width to which the lines of the `PangoLayout` should wrap or get ellipsized. The default value is -1: no width set. a `PangoLayout`. the desired width in Pango units, or -1 to indicate that no wrapping or ellipsization should be performed. Sets the wrap mode. The wrap mode only has effect if a width is set on the layout with [method@Pango.Layout.set_width]. To turn off wrapping, set the width to -1. The default value is %PANGO_WRAP_WORD. a `PangoLayout` the wrap mode A convenience method to serialize a layout to a file. It is equivalent to calling [method@Pango.Layout.serialize] followed by [func@GLib.file_set_contents]. See those two functions for details on the arguments. It is mostly intended for use inside a debugger to quickly dump a layout to a file for later inspection. %TRUE if saving was successful a `PangoLayout` `PangoLayoutSerializeFlags` the file to save it to Converts from X and Y position within a layout to the byte index to the character at that logical position. If the Y position is not inside the layout, the closest position is chosen (the position will be clamped inside the layout). If the X position is not within the layout, then the start or the end of the line is chosen as described for [method@Pango.LayoutLine.x_to_index]. If either the X or Y positions were not inside the layout, then the function returns %FALSE; on an exact hit, it returns %TRUE. %TRUE if the coordinates were inside text, %FALSE otherwise a `PangoLayout` the X offset (in Pango units) from the left edge of the layout the Y offset (in Pango units) from the top edge of the layout location to store calculated byte index location to store a integer indicating where in the grapheme the user clicked. It will either be zero, or the number of characters in the grapheme. 0 represents the leading edge of the grapheme. Errors that can be returned by [func@Pango.Layout.deserialize]. Unspecified error A JSon value could not be interpreted A required JSon member was not found Flags that influence the behavior of [func@Pango.Layout.deserialize]. New members may be added to this enumeration over time. Default behavior Apply context information from the serialization to the `PangoContext` A `PangoLayoutIter` can be used to iterate over the visual extents of a `PangoLayout`. To obtain a `PangoLayoutIter`, use [method@Pango.Layout.get_iter]. The `PangoLayoutIter` structure is opaque, and has no user-visible fields. Determines whether @iter is on the last line of the layout. %TRUE if @iter is on the last line a `PangoLayoutIter` Copies a `PangoLayoutIter`. the newly allocated `PangoLayoutIter` a `PangoLayoutIter` Frees an iterator that's no longer in use. a `PangoLayoutIter`, may be %NULL Gets the Y position of the current line's baseline, in layout coordinates. Layout coordinates have the origin at the top left of the entire layout. baseline of current line a `PangoLayoutIter` Gets the extents of the current character, in layout coordinates. Layout coordinates have the origin at the top left of the entire layout. Only logical extents can sensibly be obtained for characters; ink extents make sense only down to the level of clusters. a `PangoLayoutIter` rectangle to fill with logical extents Gets the extents of the current cluster, in layout coordinates. Layout coordinates have the origin at the top left of the entire layout. a `PangoLayoutIter` rectangle to fill with ink extents rectangle to fill with logical extents Gets the current byte index. Note that iterating forward by char moves in visual order, not logical order, so indexes may not be sequential. Also, the index may be equal to the length of the text in the layout, if on the %NULL run (see [method@Pango.LayoutIter.get_run]). current byte index a `PangoLayoutIter` Gets the layout associated with a `PangoLayoutIter`. the layout associated with @iter a `PangoLayoutIter` Obtains the extents of the `PangoLayout` being iterated over. a `PangoLayoutIter` rectangle to fill with ink extents rectangle to fill with logical extents Gets the current line. Use the faster [method@Pango.LayoutIter.get_line_readonly] if you do not plan to modify the contents of the line (glyphs, glyph widths, etc.). the current line a `PangoLayoutIter` Obtains the extents of the current line. Extents are in layout coordinates (origin is the top-left corner of the entire `PangoLayout`). Thus the extents returned by this function will be the same width/height but not at the same x/y as the extents returned from [method@Pango.LayoutLine.get_extents]. a `PangoLayoutIter` rectangle to fill with ink extents rectangle to fill with logical extents Gets the current line for read-only access. This is a faster alternative to [method@Pango.LayoutIter.get_line], but the user is not expected to modify the contents of the line (glyphs, glyph widths, etc.). the current line, that should not be modified a `PangoLayoutIter` Divides the vertical space in the `PangoLayout` being iterated over between the lines in the layout, and returns the space belonging to the current line. A line's range includes the line's logical extents. plus half of the spacing above and below the line, if [method@Pango.Layout.set_spacing] has been called to set layout spacing. The Y positions are in layout coordinates (origin at top left of the entire layout). Note: Since 1.44, Pango uses line heights for placing lines, and there may be gaps between the ranges returned by this function. a `PangoLayoutIter` start of line end of line Gets the current run. When iterating by run, at the end of each line, there's a position with a %NULL run, so this function can return %NULL. The %NULL run at the end of each line ensures that all lines have at least one run, even lines consisting of only a newline. Use the faster [method@Pango.LayoutIter.get_run_readonly] if you do not plan to modify the contents of the run (glyphs, glyph widths, etc.). the current run a `PangoLayoutIter` Gets the Y position of the current run's baseline, in layout coordinates. Layout coordinates have the origin at the top left of the entire layout. The run baseline can be different from the line baseline, for example due to superscript or subscript positioning. a `PangoLayoutIter` Gets the extents of the current run in layout coordinates. Layout coordinates have the origin at the top left of the entire layout. a `PangoLayoutIter` rectangle to fill with ink extents rectangle to fill with logical extents Gets the current run for read-only access. When iterating by run, at the end of each line, there's a position with a %NULL run, so this function can return %NULL. The %NULL run at the end of each line ensures that all lines have at least one run, even lines consisting of only a newline. This is a faster alternative to [method@Pango.LayoutIter.get_run], but the user is not expected to modify the contents of the run (glyphs, glyph widths, etc.). the current run, that should not be modified a `PangoLayoutIter` Moves @iter forward to the next character in visual order. If @iter was already at the end of the layout, returns %FALSE. whether motion was possible a `PangoLayoutIter` Moves @iter forward to the next cluster in visual order. If @iter was already at the end of the layout, returns %FALSE. whether motion was possible a `PangoLayoutIter` Moves @iter forward to the start of the next line. If @iter is already on the last line, returns %FALSE. whether motion was possible a `PangoLayoutIter` Moves @iter forward to the next run in visual order. If @iter was already at the end of the layout, returns %FALSE. whether motion was possible a `PangoLayoutIter` A `PangoLayoutLine` represents one of the lines resulting from laying out a paragraph via `PangoLayout`. `PangoLayoutLine` structures are obtained by calling [method@Pango.Layout.get_line] and are only valid until the text, attributes, or settings of the parent `PangoLayout` are modified. the layout this line belongs to, might be %NULL start of line as byte index into layout->text length of line in bytes list of runs in the line, from left to right #TRUE if this is the first line of the paragraph #Resolved PangoDirection of line Computes the logical and ink extents of a layout line. See [method@Pango.Font.get_glyph_extents] for details about the interpretation of the rectangles. a `PangoLayoutLine` rectangle used to store the extents of the glyph string as drawn rectangle used to store the logical extents of the glyph string Computes the height of the line, as the maximum of the heights of fonts used in this line. Note that the actual baseline-to-baseline distance between lines of text is influenced by other factors, such as [method@Pango.Layout.set_spacing] and [method@Pango.Layout.set_line_spacing]. a `PangoLayoutLine` return location for the line height Returns the length of the line, in bytes. the length of the line a `PangoLayoutLine` Computes the logical and ink extents of @layout_line in device units. This function just calls [method@Pango.LayoutLine.get_extents] followed by two [func@extents_to_pixels] calls, rounding @ink_rect and @logical_rect such that the rounded rectangles fully contain the unrounded one (that is, passes them as first argument to [func@extents_to_pixels]). a `PangoLayoutLine` rectangle used to store the extents of the glyph string as drawn rectangle used to store the logical extents of the glyph string Returns the resolved direction of the line. the resolved direction of the line a `PangoLayoutLine` Returns the start index of the line, as byte index into the text of the layout. the start index of the line a `PangoLayoutLine` Gets a list of visual ranges corresponding to a given logical range. This list is not necessarily minimal - there may be consecutive ranges which are adjacent. The ranges will be sorted from left to right. The ranges are with respect to the left edge of the entire layout, not with respect to the line. a `PangoLayoutLine` Start byte index of the logical range. If this value is less than the start index for the line, then the first range will extend all the way to the leading edge of the layout. Otherwise, it will start at the leading edge of the first character. Ending byte index of the logical range. If this value is greater than the end index for the line, then the last range will extend all the way to the trailing edge of the layout. Otherwise, it will end at the trailing edge of the last character. location to store a pointer to an array of ranges. The array will be of length `2*n_ranges`, with each range starting at `(*ranges)[2*n]` and of width `(*ranges)[2*n + 1] - (*ranges)[2*n]`. This array must be freed with g_free(). The coordinates are relative to the layout and are in Pango units. The number of ranges stored in @ranges Converts an index within a line to a X position. a `PangoLayoutLine` byte offset of a grapheme within the layout an integer indicating the edge of the grapheme to retrieve the position of. If > 0, the trailing edge of the grapheme, if 0, the leading of the grapheme location to store the x_offset (in Pango units) Returns whether this is the first line of the paragraph. %TRUE if this is the first line a `PangoLayoutLine` Increase the reference count of a `PangoLayoutLine` by one. the line passed in. a `PangoLayoutLine` Decrease the reference count of a `PangoLayoutLine` by one. If the result is zero, the line and all associated memory will be freed. a `PangoLayoutLine` Converts from x offset to the byte index of the corresponding character within the text of the layout. If @x_pos is outside the line, @index_ and @trailing will point to the very first or very last position in the line. This determination is based on the resolved direction of the paragraph; for example, if the resolved direction is right-to-left, then an X position to the right of the line (after it) results in 0 being stored in @index_ and @trailing. An X position to the left of the line results in @index_ pointing to the (logical) last grapheme in the line and @trailing being set to the number of characters in that grapheme. The reverse is true for a left-to-right line. %FALSE if @x_pos was outside the line, %TRUE if inside a `PangoLayoutLine` the X offset (in Pango units) from the left edge of the line. location to store calculated byte index for the grapheme in which the user clicked location to store an integer indicating where in the grapheme the user clicked. It will either be zero, or the number of characters in the grapheme. 0 represents the leading edge of the grapheme. Flags that influence the behavior of [method@Pango.Layout.serialize]. New members may be added to this enumeration over time. Default behavior Include context information Include information about the formatted output The `PangoLogAttr` structure stores information about the attributes of a single character. if set, can break line in front of character if set, must break line in front of character if set, can break here when doing character wrapping is whitespace character if set, cursor can appear in front of character. i.e. this is a grapheme boundary, or the first character in the text. This flag implements Unicode's [Grapheme Cluster Boundaries](http://www.unicode.org/reports/tr29/) semantics. is first character in a word is first non-word char after a word Note that in degenerate cases, you could have both @is_word_start and @is_word_end set for some character. is a sentence boundary. There are two ways to divide sentences. The first assigns all inter-sentence whitespace/control/format chars to some sentence, so all chars are in some sentence; @is_sentence_boundary denotes the boundaries there. The second way doesn't assign between-sentence spaces, etc. to any sentence, so @is_sentence_start/@is_sentence_end mark the boundaries of those sentences. is first character in a sentence is first char after a sentence. Note that in degenerate cases, you could have both @is_sentence_start and @is_sentence_end set for some character. (e.g. no space after a period, so the next sentence starts right away) if set, backspace deletes one character rather than the entire grapheme cluster. This field is only meaningful on grapheme boundaries (where @is_cursor_position is set). In some languages, the full grapheme (e.g. letter + diacritics) is considered a unit, while in others, each decomposed character in the grapheme is a unit. In the default implementation of [func@break], this bit is set on all grapheme boundaries except those following Latin, Cyrillic or Greek base characters. is a whitespace character that can possibly be expanded for justification purposes. (Since: 1.18) is a word boundary, as defined by UAX#29. More specifically, means that this is not a position in the middle of a word. For example, both sides of a punctuation mark are considered word boundaries. This flag is particularly useful when selecting text word-by-word. This flag implements Unicode's [Word Boundaries](http://www.unicode.org/reports/tr29/) semantics. (Since: 1.22) when breaking lines before this char, insert a hyphen. Since: 1.50 when breaking lines before this char, remove the preceding char. Since 1.50 A `PangoMatrix` specifies a transformation between user-space and device coordinates. The transformation is given by ``` x_device = x_user * matrix->xx + y_user * matrix->xy + matrix->x0; y_device = x_user * matrix->yx + y_user * matrix->yy + matrix->y0; ``` 1st component of the transformation matrix 2nd component of the transformation matrix 3rd component of the transformation matrix 4th component of the transformation matrix x translation y translation Changes the transformation represented by @matrix to be the transformation given by first applying transformation given by @new_matrix then applying the original transformation. a `PangoMatrix` a `PangoMatrix` Copies a `PangoMatrix`. the newly allocated `PangoMatrix` a `PangoMatrix` Free a `PangoMatrix`. a `PangoMatrix`, may be %NULL Returns the scale factor of a matrix on the height of the font. That is, the scale factor in the direction perpendicular to the vector that the X coordinate is mapped to. If the scale in the X coordinate is needed as well, use [method@Pango.Matrix.get_font_scale_factors]. the scale factor of @matrix on the height of the font, or 1.0 if @matrix is %NULL. a `PangoMatrix`, may be %NULL Calculates the scale factor of a matrix on the width and height of the font. That is, @xscale is the scale factor in the direction of the X coordinate, and @yscale is the scale factor in the direction perpendicular to the vector that the X coordinate is mapped to. Note that output numbers will always be non-negative. a `PangoMatrix` output scale factor in the x direction output scale factor perpendicular to the x direction Gets the slant ratio of a matrix. For a simple shear matrix in the form: 1 λ 0 1 this is simply λ. the slant ratio of @matrix a `PangoMatrix` Changes the transformation represented by @matrix to be the transformation given by first rotating by @degrees degrees counter-clockwise then applying the original transformation. a `PangoMatrix` degrees to rotate counter-clockwise Changes the transformation represented by @matrix to be the transformation given by first scaling by @sx in the X direction and @sy in the Y direction then applying the original transformation. a `PangoMatrix` amount to scale by in X direction amount to scale by in Y direction Transforms the distance vector (@dx,@dy) by @matrix. This is similar to [method@Pango.Matrix.transform_point], except that the translation components of the transformation are ignored. The calculation of the returned vector is as follows: ``` dx2 = dx1 * xx + dy1 * xy; dy2 = dx1 * yx + dy1 * yy; ``` Affine transformations are position invariant, so the same vector always transforms to the same vector. If (@x1,@y1) transforms to (@x2,@y2) then (@x1+@dx1,@y1+@dy1) will transform to (@x1+@dx2,@y1+@dy2) for all values of @x1 and @x2. a `PangoMatrix` in/out X component of a distance vector in/out Y component of a distance vector First transforms the @rect using @matrix, then calculates the bounding box of the transformed rectangle. This function is useful for example when you want to draw a rotated @PangoLayout to an image buffer, and want to know how large the image should be and how much you should shift the layout when rendering. For better accuracy, you should use [method@Pango.Matrix.transform_rectangle] on original rectangle in Pango units and convert to pixels afterward using [func@extents_to_pixels]'s first argument. a `PangoMatrix` in/out bounding box in device units Transforms the point (@x, @y) by @matrix. a `PangoMatrix` in/out X position in/out Y position First transforms @rect using @matrix, then calculates the bounding box of the transformed rectangle. This function is useful for example when you want to draw a rotated @PangoLayout to an image buffer, and want to know how large the image should be and how much you should shift the layout when rendering. If you have a rectangle in device units (pixels), use [method@Pango.Matrix.transform_pixel_rectangle]. If you have the rectangle in Pango units and want to convert to transformed pixel bounding box, it is more accurate to transform it first (using this function) and pass the result to pango_extents_to_pixels(), first argument, for an inclusive rounded rectangle. However, there are valid reasons that you may want to convert to pixels first and then transform, for example when the transformed coordinates may overflow in Pango units (large matrix translation for example). a `PangoMatrix` in/out bounding box in Pango units Changes the transformation represented by @matrix to be the transformation given by first translating by (@tx, @ty) then applying the original transformation. a `PangoMatrix` amount to translate in the X direction amount to translate in the Y direction The `PangoOverline` enumeration is used to specify whether text should be overlined, and if so, the type of line. no overline should be drawn Draw a single line above the ink extents of the text being underlined. Converts a dimension to device units by rounding. a dimension in Pango units. Converts a dimension to device units by ceiling. a dimension in Pango units. Converts a dimension to device units by flooring. a dimension in Pango units. Extracts the *right bearing* from a `PangoRectangle` representing glyph extents. The right bearing is the distance from the horizontal origin to the farthest right point of the character. This is positive except for characters drawn completely to the left of the horizontal origin. a `PangoRectangle` The `PangoRectangle` structure represents a rectangle. `PangoRectangle` is frequently used to represent the logical or ink extents of a single glyph or section of text. (See, for instance, [method@Pango.Font.get_glyph_extents].) X coordinate of the left side of the rectangle. Y coordinate of the the top side of the rectangle. width of the rectangle. height of the rectangle. `PangoRenderPart` defines different items to render for such purposes as setting colors. the text itself the area behind the text underlines strikethrough lines overlines `PangoRenderer` is a base class for objects that can render text provided as `PangoGlyphString` or `PangoLayout`. By subclassing `PangoRenderer` and overriding operations such as @draw_glyphs and @draw_rectangle, renderers for particular font backends and destinations can be created. Do renderer-specific initialization before drawing Draw a squiggly line that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. The width of the underline is rounded to an integer number of up/down segments and the resulting rectangle is centered in the original rectangle. This should be called while @renderer is already active. Use [method@Pango.Renderer.activate] to activate a renderer. a `PangoRenderer` X coordinate of underline, in Pango units in user coordinate system Y coordinate of underline, in Pango units in user coordinate system width of underline, in Pango units in user coordinate system height of underline, in Pango units in user coordinate system Draws a single glyph with coordinates in device space. a `PangoRenderer` a `PangoFont` the glyph index of a single glyph X coordinate of left edge of baseline of glyph Y coordinate of left edge of baseline of glyph Draws the glyphs in @glyph_item with the specified `PangoRenderer`, embedding the text associated with the glyphs in the output if the output format supports it. This is useful for rendering text in PDF. Note that this method does not handle attributes in @glyph_item. If you want colors, shapes and lines handled automatically according to those attributes, you need to use pango_renderer_draw_layout_line() or pango_renderer_draw_layout(). Note that @text is the start of the text for layout, which is then indexed by `glyph_item->item->offset`. If @text is %NULL, this simply calls [method@Pango.Renderer.draw_glyphs]. The default implementation of this method simply falls back to [method@Pango.Renderer.draw_glyphs]. a `PangoRenderer` the UTF-8 text that @glyph_item refers to a `PangoGlyphItem` X position of left edge of baseline, in user space coordinates in Pango units Y position of left edge of baseline, in user space coordinates in Pango units Draws the glyphs in @glyphs with the specified `PangoRenderer`. a `PangoRenderer` a `PangoFont` a `PangoGlyphString` X position of left edge of baseline, in user space coordinates in Pango units. Y position of left edge of baseline, in user space coordinates in Pango units. Draws an axis-aligned rectangle in user space coordinates with the specified `PangoRenderer`. This should be called while @renderer is already active. Use [method@Pango.Renderer.activate] to activate a renderer. a `PangoRenderer` type of object this rectangle is part of X position at which to draw rectangle, in user space coordinates in Pango units Y position at which to draw rectangle, in user space coordinates in Pango units width of rectangle in Pango units height of rectangle in Pango units draw content for a glyph shaped with `PangoAttrShape` @x, @y are the coordinates of the left edge of the baseline, in user coordinates. Draws a trapezoid with the parallel sides aligned with the X axis using the given `PangoRenderer`; coordinates are in device space. a `PangoRenderer` type of object this trapezoid is part of Y coordinate of top of trapezoid X coordinate of left end of top of trapezoid X coordinate of right end of top of trapezoid Y coordinate of bottom of trapezoid X coordinate of left end of bottom of trapezoid X coordinate of right end of bottom of trapezoid Do renderer-specific cleanup after drawing Informs Pango that the way that the rendering is done for @part has changed. This should be called if the rendering changes in a way that would prevent multiple pieces being joined together into one drawing call. For instance, if a subclass of `PangoRenderer` was to add a stipple option for drawing underlines, it needs to call ``` pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE); ``` When the stipple changes or underlines with different stipples might be joined together. Pango automatically calls this for changes to colors. (See [method@Pango.Renderer.set_color]) a `PangoRenderer` the part for which rendering has changed. updates the renderer for a new run Does initial setup before rendering operations on @renderer. [method@Pango.Renderer.deactivate] should be called when done drawing. Calls such as [method@Pango.Renderer.draw_layout] automatically activate the layout before drawing on it. Calls to [method@Pango.Renderer.activate] and [method@Pango.Renderer.deactivate] can be nested and the renderer will only be initialized and deinitialized once. a `PangoRenderer` Cleans up after rendering operations on @renderer. See docs for [method@Pango.Renderer.activate]. a `PangoRenderer` Draw a squiggly line that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. The width of the underline is rounded to an integer number of up/down segments and the resulting rectangle is centered in the original rectangle. This should be called while @renderer is already active. Use [method@Pango.Renderer.activate] to activate a renderer. a `PangoRenderer` X coordinate of underline, in Pango units in user coordinate system Y coordinate of underline, in Pango units in user coordinate system width of underline, in Pango units in user coordinate system height of underline, in Pango units in user coordinate system Draws a single glyph with coordinates in device space. a `PangoRenderer` a `PangoFont` the glyph index of a single glyph X coordinate of left edge of baseline of glyph Y coordinate of left edge of baseline of glyph Draws the glyphs in @glyph_item with the specified `PangoRenderer`, embedding the text associated with the glyphs in the output if the output format supports it. This is useful for rendering text in PDF. Note that this method does not handle attributes in @glyph_item. If you want colors, shapes and lines handled automatically according to those attributes, you need to use pango_renderer_draw_layout_line() or pango_renderer_draw_layout(). Note that @text is the start of the text for layout, which is then indexed by `glyph_item->item->offset`. If @text is %NULL, this simply calls [method@Pango.Renderer.draw_glyphs]. The default implementation of this method simply falls back to [method@Pango.Renderer.draw_glyphs]. a `PangoRenderer` the UTF-8 text that @glyph_item refers to a `PangoGlyphItem` X position of left edge of baseline, in user space coordinates in Pango units Y position of left edge of baseline, in user space coordinates in Pango units Draws the glyphs in @glyphs with the specified `PangoRenderer`. a `PangoRenderer` a `PangoFont` a `PangoGlyphString` X position of left edge of baseline, in user space coordinates in Pango units. Y position of left edge of baseline, in user space coordinates in Pango units. Draws @layout with the specified `PangoRenderer`. This is equivalent to drawing the lines of the layout, at their respective positions relative to @x, @y. a `PangoRenderer` a `PangoLayout` X position of left edge of baseline, in user space coordinates in Pango units. Y position of left edge of baseline, in user space coordinates in Pango units. Draws @line with the specified `PangoRenderer`. This draws the glyph items that make up the line, as well as shapes, backgrounds and lines that are specified by the attributes of those items. a `PangoRenderer` a `PangoLayoutLine` X position of left edge of baseline, in user space coordinates in Pango units. Y position of left edge of baseline, in user space coordinates in Pango units. Draws an axis-aligned rectangle in user space coordinates with the specified `PangoRenderer`. This should be called while @renderer is already active. Use [method@Pango.Renderer.activate] to activate a renderer. a `PangoRenderer` type of object this rectangle is part of X position at which to draw rectangle, in user space coordinates in Pango units Y position at which to draw rectangle, in user space coordinates in Pango units width of rectangle in Pango units height of rectangle in Pango units Draws a trapezoid with the parallel sides aligned with the X axis using the given `PangoRenderer`; coordinates are in device space. a `PangoRenderer` type of object this trapezoid is part of Y coordinate of top of trapezoid X coordinate of left end of top of trapezoid X coordinate of right end of top of trapezoid Y coordinate of bottom of trapezoid X coordinate of left end of bottom of trapezoid X coordinate of right end of bottom of trapezoid Gets the current alpha for the specified part. the alpha for the specified part, or 0 if it hasn't been set and should be inherited from the environment. a `PangoRenderer` the part to get the alpha for Gets the current rendering color for the specified part. the color for the specified part, or %NULL if it hasn't been set and should be inherited from the environment. a `PangoRenderer` the part to get the color for Gets the layout currently being rendered using @renderer. Calling this function only makes sense from inside a subclass's methods, like in its draw_shape vfunc, for example. The returned layout should not be modified while still being rendered. the layout, or %NULL if no layout is being rendered using @renderer at this time. a `PangoRenderer` Gets the layout line currently being rendered using @renderer. Calling this function only makes sense from inside a subclass's methods, like in its draw_shape vfunc, for example. The returned layout line should not be modified while still being rendered. the layout line, or %NULL if no layout line is being rendered using @renderer at this time. a `PangoRenderer` Gets the transformation matrix that will be applied when rendering. See [method@Pango.Renderer.set_matrix]. the matrix, or %NULL if no matrix has been set (which is the same as the identity matrix). The returned matrix is owned by Pango and must not be modified or freed. a `PangoRenderer` Informs Pango that the way that the rendering is done for @part has changed. This should be called if the rendering changes in a way that would prevent multiple pieces being joined together into one drawing call. For instance, if a subclass of `PangoRenderer` was to add a stipple option for drawing underlines, it needs to call ``` pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE); ``` When the stipple changes or underlines with different stipples might be joined together. Pango automatically calls this for changes to colors. (See [method@Pango.Renderer.set_color]) a `PangoRenderer` the part for which rendering has changed. Sets the alpha for part of the rendering. Note that the alpha may only be used if a color is specified for @part as well. a `PangoRenderer` the part to set the alpha for an alpha value between 1 and 65536, or 0 to unset the alpha Sets the color for part of the rendering. Also see [method@Pango.Renderer.set_alpha]. a `PangoRenderer` the part to change the color of the new color or %NULL to unset the current color Sets the transformation matrix that will be applied when rendering. a `PangoRenderer` a `PangoMatrix`, or %NULL to unset any existing matrix (No matrix set is the same as setting the identity matrix.) the current transformation matrix for the Renderer; may be %NULL, which should be treated the same as the identity matrix. Class structure for `PangoRenderer`. The following vfuncs take user space coordinates in Pango units and have default implementations: - draw_glyphs - draw_rectangle - draw_error_underline - draw_shape - draw_glyph_item The default draw_shape implementation draws nothing. The following vfuncs take device space coordinates as doubles and must be implemented: - draw_trapezoid - draw_glyph draws a `PangoGlyphString` a `PangoRenderer` a `PangoFont` a `PangoGlyphString` X position of left edge of baseline, in user space coordinates in Pango units. Y position of left edge of baseline, in user space coordinates in Pango units. draws a rectangle a `PangoRenderer` type of object this rectangle is part of X position at which to draw rectangle, in user space coordinates in Pango units Y position at which to draw rectangle, in user space coordinates in Pango units width of rectangle in Pango units height of rectangle in Pango units draws a squiggly line that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. a `PangoRenderer` X coordinate of underline, in Pango units in user coordinate system Y coordinate of underline, in Pango units in user coordinate system width of underline, in Pango units in user coordinate system height of underline, in Pango units in user coordinate system draw content for a glyph shaped with `PangoAttrShape` @x, @y are the coordinates of the left edge of the baseline, in user coordinates. draws a trapezoidal filled area a `PangoRenderer` type of object this trapezoid is part of Y coordinate of top of trapezoid X coordinate of left end of top of trapezoid X coordinate of right end of top of trapezoid Y coordinate of bottom of trapezoid X coordinate of left end of bottom of trapezoid X coordinate of right end of bottom of trapezoid draws a single glyph a `PangoRenderer` a `PangoFont` the glyph index of a single glyph X coordinate of left edge of baseline of glyph Y coordinate of left edge of baseline of glyph do renderer specific processing when rendering attributes change a `PangoRenderer` the part for which rendering has changed. Do renderer-specific initialization before drawing Do renderer-specific cleanup after drawing updates the renderer for a new run draws a `PangoGlyphItem` a `PangoRenderer` the UTF-8 text that @glyph_item refers to a `PangoGlyphItem` X position of left edge of baseline, in user space coordinates in Pango units Y position of left edge of baseline, in user space coordinates in Pango units The scale between dimensions used for Pango distances and device units. The definition of device units is dependent on the output device; it will typically be pixels for a screen, and points for a printer. %PANGO_SCALE is currently 1024, but this may be changed in the future. When setting font sizes, device units are always considered to be points (as in "12 point font"), rather than pixels. The `PangoScript` enumeration identifies different writing systems. The values correspond to the names as defined in the Unicode standard. See [Unicode Standard Annex 24: Script names](http://www.unicode.org/reports/tr24/) Note that this enumeration is deprecated and will not be updated to include values in newer versions of the Unicode standard. Applications should use the [enum@GLib.UnicodeScript] enumeration instead, whose values are interchangeable with `PangoScript`. a value never returned from pango_script_for_unichar() a character used by multiple different scripts a mark glyph that takes its script from the base glyph to which it is attached Arabic Armenian Bengali Bopomofo Cherokee Coptic Cyrillic Deseret Devanagari Ethiopic Georgian Gothic Greek Gujarati Gurmukhi Han Hangul Hebrew Hiragana Kannada Katakana Khmer Lao Latin Malayalam Mongolian Myanmar Ogham Old Italic Oriya Runic Sinhala Syriac Tamil Telugu Thaana Thai Tibetan Canadian Aboriginal Yi Tagalog Hanunoo Buhid Tagbanwa Braille Cypriot Limbu Osmanya Shavian Linear B Tai Le Ugaritic New Tai Lue. Since 1.10 Buginese. Since 1.10 Glagolitic. Since 1.10 Tifinagh. Since 1.10 Syloti Nagri. Since 1.10 Old Persian. Since 1.10 Kharoshthi. Since 1.10 an unassigned code point. Since 1.14 Balinese. Since 1.14 Cuneiform. Since 1.14 Phoenician. Since 1.14 Phags-pa. Since 1.14 N'Ko. Since 1.14 Kayah Li. Since 1.20.1 Lepcha. Since 1.20.1 Rejang. Since 1.20.1 Sundanese. Since 1.20.1 Saurashtra. Since 1.20.1 Cham. Since 1.20.1 Ol Chiki. Since 1.20.1 Vai. Since 1.20.1 Carian. Since 1.20.1 Lycian. Since 1.20.1 Lydian. Since 1.20.1 Batak. Since 1.32 Brahmi. Since 1.32 Mandaic. Since 1.32 Chakma. Since: 1.32 Meroitic Cursive. Since: 1.32 Meroitic Hieroglyphs. Since: 1.32 Miao. Since: 1.32 Sharada. Since: 1.32 Sora Sompeng. Since: 1.32 Takri. Since: 1.32 Bassa. Since: 1.40 Caucasian Albanian. Since: 1.40 Duployan. Since: 1.40 Elbasan. Since: 1.40 Grantha. Since: 1.40 Kjohki. Since: 1.40 Khudawadi, Sindhi. Since: 1.40 Linear A. Since: 1.40 Mahajani. Since: 1.40 Manichaean. Since: 1.40 Mende Kikakui. Since: 1.40 Modi. Since: 1.40 Mro. Since: 1.40 Nabataean. Since: 1.40 Old North Arabian. Since: 1.40 Old Permic. Since: 1.40 Pahawh Hmong. Since: 1.40 Palmyrene. Since: 1.40 Pau Cin Hau. Since: 1.40 Psalter Pahlavi. Since: 1.40 Siddham. Since: 1.40 Tirhuta. Since: 1.40 Warang Citi. Since: 1.40 Ahom. Since: 1.40 Anatolian Hieroglyphs. Since: 1.40 Hatran. Since: 1.40 Multani. Since: 1.40 Old Hungarian. Since: 1.40 Signwriting. Since: 1.40 Looks up the script for a particular character. The script of a character is defined by [Unicode Standard Annex 24: Script names](http://www.unicode.org/reports/tr24/). No check is made for @ch being a valid Unicode character; if you pass in invalid character, the result is undefined. Note that while the return type of this function is declared as `PangoScript`, as of Pango 1.18, this function simply returns the return value of [func@GLib.unichar_get_script]. Callers must be prepared to handle unknown values. Use g_unichar_get_script() the `PangoScript` for the character. a Unicode character Finds a language tag that is reasonably representative of @script. The language will usually be the most widely spoken or used language written in that script: for instance, the sample language for %PANGO_SCRIPT_CYRILLIC is ru (Russian), the sample language for %PANGO_SCRIPT_ARABIC is ar. For some scripts, no sample language will be returned because there is no language that is sufficiently representative. The best example of this is %PANGO_SCRIPT_HAN, where various different variants of written Chinese, Japanese, and Korean all use significantly different sets of Han characters and forms of shared characters. No sample language can be provided for many historical scripts as well. As of 1.18, this function checks the environment variables `PANGO_LANGUAGE` and `LANGUAGE` (checked in that order) first. If one of them is set, it is parsed as a list of language tags separated by colons or other separators. This function will return the first language in the parsed list that Pango believes may use @script for writing. This last predicate is tested using [method@Pango.Language.includes_script]. This can be used to control Pango's font selection for non-primary languages. For example, a `PANGO_LANGUAGE` enviroment variable set to "en:fa" makes Pango choose fonts suitable for Persian (fa) instead of Arabic (ar) when a segment of Arabic text is found in an otherwise non-Arabic text. The same trick can be used to choose a default language for %PANGO_SCRIPT_HAN when setting context language is not feasible. a `PangoLanguage` that is representative of the script a `PangoScript` A `PangoScriptIter` is used to iterate through a string and identify ranges in different scripts. Create a new `PangoScriptIter`, used to break a string of Unicode text into runs by Unicode script. No copy is made of @text, so the caller needs to make sure it remains valid until the iterator is freed with [method@Pango.ScriptIter.free]. the new script iterator, initialized to point at the first range in the text, which should be freed with [method@Pango.ScriptIter.free]. If the string is empty, it will point at an empty range. a UTF-8 string length of @text, or -1 if @text is nul-terminated Frees a `PangoScriptIter`. a `PangoScriptIter` Gets information about the range to which @iter currently points. The range is the set of locations p where *start <= p < *end. (That is, it doesn't include the character stored at *end) Note that while the type of the @script argument is declared as `PangoScript`, as of Pango 1.18, this function simply returns `GUnicodeScript` values. Callers must be prepared to handle unknown values. a `PangoScriptIter` location to store start position of the range location to store end position of the range location to store script for range Advances a `PangoScriptIter` to the next range. If @iter is already at the end, it is left unchanged and %FALSE is returned. %TRUE if @iter was successfully advanced a `PangoScriptIter` Flags influencing the shaping process. `PangoShapeFlags` can be passed to [func@Pango.shape_with_flags]. Default value Round glyph positions and widths to whole device units This option should be set if the target renderer can't do subpixel positioning of glyphs These flags affect how Pango treats characters that are normally not visible in the output. No special treatment for invisible characters Render spaces, tabs and newlines visibly Render line breaks visibly Render default-ignorable Unicode characters visibly An enumeration specifying the width of the font relative to other designs within a family. ultra condensed width extra condensed width condensed width semi condensed width the normal width semi expanded width expanded width extra expanded width ultra expanded width An enumeration specifying the various slant styles possible for a font. the font is upright. the font is slanted, but in a roman style. the font is slanted in an italic style. `PangoTabAlign` specifies where the text appears relative to the tab stop position. the text appears to the right of the tab stop position the text appears to the left of the tab stop position until the available space is filled. Since: 1.50 the text is centered at the tab stop position until the available space is filled. Since: 1.50 text before the first occurrence of the decimal point character appears to the left of the tab stop position (until the available space is filled), the rest to the right. Since: 1.50 A `PangoTabArray` contains an array of tab stops. `PangoTabArray` can be used to set tab stops in a `PangoLayout`. Each tab stop has an alignment, a position, and optionally a character to use as decimal point. Creates an array of @initial_size tab stops. Tab stops are specified in pixel units if @positions_in_pixels is %TRUE, otherwise in Pango units. All stops are initially at position 0. the newly allocated `PangoTabArray`, which should be freed with [method@Pango.TabArray.free]. Initial number of tab stops to allocate, can be 0 whether positions are in pixel units Creates a `PangoTabArray` and allows you to specify the alignment and position of each tab stop. You **must** provide an alignment and position for @size tab stops. the newly allocated `PangoTabArray`, which should be freed with [method@Pango.TabArray.free]. number of tab stops in the array whether positions are in pixel units alignment of first tab stop position of first tab stop additional alignment/position pairs Copies a `PangoTabArray`. the newly allocated `PangoTabArray`, which should be freed with [method@Pango.TabArray.free]. `PangoTabArray` to copy Frees a tab array and associated resources. a `PangoTabArray` Gets the Unicode character to use as decimal point. This is only relevant for tabs with %PANGO_TAB_DECIMAL alignment, which align content at the first occurrence of the decimal point character. The default value of 0 means that Pango will use the decimal point according to the current locale. a `PangoTabArray` the index of a tab stop Returns %TRUE if the tab positions are in pixels, %FALSE if they are in Pango units. whether positions are in pixels. a `PangoTabArray` Gets the number of tab stops in @tab_array. the number of tab stops in the array. a `PangoTabArray` Gets the alignment and position of a tab stop. a `PangoTabArray` tab stop index location to store alignment location to store tab position If non-%NULL, @alignments and @locations are filled with allocated arrays. The arrays are of length [method@Pango.TabArray.get_size]. You must free the returned array. a `PangoTabArray` location to store an array of tab stop alignments location to store an array of tab positions Resizes a tab array. You must subsequently initialize any tabs that were added as a result of growing the array. a `PangoTabArray` new size of the array Sets the Unicode character to use as decimal point. This is only relevant for tabs with %PANGO_TAB_DECIMAL alignment, which align content at the first occurrence of the decimal point character. By default, Pango uses the decimal point according to the current locale. a `PangoTabArray` the index of a tab stop the decimal point to use Sets whether positions in this array are specified in pixels. a `PangoTabArray` whether positions are in pixels Sets the alignment and location of a tab stop. a `PangoTabArray` the index of a tab stop tab alignment tab location in Pango units Utility function to ensure that the tab stops are in increasing order. a `PangoTabArray` Serializes a `PangoTabArray` to a string. In the resulting string, serialized tabs are separated by newlines or commas. Individual tabs are serialized to a string of the form [ALIGNMENT:]POSITION[:DECIMAL_POINT] Where ALIGNMENT is one of _left_, _right_, _center_ or _decimal_, and POSITION is the position of the tab, optionally followed by the unit _px_. If ALIGNMENT is omitted, it defaults to _left_. If ALIGNMENT is _decimal_, the DECIMAL_POINT character may be specified as a Unicode codepoint. Note that all tabs in the array must use the same unit. A typical example: 100px 200px center:300px right:400px a newly allocated string a `PangoTabArray` Deserializes a `PangoTabArray` from a string. This is the counterpart to [method@Pango.TabArray.to_string]. See that functions for details about the format. a new `PangoTabArray` a string An enumeration that affects how Pango treats characters during shaping. Leave text unchanged Display letters and numbers as lowercase Display letters and numbers as uppercase Display the first character of a word in titlecase Rounds a dimension up to whole device units, but does not convert it to device units. a dimension in Pango units. Rounds a dimension down to whole device units, but does not convert it to device units. a dimension in Pango units. Rounds a dimension to whole device units, but does not convert it to device units. a dimension in Pango units. The `PangoUnderline` enumeration is used to specify whether text should be underlined, and if so, the type of underlining. no underline should be drawn a single underline should be drawn a double underline should be drawn a single underline should be drawn at a position beneath the ink extents of the text being underlined. This should be used only for underlining single characters, such as for keyboard accelerators. %PANGO_UNDERLINE_SINGLE should be used for extended portions of text. an underline indicating an error should be drawn below. The exact style of rendering is up to the `PangoRenderer` in use, but typical styles include wavy or dotted lines. This underline is typically used to indicate an error such as a possible mispelling; in some cases a contrasting color may automatically be used. This type of underlining is available since Pango 1.4. Like @PANGO_UNDERLINE_SINGLE, but drawn continuously across multiple runs. This type of underlining is available since Pango 1.46. Like @PANGO_UNDERLINE_DOUBLE, but drawn continuously across multiple runs. This type of underlining is available since Pango 1.46. Like @PANGO_UNDERLINE_ERROR, but drawn continuously across multiple runs. This type of underlining is available since Pango 1.46. Checks that the version of Pango available at compile-time is not older than the provided version number. the major component of the version number the minor component of the version number the micro component of the version number This macro encodes the given Pango version into an integer. The numbers returned by %PANGO_VERSION and pango_version() are encoded using this macro. Two encoded version numbers can be compared as integers. the major component of the version number the minor component of the version number the micro component of the version number The major component of the version of Pango available at compile-time. The micro component of the version of Pango available at compile-time. The minor component of the version of Pango available at compile-time. A string literal containing the version of Pango available at compile-time. An enumeration specifying capitalization variant of the font. A normal font. A font with the lower case characters replaced by smaller variants of the capital characters. A font with all characters replaced by smaller variants of the capital characters. Since: 1.50 A font with the lower case characters replaced by smaller variants of the capital characters. Petite Caps can be even smaller than Small Caps. Since: 1.50 A font with all characters replaced by smaller variants of the capital characters. Petite Caps can be even smaller than Small Caps. Since: 1.50 A font with the upper case characters replaced by smaller variants of the capital letters. Since: 1.50 A font with capital letters that are more suitable for all-uppercase titles. Since: 1.50 An enumeration specifying the weight (boldness) of a font. Weight is specified as a numeric value ranging from 100 to 1000. This enumeration simply provides some common, predefined values. the thin weight (= 100) Since: 1.24 the ultralight weight (= 200) the light weight (= 300) the semilight weight (= 350) Since: 1.36.7 the book weight (= 380) Since: 1.24) the default weight (= 400) the medium weight (= 500) Since: 1.24 the semibold weight (= 600) the bold weight (= 700) the ultrabold weight (= 800) the heavy weight (= 900) the ultraheavy weight (= 1000) Since: 1.24 `PangoWrapMode` describes how to wrap the lines of a `PangoLayout` to the desired width. For @PANGO_WRAP_WORD, Pango uses break opportunities that are determined by the Unicode line breaking algorithm. For @PANGO_WRAP_CHAR, Pango allows breaking at grapheme boundaries that are determined by the Unicode text segmentation algorithm. wrap lines at word boundaries. wrap lines at character boundaries. wrap lines at word boundaries, but fall back to character boundaries if there is not enough space for a full word. do not wrap. Create a new allow-breaks attribute. If breaks are disabled, the range will be kept in a single run, as far as possible. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] %TRUE if we line breaks are allowed Create a new background alpha attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the alpha value, between 1 and 65536 Create a new background color attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the red value (ranging from 0 to 65535) the green value the blue value Create a new baseline displacement attribute. The effect of this attribute is to shift the baseline of a run, relative to the run of preceding run. <picture> <source srcset="baseline-shift-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Baseline Shift" src="baseline-shift-light.png"> </picture> the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] either a `PangoBaselineShift` enumeration value or an absolute value (> 1024) in Pango units, relative to the baseline of the previous run. Positive values displace the text upwards. Apply customization from attributes to the breaks in @attrs. The line breaks are assumed to have been produced by [func@Pango.default_break] and [func@Pango.tailor_break]. text to break. Must be valid UTF-8 length of text in bytes (may be -1 if @text is nul-terminated) `PangoAttrList` to apply Byte offset of @text from the beginning of the paragraph array with one `PangoLogAttr` per character in @text, plus one extra, to be filled in length of @attrs array Create a new font fallback attribute. If fallback is disabled, characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] %TRUE if we should fall back on other fonts for characters the active font is missing Create a new font family attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the family or comma-separated list of families Create a new font description attribute. This attribute allows setting family, style, weight, variant, stretch, and size simultaneously. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the font description Create a new font features tag attribute. You can use this attribute to select OpenType font features like small-caps, alternative glyphs, ligatures, etc. for fonts that support them. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] a string with OpenType font features, with the syntax of the [CSS font-feature-settings property](https://www.w3.org/TR/css-fonts-4/#font-rend-desc) Create a new font scale attribute. The effect of this attribute is to change the font size of a run, relative to the size of preceding run. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] a `PangoFontScale` value, which indicates font size change relative to the size of the previous run. Create a new foreground alpha attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the alpha value, between 1 and 65536 Create a new foreground color attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the red value (ranging from 0 to 65535) the green value the blue value Create a new gravity hint attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the gravity hint value Create a new gravity attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the gravity value; should not be %PANGO_GRAVITY_AUTO Create a new insert-hyphens attribute. Pango will insert hyphens when breaking lines in the middle of a word. This attribute can be used to suppress the hyphen. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] %TRUE if hyphens should be inserted Create a new language tag attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] language tag Create a new letter-spacing attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] amount of extra space to add between graphemes of the text, in Pango units Modify the height of logical line extents by a factor. This affects the values returned by [method@Pango.LayoutLine.get_extents], [method@Pango.LayoutLine.get_pixel_extents] and [method@Pango.LayoutIter.get_line_extents]. the scaling factor to apply to the logical height Override the height of logical line extents to be @height. This affects the values returned by [method@Pango.LayoutLine.get_extents], [method@Pango.LayoutLine.get_pixel_extents] and [method@Pango.LayoutIter.get_line_extents]. the line height, in %PANGO_SCALE-ths of a point Deserializes a `PangoAttrList` from a string. This is the counterpart to [method@Pango.AttrList.to_string]. See that functions for details about the format. a new `PangoAttrList` a string Create a new overline color attribute. This attribute modifies the color of overlines. If not set, overlines will use the foreground color. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the red value (ranging from 0 to 65535) the green value the blue value Create a new overline-style attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the overline style Create a new baseline displacement attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the amount that the text should be displaced vertically, in Pango units. Positive values displace the text upwards. Create a new font size scale attribute. The base font for the affected text will have its size multiplied by @scale_factor. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] factor to scale the font Marks the range of the attribute as a single sentence. Note that this may require adjustments to word and sentence classification around the range. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] Create a new shape attribute. A shape is used to impose a particular ink and logical rectangle on the result of shaping a particular glyph. This might be used, for instance, for embedding a picture or a widget inside a `PangoLayout`. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] ink rectangle to assign to each character logical rectangle to assign to each character Creates a new shape attribute. Like [func@Pango.AttrShape.new], but a user data pointer is also provided; this pointer can be accessed when later rendering the glyph. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] ink rectangle to assign to each character logical rectangle to assign to each character user data pointer function to copy @data when the attribute is copied. If %NULL, @data is simply copied as a pointer function to free @data when the attribute is freed Create a new attribute that influences how invisible characters are rendered. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] `PangoShowFlags` to apply Create a new font-size attribute in fractional points. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the font size, in %PANGO_SCALE-ths of a point Create a new font-size attribute in device units. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the font size, in %PANGO_SCALE-ths of a device unit Create a new font stretch attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the stretch Create a new strikethrough color attribute. This attribute modifies the color of strikethrough lines. If not set, strikethrough lines will use the foreground color. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the red value (ranging from 0 to 65535) the green value the blue value Create a new strike-through attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] %TRUE if the text should be struck-through Create a new font slant style attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the slant style Create a new attribute that influences how characters are transformed during shaping. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] `PangoTextTransform` to apply Fetches the attribute type name. The attribute type name is the string passed in when registering the type using [func@Pango.AttrType.register]. The returned value is an interned string (see g_intern_string() for what that means) that should not be modified or freed. the type ID name (which may be %NULL), or %NULL if @type is a built-in Pango attribute type or invalid. an attribute type ID to fetch the name for Allocate a new attribute type ID. The attribute type name can be accessed later by using [func@Pango.AttrType.get_name]. the new type ID. an identifier for the type Create a new underline color attribute. This attribute modifies the color of underlines. If not set, underlines will use the foreground color. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the red value (ranging from 0 to 65535) the green value the blue value Create a new underline-style attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the underline style Create a new font variant attribute (normal or small caps). the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy]. the variant Create a new font weight attribute. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] the weight Marks the range of the attribute as a single word. Note that this may require adjustments to word and sentence classification around the range. the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] Determines the bidirectional type of a character. The bidirectional type is specified in the Unicode Character Database. A simplified version of this function is available as [func@unichar_direction]. the bidirectional character type, as used in the Unicode bidirectional algorithm. a Unicode character Determines possible line, word, and character breaks for a string of Unicode text with a single analysis. For most purposes you may want to use [func@Pango.get_log_attrs]. Use [func@Pango.default_break], [func@Pango.tailor_break] and [func@Pango.attr_break]. the text to process. Must be valid UTF-8 length of @text in bytes (may be -1 if @text is nul-terminated) `PangoAnalysis` structure for @text an array to store character information in size of the array passed as @attrs This is the default break algorithm. It applies rules from the [Unicode Line Breaking Algorithm](http://www.unicode.org/unicode/reports/tr14/) without language-specific tailoring, therefore the @analyis argument is unused and can be %NULL. See [func@Pango.tailor_break] for language-specific breaks. See [func@Pango.attr_break] for attribute-based customization. text to break. Must be valid UTF-8 length of text in bytes (may be -1 if @text is nul-terminated) a `PangoAnalysis` structure for the @text logical attributes to fill in size of the array passed as @attrs Converts extents from Pango units to device units. The conversion is done by dividing by the %PANGO_SCALE factor and performing rounding. The @inclusive rectangle is converted by flooring the x/y coordinates and extending width/height, such that the final rectangle completely includes the original rectangle. The @nearest rectangle is converted by rounding the coordinates of the rectangle to the nearest device unit (pixel). The rule to which argument to use is: if you want the resulting device-space rectangle to completely contain the original rectangle, pass it in as @inclusive. If you want two touching-but-not-overlapping rectangles stay touching-but-not-overlapping after rounding to device units, pass them in as @nearest. rectangle to round to pixels inclusively rectangle to round to nearest pixels Searches a string the first character that has a strong direction, according to the Unicode bidirectional algorithm. The direction corresponding to the first strong character. If no such character is found, then %PANGO_DIRECTION_NEUTRAL is returned. the text to process. Must be valid UTF-8 length of @text in bytes (may be -1 if @text is nul-terminated) Locates a paragraph boundary in @text. A boundary is caused by delimiter characters, such as a newline, carriage return, carriage return-newline pair, or Unicode paragraph separator character. The index of the run of delimiters is returned in @paragraph_delimiter_index. The index of the start of the next paragraph (index after all delimiters) is stored n @next_paragraph_start. If no delimiters are found, both @paragraph_delimiter_index and @next_paragraph_start are filled with the length of @text (an index one off the end). UTF-8 text length of @text in bytes, or -1 if nul-terminated return location for index of delimiter return location for start of next paragraph Creates a new font description from a string representation. The string must have the form [FAMILY-LIST] [STYLE-OPTIONS] [SIZE] [VARIATIONS] [FEATURES] where FAMILY-LIST is a comma-separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace-separated list of words where each word describes one of style, variant, weight, stretch, or gravity, and SIZE is a decimal number (size in points) or optionally followed by the unit modifier "px" for absolute size. The following words are understood as styles: "Normal", "Roman", "Oblique", "Italic". The following words are understood as variants: "Small-Caps", "All-Small-Caps", "Petite-Caps", "All-Petite-Caps", "Unicase", "Title-Caps". The following words are understood as weights: "Thin", "Ultra-Light", "Extra-Light", "Light", "Semi-Light", "Demi-Light", "Book", "Regular", "Medium", "Semi-Bold", "Demi-Bold", "Bold", "Ultra-Bold", "Extra-Bold", "Heavy", "Black", "Ultra-Black", "Extra-Black". The following words are understood as stretch values: "Ultra-Condensed", "Extra-Condensed", "Condensed", "Semi-Condensed", "Semi-Expanded", "Expanded", "Extra-Expanded", "Ultra-Expanded". The following words are understood as gravity values: "Not-Rotated", "South", "Upside-Down", "North", "Rotated-Left", "East", "Rotated-Right", "West". The following words are understood as color values: "With-Color", "Without-Color". VARIATIONS is a comma-separated list of font variations of the form @‍axis1=value,axis2=value,... FEATURES is a comma-separated list of font features of the form \#‍feature1=value,feature2=value,... The =value part can be ommitted if the value is 1. Any one of the options may be absent. If FAMILY-LIST is absent, then the family_name field of the resulting font description will be initialized to %NULL. If STYLE-OPTIONS is missing, then all style options will be set to the default values. If SIZE is missing, the size in the resulting font description will be set to 0. A typical example: Cantarell Italic Light 15 @‍wght=200 #‍tnum=1 a new `PangoFontDescription`. string representation of a font description. Computes a `PangoLogAttr` for each character in @text. The @attrs array must have one `PangoLogAttr` for each position in @text; if @text contains N characters, it has N+1 positions, including the last position at the end of the text. @text should be an entire paragraph; logical attributes can't be computed without context (for example you need to see spaces on either side of a word to know the word is a word). text to process. Must be valid UTF-8 length in bytes of @text embedding level, or -1 if unknown language tag array with one `PangoLogAttr` per character in @text, plus one extra, to be filled in length of @attrs array Returns the mirrored character of a Unicode character. Mirror characters are determined by the Unicode mirrored property. Use [func@GLib.unichar_get_mirror_char] instead; the docs for that function provide full details. %TRUE if @ch has a mirrored character and @mirrored_ch is filled in, %FALSE otherwise a Unicode character location to store the mirrored character Finds the gravity that best matches the rotation component in a `PangoMatrix`. the gravity of @matrix, which will never be %PANGO_GRAVITY_AUTO, or %PANGO_GRAVITY_SOUTH if @matrix is %NULL a `PangoMatrix` Returns the gravity to use in laying out a `PangoItem`. The gravity is determined based on the script, base gravity, and hint. If @base_gravity is %PANGO_GRAVITY_AUTO, it is first replaced with the preferred gravity of @script. To get the preferred gravity of a script, pass %PANGO_GRAVITY_AUTO and %PANGO_GRAVITY_HINT_STRONG in. resolved gravity suitable to use for a run of text with @script `PangoScript` to query base gravity of the paragraph orientation hint Returns the gravity to use in laying out a single character or `PangoItem`. The gravity is determined based on the script, East Asian width, base gravity, and hint, This function is similar to [func@Pango.Gravity.get_for_script] except that this function makes a distinction between narrow/half-width and wide/full-width characters also. Wide/full-width characters always stand *upright*, that is, they always take the base gravity, whereas narrow/full-width characters are always rotated in vertical context. If @base_gravity is %PANGO_GRAVITY_AUTO, it is first replaced with the preferred gravity of @script. resolved gravity suitable to use for a run of text with @script and @wide. `PangoScript` to query %TRUE for wide characters as returned by g_unichar_iswide() base gravity of the paragraph orientation hint Converts a `PangoGravity` value to its natural rotation in radians. Note that [method@Pango.Matrix.rotate] takes angle in degrees, not radians. So, to call [method@Pango.Matrix,rotate] with the output of this function you should multiply it by (180. / G_PI). the rotation value corresponding to @gravity. gravity to query, should not be %PANGO_GRAVITY_AUTO Checks if a character that should not be normally rendered. This includes all Unicode characters with "ZERO WIDTH" in their name, as well as *bidi* formatting characters, and a few other ones. This is totally different from [func@GLib.unichar_iszerowidth] and is at best misnamed. %TRUE if @ch is a zero-width character, %FALSE otherwise a Unicode character Breaks a piece of text into segments with consistent directional level and font. Each byte of @text will be contained in exactly one of the items in the returned list; the generated list of items will be in logical order (the start offsets of the items are ascending). @cached_iter should be an iterator over @attrs currently positioned at a range before or containing @start_index; @cached_iter will be advanced to the range covering the position just after @start_index + @length. (i.e. if itemizing in a loop, just keep passing in the same @cached_iter). a `GList` of [struct@Pango.Item] structures. The items should be freed using [method@Pango.Item.free] in combination with [func@GLib.List.free_full]. a structure holding information that affects the itemization process. the text to itemize. Must be valid UTF-8 first byte in @text to process the number of bytes (not characters) to process after @start_index. This must be >= 0. the set of attributes that apply to @text. Cached attribute iterator Like `pango_itemize()`, but with an explicitly specified base direction. The base direction is used when computing bidirectional levels. [func@itemize] gets the base direction from the `PangoContext` (see [method@Pango.Context.set_base_dir]). a `GList` of [struct@Pango.Item] structures. The items should be freed using [method@Pango.Item.free] probably in combination with [func@GLib.List.free_full]. a structure holding information that affects the itemization process. base direction to use for bidirectional processing the text to itemize. first byte in @text to process the number of bytes (not characters) to process after @start_index. This must be >= 0. the set of attributes that apply to @text. Cached attribute iterator Convert a language tag to a `PangoLanguage`. The language tag must be in a RFC-3066 format. `PangoLanguage` pointers can be efficiently copied (copy the pointer) and compared with other language tags (compare the pointer.) This function first canonicalizes the string by converting it to lowercase, mapping '_' to '-', and stripping all characters other than letters and '-'. Use [func@Pango.Language.get_default] if you want to get the `PangoLanguage` for the current locale of the process. a `PangoLanguage` a string representing a language tag Returns the `PangoLanguage` for the current locale of the process. On Unix systems, this is the return value is derived from `setlocale (LC_CTYPE, NULL)`, and the user can affect this through the environment variables LC_ALL, LC_CTYPE or LANG (checked in that order). The locale string typically is in the form lang_COUNTRY, where lang is an ISO-639 language code, and COUNTRY is an ISO-3166 country code. For instance, sv_FI for Swedish as written in Finland or pt_BR for Portuguese as written in Brazil. On Windows, the C library does not use any such environment variables, and setting them won't affect the behavior of functions like ctime(). The user sets the locale through the Regional Options in the Control Panel. The C library (in the setlocale() function) does not use country and language codes, but country and language names spelled out in English. However, this function does check the above environment variables, and does return a Unix-style locale string based on either said environment variables or the thread's current locale. Your application should call `setlocale(LC_ALL, "")` for the user settings to take effect. GTK does this in its initialization functions automatically (by calling gtk_set_locale()). See the setlocale() manpage for more details. Note that the default language can change over the life of an application. Also note that this function will not do the right thing if you use per-thread locales with uselocale(). In that case, you should just call pango_language_from_string() yourself. the default language as a `PangoLanguage` Returns the list of languages that the user prefers. The list is specified by the `PANGO_LANGUAGE` or `LANGUAGE` environment variables, in order of preference. Note that this list does not necessarily include the language returned by [func@Pango.Language.get_default]. When choosing language-specific resources, such as the sample text returned by [method@Pango.Language.get_sample_string], you should first try the default language, followed by the languages returned by this function. a %NULL-terminated array of `PangoLanguage`* Return the bidirectional embedding levels of the input paragraph. The bidirectional embedding levels are defined by the [Unicode Bidirectional Algorithm](http://www.unicode.org/reports/tr9/). If the input base direction is a weak direction, the direction of the characters in the text will determine the final resolved direction. a newly allocated array of embedding levels, one item per character (not byte), that should be freed using [func@GLib.free]. the text to itemize. the number of bytes (not characters) to process, or -1 if @text is nul-terminated and the length should be calculated. input base direction, and output resolved direction. Finishes parsing markup. After feeding a Pango markup parser some data with [method@GLib.MarkupParseContext.parse], use this function to get the list of attributes and text out of the markup. This function will not free @context, use [method@GLib.MarkupParseContext.free] to do so. %FALSE if @error is set, otherwise %TRUE A valid parse context that was returned from [func@markup_parser_new] address of return location for a `PangoAttrList` address of return location for text with tags stripped address of return location for accelerator char Incrementally parses marked-up text to create a plain-text string and an attribute list. See the [Pango Markup](pango_markup.html) docs for details about the supported markup. If @accel_marker is nonzero, the given character will mark the character following it as an accelerator. For example, @accel_marker might be an ampersand or underscore. All characters marked as an accelerator will receive a %PANGO_UNDERLINE_LOW attribute, and the first character so marked will be returned in @accel_char, when calling [func@markup_parser_finish]. Two @accel_marker characters following each other produce a single literal @accel_marker character. To feed markup to the parser, use [method@GLib.MarkupParseContext.parse] on the returned [struct@GLib.MarkupParseContext]. When done with feeding markup to the parser, use [func@markup_parser_finish] to get the data out of it, and then use [method@GLib.MarkupParseContext.free] to free it. This function is designed for applications that read Pango markup from streams. To simply parse a string containing Pango markup, the [func@Pango.parse_markup] API is recommended instead. a `GMarkupParseContext` that should be destroyed with [method@GLib.MarkupParseContext.free]. character that precedes an accelerator, or 0 for none Parses an enum type and stores the result in @value. If @str does not match the nick name of any of the possible values for the enum and is not an integer, %FALSE is returned, a warning is issued if @warn is %TRUE, and a string representing the list of possible values is stored in @possible_values. The list is slash-separated, eg. "none/start/middle/end". If failed and @possible_values is not %NULL, returned string should be freed using g_free(). %TRUE if @str was successfully parsed enum type to parse, eg. %PANGO_TYPE_ELLIPSIZE_MODE string to parse integer to store the result in if %TRUE, issue a g_warning() on bad input place to store list of possible values on failure Parses marked-up text to create a plain-text string and an attribute list. See the [Pango Markup](pango_markup.html) docs for details about the supported markup. If @accel_marker is nonzero, the given character will mark the character following it as an accelerator. For example, @accel_marker might be an ampersand or underscore. All characters marked as an accelerator will receive a %PANGO_UNDERLINE_LOW attribute, and the first character so marked will be returned in @accel_char. Two @accel_marker characters following each other produce a single literal @accel_marker character. To parse a stream of pango markup incrementally, use [func@markup_parser_new]. If any error happens, none of the output arguments are touched except for @error. %FALSE if @error is set, otherwise %TRUE markup to parse (see the [Pango Markup](pango_markup.html) docs) length of @markup_text, or -1 if nul-terminated character that precedes an accelerator, or 0 for none address of return location for a `PangoAttrList` address of return location for text with tags stripped address of return location for accelerator char Parses a font stretch. The allowed values are "ultra_condensed", "extra_condensed", "condensed", "semi_condensed", "normal", "semi_expanded", "expanded", "extra_expanded" and "ultra_expanded". Case variations are ignored and the '_' characters may be omitted. %TRUE if @str was successfully parsed. a string to parse. a `PangoStretch` to store the result in. if %TRUE, issue a g_warning() on bad input. Parses a font style. The allowed values are "normal", "italic" and "oblique", case variations being ignored. %TRUE if @str was successfully parsed. a string to parse. a `PangoStyle` to store the result in. if %TRUE, issue a g_warning() on bad input. Parses a font variant. The allowed values are "normal", "small-caps", "all-small-caps", "petite-caps", "all-petite-caps", "unicase" and "title-caps", case variations being ignored. %TRUE if @str was successfully parsed. a string to parse. a `PangoVariant` to store the result in. if %TRUE, issue a g_warning() on bad input. Parses a font weight. The allowed values are "heavy", "ultrabold", "bold", "normal", "light", "ultraleight" and integers. Case variations are ignored. %TRUE if @str was successfully parsed. a string to parse. a `PangoWeight` to store the result in. if %TRUE, issue a g_warning() on bad input. Quantizes the thickness and position of a line to whole device pixels. This is typically used for underline or strikethrough. The purpose of this function is to avoid such lines looking blurry. Care is taken to make sure @thickness is at least one pixel when this function returns, but returned @position may become zero as a result of rounding. pointer to the thickness of a line, in Pango units corresponding position Reads an entire line from a file into a buffer. Lines may be delimited with '\n', '\r', '\n\r', or '\r\n'. The delimiter is not written into the buffer. Text after a '#' character is treated as a comment and skipped. '\' can be used to escape a # character. '\' proceeding a line delimiter combines adjacent lines. A '\' proceeding any other character is ignored and written into the output buffer unmodified. 0 if the stream was already at an %EOF character, otherwise the number of lines read (this is useful for maintaining a line number counter which doesn't combine lines with '\') a stdio stream `GString` buffer into which to write the result Reorder items from logical order to visual order. The visual order is determined from the associated directional levels of the items. The original list is unmodified. (Please open a bug if you use this function. It is not a particularly convenient interface, and the code is duplicated elsewhere in Pango for that reason.) a `GList` of `PangoItem` structures in visual order. a `GList` of `PangoItem` in logical order. Scans an integer. Leading white space is skipped. %FALSE if a parse error occurred in/out string position an int into which to write the result Scans a string into a `GString` buffer. The string may either be a sequence of non-white-space characters, or a quoted string with '"'. Instead a quoted string, '\"' represents a literal quote. Leading white space outside of quotes is skipped. %FALSE if a parse error occurred in/out string position a `GString` into which to write the result Scans a word into a `GString` buffer. A word consists of [A-Za-z_] followed by zero or more [A-Za-z_0-9]. Leading white space is skipped. %FALSE if a parse error occurred in/out string position a `GString` into which to write the result Looks up the script for a particular character. The script of a character is defined by [Unicode Standard Annex 24: Script names](http://www.unicode.org/reports/tr24/). No check is made for @ch being a valid Unicode character; if you pass in invalid character, the result is undefined. Note that while the return type of this function is declared as `PangoScript`, as of Pango 1.18, this function simply returns the return value of [func@GLib.unichar_get_script]. Callers must be prepared to handle unknown values. Use g_unichar_get_script() the `PangoScript` for the character. a Unicode character Finds a language tag that is reasonably representative of @script. The language will usually be the most widely spoken or used language written in that script: for instance, the sample language for %PANGO_SCRIPT_CYRILLIC is ru (Russian), the sample language for %PANGO_SCRIPT_ARABIC is ar. For some scripts, no sample language will be returned because there is no language that is sufficiently representative. The best example of this is %PANGO_SCRIPT_HAN, where various different variants of written Chinese, Japanese, and Korean all use significantly different sets of Han characters and forms of shared characters. No sample language can be provided for many historical scripts as well. As of 1.18, this function checks the environment variables `PANGO_LANGUAGE` and `LANGUAGE` (checked in that order) first. If one of them is set, it is parsed as a list of language tags separated by colons or other separators. This function will return the first language in the parsed list that Pango believes may use @script for writing. This last predicate is tested using [method@Pango.Language.includes_script]. This can be used to control Pango's font selection for non-primary languages. For example, a `PANGO_LANGUAGE` enviroment variable set to "en:fa" makes Pango choose fonts suitable for Persian (fa) instead of Arabic (ar) when a segment of Arabic text is found in an otherwise non-Arabic text. The same trick can be used to choose a default language for %PANGO_SCRIPT_HAN when setting context language is not feasible. a `PangoLanguage` that is representative of the script a `PangoScript` Convert the characters in @text into glyphs. Given a segment of text and the corresponding `PangoAnalysis` structure returned from [func@Pango.itemize], convert the characters into glyphs. You may also pass in only a substring of the item from [func@Pango.itemize]. It is recommended that you use [func@Pango.shape_full] instead, since that API allows for shaping interaction happening across text item boundaries. Some aspects of hyphen insertion and text transformation (in particular, capitalization) require log attrs, and thus can only be handled by [func@Pango.shape_item]. Note that the extra attributes in the @analyis that is returned from [func@Pango.itemize] have indices that are relative to the entire paragraph, so you need to subtract the item offset from their indices before calling [func@Pango.shape]. the text to process the length (in bytes) of @text `PangoAnalysis` structure from [func@Pango.itemize] glyph string in which to store results Convert the characters in @text into glyphs. Given a segment of text and the corresponding `PangoAnalysis` structure returned from [func@Pango.itemize], convert the characters into glyphs. You may also pass in only a substring of the item from [func@Pango.itemize]. This is similar to [func@Pango.shape], except it also can optionally take the full paragraph text as input, which will then be used to perform certain cross-item shaping interactions. If you have access to the broader text of which @item_text is part of, provide the broader text as @paragraph_text. If @paragraph_text is %NULL, item text is used instead. Some aspects of hyphen insertion and text transformation (in particular, capitalization) require log attrs, and thus can only be handled by [func@Pango.shape_item]. Note that the extra attributes in the @analyis that is returned from [func@Pango.itemize] have indices that are relative to the entire paragraph, so you do not pass the full paragraph text as @paragraph_text, you need to subtract the item offset from their indices before calling [func@Pango.shape_full]. valid UTF-8 text to shape. the length (in bytes) of @item_text. -1 means nul-terminated text. text of the paragraph (see details). the length (in bytes) of @paragraph_text. -1 means nul-terminated text. `PangoAnalysis` structure from [func@Pango.itemize]. glyph string in which to store results. Convert the characters in @item into glyphs. This is similar to [func@Pango.shape_with_flags], except it takes a `PangoItem` instead of separate @item_text and @analysis arguments. It also takes @log_attrs, which are needed for implementing some aspects of hyphen insertion and text transforms (in particular, capitalization). Note that the extra attributes in the @analyis that is returned from [func@Pango.itemize] have indices that are relative to the entire paragraph, so you do not pass the full paragraph text as @paragraph_text, you need to subtract the item offset from their indices before calling [func@Pango.shape_with_flags]. `PangoItem` to shape text of the paragraph (see details). the length (in bytes) of @paragraph_text. -1 means nul-terminated text. array of `PangoLogAttr` for @item glyph string in which to store results flags influencing the shaping process Convert the characters in @text into glyphs. Given a segment of text and the corresponding `PangoAnalysis` structure returned from [func@Pango.itemize], convert the characters into glyphs. You may also pass in only a substring of the item from [func@Pango.itemize]. This is similar to [func@Pango.shape_full], except it also takes flags that can influence the shaping process. Some aspects of hyphen insertion and text transformation (in particular, capitalization) require log attrs, and thus can only be handled by [func@Pango.shape_item]. Note that the extra attributes in the @analyis that is returned from [func@Pango.itemize] have indices that are relative to the entire paragraph, so you do not pass the full paragraph text as @paragraph_text, you need to subtract the item offset from their indices before calling [func@Pango.shape_with_flags]. valid UTF-8 text to shape the length (in bytes) of @item_text. -1 means nul-terminated text. text of the paragraph (see details). the length (in bytes) of @paragraph_text. -1 means nul-terminated text. `PangoAnalysis` structure from [func@Pango.itemize] glyph string in which to store results flags influencing the shaping process Skips 0 or more characters of white space. %FALSE if skipping the white space leaves the position at a '\0' character. in/out string position Splits a %G_SEARCHPATH_SEPARATOR-separated list of files, stripping white space and substituting ~/ with $HOME/. a list of strings to be freed with g_strfreev() a %G_SEARCHPATH_SEPARATOR separated list of filenames Deserializes a `PangoTabArray` from a string. This is the counterpart to [method@Pango.TabArray.to_string]. See that functions for details about the format. a new `PangoTabArray` a string Apply language-specific tailoring to the breaks in @attrs. The line breaks are assumed to have been produced by [func@Pango.default_break]. If @offset is not -1, it is used to apply attributes from @analysis that are relevant to line breaking. Note that it is better to pass -1 for @offset and use [func@Pango.attr_break] to apply attributes to the whole paragraph. text to process. Must be valid UTF-8 length in bytes of @text `PangoAnalysis` for @text Byte offset of @text from the beginning of the paragraph, or -1 to ignore attributes from @analysis array with one `PangoLogAttr` per character in @text, plus one extra, to be filled in length of @attrs array Trims leading and trailing whitespace from a string. A newly-allocated string that must be freed with g_free() a string Determines the inherent direction of a character. The inherent direction is either `PANGO_DIRECTION_LTR`, `PANGO_DIRECTION_RTL`, or `PANGO_DIRECTION_NEUTRAL`. This function is useful to categorize characters into left-to-right letters, right-to-left letters, and everything else. If full Unicode bidirectional type of a character is needed, [func@Pango.BidiType.for_unichar] can be used instead. the direction of the character. a Unicode character Converts a floating-point number to Pango units. The conversion is done by multiplying @d by %PANGO_SCALE and rounding the result to nearest integer. the value in Pango units. double floating-point value Converts a number in Pango units to floating-point. The conversion is done by dividing @i by %PANGO_SCALE. the double value. value in Pango units Returns the encoded version of Pango available at run-time. This is similar to the macro %PANGO_VERSION except that the macro returns the encoded version available at compile-time. A version number can be encoded into an integer using PANGO_VERSION_ENCODE(). The encoded version of Pango library available at run time. Checks that the Pango library in use is compatible with the given version. Generally you would pass in the constants %PANGO_VERSION_MAJOR, %PANGO_VERSION_MINOR, %PANGO_VERSION_MICRO as the three arguments to this function; that produces a check that the library in use at run-time is compatible with the version of Pango the application or module was compiled against. Compatibility is defined by two things: first the version of the running library is newer than the version @required_major.required_minor.@required_micro. Second the running library must be binary compatible with the version @required_major.required_minor.@required_micro (same major version.) For compile-time version checking use PANGO_VERSION_CHECK(). %NULL if the Pango library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by Pango and should not be modified or freed. the required major version the required minor version the required major version Returns the version of Pango available at run-time. This is similar to the macro %PANGO_VERSION_STRING except that the macro returns the version available at compile-time. A string containing the version of Pango library available at run time. The returned string is owned by Pango and should not be modified or freed. soup3-0.9.0/gir-files/PangoCairo-1.0.gir000064400000000000000000001114341046102023000156110ustar 00000000000000 `PangoCairoFont` is an interface exported by fonts for use with Cairo. The actual type of the font will depend on the particular font technology Cairo was compiled to use. Gets the `cairo_scaled_font_t` used by @font. The scaled font can be referenced and kept using cairo_scaled_font_reference(). the `cairo_scaled_font_t` used by @font a `PangoFont` from a `PangoCairoFontMap` `PangoCairoFontMap` is an interface exported by font maps for use with Cairo. The actual type of the font map will depend on the particular font technology Cairo was compiled to use. Gets a default `PangoCairoFontMap` to use with Cairo. Note that the type of the returned object will depend on the particular font backend Cairo was compiled to use; you generally should only use the `PangoFontMap` and `PangoCairoFontMap` interfaces on the returned object. The default Cairo fontmap can be changed by using [method@PangoCairo.FontMap.set_default]. This can be used to change the Cairo font backend that the default fontmap uses for example. Note that since Pango 1.32.6, the default fontmap is per-thread. Each thread gets its own default fontmap. In this way, PangoCairo can be used safely from multiple threads. the default PangoCairo fontmap for the current thread. This object is owned by Pango and must not be freed. Creates a new `PangoCairoFontMap` object. A fontmap is used to cache information about available fonts, and holds certain global parameters such as the resolution. In most cases, you can use `func@PangoCairo.font_map_get_default] instead. Note that the type of the returned object will depend on the particular font backend Cairo was compiled to use; You generally should only use the `PangoFontMap` and `PangoCairoFontMap` interfaces on the returned object. You can override the type of backend returned by using an environment variable %PANGOCAIRO_BACKEND. Supported types, based on your build, are fc (fontconfig), win32, and coretext. If requested type is not available, NULL is returned. Ie. this is only useful for testing, when at least two backends are compiled in. the newly allocated `PangoFontMap`, which should be freed with g_object_unref(). Creates a new `PangoCairoFontMap` object of the type suitable to be used with cairo font backend of type @fonttype. In most cases one should simply use [func@PangoCairo.FontMap.new], or in fact in most of those cases, just use [func@PangoCairo.FontMap.get_default]. the newly allocated `PangoFontMap` of suitable type which should be freed with g_object_unref(), or %NULL if the requested cairo font backend is not supported / compiled in. desired #cairo_font_type_t Create a `PangoContext` for the given fontmap. Use pango_font_map_create_context() instead. the newly created context; free with g_object_unref(). a `PangoCairoFontMap` Gets the type of Cairo font backend that @fontmap uses. the `cairo_font_type_t` cairo font backend type a `PangoCairoFontMap` Gets the resolution for the fontmap. See [method@PangoCairo.FontMap.set_resolution]. the resolution in "dots per inch" a `PangoCairoFontMap` Sets a default `PangoCairoFontMap` to use with Cairo. This can be used to change the Cairo font backend that the default fontmap uses for example. The old default font map is unreffed and the new font map referenced. Note that since Pango 1.32.6, the default fontmap is per-thread. This function only changes the default fontmap for the current thread. Default fontmaps of existing threads are not changed. Default fontmaps of any new threads will still be created using [func@PangoCairo.FontMap.new]. A value of %NULL for @fontmap will cause the current default font map to be released and a new default font map to be created on demand, using [func@PangoCairo.FontMap.new]. The new default font map Sets the resolution for the fontmap. This is a scale factor between points specified in a `PangoFontDescription` and Cairo units. The default value is 96, meaning that a 10 point font will be 13 units high. (10 * 96. / 72. = 13.3). a `PangoCairoFontMap` the resolution in "dots per inch". (Physical inches aren't actually involved; the terminology is conventional.) Function type for rendering attributes of type %PANGO_ATTR_SHAPE with Pango's Cairo renderer. a Cairo context with current point set to where the shape should be rendered the %PANGO_ATTR_SHAPE to render whether only the shape path should be appended to current path of @cr and no filling/stroking done. This will be set to %TRUE when called from pango_cairo_layout_path() and pango_cairo_layout_line_path() rendering functions. user data passed to pango_cairo_context_set_shape_renderer() Retrieves any font rendering options previously set with [func@PangoCairo.context_set_font_options]. This function does not report options that are derived from the target surface by [func@update_context]. the font options previously set on the context, or %NULL if no options have been set. This value is owned by the context and must not be modified or freed. a `PangoContext`, from a pangocairo font map Gets the resolution for the context. See [func@PangoCairo.context_set_resolution] the resolution in "dots per inch". A negative value will be returned if no resolution has previously been set. a `PangoContext`, from a pangocairo font map Sets callback function for context to use for rendering attributes of type %PANGO_ATTR_SHAPE. See `PangoCairoShapeRendererFunc` for details. Retrieves callback function and associated user data for rendering attributes of type %PANGO_ATTR_SHAPE as set by [func@PangoCairo.context_set_shape_renderer], if any. the shape rendering callback previously set on the context, or %NULL if no shape rendering callback have been set. a `PangoContext`, from a pangocairo font map Pointer to `gpointer` to return user data Sets the font options used when rendering text with this context. These options override any options that [func@update_context] derives from the target surface. a `PangoContext`, from a pangocairo font map a `cairo_font_options_t`, or %NULL to unset any previously set options. A copy is made. Sets the resolution for the context. This is a scale factor between points specified in a `PangoFontDescription` and Cairo units. The default value is 96, meaning that a 10 point font will be 13 units high. (10 * 96. / 72. = 13.3). a `PangoContext`, from a pangocairo font map the resolution in "dots per inch". (Physical inches aren't actually involved; the terminology is conventional.) A 0 or negative value means to use the resolution from the font map. Sets callback function for context to use for rendering attributes of type %PANGO_ATTR_SHAPE. See `PangoCairoShapeRendererFunc` for details. a `PangoContext`, from a pangocairo font map Callback function for rendering attributes of type %PANGO_ATTR_SHAPE, or %NULL to disable shape rendering. User data that will be passed to @func. Callback that will be called when the context is freed to release @data Creates a context object set up to match the current transformation and target surface of the Cairo context. This context can then be used to create a layout using [ctor@Pango.Layout.new]. This function is a convenience function that creates a context using the default font map, then updates it to @cr. If you just need to create a layout for use with @cr and do not need to access `PangoContext` directly, you can use [func@create_layout] instead. the newly created `PangoContext` a Cairo context Creates a layout object set up to match the current transformation and target surface of the Cairo context. This layout can then be used for text measurement with functions like [method@Pango.Layout.get_size] or drawing with functions like [func@show_layout]. If you change the transformation or target surface for @cr, you need to call [func@update_layout]. This function is the most convenient way to use Cairo with Pango, however it is slightly inefficient since it creates a separate `PangoContext` object for each layout. This might matter in an application that was laying out large amounts of text. the newly created `PangoLayout` a Cairo context Add a squiggly line to the current path in the specified cairo context that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. The width of the underline is rounded to an integer number of up/down segments and the resulting rectangle is centered in the original rectangle. a Cairo context The X coordinate of one corner of the rectangle The Y coordinate of one corner of the rectangle Non-negative width of the rectangle Non-negative height of the rectangle Gets a default `PangoCairoFontMap` to use with Cairo. Note that the type of the returned object will depend on the particular font backend Cairo was compiled to use; you generally should only use the `PangoFontMap` and `PangoCairoFontMap` interfaces on the returned object. The default Cairo fontmap can be changed by using [method@PangoCairo.FontMap.set_default]. This can be used to change the Cairo font backend that the default fontmap uses for example. Note that since Pango 1.32.6, the default fontmap is per-thread. Each thread gets its own default fontmap. In this way, PangoCairo can be used safely from multiple threads. the default PangoCairo fontmap for the current thread. This object is owned by Pango and must not be freed. Creates a new `PangoCairoFontMap` object. A fontmap is used to cache information about available fonts, and holds certain global parameters such as the resolution. In most cases, you can use `func@PangoCairo.font_map_get_default] instead. Note that the type of the returned object will depend on the particular font backend Cairo was compiled to use; You generally should only use the `PangoFontMap` and `PangoCairoFontMap` interfaces on the returned object. You can override the type of backend returned by using an environment variable %PANGOCAIRO_BACKEND. Supported types, based on your build, are fc (fontconfig), win32, and coretext. If requested type is not available, NULL is returned. Ie. this is only useful for testing, when at least two backends are compiled in. the newly allocated `PangoFontMap`, which should be freed with g_object_unref(). Creates a new `PangoCairoFontMap` object of the type suitable to be used with cairo font backend of type @fonttype. In most cases one should simply use [func@PangoCairo.FontMap.new], or in fact in most of those cases, just use [func@PangoCairo.FontMap.get_default]. the newly allocated `PangoFontMap` of suitable type which should be freed with g_object_unref(), or %NULL if the requested cairo font backend is not supported / compiled in. desired #cairo_font_type_t Adds the glyphs in @glyphs to the current path in the specified cairo context. The origin of the glyphs (the left edge of the baseline) will be at the current point of the cairo context. a Cairo context a `PangoFont` from a `PangoCairoFontMap` a `PangoGlyphString` Adds the text in `PangoLayoutLine` to the current path in the specified cairo context. The origin of the glyphs (the left edge of the line) will be at the current point of the cairo context. a Cairo context a `PangoLayoutLine` Adds the text in a `PangoLayout` to the current path in the specified cairo context. The top-left corner of the `PangoLayout` will be at the current point of the cairo context. a Cairo context a Pango layout Draw a squiggly line in the specified cairo context that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. The width of the underline is rounded to an integer number of up/down segments and the resulting rectangle is centered in the original rectangle. a Cairo context The X coordinate of one corner of the rectangle The Y coordinate of one corner of the rectangle Non-negative width of the rectangle Non-negative height of the rectangle Draws the glyphs in @glyph_item in the specified cairo context, embedding the text associated with the glyphs in the output if the output format supports it (PDF for example), otherwise it acts similar to [func@show_glyph_string]. The origin of the glyphs (the left edge of the baseline) will be drawn at the current point of the cairo context. Note that @text is the start of the text for layout, which is then indexed by `glyph_item->item->offset`. a Cairo context the UTF-8 text that @glyph_item refers to a `PangoGlyphItem` Draws the glyphs in @glyphs in the specified cairo context. The origin of the glyphs (the left edge of the baseline) will be drawn at the current point of the cairo context. a Cairo context a `PangoFont` from a `PangoCairoFontMap` a `PangoGlyphString` Draws a `PangoLayout` in the specified cairo context. The top-left corner of the `PangoLayout` will be drawn at the current point of the cairo context. a Cairo context a Pango layout Draws a `PangoLayoutLine` in the specified cairo context. The origin of the glyphs (the left edge of the line) will be drawn at the current point of the cairo context. a Cairo context a `PangoLayoutLine` Updates a `PangoContext` previously created for use with Cairo to match the current transformation and target surface of a Cairo context. If any layouts have been created for the context, it's necessary to call [method@Pango.Layout.context_changed] on those layouts. a Cairo context a `PangoContext`, from a pangocairo font map Updates the private `PangoContext` of a `PangoLayout` created with [func@create_layout] to match the current transformation and target surface of a Cairo context. a Cairo context a `PangoLayout`, from [func@create_layout] soup3-0.9.0/gir-files/PangoFT2-1.0.gir000064400000000000000000000531471046102023000151550ustar 00000000000000 The `PangoFT2FontMap` is the `PangoFontMap` implementation for FreeType fonts. Create a new `PangoFT2FontMap` object. A fontmap is used to cache information about available fonts, and holds certain global parameters such as the resolution and the default substitute function (see [method@PangoFT2.FontMap.set_default_substitute]). the newly created fontmap object. Unref with g_object_unref() when you are finished with it. Returns a `PangoFT2FontMap`. This font map is cached and should not be freed. If the font map is no longer needed, it can be released with pango_ft2_shutdown_display(). Use of the global PangoFT2 fontmap is deprecated; use pango_ft2_font_map_new() instead. a `PangoFT2FontMap`. Create a `PangoContext` for the given fontmap. Use [method@Pango.FontMap.create_context] instead. the newly created context; free with g_object_unref(). a `PangoFT2FontMap` Sets a function that will be called to do final configuration substitution on a `FcPattern` before it is used to load the font. This function can be used to do things like set hinting and antialiasing options. Use [method@PangoFc.FontMap.set_default_substitute] instead. a `PangoFT2FontMap` function to call to to do final config tweaking on #FcPattern objects. data to pass to @func function to call when @data is no longer used. Sets the horizontal and vertical resolutions for the fontmap. a `PangoFT2FontMap` dots per inch in the X direction dots per inch in the Y direction Call this function any time the results of the default substitution function set with pango_ft2_font_map_set_default_substitute() change. That is, if your substitution function will return different results for the same input pattern, you must call this function. Use [method@PangoFc.FontMap.substitute_changed] instead. a `PangoFT2FontMap` Function type for doing final config tweaking on prepared FcPatterns. the FcPattern to tweak. user data. Gets the `PangoCoverage` for a `PangoFT2Font`. Use [method@Pango.Font.get_coverage] instead. a `PangoCoverage` a Pango FT2 font a language tag. Returns the native FreeType2 `FT_Face` structure used for this `PangoFont`. This may be useful if you want to use FreeType2 functions directly. Use [method@PangoFc.Font.lock_face] instead; when you are done with a face from [method@PangoFc.Font.lock_face], you must call [method@PangoFc.Font.unlock_face]. a pointer to a `FT_Face` structure, with the size set correctly a `PangoFont` Retrieves kerning information for a combination of two glyphs. Use pango_fc_font_kern_glyphs() instead. The amount of kerning (in Pango units) to apply for the given combination of glyphs. a `PangoFont` the left `PangoGlyph` the right `PangoGlyph` Retrieves a `PangoContext` for the default PangoFT2 fontmap (see pango_ft2_font_map_for_display()) and sets the resolution for the default fontmap to @dpi_x by @dpi_y. Use [method@Pango.FontMap.create_context] instead. the new `PangoContext` the horizontal DPI of the target device the vertical DPI of the target device Return the index of a glyph suitable for drawing unknown characters with @font, or %PANGO_GLYPH_EMPTY if no suitable glyph found. If you want to draw an unknown-box for a character that is not covered by the font, use PANGO_GET_UNKNOWN_GLYPH() instead. a glyph index into @font, or %PANGO_GLYPH_EMPTY a `PangoFont` Renders a `PangoGlyphString` onto a FreeType2 bitmap. the FreeType2 bitmap onto which to draw the string the font in which to draw the string the glyph string to draw the x position of the start of the string (in pixels) the y position of the baseline (in pixels) Render a `PangoLayout` onto a FreeType2 bitmap a FT_Bitmap to render the layout onto a `PangoLayout` the X position of the left of the layout (in pixels) the Y position of the top of the layout (in pixels) Render a `PangoLayoutLine` onto a FreeType2 bitmap a FT_Bitmap to render the line onto a `PangoLayoutLine` the x position of start of string (in pixels) the y position of baseline (in pixels) Render a `PangoLayoutLine` onto a FreeType2 bitmap, with he location specified in fixed-point Pango units rather than pixels. (Using this will avoid extra inaccuracies from rounding to integer pixels multiple times, even if the final glyph positions are integers.) a FT_Bitmap to render the line onto a `PangoLayoutLine` the x position of start of string (in Pango units) the y position of baseline (in Pango units) Render a `PangoLayout` onto a FreeType2 bitmap, with he location specified in fixed-point Pango units rather than pixels. (Using this will avoid extra inaccuracies from rounding to integer pixels multiple times, even if the final glyph positions are integers.) a FT_Bitmap to render the layout onto a `PangoLayout` the X position of the left of the layout (in Pango units) the Y position of the top of the layout (in Pango units) Renders a `PangoGlyphString` onto a FreeType2 bitmap, possibly transforming the layed-out coordinates through a transformation matrix. Note that the transformation matrix for @font is not changed, so to produce correct rendering results, the @font must have been loaded using a `PangoContext` with an identical transformation matrix to that passed in to this function. the FreeType2 bitmap onto which to draw the string a `PangoMatrix` the font in which to draw the string the glyph string to draw the x position of the start of the string (in Pango units in user space coordinates) the y position of the baseline (in Pango units in user space coordinates) Free the global fontmap. (See pango_ft2_font_map_for_display()) Use of the global PangoFT2 fontmap is deprecated. soup3-0.9.0/gir-files/PangoFc-1.0.gir000064400000000000000000001177331046102023000151140ustar 00000000000000 `PangoFcDecoder` is a virtual base class that implementations will inherit from. It's the interface that is used to define a custom encoding for a font. These objects are created in your code from a function callback that was originally registered with [method@PangoFc.FontMap.add_decoder_find_func]. Pango requires information about the supported charset for a font as well as the individual character to glyph conversions. Pango gets that information via the #get_charset and #get_glyph callbacks into your object implementation. Generates an `FcCharSet` of supported characters for the @fcfont given. The returned `FcCharSet` will be a reference to an internal value stored by the `PangoFcDecoder` and must not be modified or freed. the `FcCharset` for @fcfont; must not be modified or freed. a `PangoFcDecoder` the `PangoFcFont` to query. Generates a `PangoGlyph` for the given Unicode point using the custom decoder. For complex scripts where there can be multiple glyphs for a single character, the decoder will return whatever glyph is most convenient for it. (Usually whatever glyph is directly in the fonts character map table.) the glyph index, or 0 if the glyph isn't covered by the font. a `PangoFcDecoder` a `PangoFcFont` to query. the Unicode code point to convert to a single `PangoGlyph`. Generates an `FcCharSet` of supported characters for the @fcfont given. The returned `FcCharSet` will be a reference to an internal value stored by the `PangoFcDecoder` and must not be modified or freed. the `FcCharset` for @fcfont; must not be modified or freed. a `PangoFcDecoder` the `PangoFcFont` to query. Generates a `PangoGlyph` for the given Unicode point using the custom decoder. For complex scripts where there can be multiple glyphs for a single character, the decoder will return whatever glyph is most convenient for it. (Usually whatever glyph is directly in the fonts character map table.) the glyph index, or 0 if the glyph isn't covered by the font. a `PangoFcDecoder` a `PangoFcFont` to query. the Unicode code point to convert to a single `PangoGlyph`. Class structure for `PangoFcDecoder`. This returns an `FcCharset` given a `PangoFcFont` that includes a list of supported characters in the font. The #FcCharSet that is returned should be an internal reference to your code. Pango will not free this structure. It is important that you make this callback fast because this callback is called separately for each character to determine Unicode coverage. the `FcCharset` for @fcfont; must not be modified or freed. a `PangoFcDecoder` the `PangoFcFont` to query. This returns a single `PangoGlyph` for a given Unicode code point. the glyph index, or 0 if the glyph isn't covered by the font. a `PangoFcDecoder` a `PangoFcFont` to query. the Unicode code point to convert to a single `PangoGlyph`. Callback function passed to [method@PangoFc.FontMap.add_decoder_find_func]. a new reference to a custom decoder for this pattern, or %NULL if the default decoder handling should be used. a fully resolved `FcPattern` specifying the font on the system user data passed to [method@PangoFc.FontMap.add_decoder_find_func] Fontconfig property that Pango reads from font patterns to populate list of OpenType features to be enabled for the font by default. The property will have a number of string elements, each of which is the OpenType feature tag of one feature to enable. This is equivalent to FC_FONT_FEATURES in versions of fontconfig that have that. Use FC_FONT_FEATURES Fontconfig property that Pango reads from font patterns to populate list of OpenType font variations to be used for a font. The property will have a string elements, each of which a comma-separated list of OpenType axis setting of the form AXIS=VALUE. This is equivalent to FC_FONT_VARIATIONS in versions of fontconfig that have that. Use FC_FONT_VARIATIONS `PangoFcFont` is a base class for font implementations using the Fontconfig and FreeType libraries. It is used in onjunction with [class@PangoFc.FontMap]. When deriving from this class, you need to implement all of its virtual functions other than shutdown() along with the get_glyph_extents() virtual function from `PangoFont`. Creates a `PangoFontDescription` that matches the specified Fontconfig pattern as closely as possible. Many possible Fontconfig pattern values, such as %FC_RASTERIZER or %FC_DPI, don't make sense in the context of `PangoFontDescription`, so will be ignored. a new `PangoFontDescription`. Free with pango_font_description_free(). a `FcPattern` if %TRUE, the pattern will include the size from the @pattern; otherwise the resulting pattern will be unsized. (only %FC_SIZE is examined, not %FC_PIXEL_SIZE) Gets the glyph index for a given Unicode character for @font. If you only want to determine whether the font has the glyph, use [method@PangoFc.Font.has_char]. the glyph index, or 0, if the Unicode character doesn't exist in the font. a `PangoFcFont` Unicode character to look up Returns the languages that are supported by @font. This corresponds to the FC_LANG member of the FcPattern. The returned array is only valid as long as the font and its fontmap are valid. Use pango_font_get_language() a %NULL-terminated array of `PangoLanguage`* a `PangoFcFont` Returns the FcPattern that @font is based on. the fontconfig pattern for this font a `PangoFcFont` Returns the index of a glyph suitable for drawing @wc as an unknown character. Use PANGO_GET_UNKNOWN_GLYPH() instead. a glyph index into @font. a `PangoFcFont` the Unicode character for which a glyph is needed. Determines whether @font has a glyph for the codepoint @wc. Use [method@Pango.Font.has_char] %TRUE if @font has the requested codepoint. a `PangoFcFont` Unicode codepoint to look up This function used to adjust each adjacent pair of glyphs in @glyphs according to kerning information in @font. Since 1.44, it does nothing. a `PangoFcFont` a `PangoGlyphString` Gets the FreeType `FT_Face` associated with a font. This face will be kept around until you call [method@PangoFc.Font.unlock_face]. Use pango_font_get_hb_font() instead the FreeType `FT_Face` associated with @font. a `PangoFcFont`. Releases a font previously obtained with [method@PangoFc.Font.lock_face]. Use pango_font_get_hb_font() instead a `PangoFcFont`. The PangoFc font map this font is associated with. The fontconfig pattern for this font. `PangoFcFontMap` is a base class for font map implementations using the Fontconfig and FreeType libraries. It is used in the Xft and FreeType backends shipped with Pango, but can also be used when creating new backends. Any backend deriving from this base class will take advantage of the wide range of shapers implemented using FreeType that come with Pango. This function saves a callback method in the `PangoFcFontMap` that will be called whenever new fonts are created. If the function returns a `PangoFcDecoder`, that decoder will be used to determine both coverage via a `FcCharSet` and a one-to-one mapping of characters to glyphs. This will allow applications to have application-specific encodings for various fonts. The `PangoFcFontMap` to add this method to. The `PangoFcDecoderFindFunc` callback function User data. A `GDestroyNotify` callback that will be called when the fontmap is finalized and the decoder is released. Clear all cached information and fontsets for this font map. This should be called whenever there is a change in the output of the default_substitute() virtual function of the font map, or if fontconfig has been reinitialized to new configuration. a `PangoFcFontMap` Informs font map that the fontconfig configuration (i.e., the `FcConfig` object) used by this font map has changed. This currently calls [method@PangoFc.FontMap.cache_clear] which ensures that list of fonts, etc will be regenerated using the updated configuration. a `PangoFcFontMap` Creates a new context for this fontmap. This function is intended only for backend implementations deriving from `PangoFcFontMap`; it is possible that a backend will store additional information needed for correct operation on the `PangoContext` after calling this function. Use pango_font_map_create_context() instead. a new `PangoContext` a `PangoFcFontMap` Finds the decoder to use for @pattern. Decoders can be added to a font map using [method@PangoFc.FontMap.add_decoder_find_func]. a newly created `PangoFcDecoder` object or %NULL if no decoder is set for @pattern. The `PangoFcFontMap` to use. The `FcPattern` to find the decoder for. Fetches the `FcConfig` attached to a font map. See also: [method@PangoFc.FontMap.set_config]. the `FcConfig` object attached to @fcfontmap, which might be %NULL. The return value is owned by Pango and should not be freed. a `PangoFcFontMap` Retrieves the `hb_face_t` for the given `PangoFcFont`. the `hb_face_t` for the given font a `PangoFcFontMap` a `PangoFcFont` Set the `FcConfig` for this font map to use. The default value is `NULL`, which causes Fontconfig to use its global "current config". You can create a new `FcConfig` object and use this API to attach it to a font map. This is particularly useful for example, if you want to use application fonts with Pango. For that, you would create a fresh `FcConfig`, add your app fonts to it, and attach it to a new Pango font map. If @fcconfig is different from the previous config attached to the font map, [method@PangoFc.FontMap.config_changed] is called. This function acquires a reference to the `FcConfig` object; the caller does **not** need to retain a reference. See [method@Pango.FontMap.add_font_file] for a backend-independent way of using application fonts with Pango. a `PangoFcFontMap` a `FcConfig` Sets a function that will be called to do final configuration substitution on a `FcPattern` before it is used to load the font. This function can be used to do things like set hinting and antialiasing options. a `PangoFcFontMap` function to call to to do final config tweaking on `FcPattern` objects data to pass to @func function to call when @data is no longer used Clears all cached information for the fontmap and marks all fonts open for the fontmap as dead. See the shutdown() virtual function of `PangoFcFont`. This function might be used by a backend when the underlying windowing system for the font map exits. This function is only intended to be called only for backend implementations deriving from `PangoFcFontMap`. a `PangoFcFontMap` Call this function any time the results of the default substitution function set with [method@PangoFc.FontMap.set_default_substitute] change. That is, if your substitution function will return different results for the same input pattern, you must call this function. a `PangoFcFontMap` Fontconfig property that Pango sets on any fontconfig pattern it passes to fontconfig if a `PangoGravity` other than %PANGO_GRAVITY_SOUTH is desired. The property will have a `PangoGravity` value as a string, like "east". This can be used to write fontconfig configuration rules to choose different fonts for horizontal and vertical writing directions. Fontconfig property that Pango sets on any fontconfig pattern it passes to fontconfig. The property will have a string equal to what g_get_prgname() returns. This can be used to write fontconfig configuration rules that only affect certain applications. This is equivalent to FC_PRGNAME in versions of fontconfig that have that. Use FC_PRGNAME Function type for doing final config tweaking on prepared `FcPattern`s. the FcPattern to tweak. user data. Fontconfig property that Pango sets on any fontconfig pattern it passes to fontconfig. The property will have an integer value equal to what [func@Pango.version] returns. This can be used to write fontconfig configuration rules that only affect certain pango versions (or only pango-using applications, or only non-pango-using applications). soup3-0.9.0/gir-files/PangoOT-1.0.gir000064400000000000000000001436621046102023000151060ustar 00000000000000 The `PangoOTTag` typedef is used to represent TrueType and OpenType four letter tags inside Pango. Use PANGO_OT_TAG_MAKE() or PANGO_OT_TAG_MAKE_FROM_STRING() macros to create PangoOTTags manually. This is used as the property bit in pango_ot_ruleset_add_feature() when a feature should be applied to all glyphs. Creates a new `PangoOTBuffer` for the given OpenType font. the newly allocated `PangoOTBuffer`, which should be freed with [method@PangoOT.Buffer.destroy]. a `PangoFcFont` Appends a glyph to a `PangoOTBuffer`, with @properties identifying which features should be applied on this glyph. See [method@PangoOT.Ruleset.add_feature]. a `PangoOTBuffer` the glyph index to add, like a `PangoGlyph` the glyph properties the cluster that this glyph belongs to Empties a `PangoOTBuffer`, make it ready to add glyphs to. a `PangoOTBuffer` Destroys a `PangoOTBuffer` and free all associated memory. a `PangoOTBuffer` Gets the glyph array contained in a `PangoOTBuffer`. The glyphs are owned by the buffer and should not be freed, and are only valid as long as buffer is not modified. a `PangoOTBuffer` location to store the array of glyphs location to store the number of glyphs Exports the glyphs in a `PangoOTBuffer` into a `PangoGlyphString`. This is typically used after the OpenType layout processing is over, to convert the resulting glyphs into a generic Pango glyph string. a `PangoOTBuffer` a `PangoGlyphString` Sets whether glyphs will be rendered right-to-left. This setting is needed for proper horizontal positioning of right-to-left scripts. a `PangoOTBuffer` %TRUE for right-to-left text Sets whether characters with a mark class should be forced to zero width. This setting is needed for proper positioning of Arabic accents, but will produce incorrect results with standard OpenType Indic fonts. a `PangoOTBuffer` %TRUE if characters with a mark class should be forced to zero width This is used as the language index in pango_ot_info_find_feature() when the default language system of the script is desired. It is also returned by pango_ot_info_find_language() if the requested language is not found, or the requested language tag was PANGO_OT_TAG_DEFAULT_LANGUAGE. The end result is that one can always call pango_ot_tag_from_language() followed by pango_ot_info_find_language() and pass the result to pango_ot_info_find_feature() without having to worry about falling back to default language system explicitly. The `PangoOTFeatureMap` typedef is used to represent an OpenType feature with the property bit associated with it. The feature tag is represented as a char array instead of a `PangoOTTag` for convenience. feature tag in represented as four-letter ASCII string. the property bit to use for this feature. See pango_ot_ruleset_add_feature() for details. The `PangoOTGlyph` structure represents a single glyph together with information used for OpenType layout processing of the glyph. It contains the following fields. the glyph itself. the properties value, identifying which features should be applied on this glyph. See pango_ot_ruleset_add_feature(). the cluster that this glyph belongs to. a component value, set by the OpenType layout engine. a ligature index value, set by the OpenType layout engine. for Pango internal use Returns the `PangoOTInfo` structure for the given FreeType font face. the `PangoOTInfo` for @face. This object will have the same lifetime as @face. a `FT_Face` Finds the index of a feature. If the feature is not found, sets @feature_index to PANGO_OT_NO_FEATURE, which is safe to pass to [method@PangoOT.Ruleset.add_feature] and similar functions. In the future, this may set @feature_index to an special value that if used in [method@PangoOT.Ruleset.add_feature] will ask Pango to synthesize the requested feature based on Unicode properties and data. However, this function will still return %FALSE in those cases. So, users may want to ignore the return value of this function in certain cases. %TRUE if the feature was found a `PangoOTInfo` the table type to obtain information about the tag of the feature to find the index of the script the index of the language whose features are searched, or %PANGO_OT_DEFAULT_LANGUAGE to use the default language of the script location to store the index of the feature Finds the index of a language and its required feature index. If the language is not found, sets @language_index to %PANGO_OT_DEFAULT_LANGUAGE and the required feature of the default language system is returned in required_feature_index. For best compatibility with some fonts, also searches the language system tag 'dflt' before falling back to the default language system, but that is transparent to the user. The user can simply ignore the return value of this function to automatically fall back to the default language system. %TRUE if the language was found a `PangoOTInfo` the table type to obtain information about the index of the script whose languages are searched the tag of the language to find location to store the index of the language location to store the required feature index of the language Finds the index of a script. If not found, tries to find the 'DFLT' and then 'dflt' scripts and return the index of that in @script_index. If none of those is found either, %PANGO_OT_NO_SCRIPT is placed in @script_index. All other functions taking an input script_index parameter know how to handle %PANGO_OT_NO_SCRIPT, so one can ignore the return value of this function completely and proceed, to enjoy the automatic fallback to the 'DFLT'/'dflt' script. %TRUE if the script was found a `PangoOTInfo` the table type to obtain information about the tag of the script to find location to store the index of the script Obtains the list of features for the given language of the given script. a newly-allocated zero-terminated array containing the tags of the available features a `PangoOTInfo` the table type to obtain information about unused parameter the index of the script to obtain information about the index of the language to list features for, or %PANGO_OT_DEFAULT_LANGUAGE, to list features for the default language of the script Obtains the list of available languages for a given script. a newly-allocated zero-terminated array containing the tags of the available languages a `PangoOTInfo` the table type to obtain information about the index of the script to list languages for unused parameter Obtains the list of available scripts. a newly-allocated zero-terminated array containing the tags of the available scripts a `PangoOTInfo` the table type to obtain information about This is used as a feature index that represent no feature, that is, should be skipped. It may be returned as feature index by pango_ot_info_find_feature() if the feature is not found, and pango_ot_ruleset_add_feature() function automatically skips this value, so no special handling is required by the user. This is used as a script index that represent no script, that is, when the requested script was not found, and a default ('DFLT') script was not found either. It may be returned as script index by pango_ot_info_find_script() if the script or a default script are not found, all other functions taking a script index essentially return if the input script index is this value, so no special handling is required by the user. The `PangoOTRuleset` structure holds a set of features selected from the tables in an OpenType font. A feature is an operation such as adjusting glyph positioning that should be applied to a text feature such as a certain type of accent. A `PangoOTRuleset` is created with [ctor@PangoOT.Ruleset.new], features are added to it with [method@PangoOT.Ruleset.add_feature], then it is applied to a `PangoGlyphString` with [method@PangoOT.Ruleset.position]. Creates a new `PangoOTRuleset` for the given OpenType info. the newly allocated `PangoOTRuleset` a `PangoOTInfo` Creates a new `PangoOTRuleset` for the given OpenType info, script, and language. This function is part of a convenience scheme that highly simplifies using a `PangoOTRuleset` to represent features for a specific pair of script and language. So one can use this function passing in the script and language of interest, and later try to add features to the ruleset by just specifying the feature name or tag, without having to deal with finding script, language, or feature indices manually. In addition to what [ctor@PangoOT.Ruleset.new] does, this function will: * Find the `PangoOTTag` script and language tags associated with @script and @language using [func@PangoOT.tag_from_script] and [func@PangoOT.tag_from_language], * For each of table types %PANGO_OT_TABLE_GSUB and %PANGO_OT_TABLE_GPOS, find the script index of the script tag found and the language system index of the language tag found in that script system, using [method@PangoOT.Info.find_script] and [method@PangoOT.Info.find_language], * For found language-systems, if they have required feature index, add that feature to the ruleset using [method@PangoOT.Ruleset.add_feature], * Remember found script and language indices for both table types, and use them in future [method@PangoOT.Ruleset.maybe_add_feature] and [method@PangoOT.Ruleset.maybe_add_features]. Because of the way return values of [method@PangoOT.Info.find_script] and [method@PangoOT.Info.find_language] are ignored, this function automatically finds and uses the 'DFLT' script and the default language-system. the newly allocated `PangoOTRuleset` a `PangoOTInfo` a `PangoScript` a `PangoLanguage` Creates a new `PangoOTRuleset` for the given OpenType info and matching the given ruleset description. This is a convenience function that calls [ctor@PangoOT.Ruleset.new_for] and adds the static GSUB/GPOS features to the resulting ruleset, followed by adding other features to both GSUB and GPOS. The static feature map members of @desc should be alive as long as @info is. the newly allocated `PangoOTRuleset` a `PangoOTInfo` a `PangoOTRulesetDescription` Returns a ruleset for the given OpenType info and ruleset description. Rulesets are created on demand using [ctor@PangoOT.Ruleset.new_from_description]. The returned ruleset should not be modified or destroyed. The static feature map members of @desc should be alive as long as @info is. the `PangoOTRuleset` for @desc. This object will have the same lifetime as @info. a `PangoOTInfo` a `PangoOTRulesetDescription` Adds a feature to the ruleset. a `PangoOTRuleset` the table type to add a feature to the index of the feature to add the property bit to use for this feature. Used to identify the glyphs that this feature should be applied to, or %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs. Gets the number of GSUB and GPOS features in the ruleset. Total number of features in the @ruleset a `PangoOTRuleset` location to store number of GSUB features location to store number of GPOS features This is a convenience function that first tries to find the feature using [method@PangoOT.Info.find_feature] and the ruleset script and language passed to [ctor@PangoOT.Ruleset.new_for] and if the feature is found, adds it to the ruleset. If @ruleset was not created using [ctor@PangoOT.Ruleset.new_for], this function does nothing. %TRUE if the feature was found and added to ruleset, %FALSE otherwise a `PangoOTRuleset` the table type to add a feature to the tag of the feature to add the property bit to use for this feature. Used to identify the glyphs that this feature should be applied to, or %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs. This is a convenience function that for each feature in the feature map array @features converts the feature name to a `PangoOTTag` feature tag using PANGO_OT_TAG_MAKE() and calls [method@PangoOT.Ruleset.maybe_add_feature] on it. The number of features in @features that were found and added to @ruleset a `PangoOTRuleset` the table type to add features to array of feature name and property bits to add number of feature records in @features array Performs the OpenType GPOS positioning on @buffer using the features in @ruleset. a `PangoOTRuleset` a `PangoOTBuffer` Performs the OpenType GSUB substitution on @buffer using the features in @ruleset. a `PangoOTRuleset` a `PangoOTBuffer` The `PangoOTRuleset` structure holds all the information needed to build a complete `PangoOTRuleset` from an OpenType font. The main use of this struct is to act as the key for a per-font hash of rulesets. The user populates a ruleset description and gets the ruleset using pango_ot_ruleset_get_for_description() or create a new one using pango_ot_ruleset_new_from_description(). a `PangoScript` a `PangoLanguage` static map of GSUB features length of @static_gsub_features, or 0. static map of GPOS features length of @static_gpos_features, or 0. map of extra features to add to both GSUB and GPOS. Unlike the static maps, this pointer need not live beyond the life of function calls taking this struct. length of @other_features, or 0. Creates a copy of @desc, which should be freed with [method@PangoOT.RulesetDescription.free]. Primarily used internally by [func@PangoOT.Ruleset.get_for_description] to cache rulesets for ruleset descriptions. the newly allocated `PangoOTRulesetDescription` ruleset description to copy Compares two ruleset descriptions for equality. Two ruleset descriptions are considered equal if the rulesets they describe are provably identical. This means that their script, language, and all feature sets should be equal. For static feature sets, the array addresses are compared directly, while for other features, the list of features is compared one by one.(Two ruleset descriptions may result in identical rulesets being created, but still compare %FALSE.) %TRUE if two ruleset descriptions are identical, %FALSE otherwise a ruleset description a ruleset description Frees a ruleset description allocated by pango_ot_ruleset_description_copy(). an allocated `PangoOTRulesetDescription` Computes a hash of a `PangoOTRulesetDescription` structure suitable to be used, for example, as an argument to g_hash_table_new(). the hash value a ruleset description Creates a `PangoOTTag` from four characters. This is similar and compatible with the FT_MAKE_TAG() macro from FreeType. First character. Second character. Third character. Fourth character. Creates a `PangoOTTag` from a string. The string should be at least four characters long (pad with space characters if needed), and need not be nul-terminated. This is a convenience wrapper around PANGO_OT_TAG_MAKE(), but cannot be used in certain situations, for example, as a switch expression, as it dereferences pointers. The string representation of the tag. The PangoOTTableType enumeration values are used to identify the various OpenType tables in the pango_ot_info_… functions. The GSUB table. The GPOS table. Finds the OpenType language-system tag best describing @language. `PangoOTTag` best matching @language or %PANGO_OT_TAG_DEFAULT_LANGUAGE if none found or if @language is %NULL. A `PangoLanguage` Finds the OpenType script tag corresponding to @script. The %PANGO_SCRIPT_COMMON, %PANGO_SCRIPT_INHERITED, and %PANGO_SCRIPT_UNKNOWN scripts are mapped to the OpenType 'DFLT' script tag that is also defined as %PANGO_OT_TAG_DEFAULT_SCRIPT. Note that multiple `PangoScript` values may map to the same OpenType script tag. In particular, %PANGO_SCRIPT_HIRAGANA and %PANGO_SCRIPT_KATAKANA both map to the OT tag 'kana'. `PangoOTTag` corresponding to @script or %PANGO_OT_TAG_DEFAULT_SCRIPT if none found. A `PangoScript` Finds a `PangoLanguage` corresponding to @language_tag. `PangoLanguage` best matching @language_tag or `PangoLanguage` corresponding to the string "xx" if none found. A `PangoOTTag` OpenType language-system tag Finds the `PangoScript` corresponding to @script_tag. The 'DFLT' script tag is mapped to %PANGO_SCRIPT_COMMON. Note that an OpenType script tag may correspond to multiple `PangoScript` values. In such cases, the `PangoScript` value with the smallest value is returned. In particular, %PANGO_SCRIPT_HIRAGANA and %PANGO_SCRIPT_KATAKANA both map to the OT tag 'kana'. This function will return %PANGO_SCRIPT_HIRAGANA for 'kana'. `PangoScript` corresponding to @script_tag or %PANGO_SCRIPT_UNKNOWN if none found. A `PangoOTTag` OpenType script tag soup3-0.9.0/gir-files/PangoXft-1.0.gir000064400000000000000000000770511046102023000153230ustar 00000000000000 `PangoXftFont` is an implementation of `PangoFcFont` using the Xft library for rendering. It is used in conjunction with `PangoXftFontMap`. Returns the `XftFont` of a font. the `XftFont` associated to @font a `PangoFont` Returns the X display of the `XftFont` of a font. the X display of the XftFont associated to @font. a `PangoFont` Gets the glyph index for a given Unicode character for @font. If you only want to determine whether the font has the glyph, use pango_xft_font_has_char(). Use pango_fc_font_get_glyph() instead. the glyph index, or 0, if the Unicode character does not exist in the font. a `PangoFont` for the Xft backend Unicode codepoint to look up Returns the index of a glyph suitable for drawing @wc as an unknown character. Use PANGO_GET_UNKNOWN_GLYPH() instead. a glyph index into @font. a `PangoFont` the Unicode character for which a glyph is needed. Determines whether @font has a glyph for the codepoint @wc. Use pango_fc_font_has_char() instead. %TRUE if @font has the requested codepoint. a `PangoFont` for the Xft backend Unicode codepoint to look up Gets the FreeType `FT_Face` associated with a font. This face will be kept around until you call pango_xft_font_unlock_face(). Use pango_fc_font_lock_face() instead. the FreeType `FT_Face` associated with @font. a `PangoFont` Releases a font previously obtained with pango_xft_font_lock_face(). Use pango_fc_font_unlock_face() instead. a `PangoFont` `PangoXftFontMap` is an implementation of `PangoFcFontMap` suitable for the Xft library as the renderer. It is used in to create fonts of type `PangoXftFont`. `PangoXftRenderer` is a subclass of `PangoRenderer` used for rendering with Pango's Xft backend. It can be used directly, or it can be further subclassed to modify exactly how drawing of individual elements occurs. Create a new `PangoXftRenderer` to allow rendering Pango objects with the Xft library. You must call pango_xft_renderer_set_draw() before using the renderer. the newly created `PangoXftRenderer` an X display the index of the screen for @display to which rendering will be done Sets the default foreground color for a XftRenderer. a XftRenderer the default foreground color Sets the XftDraw object that the renderer is drawing to. The renderer must not be currently active. a `PangoXftRenderer` a XftDraw The class structure for `PangoXftRenderer` Function type for doing final config tweaking on prepared FcPatterns. the FcPattern to tweak. user data. Retrieves a `PangoContext` appropriate for rendering with Xft fonts on the given screen of the given display. Use pango_xft_get_font_map() followed by pango_font_map_create_context() instead. the new `PangoContext`. an X display. an X screen. Returns the `PangoXftFontMap` for the given display and screen. The fontmap is owned by Pango and will be valid until the display is closed. a `PangoFontMap` object, owned by Pango. an X display the screen number of a screen within @display Renders a `PangoGlyphString` onto an Xrender Picture object. an X display the source picture to draw the string with the destination picture to draw the string onto the font in which to draw the string the glyph string to draw the x position of start of string (in pixels) the y position of baseline (in pixels) Renders a `PangoGlyphString` onto an XftDraw object wrapping an X drawable. the XftDraw object. the color in which to draw the string the font in which to draw the string the glyph string to draw the x position of start of string (in pixels) the y position of baseline (in pixels) Render a `PangoLayout` onto a XftDraw an XftDraw the foreground color in which to draw the layout (may be overridden by color attributes) a `PangoLayout` the X position of the left of the layout (in Pango units) the Y position of the top of the layout (in Pango units) Render a `PangoLayoutLine` onto a XftDraw an XftDraw the foreground color in which to draw the layout line (may be overridden by color attributes) a `PangoLayoutLine` the x position of start of string (in Pango units) the y position of baseline (in Pango units) Renders a `PangoGlyphString` onto a XftDraw, possibly transforming the layed-out coordinates through a transformation matrix. Note that the transformation matrix for @font is not changed, so to produce correct rendering results, the @font must have been loaded using a `PangoContext` with an identical transformation matrix to that passed in to this function. an XftDraw the color in which to draw the glyphs a `PangoMatrix` the font in which to draw the string the glyph string to draw the x position of the start of the string (in Pango units in user space coordinates) the y position of the baseline (in Pango units in user space coordinates) Sets a function that will be called to do final configuration substitution on a #FcPattern before it is used to load the font. This function can be used to do things like set hinting and antialiasing options. Use pango_fc_font_map_set_default_substitute() instead. an X Display the screen number of a screen within @display function to call to to do final config tweaking on #FcPattern objects. data to pass to @func function to call when @data is no longer used. Release any resources that have been cached for the combination of @display and @screen. Note that when the X display is closed, resources are released automatically, without needing to call this function. an X display the screen number of a screen within @display Call this function any time the results of the default substitution function set with pango_xft_set_default_substitute() change. That is, if your substitution function will return different results for the same input pattern, you must call this function. Use pango_fc_font_map_substitute_changed() instead. an X Display the screen number of a screen within @display soup3-0.9.0/gir-files/README.md000064400000000000000000000027271046102023000140530ustar 00000000000000# gir-files This repository contains the [GIR](https://developer.gnome.org/documentation/guidelines/programming/introspection.html) files used to generate all [`gtk-rs`](https://github.com/gtk-rs/gtk-rs) crates. ## Updating all files You can update all the files by doing: ```console $ flatpak remote-add --user --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo $ flatpak install org.gnome.Sdk//master -y --noninteractive $ flatpak run --command=python3 --filesystem=home org.gnome.Sdk//master dl.py $ ./reformat.sh && ./fix.sh ``` This command will fetch the gir files for the latest release of each library. When updating all files, make sure you do not inadvertedly overwrite gir files which were manually updated and which have not yet been included in a release of the corresponding library. ## Updating a gir file manually In general we prefer to use gir files that have been included in a release, however sometimes it is required to update a specific gir files to incorporate a bug fix or a missing API. Manually copy the updated gir file and then run ```console $ ./reformat.sh $ ./fix.sh ``` ## Validating an update After updating the gir files, please don't forget to check that [`gir`](https://github.com/gtk-rs/gir) can still run with the new files and that the generated files have no breaking changes. Refer to the [`gtk-rs`](https://github.com/gtk-rs/gtk-rs) README file for further information about regenerating the `gtk-rs` crates. soup3-0.9.0/gir-files/Vulkan-1.0.gir000064400000000000000000004663651046102023000150470ustar 00000000000000 soup3-0.9.0/gir-files/cairo-1.0.gir000064400000000000000000000526001046102023000146630ustar 00000000000000 soup3-0.9.0/gir-files/dl-gtk-macos.py000064400000000000000000000046741046102023000154330ustar 00000000000000import os import zipfile import shutil import gitlab GITLAB_URL = "https://gitlab.gnome.org" PROJECT_ID = 665 # GNOME/GTK project JOB_NAME = "macos: [macosarm]" ARTIFACT_NAME = "artifacts.zip" SAVE_PATH = "./" TARGET_FILE = "_build/gtk/GdkMacos-4.0.gir" PERSONAL_ACCESS_TOKEN = os.environ.get("GITLAB_KEY") if not PERSONAL_ACCESS_TOKEN: raise RuntimeError("GITLAB_KEY environment variable is not set") def download_and_extract_artifact(job, target_file, destination_path): artifact_path = os.path.join(SAVE_PATH, ARTIFACT_NAME) # Download artifacts archive with open(artifact_path, "wb") as f: job.artifacts(streamed=True, action=f.write) print(f"Artifact saved to: {artifact_path}") try: temp_dir = os.path.join(os.path.dirname(artifact_path), "temp_extracted") os.makedirs(temp_dir, exist_ok=True) with zipfile.ZipFile(artifact_path, "r") as zip_ref: zip_ref.extractall(temp_dir) target_file_path = os.path.join(temp_dir, target_file) if os.path.exists(target_file_path): shutil.copy(target_file_path, destination_path) print(f"Copied '{target_file_path}' to '{destination_path}'.") else: print(f"File '{target_file}' not found in the extracted contents.") finally: shutil.rmtree(temp_dir, ignore_errors=True) if os.path.exists(artifact_path): os.remove(artifact_path) print("Temporary files cleaned up.") def main(): gl = gitlab.Gitlab( GITLAB_URL, private_token=PERSONAL_ACCESS_TOKEN, ) project = gl.projects.get(PROJECT_ID) pipelines = project.pipelines.list( order_by="updated_at", sort="desc", per_page=20, ) if not pipelines: raise RuntimeError("No pipelines found") for pipeline in pipelines: pipeline = project.pipelines.get(pipeline.id) jobs = pipeline.jobs.list(all=True) for job in jobs: if job.name != JOB_NAME: continue if job.status != "success": continue if not job.artifacts_file: continue print(f"Job '{job.name}' succeeded (Job ID: {job.id}).") download_and_extract_artifact( job, TARGET_FILE, "./", ) return print("No successful job with artifacts found.") if __name__ == "__main__": main() soup3-0.9.0/gir-files/dl-win32.sh000075500000000000000000000014171046102023000144650ustar 00000000000000#!/usr/bin/env sh GTK_VERSION=$(wget -qO- "https://packages.msys2.org/api/search?query=gtk4" | jq -r ".results.exact.version") wget -qO- "https://mirror.msys2.org/mingw/ucrt64/mingw-w64-ucrt-x86_64-gtk4-$GTK_VERSION-any.pkg.tar.zst" | \ zstdcat - | tar xO "ucrt64/share/gir-1.0/GdkWin32-4.0.gir" > GdkWin32-4.0.gir # -x ucrt64/share/gir-1.0/GLibWin32-2.0.gir -x ucrt64/share/gir-1.0/GioWin32-2.0.gir GLIB_VERSION=$(wget -qO- "https://packages.msys2.org/api/search?query=glib2" | jq -r ".results.exact.version") wget -qO- "https://mirror.msys2.org/mingw/ucrt64/mingw-w64-ucrt-x86_64-glib2-$GLIB_VERSION-any.pkg.tar.zst" | \ zstdcat - | tar -x "ucrt64/share/gir-1.0/GLibWin32-2.0.gir" -x "ucrt64/share/gir-1.0/GioWin32-2.0.gir" mv ucrt64/share/gir-1.0/*.gir . rm -r ucrt64 soup3-0.9.0/gir-files/dl.py000075500000000000000000000017061046102023000135440ustar 00000000000000#!/usr/bin/env python3 import os import shutil GIR_FILES = [ "Atk-1.0", "cairo-1.0", "fontconfig-2.0", "freetype2-2.0", "Gdk-3.0", "Gdk-4.0", "GdkPixbuf-2.0", "GdkPixdata-2.0", "GdkWayland-4.0", "GdkX11-3.0", "GdkX11-4.0", "Gio-2.0", "GioUnix-2.0", "GL-1.0", "GLib-2.0", "GLibUnix-2.0", "GModule-2.0", "GObject-2.0", "Graphene-1.0", "Gsk-4.0", "Gtk-3.0", "Gtk-4.0", "HarfBuzz-0.0", "libxml2-2.0", "Pango-1.0", "PangoCairo-1.0", "PangoFc-1.0", "PangoFT2-1.0", "PangoOT-1.0", "PangoXft-1.0", "Vulkan-1.0", "win32-1.0", "xfixes-4.0", "xft-2.0", "xlib-2.0", "xrandr-1.3", ] dest_dir = os.path.abspath("./") for file in GIR_FILES: src = f"/usr/share/gir-1.0/{file}.gir" dest = f"{dest_dir}/{file}.gir" try: shutil.copy(src, dest) except FileNotFoundError: print(f"gir file not found {file}") soup3-0.9.0/gir-files/fix.sh000075500000000000000000000314421046102023000137150ustar 00000000000000#!/bin/bash set -x -e # Remove Int32 alias because it misses c:type, it not like anyone actually cares about it. xmlstarlet ed -L \ -d '///_:alias[@name="Int32"]' \ freetype2-2.0.gir # gir uses error domain to find quark function corresponding to given error enum, # but in this case it happens to be named differently, i.e., as g_option_error_quark. xmlstarlet ed -L \ -u '//*[@glib:error-domain="g-option-context-error-quark"]/@glib:error-domain' -v g-option-error-quark \ GLib-2.0.gir # GtkEntry icon signals incorrect assume GdkEventButton when other variants may be passed xmlstarlet ed -L \ -u '//_:class[@name="Entry"]/glib:signal[@name="icon-press"]//_:parameter[@name="event"]/_:type[@name="Gdk.EventButton"]/@name' -v "Gdk.Event" \ -u '//_:class[@name="Entry"]/glib:signal[@name="icon-release"]//_:parameter[@name="event"]/_:type[@name="Gdk.EventButton"]/@name' -v "Gdk.Event" \ Gtk-3.0.gir # GtkIconSize usage xmlstarlet ed -L \ -u '//_:type[@c:type="GtkIconSize"]/@name' -v "IconSize" \ -u '//_:type[@c:type="GtkIconSize*"]/@name' -v "IconSize" \ Gtk-3.0.gir # incorrect GIR due to gobject-introspection GitLab issue #189 xmlstarlet ed -L \ -u '//_:class[@name="IconTheme"]/_:method//_:parameter[@name="icon_names"]/_:array/@c:type' -v "const gchar**" \ -u '//_:class[@name="IconTheme"]/_:method[@name="get_search_path"]//_:parameter[@name="path"]/_:array/@c:type' -v "gchar***" \ -u '//_:class[@name="IconTheme"]/_:method[@name="set_search_path"]//_:parameter[@name="path"]/_:array/@c:type' -v "const gchar**" \ Gtk-3.0.gir # incorrect GIR due to gobject-introspection GitLab issue #189 xmlstarlet ed -L \ -u '//_:record[@name="KeyFile"]/_:method[@name="set_boolean_list"]//_:parameter[@name="list"]/_:array/@c:type' -v "gboolean*" \ -u '//_:record[@name="KeyFile"]/_:method[@name="set_double_list"]//_:parameter[@name="list"]/_:array/@c:type' -v "gdouble*" \ -u '//_:record[@name="KeyFile"]/_:method[@name="set_integer_list"]//_:parameter[@name="list"]/_:array/@c:type' -v "gint*" \ -u '//_:record[@name="KeyFile"]/_:method[@name="set_locale_string_list"]//_:parameter[@name="list"]/_:array/@c:type' -v "const gchar* const*" \ -u '//_:record[@name="KeyFile"]/_:method[@name="set_string_list"]//_:parameter[@name="list"]/_:array/@c:type' -v "const gchar* const*" \ GLib-2.0.gir # incorrect GIR due to gobject-introspection GitLab issue #189 xmlstarlet ed -L \ -u '//_:class[@name="Object"]/_:method[@name="getv"]//_:parameter[@name="names"]/_:array/@c:type' -v "const gchar**" \ -u '//_:class[@name="Object"]/_:method[@name="getv"]//_:parameter[@name="values"]/_:array/@c:type' -v "GValue*" \ -u '//_:class[@name="Object"]/_:method[@name="setv"]//_:parameter[@name="names"]/_:array/@c:type' -v "const gchar**" \ -u '//_:class[@name="Object"]/_:method[@name="setv"]//_:parameter[@name="values"]/_:array/@c:type' -v "const GValue*" \ -u '//_:class[@name="Object"]/_:constructor[@name="new_with_properties"]//_:parameter[@name="names"]/_:array/@c:type' -v "const char**" \ -u '//_:class[@name="Object"]/_:constructor[@name="new_with_properties"]//_:parameter[@name="values"]/_:array/@c:type' -v "const GValue*" \ GObject-2.0.gir # add missing attributes to resolve type struct for TypePlugin xmlstarlet ed -L \ -i '//_:interface[@name="TypePlugin" and not(@glib:type-struct)]' -t 'attr' -n 'glib:type-struct' -v 'TypePluginClass' \ -i '//_:record[@name="TypePluginClass" and not(@glib:is-gtype-struct-for)]' -t 'attr' -n 'glib:is-gtype-struct-for' -v 'TypePlugin' \ GObject-2.0.gir # fix wrong "full" transfer ownership xmlstarlet ed -L \ -u '//_:method[@c:identifier="gdk_frame_clock_get_current_timings"]/_:return-value/@transfer-ownership' -v "none" \ -u '//_:method[@c:identifier="gdk_frame_clock_get_timings"]/_:return-value/@transfer-ownership' -v "none" \ Gdk-3.0.gir # replace gmodule with gpointer xmlstarlet ed -L \ -u '//_:record[@name="PixbufModule"]/_:field[@name="module"]/_:type/@name' -v "gpointer" \ -u '//_:record[@name="PixbufModule"]/_:field[@name="module"]/_:type/@c:type' -v "gpointer" \ GdkPixbuf-2.0.gir # replace "gint" response_id parameters with "ResponseType" xmlstarlet ed -L \ -u '//_:parameter[@name="response_id"]/_:type[@name="gint"]/@c:type' -v "GtkResponseType" \ -u '//_:parameter[@name="response_id"]/_:type[@name="gint"]/@name' -v "ResponseType" \ Gtk-3.0.gir Gtk-4.0.gir # fix wrong "full" transfer ownership xmlstarlet ed -L \ -u '//_:constructor[@c:identifier="gtk_shortcut_label_new"]/_:return-value/@transfer-ownership' -v "none" \ Gtk-3.0.gir # add out annotation for functions returning GValue xmlstarlet ed -L \ -a '//_:method[@c:identifier="gtk_style_context_get_style_property"]//_:parameter[@name="value" and not(@direction)]' -type attr -n "direction" -v "out" \ -a '//_:method[@c:identifier="gtk_style_context_get_style_property"]//_:parameter[@name="value" and not(@caller-allocates)]' -type attr -n "caller-allocates" -v "1" \ -a '//_:method[@c:identifier="gtk_cell_area_cell_get_property"]//_:parameter[@name="value" and not(@direction)]' -type attr -n "direction" -v "out" \ -a '//_:method[@c:identifier="gtk_cell_area_cell_get_property"]//_:parameter[@name="value" and not(@caller-allocates)]' -type attr -n "caller-allocates" -v "1" \ -a '//_:method[@c:identifier="gtk_container_child_get_property"]//_:parameter[@name="value" and not(@direction)]' -type attr -n "direction" -v "out" \ -a '//_:method[@c:identifier="gtk_container_child_get_property"]//_:parameter[@name="value" and not(@caller-allocates)]' -type attr -n "caller-allocates" -v "1" \ -a '//_:method[@c:identifier="gtk_widget_style_get_property"]//_:parameter[@name="value" and not(@direction)]' -type attr -n "direction" -v "out" \ -a '//_:method[@c:identifier="gtk_widget_style_get_property"]//_:parameter[@name="value" and not(@caller-allocates)]' -type attr -n "caller-allocates" -v "1" \ Gtk-3.0.gir # remove freetype and graphite methods; GitHub issue #2557 xmlstarlet ed -L \ -d '///_:function[@c:identifier="hb_graphite2_face_get_gr_face"]' \ -d '///_:function[@c:identifier="hb_graphite2_font_get_gr_font"]' \ -d '///_:function[@c:identifier="hb_ft_face_create"]' \ -d '///_:function[@c:identifier="hb_ft_face_create_cached"]' \ -d '///_:function[@c:identifier="hb_ft_face_create_referenced"]' \ -d '///_:function[@c:identifier="hb_ft_font_create"]' \ -d '///_:function[@c:identifier="hb_ft_font_create_cached"]' \ -d '///_:function[@c:identifier="hb_ft_font_create_referenced"]' \ -d '///_:function[@c:identifier="hb_ft_font_get_face"]' \ -d '///_:function[@c:identifier="hb_ft_font_lock_face"]' \ HarfBuzz-0.0.gir # fix harfbuzz types on Pango xmlstarlet ed -L \ -i '///_:type[not(@name) and @c:type="hb_font_t*"]' -t 'attr' -n 'name' -v "gconstpointer" \ -u '//_:type[@c:type="hb_font_t*"]/@c:type' -v "gconstpointer" \ -i '///_:array[not(@name) and @c:type="hb_feature_t*"]' -t 'attr' -n 'name' -v "gconstpointer" \ -r '///_:array[@c:type="hb_feature_t*"]' -v "type" \ -d '//_:type[@c:type="hb_feature_t*"]/*' \ -d '//_:type[@c:type="hb_feature_t*"]/@length' \ -d '//_:type[@c:type="hb_feature_t*"]/@zero-terminated' \ -u '//_:type[@c:type="hb_feature_t*"]/@c:type' -v "gconstpointer" \ Pango-1.0.gir # Fix unsupported bitfield (https://github.com/gtk-rs/gir/issues/465) on pango xmlstarlet ed -L \ -d '//_:record[@c:type="PangoGlyphVisAttr"]/_:field/@bits' \ -d '//_:record[@c:type="PangoGlyphVisAttr"]/_:field[@name="is_color"]' \ Pango-1.0.gir # Remove unstable method from focal release xmlstarlet ed -L \ -d '///_:method[@c:identifier="atk_plug_set_child"]' \ Atk-1.0.gir # fix non-existant c-types xmlstarlet ed -L \ -u '//_:class[@name="WaylandDevice"]/_:method[@name="get_wl_keyboard"]//_:type[@name="gpointer"]/@c:type' -v "gpointer" \ -u '//_:class[@name="WaylandDevice"]/_:method[@name="get_wl_pointer"]//_:type[@name="gpointer"]/@c:type' -v "gpointer" \ -u '//_:class[@name="WaylandDevice"]/_:method[@name="get_wl_seat"]//_:type[@name="gpointer"]/@c:type' -v "gpointer" \ -u '//_:class[@name="WaylandDisplay"]/_:method[@name="get_wl_compositor"]//_:type[@name="gpointer"]/@c:type' -v "gpointer" \ -u '//_:class[@name="WaylandDisplay"]/_:method[@name="get_wl_display"]//_:type[@name="gpointer"]/@c:type' -v "gpointer" \ -u '//_:class[@name="WaylandMonitor"]/_:method[@name="get_wl_output"]//_:type[@name="gpointer"]/@c:type' -v "gpointer" \ -u '//_:class[@name="WaylandSeat"]/_:method[@name="get_wl_seat"]//_:type[@name="gpointer"]/@c:type' -v "gpointer" \ -u '//_:class[@name="WaylandSurface"]/_:method[@name="get_wl_surface"]//_:type[@name="gpointer"]/@c:type' -v "gpointer" \ -u '//_:class[@name="WaylandDevice"]/_:method[@name="get_xkb_keymap"]//_:type[@name="gpointer"]/@c:type' -v "gpointer" \ -u '//_:class[@name="WaylandDevice"]/_:method[@name="get_xkb_keymap"]//_:type[@name="gpointer"]/@c:type' -v "gpointer" \ -u '//_:class[@name="WaylandToplevel"]/_:method[@name="get_xdg_toplevel"]//_:type[@name="gpointer"]/@c:type' -v "gpointer" \ GdkWayland-4.0.gir # avoid always depending on x11 crate xmlstarlet ed -L \ -u '//_:class[@name="X11Display"]/_:method[@name="get_xcursor"]//_:type[@name="xlib.Cursor"]/@c:type' -v "gulong" \ -u '//_:class[@name="X11Display"]/_:method[@name="get_xdisplay"]//_:type[@name="xlib.Display"]/@c:type' -v "gpointer" \ -u '//_:class[@name="X11Display"]/_:method[@name="get_xrootwindow"]//_:type[@name="xlib.Window"]/@c:type' -v "gulong" \ -u '//_:class[@name="X11Display"]/_:method[@name="get_xscreen"]//_:type[@name="xlib.Screen"]/@c:type' -v "gpointer" \ -u '//_:class[@name="X11Monitor"]/_:method[@name="get_output"]//_:type[@name="xlib.XID"]/@c:type' -v "gulong" \ -u '//_:class[@name="X11Screen"]/_:method[@name="get_monitor_output"]//_:type[@name="xlib.XID"]/@c:type' -v "gulong" \ -u '//_:class[@name="X11Screen"]/_:method[@name="get_xscreen"]//_:type[@name="xlib.Screen"]/@c:type' -v "gpointer" \ -u '//_:class[@name="X11Surface"]/_:method[@name="get_xid"]//_:type[@name="xlib.Window"]/@c:type' -v "gulong" \ -u '//_:class[@name="X11Surface"]/_:function[@name="lookup_for_display"]//_:type[@name="xlib.Window"]/@c:type' -v "gulong" \ -u '//_:class[@name="get_xid"]/_:method[@name="lookup_for_display"]//_:type[@name="xlib.Window"]/@c:type' -v "gulong" \ -u '//_:function[@name="x11_get_xatom_by_name_for_display"]//_:type[@name="xlib.Atom"]/@c:type' -v "gulong" \ -u '//_:function[@name="x11_get_xatom_name_for_display"]//_:type[@name="xlib.Atom"]/@c:type' -v "gulong" \ -u '//_:function[@name="x11_lookup_xdisplay"]//_:type[@name="xlib.Display"]/@c:type' -v "gpointer" \ GdkX11-4.0.gir xmlstarlet ed -L \ -u '//_:callback[@name="Win32MessageFilterFunc"]//_:type[@name="win32.MSG"]/@c:type' -v "gpointer" \ -u '//_:class[@name="Win32HCursor"]//_:type[@name="win32.HCURSOR"]/@c:type' -v "gssize" \ -u '//_:class[@name="Win32Surface"]//_:type[@name="win32.HGDIOBJ"]/@c:type' -v "gssize" \ -u '//_:class[@name="Win32Surface"]//_:type[@name="win32.HWND"]/@c:type' -v "gssize" \ -u '//_:function[@name="win32_handle_table_lookup"]//_:type[@name="win32.HWND"]/@c:type' -v 'gssize' \ -u '//_:function[@name="win32_set_modal_dialog_libgtk_only"]//_:type[@name="win32.HWND"]/@c:type' -v 'gssize' \ -u '//_:function[@name="win32_icon_to_pixbuf_libgtk_only"]//_:type[@name="win32.HICON"]/@c:type' -v 'gssize' \ -u '//_:function[@name="win32_pixbuf_to_hicon_libgtk_only"]//_:type[@name="win32.HICON"]/@c:type' -v 'gssize' \ -i '//_:type[@c:type="ID3D12Fence*" and not(@name)]' -t 'attr' -n 'name' -v "gpointer" \ -u '//_:type[@c:type="ID3D12Fence*"]/@c:type' -v "gpointer" \ -i '//_:type[@c:type="ID3D12Resource*" and not(@name)]' -t 'attr' -n 'name' -v "gpointer" \ -u '//_:type[@c:type="ID3D12Resource*"]/@c:type' -v "gpointer" \ GdkWin32-4.0.gir # Fix invalid type for GtkImage and GtkStackSwitcher "icon-size" property xmlstarlet ed -L \ -u '//_:class[@name="Image"]/_:property[@name="icon-size"]/_:type/@c:type' -v "GtkIconSize" \ -u '//_:class[@name="Image"]/_:property[@name="icon-size"]/_:type/@name' -v "IconSize" \ -u '//_:class[@name="StackSwitcher"]/_:property[@name="icon-size"]/_:type/@c:type' -v "GtkIconSize" \ -u '//_:class[@name="StackSwitcher"]/_:property[@name="icon-size"]/_:type/@name' -v "IconSize" \ Gtk-3.0.gir # Fix GLibUnix type names to use GLibUnix prefix instead of GLib xmlstarlet ed -L \ -u '//_:type[@name="GLib.UnixPipe"]/@name' -v "GLibUnix.Pipe" \ -u '//_:type[@name="GLib.UnixPipeEnd"]/@name' -v "GLibUnix.PipeEnd" \ GLibUnix-2.0.gir # Fix GLibWin32 type name to remove GLib prefix xmlstarlet ed -L \ -u '//_:type[@name="GLib.Win32OSType"]/@name' -v "OSType" \ GLibWin32-2.0.gir # Fix GioWin32 NetworkMonitor types to use gpointer xmlstarlet ed -L \ -i '//_:record[@name="NetworkMonitor"]/_:field[@name="parent_instance"]/_:type[@c:type="GNetworkMonitorBase" and not(@name)]' -t 'attr' -n 'name' -v "gpointer" \ -i '//_:record[@name="NetworkMonitorClass"]/_:field[@name="parent_class"]/_:type[@c:type="GNetworkMonitorBaseClass" and not(@name)]' -t 'attr' -n 'name' -v "gpointer" \ GioWin32-2.0.gir soup3-0.9.0/gir-files/fontconfig-2.0.gir000064400000000000000000000011661046102023000157240ustar 00000000000000 soup3-0.9.0/gir-files/freetype2-2.0.gir000064400000000000000000000006331046102023000154730ustar 00000000000000 soup3-0.9.0/gir-files/libxml2-2.0.gir000064400000000000000000000016061046102023000151400ustar 00000000000000 soup3-0.9.0/gir-files/reformat.sh000075500000000000000000000003271046102023000147440ustar 00000000000000#!/bin/bash set -x -e # `///` used as `//` not works in Windows in this case for file in *.gir; do xmlstarlet ed -L \ -d '//_:doc/@line' \ -d '//_:doc/@filename' \ -d '///_:source-position' \ "$file" done soup3-0.9.0/gir-files/win32-1.0.gir000064400000000000000000000012731046102023000145300ustar 00000000000000 soup3-0.9.0/gir-files/xfixes-4.0.gir000064400000000000000000000005051046102023000150740ustar 00000000000000 soup3-0.9.0/gir-files/xft-2.0.gir000064400000000000000000000013031046102023000143620ustar 00000000000000 soup3-0.9.0/gir-files/xlib-2.0.gir000064400000000000000000000043571046102023000145330ustar 00000000000000 soup3-0.9.0/gir-files/xrandr-1.3.gir000064400000000000000000000014041046102023000150630ustar 00000000000000 soup3-0.9.0/meson.build000064400000000000000000000000631046102023000130440ustar 00000000000000project('soup3-rs', 'rust') subproject('libsoup') soup3-0.9.0/src/auto/auth.rs000064400000000000000000000254341046102023000137610ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{Message, ffi}; use glib::{ prelude::*, signal::{SignalHandlerId, connect_raw}, translate::*, }; use std::boxed::Box as Box_; glib::wrapper! { #[doc(alias = "SoupAuth")] pub struct Auth(Object); match fn { type_ => || ffi::soup_auth_get_type(), } } impl Auth { pub const NONE: Option<&'static Auth> = None; #[doc(alias = "soup_auth_new")] pub fn new(type_: glib::types::Type, msg: &Message, auth_header: &str) -> Option { skip_assert_initialized!(); unsafe { from_glib_full(ffi::soup_auth_new( type_.into_glib(), msg.to_glib_none().0, auth_header.to_glib_none().0, )) } } } pub trait AuthExt: IsA + 'static { #[doc(alias = "soup_auth_authenticate")] fn authenticate(&self, username: &str, password: &str) { unsafe { ffi::soup_auth_authenticate( self.as_ref().to_glib_none().0, username.to_glib_none().0, password.to_glib_none().0, ); } } #[doc(alias = "soup_auth_can_authenticate")] fn can_authenticate(&self) -> bool { unsafe { from_glib(ffi::soup_auth_can_authenticate( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_auth_cancel")] fn cancel(&self) { unsafe { ffi::soup_auth_cancel(self.as_ref().to_glib_none().0); } } //#[doc(alias = "soup_auth_free_protection_space")] //fn free_protection_space(&self, space: /*Unimplemented*/&[&Basic: Pointer]) { // unsafe { TODO: call ffi:soup_auth_free_protection_space() } //} #[doc(alias = "soup_auth_get_authority")] #[doc(alias = "get_authority")] fn authority(&self) -> Option { unsafe { from_glib_none(ffi::soup_auth_get_authority(self.as_ref().to_glib_none().0)) } } #[doc(alias = "soup_auth_get_authorization")] #[doc(alias = "get_authorization")] fn authorization(&self, msg: &Message) -> Option { unsafe { from_glib_full(ffi::soup_auth_get_authorization( self.as_ref().to_glib_none().0, msg.to_glib_none().0, )) } } #[doc(alias = "soup_auth_get_info")] #[doc(alias = "get_info")] fn info(&self) -> Option { unsafe { from_glib_full(ffi::soup_auth_get_info(self.as_ref().to_glib_none().0)) } } #[doc(alias = "soup_auth_get_protection_space")] #[doc(alias = "get_protection_space")] fn protection_space(&self, source_uri: &glib::Uri) -> Vec { unsafe { FromGlibPtrContainer::from_glib_full(ffi::soup_auth_get_protection_space( self.as_ref().to_glib_none().0, source_uri.to_glib_none().0, )) } } #[doc(alias = "soup_auth_get_realm")] #[doc(alias = "get_realm")] fn realm(&self) -> Option { unsafe { from_glib_none(ffi::soup_auth_get_realm(self.as_ref().to_glib_none().0)) } } #[doc(alias = "soup_auth_get_scheme_name")] #[doc(alias = "get_scheme_name")] #[doc(alias = "scheme-name")] fn scheme_name(&self) -> Option { unsafe { from_glib_none(ffi::soup_auth_get_scheme_name( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_auth_is_authenticated")] #[doc(alias = "is-authenticated")] fn is_authenticated(&self) -> bool { unsafe { from_glib(ffi::soup_auth_is_authenticated( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_auth_is_cancelled")] #[doc(alias = "is-cancelled")] fn is_cancelled(&self) -> bool { unsafe { from_glib(ffi::soup_auth_is_cancelled(self.as_ref().to_glib_none().0)) } } #[doc(alias = "soup_auth_is_for_proxy")] #[doc(alias = "is-for-proxy")] fn is_for_proxy(&self) -> bool { unsafe { from_glib(ffi::soup_auth_is_for_proxy(self.as_ref().to_glib_none().0)) } } #[doc(alias = "soup_auth_is_ready")] fn is_ready(&self, msg: &Message) -> bool { unsafe { from_glib(ffi::soup_auth_is_ready( self.as_ref().to_glib_none().0, msg.to_glib_none().0, )) } } #[doc(alias = "soup_auth_update")] fn update(&self, msg: &Message, auth_header: &str) -> bool { unsafe { from_glib(ffi::soup_auth_update( self.as_ref().to_glib_none().0, msg.to_glib_none().0, auth_header.to_glib_none().0, )) } } fn set_authority(&self, authority: Option<&str>) { ObjectExt::set_property(self.as_ref(), "authority", authority) } #[doc(alias = "is-for-proxy")] fn set_is_for_proxy(&self, is_for_proxy: bool) { ObjectExt::set_property(self.as_ref(), "is-for-proxy", is_for_proxy) } fn set_realm(&self, realm: Option<&str>) { ObjectExt::set_property(self.as_ref(), "realm", realm) } #[doc(alias = "authority")] fn connect_authority_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_authority_trampoline, F: Fn(&P) + 'static>( this: *mut ffi::SoupAuth, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Auth::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::authority".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_authority_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "is-authenticated")] fn connect_is_authenticated_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_is_authenticated_trampoline< P: IsA, F: Fn(&P) + 'static, >( this: *mut ffi::SoupAuth, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Auth::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::is-authenticated".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_is_authenticated_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "is-cancelled")] fn connect_is_cancelled_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_is_cancelled_trampoline, F: Fn(&P) + 'static>( this: *mut ffi::SoupAuth, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Auth::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::is-cancelled".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_is_cancelled_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "is-for-proxy")] fn connect_is_for_proxy_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_is_for_proxy_trampoline, F: Fn(&P) + 'static>( this: *mut ffi::SoupAuth, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Auth::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::is-for-proxy".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_is_for_proxy_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "realm")] fn connect_realm_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_realm_trampoline, F: Fn(&P) + 'static>( this: *mut ffi::SoupAuth, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Auth::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::realm".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_realm_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "scheme-name")] fn connect_scheme_name_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_scheme_name_trampoline, F: Fn(&P) + 'static>( this: *mut ffi::SoupAuth, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Auth::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::scheme-name".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_scheme_name_trampoline:: as *const (), )), Box_::into_raw(f), ) } } } impl> AuthExt for O {} soup3-0.9.0/src/auto/auth_basic.rs000064400000000000000000000040161046102023000151130ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{Auth, ffi}; use glib::prelude::*; glib::wrapper! { #[doc(alias = "SoupAuthBasic")] pub struct AuthBasic(Object) @extends Auth; match fn { type_ => || ffi::soup_auth_basic_get_type(), } } impl AuthBasic { // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`AuthBasic`] objects. /// /// This method returns an instance of [`AuthBasicBuilder`](crate::builders::AuthBasicBuilder) which can be used to create [`AuthBasic`] objects. pub fn builder() -> AuthBasicBuilder { AuthBasicBuilder::new() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`AuthBasic`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct AuthBasicBuilder { builder: glib::object::ObjectBuilder<'static, AuthBasic>, } impl AuthBasicBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn authority(self, authority: impl Into) -> Self { Self { builder: self.builder.property("authority", authority.into()), } } pub fn is_for_proxy(self, is_for_proxy: bool) -> Self { Self { builder: self.builder.property("is-for-proxy", is_for_proxy), } } pub fn realm(self, realm: impl Into) -> Self { Self { builder: self.builder.property("realm", realm.into()), } } // rustdoc-stripper-ignore-next /// Build the [`AuthBasic`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> AuthBasic { assert_initialized_main_thread!(); self.builder.build() } } soup3-0.9.0/src/auto/auth_digest.rs000064400000000000000000000040371046102023000153140ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{Auth, ffi}; use glib::prelude::*; glib::wrapper! { #[doc(alias = "SoupAuthDigest")] pub struct AuthDigest(Object) @extends Auth; match fn { type_ => || ffi::soup_auth_digest_get_type(), } } impl AuthDigest { // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`AuthDigest`] objects. /// /// This method returns an instance of [`AuthDigestBuilder`](crate::builders::AuthDigestBuilder) which can be used to create [`AuthDigest`] objects. pub fn builder() -> AuthDigestBuilder { AuthDigestBuilder::new() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`AuthDigest`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct AuthDigestBuilder { builder: glib::object::ObjectBuilder<'static, AuthDigest>, } impl AuthDigestBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn authority(self, authority: impl Into) -> Self { Self { builder: self.builder.property("authority", authority.into()), } } pub fn is_for_proxy(self, is_for_proxy: bool) -> Self { Self { builder: self.builder.property("is-for-proxy", is_for_proxy), } } pub fn realm(self, realm: impl Into) -> Self { Self { builder: self.builder.property("realm", realm.into()), } } // rustdoc-stripper-ignore-next /// Build the [`AuthDigest`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> AuthDigest { assert_initialized_main_thread!(); self.builder.build() } } soup3-0.9.0/src/auto/auth_domain.rs000064400000000000000000000211401046102023000152760ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{ServerMessage, ffi}; use glib::{ prelude::*, signal::{SignalHandlerId, connect_raw}, translate::*, }; use std::boxed::Box as Box_; glib::wrapper! { #[doc(alias = "SoupAuthDomain")] pub struct AuthDomain(Object); match fn { type_ => || ffi::soup_auth_domain_get_type(), } } impl AuthDomain { pub const NONE: Option<&'static AuthDomain> = None; } pub trait AuthDomainExt: IsA + 'static { #[doc(alias = "soup_auth_domain_accepts")] fn accepts(&self, msg: &ServerMessage) -> Option { unsafe { from_glib_full(ffi::soup_auth_domain_accepts( self.as_ref().to_glib_none().0, msg.to_glib_none().0, )) } } #[doc(alias = "soup_auth_domain_add_path")] fn add_path(&self, path: &str) { unsafe { ffi::soup_auth_domain_add_path(self.as_ref().to_glib_none().0, path.to_glib_none().0); } } #[doc(alias = "soup_auth_domain_challenge")] fn challenge(&self, msg: &ServerMessage) { unsafe { ffi::soup_auth_domain_challenge(self.as_ref().to_glib_none().0, msg.to_glib_none().0); } } #[doc(alias = "soup_auth_domain_check_password")] fn check_password(&self, msg: &ServerMessage, username: &str, password: &str) -> bool { unsafe { from_glib(ffi::soup_auth_domain_check_password( self.as_ref().to_glib_none().0, msg.to_glib_none().0, username.to_glib_none().0, password.to_glib_none().0, )) } } #[doc(alias = "soup_auth_domain_covers")] fn covers(&self, msg: &ServerMessage) -> bool { unsafe { from_glib(ffi::soup_auth_domain_covers( self.as_ref().to_glib_none().0, msg.to_glib_none().0, )) } } #[doc(alias = "soup_auth_domain_get_realm")] #[doc(alias = "get_realm")] fn realm(&self) -> Option { unsafe { from_glib_none(ffi::soup_auth_domain_get_realm( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_auth_domain_remove_path")] fn remove_path(&self, path: &str) { unsafe { ffi::soup_auth_domain_remove_path( self.as_ref().to_glib_none().0, path.to_glib_none().0, ); } } #[doc(alias = "soup_auth_domain_set_filter")] #[doc(alias = "filter")] fn set_filter bool + 'static>(&self, filter: P) { let filter_data: Box_

= Box_::new(filter); unsafe extern "C" fn filter_func bool + 'static>( domain: *mut ffi::SoupAuthDomain, msg: *mut ffi::SoupServerMessage, user_data: glib::ffi::gpointer, ) -> glib::ffi::gboolean { unsafe { let domain = from_glib_borrow(domain); let msg = from_glib_borrow(msg); let callback = &*(user_data as *mut P); (*callback)(&domain, &msg).into_glib() } } let filter = Some(filter_func::

as _); unsafe extern "C" fn dnotify_func bool + 'static>( data: glib::ffi::gpointer, ) { unsafe { let _callback = Box_::from_raw(data as *mut P); } } let destroy_call3 = Some(dnotify_func::

as _); let super_callback0: Box_

= filter_data; unsafe { ffi::soup_auth_domain_set_filter( self.as_ref().to_glib_none().0, filter, Box_::into_raw(super_callback0) as *mut _, destroy_call3, ); } } #[doc(alias = "soup_auth_domain_set_generic_auth_callback")] #[doc(alias = "generic-auth-callback")] fn set_generic_auth_callback bool + 'static>( &self, auth_callback: P, ) { let auth_callback_data: Box_

= Box_::new(auth_callback); unsafe extern "C" fn auth_callback_func< P: Fn(&AuthDomain, &ServerMessage, &str) -> bool + 'static, >( domain: *mut ffi::SoupAuthDomain, msg: *mut ffi::SoupServerMessage, username: *const std::ffi::c_char, user_data: glib::ffi::gpointer, ) -> glib::ffi::gboolean { unsafe { let domain = from_glib_borrow(domain); let msg = from_glib_borrow(msg); let username: Borrowed = from_glib_borrow(username); let callback = &*(user_data as *mut P); (*callback)(&domain, &msg, username.as_str()).into_glib() } } let auth_callback = Some(auth_callback_func::

as _); unsafe extern "C" fn dnotify_func< P: Fn(&AuthDomain, &ServerMessage, &str) -> bool + 'static, >( data: glib::ffi::gpointer, ) { unsafe { let _callback = Box_::from_raw(data as *mut P); } } let destroy_call3 = Some(dnotify_func::

as _); let super_callback0: Box_

= auth_callback_data; unsafe { ffi::soup_auth_domain_set_generic_auth_callback( self.as_ref().to_glib_none().0, auth_callback, Box_::into_raw(super_callback0) as *mut _, destroy_call3, ); } } //#[doc(alias = "filter-data")] //fn filter_data(&self) -> /*Unimplemented*/Basic: Pointer { // ObjectExt::property(self.as_ref(), "filter-data") //} //#[doc(alias = "filter-data")] //fn set_filter_data(&self, filter_data: /*Unimplemented*/Basic: Pointer) { // ObjectExt::set_property(self.as_ref(),"filter-data", filter_data) //} //#[doc(alias = "generic-auth-data")] //fn generic_auth_data(&self) -> /*Unimplemented*/Basic: Pointer { // ObjectExt::property(self.as_ref(), "generic-auth-data") //} //#[doc(alias = "generic-auth-data")] //fn set_generic_auth_data(&self, generic_auth_data: /*Unimplemented*/Basic: Pointer) { // ObjectExt::set_property(self.as_ref(),"generic-auth-data", generic_auth_data) //} fn is_proxy(&self) -> bool { ObjectExt::property(self.as_ref(), "proxy") } #[doc(alias = "filter-data")] fn connect_filter_data_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_filter_data_trampoline< P: IsA, F: Fn(&P) + 'static, >( this: *mut ffi::SoupAuthDomain, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(AuthDomain::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::filter-data".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_filter_data_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "generic-auth-data")] fn connect_generic_auth_data_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_generic_auth_data_trampoline< P: IsA, F: Fn(&P) + 'static, >( this: *mut ffi::SoupAuthDomain, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(AuthDomain::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::generic-auth-data".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_generic_auth_data_trampoline:: as *const (), )), Box_::into_raw(f), ) } } } impl> AuthDomainExt for O {} soup3-0.9.0/src/auto/auth_domain_basic.rs000064400000000000000000000140321046102023000164410ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{AuthDomain, ServerMessage, ffi}; use glib::{ prelude::*, signal::{SignalHandlerId, connect_raw}, translate::*, }; use std::boxed::Box as Box_; glib::wrapper! { #[doc(alias = "SoupAuthDomainBasic")] pub struct AuthDomainBasic(Object) @extends AuthDomain; match fn { type_ => || ffi::soup_auth_domain_basic_get_type(), } } impl AuthDomainBasic { //#[doc(alias = "soup_auth_domain_basic_new")] //pub fn new(optname1: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> AuthDomainBasic { // unsafe { TODO: call ffi:soup_auth_domain_basic_new() } //} // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`AuthDomainBasic`] objects. /// /// This method returns an instance of [`AuthDomainBasicBuilder`](crate::builders::AuthDomainBasicBuilder) which can be used to create [`AuthDomainBasic`] objects. pub fn builder() -> AuthDomainBasicBuilder { AuthDomainBasicBuilder::new() } #[doc(alias = "soup_auth_domain_basic_set_auth_callback")] #[doc(alias = "auth-callback")] pub fn set_auth_callback< P: Fn(&AuthDomainBasic, &ServerMessage, &str, &str) -> bool + 'static, >( &self, callback: P, ) { let callback_data: Box_

= Box_::new(callback); unsafe extern "C" fn callback_func< P: Fn(&AuthDomainBasic, &ServerMessage, &str, &str) -> bool + 'static, >( domain: *mut ffi::SoupAuthDomainBasic, msg: *mut ffi::SoupServerMessage, username: *const std::ffi::c_char, password: *const std::ffi::c_char, user_data: glib::ffi::gpointer, ) -> glib::ffi::gboolean { unsafe { let domain = from_glib_borrow(domain); let msg = from_glib_borrow(msg); let username: Borrowed = from_glib_borrow(username); let password: Borrowed = from_glib_borrow(password); let callback = &*(user_data as *mut P); (*callback)(&domain, &msg, username.as_str(), password.as_str()).into_glib() } } let callback = Some(callback_func::

as _); unsafe extern "C" fn dnotify_func< P: Fn(&AuthDomainBasic, &ServerMessage, &str, &str) -> bool + 'static, >( data: glib::ffi::gpointer, ) { unsafe { let _callback = Box_::from_raw(data as *mut P); } } let destroy_call3 = Some(dnotify_func::

as _); let super_callback0: Box_

= callback_data; unsafe { ffi::soup_auth_domain_basic_set_auth_callback( self.to_glib_none().0, callback, Box_::into_raw(super_callback0) as *mut _, destroy_call3, ); } } //#[doc(alias = "auth-data")] //pub fn auth_data(&self) -> /*Unimplemented*/Basic: Pointer { // ObjectExt::property(self, "auth-data") //} //#[doc(alias = "auth-data")] //pub fn set_auth_data(&self, auth_data: /*Unimplemented*/Basic: Pointer) { // ObjectExt::set_property(self,"auth-data", auth_data) //} #[doc(alias = "auth-data")] pub fn connect_auth_data_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_auth_data_trampoline( this: *mut ffi::SoupAuthDomainBasic, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::auth-data".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_auth_data_trampoline:: as *const (), )), Box_::into_raw(f), ) } } } impl Default for AuthDomainBasic { fn default() -> Self { glib::object::Object::new::() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`AuthDomainBasic`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct AuthDomainBasicBuilder { builder: glib::object::ObjectBuilder<'static, AuthDomainBasic>, } impl AuthDomainBasicBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } //pub fn auth_data(self, auth_data: /*Unimplemented*/Basic: Pointer) -> Self { // Self { builder: self.builder.property("auth-data", auth_data), } //} //pub fn filter_data(self, filter_data: /*Unimplemented*/Basic: Pointer) -> Self { // Self { builder: self.builder.property("filter-data", filter_data), } //} //pub fn generic_auth_data(self, generic_auth_data: /*Unimplemented*/Basic: Pointer) -> Self { // Self { builder: self.builder.property("generic-auth-data", generic_auth_data), } //} pub fn proxy(self, proxy: bool) -> Self { Self { builder: self.builder.property("proxy", proxy), } } pub fn realm(self, realm: impl Into) -> Self { Self { builder: self.builder.property("realm", realm.into()), } } // rustdoc-stripper-ignore-next /// Build the [`AuthDomainBasic`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> AuthDomainBasic { assert_initialized_main_thread!(); self.builder.build() } } soup3-0.9.0/src/auto/auth_domain_digest.rs000064400000000000000000000145671046102023000166540ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{AuthDomain, ServerMessage, ffi}; use glib::{ prelude::*, signal::{SignalHandlerId, connect_raw}, translate::*, }; use std::boxed::Box as Box_; glib::wrapper! { #[doc(alias = "SoupAuthDomainDigest")] pub struct AuthDomainDigest(Object) @extends AuthDomain; match fn { type_ => || ffi::soup_auth_domain_digest_get_type(), } } impl AuthDomainDigest { //#[doc(alias = "soup_auth_domain_digest_new")] //pub fn new(optname1: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> AuthDomainDigest { // unsafe { TODO: call ffi:soup_auth_domain_digest_new() } //} // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`AuthDomainDigest`] objects. /// /// This method returns an instance of [`AuthDomainDigestBuilder`](crate::builders::AuthDomainDigestBuilder) which can be used to create [`AuthDomainDigest`] objects. pub fn builder() -> AuthDomainDigestBuilder { AuthDomainDigestBuilder::new() } #[doc(alias = "soup_auth_domain_digest_set_auth_callback")] #[doc(alias = "auth-callback")] pub fn set_auth_callback< P: Fn(&AuthDomainDigest, &ServerMessage, &str) -> Option + 'static, >( &self, callback: P, ) { let callback_data: Box_

= Box_::new(callback); unsafe extern "C" fn callback_func< P: Fn(&AuthDomainDigest, &ServerMessage, &str) -> Option + 'static, >( domain: *mut ffi::SoupAuthDomainDigest, msg: *mut ffi::SoupServerMessage, username: *const std::ffi::c_char, user_data: glib::ffi::gpointer, ) -> *mut std::ffi::c_char { unsafe { let domain = from_glib_borrow(domain); let msg = from_glib_borrow(msg); let username: Borrowed = from_glib_borrow(username); let callback = &*(user_data as *mut P); (*callback)(&domain, &msg, username.as_str()).to_glib_full() } } let callback = Some(callback_func::

as _); unsafe extern "C" fn dnotify_func< P: Fn(&AuthDomainDigest, &ServerMessage, &str) -> Option + 'static, >( data: glib::ffi::gpointer, ) { unsafe { let _callback = Box_::from_raw(data as *mut P); } } let destroy_call3 = Some(dnotify_func::

as _); let super_callback0: Box_

= callback_data; unsafe { ffi::soup_auth_domain_digest_set_auth_callback( self.to_glib_none().0, callback, Box_::into_raw(super_callback0) as *mut _, destroy_call3, ); } } //#[doc(alias = "auth-data")] //pub fn auth_data(&self) -> /*Unimplemented*/Basic: Pointer { // ObjectExt::property(self, "auth-data") //} //#[doc(alias = "auth-data")] //pub fn set_auth_data(&self, auth_data: /*Unimplemented*/Basic: Pointer) { // ObjectExt::set_property(self,"auth-data", auth_data) //} #[doc(alias = "soup_auth_domain_digest_encode_password")] pub fn encode_password(username: &str, realm: &str, password: &str) -> Option { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_auth_domain_digest_encode_password( username.to_glib_none().0, realm.to_glib_none().0, password.to_glib_none().0, )) } } #[doc(alias = "auth-data")] pub fn connect_auth_data_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_auth_data_trampoline( this: *mut ffi::SoupAuthDomainDigest, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::auth-data".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_auth_data_trampoline:: as *const (), )), Box_::into_raw(f), ) } } } impl Default for AuthDomainDigest { fn default() -> Self { glib::object::Object::new::() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`AuthDomainDigest`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct AuthDomainDigestBuilder { builder: glib::object::ObjectBuilder<'static, AuthDomainDigest>, } impl AuthDomainDigestBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } //pub fn auth_data(self, auth_data: /*Unimplemented*/Basic: Pointer) -> Self { // Self { builder: self.builder.property("auth-data", auth_data), } //} //pub fn filter_data(self, filter_data: /*Unimplemented*/Basic: Pointer) -> Self { // Self { builder: self.builder.property("filter-data", filter_data), } //} //pub fn generic_auth_data(self, generic_auth_data: /*Unimplemented*/Basic: Pointer) -> Self { // Self { builder: self.builder.property("generic-auth-data", generic_auth_data), } //} pub fn proxy(self, proxy: bool) -> Self { Self { builder: self.builder.property("proxy", proxy), } } pub fn realm(self, realm: impl Into) -> Self { Self { builder: self.builder.property("realm", realm.into()), } } // rustdoc-stripper-ignore-next /// Build the [`AuthDomainDigest`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> AuthDomainDigest { assert_initialized_main_thread!(); self.builder.build() } } soup3-0.9.0/src/auto/auth_manager.rs000064400000000000000000000020411046102023000154400ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{Auth, SessionFeature, ffi}; use glib::{prelude::*, translate::*}; glib::wrapper! { #[doc(alias = "SoupAuthManager")] pub struct AuthManager(Object) @implements SessionFeature; match fn { type_ => || ffi::soup_auth_manager_get_type(), } } impl AuthManager { #[doc(alias = "soup_auth_manager_clear_cached_credentials")] pub fn clear_cached_credentials(&self) { unsafe { ffi::soup_auth_manager_clear_cached_credentials(self.to_glib_none().0); } } #[doc(alias = "soup_auth_manager_use_auth")] pub fn use_auth(&self, uri: &glib::Uri, auth: &impl IsA) { unsafe { ffi::soup_auth_manager_use_auth( self.to_glib_none().0, uri.to_glib_none().0, auth.as_ref().to_glib_none().0, ); } } } soup3-0.9.0/src/auto/auth_negotiate.rs000064400000000000000000000044541046102023000160170ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{Auth, ffi}; use glib::{prelude::*, translate::*}; glib::wrapper! { #[doc(alias = "SoupAuthNegotiate")] pub struct AuthNegotiate(Object) @extends Auth; match fn { type_ => || ffi::soup_auth_negotiate_get_type(), } } impl AuthNegotiate { // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`AuthNegotiate`] objects. /// /// This method returns an instance of [`AuthNegotiateBuilder`](crate::builders::AuthNegotiateBuilder) which can be used to create [`AuthNegotiate`] objects. pub fn builder() -> AuthNegotiateBuilder { AuthNegotiateBuilder::new() } #[doc(alias = "soup_auth_negotiate_supported")] pub fn supported() -> bool { assert_initialized_main_thread!(); unsafe { from_glib(ffi::soup_auth_negotiate_supported()) } } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`AuthNegotiate`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct AuthNegotiateBuilder { builder: glib::object::ObjectBuilder<'static, AuthNegotiate>, } impl AuthNegotiateBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn authority(self, authority: impl Into) -> Self { Self { builder: self.builder.property("authority", authority.into()), } } pub fn is_for_proxy(self, is_for_proxy: bool) -> Self { Self { builder: self.builder.property("is-for-proxy", is_for_proxy), } } pub fn realm(self, realm: impl Into) -> Self { Self { builder: self.builder.property("realm", realm.into()), } } // rustdoc-stripper-ignore-next /// Build the [`AuthNegotiate`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> AuthNegotiate { assert_initialized_main_thread!(); self.builder.build() } } soup3-0.9.0/src/auto/auth_ntlm.rs000064400000000000000000000037751046102023000150170ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{Auth, ffi}; use glib::prelude::*; glib::wrapper! { #[doc(alias = "SoupAuthNTLM")] pub struct AuthNTLM(Object) @extends Auth; match fn { type_ => || ffi::soup_auth_ntlm_get_type(), } } impl AuthNTLM { // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`AuthNTLM`] objects. /// /// This method returns an instance of [`AuthNTLMBuilder`](crate::builders::AuthNTLMBuilder) which can be used to create [`AuthNTLM`] objects. pub fn builder() -> AuthNTLMBuilder { AuthNTLMBuilder::new() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`AuthNTLM`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct AuthNTLMBuilder { builder: glib::object::ObjectBuilder<'static, AuthNTLM>, } impl AuthNTLMBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn authority(self, authority: impl Into) -> Self { Self { builder: self.builder.property("authority", authority.into()), } } pub fn is_for_proxy(self, is_for_proxy: bool) -> Self { Self { builder: self.builder.property("is-for-proxy", is_for_proxy), } } pub fn realm(self, realm: impl Into) -> Self { Self { builder: self.builder.property("realm", realm.into()), } } // rustdoc-stripper-ignore-next /// Build the [`AuthNTLM`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> AuthNTLM { assert_initialized_main_thread!(); self.builder.build() } } soup3-0.9.0/src/auto/cache.rs000064400000000000000000000073351046102023000140630ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{CacheType, SessionFeature, ffi}; use glib::{prelude::*, translate::*}; glib::wrapper! { #[doc(alias = "SoupCache")] pub struct Cache(Object) @implements SessionFeature; match fn { type_ => || ffi::soup_cache_get_type(), } } impl Cache { pub const NONE: Option<&'static Cache> = None; #[doc(alias = "soup_cache_new")] pub fn new(cache_dir: Option<&str>, cache_type: CacheType) -> Cache { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_cache_new( cache_dir.to_glib_none().0, cache_type.into_glib(), )) } } // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`Cache`] objects. /// /// This method returns an instance of [`CacheBuilder`](crate::builders::CacheBuilder) which can be used to create [`Cache`] objects. pub fn builder() -> CacheBuilder { CacheBuilder::new() } } impl Default for Cache { fn default() -> Self { glib::object::Object::new::() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`Cache`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct CacheBuilder { builder: glib::object::ObjectBuilder<'static, Cache>, } impl CacheBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn cache_dir(self, cache_dir: impl Into) -> Self { Self { builder: self.builder.property("cache-dir", cache_dir.into()), } } pub fn cache_type(self, cache_type: CacheType) -> Self { Self { builder: self.builder.property("cache-type", cache_type), } } // rustdoc-stripper-ignore-next /// Build the [`Cache`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> Cache { assert_initialized_main_thread!(); self.builder.build() } } pub trait CacheExt: IsA + 'static { #[doc(alias = "soup_cache_clear")] fn clear(&self) { unsafe { ffi::soup_cache_clear(self.as_ref().to_glib_none().0); } } #[doc(alias = "soup_cache_dump")] fn dump(&self) { unsafe { ffi::soup_cache_dump(self.as_ref().to_glib_none().0); } } #[doc(alias = "soup_cache_flush")] fn flush(&self) { unsafe { ffi::soup_cache_flush(self.as_ref().to_glib_none().0); } } #[doc(alias = "soup_cache_get_max_size")] #[doc(alias = "get_max_size")] fn max_size(&self) -> u32 { unsafe { ffi::soup_cache_get_max_size(self.as_ref().to_glib_none().0) } } #[doc(alias = "soup_cache_load")] fn load(&self) { unsafe { ffi::soup_cache_load(self.as_ref().to_glib_none().0); } } #[doc(alias = "soup_cache_set_max_size")] fn set_max_size(&self, max_size: u32) { unsafe { ffi::soup_cache_set_max_size(self.as_ref().to_glib_none().0, max_size); } } #[doc(alias = "cache-dir")] fn cache_dir(&self) -> Option { ObjectExt::property(self.as_ref(), "cache-dir") } #[doc(alias = "cache-type")] fn cache_type(&self) -> CacheType { ObjectExt::property(self.as_ref(), "cache-type") } } impl> CacheExt for O {} soup3-0.9.0/src/auto/constants.rs000064400000000000000000000010361046102023000150240ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::ffi; use glib::GStr; #[doc(alias = "SOUP_FORM_MIME_TYPE_MULTIPART")] pub static FORM_MIME_TYPE_MULTIPART: &GStr = unsafe { GStr::from_utf8_with_nul_unchecked(ffi::SOUP_FORM_MIME_TYPE_MULTIPART) }; #[doc(alias = "SOUP_FORM_MIME_TYPE_URLENCODED")] pub static FORM_MIME_TYPE_URLENCODED: &GStr = unsafe { GStr::from_utf8_with_nul_unchecked(ffi::SOUP_FORM_MIME_TYPE_URLENCODED) }; soup3-0.9.0/src/auto/content_decoder.rs000064400000000000000000000007221046102023000161500ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{SessionFeature, ffi}; glib::wrapper! { #[doc(alias = "SoupContentDecoder")] pub struct ContentDecoder(Object) @implements SessionFeature; match fn { type_ => || ffi::soup_content_decoder_get_type(), } } impl ContentDecoder {} soup3-0.9.0/src/auto/content_sniffer.rs000064400000000000000000000021261046102023000161770ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{SessionFeature, ffi}; use glib::translate::*; glib::wrapper! { #[doc(alias = "SoupContentSniffer")] pub struct ContentSniffer(Object) @implements SessionFeature; match fn { type_ => || ffi::soup_content_sniffer_get_type(), } } impl ContentSniffer { #[doc(alias = "soup_content_sniffer_new")] pub fn new() -> ContentSniffer { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_content_sniffer_new()) } } //#[doc(alias = "soup_content_sniffer_sniff")] //pub fn sniff(&self, msg: &Message, buffer: &glib::Bytes, params: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 }) -> Option { // unsafe { TODO: call ffi:soup_content_sniffer_sniff() } //} } impl Default for ContentSniffer { fn default() -> Self { Self::new() } } soup3-0.9.0/src/auto/cookie.rs000064400000000000000000000151201046102023000142600ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{SameSitePolicy, ffi}; use glib::translate::*; glib::wrapper! { #[derive(Debug, PartialOrd, Ord, Hash)] pub struct Cookie(Boxed); match fn { copy => |ptr| ffi::soup_cookie_copy(mut_override(ptr)), free => |ptr| ffi::soup_cookie_free(ptr), type_ => || ffi::soup_cookie_get_type(), } } impl Cookie { #[doc(alias = "soup_cookie_new")] pub fn new(name: &str, value: &str, domain: &str, path: &str, max_age: i32) -> Cookie { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_cookie_new( name.to_glib_none().0, value.to_glib_none().0, domain.to_glib_none().0, path.to_glib_none().0, max_age, )) } } #[doc(alias = "soup_cookie_applies_to_uri")] pub fn applies_to_uri(&mut self, uri: &glib::Uri) -> bool { unsafe { from_glib(ffi::soup_cookie_applies_to_uri( self.to_glib_none_mut().0, uri.to_glib_none().0, )) } } #[doc(alias = "soup_cookie_domain_matches")] pub fn domain_matches(&mut self, host: &str) -> bool { unsafe { from_glib(ffi::soup_cookie_domain_matches( self.to_glib_none_mut().0, host.to_glib_none().0, )) } } #[doc(alias = "soup_cookie_equal")] fn equal(&self, cookie2: &Cookie) -> bool { unsafe { from_glib(ffi::soup_cookie_equal( mut_override(self.to_glib_none().0), mut_override(cookie2.to_glib_none().0), )) } } #[doc(alias = "soup_cookie_get_domain")] #[doc(alias = "get_domain")] pub fn domain(&mut self) -> Option { unsafe { from_glib_none(ffi::soup_cookie_get_domain(self.to_glib_none_mut().0)) } } #[doc(alias = "soup_cookie_get_expires")] #[doc(alias = "get_expires")] pub fn expires(&mut self) -> Option { unsafe { from_glib_none(ffi::soup_cookie_get_expires(self.to_glib_none_mut().0)) } } #[doc(alias = "soup_cookie_get_http_only")] #[doc(alias = "get_http_only")] pub fn is_http_only(&mut self) -> bool { unsafe { from_glib(ffi::soup_cookie_get_http_only(self.to_glib_none_mut().0)) } } #[doc(alias = "soup_cookie_get_name")] #[doc(alias = "get_name")] pub fn name(&mut self) -> Option { unsafe { from_glib_none(ffi::soup_cookie_get_name(self.to_glib_none_mut().0)) } } #[doc(alias = "soup_cookie_get_path")] #[doc(alias = "get_path")] pub fn path(&mut self) -> Option { unsafe { from_glib_none(ffi::soup_cookie_get_path(self.to_glib_none_mut().0)) } } #[doc(alias = "soup_cookie_get_same_site_policy")] #[doc(alias = "get_same_site_policy")] pub fn same_site_policy(&mut self) -> SameSitePolicy { unsafe { from_glib(ffi::soup_cookie_get_same_site_policy( self.to_glib_none_mut().0, )) } } #[doc(alias = "soup_cookie_get_secure")] #[doc(alias = "get_secure")] pub fn is_secure(&mut self) -> bool { unsafe { from_glib(ffi::soup_cookie_get_secure(self.to_glib_none_mut().0)) } } #[doc(alias = "soup_cookie_get_value")] #[doc(alias = "get_value")] pub fn value(&mut self) -> Option { unsafe { from_glib_none(ffi::soup_cookie_get_value(self.to_glib_none_mut().0)) } } #[doc(alias = "soup_cookie_set_domain")] pub fn set_domain(&mut self, domain: &str) { unsafe { ffi::soup_cookie_set_domain(self.to_glib_none_mut().0, domain.to_glib_none().0); } } #[doc(alias = "soup_cookie_set_expires")] pub fn set_expires(&mut self, expires: &glib::DateTime) { unsafe { ffi::soup_cookie_set_expires(self.to_glib_none_mut().0, expires.to_glib_none().0); } } #[doc(alias = "soup_cookie_set_http_only")] pub fn set_http_only(&mut self, http_only: bool) { unsafe { ffi::soup_cookie_set_http_only(self.to_glib_none_mut().0, http_only.into_glib()); } } #[doc(alias = "soup_cookie_set_max_age")] pub fn set_max_age(&mut self, max_age: i32) { unsafe { ffi::soup_cookie_set_max_age(self.to_glib_none_mut().0, max_age); } } #[doc(alias = "soup_cookie_set_name")] pub fn set_name(&mut self, name: &str) { unsafe { ffi::soup_cookie_set_name(self.to_glib_none_mut().0, name.to_glib_none().0); } } #[doc(alias = "soup_cookie_set_path")] pub fn set_path(&mut self, path: &str) { unsafe { ffi::soup_cookie_set_path(self.to_glib_none_mut().0, path.to_glib_none().0); } } #[doc(alias = "soup_cookie_set_same_site_policy")] pub fn set_same_site_policy(&mut self, policy: SameSitePolicy) { unsafe { ffi::soup_cookie_set_same_site_policy(self.to_glib_none_mut().0, policy.into_glib()); } } #[doc(alias = "soup_cookie_set_secure")] pub fn set_secure(&mut self, secure: bool) { unsafe { ffi::soup_cookie_set_secure(self.to_glib_none_mut().0, secure.into_glib()); } } #[doc(alias = "soup_cookie_set_value")] pub fn set_value(&mut self, value: &str) { unsafe { ffi::soup_cookie_set_value(self.to_glib_none_mut().0, value.to_glib_none().0); } } #[doc(alias = "soup_cookie_to_cookie_header")] pub fn to_cookie_header(&mut self) -> Option { unsafe { from_glib_full(ffi::soup_cookie_to_cookie_header(self.to_glib_none_mut().0)) } } #[doc(alias = "soup_cookie_to_set_cookie_header")] pub fn to_set_cookie_header(&mut self) -> Option { unsafe { from_glib_full(ffi::soup_cookie_to_set_cookie_header( self.to_glib_none_mut().0, )) } } #[doc(alias = "soup_cookie_parse")] pub fn parse(header: &str, origin: Option<&glib::Uri>) -> Option { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_cookie_parse( header.to_glib_none().0, origin.to_glib_none().0, )) } } } impl PartialEq for Cookie { #[inline] fn eq(&self, other: &Self) -> bool { self.equal(other) } } impl Eq for Cookie {} soup3-0.9.0/src/auto/cookie_jar.rs000064400000000000000000000211131046102023000151130ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{Cookie, CookieJarAcceptPolicy, SessionFeature, ffi}; use glib::{ object::ObjectType as _, prelude::*, signal::{SignalHandlerId, connect_raw}, translate::*, }; use std::boxed::Box as Box_; glib::wrapper! { #[doc(alias = "SoupCookieJar")] pub struct CookieJar(Object) @implements SessionFeature; match fn { type_ => || ffi::soup_cookie_jar_get_type(), } } impl CookieJar { pub const NONE: Option<&'static CookieJar> = None; #[doc(alias = "soup_cookie_jar_new")] pub fn new() -> CookieJar { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_cookie_jar_new()) } } // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`CookieJar`] objects. /// /// This method returns an instance of [`CookieJarBuilder`](crate::builders::CookieJarBuilder) which can be used to create [`CookieJar`] objects. pub fn builder() -> CookieJarBuilder { CookieJarBuilder::new() } } impl Default for CookieJar { fn default() -> Self { Self::new() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`CookieJar`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct CookieJarBuilder { builder: glib::object::ObjectBuilder<'static, CookieJar>, } impl CookieJarBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn accept_policy(self, accept_policy: CookieJarAcceptPolicy) -> Self { Self { builder: self.builder.property("accept-policy", accept_policy), } } pub fn read_only(self, read_only: bool) -> Self { Self { builder: self.builder.property("read-only", read_only), } } // rustdoc-stripper-ignore-next /// Build the [`CookieJar`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> CookieJar { assert_initialized_main_thread!(); self.builder.build() } } pub trait CookieJarExt: IsA + 'static { #[doc(alias = "soup_cookie_jar_all_cookies")] fn all_cookies(&self) -> Vec { unsafe { FromGlibPtrContainer::from_glib_full(ffi::soup_cookie_jar_all_cookies( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_cookie_jar_get_accept_policy")] #[doc(alias = "get_accept_policy")] #[doc(alias = "accept-policy")] fn accept_policy(&self) -> CookieJarAcceptPolicy { unsafe { from_glib(ffi::soup_cookie_jar_get_accept_policy( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_cookie_jar_get_cookie_list")] #[doc(alias = "get_cookie_list")] fn cookie_list(&self, uri: &glib::Uri, for_http: bool) -> Vec { unsafe { FromGlibPtrContainer::from_glib_full(ffi::soup_cookie_jar_get_cookie_list( self.as_ref().to_glib_none().0, uri.to_glib_none().0, for_http.into_glib(), )) } } #[doc(alias = "soup_cookie_jar_get_cookie_list_with_same_site_info")] #[doc(alias = "get_cookie_list_with_same_site_info")] fn cookie_list_with_same_site_info( &self, uri: &glib::Uri, top_level: Option<&glib::Uri>, site_for_cookies: Option<&glib::Uri>, for_http: bool, is_safe_method: bool, is_top_level_navigation: bool, ) -> Vec { unsafe { FromGlibPtrContainer::from_glib_full( ffi::soup_cookie_jar_get_cookie_list_with_same_site_info( self.as_ref().to_glib_none().0, uri.to_glib_none().0, top_level.to_glib_none().0, site_for_cookies.to_glib_none().0, for_http.into_glib(), is_safe_method.into_glib(), is_top_level_navigation.into_glib(), ), ) } } #[doc(alias = "soup_cookie_jar_get_cookies")] #[doc(alias = "get_cookies")] fn cookies(&self, uri: &glib::Uri, for_http: bool) -> Option { unsafe { from_glib_full(ffi::soup_cookie_jar_get_cookies( self.as_ref().to_glib_none().0, uri.to_glib_none().0, for_http.into_glib(), )) } } #[doc(alias = "soup_cookie_jar_is_persistent")] fn is_persistent(&self) -> bool { unsafe { from_glib(ffi::soup_cookie_jar_is_persistent( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_cookie_jar_set_accept_policy")] #[doc(alias = "accept-policy")] fn set_accept_policy(&self, policy: CookieJarAcceptPolicy) { unsafe { ffi::soup_cookie_jar_set_accept_policy( self.as_ref().to_glib_none().0, policy.into_glib(), ); } } #[doc(alias = "soup_cookie_jar_set_cookie")] fn set_cookie(&self, uri: &glib::Uri, cookie: &str) { unsafe { ffi::soup_cookie_jar_set_cookie( self.as_ref().to_glib_none().0, uri.to_glib_none().0, cookie.to_glib_none().0, ); } } #[doc(alias = "soup_cookie_jar_set_cookie_with_first_party")] fn set_cookie_with_first_party(&self, uri: &glib::Uri, first_party: &glib::Uri, cookie: &str) { unsafe { ffi::soup_cookie_jar_set_cookie_with_first_party( self.as_ref().to_glib_none().0, uri.to_glib_none().0, first_party.to_glib_none().0, cookie.to_glib_none().0, ); } } #[doc(alias = "read-only")] fn is_read_only(&self) -> bool { ObjectExt::property(self.as_ref(), "read-only") } #[doc(alias = "changed")] fn connect_changed, Option<&Cookie>) + 'static>( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn changed_trampoline< P: IsA, F: Fn(&P, Option<&Cookie>, Option<&Cookie>) + 'static, >( this: *mut ffi::SoupCookieJar, old_cookie: *mut ffi::SoupCookie, new_cookie: *mut ffi::SoupCookie, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f( CookieJar::from_glib_borrow(this).unsafe_cast_ref(), Option::::from_glib_borrow(old_cookie) .as_ref() .as_ref(), Option::::from_glib_borrow(new_cookie) .as_ref() .as_ref(), ) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"changed".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( changed_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "accept-policy")] fn connect_accept_policy_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_accept_policy_trampoline< P: IsA, F: Fn(&P) + 'static, >( this: *mut ffi::SoupCookieJar, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(CookieJar::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::accept-policy".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_accept_policy_trampoline:: as *const (), )), Box_::into_raw(f), ) } } } impl> CookieJarExt for O {} soup3-0.9.0/src/auto/cookie_jar_db.rs000064400000000000000000000054031046102023000155640ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{CookieJar, CookieJarAcceptPolicy, SessionFeature, ffi}; use glib::{prelude::*, translate::*}; glib::wrapper! { #[doc(alias = "SoupCookieJarDB")] pub struct CookieJarDB(Object) @extends CookieJar, @implements SessionFeature; match fn { type_ => || ffi::soup_cookie_jar_db_get_type(), } } impl CookieJarDB { #[doc(alias = "soup_cookie_jar_db_new")] pub fn new(filename: &str, read_only: bool) -> CookieJarDB { assert_initialized_main_thread!(); unsafe { CookieJar::from_glib_full(ffi::soup_cookie_jar_db_new( filename.to_glib_none().0, read_only.into_glib(), )) .unsafe_cast() } } // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`CookieJarDB`] objects. /// /// This method returns an instance of [`CookieJarDBBuilder`](crate::builders::CookieJarDBBuilder) which can be used to create [`CookieJarDB`] objects. pub fn builder() -> CookieJarDBBuilder { CookieJarDBBuilder::new() } pub fn filename(&self) -> Option { ObjectExt::property(self, "filename") } } impl Default for CookieJarDB { fn default() -> Self { glib::object::Object::new::() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`CookieJarDB`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct CookieJarDBBuilder { builder: glib::object::ObjectBuilder<'static, CookieJarDB>, } impl CookieJarDBBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn filename(self, filename: impl Into) -> Self { Self { builder: self.builder.property("filename", filename.into()), } } pub fn accept_policy(self, accept_policy: CookieJarAcceptPolicy) -> Self { Self { builder: self.builder.property("accept-policy", accept_policy), } } pub fn read_only(self, read_only: bool) -> Self { Self { builder: self.builder.property("read-only", read_only), } } // rustdoc-stripper-ignore-next /// Build the [`CookieJarDB`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> CookieJarDB { assert_initialized_main_thread!(); self.builder.build() } } soup3-0.9.0/src/auto/cookie_jar_text.rs000064400000000000000000000054571046102023000161740ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{CookieJar, CookieJarAcceptPolicy, SessionFeature, ffi}; use glib::{prelude::*, translate::*}; glib::wrapper! { #[doc(alias = "SoupCookieJarText")] pub struct CookieJarText(Object) @extends CookieJar, @implements SessionFeature; match fn { type_ => || ffi::soup_cookie_jar_text_get_type(), } } impl CookieJarText { #[doc(alias = "soup_cookie_jar_text_new")] pub fn new(filename: &str, read_only: bool) -> CookieJarText { assert_initialized_main_thread!(); unsafe { CookieJar::from_glib_full(ffi::soup_cookie_jar_text_new( filename.to_glib_none().0, read_only.into_glib(), )) .unsafe_cast() } } // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`CookieJarText`] objects. /// /// This method returns an instance of [`CookieJarTextBuilder`](crate::builders::CookieJarTextBuilder) which can be used to create [`CookieJarText`] objects. pub fn builder() -> CookieJarTextBuilder { CookieJarTextBuilder::new() } pub fn filename(&self) -> Option { ObjectExt::property(self, "filename") } } impl Default for CookieJarText { fn default() -> Self { glib::object::Object::new::() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`CookieJarText`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct CookieJarTextBuilder { builder: glib::object::ObjectBuilder<'static, CookieJarText>, } impl CookieJarTextBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn filename(self, filename: impl Into) -> Self { Self { builder: self.builder.property("filename", filename.into()), } } pub fn accept_policy(self, accept_policy: CookieJarAcceptPolicy) -> Self { Self { builder: self.builder.property("accept-policy", accept_policy), } } pub fn read_only(self, read_only: bool) -> Self { Self { builder: self.builder.property("read-only", read_only), } } // rustdoc-stripper-ignore-next /// Build the [`CookieJarText`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> CookieJarText { assert_initialized_main_thread!(); self.builder.build() } } soup3-0.9.0/src/auto/enums.rs000064400000000000000000002075171046102023000141530ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::ffi; use glib::{prelude::*, translate::*}; #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupCacheType")] pub enum CacheType { #[doc(alias = "SOUP_CACHE_SINGLE_USER")] SingleUser, #[doc(alias = "SOUP_CACHE_SHARED")] Shared, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for CacheType { type GlibType = ffi::SoupCacheType; #[inline] fn into_glib(self) -> ffi::SoupCacheType { match self { Self::SingleUser => ffi::SOUP_CACHE_SINGLE_USER, Self::Shared => ffi::SOUP_CACHE_SHARED, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for CacheType { #[inline] unsafe fn from_glib(value: ffi::SoupCacheType) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_CACHE_SINGLE_USER => Self::SingleUser, ffi::SOUP_CACHE_SHARED => Self::Shared, value => Self::__Unknown(value), } } } impl StaticType for CacheType { #[inline] #[doc(alias = "soup_cache_type_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_cache_type_get_type()) } } } impl glib::HasParamSpec for CacheType { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for CacheType { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for CacheType { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for CacheType { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: CacheType) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupCookieJarAcceptPolicy")] pub enum CookieJarAcceptPolicy { #[doc(alias = "SOUP_COOKIE_JAR_ACCEPT_ALWAYS")] Always, #[doc(alias = "SOUP_COOKIE_JAR_ACCEPT_NEVER")] Never, #[doc(alias = "SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY")] NoThirdParty, #[doc(alias = "SOUP_COOKIE_JAR_ACCEPT_GRANDFATHERED_THIRD_PARTY")] GrandfatheredThirdParty, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for CookieJarAcceptPolicy { type GlibType = ffi::SoupCookieJarAcceptPolicy; #[inline] fn into_glib(self) -> ffi::SoupCookieJarAcceptPolicy { match self { Self::Always => ffi::SOUP_COOKIE_JAR_ACCEPT_ALWAYS, Self::Never => ffi::SOUP_COOKIE_JAR_ACCEPT_NEVER, Self::NoThirdParty => ffi::SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY, Self::GrandfatheredThirdParty => ffi::SOUP_COOKIE_JAR_ACCEPT_GRANDFATHERED_THIRD_PARTY, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for CookieJarAcceptPolicy { #[inline] unsafe fn from_glib(value: ffi::SoupCookieJarAcceptPolicy) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_COOKIE_JAR_ACCEPT_ALWAYS => Self::Always, ffi::SOUP_COOKIE_JAR_ACCEPT_NEVER => Self::Never, ffi::SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY => Self::NoThirdParty, ffi::SOUP_COOKIE_JAR_ACCEPT_GRANDFATHERED_THIRD_PARTY => Self::GrandfatheredThirdParty, value => Self::__Unknown(value), } } } impl StaticType for CookieJarAcceptPolicy { #[inline] #[doc(alias = "soup_cookie_jar_accept_policy_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_cookie_jar_accept_policy_get_type()) } } } impl glib::HasParamSpec for CookieJarAcceptPolicy { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for CookieJarAcceptPolicy { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for CookieJarAcceptPolicy { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for CookieJarAcceptPolicy { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: CookieJarAcceptPolicy) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupDateFormat")] pub enum DateFormat { #[doc(alias = "SOUP_DATE_HTTP")] Http, #[doc(alias = "SOUP_DATE_COOKIE")] Cookie, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for DateFormat { type GlibType = ffi::SoupDateFormat; #[inline] fn into_glib(self) -> ffi::SoupDateFormat { match self { Self::Http => ffi::SOUP_DATE_HTTP, Self::Cookie => ffi::SOUP_DATE_COOKIE, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for DateFormat { #[inline] unsafe fn from_glib(value: ffi::SoupDateFormat) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_DATE_HTTP => Self::Http, ffi::SOUP_DATE_COOKIE => Self::Cookie, value => Self::__Unknown(value), } } } impl StaticType for DateFormat { #[inline] #[doc(alias = "soup_date_format_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_date_format_get_type()) } } } impl glib::HasParamSpec for DateFormat { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for DateFormat { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for DateFormat { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for DateFormat { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: DateFormat) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupEncoding")] pub enum Encoding { #[doc(alias = "SOUP_ENCODING_UNRECOGNIZED")] Unrecognized, #[doc(alias = "SOUP_ENCODING_NONE")] None, #[doc(alias = "SOUP_ENCODING_CONTENT_LENGTH")] ContentLength, #[doc(alias = "SOUP_ENCODING_EOF")] Eof, #[doc(alias = "SOUP_ENCODING_CHUNKED")] Chunked, #[doc(alias = "SOUP_ENCODING_BYTERANGES")] Byteranges, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for Encoding { type GlibType = ffi::SoupEncoding; #[inline] fn into_glib(self) -> ffi::SoupEncoding { match self { Self::Unrecognized => ffi::SOUP_ENCODING_UNRECOGNIZED, Self::None => ffi::SOUP_ENCODING_NONE, Self::ContentLength => ffi::SOUP_ENCODING_CONTENT_LENGTH, Self::Eof => ffi::SOUP_ENCODING_EOF, Self::Chunked => ffi::SOUP_ENCODING_CHUNKED, Self::Byteranges => ffi::SOUP_ENCODING_BYTERANGES, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for Encoding { #[inline] unsafe fn from_glib(value: ffi::SoupEncoding) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_ENCODING_UNRECOGNIZED => Self::Unrecognized, ffi::SOUP_ENCODING_NONE => Self::None, ffi::SOUP_ENCODING_CONTENT_LENGTH => Self::ContentLength, ffi::SOUP_ENCODING_EOF => Self::Eof, ffi::SOUP_ENCODING_CHUNKED => Self::Chunked, ffi::SOUP_ENCODING_BYTERANGES => Self::Byteranges, value => Self::__Unknown(value), } } } impl StaticType for Encoding { #[inline] #[doc(alias = "soup_encoding_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_encoding_get_type()) } } } impl glib::HasParamSpec for Encoding { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for Encoding { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for Encoding { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for Encoding { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: Encoding) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupHTTPVersion")] pub enum HTTPVersion { #[doc(alias = "SOUP_HTTP_1_0")] Http10, #[doc(alias = "SOUP_HTTP_1_1")] Http11, #[doc(alias = "SOUP_HTTP_2_0")] Http20, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for HTTPVersion { type GlibType = ffi::SoupHTTPVersion; #[inline] fn into_glib(self) -> ffi::SoupHTTPVersion { match self { Self::Http10 => ffi::SOUP_HTTP_1_0, Self::Http11 => ffi::SOUP_HTTP_1_1, Self::Http20 => ffi::SOUP_HTTP_2_0, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for HTTPVersion { #[inline] unsafe fn from_glib(value: ffi::SoupHTTPVersion) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_HTTP_1_0 => Self::Http10, ffi::SOUP_HTTP_1_1 => Self::Http11, ffi::SOUP_HTTP_2_0 => Self::Http20, value => Self::__Unknown(value), } } } impl StaticType for HTTPVersion { #[inline] #[doc(alias = "soup_http_version_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_http_version_get_type()) } } } impl glib::HasParamSpec for HTTPVersion { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for HTTPVersion { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for HTTPVersion { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for HTTPVersion { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: HTTPVersion) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupLoggerLogLevel")] pub enum LoggerLogLevel { #[doc(alias = "SOUP_LOGGER_LOG_NONE")] None, #[doc(alias = "SOUP_LOGGER_LOG_MINIMAL")] Minimal, #[doc(alias = "SOUP_LOGGER_LOG_HEADERS")] Headers, #[doc(alias = "SOUP_LOGGER_LOG_BODY")] Body, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for LoggerLogLevel { type GlibType = ffi::SoupLoggerLogLevel; #[inline] fn into_glib(self) -> ffi::SoupLoggerLogLevel { match self { Self::None => ffi::SOUP_LOGGER_LOG_NONE, Self::Minimal => ffi::SOUP_LOGGER_LOG_MINIMAL, Self::Headers => ffi::SOUP_LOGGER_LOG_HEADERS, Self::Body => ffi::SOUP_LOGGER_LOG_BODY, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for LoggerLogLevel { #[inline] unsafe fn from_glib(value: ffi::SoupLoggerLogLevel) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_LOGGER_LOG_NONE => Self::None, ffi::SOUP_LOGGER_LOG_MINIMAL => Self::Minimal, ffi::SOUP_LOGGER_LOG_HEADERS => Self::Headers, ffi::SOUP_LOGGER_LOG_BODY => Self::Body, value => Self::__Unknown(value), } } } impl StaticType for LoggerLogLevel { #[inline] #[doc(alias = "soup_logger_log_level_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_logger_log_level_get_type()) } } } impl glib::HasParamSpec for LoggerLogLevel { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for LoggerLogLevel { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for LoggerLogLevel { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for LoggerLogLevel { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: LoggerLogLevel) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupMemoryUse")] pub enum MemoryUse { #[doc(alias = "SOUP_MEMORY_STATIC")] Static, #[doc(alias = "SOUP_MEMORY_TAKE")] Take, #[doc(alias = "SOUP_MEMORY_COPY")] Copy, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for MemoryUse { type GlibType = ffi::SoupMemoryUse; #[inline] fn into_glib(self) -> ffi::SoupMemoryUse { match self { Self::Static => ffi::SOUP_MEMORY_STATIC, Self::Take => ffi::SOUP_MEMORY_TAKE, Self::Copy => ffi::SOUP_MEMORY_COPY, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for MemoryUse { #[inline] unsafe fn from_glib(value: ffi::SoupMemoryUse) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_MEMORY_STATIC => Self::Static, ffi::SOUP_MEMORY_TAKE => Self::Take, ffi::SOUP_MEMORY_COPY => Self::Copy, value => Self::__Unknown(value), } } } impl StaticType for MemoryUse { #[inline] #[doc(alias = "soup_memory_use_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_memory_use_get_type()) } } } impl glib::HasParamSpec for MemoryUse { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for MemoryUse { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for MemoryUse { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for MemoryUse { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: MemoryUse) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupMessageHeadersType")] pub enum MessageHeadersType { #[doc(alias = "SOUP_MESSAGE_HEADERS_REQUEST")] Request, #[doc(alias = "SOUP_MESSAGE_HEADERS_RESPONSE")] Response, #[doc(alias = "SOUP_MESSAGE_HEADERS_MULTIPART")] Multipart, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for MessageHeadersType { type GlibType = ffi::SoupMessageHeadersType; #[inline] fn into_glib(self) -> ffi::SoupMessageHeadersType { match self { Self::Request => ffi::SOUP_MESSAGE_HEADERS_REQUEST, Self::Response => ffi::SOUP_MESSAGE_HEADERS_RESPONSE, Self::Multipart => ffi::SOUP_MESSAGE_HEADERS_MULTIPART, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for MessageHeadersType { #[inline] unsafe fn from_glib(value: ffi::SoupMessageHeadersType) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_MESSAGE_HEADERS_REQUEST => Self::Request, ffi::SOUP_MESSAGE_HEADERS_RESPONSE => Self::Response, ffi::SOUP_MESSAGE_HEADERS_MULTIPART => Self::Multipart, value => Self::__Unknown(value), } } } impl StaticType for MessageHeadersType { #[inline] #[doc(alias = "soup_message_headers_type_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_message_headers_type_get_type()) } } } impl glib::HasParamSpec for MessageHeadersType { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for MessageHeadersType { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for MessageHeadersType { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for MessageHeadersType { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: MessageHeadersType) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupMessagePriority")] pub enum MessagePriority { #[doc(alias = "SOUP_MESSAGE_PRIORITY_VERY_LOW")] VeryLow, #[doc(alias = "SOUP_MESSAGE_PRIORITY_LOW")] Low, #[doc(alias = "SOUP_MESSAGE_PRIORITY_NORMAL")] Normal, #[doc(alias = "SOUP_MESSAGE_PRIORITY_HIGH")] High, #[doc(alias = "SOUP_MESSAGE_PRIORITY_VERY_HIGH")] VeryHigh, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for MessagePriority { type GlibType = ffi::SoupMessagePriority; #[inline] fn into_glib(self) -> ffi::SoupMessagePriority { match self { Self::VeryLow => ffi::SOUP_MESSAGE_PRIORITY_VERY_LOW, Self::Low => ffi::SOUP_MESSAGE_PRIORITY_LOW, Self::Normal => ffi::SOUP_MESSAGE_PRIORITY_NORMAL, Self::High => ffi::SOUP_MESSAGE_PRIORITY_HIGH, Self::VeryHigh => ffi::SOUP_MESSAGE_PRIORITY_VERY_HIGH, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for MessagePriority { #[inline] unsafe fn from_glib(value: ffi::SoupMessagePriority) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_MESSAGE_PRIORITY_VERY_LOW => Self::VeryLow, ffi::SOUP_MESSAGE_PRIORITY_LOW => Self::Low, ffi::SOUP_MESSAGE_PRIORITY_NORMAL => Self::Normal, ffi::SOUP_MESSAGE_PRIORITY_HIGH => Self::High, ffi::SOUP_MESSAGE_PRIORITY_VERY_HIGH => Self::VeryHigh, value => Self::__Unknown(value), } } } impl StaticType for MessagePriority { #[inline] #[doc(alias = "soup_message_priority_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_message_priority_get_type()) } } } impl glib::HasParamSpec for MessagePriority { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for MessagePriority { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for MessagePriority { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for MessagePriority { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: MessagePriority) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupSameSitePolicy")] pub enum SameSitePolicy { #[doc(alias = "SOUP_SAME_SITE_POLICY_NONE")] None, #[doc(alias = "SOUP_SAME_SITE_POLICY_LAX")] Lax, #[doc(alias = "SOUP_SAME_SITE_POLICY_STRICT")] Strict, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for SameSitePolicy { type GlibType = ffi::SoupSameSitePolicy; #[inline] fn into_glib(self) -> ffi::SoupSameSitePolicy { match self { Self::None => ffi::SOUP_SAME_SITE_POLICY_NONE, Self::Lax => ffi::SOUP_SAME_SITE_POLICY_LAX, Self::Strict => ffi::SOUP_SAME_SITE_POLICY_STRICT, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for SameSitePolicy { #[inline] unsafe fn from_glib(value: ffi::SoupSameSitePolicy) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_SAME_SITE_POLICY_NONE => Self::None, ffi::SOUP_SAME_SITE_POLICY_LAX => Self::Lax, ffi::SOUP_SAME_SITE_POLICY_STRICT => Self::Strict, value => Self::__Unknown(value), } } } impl StaticType for SameSitePolicy { #[inline] #[doc(alias = "soup_same_site_policy_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_same_site_policy_get_type()) } } } impl glib::HasParamSpec for SameSitePolicy { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for SameSitePolicy { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for SameSitePolicy { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for SameSitePolicy { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: SameSitePolicy) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupSessionError")] pub enum SessionError { #[doc(alias = "SOUP_SESSION_ERROR_PARSING")] Parsing, #[doc(alias = "SOUP_SESSION_ERROR_ENCODING")] Encoding, #[doc(alias = "SOUP_SESSION_ERROR_TOO_MANY_REDIRECTS")] TooManyRedirects, #[doc(alias = "SOUP_SESSION_ERROR_TOO_MANY_RESTARTS")] TooManyRestarts, #[doc(alias = "SOUP_SESSION_ERROR_REDIRECT_NO_LOCATION")] RedirectNoLocation, #[doc(alias = "SOUP_SESSION_ERROR_REDIRECT_BAD_URI")] RedirectBadUri, #[doc(alias = "SOUP_SESSION_ERROR_MESSAGE_ALREADY_IN_QUEUE")] MessageAlreadyInQueue, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for SessionError { type GlibType = ffi::SoupSessionError; #[inline] fn into_glib(self) -> ffi::SoupSessionError { match self { Self::Parsing => ffi::SOUP_SESSION_ERROR_PARSING, Self::Encoding => ffi::SOUP_SESSION_ERROR_ENCODING, Self::TooManyRedirects => ffi::SOUP_SESSION_ERROR_TOO_MANY_REDIRECTS, Self::TooManyRestarts => ffi::SOUP_SESSION_ERROR_TOO_MANY_RESTARTS, Self::RedirectNoLocation => ffi::SOUP_SESSION_ERROR_REDIRECT_NO_LOCATION, Self::RedirectBadUri => ffi::SOUP_SESSION_ERROR_REDIRECT_BAD_URI, Self::MessageAlreadyInQueue => ffi::SOUP_SESSION_ERROR_MESSAGE_ALREADY_IN_QUEUE, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for SessionError { #[inline] unsafe fn from_glib(value: ffi::SoupSessionError) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_SESSION_ERROR_PARSING => Self::Parsing, ffi::SOUP_SESSION_ERROR_ENCODING => Self::Encoding, ffi::SOUP_SESSION_ERROR_TOO_MANY_REDIRECTS => Self::TooManyRedirects, ffi::SOUP_SESSION_ERROR_TOO_MANY_RESTARTS => Self::TooManyRestarts, ffi::SOUP_SESSION_ERROR_REDIRECT_NO_LOCATION => Self::RedirectNoLocation, ffi::SOUP_SESSION_ERROR_REDIRECT_BAD_URI => Self::RedirectBadUri, ffi::SOUP_SESSION_ERROR_MESSAGE_ALREADY_IN_QUEUE => Self::MessageAlreadyInQueue, value => Self::__Unknown(value), } } } impl glib::error::ErrorDomain for SessionError { #[inline] fn domain() -> glib::Quark { skip_assert_initialized!(); unsafe { from_glib(ffi::soup_session_error_quark()) } } #[inline] fn code(self) -> i32 { self.into_glib() } #[inline] #[allow(clippy::match_single_binding)] fn from(code: i32) -> Option { skip_assert_initialized!(); match unsafe { from_glib(code) } { value => Some(value), } } } impl StaticType for SessionError { #[inline] #[doc(alias = "soup_session_error_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_session_error_get_type()) } } } impl glib::HasParamSpec for SessionError { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for SessionError { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for SessionError { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for SessionError { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: SessionError) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupStatus")] pub enum Status { #[doc(alias = "SOUP_STATUS_NONE")] None, #[doc(alias = "SOUP_STATUS_CONTINUE")] Continue, #[doc(alias = "SOUP_STATUS_SWITCHING_PROTOCOLS")] SwitchingProtocols, #[doc(alias = "SOUP_STATUS_PROCESSING")] Processing, #[doc(alias = "SOUP_STATUS_OK")] Ok, #[doc(alias = "SOUP_STATUS_CREATED")] Created, #[doc(alias = "SOUP_STATUS_ACCEPTED")] Accepted, #[doc(alias = "SOUP_STATUS_NON_AUTHORITATIVE")] NonAuthoritative, #[doc(alias = "SOUP_STATUS_NO_CONTENT")] NoContent, #[doc(alias = "SOUP_STATUS_RESET_CONTENT")] ResetContent, #[doc(alias = "SOUP_STATUS_PARTIAL_CONTENT")] PartialContent, #[doc(alias = "SOUP_STATUS_MULTI_STATUS")] MultiStatus, #[doc(alias = "SOUP_STATUS_MULTIPLE_CHOICES")] MultipleChoices, #[doc(alias = "SOUP_STATUS_MOVED_PERMANENTLY")] MovedPermanently, #[doc(alias = "SOUP_STATUS_FOUND")] Found, #[doc(alias = "SOUP_STATUS_SEE_OTHER")] SeeOther, #[doc(alias = "SOUP_STATUS_NOT_MODIFIED")] NotModified, #[doc(alias = "SOUP_STATUS_USE_PROXY")] UseProxy, #[doc(alias = "SOUP_STATUS_NOT_APPEARING_IN_THIS_PROTOCOL")] NotAppearingInThisProtocol, #[doc(alias = "SOUP_STATUS_TEMPORARY_REDIRECT")] TemporaryRedirect, #[doc(alias = "SOUP_STATUS_PERMANENT_REDIRECT")] PermanentRedirect, #[doc(alias = "SOUP_STATUS_BAD_REQUEST")] BadRequest, #[doc(alias = "SOUP_STATUS_UNAUTHORIZED")] Unauthorized, #[doc(alias = "SOUP_STATUS_PAYMENT_REQUIRED")] PaymentRequired, #[doc(alias = "SOUP_STATUS_FORBIDDEN")] Forbidden, #[doc(alias = "SOUP_STATUS_NOT_FOUND")] NotFound, #[doc(alias = "SOUP_STATUS_METHOD_NOT_ALLOWED")] MethodNotAllowed, #[doc(alias = "SOUP_STATUS_NOT_ACCEPTABLE")] NotAcceptable, #[doc(alias = "SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED")] ProxyAuthenticationRequired, #[doc(alias = "SOUP_STATUS_REQUEST_TIMEOUT")] RequestTimeout, #[doc(alias = "SOUP_STATUS_CONFLICT")] Conflict, #[doc(alias = "SOUP_STATUS_GONE")] Gone, #[doc(alias = "SOUP_STATUS_LENGTH_REQUIRED")] LengthRequired, #[doc(alias = "SOUP_STATUS_PRECONDITION_FAILED")] PreconditionFailed, #[doc(alias = "SOUP_STATUS_REQUEST_ENTITY_TOO_LARGE")] RequestEntityTooLarge, #[doc(alias = "SOUP_STATUS_REQUEST_URI_TOO_LONG")] RequestUriTooLong, #[doc(alias = "SOUP_STATUS_UNSUPPORTED_MEDIA_TYPE")] UnsupportedMediaType, #[doc(alias = "SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE")] RequestedRangeNotSatisfiable, #[doc(alias = "SOUP_STATUS_EXPECTATION_FAILED")] ExpectationFailed, #[doc(alias = "SOUP_STATUS_MISDIRECTED_REQUEST")] MisdirectedRequest, #[doc(alias = "SOUP_STATUS_UNPROCESSABLE_ENTITY")] UnprocessableEntity, #[doc(alias = "SOUP_STATUS_LOCKED")] Locked, #[doc(alias = "SOUP_STATUS_FAILED_DEPENDENCY")] FailedDependency, #[doc(alias = "SOUP_STATUS_INTERNAL_SERVER_ERROR")] InternalServerError, #[doc(alias = "SOUP_STATUS_NOT_IMPLEMENTED")] NotImplemented, #[doc(alias = "SOUP_STATUS_BAD_GATEWAY")] BadGateway, #[doc(alias = "SOUP_STATUS_SERVICE_UNAVAILABLE")] ServiceUnavailable, #[doc(alias = "SOUP_STATUS_GATEWAY_TIMEOUT")] GatewayTimeout, #[doc(alias = "SOUP_STATUS_HTTP_VERSION_NOT_SUPPORTED")] HttpVersionNotSupported, #[doc(alias = "SOUP_STATUS_INSUFFICIENT_STORAGE")] InsufficientStorage, #[doc(alias = "SOUP_STATUS_NOT_EXTENDED")] NotExtended, #[doc(hidden)] __Unknown(i32), } impl Status { #[doc(alias = "soup_status_get_phrase")] #[doc(alias = "get_phrase")] pub fn phrase(status_code: u32) -> Option { assert_initialized_main_thread!(); unsafe { from_glib_none(ffi::soup_status_get_phrase(status_code)) } } } #[doc(hidden)] impl IntoGlib for Status { type GlibType = ffi::SoupStatus; fn into_glib(self) -> ffi::SoupStatus { match self { Self::None => ffi::SOUP_STATUS_NONE, Self::Continue => ffi::SOUP_STATUS_CONTINUE, Self::SwitchingProtocols => ffi::SOUP_STATUS_SWITCHING_PROTOCOLS, Self::Processing => ffi::SOUP_STATUS_PROCESSING, Self::Ok => ffi::SOUP_STATUS_OK, Self::Created => ffi::SOUP_STATUS_CREATED, Self::Accepted => ffi::SOUP_STATUS_ACCEPTED, Self::NonAuthoritative => ffi::SOUP_STATUS_NON_AUTHORITATIVE, Self::NoContent => ffi::SOUP_STATUS_NO_CONTENT, Self::ResetContent => ffi::SOUP_STATUS_RESET_CONTENT, Self::PartialContent => ffi::SOUP_STATUS_PARTIAL_CONTENT, Self::MultiStatus => ffi::SOUP_STATUS_MULTI_STATUS, Self::MultipleChoices => ffi::SOUP_STATUS_MULTIPLE_CHOICES, Self::MovedPermanently => ffi::SOUP_STATUS_MOVED_PERMANENTLY, Self::Found => ffi::SOUP_STATUS_FOUND, Self::SeeOther => ffi::SOUP_STATUS_SEE_OTHER, Self::NotModified => ffi::SOUP_STATUS_NOT_MODIFIED, Self::UseProxy => ffi::SOUP_STATUS_USE_PROXY, Self::NotAppearingInThisProtocol => ffi::SOUP_STATUS_NOT_APPEARING_IN_THIS_PROTOCOL, Self::TemporaryRedirect => ffi::SOUP_STATUS_TEMPORARY_REDIRECT, Self::PermanentRedirect => ffi::SOUP_STATUS_PERMANENT_REDIRECT, Self::BadRequest => ffi::SOUP_STATUS_BAD_REQUEST, Self::Unauthorized => ffi::SOUP_STATUS_UNAUTHORIZED, Self::PaymentRequired => ffi::SOUP_STATUS_PAYMENT_REQUIRED, Self::Forbidden => ffi::SOUP_STATUS_FORBIDDEN, Self::NotFound => ffi::SOUP_STATUS_NOT_FOUND, Self::MethodNotAllowed => ffi::SOUP_STATUS_METHOD_NOT_ALLOWED, Self::NotAcceptable => ffi::SOUP_STATUS_NOT_ACCEPTABLE, Self::ProxyAuthenticationRequired => ffi::SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED, Self::RequestTimeout => ffi::SOUP_STATUS_REQUEST_TIMEOUT, Self::Conflict => ffi::SOUP_STATUS_CONFLICT, Self::Gone => ffi::SOUP_STATUS_GONE, Self::LengthRequired => ffi::SOUP_STATUS_LENGTH_REQUIRED, Self::PreconditionFailed => ffi::SOUP_STATUS_PRECONDITION_FAILED, Self::RequestEntityTooLarge => ffi::SOUP_STATUS_REQUEST_ENTITY_TOO_LARGE, Self::RequestUriTooLong => ffi::SOUP_STATUS_REQUEST_URI_TOO_LONG, Self::UnsupportedMediaType => ffi::SOUP_STATUS_UNSUPPORTED_MEDIA_TYPE, Self::RequestedRangeNotSatisfiable => ffi::SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE, Self::ExpectationFailed => ffi::SOUP_STATUS_EXPECTATION_FAILED, Self::MisdirectedRequest => ffi::SOUP_STATUS_MISDIRECTED_REQUEST, Self::UnprocessableEntity => ffi::SOUP_STATUS_UNPROCESSABLE_ENTITY, Self::Locked => ffi::SOUP_STATUS_LOCKED, Self::FailedDependency => ffi::SOUP_STATUS_FAILED_DEPENDENCY, Self::InternalServerError => ffi::SOUP_STATUS_INTERNAL_SERVER_ERROR, Self::NotImplemented => ffi::SOUP_STATUS_NOT_IMPLEMENTED, Self::BadGateway => ffi::SOUP_STATUS_BAD_GATEWAY, Self::ServiceUnavailable => ffi::SOUP_STATUS_SERVICE_UNAVAILABLE, Self::GatewayTimeout => ffi::SOUP_STATUS_GATEWAY_TIMEOUT, Self::HttpVersionNotSupported => ffi::SOUP_STATUS_HTTP_VERSION_NOT_SUPPORTED, Self::InsufficientStorage => ffi::SOUP_STATUS_INSUFFICIENT_STORAGE, Self::NotExtended => ffi::SOUP_STATUS_NOT_EXTENDED, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for Status { unsafe fn from_glib(value: ffi::SoupStatus) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_STATUS_NONE => Self::None, ffi::SOUP_STATUS_CONTINUE => Self::Continue, ffi::SOUP_STATUS_SWITCHING_PROTOCOLS => Self::SwitchingProtocols, ffi::SOUP_STATUS_PROCESSING => Self::Processing, ffi::SOUP_STATUS_OK => Self::Ok, ffi::SOUP_STATUS_CREATED => Self::Created, ffi::SOUP_STATUS_ACCEPTED => Self::Accepted, ffi::SOUP_STATUS_NON_AUTHORITATIVE => Self::NonAuthoritative, ffi::SOUP_STATUS_NO_CONTENT => Self::NoContent, ffi::SOUP_STATUS_RESET_CONTENT => Self::ResetContent, ffi::SOUP_STATUS_PARTIAL_CONTENT => Self::PartialContent, ffi::SOUP_STATUS_MULTI_STATUS => Self::MultiStatus, ffi::SOUP_STATUS_MULTIPLE_CHOICES => Self::MultipleChoices, ffi::SOUP_STATUS_MOVED_PERMANENTLY => Self::MovedPermanently, ffi::SOUP_STATUS_FOUND => Self::Found, ffi::SOUP_STATUS_SEE_OTHER => Self::SeeOther, ffi::SOUP_STATUS_NOT_MODIFIED => Self::NotModified, ffi::SOUP_STATUS_USE_PROXY => Self::UseProxy, ffi::SOUP_STATUS_NOT_APPEARING_IN_THIS_PROTOCOL => Self::NotAppearingInThisProtocol, ffi::SOUP_STATUS_TEMPORARY_REDIRECT => Self::TemporaryRedirect, ffi::SOUP_STATUS_PERMANENT_REDIRECT => Self::PermanentRedirect, ffi::SOUP_STATUS_BAD_REQUEST => Self::BadRequest, ffi::SOUP_STATUS_UNAUTHORIZED => Self::Unauthorized, ffi::SOUP_STATUS_PAYMENT_REQUIRED => Self::PaymentRequired, ffi::SOUP_STATUS_FORBIDDEN => Self::Forbidden, ffi::SOUP_STATUS_NOT_FOUND => Self::NotFound, ffi::SOUP_STATUS_METHOD_NOT_ALLOWED => Self::MethodNotAllowed, ffi::SOUP_STATUS_NOT_ACCEPTABLE => Self::NotAcceptable, ffi::SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED => Self::ProxyAuthenticationRequired, ffi::SOUP_STATUS_REQUEST_TIMEOUT => Self::RequestTimeout, ffi::SOUP_STATUS_CONFLICT => Self::Conflict, ffi::SOUP_STATUS_GONE => Self::Gone, ffi::SOUP_STATUS_LENGTH_REQUIRED => Self::LengthRequired, ffi::SOUP_STATUS_PRECONDITION_FAILED => Self::PreconditionFailed, ffi::SOUP_STATUS_REQUEST_ENTITY_TOO_LARGE => Self::RequestEntityTooLarge, ffi::SOUP_STATUS_REQUEST_URI_TOO_LONG => Self::RequestUriTooLong, ffi::SOUP_STATUS_UNSUPPORTED_MEDIA_TYPE => Self::UnsupportedMediaType, ffi::SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE => Self::RequestedRangeNotSatisfiable, ffi::SOUP_STATUS_EXPECTATION_FAILED => Self::ExpectationFailed, ffi::SOUP_STATUS_MISDIRECTED_REQUEST => Self::MisdirectedRequest, ffi::SOUP_STATUS_UNPROCESSABLE_ENTITY => Self::UnprocessableEntity, ffi::SOUP_STATUS_LOCKED => Self::Locked, ffi::SOUP_STATUS_FAILED_DEPENDENCY => Self::FailedDependency, ffi::SOUP_STATUS_INTERNAL_SERVER_ERROR => Self::InternalServerError, ffi::SOUP_STATUS_NOT_IMPLEMENTED => Self::NotImplemented, ffi::SOUP_STATUS_BAD_GATEWAY => Self::BadGateway, ffi::SOUP_STATUS_SERVICE_UNAVAILABLE => Self::ServiceUnavailable, ffi::SOUP_STATUS_GATEWAY_TIMEOUT => Self::GatewayTimeout, ffi::SOUP_STATUS_HTTP_VERSION_NOT_SUPPORTED => Self::HttpVersionNotSupported, ffi::SOUP_STATUS_INSUFFICIENT_STORAGE => Self::InsufficientStorage, ffi::SOUP_STATUS_NOT_EXTENDED => Self::NotExtended, value => Self::__Unknown(value), } } } impl StaticType for Status { #[inline] #[doc(alias = "soup_status_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_status_get_type()) } } } impl glib::HasParamSpec for Status { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for Status { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for Status { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for Status { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: Status) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupTLDError")] pub enum TLDError { #[doc(alias = "SOUP_TLD_ERROR_INVALID_HOSTNAME")] InvalidHostname, #[doc(alias = "SOUP_TLD_ERROR_IS_IP_ADDRESS")] IsIpAddress, #[doc(alias = "SOUP_TLD_ERROR_NOT_ENOUGH_DOMAINS")] NotEnoughDomains, #[doc(alias = "SOUP_TLD_ERROR_NO_BASE_DOMAIN")] NoBaseDomain, #[doc(alias = "SOUP_TLD_ERROR_NO_PSL_DATA")] NoPslData, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for TLDError { type GlibType = ffi::SoupTLDError; #[inline] fn into_glib(self) -> ffi::SoupTLDError { match self { Self::InvalidHostname => ffi::SOUP_TLD_ERROR_INVALID_HOSTNAME, Self::IsIpAddress => ffi::SOUP_TLD_ERROR_IS_IP_ADDRESS, Self::NotEnoughDomains => ffi::SOUP_TLD_ERROR_NOT_ENOUGH_DOMAINS, Self::NoBaseDomain => ffi::SOUP_TLD_ERROR_NO_BASE_DOMAIN, Self::NoPslData => ffi::SOUP_TLD_ERROR_NO_PSL_DATA, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for TLDError { #[inline] unsafe fn from_glib(value: ffi::SoupTLDError) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_TLD_ERROR_INVALID_HOSTNAME => Self::InvalidHostname, ffi::SOUP_TLD_ERROR_IS_IP_ADDRESS => Self::IsIpAddress, ffi::SOUP_TLD_ERROR_NOT_ENOUGH_DOMAINS => Self::NotEnoughDomains, ffi::SOUP_TLD_ERROR_NO_BASE_DOMAIN => Self::NoBaseDomain, ffi::SOUP_TLD_ERROR_NO_PSL_DATA => Self::NoPslData, value => Self::__Unknown(value), } } } impl glib::error::ErrorDomain for TLDError { #[inline] fn domain() -> glib::Quark { skip_assert_initialized!(); unsafe { from_glib(ffi::soup_tld_error_quark()) } } #[inline] fn code(self) -> i32 { self.into_glib() } #[inline] #[allow(clippy::match_single_binding)] fn from(code: i32) -> Option { skip_assert_initialized!(); match unsafe { from_glib(code) } { value => Some(value), } } } impl StaticType for TLDError { #[inline] #[doc(alias = "soup_tld_error_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_tld_error_get_type()) } } } impl glib::HasParamSpec for TLDError { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for TLDError { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for TLDError { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for TLDError { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: TLDError) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupURIComponent")] pub enum URIComponent { #[doc(alias = "SOUP_URI_NONE")] None, #[doc(alias = "SOUP_URI_SCHEME")] Scheme, #[doc(alias = "SOUP_URI_USER")] User, #[doc(alias = "SOUP_URI_PASSWORD")] Password, #[doc(alias = "SOUP_URI_AUTH_PARAMS")] AuthParams, #[doc(alias = "SOUP_URI_HOST")] Host, #[doc(alias = "SOUP_URI_PORT")] Port, #[doc(alias = "SOUP_URI_PATH")] Path, #[doc(alias = "SOUP_URI_QUERY")] Query, #[doc(alias = "SOUP_URI_FRAGMENT")] Fragment, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for URIComponent { type GlibType = ffi::SoupURIComponent; #[inline] fn into_glib(self) -> ffi::SoupURIComponent { match self { Self::None => ffi::SOUP_URI_NONE, Self::Scheme => ffi::SOUP_URI_SCHEME, Self::User => ffi::SOUP_URI_USER, Self::Password => ffi::SOUP_URI_PASSWORD, Self::AuthParams => ffi::SOUP_URI_AUTH_PARAMS, Self::Host => ffi::SOUP_URI_HOST, Self::Port => ffi::SOUP_URI_PORT, Self::Path => ffi::SOUP_URI_PATH, Self::Query => ffi::SOUP_URI_QUERY, Self::Fragment => ffi::SOUP_URI_FRAGMENT, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for URIComponent { #[inline] unsafe fn from_glib(value: ffi::SoupURIComponent) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_URI_NONE => Self::None, ffi::SOUP_URI_SCHEME => Self::Scheme, ffi::SOUP_URI_USER => Self::User, ffi::SOUP_URI_PASSWORD => Self::Password, ffi::SOUP_URI_AUTH_PARAMS => Self::AuthParams, ffi::SOUP_URI_HOST => Self::Host, ffi::SOUP_URI_PORT => Self::Port, ffi::SOUP_URI_PATH => Self::Path, ffi::SOUP_URI_QUERY => Self::Query, ffi::SOUP_URI_FRAGMENT => Self::Fragment, value => Self::__Unknown(value), } } } impl StaticType for URIComponent { #[inline] #[doc(alias = "soup_uri_component_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_uri_component_get_type()) } } } impl glib::HasParamSpec for URIComponent { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for URIComponent { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for URIComponent { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for URIComponent { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: URIComponent) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupWebsocketCloseCode")] pub enum WebsocketCloseCode { #[doc(alias = "SOUP_WEBSOCKET_CLOSE_NORMAL")] Normal, #[doc(alias = "SOUP_WEBSOCKET_CLOSE_GOING_AWAY")] GoingAway, #[doc(alias = "SOUP_WEBSOCKET_CLOSE_PROTOCOL_ERROR")] ProtocolError, #[doc(alias = "SOUP_WEBSOCKET_CLOSE_UNSUPPORTED_DATA")] UnsupportedData, #[doc(alias = "SOUP_WEBSOCKET_CLOSE_NO_STATUS")] NoStatus, #[doc(alias = "SOUP_WEBSOCKET_CLOSE_ABNORMAL")] Abnormal, #[doc(alias = "SOUP_WEBSOCKET_CLOSE_BAD_DATA")] BadData, #[doc(alias = "SOUP_WEBSOCKET_CLOSE_POLICY_VIOLATION")] PolicyViolation, #[doc(alias = "SOUP_WEBSOCKET_CLOSE_TOO_BIG")] TooBig, #[doc(alias = "SOUP_WEBSOCKET_CLOSE_NO_EXTENSION")] NoExtension, #[doc(alias = "SOUP_WEBSOCKET_CLOSE_SERVER_ERROR")] ServerError, #[doc(alias = "SOUP_WEBSOCKET_CLOSE_TLS_HANDSHAKE")] TlsHandshake, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for WebsocketCloseCode { type GlibType = ffi::SoupWebsocketCloseCode; #[inline] fn into_glib(self) -> ffi::SoupWebsocketCloseCode { match self { Self::Normal => ffi::SOUP_WEBSOCKET_CLOSE_NORMAL, Self::GoingAway => ffi::SOUP_WEBSOCKET_CLOSE_GOING_AWAY, Self::ProtocolError => ffi::SOUP_WEBSOCKET_CLOSE_PROTOCOL_ERROR, Self::UnsupportedData => ffi::SOUP_WEBSOCKET_CLOSE_UNSUPPORTED_DATA, Self::NoStatus => ffi::SOUP_WEBSOCKET_CLOSE_NO_STATUS, Self::Abnormal => ffi::SOUP_WEBSOCKET_CLOSE_ABNORMAL, Self::BadData => ffi::SOUP_WEBSOCKET_CLOSE_BAD_DATA, Self::PolicyViolation => ffi::SOUP_WEBSOCKET_CLOSE_POLICY_VIOLATION, Self::TooBig => ffi::SOUP_WEBSOCKET_CLOSE_TOO_BIG, Self::NoExtension => ffi::SOUP_WEBSOCKET_CLOSE_NO_EXTENSION, Self::ServerError => ffi::SOUP_WEBSOCKET_CLOSE_SERVER_ERROR, Self::TlsHandshake => ffi::SOUP_WEBSOCKET_CLOSE_TLS_HANDSHAKE, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for WebsocketCloseCode { #[inline] unsafe fn from_glib(value: ffi::SoupWebsocketCloseCode) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_WEBSOCKET_CLOSE_NORMAL => Self::Normal, ffi::SOUP_WEBSOCKET_CLOSE_GOING_AWAY => Self::GoingAway, ffi::SOUP_WEBSOCKET_CLOSE_PROTOCOL_ERROR => Self::ProtocolError, ffi::SOUP_WEBSOCKET_CLOSE_UNSUPPORTED_DATA => Self::UnsupportedData, ffi::SOUP_WEBSOCKET_CLOSE_NO_STATUS => Self::NoStatus, ffi::SOUP_WEBSOCKET_CLOSE_ABNORMAL => Self::Abnormal, ffi::SOUP_WEBSOCKET_CLOSE_BAD_DATA => Self::BadData, ffi::SOUP_WEBSOCKET_CLOSE_POLICY_VIOLATION => Self::PolicyViolation, ffi::SOUP_WEBSOCKET_CLOSE_TOO_BIG => Self::TooBig, ffi::SOUP_WEBSOCKET_CLOSE_NO_EXTENSION => Self::NoExtension, ffi::SOUP_WEBSOCKET_CLOSE_SERVER_ERROR => Self::ServerError, ffi::SOUP_WEBSOCKET_CLOSE_TLS_HANDSHAKE => Self::TlsHandshake, value => Self::__Unknown(value), } } } impl StaticType for WebsocketCloseCode { #[inline] #[doc(alias = "soup_websocket_close_code_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_websocket_close_code_get_type()) } } } impl glib::HasParamSpec for WebsocketCloseCode { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for WebsocketCloseCode { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for WebsocketCloseCode { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for WebsocketCloseCode { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: WebsocketCloseCode) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupWebsocketConnectionType")] pub enum WebsocketConnectionType { #[doc(alias = "SOUP_WEBSOCKET_CONNECTION_UNKNOWN")] Unknown, #[doc(alias = "SOUP_WEBSOCKET_CONNECTION_CLIENT")] Client, #[doc(alias = "SOUP_WEBSOCKET_CONNECTION_SERVER")] Server, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for WebsocketConnectionType { type GlibType = ffi::SoupWebsocketConnectionType; #[inline] fn into_glib(self) -> ffi::SoupWebsocketConnectionType { match self { Self::Unknown => ffi::SOUP_WEBSOCKET_CONNECTION_UNKNOWN, Self::Client => ffi::SOUP_WEBSOCKET_CONNECTION_CLIENT, Self::Server => ffi::SOUP_WEBSOCKET_CONNECTION_SERVER, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for WebsocketConnectionType { #[inline] unsafe fn from_glib(value: ffi::SoupWebsocketConnectionType) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_WEBSOCKET_CONNECTION_UNKNOWN => Self::Unknown, ffi::SOUP_WEBSOCKET_CONNECTION_CLIENT => Self::Client, ffi::SOUP_WEBSOCKET_CONNECTION_SERVER => Self::Server, value => Self::__Unknown(value), } } } impl StaticType for WebsocketConnectionType { #[inline] #[doc(alias = "soup_websocket_connection_type_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_websocket_connection_type_get_type()) } } } impl glib::HasParamSpec for WebsocketConnectionType { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for WebsocketConnectionType { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for WebsocketConnectionType { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for WebsocketConnectionType { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: WebsocketConnectionType) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupWebsocketDataType")] pub enum WebsocketDataType { #[doc(alias = "SOUP_WEBSOCKET_DATA_TEXT")] Text, #[doc(alias = "SOUP_WEBSOCKET_DATA_BINARY")] Binary, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for WebsocketDataType { type GlibType = ffi::SoupWebsocketDataType; #[inline] fn into_glib(self) -> ffi::SoupWebsocketDataType { match self { Self::Text => ffi::SOUP_WEBSOCKET_DATA_TEXT, Self::Binary => ffi::SOUP_WEBSOCKET_DATA_BINARY, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for WebsocketDataType { #[inline] unsafe fn from_glib(value: ffi::SoupWebsocketDataType) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_WEBSOCKET_DATA_TEXT => Self::Text, ffi::SOUP_WEBSOCKET_DATA_BINARY => Self::Binary, value => Self::__Unknown(value), } } } impl StaticType for WebsocketDataType { #[inline] #[doc(alias = "soup_websocket_data_type_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_websocket_data_type_get_type()) } } } impl glib::HasParamSpec for WebsocketDataType { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for WebsocketDataType { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for WebsocketDataType { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for WebsocketDataType { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: WebsocketDataType) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupWebsocketError")] pub enum WebsocketError { #[doc(alias = "SOUP_WEBSOCKET_ERROR_FAILED")] Failed, #[doc(alias = "SOUP_WEBSOCKET_ERROR_NOT_WEBSOCKET")] NotWebsocket, #[doc(alias = "SOUP_WEBSOCKET_ERROR_BAD_HANDSHAKE")] BadHandshake, #[doc(alias = "SOUP_WEBSOCKET_ERROR_BAD_ORIGIN")] BadOrigin, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for WebsocketError { type GlibType = ffi::SoupWebsocketError; #[inline] fn into_glib(self) -> ffi::SoupWebsocketError { match self { Self::Failed => ffi::SOUP_WEBSOCKET_ERROR_FAILED, Self::NotWebsocket => ffi::SOUP_WEBSOCKET_ERROR_NOT_WEBSOCKET, Self::BadHandshake => ffi::SOUP_WEBSOCKET_ERROR_BAD_HANDSHAKE, Self::BadOrigin => ffi::SOUP_WEBSOCKET_ERROR_BAD_ORIGIN, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for WebsocketError { #[inline] unsafe fn from_glib(value: ffi::SoupWebsocketError) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_WEBSOCKET_ERROR_FAILED => Self::Failed, ffi::SOUP_WEBSOCKET_ERROR_NOT_WEBSOCKET => Self::NotWebsocket, ffi::SOUP_WEBSOCKET_ERROR_BAD_HANDSHAKE => Self::BadHandshake, ffi::SOUP_WEBSOCKET_ERROR_BAD_ORIGIN => Self::BadOrigin, value => Self::__Unknown(value), } } } impl glib::error::ErrorDomain for WebsocketError { #[inline] fn domain() -> glib::Quark { skip_assert_initialized!(); unsafe { from_glib(ffi::soup_websocket_error_quark()) } } #[inline] fn code(self) -> i32 { self.into_glib() } #[inline] #[allow(clippy::match_single_binding)] fn from(code: i32) -> Option { skip_assert_initialized!(); match unsafe { from_glib(code) } { Self::__Unknown(_) => Some(Self::Failed), value => Some(value), } } } impl StaticType for WebsocketError { #[inline] #[doc(alias = "soup_websocket_error_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_websocket_error_get_type()) } } } impl glib::HasParamSpec for WebsocketError { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for WebsocketError { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for WebsocketError { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for WebsocketError { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: WebsocketError) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } #[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] #[non_exhaustive] #[doc(alias = "SoupWebsocketState")] pub enum WebsocketState { #[doc(alias = "SOUP_WEBSOCKET_STATE_OPEN")] Open, #[doc(alias = "SOUP_WEBSOCKET_STATE_CLOSING")] Closing, #[doc(alias = "SOUP_WEBSOCKET_STATE_CLOSED")] Closed, #[doc(hidden)] __Unknown(i32), } #[doc(hidden)] impl IntoGlib for WebsocketState { type GlibType = ffi::SoupWebsocketState; #[inline] fn into_glib(self) -> ffi::SoupWebsocketState { match self { Self::Open => ffi::SOUP_WEBSOCKET_STATE_OPEN, Self::Closing => ffi::SOUP_WEBSOCKET_STATE_CLOSING, Self::Closed => ffi::SOUP_WEBSOCKET_STATE_CLOSED, Self::__Unknown(value) => value, } } } #[doc(hidden)] impl FromGlib for WebsocketState { #[inline] unsafe fn from_glib(value: ffi::SoupWebsocketState) -> Self { skip_assert_initialized!(); match value { ffi::SOUP_WEBSOCKET_STATE_OPEN => Self::Open, ffi::SOUP_WEBSOCKET_STATE_CLOSING => Self::Closing, ffi::SOUP_WEBSOCKET_STATE_CLOSED => Self::Closed, value => Self::__Unknown(value), } } } impl StaticType for WebsocketState { #[inline] #[doc(alias = "soup_websocket_state_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_websocket_state_get_type()) } } } impl glib::HasParamSpec for WebsocketState { type ParamSpec = glib::ParamSpecEnum; type SetValue = Self; type BuilderFn = fn(&str, Self) -> glib::ParamSpecEnumBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder_with_default } } impl glib::value::ValueType for WebsocketState { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for WebsocketState { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_enum(value.to_glib_none().0)) } } } impl ToValue for WebsocketState { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_enum(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: WebsocketState) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } soup3-0.9.0/src/auto/flags.rs000064400000000000000000000234421046102023000141110ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::ffi; use glib::{bitflags::bitflags, prelude::*, translate::*}; bitflags! { #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] #[doc(alias = "SoupCacheability")] pub struct Cacheability: u32 { #[doc(alias = "SOUP_CACHE_CACHEABLE")] const CACHEABLE = ffi::SOUP_CACHE_CACHEABLE as _; #[doc(alias = "SOUP_CACHE_UNCACHEABLE")] const UNCACHEABLE = ffi::SOUP_CACHE_UNCACHEABLE as _; #[doc(alias = "SOUP_CACHE_INVALIDATES")] const INVALIDATES = ffi::SOUP_CACHE_INVALIDATES as _; #[doc(alias = "SOUP_CACHE_VALIDATES")] const VALIDATES = ffi::SOUP_CACHE_VALIDATES as _; } } #[doc(hidden)] impl IntoGlib for Cacheability { type GlibType = ffi::SoupCacheability; #[inline] fn into_glib(self) -> ffi::SoupCacheability { self.bits() } } #[doc(hidden)] impl FromGlib for Cacheability { #[inline] unsafe fn from_glib(value: ffi::SoupCacheability) -> Self { skip_assert_initialized!(); Self::from_bits_truncate(value) } } impl StaticType for Cacheability { #[inline] #[doc(alias = "soup_cacheability_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_cacheability_get_type()) } } } impl glib::HasParamSpec for Cacheability { type ParamSpec = glib::ParamSpecFlags; type SetValue = Self; type BuilderFn = fn(&str) -> glib::ParamSpecFlagsBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder } } impl glib::value::ValueType for Cacheability { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for Cacheability { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_flags(value.to_glib_none().0)) } } } impl ToValue for Cacheability { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_flags(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: Cacheability) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } bitflags! { #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] #[doc(alias = "SoupExpectation")] pub struct Expectation: u32 { #[doc(alias = "SOUP_EXPECTATION_UNRECOGNIZED")] const UNRECOGNIZED = ffi::SOUP_EXPECTATION_UNRECOGNIZED as _; #[doc(alias = "SOUP_EXPECTATION_CONTINUE")] const CONTINUE = ffi::SOUP_EXPECTATION_CONTINUE as _; } } #[doc(hidden)] impl IntoGlib for Expectation { type GlibType = ffi::SoupExpectation; #[inline] fn into_glib(self) -> ffi::SoupExpectation { self.bits() } } #[doc(hidden)] impl FromGlib for Expectation { #[inline] unsafe fn from_glib(value: ffi::SoupExpectation) -> Self { skip_assert_initialized!(); Self::from_bits_truncate(value) } } impl StaticType for Expectation { #[inline] #[doc(alias = "soup_expectation_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_expectation_get_type()) } } } impl glib::HasParamSpec for Expectation { type ParamSpec = glib::ParamSpecFlags; type SetValue = Self; type BuilderFn = fn(&str) -> glib::ParamSpecFlagsBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder } } impl glib::value::ValueType for Expectation { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for Expectation { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_flags(value.to_glib_none().0)) } } } impl ToValue for Expectation { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_flags(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: Expectation) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } bitflags! { #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] #[doc(alias = "SoupMessageFlags")] pub struct MessageFlags: u32 { #[doc(alias = "SOUP_MESSAGE_NO_REDIRECT")] const NO_REDIRECT = ffi::SOUP_MESSAGE_NO_REDIRECT as _; #[doc(alias = "SOUP_MESSAGE_NEW_CONNECTION")] const NEW_CONNECTION = ffi::SOUP_MESSAGE_NEW_CONNECTION as _; #[doc(alias = "SOUP_MESSAGE_IDEMPOTENT")] const IDEMPOTENT = ffi::SOUP_MESSAGE_IDEMPOTENT as _; #[doc(alias = "SOUP_MESSAGE_DO_NOT_USE_AUTH_CACHE")] const DO_NOT_USE_AUTH_CACHE = ffi::SOUP_MESSAGE_DO_NOT_USE_AUTH_CACHE as _; #[doc(alias = "SOUP_MESSAGE_COLLECT_METRICS")] const COLLECT_METRICS = ffi::SOUP_MESSAGE_COLLECT_METRICS as _; } } #[doc(hidden)] impl IntoGlib for MessageFlags { type GlibType = ffi::SoupMessageFlags; #[inline] fn into_glib(self) -> ffi::SoupMessageFlags { self.bits() } } #[doc(hidden)] impl FromGlib for MessageFlags { #[inline] unsafe fn from_glib(value: ffi::SoupMessageFlags) -> Self { skip_assert_initialized!(); Self::from_bits_truncate(value) } } impl StaticType for MessageFlags { #[inline] #[doc(alias = "soup_message_flags_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_message_flags_get_type()) } } } impl glib::HasParamSpec for MessageFlags { type ParamSpec = glib::ParamSpecFlags; type SetValue = Self; type BuilderFn = fn(&str) -> glib::ParamSpecFlagsBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder } } impl glib::value::ValueType for MessageFlags { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for MessageFlags { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_flags(value.to_glib_none().0)) } } } impl ToValue for MessageFlags { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_flags(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: MessageFlags) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } bitflags! { #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] #[doc(alias = "SoupServerListenOptions")] pub struct ServerListenOptions: u32 { #[doc(alias = "SOUP_SERVER_LISTEN_HTTPS")] const HTTPS = ffi::SOUP_SERVER_LISTEN_HTTPS as _; #[doc(alias = "SOUP_SERVER_LISTEN_IPV4_ONLY")] const IPV4_ONLY = ffi::SOUP_SERVER_LISTEN_IPV4_ONLY as _; #[doc(alias = "SOUP_SERVER_LISTEN_IPV6_ONLY")] const IPV6_ONLY = ffi::SOUP_SERVER_LISTEN_IPV6_ONLY as _; } } #[doc(hidden)] impl IntoGlib for ServerListenOptions { type GlibType = ffi::SoupServerListenOptions; #[inline] fn into_glib(self) -> ffi::SoupServerListenOptions { self.bits() } } #[doc(hidden)] impl FromGlib for ServerListenOptions { #[inline] unsafe fn from_glib(value: ffi::SoupServerListenOptions) -> Self { skip_assert_initialized!(); Self::from_bits_truncate(value) } } impl StaticType for ServerListenOptions { #[inline] #[doc(alias = "soup_server_listen_options_get_type")] fn static_type() -> glib::Type { unsafe { from_glib(ffi::soup_server_listen_options_get_type()) } } } impl glib::HasParamSpec for ServerListenOptions { type ParamSpec = glib::ParamSpecFlags; type SetValue = Self; type BuilderFn = fn(&str) -> glib::ParamSpecFlagsBuilder; fn param_spec_builder() -> Self::BuilderFn { Self::ParamSpec::builder } } impl glib::value::ValueType for ServerListenOptions { type Type = Self; } unsafe impl<'a> glib::value::FromValue<'a> for ServerListenOptions { type Checker = glib::value::GenericValueTypeChecker; #[inline] unsafe fn from_value(value: &'a glib::Value) -> Self { skip_assert_initialized!(); unsafe { from_glib(glib::gobject_ffi::g_value_get_flags(value.to_glib_none().0)) } } } impl ToValue for ServerListenOptions { #[inline] fn to_value(&self) -> glib::Value { let mut value = glib::Value::for_value_type::(); unsafe { glib::gobject_ffi::g_value_set_flags(value.to_glib_none_mut().0, self.into_glib()); } value } #[inline] fn value_type(&self) -> glib::Type { Self::static_type() } } impl From for glib::Value { #[inline] fn from(v: ServerListenOptions) -> Self { skip_assert_initialized!(); ToValue::to_value(&v) } } soup3-0.9.0/src/auto/functions.rs000064400000000000000000000312661046102023000150300ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{Cookie, DateFormat, HTTPVersion, Message, MessageHeaders, ffi}; use glib::translate::*; #[doc(alias = "soup_check_version")] pub fn check_version(major: u32, minor: u32, micro: u32) -> bool { assert_initialized_main_thread!(); unsafe { from_glib(ffi::soup_check_version(major, minor, micro)) } } #[doc(alias = "soup_cookies_from_request")] pub fn cookies_from_request(msg: &Message) -> Vec { skip_assert_initialized!(); unsafe { FromGlibPtrContainer::from_glib_full(ffi::soup_cookies_from_request(msg.to_glib_none().0)) } } #[doc(alias = "soup_cookies_from_response")] pub fn cookies_from_response(msg: &Message) -> Vec { skip_assert_initialized!(); unsafe { FromGlibPtrContainer::from_glib_full(ffi::soup_cookies_from_response(msg.to_glib_none().0)) } } #[doc(alias = "soup_date_time_new_from_http_string")] pub fn date_time_new_from_http_string(date_string: &str) -> Option { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_date_time_new_from_http_string( date_string.to_glib_none().0, )) } } #[doc(alias = "soup_date_time_to_string")] pub fn date_time_to_string(date: &glib::DateTime, format: DateFormat) -> Option { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_date_time_to_string( date.to_glib_none().0, format.into_glib(), )) } } //#[doc(alias = "soup_form_decode")] //pub fn form_decode(encoded_form: &str) -> /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 } { // unsafe { TODO: call ffi:soup_form_decode() } //} //#[doc(alias = "soup_form_decode_multipart")] //pub fn form_decode_multipart(multipart: Multipart, file_control_name: Option<&str>) -> (/*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 }, glib::GString, glib::GString, glib::Bytes) { // unsafe { TODO: call ffi:soup_form_decode_multipart() } //} //#[doc(alias = "soup_form_encode")] //pub fn form_encode(first_field: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> Option { // unsafe { TODO: call ffi:soup_form_encode() } //} //#[doc(alias = "soup_form_encode_datalist")] //pub fn form_encode_datalist(form_data_set: /*Ignored*/&mut glib::Data) -> Option { // unsafe { TODO: call ffi:soup_form_encode_datalist() } //} //#[doc(alias = "soup_form_encode_hash")] //pub fn form_encode_hash(form_data_set: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 }) -> Option { // unsafe { TODO: call ffi:soup_form_encode_hash() } //} //#[doc(alias = "soup_form_encode_valist")] //pub fn form_encode_valist(first_field: &str, args: /*Unknown conversion*//*Unimplemented*/Unsupported) -> Option { // unsafe { TODO: call ffi:soup_form_encode_valist() } //} #[doc(alias = "soup_get_major_version")] #[doc(alias = "get_major_version")] pub fn major_version() -> u32 { assert_initialized_main_thread!(); unsafe { ffi::soup_get_major_version() } } #[doc(alias = "soup_get_micro_version")] #[doc(alias = "get_micro_version")] pub fn micro_version() -> u32 { assert_initialized_main_thread!(); unsafe { ffi::soup_get_micro_version() } } #[doc(alias = "soup_get_minor_version")] #[doc(alias = "get_minor_version")] pub fn minor_version() -> u32 { assert_initialized_main_thread!(); unsafe { ffi::soup_get_minor_version() } } #[doc(alias = "soup_header_contains")] pub fn header_contains(header: &str, token: &str) -> bool { assert_initialized_main_thread!(); unsafe { from_glib(ffi::soup_header_contains( header.to_glib_none().0, token.to_glib_none().0, )) } } #[cfg(feature = "v3_8")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_8")))] #[doc(alias = "soup_header_contains_case_sensitive")] pub fn header_contains_case_sensitive(header: &str, token: &str) -> bool { assert_initialized_main_thread!(); unsafe { from_glib(ffi::soup_header_contains_case_sensitive( header.to_glib_none().0, token.to_glib_none().0, )) } } //#[doc(alias = "soup_header_free_list")] //pub fn header_free_list(list: /*Unimplemented*/&[&Basic: Pointer]) { // unsafe { TODO: call ffi:soup_header_free_list() } //} //#[doc(alias = "soup_header_free_param_list")] //pub fn header_free_param_list(param_list: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 }) { // unsafe { TODO: call ffi:soup_header_free_param_list() } //} //#[doc(alias = "soup_header_g_string_append_param")] //pub fn header_g_string_append_param(string: /*Ignored*/&mut glib::String, name: &str, value: Option<&str>) { // unsafe { TODO: call ffi:soup_header_g_string_append_param() } //} //#[doc(alias = "soup_header_g_string_append_param_quoted")] //pub fn header_g_string_append_param_quoted(string: /*Ignored*/&mut glib::String, name: &str, value: &str) { // unsafe { TODO: call ffi:soup_header_g_string_append_param_quoted() } //} #[doc(alias = "soup_header_parse_list")] pub fn header_parse_list(header: &str) -> Vec { assert_initialized_main_thread!(); unsafe { FromGlibPtrContainer::from_glib_full(ffi::soup_header_parse_list(header.to_glib_none().0)) } } //#[doc(alias = "soup_header_parse_param_list")] //pub fn header_parse_param_list(header: &str) -> /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 } { // unsafe { TODO: call ffi:soup_header_parse_param_list() } //} //#[doc(alias = "soup_header_parse_param_list_strict")] //pub fn header_parse_param_list_strict(header: &str) -> /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 } { // unsafe { TODO: call ffi:soup_header_parse_param_list_strict() } //} //#[doc(alias = "soup_header_parse_quality_list")] //pub fn header_parse_quality_list(header: &str, unacceptable: /*Unimplemented*/Vec) -> Vec { // unsafe { TODO: call ffi:soup_header_parse_quality_list() } //} //#[doc(alias = "soup_header_parse_semi_param_list")] //pub fn header_parse_semi_param_list(header: &str) -> /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 } { // unsafe { TODO: call ffi:soup_header_parse_semi_param_list() } //} //#[doc(alias = "soup_header_parse_semi_param_list_strict")] //pub fn header_parse_semi_param_list_strict(header: &str) -> /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 } { // unsafe { TODO: call ffi:soup_header_parse_semi_param_list_strict() } //} #[doc(alias = "soup_headers_parse")] pub fn headers_parse(str: &str, dest: &MessageHeaders) -> bool { assert_initialized_main_thread!(); let len = str.len() as _; unsafe { from_glib(ffi::soup_headers_parse( str.to_glib_none().0, len, dest.to_glib_none().0, )) } } #[doc(alias = "soup_headers_parse_request")] pub fn headers_parse_request( str: &str, req_headers: &MessageHeaders, ) -> (u32, glib::GString, glib::GString, HTTPVersion) { assert_initialized_main_thread!(); let len = str.len() as _; unsafe { let mut req_method = std::ptr::null_mut(); let mut req_path = std::ptr::null_mut(); let mut ver = std::mem::MaybeUninit::uninit(); let ret = ffi::soup_headers_parse_request( str.to_glib_none().0, len, req_headers.to_glib_none().0, &mut req_method, &mut req_path, ver.as_mut_ptr(), ); ( ret, from_glib_full(req_method), from_glib_full(req_path), from_glib(ver.assume_init()), ) } } #[doc(alias = "soup_headers_parse_response")] pub fn headers_parse_response( str: &str, headers: &MessageHeaders, ) -> Option<(HTTPVersion, u32, glib::GString)> { assert_initialized_main_thread!(); let len = str.len() as _; unsafe { let mut ver = std::mem::MaybeUninit::uninit(); let mut status_code = std::mem::MaybeUninit::uninit(); let mut reason_phrase = std::ptr::null_mut(); let ret = from_glib(ffi::soup_headers_parse_response( str.to_glib_none().0, len, headers.to_glib_none().0, ver.as_mut_ptr(), status_code.as_mut_ptr(), &mut reason_phrase, )); if ret { Some(( from_glib(ver.assume_init()), status_code.assume_init(), from_glib_full(reason_phrase), )) } else { None } } } #[doc(alias = "soup_headers_parse_status_line")] pub fn headers_parse_status_line(status_line: &str) -> Option<(HTTPVersion, u32, glib::GString)> { assert_initialized_main_thread!(); unsafe { let mut ver = std::mem::MaybeUninit::uninit(); let mut status_code = std::mem::MaybeUninit::uninit(); let mut reason_phrase = std::ptr::null_mut(); let ret = from_glib(ffi::soup_headers_parse_status_line( status_line.to_glib_none().0, ver.as_mut_ptr(), status_code.as_mut_ptr(), &mut reason_phrase, )); if ret { Some(( from_glib(ver.assume_init()), status_code.assume_init(), from_glib_full(reason_phrase), )) } else { None } } } #[doc(alias = "soup_tld_domain_is_public_suffix")] pub fn tld_domain_is_public_suffix(domain: &str) -> bool { assert_initialized_main_thread!(); unsafe { from_glib(ffi::soup_tld_domain_is_public_suffix( domain.to_glib_none().0, )) } } #[doc(alias = "soup_tld_get_base_domain")] pub fn tld_get_base_domain(hostname: &str) -> Result { assert_initialized_main_thread!(); unsafe { let mut error = std::ptr::null_mut(); let ret = ffi::soup_tld_get_base_domain(hostname.to_glib_none().0, &mut error); if error.is_null() { Ok(from_glib_none(ret)) } else { Err(from_glib_full(error)) } } } //#[doc(alias = "soup_uri_copy")] //pub fn uri_copy(uri: &glib::Uri, first_component: URIComponent, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> Option { // unsafe { TODO: call ffi:soup_uri_copy() } //} #[doc(alias = "soup_uri_decode_data_uri")] pub fn uri_decode_data_uri(uri: &str) -> (glib::Bytes, Option) { assert_initialized_main_thread!(); unsafe { let mut content_type = std::ptr::null_mut(); let ret = from_glib_full(ffi::soup_uri_decode_data_uri( uri.to_glib_none().0, &mut content_type, )); (ret, from_glib_full(content_type)) } } #[doc(alias = "soup_uri_equal")] pub fn uri_equal(uri1: &glib::Uri, uri2: &glib::Uri) -> bool { assert_initialized_main_thread!(); unsafe { from_glib(ffi::soup_uri_equal( uri1.to_glib_none().0, uri2.to_glib_none().0, )) } } //#[doc(alias = "soup_websocket_client_prepare_handshake")] //pub fn websocket_client_prepare_handshake(msg: &Message, origin: Option<&str>, protocols: &[&str], supported_extensions: /*Ignored*/&[&glib::TypeClass]) { // unsafe { TODO: call ffi:soup_websocket_client_prepare_handshake() } //} //#[doc(alias = "soup_websocket_client_verify_handshake")] //pub fn websocket_client_verify_handshake(msg: &Message, supported_extensions: /*Ignored*/&[&glib::TypeClass], accepted_extensions: /*Unimplemented*/Vec) -> Result<(), glib::Error> { // unsafe { TODO: call ffi:soup_websocket_client_verify_handshake() } //} //#[doc(alias = "soup_websocket_server_check_handshake")] //pub fn websocket_server_check_handshake(msg: &ServerMessage, origin: Option<&str>, protocols: &[&str], supported_extensions: /*Ignored*/&[&glib::TypeClass]) -> Result<(), glib::Error> { // unsafe { TODO: call ffi:soup_websocket_server_check_handshake() } //} //#[doc(alias = "soup_websocket_server_process_handshake")] //pub fn websocket_server_process_handshake(msg: &ServerMessage, expected_origin: Option<&str>, protocols: &[&str], supported_extensions: /*Ignored*/&[&glib::TypeClass], accepted_extensions: /*Unimplemented*/Vec) -> bool { // unsafe { TODO: call ffi:soup_websocket_server_process_handshake() } //} soup3-0.9.0/src/auto/hsts_enforcer.rs000064400000000000000000000102771046102023000156630ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{HSTSPolicy, SessionFeature, ffi}; use glib::{ object::ObjectType as _, prelude::*, signal::{SignalHandlerId, connect_raw}, translate::*, }; use std::boxed::Box as Box_; glib::wrapper! { #[doc(alias = "SoupHSTSEnforcer")] pub struct HSTSEnforcer(Object) @implements SessionFeature; match fn { type_ => || ffi::soup_hsts_enforcer_get_type(), } } impl HSTSEnforcer { pub const NONE: Option<&'static HSTSEnforcer> = None; #[doc(alias = "soup_hsts_enforcer_new")] pub fn new() -> HSTSEnforcer { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_hsts_enforcer_new()) } } } impl Default for HSTSEnforcer { fn default() -> Self { Self::new() } } pub trait HSTSEnforcerExt: IsA + 'static { #[doc(alias = "soup_hsts_enforcer_get_domains")] #[doc(alias = "get_domains")] fn domains(&self, session_policies: bool) -> Vec { unsafe { FromGlibPtrContainer::from_glib_full(ffi::soup_hsts_enforcer_get_domains( self.as_ref().to_glib_none().0, session_policies.into_glib(), )) } } #[doc(alias = "soup_hsts_enforcer_get_policies")] #[doc(alias = "get_policies")] fn policies(&self, session_policies: bool) -> Vec { unsafe { FromGlibPtrContainer::from_glib_full(ffi::soup_hsts_enforcer_get_policies( self.as_ref().to_glib_none().0, session_policies.into_glib(), )) } } #[doc(alias = "soup_hsts_enforcer_has_valid_policy")] fn has_valid_policy(&self, domain: &str) -> bool { unsafe { from_glib(ffi::soup_hsts_enforcer_has_valid_policy( self.as_ref().to_glib_none().0, domain.to_glib_none().0, )) } } #[doc(alias = "soup_hsts_enforcer_is_persistent")] fn is_persistent(&self) -> bool { unsafe { from_glib(ffi::soup_hsts_enforcer_is_persistent( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_hsts_enforcer_set_policy")] fn set_policy(&self, policy: &mut HSTSPolicy) { unsafe { ffi::soup_hsts_enforcer_set_policy( self.as_ref().to_glib_none().0, policy.to_glib_none_mut().0, ); } } #[doc(alias = "soup_hsts_enforcer_set_session_policy")] fn set_session_policy(&self, domain: &str, include_subdomains: bool) { unsafe { ffi::soup_hsts_enforcer_set_session_policy( self.as_ref().to_glib_none().0, domain.to_glib_none().0, include_subdomains.into_glib(), ); } } #[doc(alias = "changed")] fn connect_changed( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn changed_trampoline< P: IsA, F: Fn(&P, &HSTSPolicy, &HSTSPolicy) + 'static, >( this: *mut ffi::SoupHSTSEnforcer, old_policy: *mut ffi::SoupHSTSPolicy, new_policy: *mut ffi::SoupHSTSPolicy, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f( HSTSEnforcer::from_glib_borrow(this).unsafe_cast_ref(), &from_glib_borrow(old_policy), &from_glib_borrow(new_policy), ) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"changed".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( changed_trampoline:: as *const (), )), Box_::into_raw(f), ) } } } impl> HSTSEnforcerExt for O {} soup3-0.9.0/src/auto/hsts_enforcer_db.rs000064400000000000000000000046171046102023000163310ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{HSTSEnforcer, SessionFeature, ffi}; use glib::{prelude::*, translate::*}; glib::wrapper! { #[doc(alias = "SoupHSTSEnforcerDB")] pub struct HSTSEnforcerDB(Object) @extends HSTSEnforcer, @implements SessionFeature; match fn { type_ => || ffi::soup_hsts_enforcer_db_get_type(), } } impl HSTSEnforcerDB { #[doc(alias = "soup_hsts_enforcer_db_new")] pub fn new(filename: &str) -> HSTSEnforcerDB { assert_initialized_main_thread!(); unsafe { HSTSEnforcer::from_glib_full(ffi::soup_hsts_enforcer_db_new(filename.to_glib_none().0)) .unsafe_cast() } } // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`HSTSEnforcerDB`] objects. /// /// This method returns an instance of [`HSTSEnforcerDBBuilder`](crate::builders::HSTSEnforcerDBBuilder) which can be used to create [`HSTSEnforcerDB`] objects. pub fn builder() -> HSTSEnforcerDBBuilder { HSTSEnforcerDBBuilder::new() } pub fn filename(&self) -> Option { ObjectExt::property(self, "filename") } } impl Default for HSTSEnforcerDB { fn default() -> Self { glib::object::Object::new::() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`HSTSEnforcerDB`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct HSTSEnforcerDBBuilder { builder: glib::object::ObjectBuilder<'static, HSTSEnforcerDB>, } impl HSTSEnforcerDBBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn filename(self, filename: impl Into) -> Self { Self { builder: self.builder.property("filename", filename.into()), } } // rustdoc-stripper-ignore-next /// Build the [`HSTSEnforcerDB`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> HSTSEnforcerDB { assert_initialized_main_thread!(); self.builder.build() } } soup3-0.9.0/src/auto/hsts_policy.rs000064400000000000000000000070731046102023000153570ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{Message, ffi}; use glib::translate::*; glib::wrapper! { #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct HSTSPolicy(Boxed); match fn { copy => |ptr| ffi::soup_hsts_policy_copy(mut_override(ptr)), free => |ptr| ffi::soup_hsts_policy_free(ptr), type_ => || ffi::soup_hsts_policy_get_type(), } } impl HSTSPolicy { #[doc(alias = "soup_hsts_policy_new")] pub fn new(domain: &str, max_age: libc::c_ulong, include_subdomains: bool) -> HSTSPolicy { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_hsts_policy_new( domain.to_glib_none().0, max_age, include_subdomains.into_glib(), )) } } #[doc(alias = "soup_hsts_policy_new_from_response")] #[doc(alias = "new_from_response")] pub fn from_response(msg: &Message) -> Option { skip_assert_initialized!(); unsafe { from_glib_full(ffi::soup_hsts_policy_new_from_response( msg.to_glib_none().0, )) } } #[doc(alias = "soup_hsts_policy_new_full")] pub fn new_full( domain: &str, max_age: libc::c_ulong, expires: &glib::DateTime, include_subdomains: bool, ) -> HSTSPolicy { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_hsts_policy_new_full( domain.to_glib_none().0, max_age, expires.to_glib_none().0, include_subdomains.into_glib(), )) } } #[doc(alias = "soup_hsts_policy_new_session_policy")] pub fn new_session_policy(domain: &str, include_subdomains: bool) -> HSTSPolicy { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_hsts_policy_new_session_policy( domain.to_glib_none().0, include_subdomains.into_glib(), )) } } #[doc(alias = "soup_hsts_policy_get_domain")] #[doc(alias = "get_domain")] pub fn domain(&mut self) -> Option { unsafe { from_glib_none(ffi::soup_hsts_policy_get_domain(self.to_glib_none_mut().0)) } } #[doc(alias = "soup_hsts_policy_get_expires")] #[doc(alias = "get_expires")] pub fn expires(&mut self) -> Option { unsafe { from_glib_full(ffi::soup_hsts_policy_get_expires(self.to_glib_none_mut().0)) } } #[doc(alias = "soup_hsts_policy_get_max_age")] #[doc(alias = "get_max_age")] pub fn max_age(&mut self) -> libc::c_ulong { unsafe { ffi::soup_hsts_policy_get_max_age(self.to_glib_none_mut().0) } } #[doc(alias = "soup_hsts_policy_includes_subdomains")] pub fn includes_subdomains(&mut self) -> bool { unsafe { from_glib(ffi::soup_hsts_policy_includes_subdomains( self.to_glib_none_mut().0, )) } } #[doc(alias = "soup_hsts_policy_is_expired")] pub fn is_expired(&mut self) -> bool { unsafe { from_glib(ffi::soup_hsts_policy_is_expired(self.to_glib_none_mut().0)) } } #[doc(alias = "soup_hsts_policy_is_session_policy")] pub fn is_session_policy(&mut self) -> bool { unsafe { from_glib(ffi::soup_hsts_policy_is_session_policy( self.to_glib_none_mut().0, )) } } } soup3-0.9.0/src/auto/logger.rs000064400000000000000000000172261046102023000142770ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{LoggerLogLevel, Message, SessionFeature, ffi}; use glib::{ prelude::*, signal::{SignalHandlerId, connect_raw}, translate::*, }; use std::boxed::Box as Box_; glib::wrapper! { #[doc(alias = "SoupLogger")] pub struct Logger(Object) @implements SessionFeature; match fn { type_ => || ffi::soup_logger_get_type(), } } impl Logger { #[doc(alias = "soup_logger_new")] pub fn new(level: LoggerLogLevel) -> Logger { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_logger_new(level.into_glib())) } } // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`Logger`] objects. /// /// This method returns an instance of [`LoggerBuilder`](crate::builders::LoggerBuilder) which can be used to create [`Logger`] objects. pub fn builder() -> LoggerBuilder { LoggerBuilder::new() } #[doc(alias = "soup_logger_get_max_body_size")] #[doc(alias = "get_max_body_size")] #[doc(alias = "max-body-size")] pub fn max_body_size(&self) -> i32 { unsafe { ffi::soup_logger_get_max_body_size(self.to_glib_none().0) } } #[doc(alias = "soup_logger_set_max_body_size")] #[doc(alias = "max-body-size")] pub fn set_max_body_size(&self, max_body_size: i32) { unsafe { ffi::soup_logger_set_max_body_size(self.to_glib_none().0, max_body_size); } } #[doc(alias = "soup_logger_set_request_filter")] pub fn set_request_filter LoggerLogLevel + 'static>( &self, request_filter: P, ) { let request_filter_data: Box_

= Box_::new(request_filter); unsafe extern "C" fn request_filter_func< P: Fn(&Logger, &Message) -> LoggerLogLevel + 'static, >( logger: *mut ffi::SoupLogger, msg: *mut ffi::SoupMessage, user_data: glib::ffi::gpointer, ) -> ffi::SoupLoggerLogLevel { unsafe { let logger = from_glib_borrow(logger); let msg = from_glib_borrow(msg); let callback = &*(user_data as *mut P); (*callback)(&logger, &msg).into_glib() } } let request_filter = Some(request_filter_func::

as _); unsafe extern "C" fn destroy_func LoggerLogLevel + 'static>( data: glib::ffi::gpointer, ) { unsafe { let _callback = Box_::from_raw(data as *mut P); } } let destroy_call3 = Some(destroy_func::

as _); let super_callback0: Box_

= request_filter_data; unsafe { ffi::soup_logger_set_request_filter( self.to_glib_none().0, request_filter, Box_::into_raw(super_callback0) as *mut _, destroy_call3, ); } } #[doc(alias = "soup_logger_set_response_filter")] pub fn set_response_filter LoggerLogLevel + 'static>( &self, response_filter: P, ) { let response_filter_data: Box_

= Box_::new(response_filter); unsafe extern "C" fn response_filter_func< P: Fn(&Logger, &Message) -> LoggerLogLevel + 'static, >( logger: *mut ffi::SoupLogger, msg: *mut ffi::SoupMessage, user_data: glib::ffi::gpointer, ) -> ffi::SoupLoggerLogLevel { unsafe { let logger = from_glib_borrow(logger); let msg = from_glib_borrow(msg); let callback = &*(user_data as *mut P); (*callback)(&logger, &msg).into_glib() } } let response_filter = Some(response_filter_func::

as _); unsafe extern "C" fn destroy_func LoggerLogLevel + 'static>( data: glib::ffi::gpointer, ) { unsafe { let _callback = Box_::from_raw(data as *mut P); } } let destroy_call3 = Some(destroy_func::

as _); let super_callback0: Box_

= response_filter_data; unsafe { ffi::soup_logger_set_response_filter( self.to_glib_none().0, response_filter, Box_::into_raw(super_callback0) as *mut _, destroy_call3, ); } } pub fn level(&self) -> LoggerLogLevel { ObjectExt::property(self, "level") } pub fn set_level(&self, level: LoggerLogLevel) { ObjectExt::set_property(self, "level", level) } #[doc(alias = "level")] pub fn connect_level_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_level_trampoline( this: *mut ffi::SoupLogger, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::level".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_level_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "max-body-size")] pub fn connect_max_body_size_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_max_body_size_trampoline( this: *mut ffi::SoupLogger, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::max-body-size".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_max_body_size_trampoline:: as *const (), )), Box_::into_raw(f), ) } } } impl Default for Logger { fn default() -> Self { glib::object::Object::new::() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`Logger`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct LoggerBuilder { builder: glib::object::ObjectBuilder<'static, Logger>, } impl LoggerBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn level(self, level: LoggerLogLevel) -> Self { Self { builder: self.builder.property("level", level), } } pub fn max_body_size(self, max_body_size: i32) -> Self { Self { builder: self.builder.property("max-body-size", max_body_size), } } // rustdoc-stripper-ignore-next /// Build the [`Logger`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> Logger { assert_initialized_main_thread!(); self.builder.build() } } soup3-0.9.0/src/auto/message.rs000064400000000000000000001413321046102023000144400ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{ Auth, HTTPVersion, MessageFlags, MessageHeaders, MessageMetrics, MessagePriority, Multipart, Status, ffi, }; use glib::{ object::ObjectType as _, prelude::*, signal::{SignalHandlerId, connect_raw}, translate::*, }; use std::boxed::Box as Box_; glib::wrapper! { #[doc(alias = "SoupMessage")] pub struct Message(Object); match fn { type_ => || ffi::soup_message_get_type(), } } impl Message { #[doc(alias = "soup_message_new")] pub fn new(method: &str, uri_string: &str) -> Result { assert_initialized_main_thread!(); unsafe { Option::<_>::from_glib_full(ffi::soup_message_new( method.to_glib_none().0, uri_string.to_glib_none().0, )) .ok_or_else(|| glib::bool_error!("Invalid URL")) } } #[doc(alias = "soup_message_new_from_encoded_form")] #[doc(alias = "new_from_encoded_form")] pub fn from_encoded_form( method: &str, uri_string: &str, encoded_form: glib::GString, ) -> Result { assert_initialized_main_thread!(); unsafe { Option::<_>::from_glib_full(ffi::soup_message_new_from_encoded_form( method.to_glib_none().0, uri_string.to_glib_none().0, encoded_form.into_glib_ptr(), )) .ok_or_else(|| glib::bool_error!("Invalid URL")) } } #[doc(alias = "soup_message_new_from_multipart")] #[doc(alias = "new_from_multipart")] pub fn from_multipart( uri_string: &str, multipart: &mut Multipart, ) -> Result { assert_initialized_main_thread!(); unsafe { Option::<_>::from_glib_full(ffi::soup_message_new_from_multipart( uri_string.to_glib_none().0, multipart.to_glib_none_mut().0, )) .ok_or_else(|| glib::bool_error!("Invalid URL")) } } #[doc(alias = "soup_message_new_from_uri")] #[doc(alias = "new_from_uri")] pub fn from_uri(method: &str, uri: &glib::Uri) -> Message { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_message_new_from_uri( method.to_glib_none().0, uri.to_glib_none().0, )) } } #[doc(alias = "soup_message_new_options_ping")] pub fn new_options_ping(base_uri: &glib::Uri) -> Message { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_message_new_options_ping( base_uri.to_glib_none().0, )) } } // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`Message`] objects. /// /// This method returns an instance of [`MessageBuilder`](crate::builders::MessageBuilder) which can be used to create [`Message`] objects. pub fn builder() -> MessageBuilder { MessageBuilder::new() } #[doc(alias = "soup_message_add_flags")] pub fn add_flags(&self, flags: MessageFlags) { unsafe { ffi::soup_message_add_flags(self.to_glib_none().0, flags.into_glib()); } } //#[doc(alias = "soup_message_add_header_handler")] //pub fn add_header_handler(&self, signal: &str, header: &str, callback: P, user_data: /*Unimplemented*/Option) -> u32 { // unsafe { TODO: call ffi:soup_message_add_header_handler() } //} //#[doc(alias = "soup_message_add_status_code_handler")] //pub fn add_status_code_handler(&self, signal: &str, status_code: u32, callback: P, user_data: /*Unimplemented*/Option) -> u32 { // unsafe { TODO: call ffi:soup_message_add_status_code_handler() } //} #[doc(alias = "soup_message_disable_feature")] pub fn disable_feature(&self, feature_type: glib::types::Type) { unsafe { ffi::soup_message_disable_feature(self.to_glib_none().0, feature_type.into_glib()); } } #[doc(alias = "soup_message_get_connection_id")] #[doc(alias = "get_connection_id")] pub fn connection_id(&self) -> u64 { unsafe { ffi::soup_message_get_connection_id(self.to_glib_none().0) } } #[doc(alias = "soup_message_get_first_party")] #[doc(alias = "get_first_party")] #[doc(alias = "first-party")] pub fn first_party(&self) -> Option { unsafe { from_glib_none(ffi::soup_message_get_first_party(self.to_glib_none().0)) } } #[doc(alias = "soup_message_get_flags")] #[doc(alias = "get_flags")] pub fn flags(&self) -> MessageFlags { unsafe { from_glib(ffi::soup_message_get_flags(self.to_glib_none().0)) } } #[cfg(feature = "v3_4")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_4")))] #[doc(alias = "soup_message_get_force_http1")] #[doc(alias = "get_force_http1")] pub fn is_force_http1(&self) -> bool { unsafe { from_glib(ffi::soup_message_get_force_http1(self.to_glib_none().0)) } } #[doc(alias = "soup_message_get_http_version")] #[doc(alias = "get_http_version")] #[doc(alias = "http-version")] pub fn http_version(&self) -> HTTPVersion { unsafe { from_glib(ffi::soup_message_get_http_version(self.to_glib_none().0)) } } #[doc(alias = "soup_message_get_is_options_ping")] #[doc(alias = "get_is_options_ping")] #[doc(alias = "is-options-ping")] pub fn is_options_ping(&self) -> bool { unsafe { from_glib(ffi::soup_message_get_is_options_ping(self.to_glib_none().0)) } } #[doc(alias = "soup_message_get_is_top_level_navigation")] #[doc(alias = "get_is_top_level_navigation")] #[doc(alias = "is-top-level-navigation")] pub fn is_top_level_navigation(&self) -> bool { unsafe { from_glib(ffi::soup_message_get_is_top_level_navigation( self.to_glib_none().0, )) } } #[doc(alias = "soup_message_get_method")] #[doc(alias = "get_method")] pub fn method(&self) -> Option { unsafe { from_glib_none(ffi::soup_message_get_method(self.to_glib_none().0)) } } #[doc(alias = "soup_message_get_metrics")] #[doc(alias = "get_metrics")] pub fn metrics(&self) -> Option { unsafe { from_glib_none(ffi::soup_message_get_metrics(self.to_glib_none().0)) } } #[doc(alias = "soup_message_get_priority")] #[doc(alias = "get_priority")] pub fn priority(&self) -> MessagePriority { unsafe { from_glib(ffi::soup_message_get_priority(self.to_glib_none().0)) } } #[doc(alias = "soup_message_get_reason_phrase")] #[doc(alias = "get_reason_phrase")] #[doc(alias = "reason-phrase")] pub fn reason_phrase(&self) -> Option { unsafe { from_glib_none(ffi::soup_message_get_reason_phrase(self.to_glib_none().0)) } } #[doc(alias = "soup_message_get_remote_address")] #[doc(alias = "get_remote_address")] #[doc(alias = "remote-address")] pub fn remote_address(&self) -> Option { unsafe { from_glib_none(ffi::soup_message_get_remote_address(self.to_glib_none().0)) } } #[doc(alias = "soup_message_get_request_headers")] #[doc(alias = "get_request_headers")] #[doc(alias = "request-headers")] pub fn request_headers(&self) -> Option { unsafe { from_glib_none(ffi::soup_message_get_request_headers(self.to_glib_none().0)) } } #[doc(alias = "soup_message_get_response_headers")] #[doc(alias = "get_response_headers")] #[doc(alias = "response-headers")] pub fn response_headers(&self) -> Option { unsafe { from_glib_none(ffi::soup_message_get_response_headers( self.to_glib_none().0, )) } } #[doc(alias = "soup_message_get_status")] #[doc(alias = "get_status")] pub fn status(&self) -> Status { unsafe { from_glib(ffi::soup_message_get_status(self.to_glib_none().0)) } } #[doc(alias = "soup_message_get_tls_ciphersuite_name")] #[doc(alias = "get_tls_ciphersuite_name")] #[doc(alias = "tls-ciphersuite-name")] pub fn tls_ciphersuite_name(&self) -> Option { unsafe { from_glib_none(ffi::soup_message_get_tls_ciphersuite_name( self.to_glib_none().0, )) } } #[doc(alias = "soup_message_get_tls_peer_certificate")] #[doc(alias = "get_tls_peer_certificate")] #[doc(alias = "tls-peer-certificate")] pub fn tls_peer_certificate(&self) -> Option { unsafe { from_glib_none(ffi::soup_message_get_tls_peer_certificate( self.to_glib_none().0, )) } } #[doc(alias = "soup_message_get_tls_peer_certificate_errors")] #[doc(alias = "get_tls_peer_certificate_errors")] #[doc(alias = "tls-peer-certificate-errors")] pub fn tls_peer_certificate_errors(&self) -> gio::TlsCertificateFlags { unsafe { from_glib(ffi::soup_message_get_tls_peer_certificate_errors( self.to_glib_none().0, )) } } #[doc(alias = "soup_message_get_tls_protocol_version")] #[doc(alias = "get_tls_protocol_version")] #[doc(alias = "tls-protocol-version")] pub fn tls_protocol_version(&self) -> gio::TlsProtocolVersion { unsafe { from_glib(ffi::soup_message_get_tls_protocol_version( self.to_glib_none().0, )) } } #[doc(alias = "soup_message_get_uri")] #[doc(alias = "get_uri")] #[doc(alias = "method")] pub fn uri(&self) -> Option { unsafe { from_glib_none(ffi::soup_message_get_uri(self.to_glib_none().0)) } } #[doc(alias = "soup_message_is_feature_disabled")] pub fn is_feature_disabled(&self, feature_type: glib::types::Type) -> bool { unsafe { from_glib(ffi::soup_message_is_feature_disabled( self.to_glib_none().0, feature_type.into_glib(), )) } } #[doc(alias = "soup_message_is_keepalive")] pub fn is_keepalive(&self) -> bool { unsafe { from_glib(ffi::soup_message_is_keepalive(self.to_glib_none().0)) } } #[doc(alias = "soup_message_query_flags")] pub fn query_flags(&self, flags: MessageFlags) -> bool { unsafe { from_glib(ffi::soup_message_query_flags( self.to_glib_none().0, flags.into_glib(), )) } } #[doc(alias = "soup_message_remove_flags")] pub fn remove_flags(&self, flags: MessageFlags) { unsafe { ffi::soup_message_remove_flags(self.to_glib_none().0, flags.into_glib()); } } #[doc(alias = "soup_message_set_first_party")] #[doc(alias = "first-party")] pub fn set_first_party(&self, first_party: &glib::Uri) { unsafe { ffi::soup_message_set_first_party(self.to_glib_none().0, first_party.to_glib_none().0); } } #[doc(alias = "soup_message_set_flags")] #[doc(alias = "flags")] pub fn set_flags(&self, flags: MessageFlags) { unsafe { ffi::soup_message_set_flags(self.to_glib_none().0, flags.into_glib()); } } #[cfg(feature = "v3_4")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_4")))] #[doc(alias = "soup_message_set_force_http1")] pub fn set_force_http1(&self, value: bool) { unsafe { ffi::soup_message_set_force_http1(self.to_glib_none().0, value.into_glib()); } } #[doc(alias = "soup_message_set_is_options_ping")] #[doc(alias = "is-options-ping")] pub fn set_is_options_ping(&self, is_options_ping: bool) { unsafe { ffi::soup_message_set_is_options_ping( self.to_glib_none().0, is_options_ping.into_glib(), ); } } #[doc(alias = "soup_message_set_is_top_level_navigation")] #[doc(alias = "is-top-level-navigation")] pub fn set_is_top_level_navigation(&self, is_top_level_navigation: bool) { unsafe { ffi::soup_message_set_is_top_level_navigation( self.to_glib_none().0, is_top_level_navigation.into_glib(), ); } } #[doc(alias = "soup_message_set_method")] #[doc(alias = "method")] pub fn set_method(&self, method: &str) { unsafe { ffi::soup_message_set_method(self.to_glib_none().0, method.to_glib_none().0); } } #[doc(alias = "soup_message_set_priority")] #[doc(alias = "priority")] pub fn set_priority(&self, priority: MessagePriority) { unsafe { ffi::soup_message_set_priority(self.to_glib_none().0, priority.into_glib()); } } #[doc(alias = "soup_message_set_request_body")] pub fn set_request_body( &self, content_type: Option<&str>, stream: Option<&impl IsA>, content_length: isize, ) { unsafe { ffi::soup_message_set_request_body( self.to_glib_none().0, content_type.to_glib_none().0, stream.map(|p| p.as_ref()).to_glib_none().0, content_length, ); } } #[doc(alias = "soup_message_set_request_body_from_bytes")] pub fn set_request_body_from_bytes( &self, content_type: Option<&str>, bytes: Option<&glib::Bytes>, ) { unsafe { ffi::soup_message_set_request_body_from_bytes( self.to_glib_none().0, content_type.to_glib_none().0, bytes.to_glib_none().0, ); } } #[doc(alias = "soup_message_set_tls_client_certificate")] pub fn set_tls_client_certificate(&self, certificate: Option<&impl IsA>) { unsafe { ffi::soup_message_set_tls_client_certificate( self.to_glib_none().0, certificate.map(|p| p.as_ref()).to_glib_none().0, ); } } #[doc(alias = "soup_message_set_uri")] #[doc(alias = "method")] pub fn set_uri(&self, uri: &glib::Uri) { unsafe { ffi::soup_message_set_uri(self.to_glib_none().0, uri.to_glib_none().0); } } #[doc(alias = "soup_message_tls_client_certificate_password_request_complete")] pub fn tls_client_certificate_password_request_complete(&self) { unsafe { ffi::soup_message_tls_client_certificate_password_request_complete( self.to_glib_none().0, ); } } #[doc(alias = "site-for-cookies")] pub fn site_for_cookies(&self) -> Option { ObjectExt::property(self, "site-for-cookies") } #[doc(alias = "site-for-cookies")] pub fn set_site_for_cookies(&self, site_for_cookies: Option<&glib::Uri>) { ObjectExt::set_property(self, "site-for-cookies", site_for_cookies) } #[doc(alias = "status-code")] pub fn status_code(&self) -> u32 { ObjectExt::property(self, "status-code") } #[doc(alias = "accept-certificate")] pub fn connect_accept_certificate< F: Fn(&Self, &gio::TlsCertificate, gio::TlsCertificateFlags) -> bool + 'static, >( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn accept_certificate_trampoline< F: Fn(&Message, &gio::TlsCertificate, gio::TlsCertificateFlags) -> bool + 'static, >( this: *mut ffi::SoupMessage, tls_peer_certificate: *mut gio::ffi::GTlsCertificate, tls_peer_errors: gio::ffi::GTlsCertificateFlags, f: glib::ffi::gpointer, ) -> glib::ffi::gboolean { unsafe { let f: &F = &*(f as *const F); f( &from_glib_borrow(this), &from_glib_borrow(tls_peer_certificate), from_glib(tls_peer_errors), ) .into_glib() } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"accept-certificate".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( accept_certificate_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "authenticate")] pub fn connect_authenticate bool + 'static>( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn authenticate_trampoline< F: Fn(&Message, &Auth, bool) -> bool + 'static, >( this: *mut ffi::SoupMessage, auth: *mut ffi::SoupAuth, retrying: glib::ffi::gboolean, f: glib::ffi::gpointer, ) -> glib::ffi::gboolean { unsafe { let f: &F = &*(f as *const F); f( &from_glib_borrow(this), &from_glib_borrow(auth), from_glib(retrying), ) .into_glib() } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"authenticate".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( authenticate_trampoline:: as *const (), )), Box_::into_raw(f), ) } } //#[doc(alias = "content-sniffed")] //pub fn connect_content_sniffed(&self, f: F) -> SignalHandlerId { // Empty ctype params: *.HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 } //} #[doc(alias = "finished")] pub fn connect_finished(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn finished_trampoline( this: *mut ffi::SoupMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"finished".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( finished_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "got-body")] pub fn connect_got_body(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn got_body_trampoline( this: *mut ffi::SoupMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"got-body".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( got_body_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[cfg(feature = "v3_4")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_4")))] #[doc(alias = "got-body-data")] pub fn connect_got_body_data(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn got_body_data_trampoline( this: *mut ffi::SoupMessage, chunk_size: std::ffi::c_uint, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this), chunk_size) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"got-body-data".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( got_body_data_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "got-headers")] pub fn connect_got_headers(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn got_headers_trampoline( this: *mut ffi::SoupMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"got-headers".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( got_headers_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "got-informational")] pub fn connect_got_informational(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn got_informational_trampoline( this: *mut ffi::SoupMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"got-informational".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( got_informational_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "hsts-enforced")] pub fn connect_hsts_enforced(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn hsts_enforced_trampoline( this: *mut ffi::SoupMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"hsts-enforced".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( hsts_enforced_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "network-event")] pub fn connect_network_event( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn network_event_trampoline< F: Fn(&Message, gio::SocketClientEvent, &gio::IOStream) + 'static, >( this: *mut ffi::SoupMessage, event: gio::ffi::GSocketClientEvent, connection: *mut gio::ffi::GIOStream, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f( &from_glib_borrow(this), from_glib(event), &from_glib_borrow(connection), ) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"network-event".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( network_event_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "request-certificate")] pub fn connect_request_certificate< F: Fn(&Self, &gio::TlsClientConnection) -> bool + 'static, >( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn request_certificate_trampoline< F: Fn(&Message, &gio::TlsClientConnection) -> bool + 'static, >( this: *mut ffi::SoupMessage, tls_connection: *mut gio::ffi::GTlsClientConnection, f: glib::ffi::gpointer, ) -> glib::ffi::gboolean { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this), &from_glib_borrow(tls_connection)).into_glib() } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"request-certificate".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( request_certificate_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "request-certificate-password")] pub fn connect_request_certificate_password< F: Fn(&Self, &gio::TlsPassword) -> bool + 'static, >( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn request_certificate_password_trampoline< F: Fn(&Message, &gio::TlsPassword) -> bool + 'static, >( this: *mut ffi::SoupMessage, tls_password: *mut gio::ffi::GTlsPassword, f: glib::ffi::gpointer, ) -> glib::ffi::gboolean { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this), &from_glib_borrow(tls_password)).into_glib() } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"request-certificate-password".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( request_certificate_password_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "restarted")] pub fn connect_restarted(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn restarted_trampoline( this: *mut ffi::SoupMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"restarted".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( restarted_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "starting")] pub fn connect_starting(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn starting_trampoline( this: *mut ffi::SoupMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"starting".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( starting_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "wrote-body")] pub fn connect_wrote_body(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn wrote_body_trampoline( this: *mut ffi::SoupMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"wrote-body".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( wrote_body_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "wrote-body-data")] pub fn connect_wrote_body_data(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn wrote_body_data_trampoline( this: *mut ffi::SoupMessage, chunk_size: std::ffi::c_uint, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this), chunk_size) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"wrote-body-data".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( wrote_body_data_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "wrote-headers")] pub fn connect_wrote_headers(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn wrote_headers_trampoline( this: *mut ffi::SoupMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"wrote-headers".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( wrote_headers_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "first-party")] pub fn connect_first_party_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_first_party_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::first-party".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_first_party_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "flags")] pub fn connect_flags_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_flags_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::flags".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_flags_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "http-version")] pub fn connect_http_version_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_http_version_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::http-version".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_http_version_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "is-options-ping")] pub fn connect_is_options_ping_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_is_options_ping_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::is-options-ping".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_is_options_ping_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "is-top-level-navigation")] pub fn connect_is_top_level_navigation_notify( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn notify_is_top_level_navigation_trampoline< F: Fn(&Message) + 'static, >( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::is-top-level-navigation".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_is_top_level_navigation_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "method")] pub fn connect_method_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_method_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::method".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_method_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "priority")] pub fn connect_priority_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_priority_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::priority".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_priority_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "reason-phrase")] pub fn connect_reason_phrase_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_reason_phrase_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::reason-phrase".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_reason_phrase_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "remote-address")] pub fn connect_remote_address_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_remote_address_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::remote-address".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_remote_address_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "request-headers")] pub fn connect_request_headers_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_request_headers_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::request-headers".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_request_headers_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "response-headers")] pub fn connect_response_headers_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_response_headers_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::response-headers".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_response_headers_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "site-for-cookies")] pub fn connect_site_for_cookies_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_site_for_cookies_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::site-for-cookies".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_site_for_cookies_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "status-code")] pub fn connect_status_code_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_status_code_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::status-code".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_status_code_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "tls-ciphersuite-name")] pub fn connect_tls_ciphersuite_name_notify( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn notify_tls_ciphersuite_name_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::tls-ciphersuite-name".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_tls_ciphersuite_name_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "tls-peer-certificate")] pub fn connect_tls_peer_certificate_notify( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn notify_tls_peer_certificate_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::tls-peer-certificate".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_tls_peer_certificate_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "tls-peer-certificate-errors")] pub fn connect_tls_peer_certificate_errors_notify( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn notify_tls_peer_certificate_errors_trampoline< F: Fn(&Message) + 'static, >( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::tls-peer-certificate-errors".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_tls_peer_certificate_errors_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "tls-protocol-version")] pub fn connect_tls_protocol_version_notify( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn notify_tls_protocol_version_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::tls-protocol-version".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_tls_protocol_version_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "uri")] pub fn connect_uri_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_uri_trampoline( this: *mut ffi::SoupMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::uri".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_uri_trampoline:: as *const (), )), Box_::into_raw(f), ) } } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`Message`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct MessageBuilder { builder: glib::object::ObjectBuilder<'static, Message>, } impl MessageBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn first_party(self, first_party: &glib::Uri) -> Self { Self { builder: self.builder.property("first-party", first_party.clone()), } } pub fn flags(self, flags: MessageFlags) -> Self { Self { builder: self.builder.property("flags", flags), } } pub fn is_options_ping(self, is_options_ping: bool) -> Self { Self { builder: self.builder.property("is-options-ping", is_options_ping), } } pub fn is_top_level_navigation(self, is_top_level_navigation: bool) -> Self { Self { builder: self .builder .property("is-top-level-navigation", is_top_level_navigation), } } pub fn method(self, method: impl Into) -> Self { Self { builder: self.builder.property("method", method.into()), } } pub fn priority(self, priority: MessagePriority) -> Self { Self { builder: self.builder.property("priority", priority), } } pub fn site_for_cookies(self, site_for_cookies: &glib::Uri) -> Self { Self { builder: self .builder .property("site-for-cookies", site_for_cookies.clone()), } } pub fn uri(self, uri: &glib::Uri) -> Self { Self { builder: self.builder.property("uri", uri.clone()), } } // rustdoc-stripper-ignore-next /// Build the [`Message`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> Message { assert_initialized_main_thread!(); self.builder.build() } } soup3-0.9.0/src/auto/message_body.rs000064400000000000000000000060661046102023000154610ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::ffi; use glib::translate::*; glib::wrapper! { #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct MessageBody(Shared); match fn { ref => |ptr| ffi::soup_message_body_ref(ptr), unref => |ptr| ffi::soup_message_body_unref(ptr), type_ => || ffi::soup_message_body_get_type(), } } impl MessageBody { #[doc(alias = "soup_message_body_new")] pub fn new() -> MessageBody { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_message_body_new()) } } #[doc(alias = "soup_message_body_append_bytes")] pub fn append_bytes(&self, buffer: &glib::Bytes) { unsafe { ffi::soup_message_body_append_bytes(self.to_glib_none().0, buffer.to_glib_none().0); } } #[doc(alias = "soup_message_body_append_take")] pub fn append_take(&self, data: &[u8]) { let length = data.len() as _; unsafe { ffi::soup_message_body_append_take(self.to_glib_none().0, data.to_glib_full(), length); } } #[doc(alias = "soup_message_body_complete")] pub fn complete(&self) { unsafe { ffi::soup_message_body_complete(self.to_glib_none().0); } } #[doc(alias = "soup_message_body_flatten")] pub fn flatten(&self) -> Option { unsafe { from_glib_full(ffi::soup_message_body_flatten(self.to_glib_none().0)) } } #[doc(alias = "soup_message_body_get_accumulate")] #[doc(alias = "get_accumulate")] pub fn is_accumulate(&self) -> bool { unsafe { from_glib(ffi::soup_message_body_get_accumulate(self.to_glib_none().0)) } } #[doc(alias = "soup_message_body_get_chunk")] #[doc(alias = "get_chunk")] pub fn chunk(&self, offset: i64) -> Option { unsafe { from_glib_full(ffi::soup_message_body_get_chunk( self.to_glib_none().0, offset, )) } } #[doc(alias = "soup_message_body_got_chunk")] pub fn got_chunk(&self, chunk: &glib::Bytes) { unsafe { ffi::soup_message_body_got_chunk(self.to_glib_none().0, chunk.to_glib_none().0); } } #[doc(alias = "soup_message_body_set_accumulate")] pub fn set_accumulate(&self, accumulate: bool) { unsafe { ffi::soup_message_body_set_accumulate(self.to_glib_none().0, accumulate.into_glib()); } } #[doc(alias = "soup_message_body_truncate")] pub fn truncate(&self) { unsafe { ffi::soup_message_body_truncate(self.to_glib_none().0); } } #[doc(alias = "soup_message_body_wrote_chunk")] pub fn wrote_chunk(&self, chunk: &glib::Bytes) { unsafe { ffi::soup_message_body_wrote_chunk(self.to_glib_none().0, chunk.to_glib_none().0); } } } impl Default for MessageBody { fn default() -> Self { Self::new() } } soup3-0.9.0/src/auto/message_headers.rs000064400000000000000000000205001046102023000161240ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{Encoding, Expectation, MessageHeadersType, ffi}; use glib::translate::*; glib::wrapper! { #[derive(PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct MessageHeaders(Shared); match fn { ref => |ptr| ffi::soup_message_headers_ref(ptr), unref => |ptr| ffi::soup_message_headers_unref(ptr), type_ => || ffi::soup_message_headers_get_type(), } } impl MessageHeaders { #[doc(alias = "soup_message_headers_new")] pub fn new(type_: MessageHeadersType) -> MessageHeaders { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_message_headers_new(type_.into_glib())) } } #[doc(alias = "soup_message_headers_append")] pub fn append(&self, name: &str, value: &str) { unsafe { ffi::soup_message_headers_append( self.to_glib_none().0, name.to_glib_none().0, value.to_glib_none().0, ); } } #[doc(alias = "soup_message_headers_clean_connection_headers")] pub fn clean_connection_headers(&self) { unsafe { ffi::soup_message_headers_clean_connection_headers(self.to_glib_none().0); } } #[doc(alias = "soup_message_headers_clear")] pub fn clear(&self) { unsafe { ffi::soup_message_headers_clear(self.to_glib_none().0); } } #[doc(alias = "soup_message_headers_foreach")] pub fn foreach(&self, func: P) { let mut func_data: P = func; unsafe extern "C" fn func_func( name: *const std::ffi::c_char, value: *const std::ffi::c_char, user_data: glib::ffi::gpointer, ) { unsafe { let name: Borrowed = from_glib_borrow(name); let value: Borrowed = from_glib_borrow(value); let callback = user_data as *mut P; (*callback)(name.as_str(), value.as_str()) } } let func = Some(func_func::

as _); let super_callback0: &mut P = &mut func_data; unsafe { ffi::soup_message_headers_foreach( self.to_glib_none().0, func, super_callback0 as *mut _ as *mut _, ); } } //#[doc(alias = "soup_message_headers_free_ranges")] //pub fn free_ranges(&self, ranges: /*Ignored*/&mut Range) { // unsafe { TODO: call ffi:soup_message_headers_free_ranges() } //} #[doc(alias = "soup_message_headers_get_content_length")] #[doc(alias = "get_content_length")] pub fn content_length(&self) -> i64 { unsafe { ffi::soup_message_headers_get_content_length(self.to_glib_none().0) } } #[doc(alias = "soup_message_headers_get_content_range")] #[doc(alias = "get_content_range")] pub fn content_range(&self) -> Option<(i64, i64, i64)> { unsafe { let mut start = std::mem::MaybeUninit::uninit(); let mut end = std::mem::MaybeUninit::uninit(); let mut total_length = std::mem::MaybeUninit::uninit(); let ret = from_glib(ffi::soup_message_headers_get_content_range( self.to_glib_none().0, start.as_mut_ptr(), end.as_mut_ptr(), total_length.as_mut_ptr(), )); if ret { Some(( start.assume_init(), end.assume_init(), total_length.assume_init(), )) } else { None } } } #[doc(alias = "soup_message_headers_get_encoding")] #[doc(alias = "get_encoding")] pub fn encoding(&self) -> Encoding { unsafe { from_glib(ffi::soup_message_headers_get_encoding( self.to_glib_none().0, )) } } #[doc(alias = "soup_message_headers_get_expectations")] #[doc(alias = "get_expectations")] pub fn expectations(&self) -> Expectation { unsafe { from_glib(ffi::soup_message_headers_get_expectations( self.to_glib_none().0, )) } } #[doc(alias = "soup_message_headers_get_headers_type")] #[doc(alias = "get_headers_type")] pub fn headers_type(&self) -> MessageHeadersType { unsafe { from_glib(ffi::soup_message_headers_get_headers_type( self.to_glib_none().0, )) } } #[doc(alias = "soup_message_headers_get_list")] #[doc(alias = "get_list")] pub fn list(&self, name: &str) -> Option { unsafe { from_glib_none(ffi::soup_message_headers_get_list( self.to_glib_none().0, name.to_glib_none().0, )) } } #[doc(alias = "soup_message_headers_get_one")] #[doc(alias = "get_one")] pub fn one(&self, name: &str) -> Option { unsafe { from_glib_none(ffi::soup_message_headers_get_one( self.to_glib_none().0, name.to_glib_none().0, )) } } //#[doc(alias = "soup_message_headers_get_ranges")] //#[doc(alias = "get_ranges")] //pub fn ranges(&self, total_length: i64, ranges: /*Ignored*/Vec) -> Option { // unsafe { TODO: call ffi:soup_message_headers_get_ranges() } //} #[doc(alias = "soup_message_headers_header_contains")] pub fn header_contains(&self, name: &str, token: &str) -> bool { unsafe { from_glib(ffi::soup_message_headers_header_contains( self.to_glib_none().0, name.to_glib_none().0, token.to_glib_none().0, )) } } #[doc(alias = "soup_message_headers_header_equals")] pub fn header_equals(&self, name: &str, value: &str) -> bool { unsafe { from_glib(ffi::soup_message_headers_header_equals( self.to_glib_none().0, name.to_glib_none().0, value.to_glib_none().0, )) } } #[doc(alias = "soup_message_headers_remove")] pub fn remove(&self, name: &str) { unsafe { ffi::soup_message_headers_remove(self.to_glib_none().0, name.to_glib_none().0); } } #[doc(alias = "soup_message_headers_replace")] pub fn replace(&self, name: &str, value: &str) { unsafe { ffi::soup_message_headers_replace( self.to_glib_none().0, name.to_glib_none().0, value.to_glib_none().0, ); } } #[doc(alias = "soup_message_headers_set_content_length")] pub fn set_content_length(&self, content_length: i64) { unsafe { ffi::soup_message_headers_set_content_length(self.to_glib_none().0, content_length); } } #[doc(alias = "soup_message_headers_set_content_range")] pub fn set_content_range(&self, start: i64, end: i64, total_length: i64) { unsafe { ffi::soup_message_headers_set_content_range( self.to_glib_none().0, start, end, total_length, ); } } #[doc(alias = "soup_message_headers_set_encoding")] pub fn set_encoding(&self, encoding: Encoding) { unsafe { ffi::soup_message_headers_set_encoding(self.to_glib_none().0, encoding.into_glib()); } } #[doc(alias = "soup_message_headers_set_expectations")] pub fn set_expectations(&self, expectations: Expectation) { unsafe { ffi::soup_message_headers_set_expectations( self.to_glib_none().0, expectations.into_glib(), ); } } #[doc(alias = "soup_message_headers_set_range")] pub fn set_range(&self, start: i64, end: i64) { unsafe { ffi::soup_message_headers_set_range(self.to_glib_none().0, start, end); } } //#[doc(alias = "soup_message_headers_set_ranges")] //pub fn set_ranges(&self, ranges: /*Ignored*/&mut Range, length: i32) { // unsafe { TODO: call ffi:soup_message_headers_set_ranges() } //} } soup3-0.9.0/src/auto/message_metrics.rs000064400000000000000000000105411046102023000161630ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::ffi; use glib::translate::*; glib::wrapper! { #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct MessageMetrics(Boxed); match fn { copy => |ptr| ffi::soup_message_metrics_copy(mut_override(ptr)), free => |ptr| ffi::soup_message_metrics_free(ptr), type_ => || ffi::soup_message_metrics_get_type(), } } impl MessageMetrics { #[doc(alias = "soup_message_metrics_get_connect_end")] #[doc(alias = "get_connect_end")] pub fn connect_end(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_connect_end(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_connect_start")] #[doc(alias = "get_connect_start")] pub fn connect_start(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_connect_start(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_dns_end")] #[doc(alias = "get_dns_end")] pub fn dns_end(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_dns_end(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_dns_start")] #[doc(alias = "get_dns_start")] pub fn dns_start(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_dns_start(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_fetch_start")] #[doc(alias = "get_fetch_start")] pub fn fetch_start(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_fetch_start(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_request_body_bytes_sent")] #[doc(alias = "get_request_body_bytes_sent")] pub fn request_body_bytes_sent(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_request_body_bytes_sent(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_request_body_size")] #[doc(alias = "get_request_body_size")] pub fn request_body_size(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_request_body_size(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_request_header_bytes_sent")] #[doc(alias = "get_request_header_bytes_sent")] pub fn request_header_bytes_sent(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_request_header_bytes_sent(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_request_start")] #[doc(alias = "get_request_start")] pub fn request_start(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_request_start(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_response_body_bytes_received")] #[doc(alias = "get_response_body_bytes_received")] pub fn response_body_bytes_received(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_response_body_bytes_received(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_response_body_size")] #[doc(alias = "get_response_body_size")] pub fn response_body_size(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_response_body_size(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_response_end")] #[doc(alias = "get_response_end")] pub fn response_end(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_response_end(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_response_header_bytes_received")] #[doc(alias = "get_response_header_bytes_received")] pub fn response_header_bytes_received(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_response_header_bytes_received(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_response_start")] #[doc(alias = "get_response_start")] pub fn response_start(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_response_start(self.to_glib_none_mut().0) } } #[doc(alias = "soup_message_metrics_get_tls_start")] #[doc(alias = "get_tls_start")] pub fn tls_start(&mut self) -> u64 { unsafe { ffi::soup_message_metrics_get_tls_start(self.to_glib_none_mut().0) } } } soup3-0.9.0/src/auto/mod.rs000064400000000000000000000111011046102023000135610ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT mod auth; pub use self::auth::Auth; mod auth_basic; pub use self::auth_basic::AuthBasic; mod auth_digest; pub use self::auth_digest::AuthDigest; mod auth_domain; pub use self::auth_domain::AuthDomain; mod auth_domain_basic; pub use self::auth_domain_basic::AuthDomainBasic; mod auth_domain_digest; pub use self::auth_domain_digest::AuthDomainDigest; mod auth_manager; pub use self::auth_manager::AuthManager; mod auth_ntlm; pub use self::auth_ntlm::AuthNTLM; mod auth_negotiate; pub use self::auth_negotiate::AuthNegotiate; mod cache; pub use self::cache::Cache; mod content_decoder; pub use self::content_decoder::ContentDecoder; mod content_sniffer; pub use self::content_sniffer::ContentSniffer; mod cookie_jar; pub use self::cookie_jar::CookieJar; mod cookie_jar_db; pub use self::cookie_jar_db::CookieJarDB; mod cookie_jar_text; pub use self::cookie_jar_text::CookieJarText; mod hsts_enforcer; pub use self::hsts_enforcer::HSTSEnforcer; mod hsts_enforcer_db; pub use self::hsts_enforcer_db::HSTSEnforcerDB; mod logger; pub use self::logger::Logger; mod message; pub use self::message::Message; mod multipart_input_stream; pub use self::multipart_input_stream::MultipartInputStream; mod server; pub use self::server::Server; mod server_message; pub use self::server_message::ServerMessage; mod session; pub use self::session::Session; mod session_feature; pub use self::session_feature::SessionFeature; mod websocket_connection; pub use self::websocket_connection::WebsocketConnection; mod websocket_extension; pub use self::websocket_extension::WebsocketExtension; mod websocket_extension_deflate; pub use self::websocket_extension_deflate::WebsocketExtensionDeflate; mod websocket_extension_manager; pub use self::websocket_extension_manager::WebsocketExtensionManager; mod cookie; pub use self::cookie::Cookie; mod hsts_policy; pub use self::hsts_policy::HSTSPolicy; mod message_body; pub use self::message_body::MessageBody; mod message_headers; pub use self::message_headers::MessageHeaders; mod message_metrics; pub use self::message_metrics::MessageMetrics; mod multipart; pub use self::multipart::Multipart; mod enums; pub use self::enums::CacheType; pub use self::enums::CookieJarAcceptPolicy; pub use self::enums::DateFormat; pub use self::enums::Encoding; pub use self::enums::HTTPVersion; pub use self::enums::LoggerLogLevel; pub use self::enums::MemoryUse; pub use self::enums::MessageHeadersType; pub use self::enums::MessagePriority; pub use self::enums::SameSitePolicy; pub use self::enums::SessionError; pub use self::enums::Status; pub use self::enums::TLDError; pub use self::enums::URIComponent; pub use self::enums::WebsocketCloseCode; pub use self::enums::WebsocketConnectionType; pub use self::enums::WebsocketDataType; pub use self::enums::WebsocketError; pub use self::enums::WebsocketState; mod flags; pub use self::flags::Cacheability; pub use self::flags::Expectation; pub use self::flags::MessageFlags; pub use self::flags::ServerListenOptions; pub(crate) mod functions; mod constants; pub use self::constants::FORM_MIME_TYPE_MULTIPART; pub use self::constants::FORM_MIME_TYPE_URLENCODED; pub(crate) mod traits { pub use super::auth::AuthExt; pub use super::auth_domain::AuthDomainExt; pub use super::cache::CacheExt; pub use super::cookie_jar::CookieJarExt; pub use super::hsts_enforcer::HSTSEnforcerExt; pub use super::server::ServerExt; pub use super::session::SessionExt; pub use super::session_feature::SessionFeatureExt; pub use super::websocket_extension::WebsocketExtensionExt; } pub(crate) mod builders { pub use super::auth_basic::AuthBasicBuilder; pub use super::auth_digest::AuthDigestBuilder; pub use super::auth_domain_basic::AuthDomainBasicBuilder; pub use super::auth_domain_digest::AuthDomainDigestBuilder; pub use super::auth_negotiate::AuthNegotiateBuilder; pub use super::auth_ntlm::AuthNTLMBuilder; pub use super::cache::CacheBuilder; pub use super::cookie_jar::CookieJarBuilder; pub use super::cookie_jar_db::CookieJarDBBuilder; pub use super::cookie_jar_text::CookieJarTextBuilder; pub use super::hsts_enforcer_db::HSTSEnforcerDBBuilder; pub use super::logger::LoggerBuilder; pub use super::message::MessageBuilder; pub use super::multipart_input_stream::MultipartInputStreamBuilder; pub use super::server::ServerBuilder; pub use super::session::SessionBuilder; pub use super::websocket_connection::WebsocketConnectionBuilder; } soup3-0.9.0/src/auto/multipart.rs000064400000000000000000000074121046102023000150350ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{MessageHeaders, ffi}; use glib::translate::*; glib::wrapper! { #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct Multipart(Boxed); match fn { copy => |ptr| glib::gobject_ffi::g_boxed_copy(ffi::soup_multipart_get_type(), ptr as *mut _) as *mut ffi::SoupMultipart, free => |ptr| glib::gobject_ffi::g_boxed_free(ffi::soup_multipart_get_type(), ptr as *mut _), type_ => || ffi::soup_multipart_get_type(), } } impl Multipart { #[doc(alias = "soup_multipart_new")] pub fn new(mime_type: &str) -> Multipart { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_multipart_new(mime_type.to_glib_none().0)) } } #[doc(alias = "soup_multipart_new_from_message")] #[doc(alias = "new_from_message")] pub fn from_message(headers: &MessageHeaders, body: &glib::Bytes) -> Option { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_multipart_new_from_message( headers.to_glib_none().0, body.to_glib_none().0, )) } } #[doc(alias = "soup_multipart_append_form_file")] pub fn append_form_file( &mut self, control_name: &str, filename: Option<&str>, content_type: Option<&str>, body: &glib::Bytes, ) { unsafe { ffi::soup_multipart_append_form_file( self.to_glib_none_mut().0, control_name.to_glib_none().0, filename.to_glib_none().0, content_type.to_glib_none().0, body.to_glib_none().0, ); } } #[doc(alias = "soup_multipart_append_form_string")] pub fn append_form_string(&mut self, control_name: &str, data: &str) { unsafe { ffi::soup_multipart_append_form_string( self.to_glib_none_mut().0, control_name.to_glib_none().0, data.to_glib_none().0, ); } } #[doc(alias = "soup_multipart_append_part")] pub fn append_part(&mut self, headers: &MessageHeaders, body: &glib::Bytes) { unsafe { ffi::soup_multipart_append_part( self.to_glib_none_mut().0, headers.to_glib_none().0, body.to_glib_none().0, ); } } #[doc(alias = "soup_multipart_get_length")] #[doc(alias = "get_length")] pub fn length(&mut self) -> i32 { unsafe { ffi::soup_multipart_get_length(self.to_glib_none_mut().0) } } #[doc(alias = "soup_multipart_get_part")] #[doc(alias = "get_part")] pub fn part(&mut self, part: i32) -> Option<(MessageHeaders, glib::Bytes)> { unsafe { let mut headers = std::ptr::null_mut(); let mut body = std::ptr::null_mut(); let ret = from_glib(ffi::soup_multipart_get_part( self.to_glib_none_mut().0, part, &mut headers, &mut body, )); if ret { Some((from_glib_none(headers), from_glib_none(body))) } else { None } } } #[doc(alias = "soup_multipart_to_message")] pub fn to_message(&mut self, dest_headers: &MessageHeaders) -> glib::Bytes { unsafe { let mut dest_body = std::ptr::null_mut(); ffi::soup_multipart_to_message( self.to_glib_none_mut().0, dest_headers.to_glib_none().0, &mut dest_body, ); from_glib_full(dest_body) } } } soup3-0.9.0/src/auto/multipart_input_stream.rs000064400000000000000000000077631046102023000176400ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{Message, MessageHeaders, ffi}; use glib::{prelude::*, translate::*}; glib::wrapper! { #[doc(alias = "SoupMultipartInputStream")] pub struct MultipartInputStream(Object) @extends gio::FilterInputStream, gio::InputStream, @implements gio::PollableInputStream; match fn { type_ => || ffi::soup_multipart_input_stream_get_type(), } } impl MultipartInputStream { #[doc(alias = "soup_multipart_input_stream_new")] pub fn new(msg: &Message, base_stream: &impl IsA) -> MultipartInputStream { skip_assert_initialized!(); unsafe { from_glib_full(ffi::soup_multipart_input_stream_new( msg.to_glib_none().0, base_stream.as_ref().to_glib_none().0, )) } } // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`MultipartInputStream`] objects. /// /// This method returns an instance of [`MultipartInputStreamBuilder`](crate::builders::MultipartInputStreamBuilder) which can be used to create [`MultipartInputStream`] objects. pub fn builder() -> MultipartInputStreamBuilder { MultipartInputStreamBuilder::new() } #[doc(alias = "soup_multipart_input_stream_get_headers")] #[doc(alias = "get_headers")] pub fn headers(&self) -> Option { unsafe { from_glib_none(ffi::soup_multipart_input_stream_get_headers( self.to_glib_none().0, )) } } #[doc(alias = "soup_multipart_input_stream_next_part")] pub fn next_part( &self, cancellable: Option<&impl IsA>, ) -> Result, glib::Error> { unsafe { let mut error = std::ptr::null_mut(); let ret = ffi::soup_multipart_input_stream_next_part( self.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error, ); if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } } } pub fn message(&self) -> Option { ObjectExt::property(self, "message") } } impl Default for MultipartInputStream { fn default() -> Self { glib::object::Object::new::() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`MultipartInputStream`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct MultipartInputStreamBuilder { builder: glib::object::ObjectBuilder<'static, MultipartInputStream>, } impl MultipartInputStreamBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn message(self, message: &Message) -> Self { Self { builder: self.builder.property("message", message.clone()), } } pub fn base_stream(self, base_stream: &impl IsA) -> Self { Self { builder: self .builder .property("base-stream", base_stream.clone().upcast()), } } pub fn close_base_stream(self, close_base_stream: bool) -> Self { Self { builder: self .builder .property("close-base-stream", close_base_stream), } } // rustdoc-stripper-ignore-next /// Build the [`MultipartInputStream`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> MultipartInputStream { assert_initialized_main_thread!(); self.builder.build() } } soup3-0.9.0/src/auto/server.rs000064400000000000000000000502721046102023000143240ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT #![allow(deprecated)] use crate::{AuthDomain, ServerListenOptions, ServerMessage, ffi}; use glib::{ object::ObjectType as _, prelude::*, signal::{SignalHandlerId, connect_raw}, translate::*, }; use std::boxed::Box as Box_; glib::wrapper! { #[doc(alias = "SoupServer")] pub struct Server(Object); match fn { type_ => || ffi::soup_server_get_type(), } } impl Server { pub const NONE: Option<&'static Server> = None; //#[doc(alias = "soup_server_new")] //pub fn new(optname1: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> Option { // unsafe { TODO: call ffi:soup_server_new() } //} // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`Server`] objects. /// /// This method returns an instance of [`ServerBuilder`](crate::builders::ServerBuilder) which can be used to create [`Server`] objects. pub fn builder() -> ServerBuilder { ServerBuilder::new() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`Server`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct ServerBuilder { builder: glib::object::ObjectBuilder<'static, Server>, } impl ServerBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn raw_paths(self, raw_paths: bool) -> Self { Self { builder: self.builder.property("raw-paths", raw_paths), } } pub fn server_header(self, server_header: impl Into) -> Self { Self { builder: self.builder.property("server-header", server_header.into()), } } pub fn tls_auth_mode(self, tls_auth_mode: gio::TlsAuthenticationMode) -> Self { Self { builder: self.builder.property("tls-auth-mode", tls_auth_mode), } } pub fn tls_certificate(self, tls_certificate: &impl IsA) -> Self { Self { builder: self .builder .property("tls-certificate", tls_certificate.clone().upcast()), } } pub fn tls_database(self, tls_database: &impl IsA) -> Self { Self { builder: self .builder .property("tls-database", tls_database.clone().upcast()), } } // rustdoc-stripper-ignore-next /// Build the [`Server`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> Server { assert_initialized_main_thread!(); self.builder.build() } } pub trait ServerExt: IsA + 'static { #[doc(alias = "soup_server_accept_iostream")] fn accept_iostream( &self, stream: &impl IsA, local_addr: Option<&impl IsA>, remote_addr: Option<&impl IsA>, ) -> Result<(), glib::Error> { unsafe { let mut error = std::ptr::null_mut(); let is_ok = ffi::soup_server_accept_iostream( self.as_ref().to_glib_none().0, stream.as_ref().to_glib_none().0, local_addr.map(|p| p.as_ref()).to_glib_none().0, remote_addr.map(|p| p.as_ref()).to_glib_none().0, &mut error, ); debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null()); if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } } } #[doc(alias = "soup_server_add_auth_domain")] fn add_auth_domain(&self, auth_domain: &impl IsA) { unsafe { ffi::soup_server_add_auth_domain( self.as_ref().to_glib_none().0, auth_domain.as_ref().to_glib_none().0, ); } } #[doc(alias = "soup_server_add_websocket_extension")] fn add_websocket_extension(&self, extension_type: glib::types::Type) { unsafe { ffi::soup_server_add_websocket_extension( self.as_ref().to_glib_none().0, extension_type.into_glib(), ); } } #[doc(alias = "soup_server_disconnect")] fn disconnect(&self) { unsafe { ffi::soup_server_disconnect(self.as_ref().to_glib_none().0); } } #[doc(alias = "soup_server_get_listeners")] #[doc(alias = "get_listeners")] fn listeners(&self) -> Vec { unsafe { FromGlibPtrContainer::from_glib_container(ffi::soup_server_get_listeners( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_server_get_tls_auth_mode")] #[doc(alias = "get_tls_auth_mode")] #[doc(alias = "tls-auth-mode")] fn tls_auth_mode(&self) -> gio::TlsAuthenticationMode { unsafe { from_glib(ffi::soup_server_get_tls_auth_mode( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_server_get_tls_certificate")] #[doc(alias = "get_tls_certificate")] #[doc(alias = "tls-certificate")] fn tls_certificate(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_get_tls_certificate( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_server_get_tls_database")] #[doc(alias = "get_tls_database")] #[doc(alias = "tls-database")] fn tls_database(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_get_tls_database( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_server_get_uris")] #[doc(alias = "get_uris")] fn uris(&self) -> Vec { unsafe { FromGlibPtrContainer::from_glib_full(ffi::soup_server_get_uris( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_server_is_https")] fn is_https(&self) -> bool { unsafe { from_glib(ffi::soup_server_is_https(self.as_ref().to_glib_none().0)) } } #[doc(alias = "soup_server_listen")] fn listen( &self, address: &impl IsA, options: ServerListenOptions, ) -> Result<(), glib::Error> { unsafe { let mut error = std::ptr::null_mut(); let is_ok = ffi::soup_server_listen( self.as_ref().to_glib_none().0, address.as_ref().to_glib_none().0, options.into_glib(), &mut error, ); debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null()); if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } } } #[doc(alias = "soup_server_listen_all")] fn listen_all(&self, port: u32, options: ServerListenOptions) -> Result<(), glib::Error> { unsafe { let mut error = std::ptr::null_mut(); let is_ok = ffi::soup_server_listen_all( self.as_ref().to_glib_none().0, port, options.into_glib(), &mut error, ); debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null()); if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } } } #[doc(alias = "soup_server_listen_local")] fn listen_local(&self, port: u32, options: ServerListenOptions) -> Result<(), glib::Error> { unsafe { let mut error = std::ptr::null_mut(); let is_ok = ffi::soup_server_listen_local( self.as_ref().to_glib_none().0, port, options.into_glib(), &mut error, ); debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null()); if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } } } #[doc(alias = "soup_server_listen_socket")] fn listen_socket( &self, socket: &impl IsA, options: ServerListenOptions, ) -> Result<(), glib::Error> { unsafe { let mut error = std::ptr::null_mut(); let is_ok = ffi::soup_server_listen_socket( self.as_ref().to_glib_none().0, socket.as_ref().to_glib_none().0, options.into_glib(), &mut error, ); debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null()); if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } } } #[cfg_attr(feature = "v3_2", deprecated = "Since 3.2")] #[allow(deprecated)] #[doc(alias = "soup_server_pause_message")] fn pause_message(&self, msg: &ServerMessage) { unsafe { ffi::soup_server_pause_message(self.as_ref().to_glib_none().0, msg.to_glib_none().0); } } #[doc(alias = "soup_server_remove_auth_domain")] fn remove_auth_domain(&self, auth_domain: &impl IsA) { unsafe { ffi::soup_server_remove_auth_domain( self.as_ref().to_glib_none().0, auth_domain.as_ref().to_glib_none().0, ); } } #[doc(alias = "soup_server_remove_handler")] fn remove_handler(&self, path: &str) { unsafe { ffi::soup_server_remove_handler(self.as_ref().to_glib_none().0, path.to_glib_none().0); } } #[doc(alias = "soup_server_remove_websocket_extension")] fn remove_websocket_extension(&self, extension_type: glib::types::Type) { unsafe { ffi::soup_server_remove_websocket_extension( self.as_ref().to_glib_none().0, extension_type.into_glib(), ); } } #[doc(alias = "soup_server_set_tls_auth_mode")] #[doc(alias = "tls-auth-mode")] fn set_tls_auth_mode(&self, mode: gio::TlsAuthenticationMode) { unsafe { ffi::soup_server_set_tls_auth_mode(self.as_ref().to_glib_none().0, mode.into_glib()); } } #[doc(alias = "soup_server_set_tls_certificate")] #[doc(alias = "tls-certificate")] fn set_tls_certificate(&self, certificate: &impl IsA) { unsafe { ffi::soup_server_set_tls_certificate( self.as_ref().to_glib_none().0, certificate.as_ref().to_glib_none().0, ); } } #[doc(alias = "soup_server_set_tls_database")] #[doc(alias = "tls-database")] fn set_tls_database(&self, tls_database: &impl IsA) { unsafe { ffi::soup_server_set_tls_database( self.as_ref().to_glib_none().0, tls_database.as_ref().to_glib_none().0, ); } } #[cfg_attr(feature = "v3_2", deprecated = "Since 3.2")] #[allow(deprecated)] #[doc(alias = "soup_server_unpause_message")] fn unpause_message(&self, msg: &ServerMessage) { unsafe { ffi::soup_server_unpause_message(self.as_ref().to_glib_none().0, msg.to_glib_none().0); } } #[doc(alias = "raw-paths")] fn is_raw_paths(&self) -> bool { ObjectExt::property(self.as_ref(), "raw-paths") } #[doc(alias = "server-header")] fn server_header(&self) -> Option { ObjectExt::property(self.as_ref(), "server-header") } #[doc(alias = "server-header")] fn set_server_header(&self, server_header: Option<&str>) { ObjectExt::set_property(self.as_ref(), "server-header", server_header) } #[doc(alias = "request-aborted")] fn connect_request_aborted( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn request_aborted_trampoline< P: IsA, F: Fn(&P, &ServerMessage) + 'static, >( this: *mut ffi::SoupServer, message: *mut ffi::SoupServerMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f( Server::from_glib_borrow(this).unsafe_cast_ref(), &from_glib_borrow(message), ) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"request-aborted".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( request_aborted_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "request-finished")] fn connect_request_finished( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn request_finished_trampoline< P: IsA, F: Fn(&P, &ServerMessage) + 'static, >( this: *mut ffi::SoupServer, message: *mut ffi::SoupServerMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f( Server::from_glib_borrow(this).unsafe_cast_ref(), &from_glib_borrow(message), ) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"request-finished".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( request_finished_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "request-read")] fn connect_request_read( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn request_read_trampoline< P: IsA, F: Fn(&P, &ServerMessage) + 'static, >( this: *mut ffi::SoupServer, message: *mut ffi::SoupServerMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f( Server::from_glib_borrow(this).unsafe_cast_ref(), &from_glib_borrow(message), ) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"request-read".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( request_read_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "request-started")] fn connect_request_started( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn request_started_trampoline< P: IsA, F: Fn(&P, &ServerMessage) + 'static, >( this: *mut ffi::SoupServer, message: *mut ffi::SoupServerMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f( Server::from_glib_borrow(this).unsafe_cast_ref(), &from_glib_borrow(message), ) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"request-started".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( request_started_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "server-header")] fn connect_server_header_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_server_header_trampoline< P: IsA, F: Fn(&P) + 'static, >( this: *mut ffi::SoupServer, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Server::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::server-header".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_server_header_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "tls-auth-mode")] fn connect_tls_auth_mode_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_tls_auth_mode_trampoline< P: IsA, F: Fn(&P) + 'static, >( this: *mut ffi::SoupServer, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Server::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::tls-auth-mode".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_tls_auth_mode_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "tls-certificate")] fn connect_tls_certificate_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_tls_certificate_trampoline< P: IsA, F: Fn(&P) + 'static, >( this: *mut ffi::SoupServer, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Server::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::tls-certificate".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_tls_certificate_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "tls-database")] fn connect_tls_database_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_tls_database_trampoline, F: Fn(&P) + 'static>( this: *mut ffi::SoupServer, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Server::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::tls-database".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_tls_database_trampoline:: as *const (), )), Box_::into_raw(f), ) } } } impl> ServerExt for O {} soup3-0.9.0/src/auto/server_message.rs000064400000000000000000000504321046102023000160260ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{HTTPVersion, MemoryUse, MessageBody, MessageHeaders, ffi}; use glib::{ object::ObjectType as _, prelude::*, signal::{SignalHandlerId, connect_raw}, translate::*, }; use std::boxed::Box as Box_; glib::wrapper! { #[doc(alias = "SoupServerMessage")] pub struct ServerMessage(Object); match fn { type_ => || ffi::soup_server_message_get_type(), } } impl ServerMessage { #[doc(alias = "soup_server_message_get_http_version")] #[doc(alias = "get_http_version")] pub fn http_version(&self) -> HTTPVersion { unsafe { from_glib(ffi::soup_server_message_get_http_version( self.to_glib_none().0, )) } } #[doc(alias = "soup_server_message_get_local_address")] #[doc(alias = "get_local_address")] pub fn local_address(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_message_get_local_address( self.to_glib_none().0, )) } } #[doc(alias = "soup_server_message_get_method")] #[doc(alias = "get_method")] pub fn method(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_message_get_method(self.to_glib_none().0)) } } #[doc(alias = "soup_server_message_get_reason_phrase")] #[doc(alias = "get_reason_phrase")] pub fn reason_phrase(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_message_get_reason_phrase( self.to_glib_none().0, )) } } #[doc(alias = "soup_server_message_get_remote_address")] #[doc(alias = "get_remote_address")] pub fn remote_address(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_message_get_remote_address( self.to_glib_none().0, )) } } #[doc(alias = "soup_server_message_get_remote_host")] #[doc(alias = "get_remote_host")] pub fn remote_host(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_message_get_remote_host( self.to_glib_none().0, )) } } #[doc(alias = "soup_server_message_get_request_body")] #[doc(alias = "get_request_body")] pub fn request_body(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_message_get_request_body( self.to_glib_none().0, )) } } #[doc(alias = "soup_server_message_get_request_headers")] #[doc(alias = "get_request_headers")] pub fn request_headers(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_message_get_request_headers( self.to_glib_none().0, )) } } #[doc(alias = "soup_server_message_get_response_body")] #[doc(alias = "get_response_body")] pub fn response_body(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_message_get_response_body( self.to_glib_none().0, )) } } #[doc(alias = "soup_server_message_get_response_headers")] #[doc(alias = "get_response_headers")] pub fn response_headers(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_message_get_response_headers( self.to_glib_none().0, )) } } #[doc(alias = "soup_server_message_get_socket")] #[doc(alias = "get_socket")] pub fn socket(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_message_get_socket(self.to_glib_none().0)) } } #[doc(alias = "soup_server_message_get_status")] #[doc(alias = "get_status")] pub fn status(&self) -> u32 { unsafe { ffi::soup_server_message_get_status(self.to_glib_none().0) } } #[cfg(feature = "v3_2")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_2")))] #[doc(alias = "soup_server_message_get_tls_peer_certificate")] #[doc(alias = "get_tls_peer_certificate")] #[doc(alias = "tls-peer-certificate")] pub fn tls_peer_certificate(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_message_get_tls_peer_certificate( self.to_glib_none().0, )) } } #[cfg(feature = "v3_2")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_2")))] #[doc(alias = "soup_server_message_get_tls_peer_certificate_errors")] #[doc(alias = "get_tls_peer_certificate_errors")] #[doc(alias = "tls-peer-certificate-errors")] pub fn tls_peer_certificate_errors(&self) -> gio::TlsCertificateFlags { unsafe { from_glib(ffi::soup_server_message_get_tls_peer_certificate_errors( self.to_glib_none().0, )) } } #[doc(alias = "soup_server_message_get_uri")] #[doc(alias = "get_uri")] pub fn uri(&self) -> Option { unsafe { from_glib_none(ffi::soup_server_message_get_uri(self.to_glib_none().0)) } } #[doc(alias = "soup_server_message_is_options_ping")] pub fn is_options_ping(&self) -> bool { unsafe { from_glib(ffi::soup_server_message_is_options_ping( self.to_glib_none().0, )) } } #[cfg(feature = "v3_2")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_2")))] #[doc(alias = "soup_server_message_pause")] pub fn pause(&self) { unsafe { ffi::soup_server_message_pause(self.to_glib_none().0); } } #[doc(alias = "soup_server_message_set_http_version")] pub fn set_http_version(&self, version: HTTPVersion) { unsafe { ffi::soup_server_message_set_http_version(self.to_glib_none().0, version.into_glib()); } } #[doc(alias = "soup_server_message_set_redirect")] pub fn set_redirect(&self, status_code: u32, redirect_uri: &str) { unsafe { ffi::soup_server_message_set_redirect( self.to_glib_none().0, status_code, redirect_uri.to_glib_none().0, ); } } #[doc(alias = "soup_server_message_set_response")] pub fn set_response(&self, content_type: Option<&str>, resp_use: MemoryUse, resp_body: &[u8]) { let resp_length = resp_body.len() as _; unsafe { ffi::soup_server_message_set_response( self.to_glib_none().0, content_type.to_glib_none().0, resp_use.into_glib(), resp_body.to_glib_none().0, resp_length, ); } } #[doc(alias = "soup_server_message_set_status")] pub fn set_status(&self, status_code: u32, reason_phrase: Option<&str>) { unsafe { ffi::soup_server_message_set_status( self.to_glib_none().0, status_code, reason_phrase.to_glib_none().0, ); } } #[doc(alias = "soup_server_message_steal_connection")] pub fn steal_connection(&self) -> Option { unsafe { from_glib_full(ffi::soup_server_message_steal_connection( self.to_glib_none().0, )) } } #[cfg(feature = "v3_2")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_2")))] #[doc(alias = "soup_server_message_unpause")] pub fn unpause(&self) { unsafe { ffi::soup_server_message_unpause(self.to_glib_none().0); } } #[doc(alias = "accept-certificate")] pub fn connect_accept_certificate< F: Fn(&Self, &gio::TlsCertificate, gio::TlsCertificateFlags) -> bool + 'static, >( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn accept_certificate_trampoline< F: Fn(&ServerMessage, &gio::TlsCertificate, gio::TlsCertificateFlags) -> bool + 'static, >( this: *mut ffi::SoupServerMessage, tls_peer_certificate: *mut gio::ffi::GTlsCertificate, tls_peer_errors: gio::ffi::GTlsCertificateFlags, f: glib::ffi::gpointer, ) -> glib::ffi::gboolean { unsafe { let f: &F = &*(f as *const F); f( &from_glib_borrow(this), &from_glib_borrow(tls_peer_certificate), from_glib(tls_peer_errors), ) .into_glib() } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"accept-certificate".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( accept_certificate_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "connected")] pub fn connect_connected(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn connected_trampoline( this: *mut ffi::SoupServerMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"connected".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( connected_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "disconnected")] pub fn connect_disconnected(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn disconnected_trampoline( this: *mut ffi::SoupServerMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"disconnected".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( disconnected_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "finished")] pub fn connect_finished(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn finished_trampoline( this: *mut ffi::SoupServerMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"finished".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( finished_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "got-body")] pub fn connect_got_body(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn got_body_trampoline( this: *mut ffi::SoupServerMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"got-body".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( got_body_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "got-chunk")] pub fn connect_got_chunk(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn got_chunk_trampoline( this: *mut ffi::SoupServerMessage, chunk: *mut glib::ffi::GBytes, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this), &from_glib_borrow(chunk)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"got-chunk".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( got_chunk_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "got-headers")] pub fn connect_got_headers(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn got_headers_trampoline( this: *mut ffi::SoupServerMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"got-headers".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( got_headers_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "wrote-body")] pub fn connect_wrote_body(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn wrote_body_trampoline( this: *mut ffi::SoupServerMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"wrote-body".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( wrote_body_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "wrote-body-data")] pub fn connect_wrote_body_data(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn wrote_body_data_trampoline( this: *mut ffi::SoupServerMessage, chunk_size: std::ffi::c_uint, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this), chunk_size) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"wrote-body-data".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( wrote_body_data_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "wrote-chunk")] pub fn connect_wrote_chunk(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn wrote_chunk_trampoline( this: *mut ffi::SoupServerMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"wrote-chunk".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( wrote_chunk_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "wrote-headers")] pub fn connect_wrote_headers(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn wrote_headers_trampoline( this: *mut ffi::SoupServerMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"wrote-headers".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( wrote_headers_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "wrote-informational")] pub fn connect_wrote_informational(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn wrote_informational_trampoline( this: *mut ffi::SoupServerMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"wrote-informational".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( wrote_informational_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[cfg(feature = "v3_2")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_2")))] #[doc(alias = "tls-peer-certificate")] pub fn connect_tls_peer_certificate_notify( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn notify_tls_peer_certificate_trampoline< F: Fn(&ServerMessage) + 'static, >( this: *mut ffi::SoupServerMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::tls-peer-certificate".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_tls_peer_certificate_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[cfg(feature = "v3_2")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_2")))] #[doc(alias = "tls-peer-certificate-errors")] pub fn connect_tls_peer_certificate_errors_notify( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn notify_tls_peer_certificate_errors_trampoline< F: Fn(&ServerMessage) + 'static, >( this: *mut ffi::SoupServerMessage, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::tls-peer-certificate-errors".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_tls_peer_certificate_errors_trampoline:: as *const (), )), Box_::into_raw(f), ) } } } soup3-0.9.0/src/auto/session.rs000064400000000000000000001125561046102023000145050ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{Message, SessionFeature, WebsocketConnection, ffi}; use glib::{ object::ObjectType as _, prelude::*, signal::{SignalHandlerId, connect_raw}, translate::*, }; use std::{boxed::Box as Box_, pin::Pin}; glib::wrapper! { #[doc(alias = "SoupSession")] pub struct Session(Object); match fn { type_ => || ffi::soup_session_get_type(), } } impl Session { pub const NONE: Option<&'static Session> = None; #[doc(alias = "soup_session_new")] pub fn new() -> Session { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_session_new()) } } //#[doc(alias = "soup_session_new_with_options")] //#[doc(alias = "new_with_options")] //pub fn with_options(optname1: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> Session { // unsafe { TODO: call ffi:soup_session_new_with_options() } //} // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`Session`] objects. /// /// This method returns an instance of [`SessionBuilder`](crate::builders::SessionBuilder) which can be used to create [`Session`] objects. pub fn builder() -> SessionBuilder { SessionBuilder::new() } } impl Default for Session { fn default() -> Self { Self::new() } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`Session`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct SessionBuilder { builder: glib::object::ObjectBuilder<'static, Session>, } impl SessionBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn accept_language(self, accept_language: impl Into) -> Self { Self { builder: self .builder .property("accept-language", accept_language.into()), } } pub fn accept_language_auto(self, accept_language_auto: bool) -> Self { Self { builder: self .builder .property("accept-language-auto", accept_language_auto), } } pub fn idle_timeout(self, idle_timeout: u32) -> Self { Self { builder: self.builder.property("idle-timeout", idle_timeout), } } pub fn local_address(self, local_address: &impl IsA) -> Self { Self { builder: self .builder .property("local-address", local_address.clone().upcast()), } } pub fn max_conns(self, max_conns: i32) -> Self { Self { builder: self.builder.property("max-conns", max_conns), } } pub fn max_conns_per_host(self, max_conns_per_host: i32) -> Self { Self { builder: self .builder .property("max-conns-per-host", max_conns_per_host), } } pub fn proxy_resolver(self, proxy_resolver: &impl IsA) -> Self { Self { builder: self .builder .property("proxy-resolver", proxy_resolver.clone().upcast()), } } pub fn remote_connectable(self, remote_connectable: &impl IsA) -> Self { Self { builder: self .builder .property("remote-connectable", remote_connectable.clone().upcast()), } } pub fn timeout(self, timeout: u32) -> Self { Self { builder: self.builder.property("timeout", timeout), } } pub fn tls_database(self, tls_database: &impl IsA) -> Self { Self { builder: self .builder .property("tls-database", tls_database.clone().upcast()), } } pub fn tls_interaction(self, tls_interaction: &impl IsA) -> Self { Self { builder: self .builder .property("tls-interaction", tls_interaction.clone().upcast()), } } pub fn user_agent(self, user_agent: impl Into) -> Self { Self { builder: self.builder.property("user-agent", user_agent.into()), } } // rustdoc-stripper-ignore-next /// Build the [`Session`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> Session { assert_initialized_main_thread!(); self.builder.build() } } pub trait SessionExt: IsA + 'static { #[doc(alias = "soup_session_abort")] fn abort(&self) { unsafe { ffi::soup_session_abort(self.as_ref().to_glib_none().0); } } #[doc(alias = "soup_session_add_feature")] fn add_feature(&self, feature: &impl IsA) { unsafe { ffi::soup_session_add_feature( self.as_ref().to_glib_none().0, feature.as_ref().to_glib_none().0, ); } } #[doc(alias = "soup_session_add_feature_by_type")] fn add_feature_by_type(&self, feature_type: glib::types::Type) { unsafe { ffi::soup_session_add_feature_by_type( self.as_ref().to_glib_none().0, feature_type.into_glib(), ); } } #[doc(alias = "soup_session_get_accept_language")] #[doc(alias = "get_accept_language")] #[doc(alias = "accept-language")] fn accept_language(&self) -> Option { unsafe { from_glib_none(ffi::soup_session_get_accept_language( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_session_get_accept_language_auto")] #[doc(alias = "get_accept_language_auto")] #[doc(alias = "accept-language-auto")] fn accepts_language_auto(&self) -> bool { unsafe { from_glib(ffi::soup_session_get_accept_language_auto( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_session_get_async_result_message")] #[doc(alias = "get_async_result_message")] fn async_result_message(&self, result: &impl IsA) -> Option { unsafe { from_glib_none(ffi::soup_session_get_async_result_message( self.as_ref().to_glib_none().0, result.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_session_get_feature")] #[doc(alias = "get_feature")] fn feature(&self, feature_type: glib::types::Type) -> Option { unsafe { from_glib_none(ffi::soup_session_get_feature( self.as_ref().to_glib_none().0, feature_type.into_glib(), )) } } #[doc(alias = "soup_session_get_feature_for_message")] #[doc(alias = "get_feature_for_message")] fn feature_for_message( &self, feature_type: glib::types::Type, msg: &Message, ) -> Option { unsafe { from_glib_none(ffi::soup_session_get_feature_for_message( self.as_ref().to_glib_none().0, feature_type.into_glib(), msg.to_glib_none().0, )) } } #[doc(alias = "soup_session_get_idle_timeout")] #[doc(alias = "get_idle_timeout")] #[doc(alias = "idle-timeout")] fn idle_timeout(&self) -> u32 { unsafe { ffi::soup_session_get_idle_timeout(self.as_ref().to_glib_none().0) } } #[doc(alias = "soup_session_get_local_address")] #[doc(alias = "get_local_address")] #[doc(alias = "local-address")] fn local_address(&self) -> Option { unsafe { from_glib_none(ffi::soup_session_get_local_address( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_session_get_max_conns")] #[doc(alias = "get_max_conns")] #[doc(alias = "max-conns")] fn max_conns(&self) -> u32 { unsafe { ffi::soup_session_get_max_conns(self.as_ref().to_glib_none().0) } } #[doc(alias = "soup_session_get_max_conns_per_host")] #[doc(alias = "get_max_conns_per_host")] #[doc(alias = "max-conns-per-host")] fn max_conns_per_host(&self) -> u32 { unsafe { ffi::soup_session_get_max_conns_per_host(self.as_ref().to_glib_none().0) } } #[doc(alias = "soup_session_get_proxy_resolver")] #[doc(alias = "get_proxy_resolver")] #[doc(alias = "proxy-resolver")] fn proxy_resolver(&self) -> Option { unsafe { from_glib_none(ffi::soup_session_get_proxy_resolver( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_session_get_remote_connectable")] #[doc(alias = "get_remote_connectable")] #[doc(alias = "remote-connectable")] fn remote_connectable(&self) -> Option { unsafe { from_glib_none(ffi::soup_session_get_remote_connectable( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_session_get_timeout")] #[doc(alias = "get_timeout")] fn timeout(&self) -> u32 { unsafe { ffi::soup_session_get_timeout(self.as_ref().to_glib_none().0) } } #[doc(alias = "soup_session_get_tls_database")] #[doc(alias = "get_tls_database")] #[doc(alias = "tls-database")] fn tls_database(&self) -> Option { unsafe { from_glib_none(ffi::soup_session_get_tls_database( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_session_get_tls_interaction")] #[doc(alias = "get_tls_interaction")] #[doc(alias = "tls-interaction")] fn tls_interaction(&self) -> Option { unsafe { from_glib_none(ffi::soup_session_get_tls_interaction( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_session_get_user_agent")] #[doc(alias = "get_user_agent")] #[doc(alias = "user-agent")] fn user_agent(&self) -> Option { unsafe { from_glib_none(ffi::soup_session_get_user_agent( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_session_has_feature")] fn has_feature(&self, feature_type: glib::types::Type) -> bool { unsafe { from_glib(ffi::soup_session_has_feature( self.as_ref().to_glib_none().0, feature_type.into_glib(), )) } } #[doc(alias = "soup_session_preconnect_async")] fn preconnect_async) + 'static>( &self, msg: &Message, io_priority: glib::Priority, cancellable: Option<&impl IsA>, callback: P, ) { let main_context = glib::MainContext::ref_thread_default(); let is_main_context_owner = main_context.is_owner(); let has_acquired_main_context = (!is_main_context_owner) .then(|| main_context.acquire().ok()) .flatten(); assert!( is_main_context_owner || has_acquired_main_context.is_some(), "Async operations only allowed if the thread is owning the MainContext" ); let user_data: Box_> = Box_::new(glib::thread_guard::ThreadGuard::new(callback)); unsafe extern "C" fn preconnect_async_trampoline< P: FnOnce(Result<(), glib::Error>) + 'static, >( _source_object: *mut glib::gobject_ffi::GObject, res: *mut gio::ffi::GAsyncResult, user_data: glib::ffi::gpointer, ) { unsafe { let mut error = std::ptr::null_mut(); ffi::soup_session_preconnect_finish(_source_object as *mut _, res, &mut error); let result = if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) }; let callback: Box_> = Box_::from_raw(user_data as *mut _); let callback: P = callback.into_inner(); callback(result); } } let callback = preconnect_async_trampoline::

; unsafe { ffi::soup_session_preconnect_async( self.as_ref().to_glib_none().0, msg.to_glib_none().0, io_priority.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, Some(callback), Box_::into_raw(user_data) as *mut _, ); } } fn preconnect_future( &self, msg: &Message, io_priority: glib::Priority, ) -> Pin> + 'static>> { let msg = msg.clone(); Box_::pin(gio::GioFuture::new(self, move |obj, cancellable, send| { obj.preconnect_async(&msg, io_priority, Some(cancellable), move |res| { send.resolve(res); }); })) } #[doc(alias = "soup_session_remove_feature")] fn remove_feature(&self, feature: &impl IsA) { unsafe { ffi::soup_session_remove_feature( self.as_ref().to_glib_none().0, feature.as_ref().to_glib_none().0, ); } } #[doc(alias = "soup_session_remove_feature_by_type")] fn remove_feature_by_type(&self, feature_type: glib::types::Type) { unsafe { ffi::soup_session_remove_feature_by_type( self.as_ref().to_glib_none().0, feature_type.into_glib(), ); } } #[doc(alias = "soup_session_send")] fn send( &self, msg: &Message, cancellable: Option<&impl IsA>, ) -> Result { unsafe { let mut error = std::ptr::null_mut(); let ret = ffi::soup_session_send( self.as_ref().to_glib_none().0, msg.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error, ); if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } } } #[doc(alias = "soup_session_send_and_read")] fn send_and_read( &self, msg: &Message, cancellable: Option<&impl IsA>, ) -> Result { unsafe { let mut error = std::ptr::null_mut(); let ret = ffi::soup_session_send_and_read( self.as_ref().to_glib_none().0, msg.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error, ); if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } } } #[doc(alias = "soup_session_send_and_read_async")] fn send_and_read_async) + 'static>( &self, msg: &Message, io_priority: glib::Priority, cancellable: Option<&impl IsA>, callback: P, ) { let main_context = glib::MainContext::ref_thread_default(); let is_main_context_owner = main_context.is_owner(); let has_acquired_main_context = (!is_main_context_owner) .then(|| main_context.acquire().ok()) .flatten(); assert!( is_main_context_owner || has_acquired_main_context.is_some(), "Async operations only allowed if the thread is owning the MainContext" ); let user_data: Box_> = Box_::new(glib::thread_guard::ThreadGuard::new(callback)); unsafe extern "C" fn send_and_read_async_trampoline< P: FnOnce(Result) + 'static, >( _source_object: *mut glib::gobject_ffi::GObject, res: *mut gio::ffi::GAsyncResult, user_data: glib::ffi::gpointer, ) { unsafe { let mut error = std::ptr::null_mut(); let ret = ffi::soup_session_send_and_read_finish( _source_object as *mut _, res, &mut error, ); let result = if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) }; let callback: Box_> = Box_::from_raw(user_data as *mut _); let callback: P = callback.into_inner(); callback(result); } } let callback = send_and_read_async_trampoline::

; unsafe { ffi::soup_session_send_and_read_async( self.as_ref().to_glib_none().0, msg.to_glib_none().0, io_priority.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, Some(callback), Box_::into_raw(user_data) as *mut _, ); } } fn send_and_read_future( &self, msg: &Message, io_priority: glib::Priority, ) -> Pin> + 'static>> { let msg = msg.clone(); Box_::pin(gio::GioFuture::new(self, move |obj, cancellable, send| { obj.send_and_read_async(&msg, io_priority, Some(cancellable), move |res| { send.resolve(res); }); })) } #[cfg(feature = "v3_4")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_4")))] #[doc(alias = "soup_session_send_and_splice")] fn send_and_splice( &self, msg: &Message, out_stream: &impl IsA, flags: gio::OutputStreamSpliceFlags, cancellable: Option<&impl IsA>, ) -> Result { unsafe { let mut error = std::ptr::null_mut(); let ret = ffi::soup_session_send_and_splice( self.as_ref().to_glib_none().0, msg.to_glib_none().0, out_stream.as_ref().to_glib_none().0, flags.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error, ); if error.is_null() { Ok(ret) } else { Err(from_glib_full(error)) } } } #[cfg(feature = "v3_4")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_4")))] #[doc(alias = "soup_session_send_and_splice_async")] fn send_and_splice_async) + 'static>( &self, msg: &Message, out_stream: &impl IsA, flags: gio::OutputStreamSpliceFlags, io_priority: glib::Priority, cancellable: Option<&impl IsA>, callback: P, ) { let main_context = glib::MainContext::ref_thread_default(); let is_main_context_owner = main_context.is_owner(); let has_acquired_main_context = (!is_main_context_owner) .then(|| main_context.acquire().ok()) .flatten(); assert!( is_main_context_owner || has_acquired_main_context.is_some(), "Async operations only allowed if the thread is owning the MainContext" ); let user_data: Box_> = Box_::new(glib::thread_guard::ThreadGuard::new(callback)); unsafe extern "C" fn send_and_splice_async_trampoline< P: FnOnce(Result) + 'static, >( _source_object: *mut glib::gobject_ffi::GObject, res: *mut gio::ffi::GAsyncResult, user_data: glib::ffi::gpointer, ) { unsafe { let mut error = std::ptr::null_mut(); let ret = ffi::soup_session_send_and_splice_finish( _source_object as *mut _, res, &mut error, ); let result = if error.is_null() { Ok(ret) } else { Err(from_glib_full(error)) }; let callback: Box_> = Box_::from_raw(user_data as *mut _); let callback: P = callback.into_inner(); callback(result); } } let callback = send_and_splice_async_trampoline::

; unsafe { ffi::soup_session_send_and_splice_async( self.as_ref().to_glib_none().0, msg.to_glib_none().0, out_stream.as_ref().to_glib_none().0, flags.into_glib(), io_priority.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, Some(callback), Box_::into_raw(user_data) as *mut _, ); } } #[cfg(feature = "v3_4")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_4")))] fn send_and_splice_future( &self, msg: &Message, out_stream: &(impl IsA + Clone + 'static), flags: gio::OutputStreamSpliceFlags, io_priority: glib::Priority, ) -> Pin> + 'static>> { let msg = msg.clone(); let out_stream = out_stream.clone(); Box_::pin(gio::GioFuture::new(self, move |obj, cancellable, send| { obj.send_and_splice_async( &msg, &out_stream, flags, io_priority, Some(cancellable), move |res| { send.resolve(res); }, ); })) } #[doc(alias = "soup_session_send_async")] fn send_async) + 'static>( &self, msg: &Message, io_priority: glib::Priority, cancellable: Option<&impl IsA>, callback: P, ) { let main_context = glib::MainContext::ref_thread_default(); let is_main_context_owner = main_context.is_owner(); let has_acquired_main_context = (!is_main_context_owner) .then(|| main_context.acquire().ok()) .flatten(); assert!( is_main_context_owner || has_acquired_main_context.is_some(), "Async operations only allowed if the thread is owning the MainContext" ); let user_data: Box_> = Box_::new(glib::thread_guard::ThreadGuard::new(callback)); unsafe extern "C" fn send_async_trampoline< P: FnOnce(Result) + 'static, >( _source_object: *mut glib::gobject_ffi::GObject, res: *mut gio::ffi::GAsyncResult, user_data: glib::ffi::gpointer, ) { unsafe { let mut error = std::ptr::null_mut(); let ret = ffi::soup_session_send_finish(_source_object as *mut _, res, &mut error); let result = if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) }; let callback: Box_> = Box_::from_raw(user_data as *mut _); let callback: P = callback.into_inner(); callback(result); } } let callback = send_async_trampoline::

; unsafe { ffi::soup_session_send_async( self.as_ref().to_glib_none().0, msg.to_glib_none().0, io_priority.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, Some(callback), Box_::into_raw(user_data) as *mut _, ); } } fn send_future( &self, msg: &Message, io_priority: glib::Priority, ) -> Pin> + 'static>> { let msg = msg.clone(); Box_::pin(gio::GioFuture::new(self, move |obj, cancellable, send| { obj.send_async(&msg, io_priority, Some(cancellable), move |res| { send.resolve(res); }); })) } #[doc(alias = "soup_session_set_accept_language")] #[doc(alias = "accept-language")] fn set_accept_language(&self, accept_language: &str) { unsafe { ffi::soup_session_set_accept_language( self.as_ref().to_glib_none().0, accept_language.to_glib_none().0, ); } } #[doc(alias = "soup_session_set_accept_language_auto")] #[doc(alias = "accept-language-auto")] fn set_accept_language_auto(&self, accept_language_auto: bool) { unsafe { ffi::soup_session_set_accept_language_auto( self.as_ref().to_glib_none().0, accept_language_auto.into_glib(), ); } } #[doc(alias = "soup_session_set_idle_timeout")] #[doc(alias = "idle-timeout")] fn set_idle_timeout(&self, timeout: u32) { unsafe { ffi::soup_session_set_idle_timeout(self.as_ref().to_glib_none().0, timeout); } } #[doc(alias = "soup_session_set_proxy_resolver")] #[doc(alias = "proxy-resolver")] fn set_proxy_resolver(&self, proxy_resolver: Option<&impl IsA>) { unsafe { ffi::soup_session_set_proxy_resolver( self.as_ref().to_glib_none().0, proxy_resolver.map(|p| p.as_ref()).to_glib_none().0, ); } } #[doc(alias = "soup_session_set_timeout")] #[doc(alias = "timeout")] fn set_timeout(&self, timeout: u32) { unsafe { ffi::soup_session_set_timeout(self.as_ref().to_glib_none().0, timeout); } } #[doc(alias = "soup_session_set_tls_database")] #[doc(alias = "tls-database")] fn set_tls_database(&self, tls_database: Option<&impl IsA>) { unsafe { ffi::soup_session_set_tls_database( self.as_ref().to_glib_none().0, tls_database.map(|p| p.as_ref()).to_glib_none().0, ); } } #[doc(alias = "soup_session_set_tls_interaction")] #[doc(alias = "tls-interaction")] fn set_tls_interaction(&self, tls_interaction: Option<&impl IsA>) { unsafe { ffi::soup_session_set_tls_interaction( self.as_ref().to_glib_none().0, tls_interaction.map(|p| p.as_ref()).to_glib_none().0, ); } } #[doc(alias = "soup_session_set_user_agent")] #[doc(alias = "user-agent")] fn set_user_agent(&self, user_agent: &str) { unsafe { ffi::soup_session_set_user_agent( self.as_ref().to_glib_none().0, user_agent.to_glib_none().0, ); } } #[doc(alias = "request-queued")] fn connect_request_queued(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn request_queued_trampoline< P: IsA, F: Fn(&P, &Message) + 'static, >( this: *mut ffi::SoupSession, msg: *mut ffi::SoupMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f( Session::from_glib_borrow(this).unsafe_cast_ref(), &from_glib_borrow(msg), ) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"request-queued".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( request_queued_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "request-unqueued")] fn connect_request_unqueued(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn request_unqueued_trampoline< P: IsA, F: Fn(&P, &Message) + 'static, >( this: *mut ffi::SoupSession, msg: *mut ffi::SoupMessage, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f( Session::from_glib_borrow(this).unsafe_cast_ref(), &from_glib_borrow(msg), ) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"request-unqueued".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( request_unqueued_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "accept-language")] fn connect_accept_language_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_accept_language_trampoline< P: IsA, F: Fn(&P) + 'static, >( this: *mut ffi::SoupSession, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Session::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::accept-language".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_accept_language_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "accept-language-auto")] fn connect_accept_language_auto_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_accept_language_auto_trampoline< P: IsA, F: Fn(&P) + 'static, >( this: *mut ffi::SoupSession, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Session::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::accept-language-auto".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_accept_language_auto_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "idle-timeout")] fn connect_idle_timeout_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_idle_timeout_trampoline< P: IsA, F: Fn(&P) + 'static, >( this: *mut ffi::SoupSession, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Session::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::idle-timeout".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_idle_timeout_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "proxy-resolver")] fn connect_proxy_resolver_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_proxy_resolver_trampoline< P: IsA, F: Fn(&P) + 'static, >( this: *mut ffi::SoupSession, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Session::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::proxy-resolver".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_proxy_resolver_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "timeout")] fn connect_timeout_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_timeout_trampoline, F: Fn(&P) + 'static>( this: *mut ffi::SoupSession, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Session::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::timeout".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_timeout_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "tls-database")] fn connect_tls_database_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_tls_database_trampoline< P: IsA, F: Fn(&P) + 'static, >( this: *mut ffi::SoupSession, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Session::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::tls-database".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_tls_database_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "tls-interaction")] fn connect_tls_interaction_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_tls_interaction_trampoline< P: IsA, F: Fn(&P) + 'static, >( this: *mut ffi::SoupSession, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Session::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::tls-interaction".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_tls_interaction_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "user-agent")] fn connect_user_agent_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_user_agent_trampoline, F: Fn(&P) + 'static>( this: *mut ffi::SoupSession, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(Session::from_glib_borrow(this).unsafe_cast_ref()) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::user-agent".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_user_agent_trampoline:: as *const (), )), Box_::into_raw(f), ) } } } impl> SessionExt for O {} soup3-0.9.0/src/auto/session_feature.rs000064400000000000000000000011671046102023000162130ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::ffi; use glib::prelude::*; glib::wrapper! { #[doc(alias = "SoupSessionFeature")] pub struct SessionFeature(Interface); match fn { type_ => || ffi::soup_session_feature_get_type(), } } impl SessionFeature { pub const NONE: Option<&'static SessionFeature> = None; } pub trait SessionFeatureExt: IsA + 'static {} impl> SessionFeatureExt for O {} soup3-0.9.0/src/auto/versions.txt000064400000000000000000000002121046102023000150460ustar 00000000000000Generated by gir (https://github.com/gtk-rs/gir @ 36917718ae60) from from gir-files (https://github.com/gtk-rs/gir-files @ a0aa73ce0d61) soup3-0.9.0/src/auto/websocket_connection.rs000064400000000000000000000474741046102023000172350ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{WebsocketConnectionType, WebsocketExtension, WebsocketState, ffi}; use glib::{ object::ObjectType as _, prelude::*, signal::{SignalHandlerId, connect_raw}, translate::*, }; use std::boxed::Box as Box_; glib::wrapper! { #[doc(alias = "SoupWebsocketConnection")] pub struct WebsocketConnection(Object); match fn { type_ => || ffi::soup_websocket_connection_get_type(), } } impl WebsocketConnection { // rustdoc-stripper-ignore-next /// Creates a new builder-pattern struct instance to construct [`WebsocketConnection`] objects. /// /// This method returns an instance of [`WebsocketConnectionBuilder`](crate::builders::WebsocketConnectionBuilder) which can be used to create [`WebsocketConnection`] objects. pub fn builder() -> WebsocketConnectionBuilder { WebsocketConnectionBuilder::new() } #[doc(alias = "soup_websocket_connection_close")] pub fn close(&self, code: libc::c_ushort, data: Option<&str>) { unsafe { ffi::soup_websocket_connection_close( self.to_glib_none().0, code, data.to_glib_none().0, ); } } #[doc(alias = "soup_websocket_connection_get_close_code")] #[doc(alias = "get_close_code")] pub fn close_code(&self) -> libc::c_ushort { unsafe { ffi::soup_websocket_connection_get_close_code(self.to_glib_none().0) } } #[doc(alias = "soup_websocket_connection_get_close_data")] #[doc(alias = "get_close_data")] pub fn close_data(&self) -> Option { unsafe { from_glib_none(ffi::soup_websocket_connection_get_close_data( self.to_glib_none().0, )) } } #[doc(alias = "soup_websocket_connection_get_connection_type")] #[doc(alias = "get_connection_type")] #[doc(alias = "connection-type")] pub fn connection_type(&self) -> WebsocketConnectionType { unsafe { from_glib(ffi::soup_websocket_connection_get_connection_type( self.to_glib_none().0, )) } } #[doc(alias = "soup_websocket_connection_get_extensions")] #[doc(alias = "get_extensions")] pub fn extensions(&self) -> Vec { unsafe { FromGlibPtrContainer::from_glib_none(ffi::soup_websocket_connection_get_extensions( self.to_glib_none().0, )) } } #[doc(alias = "soup_websocket_connection_get_io_stream")] #[doc(alias = "get_io_stream")] #[doc(alias = "io-stream")] pub fn io_stream(&self) -> Option { unsafe { from_glib_none(ffi::soup_websocket_connection_get_io_stream( self.to_glib_none().0, )) } } #[doc(alias = "soup_websocket_connection_get_keepalive_interval")] #[doc(alias = "get_keepalive_interval")] #[doc(alias = "keepalive-interval")] pub fn keepalive_interval(&self) -> u32 { unsafe { ffi::soup_websocket_connection_get_keepalive_interval(self.to_glib_none().0) } } #[cfg(feature = "v3_6")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_6")))] #[doc(alias = "soup_websocket_connection_get_keepalive_pong_timeout")] #[doc(alias = "get_keepalive_pong_timeout")] #[doc(alias = "keepalive-pong-timeout")] pub fn keepalive_pong_timeout(&self) -> u32 { unsafe { ffi::soup_websocket_connection_get_keepalive_pong_timeout(self.to_glib_none().0) } } #[doc(alias = "soup_websocket_connection_get_max_incoming_payload_size")] #[doc(alias = "get_max_incoming_payload_size")] #[doc(alias = "max-incoming-payload-size")] pub fn max_incoming_payload_size(&self) -> u64 { unsafe { ffi::soup_websocket_connection_get_max_incoming_payload_size(self.to_glib_none().0) } } #[cfg(feature = "v3_8")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_8")))] #[doc(alias = "soup_websocket_connection_get_max_total_message_size")] #[doc(alias = "get_max_total_message_size")] #[doc(alias = "max-total-message-size")] pub fn max_total_message_size(&self) -> u64 { unsafe { ffi::soup_websocket_connection_get_max_total_message_size(self.to_glib_none().0) } } #[doc(alias = "soup_websocket_connection_get_origin")] #[doc(alias = "get_origin")] pub fn origin(&self) -> Option { unsafe { from_glib_none(ffi::soup_websocket_connection_get_origin( self.to_glib_none().0, )) } } #[doc(alias = "soup_websocket_connection_get_protocol")] #[doc(alias = "get_protocol")] pub fn protocol(&self) -> Option { unsafe { from_glib_none(ffi::soup_websocket_connection_get_protocol( self.to_glib_none().0, )) } } #[doc(alias = "soup_websocket_connection_get_state")] #[doc(alias = "get_state")] pub fn state(&self) -> WebsocketState { unsafe { from_glib(ffi::soup_websocket_connection_get_state( self.to_glib_none().0, )) } } #[doc(alias = "soup_websocket_connection_get_uri")] #[doc(alias = "get_uri")] pub fn uri(&self) -> Option { unsafe { from_glib_none(ffi::soup_websocket_connection_get_uri( self.to_glib_none().0, )) } } #[doc(alias = "soup_websocket_connection_send_text")] pub fn send_text(&self, text: &str) { unsafe { ffi::soup_websocket_connection_send_text(self.to_glib_none().0, text.to_glib_none().0); } } #[doc(alias = "soup_websocket_connection_set_keepalive_interval")] #[doc(alias = "keepalive-interval")] pub fn set_keepalive_interval(&self, interval: u32) { unsafe { ffi::soup_websocket_connection_set_keepalive_interval(self.to_glib_none().0, interval); } } #[cfg(feature = "v3_6")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_6")))] #[doc(alias = "soup_websocket_connection_set_keepalive_pong_timeout")] #[doc(alias = "keepalive-pong-timeout")] pub fn set_keepalive_pong_timeout(&self, pong_timeout: u32) { unsafe { ffi::soup_websocket_connection_set_keepalive_pong_timeout( self.to_glib_none().0, pong_timeout, ); } } #[doc(alias = "soup_websocket_connection_set_max_incoming_payload_size")] #[doc(alias = "max-incoming-payload-size")] pub fn set_max_incoming_payload_size(&self, max_incoming_payload_size: u64) { unsafe { ffi::soup_websocket_connection_set_max_incoming_payload_size( self.to_glib_none().0, max_incoming_payload_size, ); } } #[cfg(feature = "v3_8")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_8")))] #[doc(alias = "soup_websocket_connection_set_max_total_message_size")] #[doc(alias = "max-total-message-size")] pub fn set_max_total_message_size(&self, max_total_message_size: u64) { unsafe { ffi::soup_websocket_connection_set_max_total_message_size( self.to_glib_none().0, max_total_message_size, ); } } #[doc(alias = "closed")] pub fn connect_closed(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn closed_trampoline( this: *mut ffi::SoupWebsocketConnection, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"closed".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( closed_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "closing")] pub fn connect_closing(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn closing_trampoline( this: *mut ffi::SoupWebsocketConnection, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"closing".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( closing_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "error")] pub fn connect_error(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn error_trampoline< F: Fn(&WebsocketConnection, &glib::Error) + 'static, >( this: *mut ffi::SoupWebsocketConnection, error: *mut glib::ffi::GError, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this), &from_glib_borrow(error)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"error".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( error_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "message")] pub fn connect_message( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn message_trampoline< F: Fn(&WebsocketConnection, i32, &glib::Bytes) + 'static, >( this: *mut ffi::SoupWebsocketConnection, type_: std::ffi::c_int, message: *mut glib::ffi::GBytes, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this), type_, &from_glib_borrow(message)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"message".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( message_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "pong")] pub fn connect_pong(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn pong_trampoline< F: Fn(&WebsocketConnection, &glib::Bytes) + 'static, >( this: *mut ffi::SoupWebsocketConnection, message: *mut glib::ffi::GBytes, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this), &from_glib_borrow(message)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"pong".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( pong_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "keepalive-interval")] pub fn connect_keepalive_interval_notify( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn notify_keepalive_interval_trampoline< F: Fn(&WebsocketConnection) + 'static, >( this: *mut ffi::SoupWebsocketConnection, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::keepalive-interval".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_keepalive_interval_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[cfg(feature = "v3_6")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_6")))] #[doc(alias = "keepalive-pong-timeout")] pub fn connect_keepalive_pong_timeout_notify( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn notify_keepalive_pong_timeout_trampoline< F: Fn(&WebsocketConnection) + 'static, >( this: *mut ffi::SoupWebsocketConnection, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::keepalive-pong-timeout".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_keepalive_pong_timeout_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "max-incoming-payload-size")] pub fn connect_max_incoming_payload_size_notify( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn notify_max_incoming_payload_size_trampoline< F: Fn(&WebsocketConnection) + 'static, >( this: *mut ffi::SoupWebsocketConnection, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::max-incoming-payload-size".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_max_incoming_payload_size_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[cfg(feature = "v3_8")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_8")))] #[doc(alias = "max-total-message-size")] pub fn connect_max_total_message_size_notify( &self, f: F, ) -> SignalHandlerId { unsafe extern "C" fn notify_max_total_message_size_trampoline< F: Fn(&WebsocketConnection) + 'static, >( this: *mut ffi::SoupWebsocketConnection, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::max-total-message-size".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_max_total_message_size_trampoline:: as *const (), )), Box_::into_raw(f), ) } } #[doc(alias = "state")] pub fn connect_state_notify(&self, f: F) -> SignalHandlerId { unsafe extern "C" fn notify_state_trampoline( this: *mut ffi::SoupWebsocketConnection, _param_spec: glib::ffi::gpointer, f: glib::ffi::gpointer, ) { unsafe { let f: &F = &*(f as *const F); f(&from_glib_borrow(this)) } } unsafe { let f: Box_ = Box_::new(f); connect_raw( self.as_ptr() as *mut _, c"notify::state".as_ptr(), Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>( notify_state_trampoline:: as *const (), )), Box_::into_raw(f), ) } } } // rustdoc-stripper-ignore-next /// A [builder-pattern] type to construct [`WebsocketConnection`] objects. /// /// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html #[must_use = "The builder must be built to be used"] pub struct WebsocketConnectionBuilder { builder: glib::object::ObjectBuilder<'static, WebsocketConnection>, } impl WebsocketConnectionBuilder { fn new() -> Self { Self { builder: glib::object::Object::builder(), } } pub fn connection_type(self, connection_type: WebsocketConnectionType) -> Self { Self { builder: self.builder.property("connection-type", connection_type), } } //pub fn extensions(self, extensions: /*Unimplemented*/Basic: Pointer) -> Self { // Self { builder: self.builder.property("extensions", extensions), } //} pub fn io_stream(self, io_stream: &impl IsA) -> Self { Self { builder: self .builder .property("io-stream", io_stream.clone().upcast()), } } pub fn keepalive_interval(self, keepalive_interval: u32) -> Self { Self { builder: self .builder .property("keepalive-interval", keepalive_interval), } } #[cfg(feature = "v3_6")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_6")))] pub fn keepalive_pong_timeout(self, keepalive_pong_timeout: u32) -> Self { Self { builder: self .builder .property("keepalive-pong-timeout", keepalive_pong_timeout), } } pub fn max_incoming_payload_size(self, max_incoming_payload_size: u64) -> Self { Self { builder: self .builder .property("max-incoming-payload-size", max_incoming_payload_size), } } #[cfg(feature = "v3_8")] #[cfg_attr(docsrs, doc(cfg(feature = "v3_8")))] pub fn max_total_message_size(self, max_total_message_size: u64) -> Self { Self { builder: self .builder .property("max-total-message-size", max_total_message_size), } } pub fn origin(self, origin: impl Into) -> Self { Self { builder: self.builder.property("origin", origin.into()), } } pub fn protocol(self, protocol: impl Into) -> Self { Self { builder: self.builder.property("protocol", protocol.into()), } } pub fn uri(self, uri: &glib::Uri) -> Self { Self { builder: self.builder.property("uri", uri.clone()), } } // rustdoc-stripper-ignore-next /// Build the [`WebsocketConnection`]. #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"] pub fn build(self) -> WebsocketConnection { assert_initialized_main_thread!(); self.builder.build() } } soup3-0.9.0/src/auto/websocket_extension.rs000064400000000000000000000060221046102023000170720ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::ffi; use glib::{prelude::*, translate::*}; glib::wrapper! { #[doc(alias = "SoupWebsocketExtension")] pub struct WebsocketExtension(Object); match fn { type_ => || ffi::soup_websocket_extension_get_type(), } } impl WebsocketExtension { pub const NONE: Option<&'static WebsocketExtension> = None; } pub trait WebsocketExtensionExt: IsA + 'static { //#[doc(alias = "soup_websocket_extension_configure")] //fn configure(&self, connection_type: WebsocketConnectionType, params: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 25 }/TypeId { ns_id: 0, id: 25 }) -> Result<(), glib::Error> { // unsafe { TODO: call ffi:soup_websocket_extension_configure() } //} #[doc(alias = "soup_websocket_extension_get_request_params")] #[doc(alias = "get_request_params")] fn request_params(&self) -> Option { unsafe { from_glib_full(ffi::soup_websocket_extension_get_request_params( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_websocket_extension_get_response_params")] #[doc(alias = "get_response_params")] fn response_params(&self) -> Option { unsafe { from_glib_full(ffi::soup_websocket_extension_get_response_params( self.as_ref().to_glib_none().0, )) } } #[doc(alias = "soup_websocket_extension_process_incoming_message")] fn process_incoming_message( &self, header: &mut u8, payload: glib::Bytes, ) -> Result { unsafe { let mut error = std::ptr::null_mut(); let ret = ffi::soup_websocket_extension_process_incoming_message( self.as_ref().to_glib_none().0, header, payload.into_glib_ptr(), &mut error, ); if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } } } #[doc(alias = "soup_websocket_extension_process_outgoing_message")] fn process_outgoing_message( &self, header: &mut u8, payload: glib::Bytes, ) -> Result { unsafe { let mut error = std::ptr::null_mut(); let ret = ffi::soup_websocket_extension_process_outgoing_message( self.as_ref().to_glib_none().0, header, payload.into_glib_ptr(), &mut error, ); if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } } } } impl> WebsocketExtensionExt for O {} soup3-0.9.0/src/auto/websocket_extension_deflate.rs000064400000000000000000000010321046102023000205520ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{WebsocketExtension, ffi}; glib::wrapper! { #[doc(alias = "SoupWebsocketExtensionDeflate")] pub struct WebsocketExtensionDeflate(Object) @extends WebsocketExtension; match fn { type_ => || ffi::soup_websocket_extension_deflate_get_type(), } } impl WebsocketExtensionDeflate {} soup3-0.9.0/src/auto/websocket_extension_manager.rs000064400000000000000000000010251046102023000205620ustar 00000000000000// This file was generated by gir (https://github.com/gtk-rs/gir) // from // from gir-files (https://github.com/gtk-rs/gir-files) // DO NOT EDIT use crate::{SessionFeature, ffi}; glib::wrapper! { #[doc(alias = "SoupWebsocketExtensionManager")] pub struct WebsocketExtensionManager(Object) @implements SessionFeature; match fn { type_ => || ffi::soup_websocket_extension_manager_get_type(), } } impl WebsocketExtensionManager {} soup3-0.9.0/src/builders.rs000064400000000000000000000001621046102023000136500ustar 00000000000000// Take a look at the license at the top of the repository in the LICENSE file. pub use crate::auto::builders::*; soup3-0.9.0/src/cookie_jar.rs000064400000000000000000000033661046102023000141550ustar 00000000000000use crate::{Cookie, CookieJar, prelude::*}; use glib::translate::*; mod sealed { pub trait Sealed {} impl> Sealed for T {} } pub trait CookieJarExtManual: IsA + sealed::Sealed + 'static { #[doc(alias = "soup_cookie_jar_add_cookie")] fn add_cookie(&self, cookie: &mut Cookie) { unsafe { ffi::soup_cookie_jar_add_cookie( self.as_ref().to_glib_none().0, mut_override(cookie.to_glib_full()), ); } } #[doc(alias = "soup_cookie_jar_add_cookie_full")] fn add_cookie_full( &self, cookie: &mut Cookie, uri: Option<&glib::Uri>, first_party: Option<&glib::Uri>, ) { unsafe { ffi::soup_cookie_jar_add_cookie_full( self.as_ref().to_glib_none().0, mut_override(cookie.to_glib_full()), uri.to_glib_none().0, first_party.to_glib_none().0, ); } } #[doc(alias = "soup_cookie_jar_add_cookie_with_first_party")] fn add_cookie_with_first_party(&self, first_party: &glib::Uri, cookie: &mut Cookie) { unsafe { ffi::soup_cookie_jar_add_cookie_with_first_party( self.as_ref().to_glib_none().0, first_party.to_glib_none().0, mut_override(cookie.to_glib_full()), ); } } #[doc(alias = "soup_cookie_jar_delete_cookie")] fn delete_cookie(&self, cookie: &mut Cookie) { unsafe { ffi::soup_cookie_jar_delete_cookie( self.as_ref().to_glib_none().0, cookie.to_glib_none_mut().0, ); } } } impl> CookieJarExtManual for O {} soup3-0.9.0/src/functions.rs000064400000000000000000000044621046102023000140560ustar 00000000000000use glib::translate::*; #[doc(alias = "soup_header_g_string_append_param")] pub fn header_g_string_append_param(header: &mut String, name: &str, value: &str) { unsafe { let hdr = glib::ffi::g_string_new_len(header.as_ptr() as *const _, header.len() as isize); ffi::soup_header_g_string_append_param(hdr, name.to_glib_none().0, value.to_glib_none().0); let s: glib::GString = from_glib_full(glib::ffi::g_string_free(hdr, glib::ffi::GFALSE)); header.clone_from(&s.as_str().to_owned()) } } #[doc(alias = "soup_header_g_string_append_param_quoted")] pub fn header_g_string_append_param_quoted(header: &mut String, name: &str, value: &str) { unsafe { let hdr = glib::ffi::g_string_new_len(header.as_ptr() as *const _, header.len() as isize); ffi::soup_header_g_string_append_param_quoted( hdr, name.to_glib_none().0, value.to_glib_none().0, ); let s: glib::GString = from_glib_full(glib::ffi::g_string_free(hdr, glib::ffi::GFALSE)); header.clone_from(&s.as_str().to_owned()) } } // #[doc(alias = "soup_cookies_free")] // pub fn cookies_free(cookies: &[&Cookie]) { // assert_initialized_main_thread!(); // unsafe { // let cookie_list: *mut glib::ffi::GSList = ToGlibContainerFromSlice::to_glib_none_from_slice(cookies).0; // ffi::soup_cookies_free(cookie_list); // } // } // #[doc(alias = "soup_cookies_to_cookie_header")] // pub fn cookies_to_cookie_header(cookies: &[Cookie]) -> Option { // assert_initialized_main_thread!(); // unsafe { // let cookie_list: *mut glib::ffi::GSList = ToGlibContainerFromSlice::to_glib_none_from_slice(cookies).0; // from_glib_full(ffi::soup_cookies_to_cookie_header(cookie_list)) // } // } // #[doc(alias = "soup_cookies_to_request")] // pub fn cookies_to_request(cookies: &[&Cookie], msg: &Message) { // skip_assert_initialized!(); // unsafe { // ffi::soup_cookies_to_request(cookies.to_glib_none().0, msg.to_glib_none().0); // } // } // #[doc(alias = "soup_cookies_to_response")] // pub fn cookies_to_response(cookies: &[Cookie], msg: &Message) { // skip_assert_initialized!(); // unsafe { // ffi::soup_cookies_to_response(cookies.to_glib_none().0, msg.to_glib_none().0); // } // } soup3-0.9.0/src/lib.rs000064400000000000000000000011231046102023000126030ustar 00000000000000// // Copyright 2013-2017, The Gtk-rs Project Developers. // // See the COPYRIGHT file at the top-level directory of this distribution. // // Licensed under the MIT license, see the LICENSE file or #![cfg_attr(docsrs, feature(doc_cfg))] pub use ffi; pub use gio; pub use glib; #[macro_use] mod rt; pub mod prelude; #[allow(unused_imports)] mod auto; pub use auto::*; mod functions; pub use auto::functions::*; pub use functions::*; pub mod builders; mod cookie_jar; mod logger; mod message_headers; mod server; mod session; mod websocket_connection; soup3-0.9.0/src/logger.rs000064400000000000000000000035221046102023000133210ustar 00000000000000use crate::{Logger, LoggerLogLevel, prelude::*}; use glib::GStr; use glib::translate::*; use std::boxed::Box as Box_; mod sealed { pub trait Sealed {} impl> Sealed for T {} } pub trait LoggerExtManual: IsA + sealed::Sealed + 'static { #[doc(alias = "soup_logger_set_printer")] fn set_printer( &self, printer: P, ) { let printer_data: Box_

= Box_::new(printer); unsafe extern "C" fn printer_func< P: Fn(&Logger, LoggerLogLevel, char, &GStr) + Send + Sync + 'static, >( logger: *mut ffi::SoupLogger, level: ffi::SoupLoggerLogLevel, direction: libc::c_char, data: *const libc::c_char, user_data: glib::ffi::gpointer, ) { unsafe { let logger = from_glib_borrow(logger); let direction: glib::Char = from_glib(direction); let data: &GStr = GStr::from_ptr(data); let callback: &P = &*(user_data as *mut _); (*callback)(&logger, from_glib(level), char::from(direction), data); } } unsafe extern "C" fn destroy_func< P: Fn(&Logger, LoggerLogLevel, char, &GStr) + Send + Sync + 'static, >( data: glib::ffi::gpointer, ) { unsafe { let _callback: Box_

= Box_::from_raw(data as *mut _); } } unsafe { ffi::soup_logger_set_printer( self.as_ref().to_glib_none().0, Some(printer_func::

as _), Box_::into_raw(printer_data) as *mut _, Some(destroy_func::

as _), ) } } } impl> LoggerExtManual for O {} soup3-0.9.0/src/message_headers.rs000064400000000000000000000107171046102023000151650ustar 00000000000000use glib::translate::*; use glib::{GString, IntoGStr, IntoOptionalGStr}; use std::collections::HashMap; use std::{fmt, ptr}; use crate::MessageHeaders; impl MessageHeaders { #[doc(alias = "soup_message_headers_get_content_disposition")] pub fn content_disposition(&self) -> Option<(GString, HashMap)> { let mut disposition = ptr::null_mut(); let mut params = ptr::null_mut(); unsafe { if bool::from_glib(ffi::soup_message_headers_get_content_disposition( mut_override(self.to_glib_none().0), &mut disposition, &mut params, )) { let params = if !params.is_null() { HashMap::from_glib_full(params) } else { HashMap::new() }; Some((GString::from_glib_full(disposition), params)) } else { None } } } #[doc(alias = "soup_message_headers_set_content_disposition")] pub fn set_content_disposition( &self, disposition: Option, params: Option>, ) { disposition.run_with_gstr(|disposition| unsafe { ffi::soup_message_headers_set_content_disposition( self.to_glib_none().0, disposition.to_glib_none().0, params.to_glib_none().0, ) }) } #[doc(alias = "soup_message_headers_get_content_type")] pub fn content_type(&self) -> Option<(GString, HashMap)> { let mut params = ptr::null_mut(); unsafe { let content_type = ffi::soup_message_headers_get_content_type( mut_override(self.to_glib_none().0), &mut params, ); if !content_type.is_null() { let params = if !params.is_null() { HashMap::from_glib_full(params) } else { HashMap::new() }; Some((GString::from_glib_none(content_type), params)) } else { None } } } #[doc(alias = "soup_message_headers_set_content_type")] pub fn set_content_type( &self, content_type: Option, params: Option>, ) { content_type.run_with_gstr(|content_type| unsafe { ffi::soup_message_headers_set_content_type( self.to_glib_none().0, content_type.to_glib_none().0, params.to_glib_none().0, ) }) } } impl fmt::Debug for MessageHeaders { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { struct Map<'a>(&'a MessageHeaders); impl fmt::Debug for Map<'_> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let mut map = f.debug_map(); self.0.foreach(|name, value| _ = map.entry(&name, &value)); map.finish() } } f.debug_tuple("MessageHeaders").field(&Map(self)).finish() } } #[cfg(test)] mod tests { use super::*; use crate::MessageHeadersType; use std::collections::HashMap; #[test] fn content_type_can_be_set_and_read() { let headers = MessageHeaders::new(MessageHeadersType::Request); headers.set_content_type(Some(EXPECTED_CONTENT_TYPE), Some(expected_params())); let (content_type, params) = headers .content_type() .expect("content type header to be present"); assert_eq!(EXPECTED_CONTENT_TYPE, content_type); assert_eq!(expected_params(), params); } #[test] fn content_disposition_can_be_set_and_read() { let headers = MessageHeaders::new(MessageHeadersType::Request); headers .set_content_disposition(Some(EXPECTED_CONTENT_DISPOSITION), Some(expected_params())); let (content_type, params) = headers .content_disposition() .expect("content disposition header to be present"); assert_eq!(EXPECTED_CONTENT_DISPOSITION, content_type); assert_eq!(expected_params(), params); } const EXPECTED_CONTENT_TYPE: &str = "text/html"; const EXPECTED_CONTENT_DISPOSITION: &str = "attachment"; fn expected_params() -> HashMap { [("param".to_owned(), "value".to_owned())] .into_iter() .collect() } } soup3-0.9.0/src/prelude.rs000064400000000000000000000004661046102023000135060ustar 00000000000000#[doc(hidden)] pub use gio::prelude::*; pub use crate::auto::traits::*; pub use crate::cookie_jar::CookieJarExtManual; pub use crate::logger::LoggerExtManual; pub use crate::server::ServerExtManual; pub use crate::session::SessionExtManual; pub use crate::websocket_connection::WebsocketConnectionExtManual; soup3-0.9.0/src/rt.rs000064400000000000000000000003351046102023000124660ustar 00000000000000// Take a look at the license at the top of the repository in the LICENSE file. /// No-op. macro_rules! assert_initialized_main_thread { () => {}; } /// No-op. macro_rules! skip_assert_initialized { () => {}; } soup3-0.9.0/src/server.rs000064400000000000000000000160221046102023000133470ustar 00000000000000use crate::{Server, ServerMessage, WebsocketConnection, prelude::*}; use glib::translate::*; use std::boxed::Box as Box_; use std::collections::HashMap; mod sealed { pub trait Sealed {} impl> Sealed for T {} } pub trait ServerExtManual: IsA + sealed::Sealed + 'static { #[doc(alias = "soup_server_add_early_handler")] fn add_early_handler) + 'static>( &self, path: Option<&str>, callback: P, ) { let callback_data: Box_

= Box_::new(callback); unsafe extern "C" fn callback_func< P: Fn(&Server, &ServerMessage, &str, HashMap<&str, &str>) + 'static, >( server: *mut ffi::SoupServer, msg: *mut ffi::SoupServerMessage, path: *const libc::c_char, query: *mut glib::ffi::GHashTable, user_data: glib::ffi::gpointer, ) { unsafe { let server = from_glib_borrow(server); let msg: Borrowed = from_glib_borrow(msg); let path: Borrowed = from_glib_borrow(path); let query_map = query_map_from_hash_table(query); let callback: &P = &*(user_data as *mut _); (*callback)(&server, &msg, path.as_str(), query_map); } } let callback = Some(callback_func::

as _); unsafe extern "C" fn destroy_func< P: Fn(&Server, &ServerMessage, &str, HashMap<&str, &str>) + 'static, >( data: glib::ffi::gpointer, ) { unsafe { let _callback: Box_

= Box_::from_raw(data as *mut _); } } let destroy_call6 = Some(destroy_func::

as _); let super_callback0: Box_

= callback_data; unsafe { ffi::soup_server_add_early_handler( self.as_ref().to_glib_none().0, path.to_glib_none().0, callback, Box_::into_raw(super_callback0) as *mut _, destroy_call6, ); } } #[doc(alias = "soup_server_add_handler")] fn add_handler) + 'static>( &self, path: Option<&str>, callback: P, ) { let callback_data: Box_

= Box_::new(callback); unsafe extern "C" fn callback_func< P: Fn(&Server, &ServerMessage, &str, HashMap<&str, &str>) + 'static, >( server: *mut ffi::SoupServer, msg: *mut ffi::SoupServerMessage, path: *const libc::c_char, query: *mut glib::ffi::GHashTable, user_data: glib::ffi::gpointer, ) { unsafe { let server = from_glib_borrow(server); let msg: Borrowed = from_glib_borrow(msg); let path: Borrowed = from_glib_borrow(path); let query_map = query_map_from_hash_table(query); let callback: &P = &*(user_data as *mut _); (*callback)(&server, &msg, path.as_str(), query_map); } } let callback = Some(callback_func::

as _); unsafe extern "C" fn destroy_func< P: Fn(&Server, &ServerMessage, &str, HashMap<&str, &str>) + 'static, >( data: glib::ffi::gpointer, ) { unsafe { let _callback: Box_

= Box_::from_raw(data as *mut _); } } let destroy_call6 = Some(destroy_func::

as _); let super_callback0: Box_

= callback_data; unsafe { ffi::soup_server_add_handler( self.as_ref().to_glib_none().0, path.to_glib_none().0, callback, Box_::into_raw(super_callback0) as *mut _, destroy_call6, ); } } #[doc(alias = "soup_server_add_websocket_handler")] fn add_websocket_handler< P: Fn(&Server, &ServerMessage, &str, &WebsocketConnection) + 'static, >( &self, path: Option<&str>, origin: Option<&str>, protocols: &[&str], callback: P, ) { let callback_data: Box_

= Box_::new(callback); unsafe extern "C" fn callback_func< P: Fn(&Server, &ServerMessage, &str, &WebsocketConnection) + 'static, >( server: *mut ffi::SoupServer, msg: *mut ffi::SoupServerMessage, path: *const libc::c_char, connection: *mut ffi::SoupWebsocketConnection, user_data: glib::ffi::gpointer, ) { unsafe { let server = from_glib_borrow(server); let msg: Borrowed = from_glib_borrow(msg); let path: Borrowed = from_glib_borrow(path); let connection = from_glib_borrow(connection); let callback: &P = &*(user_data as *mut _); (*callback)(&server, &msg, path.as_str(), &connection); } } let callback = Some(callback_func::

as _); unsafe extern "C" fn destroy_func< P: Fn(&Server, &ServerMessage, &str, &WebsocketConnection) + 'static, >( data: glib::ffi::gpointer, ) { unsafe { let _callback: Box_

= Box_::from_raw(data as *mut _); } } let destroy_call6 = Some(destroy_func::

as _); let super_callback0: Box_

= callback_data; unsafe { ffi::soup_server_add_websocket_handler( self.as_ref().to_glib_none().0, path.to_glib_none().0, origin.to_glib_none().0, protocols.to_glib_none().0, callback, Box_::into_raw(super_callback0) as *mut _, destroy_call6, ); } } } impl> ServerExtManual for O {} unsafe fn query_map_from_hash_table<'a>( query: *mut glib::ffi::GHashTable, ) -> HashMap<&'a str, &'a str> { if query.is_null() { return HashMap::new(); } unsafe extern "C" fn read_query_hash_table( key: glib::ffi::gpointer, value: glib::ffi::gpointer, hash_map: glib::ffi::gpointer, ) { unsafe { let key = glib::GStr::from_ptr_checked(key as *const libc::c_char); let value = glib::GStr::from_ptr_checked(value as *const libc::c_char); let hash_map: &mut HashMap<&str, &str> = &mut *(hash_map as *mut HashMap<&str, &str>); if let (Some(k), Some(v)) = (key, value) { hash_map.insert(k.as_str(), v.as_str()); } } } unsafe { let mut query_map = HashMap::with_capacity(glib::ffi::g_hash_table_size(query) as usize); glib::ffi::g_hash_table_foreach( query, Some(read_query_hash_table), &mut query_map as *mut HashMap<&str, &str> as *mut _, ); query_map } } soup3-0.9.0/src/session.rs000064400000000000000000000074631046102023000135350ustar 00000000000000use crate::{Message, Session, WebsocketConnection, prelude::*}; use glib::translate::*; use std::boxed::Box as Box_; use std::pin::Pin; use std::ptr; mod sealed { pub trait Sealed {} impl> Sealed for T {} } pub trait SessionExtManual: IsA + sealed::Sealed + 'static { #[doc(alias = "soup_session_websocket_connect_async")] fn websocket_connect_async) + 'static>( &self, msg: &Message, origin: Option<&str>, protocols: &[&str], io_priority: glib::Priority, cancellable: Option<&impl IsA>, callback: P, ) { let main_context = glib::MainContext::ref_thread_default(); let is_main_context_owner = main_context.is_owner(); let has_acquired_main_context = (!is_main_context_owner) .then(|| main_context.acquire().ok()) .flatten(); assert!( is_main_context_owner || has_acquired_main_context.is_some(), "Async operations only allowed if the thread is owning the MainContext" ); let user_data: Box_> = Box_::new(glib::thread_guard::ThreadGuard::new(callback)); unsafe extern "C" fn websocket_connect_async_trampoline< P: FnOnce(Result) + 'static, >( _source_object: *mut glib::gobject_ffi::GObject, res: *mut gio::ffi::GAsyncResult, user_data: glib::ffi::gpointer, ) { unsafe { let mut error = ptr::null_mut(); let ret = ffi::soup_session_websocket_connect_finish( _source_object as *mut _, res, &mut error, ); let result = if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) }; let callback: Box_> = Box_::from_raw(user_data as *mut _); let callback = callback.into_inner(); callback(result); } } let callback = websocket_connect_async_trampoline::

; unsafe { ffi::soup_session_websocket_connect_async( self.as_ref().to_glib_none().0, msg.to_glib_none().0, origin.to_glib_none().0, protocols.to_glib_none().0, io_priority.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, Some(callback), Box_::into_raw(user_data) as *mut _, ); } } fn websocket_connect_async_future( &self, msg: &Message, origin: Option<&str>, protocols: &[&str], io_priority: glib::Priority, ) -> Pin< Box_> + 'static>, > { let msg = msg.clone(); let origin = origin.map(ToOwned::to_owned); let protocols = protocols .iter() .copied() .map(String::from) .collect::>(); Box_::pin(gio::GioFuture::new(self, move |obj, cancellable, send| { let protocols = protocols.iter().map(|s| s.as_str()).collect::>(); obj.websocket_connect_async( &msg, origin.as_ref().map(::std::borrow::Borrow::borrow), &protocols, io_priority, Some(cancellable), move |res| { send.resolve(res); }, ); })) } } impl> SessionExtManual for O {} soup3-0.9.0/src/websocket_connection.rs000064400000000000000000000021241046102023000162440ustar 00000000000000use crate::{WebsocketConnection, WebsocketConnectionType, WebsocketExtension, prelude::*}; use glib::translate::*; mod sealed { pub trait Sealed {} impl> Sealed for T {} } pub trait WebsocketConnectionExtManual: IsA + sealed::Sealed + 'static { #[doc(alias = "soup_websocket_connection_new")] fn new( stream: &impl IsA, uri: &glib::Uri, type_: WebsocketConnectionType, origin: Option<&str>, protocol: Option<&str>, extensions: &[WebsocketExtension], ) -> WebsocketConnection { assert_initialized_main_thread!(); unsafe { from_glib_full(ffi::soup_websocket_connection_new( stream.as_ref().to_glib_none().0, uri.to_glib_none().0, type_.into_glib(), origin.to_glib_none().0, protocol.to_glib_none().0, extensions.to_glib_full(), )) } } } impl> WebsocketConnectionExtManual for O {} soup3-0.9.0/subprojects/libsoup.wrap000064400000000000000000000001121046102023000156100ustar 00000000000000[wrap-git] url = https://gitlab.gnome.org/GNOME/libsoup revision = master